diff --git a/doc/man/salt-api.1 b/doc/man/salt-api.1 index cbd17897d56..4ddc821c596 100644 --- a/doc/man/salt-api.1 +++ b/doc/man/salt-api.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-API" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-API" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-api \- salt-api Command . diff --git a/doc/man/salt-call.1 b/doc/man/salt-call.1 index 550a3d01324..dcbe51d4672 100644 --- a/doc/man/salt-call.1 +++ b/doc/man/salt-call.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-CALL" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-CALL" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-call \- salt-call Documentation . diff --git a/doc/man/salt-cloud.1 b/doc/man/salt-cloud.1 index cf0a632f48e..362b5daefc4 100644 --- a/doc/man/salt-cloud.1 +++ b/doc/man/salt-cloud.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-CLOUD" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-CLOUD" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-cloud \- Salt Cloud Command . diff --git a/doc/man/salt-cp.1 b/doc/man/salt-cp.1 index a5e0211e10f..4054fe84b7e 100644 --- a/doc/man/salt-cp.1 +++ b/doc/man/salt-cp.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-CP" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-CP" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-cp \- salt-cp Documentation . @@ -135,7 +135,7 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, .SS Target Selection .sp The default matching that Salt utilizes is shell\-style globbing around the -minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&. +minion id. See \fI\%https://docs.python.org/3/library/fnmatch.html#module\-fnmatch\fP\&. .INDENT 0.0 .TP .B \-E, \-\-pcre diff --git a/doc/man/salt-key.1 b/doc/man/salt-key.1 index 07ed01fceff..9c9dd7c5b31 100644 --- a/doc/man/salt-key.1 +++ b/doc/man/salt-key.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-KEY" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-KEY" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-key \- salt-key Documentation . diff --git a/doc/man/salt-master.1 b/doc/man/salt-master.1 index e603ffbe659..b2b3c3fa66e 100644 --- a/doc/man/salt-master.1 +++ b/doc/man/salt-master.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-MASTER" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-MASTER" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-master \- salt-master Documentation . diff --git a/doc/man/salt-minion.1 b/doc/man/salt-minion.1 index 51f83015cd6..09a1f75f6b8 100644 --- a/doc/man/salt-minion.1 +++ b/doc/man/salt-minion.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-MINION" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-MINION" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-minion \- salt-minion Documentation . diff --git a/doc/man/salt-proxy.1 b/doc/man/salt-proxy.1 index 1b796b229d2..4abea4b4691 100644 --- a/doc/man/salt-proxy.1 +++ b/doc/man/salt-proxy.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-PROXY" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-PROXY" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-proxy \- salt-proxy Documentation . diff --git a/doc/man/salt-run.1 b/doc/man/salt-run.1 index e928daa636f..419db160469 100644 --- a/doc/man/salt-run.1 +++ b/doc/man/salt-run.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-RUN" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-RUN" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-run \- salt-run Documentation . diff --git a/doc/man/salt-ssh.1 b/doc/man/salt-ssh.1 index 18b3df7cd0c..48bc9e0d7c4 100644 --- a/doc/man/salt-ssh.1 +++ b/doc/man/salt-ssh.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-SSH" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-SSH" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-ssh \- salt-ssh Documentation . @@ -272,7 +272,7 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, .SS Target Selection .sp The default matching that Salt utilizes is shell\-style globbing around the -minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&. +minion id. See \fI\%https://docs.python.org/3/library/fnmatch.html#module\-fnmatch\fP\&. .INDENT 0.0 .TP .B \-E, \-\-pcre diff --git a/doc/man/salt-syndic.1 b/doc/man/salt-syndic.1 index 4e8a9cdcab0..49a776b0e51 100644 --- a/doc/man/salt-syndic.1 +++ b/doc/man/salt-syndic.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-SYNDIC" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-SYNDIC" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-syndic \- salt-syndic Documentation . diff --git a/doc/man/salt-unity.1 b/doc/man/salt-unity.1 index c1ca49ed3cd..1f26c8e5569 100644 --- a/doc/man/salt-unity.1 +++ b/doc/man/salt-unity.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT-UNITY" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT-UNITY" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt-unity \- salt-unity Command . diff --git a/doc/man/salt.1 b/doc/man/salt.1 index f9973583ffb..1b2bc6c23e6 100644 --- a/doc/man/salt.1 +++ b/doc/man/salt.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME salt \- salt . @@ -183,7 +183,7 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, .SS Target Selection .sp The default matching that Salt utilizes is shell\-style globbing around the -minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&. +minion id. See \fI\%https://docs.python.org/3/library/fnmatch.html#module\-fnmatch\fP\&. .INDENT 0.0 .TP .B \-E, \-\-pcre diff --git a/doc/man/salt.7 b/doc/man/salt.7 index 90fa8c6d33c..7e2f81e1809 100644 --- a/doc/man/salt.7 +++ b/doc/man/salt.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT" "7" "Nov 14, 2020" "3002.2" "Salt" +.TH "SALT" "7" "Feb 23, 2021" "3003" "Salt" .SH NAME salt \- Salt Documentation . @@ -30,6 +30,110 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.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’s fastest, most intelligent and scalable automation\fP +\fIengine.\fP +.SS About Salt +.sp +Built on python, Salt uses simple and human\-readable YAML combined with +event\-driven automation to deploy and configure complex IT systems. In addition +to leveling\-up \fI\%vRealize Automation SaltStack Config\fP, Salt can be found under +the hood of products from Juniper, Cisco, Cloudflare, Nutanix, SUSE, and Tieto, +to name a few. +.SS About SaltStack +.sp +\fI\%SaltStack was acquired by VMware in 2020\fP\&. +Salt Project remains an open source ecosystem that VMware supports and +contributes to. +.SS Download Salt +.sp +Salt is tested and packaged to run on CentOS, Debian, RHEL, Ubuntu, MacOS, +Windows, and more. Download Salt and get started now. +.INDENT 0.0 +.IP \(bu 2 +\fI\%https://repo.saltproject.io/\fP +.IP \(bu 2 +\fI\%Installation Instructions\fP +.UNINDENT +.SS Salt Project Documentation +.sp +Installation instructions, getting started guides, in\-depth API +documentation, and contributing to Salt. +.INDENT 0.0 +.IP \(bu 2 +\fI\%Getting Started with Salt\fP +.IP \(bu 2 +\fI\%Latest Salt Documentation\fP +.IP \(bu 2 +\fI\%Salt’s Contributor 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 Community Slack Channel\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 Engage the Salt Project and The Community +.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 Freenode\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\%core@saltstack.com\fP or reach out +directly to the Community Manager, Janae Andrus via Slack. We’d 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 We’re not just talking about NaCl..SS The 30 second summary .sp @@ -198,6 +302,343 @@ A few examples of salt states from the community: .sp If you want to get involved with the development of source code or the documentation efforts, please review the contributing documentation! +.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 INSTALLATION .sp This section contains instructions to install Salt. If you are setting up your @@ -4675,7 +5116,7 @@ configuration instructions. .INDENT 3.5 .IP "Stuck?" .sp -There are many ways to get help from the Salt community including our +There are many ways to salt\-community including our \fI\%mailing list\fP and our \fI\%IRC channel\fP #salt. .UNINDENT @@ -8064,8 +8505,20 @@ state_output_diff: False .sp Default: \fBFalse\fP .sp -Automatically aggregate all states that have support for mod_aggregate by -setting to \fBTrue\fP\&. Or pass a list of state module names to automatically +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 @@ -8078,16 +8531,6 @@ state_aggregate: .fi .UNINDENT .UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -state_aggregate: True -.ft P -.fi -.UNINDENT -.UNINDENT .SS \fBstate_events\fP .sp Default: \fBFalse\fP @@ -10573,7 +11016,6 @@ For example, these two documents: .sp .nf .ft C -#!yamlex foo: 42 bar: !aggregate { element1: True @@ -10588,7 +11030,6 @@ baz: !aggregate quux .sp .nf .ft C -#!yamlex bar: !aggregate { element2: True } @@ -10615,6 +11056,15 @@ baz: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 2.0 +.INDENT 3.5 +This requires that the render pipeline +defined in the \fI\%renderer\fP master configuration ends in +\fByamlex\fP\&. +.UNINDENT +.UNINDENT .IP \(bu 2 \fBoverwrite\fP: .sp @@ -13569,7 +14019,7 @@ auth_tries: 7 New in version 2014.7.0. .sp -Default: \fB60\fP +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, @@ -13577,12 +14027,19 @@ 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: 60 +auth_timeout: 5 .ft P .fi .UNINDENT @@ -13782,6 +14239,21 @@ return_retry_timer_max: 10 .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 @@ -14675,6 +15147,36 @@ test: False .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_verbose\fP .sp Default: \fBTrue\fP @@ -25833,6 +26335,13 @@ require. \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 +The guidance here should be taken in combination with best\-practices\&. +.UNINDENT +.UNINDENT +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 Refer to the saltstack_security_announcements documentation in order to stay updated and secure. .UNINDENT @@ -25870,6 +26379,25 @@ 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 pillar and/or sdb\&. +.UNINDENT +.UNINDENT +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +Jinja supports a \fI\%secure, sandboxed template execution environment\fP that Salt +takes advantage of. Other text renderers 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 @@ -25917,6 +26445,91 @@ 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 +.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 +.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 /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 /minion_master.pub +systemctl start salt\-minion +.ft P +.fi +.UNINDENT +.UNINDENT .SS Security disclosure policy .INDENT 0.0 .TP @@ -26167,7 +26780,7 @@ The TCP transport allows for the master/minion communication to be optionally wrapped in a TLS connection. Enabling this is simple, the master and minion need to be using the tcp connection, then the \fIssl\fP option is enabled. The \fIssl\fP option is passed as a dict and corresponds to the options passed to the -Python \fIssl.wrap_socket \fP +Python \fIssl.wrap_socket \fP function. .sp A simple setup looks like this, on the Salt Master add the \fIssl\fP option to the @@ -27083,7 +27696,7 @@ Return salt data to Zabbix T} _ .TE -.SS salt.returners.appoptics_return module +.SS salt.returners.appoptics_return .sp Salt returner to return highstate stats to AppOptics Metrics .sp @@ -28209,7 +28822,7 @@ Return data to an etcd server or cluster .B salt.returners.etcd_return.save_load(jid, load, minions=None) Save the load to the specified jid .UNINDENT -.SS salt.returners.highstate_return module +.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. @@ -28636,7 +29249,7 @@ Update (or store) the end time for a given job .sp Endtime is stored as a plain text string .UNINDENT -.SS salt.returners.mattermost_returner module +.SS salt.returners.mattermost_returner .sp Return salt data via mattermost .sp @@ -31374,7 +31987,7 @@ Do any work necessary to prepare a JID, including sending a custom id .B salt.returners.smtp_return.returner(ret) Send an email with the data .UNINDENT -.SS salt.returners.splunk module +.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: @@ -31914,7 +32527,7 @@ salt \(aq*\(aq test.ping \-\-return xmpp \-\-return_kwargs \(aq{"recipient": "so .B salt.returners.xmpp_return.returner(ret) Send an xmpp message with the data .UNINDENT -.SS salt.returners.zabbix_return module +.SS salt.returners.zabbix_return .sp Return salt data to Zabbix .sp @@ -31977,6 +32590,15 @@ Renderers fall into one of two categories, based on what they output: text or data. The one exception to this would be the \fBpure python\fP renderer, which can be used in either capacity. .SS Text Renderers .sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +Jinja 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 \fBjinja\fP, \fBmako\fP, and \fBgenshi\fP, as well as the \fBgpg\fP renderer. The following are all text renderers: @@ -32241,6 +32863,15 @@ def render(yaml_data, saltenv="", sls="", **kws): .UNINDENT .SS Full List of Renderers .SS renderer modules +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +Jinja supports a \fI\%secure, sandboxed template execution environment\fP that Salt +takes advantage of. Other text renderers do not support this +functionality, so Salt highly recommends usage of \fBjinja\fP / \fBjinja|yaml\fP\&. +.UNINDENT +.UNINDENT .TS center; |l|l|. @@ -32346,7 +32977,7 @@ A flexible renderer that takes a templating engine and a data format T} _ T{ -\fBtoml\fP +\fBtomlmod\fP T} T{ T} _ @@ -32884,7 +33515,14 @@ A Python data structure .sp Jinja loading utils to enable a more powerful backend for jinja templates .sp -For Jinja usage information see Understanding Jinja\&. +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +Jinja supports a \fI\%secure, sandboxed template execution environment\fP that Salt +takes advantage of. Other text renderers 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) @@ -33306,7 +33944,7 @@ a\-secret: "NACL[MRN3cc+fmdxyQbz6WMF+jq1hKdU5X5BBI7OjK+atvHo1ll+w1gZ7XyWtZVfq9gK Decrypt the data to be rendered using the given nacl key or the one given in config .UNINDENT -.SS salt.renderers.pass module +.SS salt.renderers.pass .SS Pass Renderer for Salt .sp \fI\%pass\fP is an encrypted on\-disk password store. @@ -34705,7 +35343,7 @@ then there\(aqs no way to reliably rewrite such reference. .SS salt.renderers.toml .INDENT 0.0 .TP -.B salt.renderers.toml.render(sls_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws) +.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 @@ -35057,6 +35695,16 @@ 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 pillar and/or sdb\&. +.UNINDENT +.UNINDENT +.sp The grains are derived by executing all of the "public" functions (i.e. those which do not begin with an underscore) found in the modules located in the Salt\(aqs core grains code, followed by those in any custom grains modules. The @@ -38810,6 +39458,15 @@ Understanding Jinja\&. .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 renderers 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 @@ -41657,7 +42314,7 @@ Will insert the following message in the minion logs: .UNINDENT .SS Profiling .sp -New in version 3002.2. +New in version 3002. .sp When working with a very large codebase, it becomes increasingly imperative to @@ -43223,328 +43880,6 @@ Salt Proxy Minion End\-to\-End Example .IP \(bu 2 \fBvSphere Execution Module\fP .UNINDENT -.SS Installing and Configuring Halite -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -Halite is deprecated -.sp -The Halite project is retired. The code will remain available on GitHub. -.UNINDENT -.UNINDENT -.sp -In this tutorial, we\(aqll walk through installing and setting up Halite. The -current version of Halite is considered pre\-alpha and is supported only in Salt -\fBv2014.1.0\fP or greater. Additional information is available on GitHub: -\fI\%https://github.com/saltstack/halite\fP -.sp -Before beginning this tutorial, ensure that the salt\-master is installed. To -install the salt\-master, please review the installation documentation: -\fI\%http://docs.saltstack.com/topics/installation/index.html\fP -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Halite only works with Salt versions greater than 2014.1.0. -.UNINDENT -.UNINDENT -.SS Installing Halite Via Package -.sp -On CentOS, RHEL, or Fedora: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ yum install python\-halite -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -By default python\-halite only installs CherryPy. If you would like to use -a different webserver please review the instructions below to install -pip and your server of choice. The package does not modify the master -configuration with \fB/etc/salt/master\fP\&. -.UNINDENT -.UNINDENT -.SS Installing Halite Using pip -.sp -To begin the installation of Halite from PyPI, you\(aqll need to install pip. The -Salt package, as well as the bootstrap, do not install pip by default. -.sp -On CentOS, RHEL, or Fedora: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ yum install python\-pip -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -On Debian: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ apt\-get install python\-pip -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Once you have pip installed, use it to install halite: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ pip install \-U halite -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Depending on the webserver you want to run halite through, you\(aqll need to -install that piece as well. On RHEL based distros, use one of the following: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ pip install cherrypy -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ pip install paste -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ yum install python\-devel -$ yum install gcc -$ pip install gevent -$ pip install pyopenssl -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -On Debian based distributions: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ pip install CherryPy -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ pip install paste -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ apt\-get install gcc -$ apt\-get install python\-dev -$ apt\-get install libevent\-dev -$ pip install gevent -$ pip install pyopenssl -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Configuring Halite Permissions -.sp -Configuring Halite access permissions is easy. By default, you only need to -ensure that the @runner group is configured. In the \fB/etc/salt/master\fP file, -uncomment and modify the following lines: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -external_auth: - pam: - testuser: - \- .* - \- \(aq@runner\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -You cannot use the root user for pam login; it will fail to authenticate. -.UNINDENT -.UNINDENT -.sp -Halite uses the runner manage.present to get the status of minions, so runner -permissions are required. For example: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -external_auth: - pam: - mytestuser: - \- .* - \- \(aq@runner\(aq - \- \(aq@wheel\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Currently Halite allows, but does not require, any wheel modules. -.SS Configuring Halite Settings -.sp -Once you\(aqve configured the permissions for Halite, you\(aqll need to set up the -Halite settings in the /etc/salt/master file. Halite supports CherryPy, Paste, and Gevent out of the box. -.sp -To configure cherrypy, add the following to the bottom of your /etc/salt/master file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -halite: - level: \(aqdebug\(aq - server: \(aqcherrypy\(aq - host: \(aq0.0.0.0\(aq - port: \(aq8080\(aq - cors: False - tls: True - certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq - keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq - pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If you wish to use paste: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -halite: - level: \(aqdebug\(aq - server: \(aqpaste\(aq - host: \(aq0.0.0.0\(aq - port: \(aq8080\(aq - cors: False - tls: True - certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq - keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq - pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use gevent: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -halite: - level: \(aqdebug\(aq - server: \(aqgevent\(aq - host: \(aq0.0.0.0\(aq - port: \(aq8080\(aq - cors: False - tls: True - certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq - keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq - pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The "cherrypy" and "gevent" servers require the certpath and keypath files -to run tls/ssl. The .crt file holds the public cert and the .key file holds -the private key. Whereas the "paste" server requires a single .pem file that -contains both the cert and key. This can be created simply by concatenating -the .crt and .key files. -.sp -If you want to use a self\-signed cert, you can create one using the Salt.tls -module: -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The following command needs to be run on your salt master. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call tls.create_self_signed_cert tls -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Note that certs generated by the above command can be found under the \fB/etc/pki/tls/certs/\fP directory. -When using self\-signed certs, browsers will need approval before accepting the -cert. If the web application page has been cached with a non\-HTTPS version of -the app, then the browser cache will have to be cleared before it will -recognize and prompt to accept the self\-signed certificate. -.SS Starting Halite -.sp -Once you\(aqve configured the halite section of your /etc/salt/master, you can -restart the salt\-master service, and your halite instance will be available. -Depending on your configuration, the instance will be available either at -\fI\%https://localhost:8080/app\fP, \fI\%https://domain:8080/app\fP, or -\fI\%https://123.456.789.012:8080/app\fP . -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -halite requires an HTML 5 compliant browser. -.UNINDENT -.UNINDENT -.sp -All logs relating to halite are logged to the default /var/log/salt/master file. .SS HTTP Modules .sp This tutorial demonstrates using the various HTTP modules available in Salt. @@ -46041,7 +46376,7 @@ configuration instructions. .INDENT 3.5 .IP "Stuck?" .sp -There are many ways to get help from the Salt community including our +There are many ways to salt\-community including our \fI\%mailing list\fP and our \fI\%IRC channel\fP #salt. .UNINDENT @@ -47703,7 +48038,7 @@ configuration instructions. .INDENT 3.5 .IP "Stuck?" .sp -There are many ways to get help from the Salt community including our +There are many ways to salt\-community including our \fI\%mailing list\fP and our \fI\%IRC channel\fP #salt. .UNINDENT @@ -52562,6 +52897,16 @@ Restarting the \fBsalt\-master\fP service using execution module or application 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 pillar and/or sdb\&. +.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 @@ -52600,8 +52945,14 @@ describing the change so it can be fixed in Salt. 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. +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 hardening\-salt\&. +.UNINDENT +.UNINDENT .SS General rules .INDENT 0.0 .IP 1. 3 @@ -52615,6 +52966,16 @@ 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 pillar and/or sdb\&. +.UNINDENT +.UNINDENT .UNINDENT .SS Structuring States and Formulas .sp @@ -58765,7 +59126,7 @@ twice, even though \fBqa1\fP appears twice. \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 -In the 3002.2 release \fBsls_path\fP, \fBtplfile\fP, and \fBtpldir\fP have had some significant +In the 3002 release \fBsls_path\fP, \fBtplfile\fP, and \fBtpldir\fP have had some significant improvements which have the potential to break states that rely on old and broken functionality. These fixes can be enabled by setting the \fBenable_slsvars_fixes\fP feature flag to \fBTrue\fP in your minion\(aqs config file. @@ -77091,7 +77452,7 @@ $ salt\-cloud \-f show_image virtualbox image=my_vm_name New in version 2015.5.4. .sp -\fBAuthor\fP: Nitin Madhok <\fI\%nmadhok@clemson.edu\fP> +\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 @@ -85323,7 +85684,7 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, .SS Target Selection .sp The default matching that Salt utilizes is shell\-style globbing around the -minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&. +minion id. See \fI\%https://docs.python.org/3/library/fnmatch.html#module\-fnmatch\fP\&. .INDENT 0.0 .TP .B \-E, \-\-pcre @@ -85582,7 +85943,7 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, .SS Target Selection .sp The default matching that Salt utilizes is shell\-style globbing around the -minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&. +minion id. See \fI\%https://docs.python.org/3/library/fnmatch.html#module\-fnmatch\fP\&. .INDENT 0.0 .TP .B \-E, \-\-pcre @@ -86622,7 +86983,7 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, .SS Target Selection .sp The default matching that Salt utilizes is shell\-style globbing around the -minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&. +minion id. See \fI\%https://docs.python.org/3/library/fnmatch.html#module\-fnmatch\fP\&. .INDENT 0.0 .TP .B \-E, \-\-pcre @@ -87965,6 +88326,12 @@ A simple beacon to watch journald for specific entries T} _ T{ +\fBjunos_rre_keys\fP +T} T{ +Junos redundant routing engine beacon. +T} +_ +T{ \fBload\fP T} T{ Beacon to emit system load averages @@ -88061,6 +88428,12 @@ The status beacon is intended to send a basic health check event up to the maste T} _ T{ +\fBswapusage\fP +T} T{ +Beacon to monitor swap usage. +T} +_ +T{ \fBtelegram_bot_msg\fP T} T{ Beacon to emit Telegram messages @@ -88075,7 +88448,7 @@ _ T{ \fBwatchdog\fP T} T{ -watchdog beacon +Watch files and translate the changes into salt events. T} _ T{ @@ -88085,7 +88458,7 @@ Beacon to fire events at login of users as registered in the wtmp file T} _ .TE -.SS salt.beacons.adb module +.SS salt.beacons.adb .sp Beacon to emit adb device state changes for Android devices .sp @@ -88122,7 +88495,7 @@ beacons: .B salt.beacons.adb.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.aix_account module +.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 @@ -88156,7 +88529,7 @@ beacons: .B salt.beacons.aix_account.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.avahi_announce module +.SS salt.beacons.avahi_announce .sp Beacon to announce via avahi (zeroconf) .sp @@ -88247,7 +88620,7 @@ beacons: .B salt.beacons.avahi_announce.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.bonjour_announce module +.SS salt.beacons.bonjour_announce .sp Beacon to announce via Bonjour (zeroconf) .INDENT 0.0 @@ -88577,7 +88950,7 @@ it will override the previously defined threshold. .B salt.beacons.diskusage.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.glxinfo module +.SS salt.beacons.glxinfo .sp Beacon to emit when a display is available to a linux machine .sp @@ -88609,7 +88982,7 @@ beacons: .B salt.beacons.glxinfo.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.haproxy module +.SS salt.beacons.haproxy .sp Watch current connections of haproxy server backends. Fire an event when over a specified threshold. @@ -88802,6 +89175,39 @@ beacons: .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 @@ -88852,8 +89258,63 @@ beacons: .B salt.beacons.load.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.log module -.SS salt.beacons.memusage module +.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: + \- tags: + : + regex: +.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 @@ -89272,7 +89733,7 @@ beacons: .B salt.beacons.pkg.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.proxy_example module +.SS salt.beacons.proxy_example .sp Example beacon to use with salt\-proxy .INDENT 0.0 @@ -89310,7 +89771,7 @@ beacons: .B salt.beacons.proxy_example.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.ps module +.SS salt.beacons.ps .sp Send events covering process status .INDENT 0.0 @@ -89342,7 +89803,7 @@ processes are running or stopped. .B salt.beacons.ps.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.salt_proxy module +.SS salt.beacons.salt_proxy .sp Beacon to manage and report the status of one or more salt proxy processes @@ -89531,7 +89992,7 @@ beacons: .B salt.beacons.sh.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.smartos_imgadm module +.SS salt.beacons.smartos_imgadm .sp Beacon that fires events on image import/delete. .INDENT 0.0 @@ -89566,7 +90027,7 @@ Poll imgadm and compare available images .B salt.beacons.smartos_imgadm.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.smartos_vmadm module +.SS salt.beacons.smartos_vmadm .sp Beacon that fires events on vm state changes .INDENT 0.0 @@ -89601,7 +90062,7 @@ Poll vmadm for changes .B salt.beacons.smartos_vmadm.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.status module +.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. @@ -89751,6 +90212,42 @@ Return status for requested information .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 @@ -89811,14 +90308,12 @@ beacons: .B salt.beacons.twilio_txt_msg.validate(config) Validate the beacon configuration .UNINDENT -.SS salt.beacons.watchdog module +.SS salt.beacons.watchdog .sp -watchdog beacon +Watch files and translate the changes into salt events. .sp New in version 2019.2.0. -.sp -Watch files and translate the changes into salt events .INDENT 0.0 .TP .B depends @@ -90700,6 +91195,12 @@ GoGrid Cloud Module T} _ T{ +\fBhetzner\fP +T} T{ +Hetzner Cloud Module +T} +_ +T{ \fBjoyent\fP T} T{ Joyent Cloud Module @@ -92572,16 +93073,17 @@ The size of the volume, in GiBs. Defaults to \fB10\fP\&. Integer. The snapshot\-id from which to create the volume. Integer. .TP .B type -The volume type. This can be gp2 for General Purpose SSD, io1 for Provisioned -IOPS SSD, st1 for Throughput Optimized HDD, sc1 for Cold HDD, or standard for -Magnetic volumes. String. +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\&. +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. @@ -94337,6 +94839,163 @@ salt\-cloud \-a stop vm_name .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: + driver: hetzner +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.cloud.clouds.hetzner.avail_images(call=None) +.UNINDENT +.INDENT 0.0 +.TP +.B salt.cloud.clouds.hetzner.avail_locations(call=None) +.UNINDENT +.INDENT 0.0 +.TP +.B salt.cloud.clouds.hetzner.avail_sizes(call=None) +.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) +.UNINDENT +.INDENT 0.0 +.TP +.B salt.cloud.clouds.hetzner.list_nodes_full(call=None) +.UNINDENT +.INDENT 0.0 +.TP +.B salt.cloud.clouds.hetzner.list_ssh_keys(call=None) +.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) +.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 @@ -103582,7 +104241,7 @@ See Getting started with VMware to get started. .INDENT 0.0 .TP .B codeauthor -Nitin Madhok <\fI\%nmadhok@clemson.edu\fP> +Nitin Madhok <\fI\%nmadhok@g.clemson.edu\fP> .UNINDENT .SS Dependencies .INDENT 0.0 @@ -105092,6 +105751,53 @@ nyc\-2gb\-1cpu\-ubuntu\-17\-04: .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 +.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 +.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) @@ -105099,6 +105805,11 @@ 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 @@ -105129,6 +105840,16 @@ 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 @@ -105154,6 +105875,11 @@ 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 "start" action on a VM .UNINDENT @@ -105860,7 +106586,7 @@ Send events from webhook api T} _ .TE -.SS salt.engines.docker_events module +.SS salt.engines.docker_events .sp Send events from Docker events :Depends: Docker API >= 1.22 @@ -106266,7 +106992,7 @@ It would also be possible to add a password to the irc channel, or only allow in .UNINDENT .UNINDENT .UNINDENT -.SS salt.engines.junos_syslog module +.SS salt.engines.junos_syslog .SS Junos Syslog Engine .sp New in version 2017.7.0. @@ -106411,7 +107137,7 @@ The source for parsing the syslog messages is taken from: .TP .B salt.engines.junos_syslog.start(port=516, **kwargs) .UNINDENT -.SS salt.engines.libvirt_events module +.SS salt.engines.libvirt_events .sp An engine that listens for libvirt events and resends them to the salt event bus. .sp @@ -106931,7 +107657,7 @@ List of hosts or IPs to be allowed. List of hosts of IPs to be ignored. .UNINDENT .UNINDENT -.SS salt.engines.reactor module +.SS salt.engines.reactor .sp Setup Reactor .sp @@ -106958,7 +107684,7 @@ reactor: .TP .B salt.engines.reactor.start(refresh_interval=None, worker_threads=None, worker_hwm=None) .UNINDENT -.SS salt.engines.redis_sentinel module +.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. @@ -107005,7 +107731,7 @@ redis .TP .B salt.engines.redis_sentinel.start(hosts, channels, tag=None) .UNINDENT -.SS salt.engines.script module +.SS salt.engines.script .sp Send events based on a script\(aqs stdout .sp @@ -107079,7 +107805,7 @@ on the event bus with the data obj as is. .UNINDENT .UNINDENT .UNINDENT -.SS salt.engines.slack module +.SS salt.engines.slack .sp An engine that reads messages from Slack and can act on them .INDENT 0.0 @@ -107586,7 +108312,7 @@ engines: .B salt.engines.sqs_events.start(queue, profile=None, tag=\(aqsalt/engine/sqs\(aq, owner_acct_id=None) Listen to sqs and fire message on event bus .UNINDENT -.SS salt.engines.stalekey module +.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 @@ -107628,7 +108354,7 @@ A simple test engine, not intended for real use but as an example .B salt.engines.test.start() Listen to events and write them to a log file .UNINDENT -.SS salt.engines.thorium module +.SS salt.engines.thorium .sp Manage the Thorium complex event reaction system .INDENT 0.0 @@ -107720,7 +108446,7 @@ Sudo executor module T} _ .TE -.SS salt.executors.direct_call module +.SS salt.executors.direct_call .sp Direct call executor module .INDENT 0.0 @@ -107728,7 +108454,7 @@ Direct call executor module .B salt.executors.direct_call.execute(opts, data, func, args, kwargs) Directly calls the given function with arguments .UNINDENT -.SS salt.executors.docker module +.SS salt.executors.docker .sp Docker executor module .sp @@ -107746,7 +108472,7 @@ was unable to be run. .B salt.executors.docker.execute(opts, data, func, args, kwargs) Directly calls the given function with arguments .UNINDENT -.SS salt.executors.splay module +.SS salt.executors.splay .sp Splay function calls across targeted minions .INDENT 0.0 @@ -107790,7 +108516,7 @@ salt \-t 310 \-\-module\-executors=\(aq[splay, direct_call]\(aq \-\-executor\-op .UNINDENT .UNINDENT .UNINDENT -.SS salt.executors.sudo module +.SS salt.executors.sudo .sp Sudo executor module .INDENT 0.0 @@ -109497,7 +110223,7 @@ Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> new .TP .B depends -salt.utils, salt.ext.six, salt.module.cmdmod +salt.utils, salt.module.cmdmod .TP .B platform SmartOS @@ -113180,7 +113906,7 @@ Package support for openSUSE via the zypper package manager T} _ .TE -.SS salt.modules.acme module +.SS salt.modules.acme .SS ACME / Let\(aqs Encrypt module .sp This module currently looks for certbot script in the $PATH as @@ -113455,7 +114181,7 @@ Date in ISO format when a certificate should first be renewed Date of certificate renewal in ISO format. .UNINDENT .UNINDENT -.SS salt.modules.aix_group module +.SS salt.modules.aix_group .sp Manage groups on Solaris .sp @@ -113609,7 +114335,7 @@ salt \(aq*\(aq group.members foo \(aquser1,user2,user3,...\(aq foo:x:1234:user1,user2,user3,... .UNINDENT .UNINDENT -.SS salt.modules.aix_shadow module +.SS salt.modules.aix_shadow .sp Manage account locks on AIX systems .sp @@ -115142,7 +115868,7 @@ salt \(aq*\(aq pkg.version ... .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.aptly module +.SS salt.modules.aptly .sp Aptly Debian repository manager. .sp @@ -119932,7 +120658,7 @@ salt\-call azurearm_compute.virtual_machines_list_available_sizes testvm testgro .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.azurearm_dns module +.SS salt.modules.azurearm_dns .sp Azure (ARM) DNS Execution Module .sp @@ -123408,7 +124134,7 @@ salt myminion bamboohr.update_employee 1138 items=\(aq{"nickname": ""} .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.baredoc module +.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. @@ -123562,7 +124288,7 @@ salt myminion baredoc.state_docs at .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.bcache module +.SS salt.modules.bcache .sp Module for managing BCache sets .sp @@ -124123,7 +124849,7 @@ salt \(aq*\(aq beacons.modify ps "[{\(aqsalt\-master\(aq: \(aqstopped\(aq}, {\(a .INDENT 0.0 .TP .B salt.modules.beacons.reset(**kwargs) -Resest beacon configuration on the minion +Reset beacon configuration on the minion .sp CLI Example: .INDENT 7.0 @@ -125897,7 +126623,7 @@ salt \(aq*\(aq bluetoothd.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto3_elasticache module +.SS salt.modules.boto3_elasticache .SS Execution module for Amazon Elasticache using boto3 .sp New in version 2017.7.0. @@ -126500,7 +127226,7 @@ salt myminion boto3_elasticache.revoke_cache_security_group_ingress .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto3_elasticsearch module +.SS salt.modules.boto3_elasticsearch .sp Connection module for Amazon Elasticsearch Service .sp @@ -127666,7 +128392,7 @@ Upon failure, also contains a key \(aqerror\(aq with the error message as value. New in version Natrium. .UNINDENT -.SS salt.modules.boto3_route53 module +.SS salt.modules.boto3_route53 .sp Execution module for Amazon Route53 written against Boto 3 .sp @@ -128244,7 +128970,7 @@ salt myminion boto3_route53.update_hosted_zone_comment Name=example.org. .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto3_sns module +.SS salt.modules.boto3_sns .sp Connection module for Amazon SNS .INDENT 0.0 @@ -128534,7 +129260,7 @@ salt myminion boto3_sns.unsubscribe my_subscription_arn region=us\-east\-1 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_apigateway module +.SS salt.modules.boto_apigateway .sp Connection module for Amazon APIGateway .sp @@ -130511,7 +131237,7 @@ salt myminion boto_cloudfront.update_distribution name=mydistribution profile=aw .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_cloudtrail module +.SS salt.modules.boto_cloudtrail .sp Connection module for Amazon CloudTrail .sp @@ -131056,7 +131782,7 @@ salt myminion boto_cloudwatch.get_all_alarms region=us\-east\-1 \-\-out=txt .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_cloudwatch_event module +.SS salt.modules.boto_cloudwatch_event .sp Connection module for Amazon CloudWatch Events .sp @@ -131280,7 +132006,7 @@ salt myminion boto_cloudwatch_event.remove_targets myrule [\(aqTarget1\(aq] .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_cognitoidentity module +.SS salt.modules.boto_cognitoidentity .sp Connection module for Amazon CognitoIdentity .sp @@ -131546,7 +132272,7 @@ salt myminion boto_cognitoidentity.update_identity_pool my_id_pool_id my_id_pool .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_datapipeline module +.SS salt.modules.boto_datapipeline .sp Connection module for Amazon Data Pipeline .sp @@ -133326,7 +134052,7 @@ salt myminion boto_ec2.unassign_private_ip_addresses network_interface_name=my_e New in version 2017.7.0. .UNINDENT -.SS salt.modules.boto_efs module +.SS salt.modules.boto_efs .sp Connection module for Amazon EFS .sp @@ -134134,7 +134860,7 @@ salt myminion boto_elasticache.subnet_group_exists my\-param\-group .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_elasticsearch_domain module +.SS salt.modules.boto_elasticsearch_domain .sp Connection module for Amazon Elasticsearch Service .sp @@ -135107,7 +135833,7 @@ salt myminion boto_elb.set_tags my\-elb\-name "{\(aqTag1\(aq: \(aqValue\(aq, \(a .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_elbv2 module +.SS salt.modules.boto_elbv2 .sp Connection module for Amazon ALB .sp @@ -136900,7 +137626,7 @@ salt myminion boto_iam.user_exists_in_group myuser mygroup .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_iot module +.SS salt.modules.boto_iot .sp Connection module for Amazon IoT .sp @@ -137554,7 +138280,7 @@ salt myminion boto_iot.topic_rule_exists myrule .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_kinesis module +.SS salt.modules.boto_kinesis .sp Connection module for Amazon Kinesis .sp @@ -138293,7 +139019,7 @@ salt myminion boto_kms.update_key_description \(aqalias/mykey\(aq \(aqMy key\(aq .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_lambda module +.SS salt.modules.boto_lambda .sp Connection module for Amazon Lambda .sp @@ -139981,7 +140707,7 @@ argument instead. .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_s3 module +.SS salt.modules.boto_s3 .sp Connection module for Amazon S3 using boto3 .sp @@ -140106,7 +140832,7 @@ salt myminion boto_s3.upload_file \e .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_s3_bucket module +.SS salt.modules.boto_s3_bucket .sp Connection module for Amazon S3 Buckets .sp @@ -141443,7 +142169,7 @@ salt myminion boto_sqs.set_attributes myqueue \(aq{ReceiveMessageWaitTimeSeconds .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.boto_ssm module +.SS salt.modules.boto_ssm .sp Connection module for Amazon SSM .INDENT 0.0 @@ -143491,6 +144217,55 @@ salt \(aq*\(aq shadow.del_password username .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 @@ -144353,7 +145128,7 @@ salt \(aq*\(aq cabal.update .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.capirca_acl module +.SS salt.modules.capirca_acl .SS Capirca ACL .sp Generate ACL (firewall) configuration for network devices. @@ -145934,7 +146709,7 @@ salt \(aq*\(aq cassandra.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.celery module +.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. @@ -146003,7 +146778,7 @@ Raise timeout exception if waiting for task result times out. Default: False Config dict for celery app, See celery documentation .UNINDENT .UNINDENT -.SS salt.modules.ceph module +.SS salt.modules.ceph .sp Module to provide ceph control with salt. .INDENT 0.0 @@ -147885,7 +148660,7 @@ salt "*" chocolatey.version check_remote=True .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.chronos module +.SS salt.modules.chronos .sp Module providing a simple management interface to a chronos cluster. .sp @@ -147978,7 +148753,7 @@ salt chronos\-minion\-id chronos.update_job my\-job \(aq\(aq .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.chroot module +.SS salt.modules.chroot .INDENT 0.0 .TP .B maintainer @@ -148152,7 +148927,7 @@ salt \(aq*\(aq chroot.sls /chroot stuff pillar=\(aq{"foo": "bar"}\(aq .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.cimc module +.SS salt.modules.cimc .sp Module to provide Cisco UCS compatibility to Salt .INDENT 0.0 @@ -149018,7 +149793,7 @@ salt \(aq*\(aq cimc.tftp_update_cimc foo.bar.com HP\-SL2.bin .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.ciscoconfparse_mod module +.SS salt.modules.ciscoconfparse_mod .sp Execution module for \fI\%ciscoconfparse\fP .sp @@ -150195,6 +150970,15 @@ salt myminion cmd.powershell \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -150505,6 +151289,15 @@ salt myminion cmd.powershell_all \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -150757,6 +151550,15 @@ salt myminion cmd.retcode \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -150990,6 +151792,15 @@ salt myminion cmd.run \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -151139,7 +151950,7 @@ 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.2. +New in version 3002. .UNINDENT @@ -151300,6 +152111,15 @@ salt myminion cmd.run_all \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -151639,6 +152459,15 @@ salt myminion cmd.run_bg \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -151837,6 +152666,15 @@ salt myminion cmd.run_chroot \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -152040,6 +152878,15 @@ salt myminion cmd.run_stderr \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -152284,6 +153131,15 @@ salt myminion cmd.run_stdout \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -152559,6 +153415,15 @@ salt myminion cmd.script \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -152764,6 +153629,15 @@ salt myminion cmd.script_retcode \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -152966,6 +153840,15 @@ salt myminion cmd.shell \(aqsome command\(aq env=\(aq{"FOO": "bar"}\(aq .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 @@ -155632,7 +156515,7 @@ New in version 2018.3.0. 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.2. +New in version 3002. .UNINDENT .sp @@ -156582,7 +157465,7 @@ Some OS\(aq do not support specifying user via the \fIcrontab\fP command i.e. (S .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.cryptdev module +.SS salt.modules.cryptdev .sp Salt module to manage Unix cryptsetup jobs and the crypttab file .sp @@ -160253,7 +161136,7 @@ salt ns1 dnsutil.serial example.com .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.dockercompose module +.SS salt.modules.dockercompose .sp Module to import docker\-compose via saltstack .sp @@ -167461,7 +168344,7 @@ salt \(aq*\(aq drbd.status name= .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.dummyproxy_pkg module +.SS salt.modules.dummyproxy_pkg .sp Package support for the dummy proxy used by the test suite .INDENT 0.0 @@ -167504,7 +168387,7 @@ salt \(aq*\(aq pkg.version ... .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.dummyproxy_service module +.SS salt.modules.dummyproxy_service .sp Provide the service module for the dummy proxy used in integration tests .INDENT 0.0 @@ -170182,14 +171065,14 @@ salt \(aq*\(aq eselect.set_target kernel linux\-3.17.5\-gentoo .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.esxcluster module +.SS salt.modules.esxcluster .sp Module used to access the esxcluster proxy connection methods .INDENT 0.0 .TP .B salt.modules.esxcluster.get_details() .UNINDENT -.SS salt.modules.esxdatacenter module +.SS salt.modules.esxdatacenter .sp Module used to access the esxdatacenter proxy connection methods .INDENT 0.0 @@ -170236,7 +171119,7 @@ salt \(aqexsi\-proxy\(aq esxi.cmd get_service_policy service_name=\(aqssh\(aq .TP .B salt.modules.esxi.get_details() .UNINDENT -.SS salt.modules.esxvm module +.SS salt.modules.esxvm .sp Module used to access the esx proxy connection methods .INDENT 0.0 @@ -170514,7 +171397,7 @@ salt myminion etcd.watch /patch/to/key host=127.0.0.1 port=2379 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.ethtool module +.SS salt.modules.ethtool .sp Module for running ethtool command .sp @@ -171382,7 +172265,7 @@ New in version 3001. 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.2. +New in version 3002. .UNINDENT .UNINDENT @@ -171453,7 +172336,7 @@ Changed in version 3001: selinux attributes added 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.2. +New in version 3002. .UNINDENT .sp @@ -172343,7 +173226,7 @@ New in version 2016.3.0. 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.2. +New in version 3002. .UNINDENT .sp @@ -172444,7 +173327,7 @@ Salt fileserver (i.e. one beginning with \fBsalt://\fP). 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.2. +New in version 3002. .UNINDENT .sp @@ -173488,7 +174371,7 @@ New in version 3001. 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.2. +New in version 3002. .UNINDENT .sp @@ -175769,6 +176652,11 @@ salt \(aq*\(aq sysctl.persist coretemp_load NO config=/boot/loader.conf .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 @@ -175782,7 +176670,7 @@ salt \(aq*\(aq sysctl.show .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.freebsd_update module +.SS salt.modules.freebsd_update .sp Support for freebsd\-update utility on FreeBSD. .sp @@ -177158,7 +178046,7 @@ salt \(aq*\(aq service.stop .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.freezer module +.SS salt.modules.freezer .INDENT 0.0 .TP .B maintainer @@ -177294,7 +178182,7 @@ salt \(aq*\(aq freezer.status pre_install .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.gcp_addon module +.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, @@ -182839,7 +183727,7 @@ salt myminion git.worktree_rm /path/to/worktree .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.github module +.SS salt.modules.github .sp Module for interacting with the GitHub v3 API. .sp @@ -184388,7 +185276,7 @@ salt \(aq*\(aq glanceng.update_image_properties name=0e4febc2a5ab4f2c8f374b05416 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.glassfish module +.SS salt.modules.glassfish .sp Module for working with the Glassfish/Payara 4.x management API \&.. versionadded:: Carbon @@ -185924,7 +186812,7 @@ salt \(aq*\(aq gpg.verify filename=\(aq/path/to/important.file\(aq trustmodel=di .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.grafana4 module +.SS salt.modules.grafana4 .sp Module for working with the Grafana v4 API .sp @@ -188862,7 +189750,7 @@ salt \(aq*\(aq hashutil.sha512_digest \(aqget salted\(aq .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.heat module +.SS salt.modules.heat .sp Module for handling OpenStack Heat calls .sp @@ -189141,7 +190029,7 @@ New in version 2017.7.5,2018.3.1: The spelling mistake in parameter \fIenviromen The \fIenviroment\fP spelling mistake has been removed in Salt 3000. .UNINDENT -.SS salt.modules.helm module +.SS salt.modules.helm .sp Interface with Helm .INDENT 0.0 @@ -190777,7 +191665,7 @@ salt devserver1 hg.update /path/to/repo somebranch .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.highstate_doc module +.SS salt.modules.highstate_doc .sp This module renders highstate configuration into a more human readable format. .sp @@ -191333,7 +192221,7 @@ 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/3002.2\-108\-g4f096201ea\(aq, hide_fields=None, raise_error=True, formdata=False, formdata_fieldname=None, formdata_filename=None, decode_body=True, **kwargs) +.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/"3003"\(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 @@ -191422,7 +192310,7 @@ salt \(aq*\(aq http.wait_for_successful_query http://somelink.com/ wait_for=160 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.icinga2 module +.SS salt.modules.icinga2 .sp Module to provide icinga2 compatibility to salt. .sp @@ -191546,12 +192434,12 @@ salt \(aq*\(aq icinga2.save_cert domain.tld master.domain.tld .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.idem module +.SS salt.modules.idem .SS Idem Support .sp This module provides access to idem execution modules .sp -New in version 3002.2. +New in version 3002. .INDENT 0.0 .TP @@ -194074,10 +194962,10 @@ API Example: .sp .nf .ft C -import salt -sc = salt.client.get_local_client() -sc.cmd(\(aqtarget\(aq, \(aqini.get_ini\(aq, - [path_to_ini_file]) +import salt.client +with salt.client.giet_local_client() as sc: + sc.cmd(\(aqtarget\(aq, \(aqini.get_ini\(aq, + [path_to_ini_file]) .ft P .fi .UNINDENT @@ -194107,10 +194995,10 @@ API Example: .sp .nf .ft C -import salt -sc = salt.client.get_local_client() -sc.cmd(\(aqtarget\(aq, \(aqini.get_option\(aq, - [path_to_ini_file, section_name, option]) +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 @@ -194140,10 +195028,10 @@ API Example: .sp .nf .ft C -import salt -sc = salt.client.get_local_client() -sc.cmd(\(aqtarget\(aq, \(aqini.get_section\(aq, - [path_to_ini_file, section_name]) +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 @@ -194206,10 +195094,10 @@ API Example: .sp .nf .ft C -import salt -sc = salt.client.get_local_client() -sc.cmd(\(aqtarget\(aq, \(aqini.remove_section\(aq, - [path_to_ini_file, section_name]) +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 @@ -194260,10 +195148,12 @@ API Example: .sp .nf .ft C -import salt -sc = salt.client.get_local_client() -sc.cmd(\(aqtarget\(aq, \(aqini.set_option\(aq, - [\(aqpath_to_ini_file\(aq, \(aq{"section_to_change": {"key": "value"}}\(aq]) +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{"section_to_change": {"key": "value"}}\(aq] + ) .ft P .fi .UNINDENT @@ -194283,7 +195173,7 @@ salt \(aq*\(aq ini.set_option /path/to/ini \(aq{section_foo: {key: value}}\(aq .UNINDENT .SS salt.modules.inspectlib package .SS Submodules -.SS salt.modules.inspectlib.collector module +.SS salt.modules.inspectlib.collector .INDENT 0.0 .TP .B class salt.modules.inspectlib.collector.Inspector(cachedir=None, piddir=None, pidfilename=None) @@ -194384,7 +195274,7 @@ Check if PID is still alive. .B salt.modules.inspectlib.collector.main(dbfile, pidfile, mode) Main analyzer routine. .UNINDENT -.SS salt.modules.inspectlib.dbhandle module +.SS salt.modules.inspectlib.dbhandle .INDENT 0.0 .TP .B class salt.modules.inspectlib.dbhandle.DBHandle(path) @@ -194416,7 +195306,7 @@ Init the database, if required. Purge whole database. .UNINDENT .UNINDENT -.SS salt.modules.inspectlib.exceptions module +.SS salt.modules.inspectlib.exceptions .INDENT 0.0 .TP .B exception salt.modules.inspectlib.exceptions.InspectorKiwiProcessorException @@ -194437,7 +195327,7 @@ Snapshot exception. .B exception salt.modules.inspectlib.exceptions.SIException System information exception. .UNINDENT -.SS salt.modules.inspectlib.query module +.SS salt.modules.inspectlib.query .INDENT 0.0 .TP .B class salt.modules.inspectlib.query.Query(scope, cachedir=None) @@ -194476,7 +195366,7 @@ Load environment. .B PID_FILE = \(aq_minion_collector.pid\(aq .UNINDENT .UNINDENT -.SS salt.modules.inspectlib.entities module +.SS salt.modules.inspectlib.entities .INDENT 0.0 .TP .B class salt.modules.inspectlib.entities.AllowedDir @@ -194502,7 +195392,7 @@ Config file, belongs to the package .B class salt.modules.inspectlib.entities.PayloadFile Payload file. .UNINDENT -.SS salt.modules.inspectlib.fsdb module +.SS salt.modules.inspectlib.fsdb .INDENT 0.0 .TP .B codeauthor @@ -194711,7 +195601,7 @@ Update object(s) in the database. .B class salt.modules.inspectlib.fsdb.CsvDBEntity Serializable object for the table. .UNINDENT -.SS salt.modules.inspectlib.kiwiproc module +.SS salt.modules.inspectlib.kiwiproc .INDENT 0.0 .TP .B class salt.modules.inspectlib.kiwiproc.KiwiExporter(grains, format) @@ -194740,7 +195630,7 @@ Load data by keys. .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.inspector module +.SS salt.modules.inspector .sp Module for full system inspection. .INDENT 0.0 @@ -195003,7 +195893,7 @@ salt myminion introspect.service_highstate requires=False .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.iosconfig module +.SS salt.modules.iosconfig .sp Cisco IOS configuration manipulation helpers .sp @@ -196783,10 +197673,6 @@ salt \(aq*\(aq ipset.list_sets .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ipset.long_range(start, end) -.UNINDENT -.INDENT 0.0 -.TP .B salt.modules.ipset.new_set(set=None, set_type=None, family=\(aqipv4\(aq, comment=False, **kwargs) New in version 2014.7.0. @@ -197332,7 +198218,7 @@ salt \(aq*\(aq iptables.version family=ipv6 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.iwtools module +.SS salt.modules.iwtools .sp Support for Wireless Tools for Linux .INDENT 0.0 @@ -197937,7 +198823,7 @@ salt \(aq*\(aq jboss7_cli.run_operation \(aq{"cli_path": "integration.modules.sy .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.jenkinsmod module +.SS salt.modules.jenkinsmod .sp Module for controlling Jenkins .INDENT 0.0 @@ -198408,7 +199294,7 @@ salt myminion jinja.load_map myformula/map.jinja myformula .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.jira_mod module +.SS salt.modules.jira_mod .SS JIRA Execution module .sp New in version 2019.2.0. @@ -198730,6 +199616,10 @@ Returns the difference between the candidate and the current configuration .B id 0 The rollback ID value (0\-49) +.TP +.B d_id +0 +The rollback ID value (0\-49) .UNINDENT .sp CLI Example: @@ -198738,11 +199628,57 @@ CLI Example: .sp .nf .ft C -salt \(aqdevice_name\(aq junos.diff id=3 +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 Aluminum. + +.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/\fP\&. +.UNINDENT +.UNINDENT .TP .B template_vars Variables to be passed into the template processing engine in addition to @@ -199066,6 +200094,12 @@ This option cannot be used if \fBformat\fP is "set". .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. @@ -199201,6 +200235,10 @@ Roll back the last committed configuration changes and commit 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) @@ -199226,11 +200264,51 @@ CLI Example: .sp .nf .ft C -salt \(aqdevice_name\(aq junos.rollback id=10 +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 Aluminum. + +.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 @@ -199282,6 +200360,51 @@ salt \(aqdevice\(aq junos.rpc get\-chassis\-inventory .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 Aluminum. + +.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 @@ -199368,10 +200491,6 @@ salt \(aqdevice_name\(aq junos.shutdown shutdown=True .UNINDENT .INDENT 0.0 .TP -.B salt.modules.junos.timeoutDecorator(function) -.UNINDENT -.INDENT 0.0 -.TP .B salt.modules.junos.unlock() Unlocks the candidate configuration. .sp @@ -199760,7 +200879,7 @@ in case force is set to True, wrong files will be skipped but secret will be cre 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 module +.SS salt.modules.kapacitor .sp Kapacitor execution module. .INDENT 0.0 @@ -202661,7 +203780,7 @@ salt \(aq*\(aq kmod.remove kvm .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.kubeadm module +.SS salt.modules.kubeadm .INDENT 0.0 .TP .B maintainer @@ -205199,7 +206318,7 @@ scope=1 attrs=\(aq\(aq server=\(aqlocalhost\(aq port=\(aq7393\(aq tls=True bindp .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.libcloud_compute module +.SS salt.modules.libcloud_compute .SS Apache Libcloud Compute Management .sp Connection module for Apache Libcloud Compute management for a full list @@ -205956,7 +207075,7 @@ salt myminion libcloud_compute.reboot_node as\-2346 profile1 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.libcloud_dns module +.SS salt.modules.libcloud_dns .SS Apache Libcloud DNS Management .sp Connection module for Apache Libcloud DNS management @@ -207213,7 +208332,7 @@ salt \(aq*\(aq acl.wipefacls /tmp/house/kitchen /tmp/house/livingroom recursive= .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.linux_ip module +.SS salt.modules.linux_ip .sp The networking module for Non\-RH/Deb Linux distros .INDENT 0.0 @@ -208695,7 +209814,7 @@ salt \(aq*\(aq logadm.show_conf name=/var/log/syslog .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.logmod module +.SS salt.modules.logmod .SS On\-demand logging .sp New in version 2017.7.0. @@ -214575,7 +215694,7 @@ salt \(aq*\(aq lxd.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_assistive module +.SS salt.modules.mac_assistive .sp This module allows you to manage assistive access on macOS minions with 10.9+ .sp @@ -215258,7 +216377,7 @@ salt \(aq*\(aq pkg.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_desktop module +.SS salt.modules.mac_desktop .sp macOS implementations of various commands in the "desktop" interface .INDENT 0.0 @@ -215504,7 +216623,7 @@ salt \(aq*\(aq group.members foo \(aquser1,user2,user3,...\(aq .sp Replaces a membership list for a local group \(aqfoo\(aq. .UNINDENT -.SS salt.modules.mac_keychain module +.SS salt.modules.mac_keychain .sp Install certificates into the keychain on Mac OS .sp @@ -215746,7 +216865,7 @@ salt \(aq*\(aq keychain.unlock_keychain /tmp/test.p12 test123 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_pkgutil module +.SS salt.modules.mac_pkgutil .sp Installer support for macOS. .sp @@ -216238,7 +217357,7 @@ salt \(aq*\(aq pkg.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_power module +.SS salt.modules.mac_power .sp Module for editing power settings on macOS .INDENT 0.0 @@ -216756,7 +217875,7 @@ salt \(aq*\(aq power.set_wake_on_network True .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_service module +.SS salt.modules.mac_service .sp The service module for macOS .sp @@ -216793,7 +217912,7 @@ be used to properly interact with the service. \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -As of the 3002.2 release, if a service name of \fBsalt\-minion\fP is passed this +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. @@ -217364,7 +218483,7 @@ salt \(aq*\(aq service.stop org.cups.cupsd .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_shadow module +.SS salt.modules.mac_shadow .sp Manage macOS local directory passwords and policies .sp @@ -217901,7 +219020,7 @@ salt \(aq*\(aq shadow.set_warndays admin 90 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_softwareupdate module +.SS salt.modules.mac_softwareupdate .sp Support for the softwareupdate command on MacOS. .INDENT 0.0 @@ -218357,7 +219476,7 @@ salt \(aq*\(aq softwareupdate.update_available "" .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_sysctl module +.SS salt.modules.mac_sysctl .sp Module for viewing and modifying sysctl parameters .INDENT 0.0 @@ -218445,6 +219564,11 @@ salt \(aq*\(aq sysctl.persist coretemp_load NO config=/etc/sysctl.conf .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 @@ -218458,7 +219582,7 @@ salt \(aq*\(aq sysctl.show .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_system module +.SS salt.modules.mac_system .sp System module for sleeping, restarting, and shutting down the system on Mac OS X .sp @@ -219174,7 +220298,7 @@ salt \(aq*\(aq system.sleep \(aq10:00 PM\(aq .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_timezone module +.SS salt.modules.mac_timezone .sp Module for editing date/time settings on macOS .INDENT 0.0 @@ -220006,7 +221130,7 @@ salt \(aq*\(aq user.rename name new_name .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mac_xattr module +.SS salt.modules.mac_xattr .sp This module allows you to manage extended attributes on files or directories .INDENT 0.0 @@ -220239,7 +221363,7 @@ The user to delete the defaults with .INDENT 0.0 .TP .B salt.modules.macdefaults.read(domain, key, user=None) -Write a default to the system +Read a default from the system .sp CLI Example: .INDENT 7.0 @@ -220263,7 +221387,7 @@ The name of the domain to read from The key of the given domain to read from .TP .B user -The user to write the defaults to +The user to read the defaults as .UNINDENT .UNINDENT .INDENT 0.0 @@ -221725,7 +222849,7 @@ minion: .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.marathon module +.SS salt.modules.marathon .sp Module providing a simple management interface to a marathon cluster. .sp @@ -222258,7 +223382,7 @@ roles: {{ roles | yaml() }} .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.mattermost module +.SS salt.modules.mattermost .sp Module for sending messages to Mattermost .sp @@ -223170,7 +224294,7 @@ salt \(aq*\(aq mine.valid .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.minion module +.SS salt.modules.minion .sp Module to provide information about minions .INDENT 0.0 @@ -225365,7 +226489,7 @@ salt minion mssql.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.msteams module +.SS salt.modules.msteams .sp Module for sending messages to MS Teams .sp @@ -227208,7 +228332,7 @@ salt \(aq*\(aq nagios_rpc.service_status hostname=webserver.domain.com service=\ .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.namecheap_domains module +.SS salt.modules.namecheap_domains .sp Namecheap Domain Management .sp @@ -227807,7 +228931,7 @@ salt \(aq*\(aq namecheap_domains_ns.update sld tld nameserver old_ip new_ip .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.namecheap_ssl module +.SS salt.modules.namecheap_ssl .sp Namecheap SSL Certificate Management .sp @@ -228697,7 +229821,7 @@ salt \(aqmy\-minion\(aq namecheap_ssl.renew 1 my\-cert\-id RapidSSL .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.namecheap_users module +.SS salt.modules.namecheap_users .sp Namecheap User Management .sp @@ -228782,7 +229906,7 @@ salt \(aqmy\-minion\(aq namecheap_users.get_balances .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_bgp module +.SS salt.modules.napalm_bgp .SS NAPALM BGP .sp Manages BGP configuration on network devices and provides statistics. @@ -229113,7 +230237,7 @@ Output Example: .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_formula module +.SS salt.modules.napalm_formula .SS NAPALM Formula helpers .sp New in version 2019.2.0. @@ -229425,7 +230549,7 @@ salt \(aq*\(aq napalm_formula.traverse "{\(aqfoo\(aq: {\(aqbar\(aq: {\(aqbaz\(aq .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_mod module +.SS salt.modules.napalm_mod .SS NAPALM helpers .sp Helpers for the NAPALM modules. @@ -232185,7 +233309,7 @@ edge01.bjm01: .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_network module +.SS salt.modules.napalm_network .SS NAPALM Network .sp Basic methods for interaction with the network device through the virtual proxy \(aqnapalm\(aq. @@ -234346,7 +235470,7 @@ salt \(aq*\(aq net.traceroute 8.8.8.8 source=127.0.0.1 ttl=5 timeout=1 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_ntp module +.SS salt.modules.napalm_ntp .SS NAPALM NTP .sp Manages NTP on network devices. @@ -234683,7 +235807,7 @@ Example output: .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_probes module +.SS salt.modules.napalm_probes .SS NAPALM Probes .sp Manages RPM/SLA probes on the network device. @@ -235082,7 +236206,7 @@ junos_minion: .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_route module +.SS salt.modules.napalm_route .SS NAPALM Route .sp Retrieves route details from network devices. @@ -235217,7 +236341,7 @@ Output example: .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_snmp module +.SS salt.modules.napalm_snmp .SS NAPALM SNMP .sp Manages SNMP on network devices. @@ -235432,7 +236556,7 @@ edge01.lon01: .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_users module +.SS salt.modules.napalm_users .SS NAPALM Users .sp Manages the configuration of the users on network devices. @@ -235606,7 +236730,7 @@ salt \(aq*\(aq users.set_users "{\(aqmircea\(aq: {}}" .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.napalm_yang_mod module +.SS salt.modules.napalm_yang_mod .SS NAPALM YANG .sp NAPALM YANG basic operations. @@ -236241,7 +237365,7 @@ salt myminion netaddress.list_cidr_ips_ipv6 192.168.0.0/20 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.netbox module +.SS salt.modules.netbox .SS NetBox .sp Module to query NetBox @@ -237210,6 +238334,11 @@ salt \(aq*\(aq sysctl.persist net.inet.icmp.icmplim 50 .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 @@ -242475,7 +243604,7 @@ salt \(aq*\(aq neutronng.subnet_update name=subnet1 dns_nameservers=\(aq["8.8.8. .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.nexus module +.SS salt.modules.nexus .sp Module for fetching artifacts from Nexus 3.x .sp @@ -242998,7 +244127,7 @@ salt \(aq*\(aq nftables.flush filter input family=ipv6 .INDENT 0.0 .TP .B salt.modules.nftables.get_policy(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) -New in version 3002.2. +New in version 3002. .sp Return the current policy for the specified table/chain @@ -243081,7 +244210,7 @@ salt \(aq*\(aq nftables.get_rules family=ipv6 .INDENT 0.0 .TP .B salt.modules.nftables.get_rules_json(family=\(aqipv4\(aq) -New in version 3002.2. +New in version 3002. .sp Return a list of dictionaries comprising the current, in\-memory rules @@ -243239,7 +244368,7 @@ salt \(aq*\(aq nftables.new_table filter family=ipv6 .INDENT 0.0 .TP .B salt.modules.nftables.save(filename=None, family=\(aqipv4\(aq) -Changed in version 3002.2. +Changed in version 3002. .sp Save the current in\-memory rules to disk. On systems where /etc/nftables is @@ -243261,7 +244390,7 @@ salt \(aq*\(aq nftables.save /etc/nftables .INDENT 0.0 .TP .B salt.modules.nftables.set_policy(table=\(aqfilter\(aq, chain=None, policy=None, family=\(aqipv4\(aq) -New in version 3002.2. +New in version 3002. .sp Set the current policy for the specified table/chain. This only works on @@ -243407,7 +244536,7 @@ salt \(aq*\(aq nginx.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.nilrt_ip module +.SS salt.modules.nilrt_ip .sp The networking module for NI Linux Real\-Time distro .INDENT 0.0 @@ -245811,7 +246940,7 @@ salt myminion nspawn.stop arch1 kill=True .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.nxos module +.SS salt.modules.nxos .sp Execution module for Cisco NX OS Switches. .sp @@ -246456,7 +247585,7 @@ salt \(aq*\(aq nxos.unset_role username=daniel role=vdc\-admin .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.nxos_api module +.SS salt.modules.nxos_api .sp Execution module to manage Cisco Nexus Switches (NX\-OS) over the NX\-API .sp @@ -246829,7 +247958,7 @@ salt \(aqregular\-minion\(aq nxos_api.show \(aqshow interfaces\(aq host=sw01.exa .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.nxos_upgrade module +.SS salt.modules.nxos_upgrade .sp Execution module to upgrade Cisco NX\-OS Switches. .sp @@ -247109,6 +248238,11 @@ salt \(aq*\(aq sysctl.persist net.inet.ip.forwarding 1 .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 @@ -247925,7 +249059,7 @@ salt \(aq*\(aq service.stop .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.openscap module +.SS salt.modules.openscap .sp Module for OpenSCAP Management .INDENT 0.0 @@ -248053,7 +249187,7 @@ salt\-call openstack_config.set /etc/keystone/keystone.conf sql connection foo .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.openstack_mng module +.SS salt.modules.openstack_mng .sp Module for OpenStack Management .INDENT 0.0 @@ -248123,7 +249257,7 @@ salt \(aq*\(aq openstack_mng.stop_service neutron .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.openvswitch module +.SS salt.modules.openvswitch .sp Support for Open vSwitch \- module with basic Open vSwitch commands. .sp @@ -248498,7 +249632,7 @@ salt \(aq*\(aq openvswitch.port_remove br0 8080 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.opkg module +.SS salt.modules.opkg .sp Support for Opkg .sp @@ -250677,7 +251811,7 @@ salt \(aq*\(aq osquery.xprotect_reports .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.out module +.SS salt.modules.out .SS Output Module .sp New in version 2018.3.0. @@ -253686,7 +254820,7 @@ salt \(aq*\(aq panos.unlock_admin username=bob .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.parallels module +.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, @@ -254849,7 +255983,7 @@ salt \(aq*\(aq partition.toggle /dev/sda 1 boot .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.pcs module +.SS salt.modules.pcs .SS Configure a Pacemaker/Corosync cluster with PCS .sp Configure Pacemaker/Cororsync clusters with the @@ -255621,7 +256755,7 @@ salt \(aq*\(aq pecl.update fuse .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.peeringdb module +.SS salt.modules.peeringdb .SS PeeringDB Module .sp New in version 2019.2.0. @@ -256172,7 +257306,7 @@ salt \(aq*\(aq pf.table add table=local_hosts addresses=\(aq["127.0.0.1", "::1"] .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.philips_hue module +.SS salt.modules.philips_hue .sp Philips HUE lamps module for proxy. .sp @@ -258417,7 +259551,7 @@ salt \(aq*\(aq pkg.backup /tmp/pkg chroot=/path/to/chroot .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.check(jail=None, chroot=None, root=None, depends=False, recompute=False, checksum=False) +.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 @@ -258469,7 +259603,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.check recompute=True +salt \(aq*\(aq pkg.check depends=True .ft P .fi .UNINDENT @@ -258484,7 +259618,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.check depends=True +salt \(aq*\(aq pkg.check recompute=True .ft P .fi .UNINDENT @@ -258504,6 +259638,21 @@ salt \(aq*\(aq pkg.check checksum=True .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 @@ -259889,7 +261038,7 @@ salt \(aq*\(aq pkg.search pattern prefix=True .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.stats(local=False, remote=False, jail=None, chroot=None, root=None) +.B salt.modules.pkgng.stats(local=False, remote=False, jail=None, chroot=None, root=None, bytes=False) Return pkgng stats. .sp CLI Example: @@ -259935,6 +261084,21 @@ salt \(aq*\(aq pkg.stats remote=True .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 @@ -262891,7 +264055,7 @@ returns a list of applied powerpath license keys .B salt.modules.powerpath.remove_license(key) Remove a license .UNINDENT -.SS salt.modules.proxy module +.SS salt.modules.proxy .sp This module allows you to manage proxy settings .INDENT 0.0 @@ -265366,7 +266530,7 @@ salt \(aq*\(aq purefb.snap_eradicate foo suffix=snap .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.pushbullet module +.SS salt.modules.pushbullet .sp Module for sending messages to Pushbullet (\fI\%https://www.pushbullet.com\fP) .sp @@ -270134,7 +271298,7 @@ salt \(aq*\(aq pkg.version ... .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.rest_sample_utils module +.SS salt.modules.rest_sample_utils .sp Utility functions for the rest_sample .INDENT 0.0 @@ -270329,7 +271493,7 @@ salt \(aq*\(aq service.stop .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.restartcheck module +.SS salt.modules.restartcheck .sp checkrestart functionality for Debian and Red Hat Based systems .sp @@ -273060,7 +274224,7 @@ salt myminion s3.put mybucket remotepath local_file=/path/to/file .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.s6 module +.SS salt.modules.s6 .sp s6 service module .sp @@ -273259,7 +274423,7 @@ salt \(aq*\(aq s6.term .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.salt_proxy module +.SS salt.modules.salt_proxy .sp Salt proxy module .sp @@ -275725,6 +276889,23 @@ salt \(aq*\(aq schedule.is_enabled .UNINDENT .INDENT 0.0 .TP +.B salt.modules.schedule.job_status(name) +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 +.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) List the jobs currently scheduled on the minion .sp @@ -275919,7 +277100,7 @@ salt \(aq*\(aq schedule.skip_job job time .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.scp module +.SS salt.modules.scp .SS SCP Module .sp New in version 2019.2.0. @@ -277339,7 +278520,7 @@ salt \(aq*\(aq serverdensity_device.update 51f7eafcdba4bb235e000ae4 name=better_ .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.servicenow module +.SS salt.modules.servicenow .sp Module for execution of ServiceNow CI (configuration items) .sp @@ -277675,8 +278856,11 @@ salt \(aq*\(aq slack.list_users api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 .UNINDENT .INDENT 0.0 .TP -.B salt.modules.slack_notify.post_message(channel, message, from_name, api_key=None, icon=None) +.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 @@ -277691,6 +278875,10 @@ Send a message to a Slack channel. \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 @@ -277727,7 +278915,7 @@ minion, and it is using a different module (or gives an error similar to Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277747,7 +278935,7 @@ salt \(aq*\(aq service.available sshd .B salt.modules.slackware_service.disable(name, **kwargs) Disable the named service to start at boot .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277767,7 +278955,7 @@ salt \(aq*\(aq service.disable .B salt.modules.slackware_service.disabled(name) Return True if the named service is enabled, false otherwise .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277787,7 +278975,7 @@ salt \(aq*\(aq service.disabled .B salt.modules.slackware_service.enable(name, **kwargs) Enable the named service to start at boot .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277807,7 +278995,7 @@ salt \(aq*\(aq service.enable .B salt.modules.slackware_service.enabled(name, **kwargs) Return True if the named service is enabled, false otherwise .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277827,7 +279015,7 @@ salt \(aq*\(aq service.enabled .B salt.modules.slackware_service.force_reload(name) Force\-reload the named service .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277847,7 +279035,7 @@ salt \(aq*\(aq service.force_reload .B salt.modules.slackware_service.get_all() Return all available boot services .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277867,7 +279055,7 @@ salt \(aq*\(aq service.get_all .B salt.modules.slackware_service.get_disabled() Return a set of services that are installed but disabled .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277887,7 +279075,7 @@ salt \(aq*\(aq service.get_disabled .B salt.modules.slackware_service.get_enabled() Return a list of service that are enabled on boot .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277909,7 +279097,7 @@ The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277929,7 +279117,7 @@ salt \(aq*\(aq service.missing sshd .B salt.modules.slackware_service.reload_(name) Reload the named service .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277949,7 +279137,7 @@ salt \(aq*\(aq service.reload .B salt.modules.slackware_service.restart(name) Restart the named service .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277969,7 +279157,7 @@ salt \(aq*\(aq service.restart .B salt.modules.slackware_service.start(name) Start the specified service .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -277991,7 +279179,7 @@ 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.2. +New in version 3002. .INDENT 7.0 .TP @@ -278028,7 +279216,7 @@ salt \(aq*\(aq service.status [service signature] .B salt.modules.slackware_service.stop(name) Stop the specified service .sp -New in version 3002.2. +New in version 3002. .sp CLI Example: @@ -278792,7 +279980,7 @@ salt \(aq*\(aq imgadm.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.smartos_nictagadm module +.SS salt.modules.smartos_nictagadm .sp Module for running nictagadm command on SmartOS :maintainer: Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> @@ -280531,7 +281719,7 @@ salt \(aq*\(aq smtp.send_msg \(aqadmin@example.com\(aq \(aqThis is a salt module .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.snapper module +.SS salt.modules.snapper .sp Module to manage filesystem snapshots with snapper .sp @@ -283824,7 +285012,7 @@ salt \(aq*\(aq solr.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.solrcloud module +.SS salt.modules.solrcloud .sp Module for solrcloud configuration .sp @@ -284955,7 +286143,7 @@ Service support for the REST example .TP .B salt.modules.ssh_pkg.remove(name=None, pkgs=None, **kwargs) .UNINDENT -.SS salt.modules.ssh_service module +.SS salt.modules.ssh_service .sp Provide the service module for the proxy\-minion SSH sample \&.. versionadded:: 2015.8.2 @@ -288834,7 +290022,7 @@ salt \(aq*\(aq sysbench.threads .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.sysfs module +.SS salt.modules.sysfs .sp Module for interfacing with SysFS .sp @@ -292036,10 +293224,17 @@ 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 \fB\(gakwargs\fP, this -is used to both test the publication data and cli argument passing, but +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. -Returns {"args": args, "kwargs": kwargs}. +.INDENT 7.0 +.TP +.B Returns +\fB{"args": args, "kwargs": kwargs}\fP +.TP +.B Return type +\fI\%dict\fP +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -292056,7 +293251,8 @@ salt \(aq*\(aq test.arg 1 "two" 3.1 txt="hello" wow=\(aq{a: 1, b: "hello"}\(aq .INDENT 0.0 .TP .B salt.modules.test.arg_clean(*args, **kwargs) -Like test.arg but cleans kwargs of the __pub* items +Like \fI\%test.arg\fP but cleans \fBkwargs\fP of the \fB__pub*\fP items +.sp CLI Example: .INDENT 7.0 .INDENT 3.5 @@ -292072,10 +293268,14 @@ salt \(aq*\(aq test.arg_clean 1 "two" 3.1 txt="hello" wow=\(aq{a: 1, b: "hello"} .INDENT 0.0 .TP .B salt.modules.test.arg_repr(*args, **kwargs) -Print out the data passed into the function \fB*args\fP and \fB\(gakwargs\fP, this -is used to both test the publication data and cli argument passing, but +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. -Returns {"args": repr(args), "kwargs": repr(kwargs)}. +.INDENT 7.0 +.TP +.B Returns +\fB{"args": repr(args), "kwargs": repr(kwargs)}\fP +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -292092,8 +293292,13 @@ salt \(aq*\(aq test.arg_repr 1 "two" 3.1 txt="hello" wow=\(aq{a: 1, b: "hello"}\ .INDENT 0.0 .TP .B salt.modules.test.arg_type(*args, **kwargs) -Print out the types of the args and kwargs. This is used to test the types -of the args and kwargs passed down to the minion +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 @@ -292181,9 +293386,9 @@ salt \(aq*\(aq test.conf_test .INDENT 0.0 .TP .B salt.modules.test.cross_test(func, args=None) -Execute a minion function via the __salt__ object in the test -module, used to verify that the minion functions can be called -via the __salt__ module. +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 @@ -292236,7 +293441,7 @@ salt \(aq*\(aq test.exception \(aqOh noes!\(aq .INDENT 0.0 .TP .B salt.modules.test.false_() -Always return False +Always return \fBFalse\fP .sp CLI Example: .INDENT 7.0 @@ -292253,7 +293458,7 @@ salt \(aq*\(aq test.false .INDENT 0.0 .TP .B salt.modules.test.fib(num) -Return the num\-th Fibonacci number, and the time it took to compute in +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. @@ -292291,7 +293496,7 @@ salt \(aq*\(aq test.get_opts .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 kwarg passing, but also to display +both test the publication data and CLI \fBkwarg\fP passing, but also to display the information available within the publication data. .sp CLI Example: @@ -292348,8 +293553,8 @@ salt \(aq*\(aq test.not_loaded .INDENT 0.0 .TP .B salt.modules.test.opts_pkg() -Return an opts package with the grains and opts for this minion. -This is primarily used to create the options used for master side +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: @@ -292437,7 +293642,8 @@ salt \(aq*\(aq test.providers .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 +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 @@ -292486,8 +293692,8 @@ Changed in version 2018.3.0: Function has been renamed from \fBtest.rand_str\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 hash_type specified by the -minion\(aqs \fBhash_type\fP config option is used. +that number. If no \fBhash_type\fP is passed, the \fBhash_type\fP specified by the +Minion\(aqs \fBhash_type\fP config option is used. .sp CLI Example: .INDENT 7.0 @@ -292557,7 +293763,7 @@ salt \(aq*\(aq test.stack .INDENT 0.0 .TP .B salt.modules.test.true_() -Always return True +Always return \fBTrue\fP .sp CLI Example: .INDENT 7.0 @@ -292574,21 +293780,19 @@ salt \(aq*\(aq test.true .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 None. -If \fIreturn_try_exception\fP is set True return the exception. +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 -CLI Example: +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 @@ -292597,7 +293801,7 @@ CLI Example: .INDENT 0.0 .TP .B salt.modules.test.tty(*args, **kwargs) -Deprecated! Moved to cmdmod. +Deprecated! Moved to \fBcmd.tty\fP .sp CLI Example: .INDENT 7.0 @@ -292692,7 +293896,7 @@ Module for running arbitrary tests with a __virtual__ function .TP .B salt.modules.test_virtual.ping() .UNINDENT -.SS salt.modules.testinframod module +.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. @@ -292700,7 +293904,7 @@ 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. -.SS salt.modules.textfsm_mod module +.SS salt.modules.textfsm_mod .SS TextFSM .sp New in version 2018.3.0. @@ -292722,8 +293926,7 @@ textfsm Python library \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -For Python 2/3 compatibility, it is more recommended to -install the \fBjtextfsm\fP library: \fBpip install jtextfsm\fP\&. +Install \fBtextfsm\fP library: \fBpip install textfsm\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 @@ -293103,7 +294306,7 @@ salt \(aq*\(aq timezone.get_hwclock .INDENT 0.0 .TP .B salt.modules.timezone.get_offset() -Get current numeric timezone offset from UCT (i.e. \-0700) +Get current numeric timezone offset from UTC (i.e. \-0700) .sp CLI Example: .INDENT 7.0 @@ -297169,7 +298372,7 @@ salt \(aq*\(aq varnish.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.vault module +.SS salt.modules.vault .sp Functions to interact with Hashicorp Vault. .INDENT 0.0 @@ -297750,7 +298953,7 @@ salt \(aq*\(aq vbox_guest.list_shared_folders_users list of users who have access to auto\-mounted shared folders .UNINDENT .UNINDENT -.SS salt.modules.vboxmanage module +.SS salt.modules.vboxmanage .sp Support for VirtualBox using the VBoxManage command .sp @@ -298047,7 +299250,7 @@ salt \(aq*\(aq vboxmanage.vboxcmd .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.vcenter module +.SS salt.modules.vcenter .sp Module used to access the vcenter proxy connection methods .INDENT 0.0 @@ -298253,7 +299456,7 @@ all migration functions .SS Units Units specification .sp -New in version 3002.2. +New in version 3002. .sp The string should contain a number optionally followed @@ -299567,7 +300770,7 @@ salt \(aq*\(aq virt.get_xml .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, **kwargs) +.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 @@ -299576,16 +300779,137 @@ Initialize a new vm .IP \(bu 2 \fBname\fP \-\- name of the virtual machine to create .IP \(bu 2 -\fBcpu\fP \-\- Number of virtual CPUs to assign to the virtual machine +\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 Aluminium. + + .IP \(bu 2 \fBmem\fP \-\- .sp -Amount of memory to allocate to the virtual machine in MiB. Since 3002.2, a dictionary can be used to +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 and \fBmin_guarantee\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. +\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 @@ -299596,17 +300920,24 @@ an integer. \(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 + \(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.2. +Changed in version 3002. .IP \(bu 2 @@ -299716,6 +301047,17 @@ password to connect with, overriding defaults 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 Aluminium. + + .IP \(bu 2 \fBboot\fP \-\- .sp @@ -299753,8 +301095,290 @@ Values can be \fBhd\fP, \fBfd\fP, \fBcdrom\fP or \fBnetwork\fP\&. .sp By default, the value will \fB"hd"\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 Aluminium. + +.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 Aluminium. + +.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 Aluminium. + +.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 Aluminium. + + +.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 Aluminium. + + +.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 Aluminium. + + +.UNINDENT +.UNINDENT +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 conains 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 "emulator", 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 Boot parameters definition .sp The boot parameters dictionary can contains the following properties: @@ -299815,6 +301439,33 @@ 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"hugepages": [{"nodeset": "1\-4,^3", "size": "2m"}, {"nodeset": "3", "size": "1g"}]\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 Network Interfaces Definitions .sp @@ -299943,6 +301594,18 @@ virt: .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 +\&..versionadded:: Aluminium +.TP +.B iothread_id +I/O thread id to assign the disk to. +(Default: none assigned) +.sp +\&..versionadded:: Aluminium .UNINDENT Graphics Definition .sp @@ -299969,6 +301632,41 @@ It has a \fBtype\fP property with \fBaddress\fP and \fBNone\fP as possible value By default, not setting the \fBlisten\fP part of the dictionary will default to listen on all addresses. .UNINDENT +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 CLI Example.INDENT 7.0 .INDENT 3.5 .sp @@ -300289,7 +301987,7 @@ Shared storage migration .sp True to connect over ssh .sp -Deprecated since version 3002.2. +Deprecated since version 3002. .IP \(bu 2 @@ -300367,7 +302065,7 @@ username: Username to connect with target host password: Password to connect with target host .UNINDENT .sp -New in version 3002.2. +New in version 3002. .UNINDENT @@ -300422,7 +302120,7 @@ Attempt to execute non\-shared storage "all" migration .sp True to connect over ssh .sp -Deprecated since version 3002.2. +Deprecated since version 3002. .IP \(bu 2 @@ -300494,7 +302192,7 @@ username: Username to connect with target host password: Password to connect with target host .UNINDENT .sp -New in version 3002.2. +New in version 3002. .UNINDENT @@ -300546,7 +302244,7 @@ Attempt to execute non\-shared storage "inc" migration .sp True to connect over ssh .sp -Deprecated since version 3002.2. +Deprecated since version 3002. .IP \(bu 2 @@ -300618,7 +302316,7 @@ username: Username to connect with target host password: Password to connect with target host .UNINDENT .sp -New in version 3002.2. +New in version 3002. .UNINDENT @@ -300674,35 +302372,87 @@ salt \(aq*\(aq virt.migrate_start_postcopy .UNINDENT .INDENT 0.0 .TP -.B salt.modules.virt.nesthash() +.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, **kwargs) +.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 +\fBname\fP \-\- Network name. .IP \(bu 2 -\fBbridge\fP \-\- Bridge name +\fBbridge\fP \-\- Bridge name. .IP \(bu 2 -\fBforward\fP \-\- Forward mode(bridge, router, nat) +\fBforward\fP \-\- +.sp +Forward mode (bridge, router, nat). +.sp +Changed in version Aluminium: a \fBNone\fP value creates an isolated network with no forwarding at all + + .IP \(bu 2 -\fBvport\fP \-\- Virtualport type +\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 Aluminium: possible dictionary value + + .IP \(bu 2 -\fBtag\fP \-\- Vlan tag +\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 Aluminium: possible dictionary value + + .IP \(bu 2 -\fBautostart\fP \-\- Network autostart (default True) +\fBautostart\fP \-\- Network autostart (default True). .IP \(bu 2 -\fBstart\fP \-\- Network start (default True) +\fBstart\fP \-\- Network start (default True). .IP \(bu 2 \fBipv4_config\fP (\fI\%dict\fP\fI or \fP\fI\%None\fP) \-\- .sp -IP v4 configuration +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\&. @@ -300713,7 +302463,7 @@ New in version 3000. .IP \(bu 2 \fBipv6_config\fP (\fI\%dict\fP\fI or \fP\fI\%None\fP) \-\- .sp -IP v6 configuration +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\&. @@ -300722,15 +302472,173 @@ New in version 3000. .IP \(bu 2 -\fBconnection\fP \-\- libvirt connection URI, overriding defaults +\fBconnection\fP \-\- libvirt connection URI, overriding defaults. .IP \(bu 2 -\fBusername\fP \-\- username to connect with, overriding defaults +\fBusername\fP \-\- username to connect with, overriding defaults. .IP \(bu 2 -\fBpassword\fP \-\- password to connect with, overriding defaults +\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 Aluminium. + + +.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 -** IP configuration definition +New in version Aluminium. + + +.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 Aluminium. + + +.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: "eth10 eth11 eth12" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version Aluminium. + + +.IP \(bu 2 +\fBaddresses\fP \-\- +.sp +whitespace separated list of addreses 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: "0000:04:00.1 0000:e3:01.2" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version Aluminium. + + +.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: "eth0" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version Aluminium. + + +.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: "v=spf1 a \-all" + _http.tcp.example.com: "name=value,paper=A4" + 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 Aluminium. + + +.UNINDENT +.UNINDENT +IP configuration definition .sp Both the IPv4 and IPv6 configuration dictionaries can contain the following properties: .INDENT 7.0 @@ -300739,7 +302647,49 @@ Both the IPv4 and IPv6 configuration dictionaries can contain the following prop CIDR notation for the network. For example \(aq192.168.124.0/24\(aq .TP .B dhcp_ranges -A list of dictionary with \fB\(aqstart\(aq\fP and \fB\(aqend\(aq\fP properties. +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 Aluminium. + +.TP +.B bootp +A dictionary with a \fBfile\fP property and an optional \fBserver\fP one. +.sp +New in version Aluminium. + +.TP +.B tftp +The path to the TFTP root directory to serve. +.sp +New in version Aluminium. + +.UNINDENT +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: @@ -300966,6 +302916,242 @@ salt \(aq*\(aq virt.network_undefine default .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\fI\%None\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\fI\%None\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: "eth10 eth11 eth12" +.ft P +.fi +.UNINDENT +.UNINDENT + +.IP \(bu 2 +\fBaddresses\fP \-\- +.sp +whitespace separated list of addreses 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: "0000:04:00.1 0000:e3:01.2" +.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: "eth0" +.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: "v=spf1 a \-all" + _http.tcp.example.com: "name=value,paper=A4" + 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 Aluminium. + +.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 Aluminium. + .UNINDENT .INDENT 0.0 .TP @@ -302496,7 +304682,7 @@ salt \(aq*\(aq virt.undefine .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, test=False, boot_dev=None, **kwargs) +.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, **kwargs) Update the definition of an existing domain. .INDENT 7.0 .TP @@ -302505,16 +304691,25 @@ Update the definition of an existing domain. .IP \(bu 2 \fBname\fP \-\- Name of the domain to update .IP \(bu 2 -\fBcpu\fP \-\- Number of virtual CPUs to assign to the virtual machine +\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.2, a dictionary can be used to +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 and \fBmin_guarantee\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. +\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. @@ -302531,7 +304726,7 @@ is mapped to \fBnull\fP in sls file, pass \fBnull\fP in sls file instead. .UNINDENT .UNINDENT .sp -Changed in version 3002.2. +Changed in version 3002. .IP \(bu 2 @@ -302599,7 +304794,51 @@ Values can be \fBhd\fP, \fBfd\fP, \fBcdrom\fP or \fBnetwork\fP\&. .sp By default, the value will \fB"hd"\fP\&. .sp -New in version 3002.2. +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 Aluminium. + + +.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 Aluminium. + + +.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 Aluminium. + + +.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 Aluminium. .IP \(bu 2 @@ -302610,6 +304849,111 @@ run in dry\-run mode if set to True 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 Aluminium. + +.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 Aluminium. + +.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 Aluminium. + + .UNINDENT .TP .B Returns @@ -305448,12 +307792,14 @@ Default is None. Should be used by state functions not invoked directly. .UNINDENT .UNINDENT +.sp +CLI Example: .INDENT 7.0 -.TP -.B CLI Example: +.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) @@ -305936,29 +308282,6 @@ salt \(aq*\(aq vsphere.get_vsan_enabled my.vcenter.location root bad\-password .UNINDENT .INDENT 0.0 .TP -.B salt.modules.vsphere.gets_service_instance_via_proxy(fn) -Decorator that connects to a target system (vCenter or ESXi host) using the -proxy details and passes the connection (vim.ServiceInstance) to -the decorated function. -.sp -Supported proxies: esxi, esxcluster, esxdatacenter. -Notes -.sp -1. The decorated function must have a \fBservice_instance\fP parameter -or a \fB**kwarg\fP type argument (name of argument is not important); -2. If the \fBservice_instance\fP parameter is already defined, the value -is passed through to the decorated function; -3. If the \fBservice_instance\fP parameter in not defined, the -connection is created using the proxy details and the service instance -is returned. -.INDENT 7.0 -.TP -.B CLI Example: -None, this is a decorator -.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 @@ -307906,16 +310229,6 @@ salt \(aq*\(aq vsphere.set_syslog_config my.vcenter.location root bad\-password .UNINDENT .INDENT 0.0 .TP -.B salt.modules.vsphere.supports_proxies(*proxy_types) -Decorator to specify which proxy types are supported by a function -.INDENT 7.0 -.TP -.B proxy_types: -Arbitrary list of strings with the supported types of proxies -.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 @@ -308772,7 +311085,7 @@ salt \(aq*\(aq webutil.verify /etc/httpd/htpasswd larry maybepassword opts=ns .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_auditpol module +.SS salt.modules.win_auditpol .sp A salt module for modifying the audit policies on the machine .sp @@ -309043,7 +311356,7 @@ salt \(aq*\(aq autoruns.list .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_certutil module +.SS salt.modules.win_certutil .sp This module allows you to install certificates into the windows certificate manager. @@ -309474,7 +311787,7 @@ salt \(aq*\(aq disk.usage .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_dism module +.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 @@ -313474,7 +315787,7 @@ salt \(aq*\(aq group.members foo \(aquser1,user2,user3\(aq .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_iis module +.SS salt.modules.win_iis .sp Microsoft IIS site management via WebAdministration powershell module .INDENT 0.0 @@ -315124,7 +317437,7 @@ salt \-G \(aqos_family:Windows\(aq ip.set_static_ip \(aqLocal Area Connection\(a .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_lgpo module +.SS salt.modules.win_lgpo .sp Manage Local Policy on Windows .sp @@ -315658,7 +317971,7 @@ salt \(aq*\(aq lgpo.set_user_policy "Control Panel\eDisplay\eDisable the Display .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_license module +.SS salt.modules.win_license .sp This module allows you to manage windows licensing via slmgr.vbs .INDENT 0.0 @@ -317424,7 +319737,7 @@ salt \(aq*\(aq pkg.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_pki module +.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 @@ -318188,7 +320501,7 @@ salt \(aq*\(aq powercfg.set_standby_timeout 30 power=dc .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_psget module +.SS salt.modules.win_psget .sp Module for managing PowerShell through PowerShellGet (PSGet) .INDENT 0.0 @@ -319709,7 +322022,7 @@ salt \(aq*\(aq shadow.unlock_account .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_smtp_server module +.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. @@ -320068,7 +322381,7 @@ salt \(aq*\(aq win_smtp_server.set_server_setting settings="{\(aqMaxRecipients\( .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_snmp module +.SS salt.modules.win_snmp .sp Module for managing SNMP service settings on Windows servers. The Windows feature \(aqSNMP\-Service\(aq must be installed. @@ -322315,7 +324628,7 @@ salt \(aqminion\-id\(aq system.unjoin_domain username=\(aqunjoinuser\(aq \e .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.win_task module +.SS salt.modules.win_task .sp Windows Task Scheduler Module \&.. versionadded:: 2016.3.0 @@ -326082,7 +328395,7 @@ salt\-call winrepo.update_git_repos .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.wordpress module +.SS salt.modules.wordpress .sp This module is used to manage Wordpress installations .INDENT 0.0 @@ -327723,7 +330036,7 @@ salt \(aq*\(aq virt.vm_state .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.xbpspkg module +.SS salt.modules.xbpspkg .sp Package support for XBPS package manager (used by VoidLinux) .sp @@ -328544,6 +330857,9 @@ 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. + .INDENT 0.0 .TP .B class salt.modules.yumpkg.AvailablePackages(*args, **kwargs) @@ -330314,7 +332630,7 @@ salt \(aq*\(aq pkg.version_cmp \(aq0.2\-001\(aq \(aq0.2.0.1\-002\(aq .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.zabbix module +.SS salt.modules.zabbix .sp Support for Zabbix .INDENT 0.0 @@ -332658,7 +334974,7 @@ Module for running ZFS command .INDENT 0.0 .TP .B codeauthor -Nitin Madhok <\fI\%nmadhok@clemson.edu\fP>, Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> +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> @@ -335217,7 +337533,7 @@ Module for running ZFS zpool command .INDENT 0.0 .TP .B codeauthor -Nitin Madhok <\fI\%nmadhok@clemson.edu\fP>, Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> +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> @@ -338010,32 +340326,6 @@ _ .IP \(bu 2 \fI\%Using a WSGI\-compliant web server\fP .UNINDENT -.IP \(bu 2 -\fI\%REST URI Reference\fP -.INDENT 2.0 -.IP \(bu 2 -\fI\%/\fP -.IP \(bu 2 -\fI\%/login\fP -.IP \(bu 2 -\fI\%/logout\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 -.IP \(bu 2 -\fI\%/keys\fP -.IP \(bu 2 -\fI\%/ws\fP -.IP \(bu 2 -\fI\%/stats\fP -.UNINDENT .UNINDENT .sp A script to start the CherryPy WSGI server @@ -338162,13 +340452,13 @@ The socket interface for the HTTP server to listen on. 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 +.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 +.B log_error_file Path to a file to write HTTP error logs. .sp New in version 2016.11.0. @@ -342863,7 +345153,7 @@ This outputter is used to display Orchestrate Runner stages, and should not be c .B salt.output.overstatestage.output(data, **kwargs) Format the data for printing stage information from the overstate system .UNINDENT -.SS salt.output.pony module +.SS salt.output.pony .SS Display Pony output data structure .INDENT 0.0 .TP @@ -343763,7 +346053,7 @@ confidant\-common, confidant\-client .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 module +.SS salt.pillar.consul_pillar .sp Use Consul K/V as a Pillar source with values parsed as YAML .INDENT 0.0 @@ -344004,7 +346294,7 @@ Return a client object for accessing consul Perform data formatting to be used as pillar data and merge it with the current pillar data .UNINDENT -.SS salt.pillar.csvpillar module +.SS salt.pillar.csvpillar .sp Store key/value pairs in a CSV file .sp @@ -344133,7 +346423,7 @@ column names they may be specified here instead. .UNINDENT .UNINDENT .UNINDENT -.SS salt.pillar.digicert module +.SS salt.pillar.digicert .sp Digicert Pillar Certificates .sp @@ -345397,7 +347687,7 @@ ext_pillar: .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 module +.SS salt.pillar.gpg .sp Decrypt pillar data through the builtin GPG renderer .sp @@ -345482,7 +347772,7 @@ Use hiera data as a Pillar source .B salt.pillar.hiera.ext_pillar(minion_id, pillar, conf) Execute hiera and return the data .UNINDENT -.SS salt.pillar.http_json module +.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 @@ -345556,7 +347846,7 @@ A dictionary of the pillar data to add. \fI\%dict\fP .UNINDENT .UNINDENT -.SS salt.pillar.http_yaml module +.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 @@ -345650,7 +347940,7 @@ Read in the generated libvirt keys 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 module +.SS salt.pillar.makostack .sp Simple and flexible YAML ext_pillar which can read pillar from within pillar. .sp @@ -346716,7 +349006,7 @@ Whether should retrieve the prefixes of the site the device belongs to. .B salt.pillar.netbox.ext_pillar(minion_id, pillar, *args, **kwargs) Query NetBox API for minion data .UNINDENT -.SS salt.pillar.neutron module +.SS salt.pillar.neutron .sp Use Openstack Neutron data as a Pillar source. Will list all networks listed inside of Neutron, to all minions. @@ -347338,7 +349628,7 @@ search_order: .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 module +.SS salt.pillar.postgres .sp Retrieve Pillar data by doing a postgres query .sp @@ -347758,7 +350048,7 @@ For additional configuration instructions, see the \fBsaltclass\fP module .B salt.pillar.saltclass.ext_pillar(minion_id, pillar, *args, **kwargs) Compile pillar data .UNINDENT -.SS salt.pillar.sql_base module +.SS salt.pillar.sql_base .sp Retrieve Pillar data by doing a SQL query .sp @@ -348053,7 +350343,7 @@ merging them into a dict form. .B with_lists = None .UNINDENT .UNINDENT -.SS salt.pillar.sqlcipher module +.SS salt.pillar.sqlcipher .sp Retrieve Pillar data by running a SQLCipher query .sp @@ -348145,7 +350435,7 @@ This class receives and processes the database rows from SQLCipher. .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 module +.SS salt.pillar.sqlite3 .sp Retrieve Pillar data by doing a SQLite3 query .sp @@ -349122,7 +351412,7 @@ varstack on how this file is evaluated. .B salt.pillar.varstack_pillar.ext_pillar(minion_id, pillar, conf) Parse varstack data and return the result .UNINDENT -.SS salt.pillar.vault module +.SS salt.pillar.vault .sp Vault Pillar Module .INDENT 0.0 @@ -349302,7 +351592,7 @@ local: .B salt.pillar.vault.ext_pillar(minion_id, pillar, conf, nesting_key=None) Get pillar data from Vault for the configuration \fBconf\fP\&. .UNINDENT -.SS salt.pillar.venafi module +.SS salt.pillar.venafi .sp Venafi Pillar Certificates .sp @@ -349335,7 +351625,7 @@ Accept a key from a hypervisor if the virt runner has already submitted an autho .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 module +.SS salt.pillar.vmware_pillar .sp Pillar data from vCenter or an ESXi host .sp @@ -349783,7 +352073,7 @@ Connection open successfully? .B salt.proxy.arista_pyeapi.shutdown(opts) Closes connection with the device. .UNINDENT -.SS salt.proxy.chronos module +.SS salt.proxy.chronos .SS Chronos .sp Proxy minion for managing a Chronos cluster. @@ -349826,7 +352116,7 @@ Is the chronos api responding? .B salt.proxy.chronos.shutdown(opts) For this proxy shutdown is a no\-op .UNINDENT -.SS salt.proxy.cimc module +.SS salt.proxy.cimc .SS Proxy Minion interface module for managing Cisco Integrated Management Controller devices .sp New in version 2018.3.0. @@ -350320,7 +352610,7 @@ a list of element names in order, comma separated Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT -.SS salt.proxy.docker module +.SS salt.proxy.docker .sp Docker Proxy Minion .INDENT 0.0 @@ -350388,7 +352678,7 @@ List of module executors to use for this Proxy Minion .B salt.proxy.docker.shutdown(opts) Nothing needs to be done to shutdown .UNINDENT -.SS salt.proxy.dummy module +.SS salt.proxy.dummy .sp This is the a dummy proxy\-minion designed for testing the proxy minion subsystem. .INDENT 0.0 @@ -350487,7 +352777,7 @@ Test function so we have something to call from a state .B salt.proxy.dummy.uptodate() Call the REST endpoint to see if the packages on the "server" are up to date. .UNINDENT -.SS salt.proxy.esxcluster module +.SS salt.proxy.esxcluster .sp Proxy Minion interface module for managing VMWare ESXi clusters. .SS Dependencies @@ -350694,7 +352984,7 @@ salt esx\-cluster test.ping Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT -.SS salt.proxy.esxdatacenter module +.SS salt.proxy.esxdatacenter .sp Proxy Minion interface module for managing VMWare ESXi clusters. .SS Dependencies @@ -351285,7 +353575,7 @@ salt esxi\-host test.ping Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT -.SS salt.proxy.esxvm module +.SS salt.proxy.esxvm .sp Proxy Minion interface module for managing VMWare ESXi virtual machines. .SS Dependencies @@ -351845,6 +354135,17 @@ salt\-proxy \-\-proxyid=vmx .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 @@ -351857,6 +354158,10 @@ New in version 2018.3.0. .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 @@ -351881,11 +354186,19 @@ 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 module +.SS salt.proxy.marathon .SS Marathon .sp Proxy minion for managing a Marathon cluster. @@ -352542,7 +354855,7 @@ Connection open successfully? .B salt.proxy.netmiko_px.shutdown(opts) Closes connection with the device. .UNINDENT -.SS salt.proxy.nxos module +.SS salt.proxy.nxos .sp Proxy Minion for Cisco NX\-OS Switches .sp @@ -352797,7 +355110,7 @@ send commands to an nxos device using the proxy minion. Not supported. Only used as a place holder to satisfy shutdown function requirement. .UNINDENT -.SS salt.proxy.nxos_api module +.SS salt.proxy.nxos_api .sp Proxy Minion to manage Cisco Nexus Switches (NX\-OS) over the NX\-API .sp @@ -352961,7 +355274,7 @@ Executes an RPC request over the NX\-API. .B salt.proxy.nxos_api.shutdown(opts) Closes connection with the device. .UNINDENT -.SS salt.proxy.panos module +.SS salt.proxy.panos .SS Proxy Minion interface module for managing Palo Alto firewall devices .sp New in version 2018.3.0. @@ -353197,7 +355510,7 @@ Returns true if the device is reachable, else false. Shutdown the connection to the proxy device. For this proxy, shutdown is a no\-op. .UNINDENT -.SS salt.proxy.philips_hue module +.SS salt.proxy.philips_hue .sp Philips HUE lamps module for proxy. .sp @@ -353813,7 +356126,7 @@ New in version 2015.8.2. .B salt.proxy.ssh_sample.shutdown(opts) Disconnect .UNINDENT -.SS salt.proxy.vcenter module +.SS salt.proxy.vcenter .sp Proxy Minion interface module for managing VMWare vCenters. .INDENT 0.0 @@ -354096,7 +356409,7 @@ New in version 2014.7.0. T} _ .TE -.SS salt.queues.pgjsonb_queue module +.SS salt.queues.pgjsonb_queue .sp New in version 2016.3.0. @@ -354191,7 +356504,7 @@ Return a list of Salt Queues on the Salt Master .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 module +.SS salt.queues.sqlite_queue .sp New in version 2014.7.0. @@ -354616,7 +356929,7 @@ Read in the roster from a flat file using the renderer system Return the targets from the flat yaml file, checks opts for location but defaults to /etc/salt/roster .UNINDENT -.SS salt.roster.range module +.SS salt.roster.range .sp This roster resolves targets from a range server. .INDENT 0.0 @@ -355083,7 +357396,7 @@ Runner to interact with Novell ASAM Fan\-Out Driver .INDENT 0.0 .TP .B codeauthor -Nitin Madhok <\fI\%nmadhok@clemson.edu\fP> +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 @@ -355949,7 +358262,7 @@ Runner to interact with DNS server and create/delete/update DNS records .INDENT 0.0 .TP .B codeauthor -Nitin Madhok <\fI\%nmadhok@clemson.edu\fP> +Nitin Madhok <\fI\%nmadhok@g.clemson.edu\fP> .UNINDENT .INDENT 0.0 .TP @@ -359977,6 +362290,28 @@ salt\-run pagerduty.list_maintenance_windows my\-pagerduty\-account 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 @@ -360054,6 +362389,28 @@ print(pillar) .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. @@ -361765,7 +364122,7 @@ Runner to interact with Spacewalk using Spacewalk API .INDENT 0.0 .TP .B codeauthor -Nitin Madhok <\fI\%nmadhok@clemson.edu\fP>, Joachim Werner <\fI\%joe@suse.com\fP>, Benedikt Werner <\fI\%1benediktwerner@gmail.com\fP> +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> @@ -362975,7 +365332,7 @@ Pull sdb values from a YAML file T} _ .TE -.SS salt.sdb.cache module +.SS salt.sdb.cache .sp cache Module .INDENT 0.0 @@ -363128,7 +365485,7 @@ 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 module +.SS salt.sdb.consul .sp Consul sdb Module .INDENT 0.0 @@ -363249,7 +365606,7 @@ Get a value from couchdb by id .B salt.sdb.couchdb.set_(key, value, profile=None) Set a key/value pair in couchdb .UNINDENT -.SS salt.sdb.env module +.SS salt.sdb.env .sp Environment sdb Module .INDENT 0.0 @@ -363548,7 +365905,7 @@ Get a value from memcached .B salt.sdb.memcached.set_(key, value, profile=None) Set a key/value pair in memcached .UNINDENT -.SS salt.sdb.redis_sdb module +.SS salt.sdb.redis_sdb .SS Redis SDB module .INDENT 0.0 .INDENT 3.5 @@ -363595,7 +365952,7 @@ Get a value from the Redis SDB. .B salt.sdb.redis_sdb.set_(key, value, profile=None) Set a value into the Redis SDB. .UNINDENT -.SS salt.sdb.rest module +.SS salt.sdb.rest .sp Generic REST API SDB Module .INDENT 0.0 @@ -363783,7 +366140,7 @@ Get a value from sqlite3 .B salt.sdb.sqlite3.set_(key, value, profile=None) Set a key/value pair in sqlite3 .UNINDENT -.SS salt.sdb.tism module +.SS salt.sdb.tism .sp tISM \- the Immutable Secrets Manager SDB Module .INDENT 0.0 @@ -363836,7 +366193,7 @@ tism: .B salt.sdb.tism.get(key, service=None, profile=None) Get a decrypted secret from the tISMd API .UNINDENT -.SS salt.sdb.vault module +.SS salt.sdb.vault .sp Vault SDB Module .INDENT 0.0 @@ -363912,7 +366269,7 @@ Get a value from the vault service .B salt.sdb.vault.set_(key, value, profile=None) Set a key/value pair in the vault service .UNINDENT -.SS salt.sdb.yaml module +.SS salt.sdb.yaml .sp Pull sdb values from a YAML file .INDENT 0.0 @@ -364038,7 +366395,7 @@ salt.serializers.yamlex T} _ .TE -.SS salt.serializers.configparser module +.SS salt.serializers.configparser .SS salt.serializers.configparser .sp New in version 2016.3.0. @@ -364191,7 +366548,7 @@ Serialize Python data to plist. To create a binary plist pass bytes of serialized plist. .UNINDENT .UNINDENT -.SS salt.serializers.python module +.SS salt.serializers.python .SS salt.serializers.python .sp New in version 2016.3.0. @@ -366597,7 +368954,7 @@ States for managing zpools T} _ .TE -.SS salt.states.acme module +.SS salt.states.acme .SS ACME / Let\(aqs Encrypt certificate management state .sp See also the module documentation @@ -367053,7 +369410,7 @@ it still needs keyword \fBthis\fP with empty string (or "" if nicer output is r .TP .B salt.states.apache.configfile(name, config) .UNINDENT -.SS salt.states.apache_conf module +.SS salt.states.apache_conf .sp Manage Apache Confs .sp @@ -367147,7 +369504,7 @@ New in version 2016.3.0. Name of the Apache module .UNINDENT .UNINDENT -.SS salt.states.apache_site module +.SS salt.states.apache_site .sp Manage Apache Sites .sp @@ -368695,7 +371052,7 @@ Ensure availability set exists: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.azurearm_dns module +.SS salt.states.azurearm_dns .sp Azure (ARM) DNS State Module .sp @@ -372229,7 +374586,7 @@ Set Read\-Write .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.boto3_elasticache module +.SS salt.states.boto3_elasticache .SS Manage Elasticache with boto3 .sp New in version 2017.7.0. @@ -373096,7 +375453,7 @@ 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 module +.SS salt.states.boto3_elasticsearch .SS Manage Elasticsearch Service .sp New in version Natrium. @@ -373526,7 +375883,7 @@ Upgrade Elasticsearch Domain: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.boto3_route53 module +.SS salt.states.boto3_route53 .sp Manage Route53 records with Boto 3 .sp @@ -373914,7 +376271,7 @@ Access key to be used. Dict, or pillar key pointing to a dict, containing AWS region/key/keyid. .UNINDENT .UNINDENT -.SS salt.states.boto3_sns module +.SS salt.states.boto3_sns .SS Manage SNS Topics .sp Create and destroy SNS topics. Be aware that this interacts with Amazon\(aqs @@ -374089,7 +376446,7 @@ 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 module +.SS salt.states.boto_apigateway .SS Manage Apigateway Rest APIs .sp New in version 2016.11.0. @@ -375335,7 +377692,7 @@ Manage my_distribution CloudFront distribution: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.boto_cloudtrail module +.SS salt.states.boto_cloudtrail .SS Manage CloudTrail Objects .sp New in version 2016.3.0. @@ -375624,7 +377981,7 @@ 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 module +.SS salt.states.boto_cloudwatch_event .SS Manage CloudTrail Objects .sp New in version 2016.11.0. @@ -375765,7 +378122,7 @@ 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 module +.SS salt.states.boto_cognitoidentity .SS Manage CognitoIdentity Functions .sp New in version 2016.11.0. @@ -375912,7 +378269,7 @@ 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 module +.SS salt.states.boto_datapipeline .sp Manage Data Pipelines .sp @@ -377337,7 +379694,7 @@ 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 module +.SS salt.states.boto_elasticsearch_domain .SS Manage Elasticsearch Domains .sp New in version 2016.11.0. @@ -378011,7 +380368,7 @@ add\-instances: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.boto_elbv2 module +.SS salt.states.boto_elbv2 .sp Manage AWS Application Load Balancer .sp @@ -379092,7 +381449,7 @@ New in version 2015.8.0. .UNINDENT .UNINDENT -.SS salt.states.boto_iot module +.SS salt.states.boto_iot .SS Manage IoT Objects .sp New in version 2016.3.0. @@ -379428,7 +381785,7 @@ 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 module +.SS salt.states.boto_kinesis .SS Manage Kinesis Streams .sp New in version 2017.7.0. @@ -379689,7 +382046,7 @@ 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 module +.SS salt.states.boto_lambda .SS Manage Lambda Functions .sp New in version 2016.3.0. @@ -381005,7 +383362,7 @@ If using split_dns, specify if this is the private zone. .TP .B salt.states.boto_route53.rr_present(*args, **kwargs) .UNINDENT -.SS salt.states.boto_s3 module +.SS salt.states.boto_s3 .SS Manage S3 Resources .sp New in version 2018.3.0. @@ -381122,7 +383479,7 @@ 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 module +.SS salt.states.boto_s3_bucket .SS Manage S3 Buckets .sp New in version 2016.3.0. @@ -383074,7 +385431,7 @@ state function. .B salt.states.cabal.removed(name, user=None, env=None) Verify that given package is not installed. .UNINDENT -.SS salt.states.ceph module +.SS salt.states.ceph .sp Manage ceph with salt. .sp @@ -383234,7 +385591,7 @@ default is indefinitely. User to set privilege to .UNINDENT .UNINDENT -.SS salt.states.chocolatey module +.SS salt.states.chocolatey .sp Manage Chocolatey package installs \&.. versionadded:: 2016.3.0 @@ -383446,7 +385803,7 @@ upgrade_some_package: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.chronos_job module +.SS salt.states.chronos_job .sp Configure Chronos jobs via a salt proxy. .INDENT 0.0 @@ -384343,6 +386700,15 @@ mycommand: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.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 .TP .B prepend_path $PATH segment to prepend (trailing \(aq:\(aq not necessary) to $PATH. This is @@ -384586,6 +386952,15 @@ mycommand: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.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 .TP .B saltenv \fBbase\fP @@ -384766,6 +387141,15 @@ mycommand: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.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 .TP .B umask The umask (in octal) to use when running the command. @@ -384924,6 +387308,15 @@ mycommand: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.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 .TP .B umask The umask (in octal) to use when running the command. @@ -385548,7 +387941,7 @@ New in version 2016.3.0. .UNINDENT .UNINDENT -.SS salt.states.cryptdev module +.SS salt.states.cryptdev .SS Opening of Encrypted Devices .sp Ensure that an encrypted device is mapped with the \fImapped\fP function: @@ -385572,7 +387965,7 @@ swap: mappedbyuuid: crypted.mapped: - \- device: UUID=066e0200\-2867\-4ebe\-b9e6\-f3002.26ca2314 + \- device: UUID=066e0200\-2867\-4ebe\-b9e6\-f30026ca2314 \- keyfile: /etc/keyfile.key \- config: /etc/alternate\-crypttab .ft P @@ -385593,7 +387986,7 @@ 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\-f3002.26ca2314\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 @@ -385643,7 +388036,7 @@ Set if the map should be removed from the crypttab. Default is \fBTrue\fP Set if the device should be unmapped immediately. Default is \fBFalse\fP\&. .UNINDENT .UNINDENT -.SS salt.states.csf module +.SS salt.states.csf .SS CSF Ip tables management .INDENT 0.0 .TP @@ -390494,7 +392887,7 @@ The password used to authenticate The permissions that should be assigned to a user .UNINDENT .UNINDENT -.SS salt.states.dvs module +.SS salt.states.dvs .sp Manage VMware distributed virtual switches (DVSs) and their distributed virtual portgroups (DVportgroups). @@ -391201,7 +393594,7 @@ profile: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.esxcluster module +.SS salt.states.esxcluster .sp Manage VMware ESXi Clusters. .SS Dependencies @@ -391308,7 +393701,7 @@ 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 module +.SS salt.states.esxdatacenter .sp Salt states to create and manage VMware vSphere datacenters (datacenters). .INDENT 0.0 @@ -391968,7 +394361,7 @@ configure\-host\-vsan: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.esxvm module +.SS salt.states.esxvm .sp Salt state to create, update VMware ESXi Virtual Machines. .SS Dependencies @@ -392516,7 +394909,7 @@ my_etd_config: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.ethtool module +.SS salt.states.ethtool .sp Configuration of network device .sp @@ -392697,7 +395090,7 @@ mycompany/mystaterun/status/update: .UNINDENT .INDENT 0.0 .TP -.B salt.states.event.wait(name, sfun=None) +.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. @@ -395598,7 +397991,7 @@ create_config_file: 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.2. +New in version 3002. .UNINDENT .UNINDENT @@ -396647,7 +399040,7 @@ New in version 2015.8.0. Write the data as this format. See the list of all\-salt.serializers for supported output formats. .sp -Changed in version 3002.2: \fBserializer\fP argument added as an alternative to \fBformatter\fP\&. +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 @@ -397126,7 +399519,7 @@ Usage: New in version 0.9.5. .UNINDENT -.SS salt.states.firewall module +.SS salt.states.firewall .sp State to check firewall configurations .sp @@ -398423,7 +400816,7 @@ New in version 2018.3.1. .UNINDENT .UNINDENT -.SS salt.states.github module +.SS salt.states.github .sp Github User State Module .sp @@ -398777,7 +401170,7 @@ Boolean to control if image is enabled An arbitrary description of the image .UNINDENT .UNINDENT -.SS salt.states.glassfish module +.SS salt.states.glassfish .sp Manage Glassfish/Payara server \&.. versionadded:: Carbon @@ -399225,7 +401618,7 @@ desktop_lockdown: sets values in the org.gnome.desktop.lockdown schema .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 module +.SS salt.states.gpg .SS Management of the GPG keychains .sp New in version 2016.3.0. @@ -399499,7 +401892,7 @@ A pillar key or dict that contains a list of hosts and an elasticsearch index to use. .UNINDENT .UNINDENT -.SS salt.states.grafana4_dashboard module +.SS salt.states.grafana4_dashboard .sp Manage Grafana v4.0 Dashboards .sp @@ -399620,7 +402013,7 @@ Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT -.SS salt.states.grafana4_datasource module +.SS salt.states.grafana4_datasource .sp Manage Grafana v4.0 data sources .sp @@ -399761,7 +402154,7 @@ Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT -.SS salt.states.grafana4_org module +.SS salt.states.grafana4_org .sp Manage Grafana v4.0 orgs .sp @@ -399896,7 +402289,7 @@ Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT -.SS salt.states.grafana4_user module +.SS salt.states.grafana4_user .sp Manage Grafana v4.0 users .sp @@ -399999,7 +402392,7 @@ Configuration profile used to connect to the Grafana instance. Default is \(aqgrafana\(aq. .UNINDENT .UNINDENT -.SS salt.states.grafana_dashboard module +.SS salt.states.grafana_dashboard .sp Manage Grafana v2.0 Dashboards .sp @@ -400087,7 +402480,7 @@ A dict that defines a dashboard that should be managed. A pillar key or dict that contains grafana information .UNINDENT .UNINDENT -.SS salt.states.grafana_datasource module +.SS salt.states.grafana_datasource .sp Manage Grafana v2.0 data sources .sp @@ -400597,7 +402990,7 @@ Administrators: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.heat module +.SS salt.states.heat .SS Management of Heat .sp New in version 2017.7.0. @@ -400712,7 +403105,7 @@ New in version 2017.7.5,2018.3.1: The spelling mistake in parameter \fIenviromen The \fIenviroment\fP spelling mistake has been removed in Salt 3000. .UNINDENT -.SS salt.states.helm module +.SS salt.states.helm .INDENT 0.0 .TP .B salt.states.helm.release_absent(name, namespace=None, flags=None, kvflags=None) @@ -400958,7 +403351,7 @@ New in version 2017.7.0. .UNINDENT .UNINDENT -.SS salt.states.highstate_doc module +.SS salt.states.highstate_doc .sp To be used with processors in module \fIhighstate_doc\fP\&. .INDENT 0.0 @@ -401280,7 +403673,7 @@ All other arguments are passed to the http.query state. .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.icinga2 module +.SS salt.states.icinga2 .SS Icinga2 state .sp New in version 2017.7.0. @@ -401400,7 +403793,7 @@ Icinga2 master node for which this certificate will be saved .sp This state provides access to idem states .sp -New in version 3002.2. +New in version 3002. .INDENT 0.0 .TP @@ -401642,7 +404035,7 @@ The mask of events that should be monitored for The cmd that should be executed .UNINDENT .UNINDENT -.SS salt.states.influxdb08_database module +.SS salt.states.influxdb08_database .SS Management of Influxdb 0.8 databases .sp (compatible with InfluxDB version 0.5\-0.8) @@ -401693,7 +404086,7 @@ The host to connect to The port to connect to .UNINDENT .UNINDENT -.SS salt.states.influxdb08_user module +.SS salt.states.influxdb08_user .SS Management of InfluxDB 0.8 users .sp (compatible with InfluxDB version 0.5\-0.8) @@ -401753,7 +404146,7 @@ The host to connect to The port to connect to .UNINDENT .UNINDENT -.SS salt.states.influxdb_continuous_query module +.SS salt.states.influxdb_continuous_query .SS Management of Influxdb continuous queries .sp New in version 2017.7.0. @@ -401821,7 +404214,7 @@ Ensure that given database is present. Name of the database to create. .UNINDENT .UNINDENT -.SS salt.states.influxdb_retention_policy module +.SS salt.states.influxdb_retention_policy .SS Management of Influxdb retention policies .sp New in version 2017.7.0. @@ -403431,7 +405824,7 @@ configuration_reloaded: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.jenkins module +.SS salt.states.jenkins .SS Management of Jenkins .sp New in version 2016.3.0. @@ -403459,7 +405852,7 @@ The unique name for the Jenkins job The Salt URL for the file to use for configuring the job .UNINDENT .UNINDENT -.SS salt.states.junos module +.SS salt.states.junos .SS State modules to interact with Junos devices. .INDENT 0.0 .TP @@ -403509,7 +405902,7 @@ get software version of device: \fBRequired\fP \-\- .INDENT 2.0 .IP \(bu 2 name: -The command that need to be executed on Junos CLI. +The command that need to be executed on Junos CLI. (default = None) .UNINDENT .IP \(bu 2 @@ -403656,7 +406049,7 @@ Copies the file from the local device to the junos device. .B Parameters \fBRequired\fP \-\- .INDENT 7.0 .IP \(bu 2 -src: +name: The sorce path where the file is kept. .IP \(bu 2 dest: @@ -403838,7 +406231,7 @@ salt://images/junos_image.tgz: .IP \(bu 2 \fBRequired\fP \-\- .INDENT 2.0 .IP \(bu 2 -path: +name: Path where the image file is present on the pro xy minion. .UNINDENT @@ -403984,7 +406377,7 @@ lock the config: .UNINDENT .INDENT 0.0 .TP -.B salt.states.junos.rollback(name, id, **kwargs) +.B salt.states.junos.rollback(name, d_id, **kwargs) Rollbacks the committed changes. .INDENT 7.0 .INDENT 3.5 @@ -404004,7 +406397,11 @@ rollback the changes: \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 @@ -404122,7 +406519,7 @@ device_name: .IP \(bu 2 \fBRequired\fP \-\- .INDENT 2.0 .IP \(bu 2 -hostname: The name to be set. (default = None) +name: The name to be set. (default = None) .UNINDENT .IP \(bu 2 @@ -404223,7 +406620,7 @@ reset my device: .sp name: can be anything .UNINDENT -.SS salt.states.kapacitor module +.SS salt.states.kapacitor .sp Kapacitor state module. .INDENT 0.0 @@ -406224,7 +408621,7 @@ mode. .UNINDENT .UNINDENT -.SS salt.states.libcloud_dns module +.SS salt.states.libcloud_dns .sp Manage DNS records and zones using libcloud .INDENT 0.0 @@ -406379,7 +408776,7 @@ Ensures a record is present. .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.libcloud_loadbalancer module +.SS salt.states.libcloud_loadbalancer .SS Apache Libcloud Load Balancer State .sp Manage load balancers using libcloud @@ -406529,7 +408926,7 @@ Ensure a load balancer member is present .TP .B salt.states.libcloud_loadbalancer.state_result(result, message, name, changes=None) .UNINDENT -.SS salt.states.libcloud_storage module +.SS salt.states.libcloud_storage .SS Apache Libcloud Storage State .sp Manage cloud storage using libcloud @@ -406923,7 +409320,7 @@ Set the locale for the system The name of the locale to use .UNINDENT .UNINDENT -.SS salt.states.logadm module +.SS salt.states.logadm .sp Management of logs using Solaris logadm. .INDENT 0.0 @@ -406991,7 +409388,7 @@ boolean|string|int optional additional flags and parameters .UNINDENT .UNINDENT -.SS salt.states.logrotate module +.SS salt.states.logrotate .sp Module for managing logrotate. .sp @@ -407048,7 +409445,7 @@ logrotate\-wtmp\-rotate: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.loop module +.SS salt.states.loop .sp Loop state .sp @@ -407271,7 +409668,7 @@ New in version 2018.3.0. Assume yes to all prompts .UNINDENT .sp -New in version 3002.2.0. +New in version 3002.0. .INDENT 7.0 .TP @@ -407847,7 +410244,7 @@ web01: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.lxd module +.SS salt.states.lxd .sp Manage LXD profiles. .sp @@ -407976,7 +410373,7 @@ 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 module +.SS salt.states.lxd_container .sp Manage LXD containers. .sp @@ -408448,7 +410845,7 @@ 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 module +.SS salt.states.lxd_image .sp Manage LXD images. .sp @@ -408636,7 +411033,7 @@ 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 module +.SS salt.states.lxd_profile .sp Manage LXD profiles. .sp @@ -408763,7 +411160,7 @@ normally uses self\-signed certificates. 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 module +.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 @@ -408793,7 +411190,7 @@ The bundle ID or path to command Should assistive access be enabled on this application? .UNINDENT .UNINDENT -.SS salt.states.mac_keychain module +.SS salt.states.mac_keychain .SS Installing of certificates to the keychain .sp Install certificats to the macOS keychain @@ -408877,7 +411274,7 @@ If your keychain is likely to be locked pass the password and it will be unlocke before running the import .UNINDENT .UNINDENT -.SS salt.states.mac_xattr module +.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 @@ -409087,7 +411484,7 @@ Enforce that the value of the variable does not contain the provided value. .UNINDENT .UNINDENT -.SS salt.states.marathon_app module +.SS salt.states.marathon_app .sp Configure Marathon apps via a salt proxy. .INDENT 0.0 @@ -410204,7 +412601,7 @@ Mount any type of mountable filesystem with the mounted function: /srv/bigdata: mount.mounted: - \- device: UUID=066e0200\-2867\-4ebe\-b9e6\-f3002.26ca2314 + \- device: UUID=066e0200\-2867\-4ebe\-b9e6\-f30026ca2314 \- fstype: xfs \- opts: nobootwait,noatime,nodiratime,nobarrier,logbufs=8 \- dump: 0 @@ -410342,7 +412739,7 @@ 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\-f3002.26ca2314\fP or \fBLABEL=DATA\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 @@ -410535,7 +412932,7 @@ 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 module +.SS salt.states.mssql_database .SS Management of Microsoft SQLServer Databases .sp The mssql_database module is used to create @@ -410577,7 +412974,7 @@ Defaults to NONE Can be a list of strings, a dictionary, or a list of dictionaries .UNINDENT .UNINDENT -.SS salt.states.mssql_login module +.SS salt.states.mssql_login .SS Management of Microsoft SQLServer Logins .sp The mssql_login module is used to create @@ -410631,7 +413028,7 @@ Add this login to all the server roles in the list Can be a list of strings, a dictionary, or a list of dictionaries .UNINDENT .UNINDENT -.SS salt.states.mssql_role module +.SS salt.states.mssql_role .SS Management of Microsoft SQLServer Databases .sp The mssql_role module is used to create @@ -410673,7 +413070,7 @@ Adds owner using AUTHORIZATION option Can only be a list of strings .UNINDENT .UNINDENT -.SS salt.states.mssql_user module +.SS salt.states.mssql_user .SS Management of Microsoft SQLServer Users .sp The mssql_user module is used to create @@ -410727,7 +413124,7 @@ Add this user to all the roles in the list Can be a list of strings, a dictionary, or a list of dictionaries .UNINDENT .UNINDENT -.SS salt.states.msteams module +.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. @@ -411039,7 +413436,7 @@ query_id: .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, **connection_args) +.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 @@ -411070,11 +413467,15 @@ The file or grain will be overwritten if it already exists (default) .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, **connection_args) +.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. @@ -411111,6 +413512,10 @@ The saltenv to pull the query_file from .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 @@ -414021,7 +416426,7 @@ argument. .UNINDENT .SS Network Teaming (RHEL/CentOS 7 and later) .sp -New in version 3002.2. +New in version 3002. .INDENT 0.0 .IP \(bu 2 @@ -414541,7 +416946,7 @@ IPv6 address mode. Valid values are: ‘dhcpv6\-stateful’, ‘dhcpv6\-stateless’, or ‘slaac’. .UNINDENT .UNINDENT -.SS salt.states.nexus module +.SS salt.states.nexus .sp This state downloads artifacts from Nexus 3.x. .sp @@ -414961,7 +417366,7 @@ Networking family, either ipv4 or ipv6 New in version 2014.7.0. .sp -Changed in version 3002.2. +Changed in version 3002. .sp Verify a chain exists in a table. @@ -415005,7 +417410,7 @@ specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with New in version 2014.7.0. .sp -Changed in version 3002.2. +Changed in version 3002. .sp Flush current nftables state @@ -415018,7 +417423,7 @@ Networking family, either ipv4 or ipv6 If set to True, attempts to flush a non\-existent table will not result in a failed state. .sp -New in version 3002.2. +New in version 3002. .UNINDENT .UNINDENT @@ -415047,7 +417452,7 @@ specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with .INDENT 0.0 .TP .B salt.states.nftables.set_policy(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq, **kwargs) -New in version 3002.2. +New in version 3002. .sp Sets the default policy for nftables chains @@ -415073,7 +417478,7 @@ or /etc/nftables/salt\-all\-in\-one.nft if the former is a directory) .INDENT 0.0 .TP .B salt.states.nftables.table_absent(name, family=\(aqipv4\(aq, **kwargs) -New in version 3002.2. +New in version 3002. .sp Ensure an nftables table is absent @@ -415089,7 +417494,7 @@ Networking family, either ipv4 or ipv6 .INDENT 0.0 .TP .B salt.states.nftables.table_present(name, family=\(aqipv4\(aq, **kwargs) -New in version 3002.2. +New in version 3002. .sp Ensure an nftables table is present @@ -415273,7 +417678,7 @@ Manage NTP servers A list of NTP servers .UNINDENT .UNINDENT -.SS salt.states.nxos module +.SS salt.states.nxos .sp State module for Cisco NX\-OS Switch Proxy and Native minions .sp @@ -415478,7 +417883,7 @@ update: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.nxos_upgrade module +.SS salt.states.nxos_upgrade .sp Manage NX\-OS System Image Upgrades. .INDENT 0.0 @@ -415598,7 +418003,7 @@ The parameter to change. If the parameter is not supplied, the name will be use The value to set .UNINDENT .UNINDENT -.SS salt.states.openvswitch_bridge module +.SS salt.states.openvswitch_bridge .sp Management of Open vSwitch bridges. .INDENT 0.0 @@ -415621,7 +418026,7 @@ Ensures that the named bridge exists, eventually creates it. \fBname\fP \-\- The name of the bridge. .UNINDENT .UNINDENT -.SS salt.states.openvswitch_port module +.SS salt.states.openvswitch_port .sp Management of Open vSwitch ports. .INDENT 0.0 @@ -416843,7 +419248,7 @@ panos/hostname: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.pbm module +.SS salt.states.pbm .sp Manages VMware storage policies (called pbm because the vCenter endpoint is /pbm) @@ -416976,7 +419381,7 @@ Configures storage policies on a vCenter. List of dict representation of the required storage policies .UNINDENT .UNINDENT -.SS salt.states.pcs module +.SS salt.states.pcs .SS Management of Pacemaker/Corosync clusters with PCS .sp A state module to manage Pacemaker/Corosync clusters @@ -420456,11 +422861,6 @@ 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 -Also, some Ubuntu releases have a \fI\%bug\fP in their -\fBpython\-software\-properties\fP package, a missing dependency on pycurl, so -\fBpython\-pycurl\fP will need to be manually installed if it is not present -once \fBpython\-software\-properties\fP is installed. -.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. @@ -420484,7 +422884,7 @@ hello\-copr: .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 pkg.del_repo. +is essentially a wrapper around \fBpkg.del_repo\fP\&. .INDENT 7.0 .TP .B name @@ -420498,7 +422898,7 @@ the regular package manager commands. .B copr Use community packages outside of the main package repository. .sp -New in version 3002.2. +New in version 3002. .INDENT 7.0 .INDENT 3.5 @@ -420598,8 +422998,8 @@ repo. Secondly, it will be the name of the file as stored in .TP .B enabled True -Whether or not the repo is enabled. Can be specified as True/False or -1/0. +Whether the repo is enabled or not. Can be specified as \fBTrue\fP/\fBFalse\fP or +\fB1\fP/\fB0\fP\&. .TP .B disabled False @@ -420612,11 +423012,11 @@ reverse will be passed as \fBenabled\fP\&. For example passing Fedora and RedHat based distributions only. Use community packages outside of the main package repository. .sp -New in version 3002.2. +New in version 3002. .TP .B humanname -This is used as the "name" value in the repo file in +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 @@ -420631,8 +423031,8 @@ 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 True, automatically -trust and import public GPG key for the repository. The key should be +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 @@ -420697,8 +423097,8 @@ logstash\-ppa: .TP .B name On apt\-based systems this must be the complete entry as it would be -seen in the sources.list file. This can have a limited subset of -components (i.e. \(aqmain\(aq) which can be added/modified with the +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 @@ -420745,30 +423145,30 @@ 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, architectures can restrict the available -architectures that the repository provides (e.g. only amd64). -architectures should be a comma\-separated list. +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. main, nonfree, ...). For -purposes of this, comps should be a comma\-separated list. +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 .list that the repository is configured in. +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. unstable). This option is rarely needed. +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 +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 @@ -420783,14 +423183,10 @@ Use either \fBkeyid\fP/\fBkeyserver\fP or \fBkey_url\fP, but not both. .UNINDENT .TP .B key_text -.INDENT 7.0 -.INDENT 3.5 The string representation of the GPG key to install. .sp New in version 2018.3.0. -.UNINDENT -.UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 @@ -420803,15 +423199,15 @@ not more than one method. .B consolidate False If set to \fBTrue\fP, this will consolidate all sources definitions to the -sources.list file, cleanup the now unused files, consolidate components -(e.g. main) for the same URI, type, and architecture to a single line, -and finally remove comments from the sources.list file. The consolidate +\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. +set on one repo managed by Salt to take effect. .TP .B clean_file False -If set to \fBTrue\fP, empty the file before config repo +If set to \fBTrue\fP, empty the file before configuring the defined repository .sp \fBNOTE:\fP .INDENT 7.0 @@ -420827,7 +423223,7 @@ New in version 2015.8.0. .B refresh True If set to \fBFalse\fP this will skip refreshing the apt package database -on debian based systems. +on Debian based systems. .TP .B refresh_db True @@ -420835,8 +423231,9 @@ Deprecated since version 2018.3.0: Use \fBrefresh\fP instead. .TP .B require_in -Set this to a list of pkg.installed or pkg.latest to trigger the -running of apt\-get update prior to attempting to install these +Set this to a list of \fBpkg.installed\fP or +\fBpkg.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. .UNINDENT .UNINDENT @@ -420957,7 +423354,7 @@ security/nmap: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.postgres_cluster module +.SS salt.states.postgres_cluster .SS Management of PostgreSQL clusters .sp The postgres_cluster state module is used to manage PostgreSQL clusters. @@ -422330,7 +424727,7 @@ The user to which the process belongs Signal to send to the process(es). .UNINDENT .UNINDENT -.SS salt.states.proxy module +.SS salt.states.proxy .SS Allows you to manage proxy settings on minions .sp Setup proxy settings on minions @@ -424296,7 +426693,7 @@ New in version 0.17.0. .UNINDENT .UNINDENT -.SS salt.states.salt_proxy module +.SS salt.states.salt_proxy .sp Salt proxy state .sp @@ -426679,7 +429076,7 @@ server\-warning\-message: The message to send via SMTP .UNINDENT .UNINDENT -.SS salt.states.snapper module +.SS salt.states.snapper .SS Managing implicit state and baselines using snapshots .sp New in version 2016.11.0. @@ -426857,7 +429254,7 @@ Snapper config name (Default: root) List of files to ignore. (Default: None) .UNINDENT .UNINDENT -.SS salt.states.solrcloud module +.SS salt.states.solrcloud .sp States for solrcloud alias and collection configuration .sp @@ -428634,7 +431031,7 @@ Returns successful A unique string to serve as the state\(aqs ID .UNINDENT .UNINDENT -.SS salt.states.testinframod module +.SS salt.states.testinframod .SS salt.states.timezone .SS Management of timezones .sp @@ -429873,7 +432270,7 @@ node_name: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.vault module +.SS salt.states.vault .sp States for managing Hashicorp Vault. Currently handles policies. Configuration instructions are documented in the execution module docs. @@ -430082,7 +432479,7 @@ The user that acknowledged the incident. .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.virt module +.SS salt.states.virt .SS Manage virt .sp For the key certificate this state uses the external pillar in the master to call @@ -430100,7 +432497,7 @@ libvirt_keys: .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, update=True, boot_dev=None) +.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) Starts an existing guest, or defines and starts a new VM with specified arguments. .sp New in version 3001. @@ -430112,37 +432509,170 @@ New in version 3001. .IP \(bu 2 \fBname\fP \-\- name of the virtual machine to run .IP \(bu 2 -\fBcpu\fP \-\- number of CPUs for the virtual machine to create -.IP \(bu 2 -\fBmem\fP \-\- +\fBcpu\fP \-\- .sp -Amount of memory to allocate to the virtual machine in MiB. Since 3002.2, 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 and \fBmin_guarantee\fP\&. The -structure of the dictionary is documented in init\-mem\-def\&. Both decimal and binary base are supported. -Detail unit specification is documented in virt\-units\&. Please note that the value for \fBslots\fP must be -an integer. +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 init\-cpu\-def\&. .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 -} +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 -Changed in version 3002.2. +New in version Aluminium. + + +.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 init\-mem\-def\&. Both decimal and binary base are supported. Detail unit +specification is documented in virt\-units\&. 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 @@ -430203,14 +432733,6 @@ pass a None object, for instance: \(aqkernel\(aq: \fBNone\fP\&. New in version 3000. -.IP \(bu 2 -\fBupdate\fP \-\- -.sp -set to \fBFalse\fP to prevent updating a defined domain. (Default: \fBTrue\fP) -.sp -Deprecated since version 3001. - - .IP \(bu 2 \fBboot_dev\fP \-\- .sp @@ -430219,7 +432741,150 @@ Values can be \fBhd\fP, \fBfd\fP, \fBcdrom\fP or \fBnetwork\fP\&. .sp By default, the value will \fB"hd"\fP\&. .sp -New in version 3002.2. +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 init\-cpu\-def\&. +.sp +New in version Aluminium. + +.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 Aluminium. + +.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 Aluminium. + +.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 init\-chardevs\-def for more details on the possible values. +.sp +New in version Aluminium. + + +.IP \(bu 2 +\fBconsoles\fP \-\- +.sp +Dictionary providing details on the consoles device to create. (Default: \fBNone\fP) +See init\-chardevs\-def for more details on the possible values. +.sp +New in version Aluminium. + + +.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 Aluminium. + + +.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 Aluminium. + + +.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 \fBnode_devices()\fP function. +(Default: \fBNone\fP) +.sp +New in version Aluminium. .UNINDENT @@ -430328,28 +432993,82 @@ New in version 2018.3.0. .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) +.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 \-\- Forward mode(bridge, router, nat) +\fBforward\fP \-\- +.sp +Forward mode(bridge, router, nat) +.sp +Changed in version Aluminium: a \fBNone\fP value creates an isolated network with no forwarding at all + + .IP \(bu 2 -\fBvport\fP \-\- Virtualport type (Default: \fB\(aqNone\(aq\fP) +\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 Aluminium: possible dictionary value + + .IP \(bu 2 -\fBtag\fP \-\- Vlan tag (Default: \fB\(aqNone\(aq\fP) +\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 Aluminium: possible dictionary value + + .IP \(bu 2 -\fBipv4_config\fP \-\- IPv4 network configuration. See the :py:func\(gavirt.network_define -\(ga function corresponding parameter documentation +\fBipv4_config\fP \-\- IPv4 network configuration. See the +\fBvirt.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 :py:func\(gavirt.network_define -\(ga function corresponding parameter documentation +\fBipv6_config\fP \-\- IPv6 network configuration. See the \fBvirt.network_define\fP function corresponding parameter documentation for more details on this dictionary. (Default: None). .IP \(bu 2 @@ -430360,6 +433079,165 @@ for more details on this dictionary. \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 Aluminium. + + +.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 Aluminium. + + +.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 Aluminium. + + +.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: "eth10 eth11 eth12" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version Aluminium. + + +.IP \(bu 2 +\fBaddresses\fP \-\- +.sp +whitespace separated list of addreses 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: "0000:04:00.1 0000:e3:01.2" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version Aluminium. + + +.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: "eth0" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version Aluminium. + + +.IP \(bu 2 +\fBdns\fP \-\- +.sp +virtual network DNS configuration +The value is a dictionary described in net\-define\-dns\&. +(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: "v=spf1 a \-all" + _http.tcp.example.com: "name=value,paper=A4" + 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 Aluminium. + + .UNINDENT .UNINDENT .sp @@ -430416,20 +433294,74 @@ network_name: .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) +.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 \-\- Forward mode(bridge, router, nat) +\fBforward\fP \-\- +.sp +Forward mode(bridge, router, nat) +.sp +Changed in version Aluminium: a \fBNone\fP value creates an isolated network with no forwarding at all + + .IP \(bu 2 -\fBvport\fP \-\- Virtualport type (Default: \fB\(aqNone\(aq\fP) +\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 Aluminium: possible dictionary value + + .IP \(bu 2 -\fBtag\fP \-\- Vlan tag (Default: \fB\(aqNone\(aq\fP) +\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 Aluminium: possible dictionary value + + .IP \(bu 2 \fBipv4_config\fP \-\- .sp @@ -430478,6 +433410,165 @@ password to connect with, overriding defaults 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 Aluminium. + + +.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 Aluminium. + + +.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 Aluminium. + + +.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: "eth10 eth11 eth12" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version Aluminium. + + +.IP \(bu 2 +\fBaddresses\fP \-\- +.sp +whitespace separated list of addreses 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: "0000:04:00.1 0000:e3:01.2" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version Aluminium. + + +.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: "eth0" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version Aluminium. + + +.IP \(bu 2 +\fBdns\fP \-\- +.sp +virtual network DNS configuration +The value is a dictionary described in net\-define\-dns\&. +(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.: "printer=lpr5" + example.com.: "This domain name is reserved for use in documentation" + 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 Aluminium. + + .UNINDENT .UNINDENT .INDENT 7.0 @@ -430807,7 +433898,7 @@ domain_name_1: .UNINDENT .INDENT 0.0 .TP -.B salt.states.virt.running(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, update=False, connection=None, username=None, password=None, os_type=None, arch=None, boot=None, boot_dev=None) +.B salt.states.virt.running(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, boot_dev=None, numatune=None, hypervisor_features=None, clock=None, serials=None, consoles=None, stop_on_reboot=False, host_devices=None) Starts an existing guest, or defines and starts a new VM with specified arguments. .sp New in version 2016.3.0. @@ -430819,16 +433910,25 @@ New in version 2016.3.0. .IP \(bu 2 \fBname\fP \-\- name of the virtual machine to run .IP \(bu 2 -\fBcpu\fP \-\- number of CPUs for the virtual machine to create +\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 init\-cpu\-def\&. +.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.2, a dictionary can be used to +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 and \fBmin_guarantee\fP\&. The -structure of the dictionary is documented in init\-mem\-def\&. Both decimal and binary base are supported. -Detail unit specification is documented in virt\-units\&. Please note that the value for \fBslots\fP must be -an integer. +\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 init\-mem\-def\&. Both decimal and binary base are supported. Detail unit +specification is documented in virt\-units\&. 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. @@ -430845,7 +433945,7 @@ is mapped to \fBnull\fP in sls file, pass \fBnull\fP in sls file instead. .UNINDENT .UNINDENT .sp -Changed in version 3002.2. +Changed in version 3002. .IP \(bu 2 @@ -430952,17 +434052,6 @@ Salt command to execute to seed the image. (Default: \fB\(aqseed.apply\(aq\fP) New in version 2019.2.0. -.IP \(bu 2 -\fBupdate\fP \-\- -.sp -set to \fBTrue\fP to update a defined domain. (Default: \fBFalse\fP) -.sp -New in version 2019.2.0. - -.sp -Deprecated since version 3001. - - .IP \(bu 2 \fBconnection\fP \-\- .sp @@ -431020,6 +434109,24 @@ pass a None object, for instance: \(aqkernel\(aq: \fBNone\fP\&. New in version 3000. +.IP \(bu 2 +\fBserials\fP \-\- +.sp +Dictionary providing details on the serials connection to create. (Default: \fBNone\fP) +See init\-chardevs\-def for more details on the possible values. +.sp +New in version Aluminium. + + +.IP \(bu 2 +\fBconsoles\fP \-\- +.sp +Dictionary providing details on the consoles device to create. (Default: \fBNone\fP) +See init\-chardevs\-def for more details on the possible values. +.sp +New in version Aluminium. + + .IP \(bu 2 \fBboot_dev\fP \-\- .sp @@ -431028,7 +434135,114 @@ Values can be \fBhd\fP, \fBfd\fP, \fBcdrom\fP or \fBnetwork\fP\&. .sp By default, the value will \fB"hd"\fP\&. .sp -New in version 3002.2. +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 init\-cpu\-def\&. +.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 Aluminium. + + +.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 Aluminium. + + +.IP \(bu 2 +\fBhypervisor_features\fP \-\- +.sp +Enable or disable hypervisor\-specific features on the virtual machine. +.sp +New in version Aluminium. + +.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 Aluminium. + +.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 +\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 \fBnode_devices()\fP function. +(Default: \fBNone\fP) +.sp +New in version Aluminium. .UNINDENT @@ -431483,7 +434697,7 @@ Update an existing user\(aqs password if it\(aqs different from what\(aqs in the htpasswd file (unlike force, which updates regardless) .UNINDENT .UNINDENT -.SS salt.states.win_certutil module +.SS salt.states.win_certutil .SS Installing of certificates to the Windows Certificate Manager .sp Install certificates to the Windows Certificate Manager @@ -431664,7 +434878,7 @@ Ensure an object is inheriting ACLs from its parent .B salt.states.win_dacl.present(name, objectType, user, permission, acetype, propagation) Ensure an ACE is present .UNINDENT -.SS salt.states.win_dism module +.SS salt.states.win_dism .SS Installing of Windows features using DISM .sp Install windows features/capabilties with DISM @@ -432178,7 +435392,7 @@ enable_all: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.win_iis module +.SS salt.states.win_iis .sp Microsoft IIS site management .sp @@ -432926,7 +436140,7 @@ site0\-IIS\-level\-security: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.win_lgpo module +.SS salt.states.win_lgpo .SS Manage Windows Local Group Policy .sp New in version 2016.11.0. @@ -433200,7 +436414,7 @@ Default is \fBen\-US\fP .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.win_license module +.SS salt.states.win_license .SS Installation and activation of windows licenses .sp Install and activate windows licenses @@ -433448,7 +436662,7 @@ Examples: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.win_pki module +.SS salt.states.win_pki .sp Microsoft certificate management via the Pki PowerShell module. .INDENT 0.0 @@ -433904,7 +437118,7 @@ uninstall_multiple_features: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.win_smtp_server module +.SS salt.states.win_smtp_server .sp Module for managing IIS SMTP server configuration on Windows servers. .INDENT 0.0 @@ -434149,7 +437363,7 @@ smtp\-settings: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.win_snmp module +.SS salt.states.win_snmp .sp Module for managing SNMP service settings on Windows servers. .INDENT 0.0 @@ -434483,7 +437697,7 @@ set workgroup: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.win_wua module +.SS salt.states.win_wua .sp Installation of Windows Updates using the Windows Update Agent .sp @@ -434804,7 +438018,7 @@ update_critical: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.win_wusa module +.SS salt.states.win_wusa .sp Microsoft Updates (KB) Management .sp @@ -434898,7 +438112,7 @@ winrepo: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.wordpress module +.SS salt.states.wordpress .sp This state module is used to manage Wordpress installations .INDENT 0.0 @@ -435702,7 +438916,7 @@ zabbix\-action\-present: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.zabbix_host module +.SS salt.states.zabbix_host .sp Management of Zabbix hosts. .INDENT 0.0 @@ -435849,7 +439063,7 @@ create_test_host: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.zabbix_hostgroup module +.SS salt.states.zabbix_hostgroup .sp Management of Zabbix host groups. .INDENT 0.0 @@ -435925,7 +439139,7 @@ create_testing_host_group: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.zabbix_mediatype module +.SS salt.states.zabbix_mediatype .sp Management of Zabbix mediatypes. .INDENT 0.0 @@ -436234,7 +439448,7 @@ zabbix\-template\-present: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.zabbix_user module +.SS salt.states.zabbix_user .sp Management of Zabbix users. .INDENT 0.0 @@ -436399,7 +439613,7 @@ make_user: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.zabbix_usergroup module +.SS salt.states.zabbix_usergroup .sp Management of Zabbix user groups. .INDENT 0.0 @@ -436481,7 +439695,7 @@ make_new_thai_monks_usergroup: .UNINDENT .UNINDENT .UNINDENT -.SS salt.states.zabbix_usermacro module +.SS salt.states.zabbix_usermacro .sp Management of Zabbix usermacros. :codeauthor: Raymond Kuiper <\fI\%qix@the\-wired.net\fP> @@ -438331,7 +441545,7 @@ React by calling asynchronous runners T} _ .TE -.SS salt.thorium.calc module +.SS salt.thorium.calc .sp Used to manage the thorium register. The thorium register is where compound values are stored and computed, such as averages etc. @@ -438544,7 +441758,7 @@ foo: .UNINDENT .UNINDENT .UNINDENT -.SS salt.thorium.check module +.SS salt.thorium.check .sp The check Thorium state is used to create gateways to commands, the checks make it easy to make states that watch registers for changes and then just @@ -438927,7 +442141,7 @@ run_remote_ex: .UNINDENT .UNINDENT .UNINDENT -.SS salt.thorium.file module +.SS salt.thorium.file .sp Writes matches to disk to verify activity, helpful when testing .sp @@ -439014,7 +442228,7 @@ foo: .UNINDENT .UNINDENT .UNINDENT -.SS salt.thorium.key module +.SS salt.thorium.key .sp The key Thorium State is used to apply changes to the accepted/rejected/pending keys .sp @@ -439046,7 +442260,7 @@ clean_keys: .UNINDENT .UNINDENT .UNINDENT -.SS salt.thorium.local module +.SS salt.thorium.local .sp Run remote execution commands via the local client .INDENT 0.0 @@ -439083,7 +442297,7 @@ run_remote_ex: .UNINDENT .UNINDENT .UNINDENT -.SS salt.thorium.reg module +.SS salt.thorium.reg .sp Used to manage the thorium register. The thorium register is where compound values are stored and computed, such as averages etc. @@ -439192,7 +442406,7 @@ foo: .UNINDENT .UNINDENT .UNINDENT -.SS salt.thorium.runner module +.SS salt.thorium.runner .sp React by calling asynchronous runners .INDENT 0.0 @@ -439224,7 +442438,7 @@ run_cloud: .UNINDENT .UNINDENT .UNINDENT -.SS salt.thorium.status module +.SS salt.thorium.status .sp This thorium state is used to track the status beacon events and keep track of the active status of minions @@ -439238,7 +442452,7 @@ Activate this register to turn on a minion status tracking register, this register keeps the current status beacon data and the time that each beacon was last checked in. .UNINDENT -.SS salt.thorium.timer module +.SS salt.thorium.timer .sp Allow for flow based timers. These timers allow for a sleep to exist across multiple runs of the flow @@ -439263,7 +442477,7 @@ hold_on_a_moment: .UNINDENT .UNINDENT .UNINDENT -.SS salt.thorium.wheel module +.SS salt.thorium.wheel .sp React by calling asynchronous runners .INDENT 0.0 @@ -444956,556 +448170,786 @@ nox \-e \(aqchangelog(draft=False)\(aq \-\- 3000.1 After this is run towncrier will automatically remove all the files in the changelog directory. .SS Contributing .sp -There is a great need for contributions to Salt and patches are welcome! The -goal here is to make contributions clear, make sure there is a trail for where -the code has come from, and most importantly, to give credit where credit is -due! -.sp -There are a number of ways to contribute to Salt development, including (but -not limited to): +So you want to contribute to the Salt project? Excellent! You can help +in a number of ways: .INDENT 0.0 .IP \(bu 2 -filing well\-written bug reports +Using Salt and opening well\-written bug reports. .IP \(bu 2 -enhancing the documentation +Joining a \fI\%working group\fP\&. .IP \(bu 2 -providing workarounds, patches, and other code without tests +Answering 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 -engaging in constructive discussion +Fixing bugs. .IP \(bu 2 -helping out in \fI\%#salt on Freenode\fP, -the \fI\%Community Slack\fP, -the \fI\%salt\-users\fP mailing list, -a \fI\%SaltStack meetup\fP, -or \fI\%Server Fault\fP\&. +\fI\%Enhancing the documentation\fP\&. .IP \(bu 2 -telling others about problems you solved with Salt +Providing workarounds, patches, or other code without tests. +.IP \(bu 2 +Telling other people about problems you solved using Salt. .UNINDENT .sp -If this or other Salt documentation is unclear, please review Writing -Salt Documentation\&. PRs are welcome! -.SS Quickstart +If you’d like to update docs or fix an issue, you’re going to need the +Salt repo. The best way to contribute is using +\fI\%Git\fP\&. +.SS Environment Setup .sp -If you just want to get started before reading the rest of this guide, you can -get the process started by running the following: +To hack on Salt or the docs you’re going to need to set up your +development environment. If you already have a workflow that you’re +comfortable with, you can use that, but otherwise this is an opinionated +guide for setting up your dev environment. Follow these steps and you’ll +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 -python3 \-m pip install \-\-user pre\-commit -git clone \-\-origin upstream https://github.com/saltstack/salt.git -cd salt +git clone https://github.com/pyenv/pyenv.git ~/.pyenv +export PATH="$HOME/.pyenv/bin:$PATH" +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="$HOME/.pyenv/bin:$PATH"\(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.7.0 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If that fails, don’t panic! You’re probably just missing some build +dependencies. Check out \fI\%pyenv common build +problems\fP\&. +.sp +Now that you’ve 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.7.0 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’re 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’s all you’ll 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’s +gonna be a while. +.sp +You’re also going to want to head over to GitHub and create your own +\fI\%fork of Salt\fP\&. Once you’ve +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 +.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’ll 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 \fBpre\-commit\fP and \fBnox\fP Setup +.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 -While those commands are running, finish reading the rest of this guide. -.SS Pre\-commit -.sp -To reduce friction during the development process, SaltStack uses \fI\%pre\-commit\fP\&. This tool adds pre\-commit hooks to git to automate several -processes that used to be manual. Rather than having to remember to run several -different tools before you commit, you only have to run \fBgit commit\fP, and you -will be notified about style and lint issues before you ever open a PR. -.sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 -Currently there is an issue with the pip\-tools\-compile pre\-commit hook on windows. +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 -.SS Salt Coding Style .sp -After the 3000 release, SaltStack is \fI\%joining the ranks\fP of projects -in adopting the \fI\%Black code formatter\fP in order to ease the adoption -of a unified code formatting style. +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’s time to +start hacking on Salt! +.SS Salt Issues +.SS Create Your Own .sp -Where Black is silent, SaltStack has its own coding style guide that informs -contributors on various style points. Please review the Salt Coding Style documentation for information about Salt\(aqs particular coding -patterns. +Perhaps you’ve come to this guide because you found a problem in Salt, +and you’ve 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’s the case, head on over to \fI\%Salt’s issue +tracker on +GitHub\fP\&. .sp -Within the Salt Coding Style documentation, there is a -section about running Salt\(aqs \fB\&.testing.pylintrc\fP file. SaltStack recommends -running the \fB\&.testing.pylintrc\fP file on any files you are changing with your -code contribution before submitting a pull request to Salt\(aqs repository. +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 -If you\(aqve installed \fBpre\-commit\fP, this will automatically happen before each -commit. Otherwise, see the Linting documentation -for more information. -.SS Copyright Headers +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 -Copyright headers are not needed for files in the Salt project. Files that have -existing copyright headers should be considered legacy and not an example to -follow. -.SS New Features -.sp -Feature requests through Salt go through a multi\-stage process. -.sp -All features are added to major releases only. Salt does not accept -feature additions in bug\-fix branches. Therefore, all feature work -is done exclusively in the develop branch. -.sp -To formally propose a new feature, the proposal must take the form -of an RFC. To create an RFC, copy the template file found in the rfcs/ -directory of the Salt codebase and fill the outline with the reasoning -for the new feature and with implementation details. -.sp -Upon submitting the written RFC via a pull\-request, it will be reviewed -by the core development team as well as the community. Once discussed -and agreed upon, the RFC may be merged. -.sp -A merged RFC indicates that a feature has been accepted and will be -added to an upcoming release of Salt. -.SS Sending a GitHub pull request -.sp -Sending pull requests on GitHub is the preferred method for receiving -contributions. The workflow advice below mirrors \fI\%GitHub\(aqs own guide\fP and is well worth reading. +In a nutshell: .INDENT 0.0 -.IP 1. 3 -\fI\%Fork saltstack/salt\fP on GitHub. -.IP 2. 3 -Make a local clone of your fork. (Skip this step if you followed -the Quickstart) -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -git clone git@github.com:my\-account/salt.git -cd salt -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 3. 3 -Add \fI\%saltstack/salt\fP as a git remote. -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -git remote add upstream https://github.com/saltstack/salt.git -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If you followed the Quickstart, you\(aqll add your own remote instead -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -git remote add my\-account git@github.com:my\-account/salt.git -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 4. 3 -Create a new branch in your clone. -.sp -\fBNOTE:\fP -.INDENT 3.0 -.INDENT 3.5 -A branch should have one purpose. For example, "Fix bug X," or "Add -feature Y". Multiple unrelated fixes and/or features should be -isolated into separate branches. -.UNINDENT -.UNINDENT -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -git fetch upstream -git checkout \-b fix\-broken\-thing upstream/master -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 5. 3 -Edit and commit changes to your branch. -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -vim path/to/file1 path/to/file2 tests/test_file1.py tests/test_file2.py -git diff -git add path/to/file1 path/to/file2 -git commit -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Write a short, descriptive commit title and a longer commit message if -necessary. Use an imperative style for the title. -.sp -GOOD -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -Fix broken things in file1 and file2 - -Fixes #31337 - -We needed to make this change because the underlying dependency -changed. Now this uses the up\-to\-date API. - -# Please enter the commit message for your changes. Lines starting -# with \(aq#\(aq will be ignored, and an empty message aborts the commit. -# On branch fix\-broken\-thing -# Changes to be committed: -# modified: path/to/file1 -# modified: path/to/file2 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -BAD -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -Fixes broken things - -# Please enter the commit message for your changes. Lines starting -# with \(aq#\(aq will be ignored, and an empty message aborts the commit. -# On branch fix\-broken\-thing -# Changes to be committed: -# modified: path/to/file1 -# modified: path/to/file2 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Taking a few moments to explain \fIwhy\fP you made a change will save time -and effort in the future when others come to investigate a change. A -clear explanation of why something changed can help future developers -avoid introducing bugs, or breaking an edge case. -.sp -\fBNOTE:\fP -.INDENT 3.0 -.INDENT 3.5 -If your change fixes a bug or implements a feature already filed in the -\fI\%issue tracker\fP, be sure to -\fI\%reference the issue\fP -number in the commit message body. -.UNINDENT -.UNINDENT -.sp -If you get stuck, there are many introductory Git resources on -\fI\%https://help.github.com/en\fP\&. -.IP 6. 3 -Push your locally\-committed changes to your GitHub fork. -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -git push \-u origin fix\-broken\-thing -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -or -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -git push \-u origin add\-cool\-feature -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 3.0 -.INDENT 3.5 -You may want to rebase before pushing to work out any potential -conflicts: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -git fetch upstream -git rebase upstream/master fix\-broken\-thing -git push \-u origin fix\-broken\-thing -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If you do rebase, and the push is rejected with a -\fB(non\-fast\-forward)\fP comment, then run \fBgit status\fP\&. You will -likely see a message about the branches diverging: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -On branch fix\-broken\-thing -Your branch and \(aqorigin/fix\-broken\-thing\(aq have diverged, -and have 1 and 2 different commits each, respectively. - (use "git pull" to merge the remote branch into yours) -nothing to commit, working tree clean -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Do \fBNOT\fP perform a \fBgit pull\fP or \fBgit merge\fP here. Instead, add -\fB\-\-force\-with\-lease\fP to the end of the \fBgit push\fP command to get the changes -pushed to your fork. Pulling or merging, while they will resolve the -non\-fast\-forward issue, will likely add extra commits to the pull -request which were not part of your changes. -.UNINDENT -.UNINDENT -.IP 7. 3 -Find the branch on your GitHub salt fork. -.sp -\fI\%https://github.com/my\-account/salt/branches/fix\-broken\-thing\fP -.IP 8. 3 -Open a new pull request. -.sp -Click on \fBPull Request\fP on the right near the top of the page, -.sp -\fI\%https://github.com/my\-account/salt/pull/new/fix\-broken\-thing\fP -.INDENT 3.0 -.IP 1. 3 -Choose \fBmaster\fP as the base Salt branch. -.IP 2. 3 -Review that the proposed changes are what you expect. -.IP 3. 3 -Write a descriptive comment. If you added good information to your git -commit message, they will already be present here. Include links to -related issues (e.g. \(aqFixes #31337.\(aq) in the comment field. -.IP 4. 3 -Click \fBCreate pull request\fP\&. -.UNINDENT -.IP 9. 3 -Salt project members will review your pull request and automated tests will -run on it. -.sp -If you recognize any test failures as being related to your proposed -changes or if a reviewer asks for modifications: -.INDENT 3.0 -.IP 1. 3 -Make the new changes in your local clone on the same local branch. -.IP 2. 3 -Push the branch to GitHub again using the same commands as before. -.IP 3. 3 -New and updated commits will be added to the pull request automatically. -.IP 4. 3 -Feel free to add a comment to the discussion. -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Jenkins -.sp -Pull request against \fI\%saltstack/salt\fP are automatically tested on a -variety of operating systems and configurations. On average these tests -take a couple of hours. Depending on your GitHub notification settings -you may also receive an email message about the test results. -.sp -Test progress and results can be found at \fI\%https://jenkinsci.saltstack.com/\fP\&. -.UNINDENT -.UNINDENT -.SS Salt\(aqs Branch Topology -.sp -Salt will only have one active branch \- \fBmaster\fP\&. -This will include bug fixes, features and CVE “Common Vulnerabilities and Exposures”. -.sp -The release will be cut from the master when the time comes for a new release, -which should be every 3 to 4 months. -.sp -To be able to merge code: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP 1. 3 -The code must have a well\-written test. -Note that you are only expected to write tests for what you did, not the whole modules or function. -.IP 2. 3 -All tests must pass. -.UNINDENT -.UNINDENT -.UNINDENT -.sp -The SaltStack employee that reviews your pull request might request changes or deny the pull request for various reasons. -.sp -Salt uses a typical branch strategy \- \fBmaster\fP is the next expected release. -Code should only make it to \fBmaster\fP once it\(aqs production ready. This means -that typical changes (fixes, features) should have accompanying tests. -.SS Closing GitHub issues from commits -.sp -SaltStack encourages using \fI\%the magic keywords to close a GitHub issue\fP\&. These should appear in the commit message text -directly. -.SS Release Naming Convention -.sp -A new convention will start when Salt releases Salt 3000. -Every new release name will increment by one ‘Salt last_release_number + 1’. -.sp -This naming convention is very different from past releases, which was \(aqYYYY.MM.PATCH\(aq. -.SS Handling CVE -.sp -If a CVE is discovered, Salt will create a new release that \fBonly\fP contains the tests and patch for the CVE. -This method should improve the upgrade process by reducing the chances of breaking something. -.SS Backporting Pull Requests -.sp -On rare occasions, a serious bug will be found in the middle of a release -cycle. These bugs will require a point release. Contributors should still -submit fixes directly to \fBmaster\fP, but they should also call attention to the -fact that it addresses a critical issue and will need to be back\-ported. -.SS Keeping Salt Forks in Sync -.sp -Salt advances quickly. It is therefore critical to pull upstream changes from -upstream into your fork on a regular basis. Nothing is worse than putting hard -work into a pull request only to see bunches of merge conflicts because it has -diverged too far from upstream. -.sp -\fBSEE ALSO:\fP -.INDENT 0.0 -.INDENT 3.5 -\fI\%GitHub Fork a Repo Guide\fP -.UNINDENT -.UNINDENT -.sp -The following assumes \fBorigin\fP is the name of your fork and \fBupstream\fP is -the name of the main \fI\%saltstack/salt\fP repository. -.INDENT 0.0 -.IP 1. 3 -View existing remotes. -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -git remote \-v -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 2. 3 -Add the \fBupstream\fP remote. -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -# For ssh github -git remote add upstream git@github.com:saltstack/salt.git - -# For https github -git remote add upstream https://github.com/saltstack/salt.git -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 3. 3 -Pull upstream changes into your clone. -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -git fetch upstream -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 4. 3 -Update your copy of the \fBmaster\fP branch. -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -git checkout master -git merge \-\-ff\-only upstream/master -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If Git complains that a fast\-forward merge is not possible, you have local -commits. -.INDENT 3.0 .IP \(bu 2 -Run \fBgit pull \-\-rebase origin master\fP to rebase your changes on top of -the upstream changes. +\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 -Or, run \fBgit branch \fP to create a new branch with your -commits. You will then need to reset your \fBmaster\fP branch before -updating it with the changes from upstream. +\fBComplete\fP: Minimum also means complete. If your example is missing +information, then it’s 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 -If Git complains that local files will be overwritten, you have changes to -files in your working directory. Run \fBgit status\fP to see the files in -question. -.IP 5. 3 -Update your fork. -.INDENT 3.0 +Slow is smooth, and smooth is fast \- it may feel like you’re taking a +long time to create your issue if you’re 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’t 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’s a good idea to comment on the issue and +mention that you’re working on it. Good communication is key to +collaboration \- so if you don’t 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’t Write Tests or Docs? +.sp +If you aren’t 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’s 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’d 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. Since we use nox, 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 -git push origin master +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 -.IP 6. 3 -Repeat the previous two steps for any other branches you work with, such as -the current release branch. +.sp +The first time this 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 Sphinx is 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 -.SS Posting patches to the mailing list .sp -Patches will also be accepted by email. Format patches using \fI\%git -format\-patch\fP and send them to the \fI\%salt\-users\fP mailing list. The contributor -will then get credit for the patch, and the Salt community will have an archive -of the patch and a place for discussion. -.SS Issue and Pull Request Labeling System +And then refresh your browser to get your updated docs. This one should +be quite a bit faster since Sphinx won’t need to rebuild everything. .sp -SaltStack uses several labeling schemes to help facilitate code contributions -and bug resolution. See the Labels and Milestones documentation for more information. -.SS Mentionbot +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’s a docs\-only change by +adding \fB[Documentation]\fP to the title of your PR. Otherwise you’ll +want to write some tests and code. +.SS Running Development Salt .sp -SaltStack runs a mention\-bot which notifies contributors who might be able -to help review incoming pull\-requests based on their past contribution to -files which are being changed. +Note: If you run into any issues in this section, check the +Troubleshooting section. .sp -If you do not wish to receive these notifications, please add your GitHub -handle to the blacklist line in the \fB\&.mention\-bot\fP file located in the -root of the Salt repository. -.SS Bootstrap Script Changes +If you’re going to hack on the Salt codebase you’re 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 -Salt\(aqs Bootstrap Script, known as \fI\%bootstrap\-salt.sh\fP in the Salt repo, has its own -repository, contributing guidelines, and release cadence. +.nf +.ft C +python \-m pip install \-e . +.ft P +.fi +.UNINDENT +.UNINDENT .sp -All changes to the Bootstrap Script should be made to \fI\%salt\-bootstrap repo\fP\&. Any -pull requests made to the \fI\%bootstrap\-salt.sh\fP file in the Salt repository will be -automatically overwritten upon the next stable release of the Bootstrap Script. +This will let you make changes to Salt without having to re\-install it. .sp -For more information on the release process or how to contribute to the Bootstrap -Script, see the Bootstrap Script\(aqs \fI\%Contributing Guidelines\fP\&. +After all of the dependencies and Salt are installed, it’s 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 <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 <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’re running \fBsalt\-call\fP instead of \fBsalt\fP, and you’re +not specifying the minion (\fB\e*\fP), but if you’re running the dev +version then you still will need to pass in the config dir. Now that +you’ve got Salt running, you can hack away on the Salt codebase! +.sp +If you need to restart Salt for some reason, if you’ve made changes and +they don’t 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’d 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’ll +find those in the \fBsalt/tests\fP directory. +.sp +When you’re 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’t answer those questions then you might need to refactor your +tests. +.sp +When you’re running tests locally, you should make sure that if you +remove your code changes your tests are failing. If your tests \fIaren’t\fP +failing when you haven’t yet made changes, then it’s possible that +you’re 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’s 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 "pytest\-3.7(coverage=False)" \-\- tests/unit/cli/test_batch.py +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +It’s a good idea to install +\fI\%espeak\fP or use \fBsay\fP on +Mac if you’re 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 "pytest\-3.7(coverage=False)" \-\- tests/unit/cli/test_batch.py; espeak "Tests done, woohoo!" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +That way you don’t have to keep monitoring the actual test run. +.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’t 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.\fP format. For +instanch, if you fixed issue 123, you would do: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +echo "Made sys.doc inform when no minions return" > changelog/123.fixed +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +And that’s all that would go into your file. When it comes to your +commit message, it’s 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’t 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. +.SS PR Time! +.sp +Once you’ve done all your dev work and tested locally, you should check +out our \fI\%PR +guidelines\fP\&. +After you read that page, it’s 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’re 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’ve 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’re not in a code freeze, ideally your code will be merged +that day. If you haven’t heard from your assigned reviewer, ping them on +GitHub, \fI\%irc\fP, or Community +Slack. +.sp +It’s 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’s 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’re not interested in driving your PR to +completion then just note that in your PR. Something like, “I’m 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’ll +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’re 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 "/path/to/your/virtualenv/var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc" 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 "/var/log/salt/master", 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’ll 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 .SS Deprecating Code .sp Salt should remain backwards compatible, though sometimes, this backwards @@ -445521,17 +448965,17 @@ new behavior, the deprecation time frame should be carefully determined based on the significance and complexity of the changes required by the user. .sp Salt feature releases are based on the Periodic Table. Any new features going -into the develop branch will be named after the next element in the Periodic -Table. For example, Beryllium was the feature release name of the develop -branch before the 2015.8 branch was tagged. At that point in time, any new -features going into the develop branch after 2015.8 was branched were part of -the Boron feature release. +into the \fBmaster\fP branch will be named after the next element in the Periodic +Table. For example, Magnesium was the feature release name associated with the +\fBv3002\fP tag. At that point in time, any new features going into the +\fBmaster\fP branch, after \fBv3002\fP was tagged, were part of the Aluminium feature +release. .sp A deprecation warning should be in place for at least two major releases before the deprecated code and its accompanying deprecation warning are removed. More time should be given for more complex changes. For example, if the current release under development is \fB3001\fP, the deprecated code and associated -warnings should remain in place and warn for at least \fBAluminum\fP\&. +warnings should remain in place and warn for at least \fBAluminium\fP\&. .sp To help in this deprecation task, salt provides \fBsalt.utils.versions.warn_until\fP\&. The @@ -445551,7 +448995,7 @@ Consider the following example: def some_function(bar=False, foo=None): if foo is not None: salt.utils.versions.warn_until( - "Aluminum", + "Aluminium", "The \(aqfoo\(aq argument has been deprecated and its " "functionality removed, as such, its usage is no longer " "required.", @@ -445561,9 +449005,9 @@ def some_function(bar=False, foo=None): .UNINDENT .UNINDENT .sp -Development begins on the \fBAluminum\fP release when the \fB3002.2\fP branch is -forked from the develop branch. Once this occurs, all uses of the -\fBwarn_until\fP function targeting \fBAluminum\fP, along with the code they are +Development begins on \fBAluminium\fP, or \fBv3003\fP, after the \fBv3002\fP tag is +applied to the \fBmaster\fP branch. Once this occurs, all uses of the +\fBwarn_until\fP function targeting \fBAluminium\fP, along with the code they are warning about should be removed from the code. .SS Python 2 Deprecation FAQ .SS FAQ @@ -446351,15 +449795,6 @@ been moved beyond the \fBBlocked\fP milestone, it is very likely that it will only have a status label. .INDENT 0.0 .IP \(bu 2 -\fBBugfix \- back\-port\fP The pull request needs to be back\-ported to an older -release branch. This is done by recreating the pull request against that branch. Once the back\-port is -completed, this label is replaced with a \fBBugfix \- [Done] back\-ported\fP -label. Normally, new features should go into the develop and bug fixes into -the oldest supported release branch, see here\&. -.IP \(bu 2 -\fBBugfix \- [Done] back\-ported\fP \- The pull request has been back\-ported to an -older branch. -.IP \(bu 2 \fBCannot Reproduce\fP \- The issue is a bug and has been reviewed by a SaltStack engineer, but it cannot be replicated with the provided information and context. Those involved with the bug will need to work through @@ -446396,77 +449831,22 @@ cogent conclusion, this label will be removed and the issue will be accepted. If it is a pull request, the results of the discussion may require additional changes and thus, a \fBPending Changes\fP label. .IP \(bu 2 -\fBWon\(aqt Fix for Now\fP \- The issue is legitimate, but it is not something the -SaltStack team is currently able or willing to fix or implement. Issues -having this label may be revisited in the future. -.UNINDENT -.SS Type of Change -.sp -Every pull request should receive a change label. These labels measure the -quantity of change as well as the significance of the change. The amount of -change and the importance of the code area changed are considered, but often -the depth of secondary code review required and the potential repercussions of -the change may also advise the label choice. -.sp -Core code areas include: state compiler, crypto engine, master and minion and -syndic daemons, transport, pillar rendering, loader, transport layer, event -system, salt.utils, client, cli, logging, netapi, runner engine, templating -engine, top file compilation, file client, file server, mine, salt\-ssh, test -runner, etc. -.sp -Non\-core code usually constitutes the specific set of plugins for each of the -several plugin layers of Salt: execution modules, states, runners, returners, -clouds, etc. -.INDENT 0.0 -.IP \(bu 2 -\fBMinor Change\fP -.INDENT 2.0 -.IP \(bu 2 -Less than 64 lines changed, or -.IP \(bu 2 -Less than 8 core lines changed -.UNINDENT -.IP \(bu 2 -\fBMedium Change\fP -.INDENT 2.0 -.IP \(bu 2 -Less than 256 lines changed, or -.IP \(bu 2 -Less than 64 core lines changed -.UNINDENT -.IP \(bu 2 -\fBMaster Change\fP -.INDENT 2.0 -.IP \(bu 2 -More than 256 lines changed, or -.IP \(bu 2 -More than 64 core lines changed -.UNINDENT -.IP \(bu 2 -\fBExpert Change\fP -.INDENT 2.0 -.IP \(bu 2 -Needs specialized, in\-depth review -.UNINDENT +\fBwon\(aqt\-fix\fP \- The issue is legitimate, but it is not something the +Salt core team is currently able or willing to fix or implement. Issues +having this label may be revisited in the future, or solved by a Salt +community member. .UNINDENT .SS Test Status .sp These labels relate to the status of the automated tests that run on pull -requests. If the tests on a pull request fail and are not overridden by one of -these labels, the pull request submitter needs to update the code and/or tests -so that the tests pass and the pull request can be merged. +requests. .INDENT 0.0 .IP \(bu 2 -\fBLint\fP \- The pull request has passed all tests except for the code lint -checker. +\fBhas\-failing\-test\fP \- The PR currently has one or more failing tests that +prevent the PR from being merged. .IP \(bu 2 -\fBTests Passed\fP \- The pull request has passed all tests even though some -test results are negative. Sometimes the automated testing infrastructure -will encounter internal errors unrelated to the code change in the pull -request that cause test runs to fail. These errors can be caused by cloud -host and network issues and also Jenkins issues like erroneously accumulating -workspace artifacts, resource exhaustion, and bugs that arise from long -running Jenkins processes. +\fBNeeds Testcase\fP \- The PR has code changes, but lack any automated tests. +These PRs need automated tests written before they may be merged. .UNINDENT .SS Other .sp @@ -446480,11 +449860,6 @@ solution, or a very difficult but necessary change. \fBHelp Wanted\fP \- The issue appears to have a simple solution. Issues having this label should be a good starting place for new contributors to Salt. .IP \(bu 2 -\fBNeeds Testcase\fP \- The issue or pull request relates to a feature that -needs test coverage. The pull request containing the tests should reference -the issue or pull request having this label, whereupon the label should be -removed. -.IP \(bu 2 \fBRegression\fP \- The issue is a bug that breaks functionality known to work in previous releases. .IP \(bu 2 @@ -448941,6 +452316,19 @@ nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq .UNINDENT .UNINDENT .sp +As a contrast, when using the deprecated \fBruntests.py\fP test runner, the +command would be: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +nox \-e \(aqruntests\-zeromq\-3(coverage=False)\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp To run all the tests but on the tcp transport, you would need to specify the tcp session. .INDENT 0.0 .INDENT 3.5 @@ -448953,6 +452341,19 @@ nox \-e \(aqpytest\-tcp\-3(coverage=False)\(aq .UNINDENT .UNINDENT .sp +As a contrast, when using the deprecated \fBruntests.py\fP test runner, the +command would be: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +nox \-e \(aqruntests\-tcp\-3(coverage=False)\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp You can view all available sessions by running: .INDENT 0.0 .INDENT 3.5 @@ -449102,17 +452503,28 @@ Instead of running the entire test suite all at once, which can take a long time there are several ways to run only specific groups of tests or individual tests: .INDENT 0.0 .IP \(bu 2 -Run \fI\%unit tests only\fP: \fBnox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/unit/\fP +Run \fI\%unit tests only\fP: \fBnox \-e +\(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/unit/\fP, using the deprecated \fBruntests.py\fP the command would be \fBnox \-e +\(aqruntests\-zeromq\-3(coverage=False)\(aq \-\- \-\-unit\-tests\fP .IP \(bu 2 -Run unit and integration tests for states: \fBnox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/unit/states/ tests/integration/states/\fP +Run unit and integration tests for states: \fBnox \-e +\(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/unit/states/ tests/integration/states/\fP, using the deprecated +\fBruntests.py\fP the command would be \fBnox \-e \(aqruntests\-zeromq\-3(coverage=False)\(aq \-\- \-\-state\-tests\fP .IP \(bu 2 -Run integration tests for an individual module: \fBnox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/integration/modules/test_virt.py\fP +Run integration tests for an individual module: \fBnox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- +tests/integration/modules/test_virt.py\fP, using the deprecated \fBruntests.py\fP the command would be \fBnox \-e +\(aqruntests\-zeromq\-3(coverage=False)\(aq \-\- \-n integration.modules.test_virt\fP .IP \(bu 2 -Run unit tests for an individual module: \fBnox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/unit/modules/test_virt.py\fP +Run unit tests for an individual module: \fBnox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- +tests/unit/modules/test_virt.py\fP, using the deprecated \fBruntests.py\fP the command would be \fBnox \-e +\(aqruntests\-zeromq\-3(coverage=False)\(aq \-\- \-n unit.modules.test_virt\fP .IP \(bu 2 Run an individual test by using the class and test name (this example is for the \fBtest_default_kvm_profile\fP test in the \fBtests/integration/module/test_virt.py\fP): -\fBnox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/integration/modules/test_virt.py::VirtTest::test_default_kvm_profile\fP +\fBnox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- +tests/integration/modules/test_virt.py::VirtTest::test_default_kvm_profile\fP, using the deprecated \fBruntests.py\fP the +command would be \fBnox \-e \(aqruntests\-zeromq\-3(coverage=False)\(aq \-\- \-n +integration.modules.test_virt.VirtTest.test_default_kvm_profile\fP .UNINDENT .sp For more specific examples of how to run various test subsections or individual @@ -449138,6 +452550,19 @@ nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/unit/ .UNINDENT .UNINDENT .sp +As a contrast, when using the deprecated \fBruntests.py\fP test runner, the +command would be: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +nox \-e \(aqruntests\-zeromq\-3(coverage=False)\(aq \-\- \-\-unit\-tests +.ft P +.fi +.UNINDENT +.UNINDENT +.sp All of the other options to run individual tests, entire classes of tests, or entire test modules still apply. .SS Running Destructive Integration Tests @@ -449174,6 +452599,19 @@ nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- \-\-run\-destructive .fi .UNINDENT .UNINDENT +.sp +As a contrast, when using the deprecated \fBruntests.py\fP test runner, the +command would be: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +nox \-e \(aqruntests\-zeromq\-3(coverage=False)\(aq \-\- \-\-run\-destuctive +.ft P +.fi +.UNINDENT +.UNINDENT .SS Running Cloud Provider Tests .sp Salt\(aqs testing suite also includes integration tests to assess the successful @@ -449239,6 +452677,19 @@ nox \-e \(aqpytest\-cloud\-3(coverage=False)\(aq .fi .UNINDENT .UNINDENT +.sp +As a contrast, when using the deprecated \fBruntests.py\fP test runner, the +command would be: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +nox \-e \(aqruntests\-cloud\-3(coverage=False)\(aq +.ft P +.fi +.UNINDENT +.UNINDENT .SS Automated Test Runs .sp SaltStack maintains a Jenkins server to allow for the execution of tests @@ -449338,11 +452789,19 @@ for more details about where to submit tests for functions or files that do not already have tests. .SS Tests to Accompany a Bugfix .sp -If you are writing tests for code that fixes a bug in Salt, please write the test -in the same pull request as the bugfix. If you\(aqre unsure of where to submit your -bugfix and accompanying test, please review the -Which Salt Branch? documentation in Salt\(aqs -Contributing guide. +If you are writing tests for code that fixes a bug in Salt, tests will be +required before merging the PR. A great option for most bugfixes is to adopt a +TDD style approach: +.INDENT 0.0 +.IP \(bu 2 +reproduce the issue +.IP \(bu 2 +write a test that exhibits the behavior +.IP \(bu 2 +write the bugfix +.UNINDENT +.sp +This helps ensure that known issues are not reintroduced into the codebase. .SS Tests for Entire Files or Functions .sp Sometimes entire files in Salt are completely untested. If you are writing tests for @@ -450169,14 +453628,16 @@ a function\(aqs logic. .sp Salt loader modules use a series of globally available dunder variables, \fB__salt__\fP, \fB__opts__\fP, \fB__pillar__\fP, etc. To facilitate testing these -modules a helper class was created, \fBLoaderModuleMock\fP which can be found in -\fBtests/support/pytest/loader.py\fP\&. The reason for the existence of this class -is because historically one would add these dunder variables directly on the -imported module. This, however, introduces unexpected behavior when running the -full test suite since those attributes would not be removed once we were done -testing the module and would therefore leak to other modules being tested with -unpredictable results. This is the kind of work that should be deferred to -mock, and that\(aqs exactly what this class provides. +modules \fI\%pytest\-salt\-factories\fP has a plugin which will prepare the module globals +by patching and mocking the dunders prior to running each test, as long as the test module +defines a fixture named \fBconfigure_loader_modules\fP\&. Check out the code for the +\fIpytest\-salt\-factories plugin\fP to know how it\(aqs internals work. +.sp +The reason for the existence of this plugin is because historically one would add these dunder +variables directly on the imported module. This, however, introduces unexpected behavior when +running the full test suite since those attributes would not be removed once we were done testing +the module and would therefore leak to other modules being tested with unpredictable results. This +is the kind of work that should be deferred to mock, and that\(aqs exactly what this plugin provides. .sp As an example, if one needs to specify some options which should be available to the module being tested one should do: @@ -450189,33 +453650,32 @@ import pytest import salt.modules.somemodule as somemodule -@pytest.fixture(autouse=True) -def setup_loader(): - setup_loader_modules = {somemodule: {"__opts__": {"test": True}}} - with pytest.helpers.loader_mock(setup_loader_modules) as loader_mock: - yield loader_mock +@pytest.fixture +def configure_loader_modules(): + """ + This fixture should return a dictionary which is what\(aqs going to be used to + patch and mock Salt\(aqs loader + """ + return {somemodule: {"__opts__": {"test": True}}} .ft P .fi .UNINDENT .UNINDENT .sp -Consider this more extensive example from -\fBtests/pytests/unit/beacons/test_sensehat.py\fP: +Consider this more extensive example from \fBtests/pytests/unit/beacons/test_sensehat.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -from __future__ import absolute_import - import pytest import salt.beacons.sensehat as sensehat from tests.support.mock import MagicMock -@pytest.fixture(autouse=True) -def setup_loader(): - setup_loader_modules = { +@pytest.fixture +def configure_loader_modules(): + return { sensehat: { "__salt__": { "sensehat.get_humidity": MagicMock(return_value=80), @@ -450224,8 +453684,6 @@ def setup_loader(): }, } } - with pytest.helpers.loader_mock(setup_loader_modules) as loader_mock: - yield loader_mock def test_non_list_config(): @@ -450788,7 +454246,7 @@ from tests.support.mock import MagicMock, patch, call .SS Evaluating Truth .sp A longer discussion on the types of assertions one can make can be found by -reading \fI\%PyTests\(aqs documentation on assertions\fP\&. +reading \fI\%PyTest\(aqs documentation on assertions\fP\&. .SS Tests Using Mock Objects .sp In many cases, the purpose of a Salt module is to interact with some external @@ -450839,14 +454297,14 @@ additional imports for MagicMock: .sp .nf .ft C -# Import Salt execution module to test from salt.modules import db - -# Import Mock libraries from tests.support.mock import MagicMock, patch, call -# Create test case + def test_create_user(): + """ + Test creating a user + """ # First, we replace \(aqexecute_query\(aq with our own mock function with patch.object(db, "execute_query", MagicMock()) as db_exq: @@ -450882,6 +454340,19 @@ function into \fB__salt__\fP that\(aqs actually a MagicMock instance. .sp .nf .ft C +import pytest +import salt.modules.my_module as my_module + + +@pytest.fixture +def configure_loader_modules(): + """ + This fixture should return a dictionary which is what\(aqs going to be used to + patch and mock Salt\(aqs loader + """ + return {my_module: {}} + + def show_patch(self): with patch.dict(my_module.__salt__, {"function.to_replace": MagicMock()}): # From this scope, carry on with testing, with a modified __salt__! @@ -450898,38 +454369,28 @@ execution module. Given a module called \fBfib.py\fP that has a function called sequential Fibonacci numbers of that length. .sp A unit test to test this function might be commonly placed in a file called -\fBtests/unit/modules/test_fib.py\fP\&. The convention is to place unit tests for -Salt execution modules in \fBtest/unit/modules/\fP and to name the tests module +\fBtests/pytests/unit/modules/test_fib.py\fP\&. The convention is to place unit tests for +Salt execution modules in \fBtest/pytests/unit/modules/\fP and to name the tests module prefixed with \fBtest_*.py\fP\&. .sp Tests are grouped around test cases, which are logically grouped sets of tests -against a piece of functionality in the tested software. Test cases are created -as Python classes in the unit test module. To return to our example, here\(aqs how +against a piece of functionality in the tested software. To return to our example, here\(aqs how we might write the skeleton for testing \fBfib.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -# Import Salt Testing libs -from tests.support.unit import TestCase - -# Import Salt execution module to test import salt.modules.fib as fib -# Create test case class and inherit from Salt\(aqs customized TestCase -class FibTestCase(TestCase): - """ - This class contains a set of functions that test salt.modules.fib. - """ - def test_fib(self): - """ - To create a unit test, we should prefix the name with \(gatest_\(aq so - that it\(aqs recognized by the test runner. - """ - fib_five = (0, 1, 1, 2, 3) - self.assertEqual(fib.calculate(5), fib_five) +def test_fib(): + """ + To create a unit test, we should prefix the name with \(gatest_\(aq so + that it\(aqs recognized by the test runner. + """ + fib_five = (0, 1, 1, 2, 3) + assert fib.calculate(5) == fib_five .ft P .fi .UNINDENT @@ -450943,7 +454404,7 @@ executed: .sp .nf .ft C -tests/runtests.py \-v \-n unit.modules.test_fib +nox \-e \(aqpytest\-3(coverage=False)\(aq \-\- \-v tests/pytests/unit/modules/test_fib.py .ft P .fi .UNINDENT @@ -450951,25 +454412,15 @@ tests/runtests.py \-v \-n unit.modules.test_fib .sp This will report the status of the test: success, failure, or error. The \fB\-v\fP flag increases output verbosity. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -tests/runtests.py \-n unit.modules.test_fib \-v -.ft P -.fi -.UNINDENT -.UNINDENT .sp To review the results of a particular run, take a note of the log location -given in the output for each test: +given in the output for each test run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -Logging tests on /var/folders/nl/d809xbq577l3qrbj3ymtpbq80000gn/T/salt\-runtests.log +\&...etc... \-\-log\-file=artifacts/logs/runtests\-20210106103414.685791.log ...etc... .ft P .fi .UNINDENT @@ -450992,8 +454443,8 @@ def get(name): salt \(aq*\(aq sysctl.get net.ipv4.ip_forward """ - cmd = "sysctl \-n {0}".format(name) - out = __salt__["cmd.run"](cmd) + cmd = "sysctl \-n {}".format(name) + out = __salt__["cmd.run"](cmd, python_shell=False) return out .ft P .fi @@ -451014,27 +454465,23 @@ will also redefine the \fB__salt__\fP dictionary such that it only contains .sp .nf .ft C -# Import Salt Libs +import pytest import salt.modules.linux_sysictl as linux_sysctl - -# Import Salt Testing Libs -from tests.support.mixins import LoaderModuleMockMixin -from tests.support.unit import TestCase from tests.support.mock import MagicMock, patch -class LinuxSysctlTestCase(TestCase, LoaderModuleMockMixin): - """ - TestCase for salt.modules.linux_sysctl module - """ +@pytest.fixture +def configure_loader_modules(): + return {linux_sysctl: {}} - def test_get(self): - """ - Tests the return of get function - """ - mock_cmd = MagicMock(return_value=1) - with patch.dict(linux_sysctl.__salt__, {"cmd.run": mock_cmd}): - self.assertEqual(linux_sysctl.get("net.ipv4.ip_forward"), 1) + +def test_get(): + """ + Tests the return of get function + """ + mock_cmd = MagicMock(return_value=1) + with patch.dict(linux_sysctl.__salt__, {"cmd.run": mock_cmd}): + assert linux_sysctl.get("net.ipv4.ip_forward") == 1 .ft P .fi .UNINDENT @@ -451070,27 +454517,30 @@ def assign(name, value): salt \(aq*\(aq sysctl.assign net.ipv4.ip_forward 1 """ value = str(value) - sysctl_file = "/proc/sys/{0}".format(name.replace(".", "/")) + + tran_tab = name.translate("".maketrans("./", "/.")) + + sysctl_file = "/proc/sys/{}".format(tran_tab) if not os.path.exists(sysctl_file): - raise CommandExecutionError("sysctl {0} does not exist".format(name)) + raise CommandExecutionError("sysctl {} does not exist".format(name)) ret = {} - cmd = \(aqsysctl \-w {0}="{1}"\(aq.format(name, value) - data = __salt__["cmd.run_all"](cmd) + cmd = \(aqsysctl \-w {}="{}"\(aq.format(name, value) + data = __salt__["cmd.run_all"](cmd, python_shell=False) out = data["stdout"] err = data["stderr"] # Example: # # sysctl \-w net.ipv4.tcp_rmem="4096 87380 16777216" # net.ipv4.tcp_rmem = 4096 87380 16777216 - regex = re.compile(r"^{0}\es+=\es+{1}$".format(re.escape(name), re.escape(value))) + regex = re.compile(r"^{}\es+=\es+{}$".format(re.escape(name), re.escape(value))) if not regex.match(out) or "Invalid argument" in str(err): if data["retcode"] != 0 and err: error = err else: error = out - raise CommandExecutionError("sysctl \-w failed: {0}".format(error)) + raise CommandExecutionError("sysctl \-w failed: {}".format(error)) new_name, new_value = out.split(" = ", 1) ret[new_name] = new_value return ret @@ -451115,26 +454565,22 @@ with. .sp .nf .ft C -# Import Salt Libs +import pytest import salt.modules.linux_sysctl as linux_sysctl from salt.exceptions import CommandExecutionError - -# Import Salt Testing Libs -from tests.support.mixins import LoaderModuleMockMixin -from tests.support.unit import TestCase from tests.support.mock import MagicMock, patch -class LinuxSysctlTestCase(TestCase, LoaderModuleMockMixin): - """ - TestCase for salt.modules.linux_sysctl module - """ +@pytest.fixture +def configure_loader_modules(): + return {linux_sysctl: {}} - @patch("os.path.exists", MagicMock(return_value=False)) - def test_assign_proc_sys_failed(self): - """ - Tests if /proc/sys/ exists or not - """ + +def test_assign_proc_sys_failed(): + """ + Tests if /proc/sys/ exists or not + """ + with patch("os.path.exists", MagicMock(return_value=False)): cmd = { "pid": 1337, "retcode": 0, @@ -451143,15 +454589,15 @@ class LinuxSysctlTestCase(TestCase, LoaderModuleMockMixin): } mock_cmd = MagicMock(return_value=cmd) with patch.dict(linux_sysctl.__salt__, {"cmd.run_all": mock_cmd}): - self.assertRaises( - CommandExecutionError, linux_sysctl.assign, "net.ipv4.ip_forward", 1 - ) + with pytest.raises(CommandExecutionError): + linux_sysctl.assign("net.ipv4.ip_forward", 1) - @patch("os.path.exists", MagicMock(return_value=True)) - def test_assign_cmd_failed(self): - """ - Tests if the assignment was successful or not - """ + +def test_assign_cmd_failed(): + """ + Tests if the assignment was successful or not + """ + with patch("os.path.exists", MagicMock(return_value=True)): cmd = { "pid": 1337, "retcode": 0, @@ -451160,18 +454606,15 @@ class LinuxSysctlTestCase(TestCase, LoaderModuleMockMixin): } mock_cmd = MagicMock(return_value=cmd) with patch.dict(linux_sysctl.__salt__, {"cmd.run_all": mock_cmd}): - self.assertRaises( - CommandExecutionError, - linux_sysctl.assign, - "net.ipv4.ip_forward", - "backward", - ) + with pytest.raises(CommandExecutionError): + linux_sysctl.assign("net.ipv4.ip_forward", "backward") - @patch("os.path.exists", MagicMock(return_value=True)) - def test_assign_success(self): - """ - Tests the return of successful assign function - """ + +def test_assign_success(): + """ + Tests the return of successful assign function + """ + with patch("os.path.exists", MagicMock(return_value=True)): cmd = { "pid": 1337, "retcode": 0, @@ -451181,7 +454624,7 @@ class LinuxSysctlTestCase(TestCase, LoaderModuleMockMixin): ret = {"net.ipv4.ip_forward": "1"} mock_cmd = MagicMock(return_value=cmd) with patch.dict(linux_sysctl.__salt__, {"cmd.run_all": mock_cmd}): - self.assertEqual(linux_sysctl.assign("net.ipv4.ip_forward", 1), ret) + assert linux_sysctl.assign("net.ipv4.ip_forward", 1) == ret .ft P .fi .UNINDENT @@ -451200,11 +454643,7 @@ The primary rule of git management in SaltStack is to make life easy on contributors and developers to send in code. Simplicity is always a goal! .SS New Code Entry .sp -All new SaltStack code should be submitted against either the \fBdevelop\fP branch -or a point release branch, depending on the nature of the submission. Please see -the Which Salt Branch? section of Salt\(aqs -Contributing documentation or the Release Branching -section below for more information. +All new SaltStack code should be submitted against \fBmaster\fP\&. .SS Release Branching .sp SaltStack maintains two types of releases, \fBFeature Releases\fP and @@ -451216,7 +454655,7 @@ and 2015.8.0 \-> 2015.8.1 signifies a point release. .sp Each feature release is maintained in a dedicated git branch derived from the last applicable release commit on develop. All file changes relevant to the -feature release will be completed in the develop branch prior to the creation +feature release will be completed in the \fBmaster\fP branch prior to the creation of the feature release branch. The feature release branch will be named after the relevant numbers to the feature release, which constitute the first two numbers. This means that the release branch for the 2015.8.0 series is named @@ -451228,7 +454667,7 @@ A feature release branch is created with the following command: .sp .nf .ft C -# git checkout \-b 2015.8 # From the develop branch +# git checkout \-b 2015.8 # From the master branch # git push origin 2015.8 .ft P .fi @@ -451236,29 +454675,8 @@ A feature release branch is created with the following command: .UNINDENT .SS Point Releases .sp -Each point release is derived from its parent release branch. Constructing point -releases is a critical aspect of Salt development and is managed by members of -the core development team. Point releases comprise bug and security fixes. Bug -fixes can be made against a point release branch in one of two ways: the bug -fix can be submitted directly against the point release branch, or an attempt -can be made to back\-port the fix to the point release branch. -.sp -Bug fixes should be made against the earliest supported release branch on which -the bug is present. The Salt development team regularly merges older point -release branches forward into newer point release branches. That way, the bug -fixes that are submitted to older release branches can cascade up through all -related release branches. -.sp -For more information, please see the Which Salt Branch? -section of Salt\(aqs Contributing documentation. -.sp -Generally point releases are made every 2 months or if there is a security fix -they can be made sooner. -.sp -The point release is designated by branching (ex 2019.2.1) and then tagging (v2019.2.1) -from that newly created release branch when its determined the release is stable. -From the tag point a new source tarball is generated and published to PyPI, -and a release announcement is made. +As documented in \fI\%SEP 14\fP, +point releases should be rare. .SS Salt Conventions .SS Writing Salt Documentation .sp @@ -451416,7 +454834,7 @@ Edit the file for the module type: .IP 2. 3 Add the new module to the alphebetized list. .IP 3. 3 -\fI\%Build the documentation\fP which will generate an \fB\&.rst\fP +Build the documentation which will generate an \fB\&.rst\fP file for the new module in the same directory as the \fBindex.rst\fP\&. .IP 4. 3 Commit the changes to \fBindex.rst\fP and the new \fB\&.rst\fP file and send a @@ -451566,75 +454984,6 @@ single minion. .fi .UNINDENT .UNINDENT -.SS Documentation Changes and Fixes -.sp -Documentation changes and fixes should be made against the earliest supported -release branch that the update applies to. The practice of updating a release -branch instead of making all documentation changes against Salt\(aqs main, default -branch, \fBmaster\fP, is necessary in order for the docs to be as up\-to\-date as -possible when the docs are built. -.sp -The workflow mentioned above is also in line with the recommendations outlined -in Salt\(aqs contributing page. You can read more about how to choose where -to submit documentation fixes by reading the which\-salt\-branch section. -.sp -For an explanation of how to submit changes against various branches, see the -github\-pull\-request section. Specifically, see the section describing -how to \fBCreate a new branch\fP and the steps that follow. -.SS Building the documentation -.INDENT 0.0 -.IP 1. 3 -Install Sphinx using a system package manager or pip. The package name is -often of the form \fBpython\-sphinx\fP\&. There are no other dependencies. -.IP 2. 3 -Build the documentation using the provided Makefile or \fB\&.bat\fP file on -Windows. -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -cd /path/to/salt/doc -make html -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 3. 3 -The generated documentation will be written to the \fBdoc/_build/\fP -directory. -.IP 4. 3 -A useful method of viewing the HTML documentation locally is to start -Python\(aqs built\-in HTTP server: -.sp -Python 3: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -cd /path/to/salt/doc/_build/html -python3 \-m http.server -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Python 2: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -cd /path/to/salt/doc/_build/html -python \-m SimpleHTTPServer -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Then pull up the documentation in a web browser at \fI\%http://localhost:8000/\fP\&. -.UNINDENT .SS Salt Formulas .sp Formulas are pre\-written Salt States. They are as open\-ended as Salt States @@ -453586,10 +456935,6 @@ Update win\-repo\-ng with new salt versions. .IP 20. 4 Announce release is live to irc, salt\-users, salt\-announce and release slack channel. .UNINDENT -.sp -For more information about the difference between the \fBmaster\fP branch and -bugfix release branches, please refer to the Which Salt Branch? section of Salt\(aqs Contributing -documentation. .SS Salt Coding Style .sp To make it easier to contribute and read Salt code, SaltStack has \fI\%adopted @@ -453601,46 +456946,32 @@ grounds to talk down to another member of the community (There are no grounds to treat others without respect, especially people working to improve Salt)! .SS Linting .sp -Most Salt style conventions are codified in Salt\(aqs \fB\&.testing.pylintrc\fP file. -Salt\(aqs pylint file has two dependencies: \fI\%pylint\fP and \fI\%saltpylint\fP\&. You can -install these dependencies with \fBpip\fP: +Most Salt style conventions are codified in Salt\(aqs \fB\&.pylintrc\fP file. +Salt\(aqs pylint file has two dependencies: \fI\%pylint\fP and \fI\%saltpylint\fP, however, linting should +be done using nox\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -pip install pylint -pip install saltpylint +nox \-e lint .ft P .fi .UNINDENT .UNINDENT .sp -The \fB\&.testing.pylintrc\fP file is found in the root of the Salt project and can -be passed as an argument to the \fI\%pylint\fP program as follows: +One can target either salt\(aqs source code or the test suite(different pylint rules apply): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -pylint \-\-rcfile=/path/to/salt/.testing.pylintrc salt/dir/to/lint +nox \-e lint\-salt +nox \-e lint\-tests .ft P .fi .UNINDENT .UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -There are two pylint files in the \fBsalt\fP directory. One is the -\fB\&.pylintrc\fP file and the other is the \fB\&.testing.pylintrc\fP file. The -tests that run in Jenkins against GitHub Pull Requests use -\fB\&.testing.pylintrc\fP\&. The \fBtesting.pylintrc\fP file is a little less -strict than the \fB\&.pylintrc\fP and is used to make it easier for contributors -to submit changes. The \fB\&.pylintrc\fP file can be used for linting, but the -\fBtesting.pylintrc\fP is the source of truth when submitting pull requests. -.UNINDENT -.UNINDENT .SS Variables .sp Variables should be a minimum of three characters and should provide an @@ -453656,22 +456987,35 @@ to them to pad them to three characters. .SS Formatting Strings .sp All strings which require formatting should use the \fI\&.format\fP string method: +.sp +Please do NOT use printf formatting, unless it\(aqs a log message. +.sp +Good: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C data = "some text" -more = "{0} and then some".format(data) +more = "{} and then some".format(data) +log.debug("%s and then some", data) .ft P .fi .UNINDENT .UNINDENT .sp -Make sure to use indices or identifiers in the format brackets, since empty -brackets are not supported by python 2.6. +Bad: +.INDENT 0.0 +.INDENT 3.5 .sp -Please do NOT use printf formatting. +.nf +.ft C +data = "some text" +log.debug("{} and then some".format(data)) +.ft P +.fi +.UNINDENT +.UNINDENT .SS Docstring Conventions .sp When adding a new function or state, where possible try to use a @@ -454644,7 +457988,7 @@ information about the version numbering scheme. .sp Release Candidate .SS Previous Releases -.SS Salt 3002.2 Release Notes \- Codename Magnesium +.SS Salt 3002 Release Notes \- Codename Magnesium .SS New Features .SS Network Teaming Support Added (RHEL/CentOS) .sp @@ -454949,9 +458293,9 @@ Added features config option for feature flags. Added a feature flag This flag will be depricated in the Phosphorus release when this functionality becomes the default. (#58652) .UNINDENT -.SS Salt 3002.2.1 Release Notes +.SS Salt 3002.1 Release Notes .sp -Version 3002.2.1 is a CVE fix release for 3002.2\&. +Version 3002.1 is a CVE fix release for 3002\&. .SS Fixed .INDENT 0.0 .IP \(bu 2 @@ -454964,6 +458308,44 @@ Prior to this change eauth was not properly validated when calling Salt ssh via the salt\-api. Any value for \(aqeauth\(aq or \(aqtoken\(aq would allow a user to bypass authentication and make calls to Salt ssh. (CVE\-2020\-25592) .UNINDENT +.SS Salt "3003" Release Notes +.sp +Version "3003" is a bugfix release for 3002\&. +.SS Fixed +.INDENT 0.0 +.IP \(bu 2 +Change dict check to isinstance instead of type() for key_values in file.keyvalue. (#57758) +.IP \(bu 2 +Fail when func_ret is False when using the new module.run syntax. (#57768) +.IP \(bu 2 +Fix comparison of certificate values (#58296) +.IP \(bu 2 +When using ssh_pre_flight if there is a failure, fail on retcode not stderr. (#58439) +.IP \(bu 2 +Fix use of unauthd cached vmware service instance (#58691) +.IP \(bu 2 +Removing use of undefined varilable in utils/slack.py. (#58753) +.IP \(bu 2 +Restored the ability to specify the amount of extents for a Logical +Volume as a percentage. (#58759) +.IP \(bu 2 +Ensuring that the version check function is run a second time in all the user related functions incase the user being managed is the connection user and the password has been updated. (#58773) +.IP \(bu 2 +Allow bytes in gpg renderer (#58794) +.IP \(bu 2 +Fix issue where win_wua module fails to load when BITS is set to Manual (#58848) +.IP \(bu 2 +Ensure that elasticsearch.index_exists is available before loading the elasticsearch returner. (#58851) +.IP \(bu 2 +Log a different object when debugging if we\(aqre using disk cache vs memory cache. The disk cache pillar class has the dict object but the cache pillar object which is used with the memory cache does not include a _dict obeject because it is a dict already. (#58861) +.IP \(bu 2 +Do not generate grains for every job run on Windows minions. This makes Windows +conform more to the way posix OSes work today. (#58904) +.IP \(bu 2 +Fixes salt\-ssh authentication when using tty (#58922) +.IP \(bu 2 +Revert LazyLoader finalizer. Removed the weakref.finalizer code. On some occasions, the finalized would run when trying to load a new module, firing a race condition. (#58947) +.UNINDENT .SS Salt 3001 Release Notes \- Codename Sodium .SS Python 2 Dropped .sp @@ -455289,6 +458671,14 @@ Prior to this change eauth was not properly validated when calling Salt ssh via the salt\-api. Any value for \(aqeauth\(aq or \(aqtoken\(aq would allow a user to bypass authentication and make calls to Salt ssh. (CVE\-2020\-25592) .UNINDENT +.SS Salt 3001.4 Release Notes +.sp +Version 3001.4 is a bugfix release for 3001\&. +.SS Fixed +.INDENT 0.0 +.IP \(bu 2 +Fixes salt\-ssh authentication when using tty (#58922) +.UNINDENT .SS Salt 3000 Release Notes \- Codename Neon .SS Security Advisory .sp @@ -457344,6 +460734,14 @@ Prior to this change eauth was not properly validated when calling Salt ssh via the salt\-api. Any value for \(aqeauth\(aq or \(aqtoken\(aq would allow a user to bypass authentication and make calls to Salt ssh. (CVE\-2020\-25592) .UNINDENT +.SS Salt 3000.6 Release Notes +.sp +Version 3000.6 is a bugfix release for 3000\&. +.SS Fixed +.INDENT 0.0 +.IP \(bu 2 +Fixes salt\-ssh authentication when using tty (#58922) +.UNINDENT .SS Salt 2019.2.0 Release Notes \- Codename Fluorine .SS Python 2.7 Deprecation .sp @@ -467131,6 +470529,14 @@ Prior to this change eauth was not properly validated when calling Salt ssh via the salt\-api. Any value for \(aqeauth\(aq or \(aqtoken\(aq would allow a user to bypass authentication and make calls to Salt ssh. (CVE\-2020\-25592) .UNINDENT +.SS Salt 2019.2.8 Release Notes +.sp +Version 2019.2.8 is a bugfix release for 2019.2.0\&. +.SS Fixed +.INDENT 0.0 +.IP \(bu 2 +Fixes salt\-ssh authentication when using tty (#58922) +.UNINDENT .SS Salt 2018.3.0 Release Notes \- Codename Oxygen .sp \fBWARNING:\fP @@ -489562,15 +492968,15 @@ ab1b099730 Merge pull request \fI\%#42948\fP from Ch3LL/2017.7.0_follow_up .UNINDENT .UNINDENT .IP \(bu 2 -\fBISSUE\fP \fI\%#42989\fP: (\fI\%blbradley\fP) GitFS GitPython performance regression in 2017.7.1 (refs: \fI\%#43002.2\fP) +\fBISSUE\fP \fI\%#42989\fP: (\fI\%blbradley\fP) GitFS GitPython performance regression in 2017.7.1 (refs: \fI\%#43002\fP) .IP \(bu 2 -\fBPR\fP \fI\%#43034\fP: (\fI\%rallytime\fP) Back\-port \fI\%#43002.2\fP to 2017.7 +\fBPR\fP \fI\%#43034\fP: (\fI\%rallytime\fP) Back\-port \fI\%#43002\fP to 2017.7 @ \fI2017\-08\-17 23:18:16 UTC\fP .INDENT 2.0 .IP \(bu 2 -\fBPR\fP \fI\%#43002.2\fP: (\fI\%the\-glu\fP) Try to fix \fI\%#42989\fP (refs: \fI\%#43034\fP) +\fBPR\fP \fI\%#43002\fP: (\fI\%the\-glu\fP) Try to fix \fI\%#42989\fP (refs: \fI\%#43034\fP) .IP \(bu 2 -bcbb973a71 Merge pull request \fI\%#43034\fP from rallytime/bp\-43002.2 +bcbb973a71 Merge pull request \fI\%#43034\fP from rallytime/bp\-43002 .IP \(bu 2 350c0767dc Try to fix \fI\%#42989\fP by doing sslVerify and refspecs for origin remote only if there is no remotes .UNINDENT @@ -490704,7 +494110,7 @@ ab21bd9b5b Sync cloud modules when saltutil.sync_all is run @ \fI2017\-07\-27 22:32:07 UTC\fP .INDENT 2.0 .IP \(bu 2 -e2dd443002.2 Merge pull request \fI\%#42601\fP from rallytime/merge\-2017.7 +e2dd443002 Merge pull request \fI\%#42601\fP from rallytime/merge\-2017.7 .IP \(bu 2 36a1bcf8c5 Merge branch \(aq2016.11\(aq into \(aq2017.7\(aq .INDENT 2.0 @@ -506448,7 +509854,7 @@ abe4eb3b98 fix encoding problem aws responses .IP \(bu 2 1001987f64 Catch possible exception from lsb_release (\fI\%#37962\fP) .IP \(bu 2 -33002.21cd8b Handle empty tokens safely (\fI\%#37961\fP) +330021cd8b Handle empty tokens safely (\fI\%#37961\fP) .IP \(bu 2 ea46639ce7 Merge pull request \fI\%#37272\fP from vutny/fix\-getting\-default\-logging\-opts .INDENT 2.0 @@ -534137,7 +537543,7 @@ a6c1d0b408 Fixed a bug where logging_command wasnt set as a key in a couple spot .IP \(bu 2 8bb7cb7ff4 Use correct indexes .IP \(bu 2 -c3483002.2b0 [2015.8] Fixup salt\-cloud logging +c3483002b0 [2015.8] Fixup salt\-cloud logging .UNINDENT .IP \(bu 2 \fBPR\fP \fI\%#27332\fP: (\fI\%terminalmage\fP) Adjust dockerng/dockerio docstrings @@ -545085,7 +548491,7 @@ f7e58a241c Merge branch \(aq2015.5\(aq into \(aq2015.8\(aq 1cb1c2da07 Fixes wrong function scope .UNINDENT .IP \(bu 2 -1c6c9b1a06 Merge pull request \fI\%#3002.25\fP from jtand/boto_tests +1c6c9b1a06 Merge pull request \fI\%#30025\fP from jtand/boto_tests .INDENT 2.0 .IP \(bu 2 e706642152 Skipping some Boto tests until resolved moto issue @@ -545257,11 +548663,11 @@ a257249789 Add versionadded to SSH Port docs 0bb83e51aa Updated Cloud msic section. .UNINDENT .IP \(bu 2 -\fBPR\fP \fI\%#3002.29\fP: (\fI\%terminalmage\fP) git.latest: Fix handling of nonexistant branches +\fBPR\fP \fI\%#30029\fP: (\fI\%terminalmage\fP) git.latest: Fix handling of nonexistant branches @ \fI2015\-12\-28 19:39:29 UTC\fP .INDENT 2.0 .IP \(bu 2 -a5f7d9c2fc Merge pull request \fI\%#3002.29\fP from terminalmage/git.latest\-nonexistant\-branch +a5f7d9c2fc Merge pull request \fI\%#30029\fP from terminalmage/git.latest\-nonexistant\-branch .IP \(bu 2 0b95894c9f git.latest: Fix handling of nonexistant branches .UNINDENT @@ -545284,11 +548690,11 @@ e7fe24dc64 Merge pull request \fI\%#30016\fP from alprs/fix\-gen_locale_normaliz 5799729aee locale module: don\(aqt escape the slash in n .UNINDENT .IP \(bu 2 -\fBPR\fP \fI\%#3002.22\fP: (\fI\%gqgunhed\fP) Two minor typos fixed +\fBPR\fP \fI\%#30022\fP: (\fI\%gqgunhed\fP) Two minor typos fixed @ \fI2015\-12\-28 15:22:24 UTC\fP .INDENT 2.0 .IP \(bu 2 -b871ce5310 Merge pull request \fI\%#3002.22\fP from gqgunhed/winrepo_typo +b871ce5310 Merge pull request \fI\%#30022\fP from gqgunhed/winrepo_typo .IP \(bu 2 a052ff016e fixed minor typos and a :ref: link .IP \(bu 2 @@ -545297,11 +548703,11 @@ e47db1a076 Merge remote\-tracking branch \(aqrefs/remotes/saltstack/2015.8\(aq i 0c4c8b9b5c Merge remote\-tracking branch \(aqrefs/remotes/saltstack/2015.8\(aq into 2015.8 .UNINDENT .IP \(bu 2 -\fBPR\fP \fI\%#3002.26\fP: (\fI\%anlutro\fP) states.at: fix wrong variable being used +\fBPR\fP \fI\%#30026\fP: (\fI\%anlutro\fP) states.at: fix wrong variable being used @ \fI2015\-12\-28 15:21:23 UTC\fP .INDENT 2.0 .IP \(bu 2 -4b8ac20d45 Merge pull request \fI\%#3002.26\fP from alprs/fix\-at_without_tag_job +4b8ac20d45 Merge pull request \fI\%#30026\fP from alprs/fix\-at_without_tag_job .IP \(bu 2 c0fe9c09bd states.at: fix wrong variable being used .UNINDENT @@ -551509,9 +554915,9 @@ b869a92eea Change Zypper calls to a single point .IP \(bu 2 \fBPR\fP \fI\%#33017\fP: (\fI\%rallytime\fP) Update the docs for saltutil.find_job to be more clear/accurate .IP \(bu 2 -\fBPR\fP \fI\%#33031\fP: (\fI\%rallytime\fP) Back\-port \fI\%#33002.2\fP to 2015.8 +\fBPR\fP \fI\%#33031\fP: (\fI\%rallytime\fP) Back\-port \fI\%#33002\fP to 2015.8 .IP \(bu 2 -\fBPR\fP \fI\%#33002.2\fP: (\fI\%whiteinge\fP) Add saltenv to the cmd.script state function (refs: \fI\%#33031\fP) +\fBPR\fP \fI\%#33002\fP: (\fI\%whiteinge\fP) Add saltenv to the cmd.script state function (refs: \fI\%#33031\fP) .IP \(bu 2 \fBPR\fP \fI\%#33021\fP: (\fI\%UtahDave\fP) Fix syndic regression (refs: \fI\%#33044\fP) .UNINDENT @@ -567064,13 +570470,13 @@ cfbfd58afe Noting that file_roots and "state tree" should both be avoided, becau 1cb1c2da07 Fixes wrong function scope .UNINDENT .IP \(bu 2 -\fBPR\fP \fI\%#3002.25\fP: (\fI\%justinta\fP) Skipping some Boto tests until resolved moto issue +\fBPR\fP \fI\%#30025\fP: (\fI\%justinta\fP) Skipping some Boto tests until resolved moto issue @ \fI2015\-12\-28 15:21:45 UTC\fP .INDENT 2.0 .IP \(bu 2 -\fBPR\fP \fI\%#29725\fP: (\fI\%cachedout\fP) Disable some boto tests per resolution of moto issue (refs: \fI\%#3002.25\fP) +\fBPR\fP \fI\%#29725\fP: (\fI\%cachedout\fP) Disable some boto tests per resolution of moto issue (refs: \fI\%#30025\fP) .IP \(bu 2 -1c6c9b1a06 Merge pull request \fI\%#3002.25\fP from jtand/boto_tests +1c6c9b1a06 Merge pull request \fI\%#30025\fP from jtand/boto_tests .IP \(bu 2 e706642152 Skipping some Boto tests until resolved moto issue .UNINDENT @@ -576689,6 +580095,31 @@ runners and commands like salt\-key. Tests have been added to test the aspects of the client APIs and ensure that the client calls work, and that they manage passed data, in a desirable way. .SS Upcoming Release +.SS Salt 3003 Release Notes \- Codename Aluminium +.sp +Salt 3003 is an \fIunreleased\fP upcoming feature release. +.SS Execution Module Changes +.SS Changed +.INDENT 0.0 +.IP \(bu 2 +The \fBpkg\fP module now supports \fBtdnf\fP used by +VMWare Photon OS. As part of this change, \fBVMWare Photon OS\fP\(aqs +\fBos_family\fP grain will now resolve as \fBRedHat\fP\&. This may require changes +to existing uses of \fBgrains.filter_by\fP +.IP \(bu 2 +The \fBsalt\-run\fP CLI now accepts \fB\-\-jid\fP which allows scripting against it. +.UNINDENT +.SS Salt Cloud +.SS Added +.INDENT 0.0 +.IP \(bu 2 +Firewall groups support to Vultr Salt Cloud provider +.UNINDENT +.SS Fixed +.INDENT 0.0 +.IP \(bu 2 +The Google Cloud Engine salt\-cloud provider now requires \fIapache\-libcloud>=2.5.0\fP\&. Service account authentication is broken on older versions. +.UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 diff --git a/doc/man/spm.1 b/doc/man/spm.1 index 15029351ef4..dd49e470437 100644 --- a/doc/man/spm.1 +++ b/doc/man/spm.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SPM" "1" "Nov 14, 2020" "3002.2" "Salt" +.TH "SPM" "1" "Feb 23, 2021" "3003" "Salt" .SH NAME spm \- Salt Package Manager Command .