From 701f47a658bfcb25dc8aec2576bfac4a6a189d32 Mon Sep 17 00:00:00 2001 From: Jacob Hammons Date: Tue, 1 Sep 2015 17:09:35 -0600 Subject: [PATCH] Added rst source for salt-proxy man page, added build and copy lines for this man page to doc/conf.py and setup.py Added salt-proxy release notes topic Added note to pip state for Refs #21845 Regenerated and versioned man pages --- doc/conf.py | 1 + doc/man/salt-api.1 | 2 +- doc/man/salt-call.1 | 2 +- doc/man/salt-cloud.1 | 2 +- doc/man/salt-cp.1 | 2 +- doc/man/salt-key.1 | 2 +- doc/man/salt-master.1 | 2 +- doc/man/salt-minion.1 | 2 +- doc/man/salt-proxy.1 | 19 +- doc/man/salt-run.1 | 2 +- doc/man/salt-ssh.1 | 2 +- doc/man/salt-syndic.1 | 2 +- doc/man/salt-unity.1 | 2 +- doc/man/salt.1 | 2 +- doc/man/salt.7 | 57611 +++++++++++----- doc/man/spm.1 | 2 +- doc/ref/cli/index.rst | 6 + doc/ref/cli/salt-proxy.rst | 73 + doc/topics/proxyminion/index.rst | 12 +- doc/topics/releases/2015.8.0.rst | 5 + .../releases/includes/proxy-2015.8.0.rst | 110 + salt/states/pip_state.py | 6 + setup.py | 2 + 23 files changed, 40155 insertions(+), 17716 deletions(-) create mode 100644 doc/ref/cli/salt-proxy.rst create mode 100644 doc/topics/releases/includes/proxy-2015.8.0.rst diff --git a/doc/conf.py b/doc/conf.py index e2d95c00018..332f8177338 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -386,6 +386,7 @@ man_pages = [ ('ref/cli/salt-key', 'salt-key', 'salt-key Documentation', authors, 1), ('ref/cli/salt-cp', 'salt-cp', 'salt-cp Documentation', authors, 1), ('ref/cli/salt-call', 'salt-call', 'salt-call Documentation', authors, 1), + ('ref/cli/salt-proxy', 'salt-proxy', 'salt-proxy Documentation', authors, 1), ('ref/cli/salt-syndic', 'salt-syndic', 'salt-syndic Documentation', authors, 1), ('ref/cli/salt-run', 'salt-run', 'salt-run Documentation', authors, 1), ('ref/cli/salt-ssh', 'salt-ssh', 'salt-ssh Documentation', authors, 1), diff --git a/doc/man/salt-api.1 b/doc/man/salt-api.1 index 150b29b35a1..385dab4d92e 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-API" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-api \- salt-api Command . diff --git a/doc/man/salt-call.1 b/doc/man/salt-call.1 index 6040f5ef2ca..22f09ee6a85 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-CALL" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-call \- salt-call Documentation . diff --git a/doc/man/salt-cloud.1 b/doc/man/salt-cloud.1 index 7553711481e..46b9e0e281b 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-CLOUD" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-cloud \- Salt Cloud Command . diff --git a/doc/man/salt-cp.1 b/doc/man/salt-cp.1 index f7cd16cf098..44af02489df 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-CP" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-cp \- salt-cp Documentation . diff --git a/doc/man/salt-key.1 b/doc/man/salt-key.1 index 67e077a700b..29849369f96 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-KEY" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-key \- salt-key Documentation . diff --git a/doc/man/salt-master.1 b/doc/man/salt-master.1 index fe3d700544d..6d2cf35fe9c 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-MASTER" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-master \- salt-master Documentation . diff --git a/doc/man/salt-minion.1 b/doc/man/salt-minion.1 index 10d82f71a37..bc7b66716ae 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-MINION" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-minion \- salt-minion Documentation . diff --git a/doc/man/salt-proxy.1 b/doc/man/salt-proxy.1 index 146d93aa1b4..730c7b0d25b 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-PROXY" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-proxy \- salt-proxy Documentation . @@ -31,8 +31,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .sp -The Salt Proxy minion daemon, receives commands from a remote Salt master -and communicates with devices unable to run a full minion. +Receives commands from a Salt master and proxies these commands to +devices that are unable to run a full minion. .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 @@ -46,8 +46,9 @@ salt\-proxy [ options ] .UNINDENT .SH DESCRIPTION .sp -The Salt proxy minion receives commands from the central Salt master, transmits apppropriate commands - to devices unable to run a minion, and replies with the results of said commands. +The Salt proxy minion receives commands from a Salt master, transmits +appropriate commands to devices that are unable to run a minion, and replies +with the results of said commands. .SH OPTIONS .INDENT 0.0 .TP @@ -72,9 +73,9 @@ Show the help message and exit .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir -The location of the Salt configuration directory. This directory contains -the configuration files for Salt master and minions. The default location -on most systems is \fB/etc/salt\fP\&. +The location of the Salt configuration directory. This directory +contains the configuration files for Salt master and minions. +The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -89,7 +90,7 @@ Run salt\-proxy as a daemon .INDENT 0.0 .TP .B \-\-pid\-file PIDFILE -Specify the location of the pidfile. Default: /var/run/salt\-proxy-\&.pid +Specify the location of the pidfile. Default: \fB/var/run/salt\-proxy\-.pid\fP .UNINDENT .SS Logging Options .sp diff --git a/doc/man/salt-run.1 b/doc/man/salt-run.1 index 915c856af14..bd6c0e160f1 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-RUN" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-run \- salt-run Documentation . diff --git a/doc/man/salt-ssh.1 b/doc/man/salt-ssh.1 index 618304b5692..16c2325e747 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-SSH" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-ssh \- salt-ssh Documentation . diff --git a/doc/man/salt-syndic.1 b/doc/man/salt-syndic.1 index 90523f15455..67ec4960711 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-SYNDIC" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-syndic \- salt-syndic Documentation . diff --git a/doc/man/salt-unity.1 b/doc/man/salt-unity.1 index faa941b48df..338410a2517 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" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT-UNITY" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt-unity \- salt-unity Command . diff --git a/doc/man/salt.1 b/doc/man/salt.1 index 397dc2c32b9..58295f84c4b 100644 --- a/doc/man/salt.1 +++ b/doc/man/salt.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT" "1" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT" "1" "September 01, 2015" "2015.8.0" "Salt" .SH NAME salt \- salt . diff --git a/doc/man/salt.7 b/doc/man/salt.7 index 49e69465d63..65f40eeb8eb 100644 --- a/doc/man/salt.7 +++ b/doc/man/salt.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SALT" "7" "July 29, 2015" "2015.8.0rc2-13-g733b842" "Salt" +.TH "SALT" "7" "September 01, 2015" "2015.8.0rc3-168-g47bc60a" "Salt" .SH NAME salt \- Salt Documentation . @@ -525,6 +525,45 @@ yum \-\-enablerepo=updates\-testing install salt\-minion .fi .UNINDENT .UNINDENT +.SS Installation Using pip +.sp +Since Salt is on \fI\%PyPI\fP, it can be installed using pip, though most users +prefer to install using a package manager. +.sp +Installing from pip has a few additional requirements: +.INDENT 0.0 +.IP \(bu 2 +Install the group \(aqDevelopment Tools\(aq, \fBdnf groupinstall \(aqDevelopment Tools\(aq\fP +.IP \(bu 2 +Install the \(aqzeromq\-devel\(aq package if it fails on linking against that +afterwards as well. +.UNINDENT +.sp +A pip install does not make the init scripts or the /etc/salt directory, and you +will need to provide your own systemd service unit. +.sp +Installation from pip: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +pip install salt +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +If installing from pip (or from source using \fBsetup.py install\fP), be +advised that the \fByum\-utils\fP package is needed for Salt to manage +packages. Also, if the Python dependencies are not already installed, then +you will need additional libraries/tools installed to build some of them. +More information on this can be found \fIhere\fP\&. +.UNINDENT +.UNINDENT .SS Post\-installation tasks .sp \fBMaster\fP @@ -920,32 +959,6 @@ sudo salt\-master \-\-log\-level=all .sp Now go to the \fBConfiguring Salt\fP page. .SS RHEL / CentOS / Scientific Linux / Amazon Linux / Oracle Linux -.SS Installation Using pip -.sp -Since Salt is on \fI\%PyPI\fP, it can be installed using pip, though most users -prefer to install using RPMs (which can be installed from \fI\%EPEL\fP). -Installation from pip is easy: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -pip install salt -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -If installing from pip (or from source using \fBsetup.py install\fP), be -advised that the \fByum\-utils\fP package is needed for Salt to manage -packages. Also, if the Python dependencies are not already installed, then -you will need additional libraries/tools installed to build some of them. -More information on this can be found \fIhere\fP\&. -.UNINDENT -.UNINDENT .SS Installation from Repository .SS RHEL/CentOS 5 .sp @@ -1025,6 +1038,45 @@ yum \-\-enablerepo=epel\-testing install salt\-minion .fi .UNINDENT .UNINDENT +.SS Installation Using pip +.sp +Since Salt is on \fI\%PyPI\fP, it can be installed using pip, though most users +prefer to install using RPMs (which can be installed from \fI\%EPEL\fP). +.sp +Installing from pip has a few additional requirements: +.INDENT 0.0 +.IP \(bu 2 +Install the group \(aqDevelopment Tools\(aq, \fByum groupinstall \(aqDevelopment Tools\(aq\fP +.IP \(bu 2 +Install the \(aqzeromq\-devel\(aq package if it fails on linking against that +afterwards as well. +.UNINDENT +.sp +A pip install does not make the init scripts or the /etc/salt directory, and you +will need to provide your own systemd service unit. +.sp +Installation from pip: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +pip install salt +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +If installing from pip (or from source using \fBsetup.py install\fP), be +advised that the \fByum\-utils\fP package is needed for Salt to manage +packages. Also, if the Python dependencies are not already installed, then +you will need additional libraries/tools installed to build some of them. +More information on this can be found \fIhere\fP\&. +.UNINDENT +.UNINDENT .SS ZeroMQ 4 .sp We recommend using ZeroMQ 4 where available. SaltStack provides ZeroMQ 4.0.4 @@ -1495,214 +1547,18 @@ of the Salt States currently work on Windows, as well. .sp Salt Minion Windows installers can be found here. The output of \fImd5sum \fP should match the contents of the corresponding md5 file. -.INDENT 0.0 -.INDENT 3.5 -.IP "Download here" -.INDENT 0.0 -.IP \(bu 2 -2015.5.2 -.IP \(bu 2 -\fI\%Salt\-Minion\-2015.5.2\-x86\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2015.5.2\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2015.5.1\-3 -.IP \(bu 2 -\fI\%Salt\-Minion\-2015.5.1\-3\-x86\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2015.5.1\-3\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2015.5.0\-2 -.IP \(bu 2 -\fI\%Salt\-Minion\-2015.5.0\-2\-x86\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2015.5.0\-2\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.7.5\-2 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.7.5\-2\-x86\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.7.5\-2\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.7.4 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.7.4\-x86\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.7.4\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.7.2 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.7.2\-x86\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.7.2\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.7.1 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.7.1\-x86\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.7.1\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.7.0 -.IP \(bu 2 -Salt\-Minion\-2014.7.0\-1\-win32\-Setup.exe | md5 -.IP \(bu 2 -.INDENT 2.0 -.TP -.B Salt\-Minion\-2014.7.0\-AMD64\-Setup.exe | md5 -. -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -The 2014.7.0 installers have been removed because of a regression. Please use the 2014.7.1 release instead. -.UNINDENT -.UNINDENT -.UNINDENT -.IP \(bu 2 -2014.1.13 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.13\-x86\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.13\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.1.11 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.11\-win32\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.11\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.1.10 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.10\-win32\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.10\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.1.7 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.7\-win32\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.7\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.1.5 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.5\-win32\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.5\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.1.4 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.4\-win32\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.4\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.1.3\-1 (packaging bugfix) -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.3\-1\-win32\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.3\-1\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.1.3 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.3\-win32\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.3\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.1.1 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.1\-win32\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.1\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -2014.1.0 -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.0\-win32\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -\fI\%Salt\-Minion\-2014.1.0\-AMD64\-Setup.exe\fP | \fI\%md5\fP -.IP \(bu 2 -0.17.5\-2 (bugfix release) -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.5\-2\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.5\-2\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.17.5 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.5\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.5\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.17.4 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.4\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.4\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.17.2 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.2\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.2\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.17.1.1 \- Windows Installer bugfix release -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1.1\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1.1\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.17.1 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.17.0 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.0\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.0\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.16.3 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.3\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.3\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.16.2 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.2\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.2\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.16.0 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.0\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.0\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.15.3 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.15.3\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.15.3\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.14.1 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.14.1\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.14.1\-AMD64\-Setup.exe\fP -.IP \(bu 2 -0.14.0 -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.14.0\-win32\-Setup.exe\fP -.IP \(bu 2 -\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.14.0\-AMD64\-Setup.exe\fP -.UNINDENT -.UNINDENT -.UNINDENT +.sp +\fBLatest stable build from the selected branch\fP: + +.sp +\fI\%Earlier builds from supported branches\fP +.sp +\fI\%Archived builds from unsupported branches\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -The executables above will install dependencies that the Salt minion +The installation executable installs dependencies that the Salt minion requires. .UNINDENT .UNINDENT @@ -4035,7 +3891,7 @@ So the httpd.conf is just a file in the apache directory, and is referenced directly. .INDENT 0.0 .INDENT 3.5 -.IP "Do not use dots in SLS file names" +.IP "Do not use dots in SLS file names or their directories" .sp The initial implementation of \fBtop.sls\fP and \fIinclude\-declaration\fP followed the python import model where a slash @@ -4043,6 +3899,10 @@ is represented as a period. This means that a SLS file with a period in the name ( besides the suffix period) can not be referenced. For example, webserver_1.0.sls is not referenceable because webserver_1.0 would refer to the directory/file webserver_1/0.sls +.sp +The same applies for any subdirecortories, this is especially \(aqtricky\(aq when +git repos are created. Another command that typically can\(aqt render it\(aqs +output is \fB\(gastate.show_sls\(ga\fP of a file in a path that contains a dot. .UNINDENT .UNINDENT .sp @@ -6522,10 +6382,14 @@ salt\-key \-A \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -Keys should be verified! The secure thing to do before accepting a key is -to run \fBsalt\-key \-f minion\-id\fP to print the fingerprint of the minion\(aqs -public key. This fingerprint can then be compared against the fingerprint -generated on the minion. +Keys should be verified! Print the master key fingerprint by running \fBsalt\-key \-F master\fP +on the Salt master. Copy the \fBmaster.pub\fP fingerprint from the Local Keys section, +and then set this value as the \fBmaster_finger\fP in the minion configuration +file. Restart the Salt minion. +.sp +On the master, run \fBsalt\-key \-f minion\-id\fP to print the fingerprint of the +minion\(aqs public key that was received by the master. On the minion, run +\fBsalt\-call key.finger \-\-local\fP to print the fingerprint of the minion key. .sp On the master: .INDENT 0.0 @@ -9491,57 +9355,16 @@ Similarly, the tag name \fBsalt/fileserver/gitfs/update\fP can be replaced by anything, so long as the usage is consistent. .SS Using Git as an External Pillar Source .sp -Git repositories can also be used to provide \fBPillar\fP data, using the \fBExternal Pillar\fP system. Note that this is different -from gitfs, and is not yet at feature parity with it. +The git external pillar (a.k.a. git_pillar) has been rewritten for the 2015.8.0 +release. This rewrite brings with it \fI\%pygit2\fP support (allowing for access to +authenticated repositories), as well as more granular support for per\-remote +configuration. .sp -To define a git external pillar, add a section like the following to the salt -master config file: -.INDENT 0.0 -.INDENT 3.5 +To make use of the new features, changes to the git ext_pillar configuration +must be made. The new configuration schema is detailed \fIhere\fP\&. .sp -.nf -.ft C -ext_pillar: - \- git: [root=] -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Changed in version 2014.7.0: The optional \fBroot\fP parameter was added - -.sp -The \fB\fP param is the branch containing the pillar SLS tree. The -\fB\fP param is the URI for the repository. To add the -\fBmaster\fP branch of the specified repo as an external pillar source: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -ext_pillar: - \- git: master https://domain.com/pillar.git -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Use the \fBroot\fP parameter to use pillars from a subdirectory of a git -repository: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -ext_pillar: - \- git: master https://domain.com/pillar.git root=subdirectory -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -More information on the git external pillar can be found in the -\fBsalt.pillar.get_pillar docs\fP\&. +For Salt releases before 2015.8.0, click \fIhere\fP +for documentation. .SS Why aren\(aqt my custom modules/states/etc. syncing to my Minions? .sp In versions 0.16.3 and older, when using the \fBgit fileserver backend\fP, certain versions of GitPython may generate errors @@ -13115,12 +12938,12 @@ web6: .UNINDENT .UNINDENT .SS Using Salt at scale -.SS Using salt at scale +.SS Using Salt at scale .sp The focus of this tutorial will be building a Salt infrastructure for handling large numbers of minions. This will include tuning, topology, and best practices. .sp -For how to install the saltmaster please +For how to install the Salt Master please go here: \fI\%Installing saltstack\fP .sp \fBNOTE:\fP @@ -13133,12 +12956,12 @@ When used with minions, the term \(aqmany\(aq refers to at least a thousand and \(aqa few\(aq always means 500. .sp For simplicity reasons, this tutorial will default to the standard ports -used by salt. +used by Salt. .UNINDENT .UNINDENT .SS The Master .sp -The most common problems on the salt\-master are: +The most common problems on the Salt Master are: .INDENT 0.0 .IP 1. 3 too many minions authing at once @@ -13153,7 +12976,7 @@ too few resources (CPU/HDD) .UNINDENT .sp The first three are all "thundering herd" problems. To mitigate these issues -we must configure the minions to back\-off appropriately when the master is +we must configure the minions to back\-off appropriately when the Master is under heavy load. .sp The fourth is caused by masters with little hardware resources in combination @@ -13162,9 +12985,9 @@ with a possible bug in ZeroMQ. At least thats what it looks like till today \fI\%Issue 5948\fP, \fI\%Mail thread\fP) .sp -To fully understand each problem, it is important to understand, how salt works. +To fully understand each problem, it is important to understand, how Salt works. .sp -Very briefly, the saltmaster offers two services to the minions. +Very briefly, the Salt Master offers two services to the minions. .INDENT 0.0 .IP \(bu 2 a job publisher on port 4505 @@ -13173,33 +12996,39 @@ an open port 4506 to receive the minions returns .UNINDENT .sp All minions are always connected to the publisher on port 4505 and only connect -to the open return port 4506 if necessary. On an idle master, there will only +to the open return port 4506 if necessary. On an idle Master, there will only be connections on port 4505. .SS Too many minions authing .sp -When the minion service is first started up, it will connect to its master\(aqs publisher +When the Minion service is first started up, it will connect to its Master\(aqs publisher on port 4505. If too many minions are started at once, this can cause a "thundering herd". This can be avoided by not starting too many minions at once. .sp The connection itself usually isn\(aqt the culprit, the more likely cause of master\-side -issues is the authentication that the minion must do with the master. If the master -is too heavily loaded to handle the auth request it will time it out. The minion +issues is the authentication that the Minion must do with the Master. If the Master +is too heavily loaded to handle the auth request it will time it out. The Minion will then wait \fIacceptance_wait_time\fP to retry. If \fIacceptance_wait_time_max\fP is -set then the minion will increase its wait time by the \fIacceptance_wait_time\fP each +set then the Minion will increase its wait time by the \fIacceptance_wait_time\fP each subsequent retry until reaching \fIacceptance_wait_time_max\fP\&. .SS Too many minions re\-authing .sp -This is most likely to happen in the testing phase, when all minion keys have -already been accepted, the framework is being tested and parameters change -frequently in the masters configuration file. +This is most likely to happen in the testing phase of a Salt deployment, when +all Minion keys have already been accepted, but the framework is being tested +and parameters are frequently changed in the Salt Master\(aqs configuration +file(s). .sp -In a few cases (master restart, remove minion key, etc.) the salt\-master generates -a new AES\-key to encrypt its publications with. The minions aren\(aqt notified of -this but will realize this on the next pub job they receive. When the minion -receives such a job it will then re\-auth with the master. Since Salt does minion\-side -filtering this means that all the minions will re\-auth on the next command published -on the master\-\- causing another "thundering herd". This can be avoided by -setting the +The Salt Master generates a new AES key to encrypt its publications at certain +events such as a Master restart or the removal of a Minion key. If you are +encountering this problem of too many minions re\-authing against the Master, +you will need to recalibrate your setup to reduce the rate of events like a +Master restart or Minion key removal (\fBsalt\-key \-d\fP). +.sp +When the Master generates a new AES key, the minions aren\(aqt notified of this +but will discover it on the next pub job they receive. When the Minion +receives such a job it will then re\-auth with the Master. Since Salt does +minion\-side filtering this means that all the minions will re\-auth on the next +command published on the master\-\- causing another "thundering herd". This can +be avoided by setting the .INDENT 0.0 .INDENT 3.5 .sp @@ -13213,7 +13042,7 @@ random_reauth_delay: 60 .sp in the minions configuration file to a higher value and stagger the amount of re\-auth attempts. Increasing this value will of course increase the time -it takes until all minions are reachable via salt commands. +it takes until all minions are reachable via Salt commands. .SS Too many minions re\-connecting .sp By default the zmq socket will re\-connect every 100ms which for some larger @@ -13246,16 +13075,16 @@ recon_randomize: enables randomization between recon_default and recon_max To tune this values to an existing environment, a few decision have to be made. .INDENT 0.0 .IP 1. 3 -How long can one wait, before the minions should be online and reachable via salt? +How long can one wait, before the minions should be online and reachable via Salt? .IP 2. 3 -How many reconnects can the master handle without a syn flood? +How many reconnects can the Master handle without a syn flood? .UNINDENT .sp These questions can not be answered generally. Their answers depend on the hardware and the administrators requirements. .sp Here is an example scenario with the goal, to have all minions reconnect -within a 60 second time\-frame on a salt\-master service restart. +within a 60 second time\-frame on a Salt Master service restart. .INDENT 0.0 .INDENT 3.5 .sp @@ -13269,7 +13098,7 @@ recon_randomize: True .UNINDENT .UNINDENT .sp -Each minion will have a randomized reconnect value between \(aqrecon_default\(aq +Each Minion will have a randomized reconnect value between \(aqrecon_default\(aq and \(aqrecon_default + recon_max\(aq, which in this example means between 1000ms and 60000ms (or between 1 and 60 seconds). The generated random\-value will be doubled after each attempt to reconnect (ZeroMQ default behavior). @@ -13325,11 +13154,11 @@ $ salt * test.ping .UNINDENT .UNINDENT .sp -it may cause thousands of minions trying to return their data to the salt\-master -open port 4506. Also causing a flood of syn\-flood if the master can\(aqt handle that many +it may cause thousands of minions trying to return their data to the Salt Master +open port 4506. Also causing a flood of syn\-flood if the Master can\(aqt handle that many returns at once. .sp -This can be easily avoided with salts batch mode: +This can be easily avoided with Salt\(aqs batch mode: .INDENT 0.0 .INDENT 3.5 .sp @@ -13346,12 +13175,12 @@ minions. .SS Too few resources .sp The masters resources always have to match the environment. There is no way -to give good advise without knowing the environment the master is supposed to +to give good advise without knowing the environment the Master is supposed to run in. But here are some general tuning tips for different situations: -.SS The master is CPU bound +.SS The Master is CPU bound .sp Salt uses RSA\-Key\-Pairs on the masters and minions end. Both generate 4096 -bit key\-pairs on first start. While the key\-size for the master is currently +bit key\-pairs on first start. While the key\-size for the Master is currently not configurable, the minions keysize can be configured with different key\-sizes. For example with a 2048 bit key: .INDENT 0.0 @@ -13370,11 +13199,11 @@ masters end should not be neglected. See here for reference: \fI\%Pull Request 9235\fP how much influence the key\-size can have. .sp -Downsizing the salt\-masters key is not that important, because the minions -do not encrypt as many messages as the master does. -.SS The master is disk IO bound +Downsizing the Salt Master\(aqs key is not that important, because the minions +do not encrypt as many messages as the Master does. +.SS The Master is disk IO bound .sp -By default, the master saves every minion\(aqs return for every job in its +By default, the Master saves every Minion\(aqs return for every job in its job\-cache. The cache can then be used later, to lookup results for previous jobs. The default directory for this is: .INDENT 0.0 @@ -13390,7 +13219,7 @@ cachedir: /var/cache/salt .sp and then in the \fB/proc\fP directory. .sp -Each job return for every minion is saved in a single file. Over time this +Each job return for every Minion is saved in a single file. Over time this directory can grow quite large, depending on the number of published jobs. The amount of files and directories will scale with the number of jobs published and the retention time defined by @@ -13431,9 +13260,9 @@ If the job cache is necessary there are (currently) 2 options: .INDENT 0.0 .IP \(bu 2 ext_job_cache: this will have the minions store their return data directly -into a returner (not sent through the master) +into a returner (not sent through the Master) .IP \(bu 2 -master_job_cache (New in \fI2014.7.0\fP): this will make the master store the job +master_job_cache (New in \fI2014.7.0\fP): this will make the Master store the job data using a returner (instead of the local job cache on disk). .UNINDENT .SH TARGETING MINIONS @@ -13622,17 +13451,16 @@ salt \-L \(aqweb1,web2,web3\(aq test.ping .sp Salt comes with an interface to derive information about the underlying system. This is called the grains interface, because it presents salt with grains of -information. +information. Grains are collected for the operating system, domain name, +IP address, kernel, OS type, memory, and many other system properties. .sp The grains interface is made available to Salt modules and components so that the right salt minion commands are automatically available on the right systems. .sp -It is important to remember that grains are bits of information loaded when -the salt minion starts, so this information is static. This means that the -information in grains is unchanging, therefore the nature of the data is -static. So grains information are things like the running kernel, or the -operating system. +Grain data is relatively static, though if system information changes +(for example, if network settings are changed), or if a new value is assigned +to a custom grain, grain data is refreshed. .sp \fBNOTE:\fP .INDENT 0.0 @@ -14889,19 +14717,19 @@ salt \(aq*\(aq state.highstate pillar=\(aq["cheese", "milk", "bread"]\(aq .UNINDENT .SS Master Config In Pillar .sp -For convenience the data stored in the master configuration file is made +For convenience the data stored in the master configuration file can be made available in all minion\(aqs pillars. This makes global configuration of services and systems very easy but may not be desired if sensitive data is stored in the -master configuration. +master configuration. This option is disabled by default. .sp -To disable the master config from being added to the pillar set \fBpillar_opts\fP -to \fBFalse\fP: +To enable the master config from being added to the pillar set \fBpillar_opts\fP +to \fBTrue\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -pillar_opts: False +pillar_opts: True .ft P .fi .UNINDENT @@ -15510,16 +15338,17 @@ Ink servers in the master configuration. highstate_run: local.state.highstate: \- tgt: {{ data[\(aqid\(aq] }} - \- ret: smtp_return + \- ret: smtp .ft P .fi .UNINDENT .UNINDENT .sp The above will also return the highstate result data using the \fIsmtp_return\fP -returner. The returner needs to be configured on the minion for this to -work. See \fBsalt.returners.smtp_return\fP documentation for -that. +returner (use virtualname like when using from the command line with \fI\-\-return\fP). +The returner needs to be configured on the minion for this to work. +See \fBsalt.returners.smtp_return\fP documentation +for that. .SS Syncing Custom Types on Minion Start .sp Salt will sync all custom types (by running a \fBsaltutil.sync_all\fP) on every highstate. However, there is a @@ -15802,6 +15631,9 @@ The above configuration allows the user \fBthatch\fP to execute functions in the test and network modules on the minions that match the web* target. User \fBsteve\fP is given unrestricted access to minion commands. .sp +Salt respects the current PAM configuration in place, and uses the \(aqlogin\(aq +service to authenticate. +.sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 @@ -15875,6 +15707,15 @@ external_auth: .fi .UNINDENT .UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +All users that have external authentication privileges are allowed to run +\fBsaltutil.findjob\fP\&. Be aware +that this could inadvertently expose some data such as minion IDs. +.UNINDENT +.UNINDENT .SS Tokens .sp With external authentication alone, the authentication credentials will be @@ -15912,6 +15753,7 @@ LDAP usage requires that you have installed python\-ldap. .sp Salt supports both user and group authentication for LDAP (and Active Directory accessed via its LDAP interface) +.SS OpenLDAP and similar systems .sp LDAP configuration happens in the Salt master configuration file. .sp @@ -15921,16 +15763,43 @@ Server configuration values and their defaults: .sp .nf .ft C +# Server to auth against auth.ldap.server: localhost + +# Port to connect via auth.ldap.port: 389 + +# Use TLS when connecting auth.ldap.tls: False + +# LDAP scope level, almost always 2 auth.ldap.scope: 2 -auth.ldap.uri: \(aq\(aq -auth.ldap.tls: False + +# Server specified in URI format +auth.ldap.uri: \(aq\(aq # Overrides .ldap.server, .ldap.port, .ldap.tls above + +# Verify server\(aqs TLS certificate auth.ldap.no_verify: False + +# Bind to LDAP anonymously to determine group membership +# Active Directory does not allow anonymous binds without special configuration auth.ldap.anonymous: False + +# FOR TESTING ONLY, this is a VERY insecure setting. +# If this is True, the LDAP bind password will be ignored and +# access will be determined by group membership alone with +# the group memberships being retrieved via anonymous bind +auth.ldap.auth_by_group_membership_only: False + +# Require authenticating user to be part of this Organizational Unit +# This can be blank if your LDAP schema does not use this kind of OU auth.ldap.groupou: \(aqGroups\(aq + +# Object Class for groups. An LDAP search will be done to find all groups of this +# class to which the authenticating user belongs. auth.ldap.groupclass: \(aqposixGroup\(aq + +# Unique ID attribute name for the user auth.ldap.accountattributename: \(aqmemberUid\(aq # These are only for Active Directory @@ -15941,33 +15810,42 @@ auth.ldap.persontype: \(aqperson\(aq .UNINDENT .UNINDENT .sp -Salt also needs to know which Base DN to search for users and groups and -the DN to bind to: +There are two phases to LDAP authentication. First, Salt authenticates to search for a users\(aqs Distinguished Name +and group membership. The user it authenticates as in this phase is often a special LDAP system user with +read\-only access to the LDAP directory. After Salt searches the directory to determine the actual user\(aqs DN +and groups, it re\-authenticates as the user running the Salt commands. +.sp +If you are already aware of the structure of your DNs and permissions in your LDAP store are set such that +users can look up their own group memberships, then the first and second users can be the same. To tell Salt this is +the case, omit the \fBauth.ldap.bindpw\fP parameter. You can template the binddn like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth.ldap.basedn: dc=saltstack,dc=com -auth.ldap.binddn: cn=admin,dc=saltstack,dc=com +auth.ldap.binddn: uid={{ username }},cn=users,cn=accounts,dc=saltstack,dc=com .ft P .fi .UNINDENT .UNINDENT .sp -To bind to a DN, a password is required +Salt will use the password entered on the salt command line in place of the bindpw. +.sp +To use two separate users, specify the LDAP lookup user in the binddn directive, and include a bindpw like so .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +auth.ldap.binddn: uid=ldaplookup,cn=sysaccounts,cn=etc,dc=saltstack,dc=com auth.ldap.bindpw: mypassword .ft P .fi .UNINDENT .UNINDENT .sp -Salt uses a filter to find the DN associated with a user. Salt +As mentioned before, Salt uses a filter to find the DN associated with a user. Salt substitutes the \fB{{ username }}\fP value for the username when querying LDAP .INDENT 0.0 .INDENT 3.5 @@ -15994,6 +15872,7 @@ auth.ldap.groupou: Groups .fi .UNINDENT .UNINDENT +.SS Active Directory .sp Active Directory handles group membership differently, and does not utilize the \fBgroupou\fP configuration variable. AD needs the following options in @@ -16032,7 +15911,7 @@ of the user is looked up with the following LDAP search: .UNINDENT .sp This should return a distinguishedName that we can use to filter for group -membership. Then the following LDAP query is executed: +membership. Then the following LDAP query is executed: .INDENT 0.0 .INDENT 3.5 .sp @@ -17287,6 +17166,24 @@ Fired each time a minion returns data for a job. .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B salt/job//prog// +Fired each time a each function in a state run completes execution. Must be +enabled using the \fBstate_events\fP option. +.INDENT 7.0 +.TP +.B Variables +.INDENT 7.0 +.IP \(bu 2 +\fBdata\fP \-\- The data returned from the state module function. +.IP \(bu 2 +\fBid\fP \-\- The minion ID. +.IP \(bu 2 +\fBjid\fP \-\- The job ID. +.UNINDENT +.UNINDENT +.UNINDENT .SS Presence events .INDENT 0.0 .TP @@ -17968,7 +17865,7 @@ A tutorial on setting up multimaster with "hot" masters is here: \fBMultimaster Tutorial\fP .SS Multimaster with Failover .sp -Changing the \fBmaster_type\fP parameter from \fBstandard\fP to \fBfailover\fP will +Changing the \fBmaster_type\fP parameter from \fBstr\fP to \fBfailover\fP will cause minions to connect to the first responding master in the list of masters. Every \fBmaster_alive_check\fP seconds the minions will check to make sure the current master is still responding. If the master does not respond, @@ -18000,117 +17897,264 @@ certain masters control certain segments of the infrastructure, and "Master of Masters" nodes can control multiple segments underneath them. .sp Syndics are covered in depth in \fBSalt Syndic\fP\&. +.SS Syndic with Multimaster +.sp +New in version 2015.5.0. + +.sp +Syndic with Multimaster lets you connect a syndic to multiple masters to provide +an additional layer of redundancy in a syndic configuration. +.sp +Syndics are covered in depth in \fBSalt Syndic\fP\&. .SH SALT SYNDIC .sp -The Salt Syndic interface is a powerful tool which allows for the construction -of Salt command topologies. A basic Salt setup has a Salt Master commanding a -group of Salt Minions. The Syndic interface is a special passthrough -minion, it is run on a master and connects to another master, then the master -that the Syndic minion is listening to can control the minions attached to -the master running the syndic. +The most basic or typical Salt topology consists of a single Master node +controlling a group of Minion nodes. An intermediate node type, called Syndic, +when used offers greater structural flexibility and scalability in the +construction of Salt topologies than topologies constructed only out of Master +and Minion node types. .sp -The intent for supporting many layouts is not presented with the intent of -supposing the use of any single topology, but to allow a more flexible method -of controlling many systems. +A Syndic node can be thought of as a special passthrough Minion node. A Syndic +node consists of a \fBsalt\-syndic\fP daemon and a \fBsalt\-master\fP daemon running +on the same system. The \fBsalt\-master\fP daemon running on the Syndic node +controls a group of lower level Minion nodes and the \fBsalt\-syndic\fP daemon +connects higher level Master node, sometimes called a Master of Masters. +.sp +The \fBsalt\-syndic\fP daemon relays publications and events between the Master +node and the local \fBsalt\-master\fP daemon. This gives the Master node control +over the Minion nodes attached to the \fBsalt\-master\fP daemon running on the +Syndic node. .SS Configuring the Syndic .sp -Since the Syndic only needs to be attached to a higher level master the -configuration is very simple. On a master that is running a syndic to connect -to a higher level master the \fBsyndic_master\fP option needs to be -set in the master config file. The \fBsyndic_master\fP option contains the -hostname or IP address of the master server that can control the master that -the syndic is running on. +To setup a Salt Syndic you need to tell the Syndic node and its Master node +about each other. If your Master node is located at \fB10.10.0.1\fP, then your +configurations would be: .sp -The master that the syndic connects to sees the syndic as an ordinary minion, -and treats it as such. the higher level master will need to accept the syndic\(aqs -minion key like any other minion. This master will also need to set the -\fBorder_masters\fP value in the configuration to \fBTrue\fP\&. The -\fBorder_masters\fP option in the config on the higher level master is very -important, to control a syndic extra information needs to be sent with the -publications, the \fBorder_masters\fP option makes sure that the extra data is -sent out. -.sp -To sum up, you have those configuration options available on the master side: +On the Syndic node: .INDENT 0.0 .INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -\fBsyndic_master\fP: MasterOfMaster ip/address -.IP \(bu 2 -\fBsyndic_master_port\fP: MasterOfMaster ret_port -.IP \(bu 2 -\fBsyndic_log_file\fP: path to the logfile (absolute or not) -.IP \(bu 2 -\fBsyndic_pidfile\fP: path to the pidfile (absolute or not) +.sp +.nf +.ft C +# /etc/salt/master +syndic_master: 10.10.0.1 # may be either an IP address or a hostname +.ft P +.fi .UNINDENT .UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# /etc/salt/minion + +# id is shared by the salt\-syndic daemon and a possible salt\-minion daemon +# on the Syndic node +id: my_syndic +.ft P +.fi +.UNINDENT .UNINDENT .sp -Each Syndic must provide its own \fBfile_roots\fP directory. Files will not be -automatically transferred from the master\-master. +On the Master node: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# /etc/salt/master +order_masters: True +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBsyndic_master\fP option tells the Syndic node where to find the +Master node in the same way that the \fBmaster\fP option tells a +Minion node where to find a Master node. +.sp +The \fBid\fP option is used by the \fBsalt\-syndic\fP daemon to identify +with the Master node and if unset will default to the hostname or IP address of +the Syndic just as with a Minion. +.sp +The \fBorder_masters\fP option configures the Master node to send +extra information with its publications that is needed by Syndic nodes +connected directly to it. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Each Syndic must provide its own \fBfile_roots\fP directory. Files will not +be automatically transferred from the Master node. +.UNINDENT +.UNINDENT +.SS Configuring the Syndic with Multimaster +.sp +New in version 2015.5.0. + +.sp +Syndic with Multimaster lets you connect a syndic to multiple masters to provide +an additional layer of redundancy in a syndic configuration. +.sp +Higher level masters should first be configured in a multimaster configuration. +See \fBMultimaster Tutorial\fP\&. +.sp +On the syndic, the \fBsyndic_master\fP option is populated with +a list of the higher level masters. +.sp +Since each syndic is connected to each master, jobs sent from any master are +forwarded to minions that are connected to each syndic. If the \fBmaster_id\fP value +is set in the master config on the higher level masters, job results are returned +to the master that originated the request in a best effort fashion. Events/jobs +without a \fBmaster_id\fP are returned to any available master. .SS Running the Syndic .sp -The Syndic is a separate daemon that needs to be started on the master that is -controlled by a higher master. Starting the Syndic daemon is the same as -starting the other Salt daemons. +The \fBsalt\-syndic\fP daemon is a separate process that needs to be started in +addition to the \fBsalt\-master\fP daemon running on the Syndic node. Starting +the \fBsalt\-syndic\fP daemon is the same as starting the other Salt daemons. +.sp +The Master node in many ways sees the Syndic as an ordinary Minion node. In +particular, the Master will need to accept the Syndic\(aqs Minion key as it would +for any other Minion. +.sp +On the Syndic node: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-syndic +or +# service salt\-syndic start .ft P .fi .UNINDENT .UNINDENT .sp -\fBNOTE:\fP +On the Master node: .INDENT 0.0 .INDENT 3.5 -If you have an exceptionally large infrastructure or many layers of -syndics, you may find that the CLI doesn\(aqt wait long enough for the syndics -to return their events. If you think this is the case, you can set the -\fBsyndic_wait\fP value in the upper master config. The default -value is \fB1\fP, and should work for the majority of deployments. +.sp +.nf +.ft C +# salt\-key \-a my_syndic +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The Master node will now be able to control the Minion nodes connected to the +Syndic. Only the Syndic key will be listed in the Master node\(aqs key registry +but this also means that key activity between the Syndic\(aqs Minions and the +Syndic does not encumber the Master node. In this way, the Syndic\(aqs key on the +Master node can be thought of as a placeholder for the keys of all the Minion +and Syndic nodes beneath it, giving the Master node a clear, high level +structural view on the Salt cluster. +.sp +On the Master node: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# salt\-key \-L +Accepted Keys: +my_syndic +Denied Keys: +Unaccepted Keys: +Rejected Keys: + +# salt \(aq*\(aq test.ping +minion_1: + True +minion_2: + True +minion_4: + True +minion_3: + True +.ft P +.fi .UNINDENT .UNINDENT .SS Topology .sp -The \fBsalt\-syndic\fP is little more than a command and event forwarder. When a -command is issued from a higher\-level master, it will be received by the -configured syndics on lower\-level masters, and propagated to to their minions, -and other syndics that are bound to them further down in the hierarchy. When -events and job return data are generated by minions, they aggregated back, -through the same syndic(s), to the master which issued the command. +A Master node (a node which is itself not a Syndic to another higher level +Master node) must run a \fBsalt\-master\fP daemon and optionally a \fBsalt\-minion\fP +daemon. .sp -The master sitting at the top of the hierarchy (the Master of Masters) will \fInot\fP -be running the \fBsalt\-syndic\fP daemon. It will have the \fBsalt\-master\fP -daemon running, and optionally, the \fBsalt\-minion\fP daemon. Each syndic -connected to an upper\-level master will have both the \fBsalt\-master\fP and the -\fBsalt\-syndic\fP daemon running, and optionally, the \fBsalt\-minion\fP daemon. +A Syndic node must run \fBsalt\-syndic\fP and \fBsalt\-master\fP daemons and +optionally a \fBsalt\-minion\fP daemon. .sp -Nodes on the lowest points of the hierarchy (minions which do not propagate -data to another level) will only have the \fBsalt\-minion\fP daemon running. There -is no need for either \fBsalt\-master\fP or \fBsalt\-syndic\fP to be running on a -standard minion. -.SS Syndic and the CLI +A Minion node must run a \fBsalt\-minion\fP daemon. .sp -In order for the high\-level master to return information from minions that are -below the syndic(s), the CLI requires a short wait time in order to allow the -syndic(s) to gather responses from their minions. This value is defined in the -\fBsyndic_wait\fP and has a default of five seconds. +When a \fBsalt\-master\fP daemon issues a command, it will be received by the +Syndic and Minion nodes directly connected to it. A Minion node will process +the command in the way it ordinarily would. On a Syndic node, the +\fBsalt\-syndic\fP daemon will relay the command to the \fBsalt\-master\fP daemon +running on the Syndic node, which then propagates the command to to the Minions +and Syndics connected to it. .sp -While it is possible to run a syndic without a minion installed on the same machine, -it is recommended, for a faster CLI response time, to do so. Without a minion -installed on the syndic, the timeout value of \fBsyndic_wait\fP increases -significantly \- about three\-fold. With a minion installed on the syndic, the CLI -timeout resides at the value defined in \fBsyndic_wait\fP\&. +When events and job return data are generated by \fBsalt\-minion\fP daemons, they +are aggregated by the \fBsalt\-master\fP daemon they are connected to, which +\fBsalt\-master\fP daemon then relays the data back through its \fBsalt\-syndic\fP +daemon until the data reaches the Master or Syndic node that issued the command. +.SS Syndic wait .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -To reduce the amount of time the CLI waits for minions to respond, install a minion -on the syndic or tune the value of the \fBsyndic_wait\fP configuration. +To reduce the amount of time the CLI waits for Minions to respond, install +a Minion on the Syndic or tune the value of the \fBsyndic_wait\fP +configuration. +.UNINDENT +.UNINDENT +.sp +While it is possible to run a Syndic without a Minion installed on the same +system, it is recommended, for a faster CLI response time, to do so. Without a +Minion installed on the Syndic node, the timeout value of \fBsyndic_wait\fP +increases significantly \- about three\-fold. With a Minion installed on the +Syndic, the CLI timeout resides at the value defined in \fBsyndic_wait\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If you have a very large infrastructure or many layers of Syndics, you may +find that the CLI doesn\(aqt wait long enough for the Syndics to return their +events. If you think this is the case, you can set the +\fBsyndic_wait\fP value in the Master configs on the Master or +Syndic nodes from which commands are executed. The default value is \fB5\fP, +and should work for the majority of deployments. +.UNINDENT +.UNINDENT +.sp +In order for a Master or Syndic node to return information from Minions that +are below their Syndics, the CLI requires a short wait time in order to allow +the Syndics to gather responses from their Minions. This value is defined in +the \fBsyndic_wait\fP config option and has a default of five seconds. +.SS Syndic config options +.sp +These are the options that can be used to configure a Syndic node. Note that +other than \fBid\fP, Syndic config options are placed in the Master config on the +Syndic node. +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +\fBid\fP: Syndic id (shared by the \fBsalt\-syndic\fP daemon with a +potential \fBsalt\-minion\fP daemon on the same system) +.IP \(bu 2 +\fBsyndic_master\fP: Master node IP address or hostname +.IP \(bu 2 +\fBsyndic_master_port\fP: Master node ret_port +.IP \(bu 2 +\fBsyndic_log_file\fP: path to the logfile (absolute or not) +.IP \(bu 2 +\fBsyndic_pidfile\fP: path to the pidfile (absolute or not) +.IP \(bu 2 +\fBsyndic_wait\fP: time in seconds to wait on returns from this syndic +.UNINDENT .UNINDENT .UNINDENT .SH SALT PROXY MINION DOCUMENTATION @@ -18131,6 +18175,20 @@ your typical housecat would be excellent source material for a PhD thesis. .sp Salt proxy\-minions provide the \(aqplumbing\(aq that allows device enumeration and discovery, control, status, remote execution, and state management. +.sp +See the \fBProxy Minion Walkthrough\fP for an end\-to\-end +demonstration of a working proxy minion. +.SS New in 2015.8 +.sp +Starting with the 2015.8 release of Salt, proxy processes are no longer forked off from a controlling minion. +Instead, they have their own script \fBsalt\-proxy\fP which takes mostly the same arguments that the +standard Salt minion does with the addition of \fB\-\-proxyid\fP\&. This is the id that the salt\-proxy will +use to identify itself to the master. Proxy configurations are still best kept in Pillar and their format +has not changed. +.sp +This change allows for better process control and logging. Proxy processes can now be listed with standard +process management utilities (\fBps\fP from the command line). Also, a full Salt minion is no longer +required (though it is still strongly recommended) on machines hosting proxies. .SS Getting Started .sp The following diagram may be helpful in understanding the structure of a Salt @@ -18139,18 +18197,16 @@ installation that includes proxy\-minions: .sp The key thing to remember is the left\-most section of the diagram. Salt\(aqs nature is to have a minion connect to a master, then the master may control -the minion. However, for proxy minions, the target device cannot run a minion, -and thus must rely on a separate minion to fire up the proxy\-minion and make the -initial and persistent connection. +the minion. However, for proxy minions, the target device cannot run a minion. .sp After the proxy minion is started and initiates its connection to the \(aqdumb\(aq -device, it connects back to the salt\-master and ceases to be affiliated in -any way with the minion that started it. +device, it connects back to the salt\-master and for all intents and purposes +looks like just another minion to the Salt master. .sp To create support for a proxied device one needs to create four things: .INDENT 0.0 .IP 1. 3 -The \fI\%proxytype connection class\fP (located in salt/proxy). +The \fI\%proxy_connection_module\fP (located in salt/proxy). .IP 2. 3 The \fI\%grains support code\fP (located in salt/grains). .IP 3. 3 @@ -18159,7 +18215,7 @@ device. .IP 4. 3 \fISalt states\fP specific to the controlled device. .UNINDENT -.SS Configuration parameters on the master +.SS Configuration parameters .sp Proxy minions require no configuration parameters in /etc/salt/master. .sp @@ -18178,75 +18234,123 @@ based on the diagram above: .nf .ft C base: - minioncontroller1: - \- networkswitches - minioncontroller2: - \- reallydumbdevices - minioncontroller3: - \- smsgateway -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fB/srv/pillar/networkswitches.sls\fP -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -proxy: dumbdevice1: - proxytype: networkswitch - host: 172.23.23.5 - username: root - passwd: letmein + \- dumbdevice1 dumbdevice2: - proxytype: networkswitch - host: 172.23.23.6 - username: root - passwd: letmein + \- dumbdevice2 dumbdevice3: - proxytype: networkswitch - host: 172.23.23.7 - username: root - passwd: letmein -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fB/srv/pillar/reallydumbdevices.sls\fP -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -proxy: + \- dumbdevice3 dumbdevice4: - proxytype: i2c_lightshow - i2c_address: 1 + \- dumbdevice4 dumbdevice5: - proxytype: i2c_lightshow - i2c_address: 2 + \- dumbdevice5 dumbdevice6: - proxytype: 433mhz_wireless + \- dumbdevice6 + dumbdevice7: + \- dumbdevice7 .ft P .fi .UNINDENT .UNINDENT .sp -\fB/srv/pillar/smsgateway.sls\fP +\fB/srv/pillar/dumbdevice1.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: - minioncontroller3: - dumbdevice7: - proxytype: sms_serial - deventry: /dev/tty04 + proxytype: networkswitch + host: 172.23.23.5 + username: root + passwd: letmein +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fB/srv/pillar/dumbdevice2.sls\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +proxy: + proxytype: networkswitch + host: 172.23.23.6 + username: root + passwd: letmein +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fB/srv/pillar/dumbdevice3.sls\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +proxy: + proxytype: networkswitch + host: 172.23.23.7 + username: root + passwd: letmein +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fB/srv/pillar/dumbdevice4.sls\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +proxy: + proxytype: i2c_lightshow + i2c_address: 1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fB/srv/pillar/dumbdevice5.sls\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +proxy: + proxytype: i2c_lightshow + i2c_address: 2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fB/srv/pillar/dumbdevice6.sls\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +proxy: + proxytype: 433mhz_wireless +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fB/srv/pillar/dumbdevice7.sls\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +proxy: + proxytype: sms_serial + deventry: /dev/tty04 .ft P .fi .UNINDENT @@ -18273,123 +18377,255 @@ dumbdevice7 is an SMS gateway connected to machine minioncontroller3 via a serial port. .UNINDENT .sp -Because of the way pillar works, each of the salt\-minions that fork off the +Because of the way pillar works, each of the salt\-proxy processes that fork off the proxy minions will only see the keys specific to the proxies it will be -handling. In other words, from the above example, only minioncontroller1 will -see the connection information for dumbdevices 1, 2, and 3. Minioncontroller2 -will see configuration data for dumbdevices 4, 5, and 6, and minioncontroller3 -will be privy to dumbdevice7. +handling. .sp Also, in general, proxy\-minions are lightweight, so the machines that run them -could conceivably control a large number of devices. The example above is just -to illustrate that it is possible for the proxy services to be spread across +could conceivably control a large number of devices. To run more than one proxy from +a single machine, simply start an additional proxy process with \fB\-\-proxyid\fP +set to the id to which you want the proxy to bind. +It is possible for the proxy services to be spread across many machines if necessary, or intentionally run on machines that need to control devices because of some physical interface (e.g. i2c and serial above). Another reason to divide proxy services might be security. In more secure environments only certain machines may have a network path to certain devices. +.SS Proxymodules .sp -Now our salt\-minions know if they are supposed to spawn a proxy\-minion process -to control a particular device. That proxy\-minion process will initiate -a connection back to the master to enable control. -.SS Proxytypes +A proxy module encapsulates all the code necessary to interface with a device. +Proxymodules are located inside the salt.proxy module. At a minimum +a proxymodule object must implement the following functions: .sp -A proxytype is a Python class called \(aqProxyconn\(aq that encapsulates all the code -necessary to interface with a device. Proxytypes are located inside the -salt.proxy module. At a minimum a proxytype object must implement the -following methods: +\fB__virtual__()\fP: This function performs the same duty that it does for other +types of Salt modules. Logic goes here to determine if the module can be +loaded, checking for the presence of Python modules on which the proxy depends. +Returning \fBFalse\fP will prevent the module from loading. .sp -\fBproxytype(self)\fP: Returns a string with the name of the proxy type. +\fBinit(opts)\fP: Perform any initialization that the device needs. This is +a good place to bring up a persistent connection to a device, or authenticate +to create a persistent authorization token. .sp -\fBproxyconn(self, **kwargs)\fP: Provides the primary way to connect and communicate -with the device. Some proxyconns instantiate a particular object that opens a -network connection to a device and leaves the connection open for communication. -Others simply abstract a serial connection or even implement endpoints to communicate -via REST over HTTP. +\fBshutdown()\fP: Code to cleanly shut down or close a connection to +a controlled device goes here. This function must exist, but can contain only +the keyword \fBpass\fP if there is no shutdown logic required. .sp -\fBid(self, opts)\fP: Returns a unique, unchanging id for the controlled device. This is +\fBping()\fP: While not required, it is highly recommended that this function also +be defined in the proxymodule. The code for \fBping\fP should contact the +controlled device and make sure it is really available. +.sp +Pre 2015.8 the proxymodule also must have an \fBid()\fP function. 2015.8 and following don\(aqt use +this function because the proxy\(aqs id is required on the command line. +.sp +\fBid(opts)\fP: Returns a unique, unchanging id for the controlled device. This is the "name" of the device, and is used by the salt\-master for targeting and key authentication. .sp -Optionally, the class may define a \fBshutdown(self, opts)\fP method if the -controlled device should be informed when the minion goes away cleanly. +Here is an example proxymodule used to interface to a \fIvery\fP simple REST +server. Code for the server is in the \fI\%salt\-contrib GitHub repository\fP .sp -It is highly recommended that the \fBtest.ping\fP execution module also be defined -for a proxytype. The code for \fBping\fP should contact the controlled device and make -sure it is really available. -.sp -Here is an example proxytype used to interface to Juniper Networks devices that run -the Junos operating system. Note the additional library requirements\-\-most of the -"hard part" of talking to these devices is handled by the jnpr.junos, jnpr.junos.utils, -and jnpr.junos.cfg modules. +This proxymodule enables "service" enumeration, starting, stopping, restarting, +and status; "package" installation, and a ping. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +# \-*\- coding: utf\-8 \-*\- +\(aq\(aq\(aq +This is a simple proxy\-minion designed to connect to and communicate with +the bottle\-based web service contained in +https://github.com/saltstack/salt\-contrib/proxyminion_rest_example +\(aq\(aq\(aq +from __future__ import absolute_import + # Import python libs import logging -import os +import salt.utils.http -import jnpr.junos -import jnpr.junos.utils -import jnpr.junos.cfg -HAS_JUNOS = True +HAS_REST_EXAMPLE = True -class Proxyconn(object): +# This must be present or the Salt loader won\(aqt load this module +__proxyenabled__ = [\(aqrest_sample\(aq] - def __init__(self, details): - self.conn = jnpr.junos.Device(user=details[\(aqusername\(aq], host=details[\(aqhost\(aq], password=details[\(aqpasswd\(aq]) - self.conn.open() - self.conn.bind(cu=jnpr.junos.cfg.Resource) +# Variables are scoped to this module so we can have persistent data +# across calls to fns in here. +GRAINS_CACHE = {} +DETAILS = {} + +# Want logging! +log = logging.getLogger(__file__) - def proxytype(self): - return \(aqjunos\(aq +# This does nothing, it\(aqs here just as an example and to provide a log +# entry when the module is loaded. +def __virtual__(): + \(aq\(aq\(aq + Only return if all the modules are available + \(aq\(aq\(aq + log.debug(\(aqrest_sample proxy __virtual__() called...\(aq) + return True + +# Every proxy module needs an \(aqinit\(aq, though you can +# just put a \(aqpass\(aq here if it doesn\(aqt need to do anything. +def init(opts): + log.debug(\(aqrest_sample proxy init() called...\(aq) + + # Save the REST URL + DETAILS[\(aqurl\(aq] = opts[\(aqproxy\(aq][\(aqurl\(aq] + + # Make sure the REST URL ends with a \(aq/\(aq + if not DETAILS[\(aqurl\(aq].endswith(\(aq/\(aq): + DETAILS[\(aqurl\(aq] += \(aq/\(aq - def id(self, opts): - return self.conn.facts[\(aqhostname\(aq] +def id(opts): + \(aq\(aq\(aq + Return a unique ID for this proxy minion. This ID MUST NOT CHANGE. + If it changes while the proxy is running the salt\-master will get + really confused and may stop talking to this minion + \(aq\(aq\(aq + r = salt.utils.http.query(opts[\(aqproxy\(aq][\(aqurl\(aq]+\(aqid\(aq, decode_type=\(aqjson\(aq, decode=True) + return r[\(aqdict\(aq][\(aqid\(aq].encode(\(aqascii\(aq, \(aqignore\(aq) - def ping(self): - return self.conn.connected +def grains(): + \(aq\(aq\(aq + Get the grains from the proxied device + \(aq\(aq\(aq + if not GRAINS_CACHE: + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqinfo\(aq, decode_type=\(aqjson\(aq, decode=True) + GRAINS_CACHE = r[\(aqdict\(aq] + return GRAINS_CACHE - def shutdown(self, opts): +def grains_refresh(): + \(aq\(aq\(aq + Refresh the grains from the proxied device + \(aq\(aq\(aq + GRAINS_CACHE = {} + return grains() - print(\(aqProxy module {} shutting down!!\(aq.format(opts[\(aqid\(aq])) - try: - self.conn.close() - except Exception: - pass + +def service_start(name): + \(aq\(aq\(aq + Start a "service" on the REST server + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/start/\(aq+name, decode_type=\(aqjson\(aq, decode=True) + return r[\(aqdict\(aq] + + +def service_stop(name): + \(aq\(aq\(aq + Stop a "service" on the REST server + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/stop/\(aq+name, decode_type=\(aqjson\(aq, decode=True) + return r[\(aqdict\(aq] + + +def service_restart(name): + \(aq\(aq\(aq + Restart a "service" on the REST server + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/restart/\(aq+name, decode_type=\(aqjson\(aq, decode=True) + return r[\(aqdict\(aq] + + +def service_list(): + \(aq\(aq\(aq + List "services" on the REST server + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/list\(aq, decode_type=\(aqjson\(aq, decode=True) + return r[\(aqdict\(aq] + + +def service_status(name): + \(aq\(aq\(aq + Check if a service is running on the REST server + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/status/\(aq+name, decode_type=\(aqjson\(aq, decode=True) + return r[\(aqdict\(aq] + + +def package_list(): + \(aq\(aq\(aq + List "packages" installed on the REST server + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqpackage/list\(aq, decode_type=\(aqjson\(aq, decode=True) + return r[\(aqdict\(aq] + + +def package_install(name, **kwargs): + \(aq\(aq\(aq + Install a "package" on the REST server + \(aq\(aq\(aq + cmd = DETAILS[\(aqurl\(aq]+\(aqpackage/install/\(aq+name + if \(aqversion\(aq in kwargs: + cmd += \(aq/\(aq+kwargs[\(aqversion\(aq] + else: + cmd += \(aq/1.0\(aq + r = salt.utils.http.query(cmd, decode_type=\(aqjson\(aq, decode=True) + + +def package_remove(name): + + \(aq\(aq\(aq + Remove a "package" on the REST server + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqpackage/remove/\(aq+name, decode_type=\(aqjson\(aq, decode=True) + return r[\(aqdict\(aq] + + +def package_status(name): + \(aq\(aq\(aq + Check the installation status of a package on the REST server + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqpackage/status/\(aq+name, decode_type=\(aqjson\(aq, decode=True) + return r[\(aqdict\(aq] + + +def ping(): + \(aq\(aq\(aq + Is the REST server up? + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqping\(aq, decode_type=\(aqjson\(aq, decode=True) + try: + return r[\(aqdict\(aq].get(\(aqret\(aq, False) + except Exception: + return False + + +def shutdown(opts): + \(aq\(aq\(aq + For this proxy shutdown is a no\-op + \(aq\(aq\(aq + log.debug(\(aqrest_sample proxy shutdown() called...\(aq) + pass .ft P .fi .UNINDENT .UNINDENT .sp Grains are data about minions. Most proxied devices will have a paltry amount -of data as compared to a typical Linux server. Because proxy\-minions are -started by a regular minion, they inherit a sizeable number of grain settings -which can be useful, especially when targeting (PYTHONPATH, for example). -.sp -All proxy minions set a grain called \(aqproxy\(aq. If it is present, you know the -minion is controlling another device. To add more grains to your proxy minion -for a particular device, create a file in salt/grains named [proxytype].py and -place inside it the different functions that need to be run to collect the data -you are interested in. Here\(aqs an example: +of data as compared to a typical Linux server. By default, a proxy minion will +have several grains taken from the host. Salt core code requires values for \fBkernel\fP, +\fBos\fP, and \fBos_family\fP\-\-all of these are forced to be \fBproxy\fP for proxy\-minions. +To add others to your proxy minion for +a particular device, create a file in salt/grains named [proxytype].py and place +inside it the different functions that need to be run to collect the data you +are interested in. Here\(aqs an example: .SS The __proxyenabled__ directive .sp -Salt states and execution modules, by, and large, cannot "automatically" work +Salt execution modules, by, and large, cannot "automatically" work with proxied devices. Execution modules like \fBpkg\fP or \fBsqlite3\fP have no -meaning on a network switch or a housecat. For a state/execution module to be +meaning on a network switch or a housecat. For an execution module to be available to a proxy\-minion, the \fB__proxyenabled__\fP variable must be defined in the module as an array containing the names of all the proxytypes that this module can support. The array can contain the special value \fB*\fP to indicate that the module supports all proxies. .sp If no \fB__proxyenabled__\fP variable is defined, then by default, the -state/execution module is unavailable to any proxy. +execution module is unavailable to any proxy. .sp Here is an excerpt from a module that was modified to support proxy\-minions: .INDENT 0.0 @@ -18397,37 +18633,41 @@ Here is an excerpt from a module that was modified to support proxy\-minions: .sp .nf .ft C -def ping(): +__proxyenabled__ = [\(aq*\(aq] - if \(aqproxyobject\(aq in __opts__: - if \(aqping\(aq in __opts__[\(aqproxyobject\(aq].__attr__(): - return __opts[\(aqproxyobject\(aq].ping() - else: - return False - else: - return True +[...] + + def ping(): + + if \(aqproxymodule\(aq in __opts__: + ping_cmd = __opts__[\(aqproxymodule\(aq].loaded_base_name + \(aq.ping\(aq + return __opts__[\(aqproxymodule\(aq][ping_cmd]() + else: + return True .ft P .fi .UNINDENT .UNINDENT .sp -And then in salt.proxy.junos we find +And then in salt.proxy.rest_sample.py we find .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -def ping(self): - - return self.connected +def ping(): + \(aq\(aq\(aq + Is the REST server up? + \(aq\(aq\(aq + r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqping\(aq, decode_type=\(aqjson\(aq, decode=True) + try: + return r[\(aqdict\(aq].get(\(aqret\(aq, False) + except Exception: + return False .ft P .fi .UNINDENT .UNINDENT -.sp -The Junos API layer lacks the ability to do a traditional \(aqping\(aq, so the -example simply checks the connection object field that indicates -if the ssh connection was successfully made to the device. .SH THE RAET TRANSPORT .sp \fBNOTE:\fP @@ -18566,6 +18806,17 @@ For more information on libsodium and CurveCP please see: \fIRaet Programming Introduction\fP .SH WINDOWS SOFTWARE REPOSITORY .sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Git repository management for the Windows Software Repository has changed +in version 2015.8.0, and several master/minion config parameters have been +renamed to make their naming more consistent with each other. Please see +\fI\%below\fP for important details if upgrading +from an earlier Salt release. +.UNINDENT +.UNINDENT +.sp The Salt Windows Software Repository provides a package manager and software repository similar to what is provided by yum and apt on Linux. .sp @@ -18620,12 +18871,13 @@ between the pre and post \fBpkg.list_pkgs\fP results. .SS Usage .sp By default, the Windows software repository is found at \fB/srv/salt/win/repo\fP -This can be changed in the master config file (default location is -\fB/etc/salt/master\fP) by modifying the \fBwin_repo\fP variable, but this must -reside somewhere inside the master\(aqs \fIfile_roots\fP\&. Each piece of software -should have its own directory which contains the installers and a package -definition file. This package definition file is a YAML file named -\fBinit.sls\fP\&. +(\fBC:\esalt\esrv\esalt\ewin\erepo\fP on standalone minions). This can be changed in +the master config file by setting the \fBwinrepo_dir\fP option +(\fBNOTE:\fP this option was called \fBwin_repo\fP in Salt versions prior to +2015.8.0). However, this path must reside somewhere inside the master\(aqs +\fBfile_roots\fP\&. Each piece of software should have its own directory +which contains the installers and a package definition file. This package +definition file is a YAML file named \fBinit.sls\fP\&. .sp The package definition file should look similar to this example for Firefox: \fB/srv/salt/win/repo/firefox/init.sls\fP @@ -18634,7 +18886,7 @@ The package definition file should look similar to this example for Firefox: .sp .nf .ft C -Firefox: +firefox: 17.0.1: installer: \(aqsalt://win/repo/firefox/English/Firefox Setup 17.0.1.exe\(aq full_name: Mozilla Firefox 17.0.1 (x86 en\-US) @@ -18752,10 +19004,30 @@ project\(aqs \fI\%wiki\fP: installer: salt://win/repo/7zip/7z920\-x64.msi full_name: 7\-Zip 9.20 (x64 edition) reboot: False - install_flags: \(aq /q \(aq + install_flags: \(aq/qn /norestart\(aq + msiexec: True + uninstaller: \(aq{23170F69\-40C1\-2702\-0920\-000001000000}\(aq + uninstall_flags: \(aq/qn /norestart\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternatively the \fBuninstaller\fP can also simply repeat the URL of the msi file. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +7zip: + 9.20.00.0: + installer: salt://win/repo/7zip/7z920\-x64.msi + full_name: 7\-Zip 9.20 (x64 edition) + reboot: False + install_flags: \(aq/qn /norestart\(aq msiexec: True uninstaller: salt://win/repo/7zip/7z920\-x64.msi - uninstall_flags: \(aq /qn\(aq + uninstall_flags: \(aq/qn /norestart\(aq .ft P .fi .UNINDENT @@ -18774,7 +19046,7 @@ sqlexpress: installer: \(aqsalt://win/repo/sqlexpress/setup.exe\(aq full_name: Microsoft SQL Server 2014 Setup (English) reboot: False - install_flags: \(aq /ACTION=install /IACCEPTSQLSERVERLICENSETERMS /Q\(aq + install_flags: \(aq/ACTION=install /IACCEPTSQLSERVERLICENSETERMS /Q\(aq cache_dir: True .ft P .fi @@ -18782,7 +19054,8 @@ sqlexpress: .UNINDENT .SS Generate Repo Cache File .sp -Once the sls file has been created, generate the repository cache file with the winrepo runner: +Once the sls file has been created, generate the repository cache file with the +winrepo runner: .INDENT 0.0 .INDENT 3.5 .sp @@ -18808,7 +19081,7 @@ for the Linux package managers: .sp .nf .ft C -salt \(aq*\(aq pkg.refresh_db +salt winminion pkg.refresh_db .ft P .fi .UNINDENT @@ -18821,11 +19094,11 @@ Now you can query the available version of Firefox using the Salt pkg module. .sp .nf .ft C -salt \(aq*\(aq pkg.available_version Firefox +salt winminion pkg.available_version firefox -{\(aqFirefox\(aq: {\(aq15.0.1\(aq: \(aqMozilla Firefox 15.0.1 (x86 en\-US)\(aq, - \(aq16.0.2\(aq: \(aqMozilla Firefox 16.0.2 (x86 en\-US)\(aq, - \(aq17.0.1\(aq: \(aqMozilla Firefox 17.0.1 (x86 en\-US)\(aq}} +{\(aqfirefox\(aq: {\(aq15.0.1\(aq: \(aqMozilla Firefox 15.0.1 (x86 en\-US)\(aq, + \(aq16.0.2\(aq: \(aqMozilla Firefox 16.0.2 (x86 en\-US)\(aq, + \(aq17.0.1\(aq: \(aqMozilla Firefox 17.0.1 (x86 en\-US)\(aq}} .ft P .fi .UNINDENT @@ -18839,7 +19112,7 @@ by single quotes. .sp .nf .ft C -salt \(aq*\(aq pkg.install \(aqFirefox\(aq +salt winminion pkg.install \(aqfirefox\(aq .ft P .fi .UNINDENT @@ -18851,7 +19124,7 @@ The above line will install the latest version of Firefox. .sp .nf .ft C -salt \(aq*\(aq pkg.install \(aqFirefox\(aq version=16.0.2 +salt winminion pkg.install \(aqfirefox\(aq version=16.0.2 .ft P .fi .UNINDENT @@ -18859,9 +19132,9 @@ salt \(aq*\(aq pkg.install \(aqFirefox\(aq version=16.0.2 .sp The above line will install version 16.0.2 of Firefox. .sp -If a different version of the package is already installed it will -be replaced with the version in winrepo (only if the package itself supports -live updating). +If a different version of the package is already installed it will be replaced +with the version in the winrepo (only if the package itself supports live +updating). .sp You can also specify the full name: .INDENT 0.0 @@ -18869,7 +19142,7 @@ You can also specify the full name: .sp .nf .ft C -salt \(aq*\(aq pkg.install \(aqMozilla Firefox 17.0.1 (x86 en\-US)\(aq +salt winminion pkg.install \(aqMozilla Firefox 17.0.1 (x86 en\-US)\(aq .ft P .fi .UNINDENT @@ -18882,9 +19155,8 @@ Uninstall software using the pkg module: .sp .nf .ft C -salt \(aq*\(aq pkg.remove \(aqFirefox\(aq - -salt \(aq*\(aq pkg.purge \(aqFirefox\(aq +salt winminion pkg.remove firefox +salt winminion pkg.purge firefox .ft P .fi .UNINDENT @@ -18893,28 +19165,115 @@ salt \(aq*\(aq pkg.purge \(aqFirefox\(aq \fBpkg.purge\fP just executes \fBpkg.remove\fP on Windows. At some point in the future \fBpkg.purge\fP may direct the installer to remove all configs and settings for software packages that support that option. -.SS Standalone Minion Salt Windows Repo Module +.SS Managing Windows Software on a Standalone Windows Minion .sp -In order to facilitate managing a Salt Windows software repo with Salt on a -Standalone Minion on Windows, a new module named winrepo has been added to -Salt. winrepo matches what is available in the salt runner and allows you to -manage the Windows software repo contents. Example: \fBsalt \(aq*\(aq -winrepo.genrepo\fP -.SS Git Hosted Repo +The examples above for managing the winrepo using the \fBwinrepo runner\fP apply to the master, but some use cases call for +running a standalone (a.k.a. masterless) minion on a Windows server. For these +cases, the runner functions are not available, so an \fBexecution module\fP exists to provide the same functionality to standalone +minions. The functions are named the same as the ones in the runner, and are +used in the same way; the only difference is that \fBsalt\-call\fP is used instead +of \fBsalt\-run\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-call winrepo.genrepo +salt\-call pkg.refresh_db +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Package definition SLS files need to be in the correct location for +\fBwinrepo.genrepo\fP to find them. This +location is governed by minion config parameters. With much of Salt\(aqs Windows +Repo code having been rewritten for version 2015.8.0, the parameter names will +differ depending on which version the minion is running. The following two +sections include information on additional configuration required when running +a standalone minion. +.SS Minion Config Options for Releases Older Than 2015.8.0 +.sp +If connected to a master, the minion will by default look for the winrepo +cachefile (the file generated by the :py:func\(gawinrepo.genrepo runner +\(ga) at \fBsalt://win/repo/winrepo.p\fP\&. If the +cachefile is in a different path on the salt fileserver, then +\fBwin_repo_cachefile\fP will need to be updated to reflect the proper +location. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Additional Info for Standalone Minions +.sp +Additional configuration needs to be added to the minion config: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +win_repo: \(aqC:\epath\eto\ewin\erepo\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This path still needs to be within the minion\(aqs \fBfile_roots\fP, +just as when managing the Windows Repo on the master. +.UNINDENT +.UNINDENT +.SS Minion Config Options for Releases 2015.8.0 and Newer +.sp +The \fBwinrepo_source_dir\fP config parameter (default: +\fBsalt://win/repo\fP) controls where \fBpkg.refresh_db\fP looks for the cachefile (default: +\fBwinrepo.p\fP). This means that the default location for the winrepo cachefile +would be \fBsalt://win/repo/winrepo.p\fP\&. Both \fBwinrepo_source_dir\fP +and \fBwinrepo_cachefile\fP can be adjusted to match the actual +location of this file on the Salt fileserver. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Additional Info for Standalone Minions +.sp +The above still holds true regarding \fBwinrepo_source_dir\fP, the +differences are that the minion\(aqs \fBfile_roots\fP is where that +\fBsalt://\fP URL will resolve, and the \fBwinrepo\fP execution module must be used to generate this +cachefile. +.sp +If \fBfile_roots\fP has not been modified in the minion +configuration, then no additional configuration needs to be added to the +minion configuration. The \fBwinrepo.genrepo\fP function from the \fBwinrepo\fP execution module will by default look for the +filename specified by \fBwinrepo_cachefile\fP within +\fBC:\esalt\esrv\esalt\ewin\erepo\fP\&. If the \fBfile_roots\fP parameter +has been modified, then \fBwinrepo_dir\fP must be modified to fall +within that path, at the proper relative path. For example, if the +\fBbase\fP environment in \fBfile_roots\fP points to \fBD:\efoo\fP, and +\fBwinrepo_source_dir\fP is \fBsalt://win/repo\fP, then +\fBwinrepo_dir\fP must be set to \fBD:\efoo\ewin\erepo\fP to ensure +that \fBwinrepo.genrepo\fP puts the +cachefile into right location. +.UNINDENT +.UNINDENT +.SS Maintaining Windows Repo Definitions in Git Repositories .sp Windows software package definitions can also be hosted in one or more git -repositories. The default repo is one hosted on GitHub.com by SaltStack,Inc., which -includes package definitions for open source software. This repo points to the -HTTP or ftp locations of the installer files. Anyone is welcome to send a pull -request to this repo to add new package definitions. Browse the repo -here: \fI\%https://github.com/saltstack/salt\-winrepo\fP . +repositories. The default repository configured is hosted on GitHub.com by +SaltStack, Inc. It includes package definitions for various open source +software projects. .sp -Configure which git repos the master can search for package definitions by -modifying or extending the \fBwin_gitrepos\fP configuration option list in the -master config. +This repo points to the HTTP or ftp locations of the installer files. Anyone is +welcome to send a pull request to this repo to add new package definitions. +Browse the repo here: \fI\%https://github.com/saltstack/salt\-winrepo.git\fP . .sp -Checkout each git repo in \fBwin_gitrepos\fP, compile your package repository -cache and then refresh each minion\(aqs package cache: +Configure which git repositories the master can search for package definitions +by modifying or extending the \fBwinrepo_remotes\fP option (\fBNOTE:\fP +this option was called \fBwin_gitrepos\fP in Salt versions prior to 2015.8.0). +.sp +Use the \fBwinrepo.update_git_repos\fP runner to clone/update the configured +repos, then use \fBwinrepo.genrepo\fP +runner to compile the repository cache. Finally, use \fBpkg.refresh_db\fP on each minion to have them update their +copy of the repository cache. Command examples are as follows: .INDENT 0.0 .INDENT 3.5 .sp @@ -18922,20 +19281,190 @@ cache and then refresh each minion\(aqs package cache: .ft C salt\-run winrepo.update_git_repos salt\-run winrepo.genrepo -salt \(aq*\(aq pkg.refresh_db +salt winminion pkg.refresh_db .ft P .fi .UNINDENT .UNINDENT +.sp +For standalone minions, the usage would be slightly different: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-call winrepo.update_git_repos +salt\-call winrepo.genrepo +salt\-call pkg.refresh_db +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Changes in Version 2015.8.0 +.SS Config Parameters Renamed +.sp +Many of the winrepo configuration parameters have changed in version 2015.8.0 +to make the naming more consistent. The old parameter names will still work, +but a warning will be logged indicating that the old name is deprecated. Below +are the parameters which have changed for version 2015.8.0: +.SS Master Config +.TS +center; +|l|l|. +_ +T{ +Old Name +T} T{ +New Name +T} +_ +T{ +win_repo +T} T{ +\fBwinrepo_dir\fP +T} +_ +T{ +win_repo_mastercachefile +T} T{ +\fBwinrepo_cachefile\fP +T} +_ +T{ +win_gitrepos +T} T{ +\fBwinrepo_remotes\fP +T} +_ +.TE +.sp +See \fIhere\fP for detailed information on all +master config options for the Windows Repo. +.SS Minion Config +.TS +center; +|l|l|. +_ +T{ +Old Name +T} T{ +New Name +T} +_ +T{ +win_repo +T} T{ +\fBwinrepo_dir\fP +T} +_ +T{ +win_repo_cachefile +T} T{ +\fBwinrepo_cachefile\fP +T} +_ +T{ +win_gitrepos +T} T{ +\fBwinrepo_remotes\fP +T} +_ +.TE +.sp +See \fIhere\fP for detailed information on all +minion config options for the Windows Repo. +.SS \fI\%GitPython\fP/\fI\%pygit2\fP Support for Maintaining Git Repos +.sp +The \fBwinrepo.update_git_repos\fP +runner (and the corresponding \fBremote execution function\fP for standalone minions) now makes use +of the same underlying code used by the \fIGit Fileserver Backend\fP and \fBGit External Pillar\fP to +maintain and update its local clones of git repositories. If a compatible +version of either \fI\%pygit2\fP (0.20.3 and later) or \fI\%GitPython\fP (0.3.0 or later) is +installed, then Salt will use it instead of the old method (which invokes the +\fBgit.latest\fP state). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If compatible versions of both \fI\%pygit2\fP and \fI\%GitPython\fP are installed, then +Salt will prefer \fI\%pygit2\fP, to override this behavior use the +\fBwinrepo_provider\fP configuration parameter: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_provider: gitpython +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBwinrepo execution module\fP (discussed +above in the \fI\%Managing Windows Software on a Standalone Windows Minion\fP section) does not yet support the new +\fI\%GitPython\fP/\fI\%pygit2\fP functionality. +.UNINDENT +.UNINDENT +.sp +One important change this brings is the the fact that each repo configured +under the \fBwinrepo_remotes\fP option (\fBwin_gitrepos\fP in Salt +versions prior to 2015.8.0) will have its URL hashed and and the files will be +checked out into a subdirectory containing that hashed name (for example, +\fB/srv/salt/win/repo/f42c3382aeeaa8733908e5c256dba1ca/myprogram.sls\fP). There +is no functional reason for the hashed name, it just comes from using the same +back\-end code that gitfs and git_pillar are using. +.sp +To minimize potential issues, it is a good idea to remove any winrepo git +repositories that were checked out by the old (pre\-2015.8.0) winrepo code when +upgrading the master to 2015.8.0 or later, and run +\fBwinrepo.update_git_repos\fP to +clone them anew after the master is started. +.sp +Additional added features include the ability to access authenticated git +repositories (\fBNOTE:\fP \fI\%pygit2\fP only), and to set per\-remote config settings. An +example of this would be the following: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_remotes: + \- https://github.com/saltstack/salt\-winrepo.git + \- git@github.com:myuser/myrepo.git: + \- pubkey: /path/to/key.pub + \- privkey: /path/to/key + \- passphrase: myaw3s0m3pa$$phr4$3 + \- https://github.com/myuser/privaterepo.git: + \- user: mygithubuser + \- password: CorrectHorseBatteryStaple +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Per\-remote configuration settings work in the same fashion as they do in +gitfs, with global parameters being overridden by their per\-remote +counterparts (for instance, setting \fBwinrepo_passphrase\fP would +set a global passphrase for winrepo that would apply to all SSH\-based +remotes, unless overridden by a \fBpassphrase\fP per\-remote parameter). +.sp +See \fIhere\fP for more a more in\-depth +explanation of how per\-remote configuration works in gitfs, the same +principles apply to winrepo. +.UNINDENT +.UNINDENT .SS Troubleshooting .SS Incorrect name/version .sp -If the package seems to install properly, but salt reports a failure -then it is likely you have a version or \fBfull_name\fP mismatch. +If the package seems to install properly, but salt reports a failure then it is +likely you have a version or \fBfull_name\fP mismatch. .sp Check the exact \fBfull_name\fP and version used by the package. Use -\fBpkg.list_pkgs\fP to check that the names and version exactly match -what is installed. +\fBpkg.list_pkgs\fP to check that the names and version exactly match what is +installed. .SS Changes to sls files not being picked up .sp Ensure you have (re)generated the repository cache file and then @@ -18946,7 +19475,7 @@ updated the repository cache on the relevant minions: .nf .ft C salt\-run winrepo.genrepo -salt \(aqMINION\(aq pkg.refresh_db +salt winminion pkg.refresh_db .ft P .fi .UNINDENT @@ -19002,7 +19531,7 @@ Follow \fI\%issue 11801\fP for any changes to this behavior. .SS Dealing with various username forms .sp Salt does not understand the various forms that Windows usernames can come in, -e.g. username, mydomainusername, \fI\%username@mydomain.tld\fP can all refer to the +e.g. username, mydomain\eusername, \fI\%username@mydomain.tld\fP can all refer to the same user. In fact, Salt generally only considers the raw username value, i.e. the username without the domain or host information. .sp @@ -19037,9 +19566,9 @@ changing file permissions, besides modifying the owner/user. Salt Cloud is built\-in to Salt and is configured on and executed from your Salt Master. .SS Define a Provider .sp -The first step is to add the credentials for your cloud provider. Credentials -and provider settings are stored in provider configuration files. -Provider configurations contain the details needed to connect to a cloud provider such as EC2, GCE, Rackspace, etc., +The first step is to add the credentials for your cloud host. Credentials +and other settings provided by the cloud host are stored in provider configuration files. +Provider configurations contain the details needed to connect to a cloud host such as EC2, GCE, Rackspace, etc., and any global options that you want set on your cloud minions (such as the location of your Salt Master). .sp On your Salt Master, browse to \fB/etc/salt/cloud.providers.d/\fP and create a file called \fB.provider.conf\fP, @@ -19047,7 +19576,7 @@ replacing \fB\fP with \fBec2\fP, \fBsoftlayer\fP, and so on. The name important as long as the file ends in \fB\&.conf\fP\&. .sp Next, browse to the \fI\%Provider specifics\fP and add any required settings for your -provider to this file. Here is an example for Amazon EC2: +cloud host to this file. Here is an example for Amazon EC2: .INDENT 0.0 .INDENT 3.5 .sp @@ -19073,7 +19602,7 @@ my\-ec2: .UNINDENT .UNINDENT .sp -The required configuration varies between providers so make sure you read the provider specifics. +The required configuration varies between cloud hosts so make sure you read the provider specifics. .SS List Cloud Provider Options .sp You can now query the cloud provider you configured for available locations, @@ -19402,7 +19931,8 @@ using the Python \fBpprint\fP standard library module. .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. -Without the static option, you will get a JSON string for each minion. +Without the static option, you will get a separate JSON string per minion +which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT @@ -19545,7 +20075,7 @@ Assuming there is a profile configured as following: .nf .ft C fedora_rackspace: - provider: rackspace + provider: my\-rackspace\-config image: Fedora 17 size: 256 server script: bootstrap\-salt @@ -19601,7 +20131,7 @@ a yaml configuration. The syntax for declaring profiles is simple: .nf .ft C fedora_rackspace: - provider: rackspace + provider: my\-rackspace\-config image: Fedora 17 size: 256 server script: bootstrap\-salt @@ -19615,14 +20145,14 @@ and does not normally need to be specified. Further examples in this document will not show the \fBscript\fP option. .sp A few key pieces of information need to be declared and can change based on the -public cloud provider. A number of additional parameters can also be inserted: +cloud provider. A number of additional parameters can also be inserted: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos_rackspace: - driver: rackspace + provider: my\-rackspace\-config image: CentOS 6.2 size: 1024 server minion: @@ -19669,45 +20199,45 @@ management tools as well as version control systems. .nf .ft C rhel_ec2: - provider: ec2 + provider: my\-ec2\-config image: ami\-e565ba8c size: t1.micro minion: cheese: edam ubuntu_ec2: - provider: ec2 + provider: my\-ec2\-config image: ami\-7e2da54e size: t1.micro minion: cheese: edam ubuntu_rackspace: - provider: rackspace + provider: my\-rackspace\-config image: Ubuntu 12.04 LTS size: 256 server minion: cheese: edam fedora_rackspace: - provider: rackspace + provider: my\-rackspace\-config image: Fedora 17 size: 256 server minion: cheese: edam cent_linode: - provider: linode + provider: my\-linode\-config image: CentOS 6.2 64bit size: Linode 512 cent_gogrid: - provider: gogrid + provider: my\-gogrid\-config image: 12834 size: 512MB cent_joyent: - provider: joyent + provider: my\-joyent\-config image: centos\-6 size: Small 1GB .ft P @@ -20130,7 +20660,7 @@ and its listening port, if the port is not set to the default. .sp The data specific to interacting with public clouds is set up here. .sp -Cloud provider configuration syntax can live in several places. The first is in +Cloud provider configuration settings can live in several places. The first is in \fB/etc/salt/cloud\fP: .INDENT 0.0 .INDENT 3.5 @@ -20281,13 +20811,13 @@ cloud: profiles: ubuntu\-nova: - driver: my\-nova + provider: my\-nova size: performance1\-8 image: bb02b1a3\-bc77\-4d17\-ab5b\-421d89850fca script_args: git develop ubuntu\-openstack: - driver: my\-openstack + provider: my\-openstack size: performance1\-8 image: bb02b1a3\-bc77\-4d17\-ab5b\-421d89850fca script_args: git develop @@ -20334,7 +20864,7 @@ Rackspace cloud requires two configuration options; a \fBuser\fP and an \fBapike my\-rackspace\-config: user: example_user apikey: 123984bjjas87034 - driver: rackspace\-config + driver: rackspace .ft P .fi .UNINDENT @@ -20624,7 +21154,7 @@ In the cloud profile that uses this provider configuration, the syntax for the .SS Proxmox .sp Using Salt with Proxmox requires a \fBuser\fP, \fBpassword\fP, and \fBURL\fP\&. These can be -obtained from your cloud provider. Both PAM and PVE users can be used. +obtained from your cloud host. Both PAM and PVE users can be used. .INDENT 0.0 .INDENT 3.5 .sp @@ -20672,7 +21202,7 @@ And in the map file: .nf .ft C devhost10\-lxc: - driver: devhost10\-lxc + provider: devhost10\-lxc from_container: ubuntu backing: lvm sudo: True @@ -21065,7 +21595,7 @@ windows\-server\-2012: .SS Getting Started With Aliyun ECS .sp The Aliyun ECS (Elastic Computer Service) is one of the most popular public -cloud providers in China. This cloud provider can be used to manage aliyun +cloud hosts in China. This cloud host can be used to manage aliyun instance using salt\-cloud. .sp \fI\%http://www.aliyun.com/\fP @@ -21096,6 +21626,20 @@ my\-aliyun\-config: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Profiles .SS Cloud Profiles .sp @@ -21107,7 +21651,7 @@ Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the .nf .ft C aliyun_centos: - driver: my\-aliyun\-config + provider: my\-aliyun\-config size: ecs.t1.small location: cn\-qingdao securitygroup: G1989096784427999 @@ -21336,6 +21880,20 @@ Azure via the "Upload a Management Certificate" action of the "Management Certif tab within the "Settings" section of the management portal. .sp Optionally, a \fBmanagement_host\fP may be configured, if necessary for the region. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: @@ -22884,7 +23442,7 @@ Number of times to retry download of blob chunk if an error occurs. Sleep time in secs between retries. .SS Getting Started With DigitalOcean .sp -DigitalOcean is a public cloud provider that specializes in Linux instances. +DigitalOcean is a public cloud host that specializes in Linux instances. .SS Configuration .sp Using Salt for DigitalOcean requires a \fBpersonal_access_token\fP, an \fBssh_key_file\fP, @@ -22910,6 +23468,20 @@ my\-digitalocean\-config: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Profiles .SS Cloud Profiles .sp @@ -23062,9 +23634,9 @@ Additional documentation is available from \fI\%DigitalOcean\fP\&. Amazon EC2 is a very widely used public cloud platform and one of the core platforms Salt Cloud has been built to support. .sp -Previously, the suggested provider for AWS EC2 was the \fBaws\fP provider. This -has been deprecated in favor of the \fBec2\fP provider. Configuration using the -old \fBaws\fP provider will still function, but that driver is no longer in +Previously, the suggested driver for AWS EC2 was the \fBaws\fP driver. This +has been deprecated in favor of the \fBec2\fP driver. Configuration using the +old \fBaws\fP driver will still function, but that driver is no longer in active development. .SS Dependencies .sp @@ -23204,6 +23776,20 @@ my\-ec2\-southeast\-private\-ips: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Access Credentials .sp The \fBid\fP and \fBkey\fP settings may be found in the Security Credentials area @@ -23314,13 +23900,13 @@ Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: base_ec2_private: provider: my\-ec2\-southeast\-private\-ips image: ami\-e565ba8c - size: t1.micro + size: t2.micro ssh_username: ec2\-user base_ec2_public: provider: my\-ec2\-southeast\-public\-ips image: ami\-e565ba8c - size: t1.micro + size: t2.micro ssh_username: ec2\-user base_ec2_db: @@ -24274,7 +24860,7 @@ profile where the interfaces are manually configured like this. These are both really properties of each network interface, not of the machine itself. .SS Getting Started With GoGrid .sp -GoGrid is a public cloud provider supporting Linux and Windows. +GoGrid is a public cloud host that supports Linux and Windows. .SS Configuration .sp To use Salt Cloud with GoGrid log into the GoGrid web interface and create an @@ -24310,6 +24896,20 @@ with the GoGrid driver. Map files will work with GoGrid, but the \fB\-P\fP argument should not be used on maps referencing GoGrid instances. .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Profiles .SS Cloud Profiles .sp @@ -24544,6 +25144,20 @@ The value provided for \fBproject\fP must not contain underscores or spaces and is labeled as "Project ID" on the Google Developers Console. .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: @@ -25160,6 +25774,20 @@ hpcloud\-config: .UNINDENT .sp The subsequent example that follows is using the openstack driver. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Compute Region .sp Originally, HP Cloud, in its OpenStack Essex version (1.0), had 3 @@ -25307,7 +25935,7 @@ hp_ae1_ubuntu: With this setup, salt\-cloud will use the private IP address to ssh into the instance and set up the salt\-minion .SS Getting Started With Joyent .sp -Joyent is a public cloud provider supporting SmartOS, Linux, FreeBSD, and +Joyent is a public cloud host that supports SmartOS, Linux, FreeBSD, and Windows. .SS Dependencies .sp @@ -25336,6 +25964,20 @@ my\-joyent\-config: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Profiles .SS Cloud Profiles .sp @@ -25494,13 +26136,6 @@ You can only act on one minion and one provider at a time. Listing images must be targeted to a particular LXC provider (nothing will be outputted with \fBall\fP) .UNINDENT -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -On pre \fB2015.5.2\fP, you need to specify explitly the network bridge -.UNINDENT -.UNINDENT .SS Operation .sp Salt\(aqs LXC support does use \fBlxc.init\fP @@ -25546,6 +26181,20 @@ devhost10\-lxc: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Profile configuration .sp Please read \fItutorial\-lxc\fP before anything else. @@ -25731,7 +26380,7 @@ Running container information (IP addresses, etc.) .UNINDENT .SS Getting Started With Linode .sp -Linode is a public cloud provider with a focus on Linux instances. +Linode is a public cloud host with a focus on Linux instances. .sp Starting with the 2015.8.0 release of Salt, the Linode driver uses Linode\(aqs native REST API. There are no external dependencies required to use the @@ -25761,6 +26410,20 @@ my\-linode\-config: .sp The password needs to be 8 characters and contain lowercase, uppercase, and numbers. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Profiles .SS Cloud Profiles .sp @@ -25970,6 +26633,20 @@ my\-openstack\-config: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Using nova client to get information from OpenStack .sp One of the best ways to get information about OpenStack is using the novaclient @@ -26083,7 +26760,7 @@ userdata_file: /etc/salt/cloud\-init/packages.yml .sp Parallels Cloud Server is a product by Parallels that delivers a cloud hosting solution. The PARALLELS module for Salt Cloud enables you to manage instances -hosted by a provider using PCS. Further information can be found at: +hosted using PCS. Further information can be found at: .sp \fI\%http://www.parallels.com/products/pcs/\fP .INDENT 0.0 @@ -26105,7 +26782,7 @@ minion: PARALLELS.user: myuser PARALLELS.password: badpass -# Set the access URL for your PARALLELS provider +# Set the access URL for your PARALLELS host # PARALLELS.url: https://api.cloud.xmission.com:4465/paci/v1.0/ .ft P @@ -26142,36 +26819,29 @@ my\-parallels\-config: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Access Credentials .sp The \fBuser\fP, \fBpassword\fP, and \fBurl\fP will be provided to you by your cloud -provider. These are all required in order for the PARALLELS driver to work. +host. These are all required in order for the PARALLELS driver to work. .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/parallels.conf\fP: .INDENT 0.0 -.IP \(bu 2 -Using the old cloud configuration format: -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -parallels\-ubuntu: - provider: parallels - image: ubuntu\-12.04\-x86_64 -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.IP \(bu 2 -Using the new cloud configuration format and the cloud configuration example -from above: -.UNINDENT -.INDENT 0.0 .INDENT 3.5 .sp .nf @@ -26196,7 +26866,7 @@ The profile can be realized now with a salt command: .UNINDENT .UNINDENT .sp -This will create an instance named \fBmyubuntu\fP on the cloud provider. The +This will create an instance named \fBmyubuntu\fP on the cloud host. The minion that is installed on this instance will have an \fBid\fP of \fBmyubuntu\fP\&. If the command was executed on the salt\-master, its Salt key will automatically be signed on the master. @@ -26254,8 +26924,8 @@ my\-parallels\-config: .sp Unlike other cloud providers in Salt Cloud, Parallels does not utilize a \fBsize\fP setting. This is because Parallels allows the end\-user to specify a -more detailed configuration for their instances, than is allowed by many other -cloud providers. The following options are available to be used in a profile, +more detailed configuration for their instances than is allowed by many other +cloud hosts. The following options are available to be used in a profile, with their default settings listed. .INDENT 0.0 .INDENT 3.5 @@ -26331,7 +27001,7 @@ my\-proxmox\-config: user: myuser@pve password: badpass - # Set the access URL for your PROXMOX provider + # Set the access URL for your PROXMOX host # url: your.proxmox.host driver: proxmox @@ -26339,10 +27009,24 @@ my\-proxmox\-config: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Access Credentials .sp The \fBuser\fP, \fBpassword\fP, and \fBurl\fP will be provided to you by your cloud -provider. These are all required in order for the PROXMOX driver to work. +host. These are all required in order for the PROXMOX driver to work. .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or @@ -26357,7 +27041,7 @@ Configure a profile to be used: .nf .ft C proxmox\-ubuntu: - provider: proxmox + provider: my\-proxmox\-config image: local:vztmpl/ubuntu\-12.04\-standard_12.04\-1_amd64.tar.gz technology: openvz host: myvmhost @@ -26380,7 +27064,7 @@ The profile can be realized now with a salt command: .UNINDENT .UNINDENT .sp -This will create an instance named \fBmyubuntu\fP on the cloud provider. The +This will create an instance named \fBmyubuntu\fP on the cloud host. The minion that is installed on this instance will have a \fBhostname\fP of \fBmyubuntu\fP\&. If the command was executed on the salt\-master, its Salt key will automatically be signed on the master. @@ -26470,7 +27154,7 @@ image: local:vztmpl/ubuntu\-12.04\-standard_12.04\-1_amd64.tar.gz Rackspace is a major public cloud platform which may be configured using either the \fIrackspace\fP or the \fIopenstack\fP driver, depending on your needs. .sp -Please note that the \fIrackspace\fP driver is only intended for 1st gen instances, +Please note that the \fIrackspace\fP driver is intended only for 1st gen instances, aka, "the old cloud" at Rackspace. It is required for 1st gen instances, but will \fInot\fP work with OpenStack\-based instances. Unless you explicitly have a reason to use it, it is highly recommended that you use the \fIopenstack\fP driver @@ -26543,6 +27227,20 @@ my\-rackspace\-config: .sp The settings that follow are for using Rackspace with the \fIopenstack\fP driver, and will not work with the \fIrackspace\fP driver. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Compute Region .sp Rackspace currently has six compute regions which may be used: @@ -26681,9 +27379,9 @@ FreeBSD\-9.0\-512: .UNINDENT .SS Private Subnets .sp -By default salt\-cloud will not add Rackspace private networks to new servers. To enable +By default salt\-cloud will not add Rackspace private networks to new servers. To enable a private network to a server instantiated by salt cloud, add the following section -to the provider file (typically \fB/etc/salt/cloud.providers.d/rackspace.conf\fP) +to the provider file (typically \fB/etc/salt/cloud.providers.d/rackspace.conf\fP) .INDENT 0.0 .INDENT 3.5 .sp @@ -26716,7 +27414,7 @@ subnet IP, update the interface: line in the /etc/salt/master file to be the pri subnet IP of the salt master. .SS Getting Started With Scaleway .sp -Scaleway is the first IaaS provider worldwide to offer an ARM based cloud. It’s the ideal platform for horizontal scaling with BareMetal SSD servers. The solution provides on demand resources: it comes with on\-demand SSD storage, movable IPs , images, security group and an Object Storage solution. \fI\%https://scaleway.com\fP +Scaleway is the first IaaS host worldwide to offer an ARM based cloud. It’s the ideal platform for horizontal scaling with BareMetal SSD servers. The solution provides on demand resources: it comes with on\-demand SSD storage, movable IPs , images, security group and an Object Storage solution. \fI\%https://scaleway.com\fP .SS Configuration .sp Using Salt for Scaleway, requires an \fBaccess key\fP and an \fBAPI token\fP\&. \fBAPI tokens\fP are unique identifiers associated with your Scaleway account. @@ -26739,6 +27437,20 @@ my\-scaleway\-config: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Profiles .SS Cloud Profiles .sp @@ -26828,7 +27540,7 @@ Additional documentation about Scaleway can be found at \fI\%https://www.scalewa .UNINDENT .SS Getting Started With SoftLayer .sp -SoftLayer is a public cloud provider, and baremetal hardware hosting provider. +SoftLayer is a public cloud host, and baremetal hardware hosting service. .SS Dependencies .sp The SoftLayer driver for Salt Cloud requires the softlayer package, which is @@ -26884,6 +27596,20 @@ Set up the cloud config at \fB/etc/salt/cloud.providers\fP: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Access Credentials .sp The \fIuser\fP setting is the same user as is used to log into the SoftLayer @@ -27278,7 +28004,7 @@ The \fIglobalIdentifier\fP returned in this list is necessary for the \fIglobal_identifier\fP option when creating an image using a custom template. .SS Optional Products for SoftLayer HW .sp -The softlayer_hw provider supports the ability to add optional products, which +The softlayer_hw driver supports the ability to add optional products, which are supported by SoftLayer\(aqs API. These products each have an ID associated with them, that can be passed into Salt Cloud with the \fIoptional_products\fP option: .INDENT 0.0 @@ -27462,13 +28188,13 @@ here: .UNINDENT .SS Getting Started with VEXXHOST .sp -\fI\%VEXXHOST\fP is an cloud computing provider which provides +\fI\%VEXXHOST\fP is a cloud computing host which provides \fI\%Canadian cloud computing\fP services -which are based in Monteral and uses the libcloud OpenStack driver. VEXXHOST +which are based in Monteral and use the libcloud OpenStack driver. VEXXHOST currently runs the Havana release of OpenStack. When provisioning new instances, they automatically get a public IP and private IP address. Therefore, you do not need to assign a floating IP to access your instance -once it\(aqs booted. +after it\(aqs booted. .SS Cloud Provider Configuration .sp To use the \fIopenstack\fP driver for the VEXXHOST public cloud, you will need to @@ -27483,7 +28209,7 @@ driver. .sp .nf .ft C -vexxhost: +my\-vexxhost\-config: # Set the location of the salt\-master # minion: @@ -27514,6 +28240,20 @@ vexxhost: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Authentication .sp All of the authentication fields that you need can be found by logging into @@ -27545,7 +28285,7 @@ profile will build an Ubuntu 12.04 LTS \fInb.2G\fP instance. .nf .ft C vh_ubuntu1204_2G: - provider: vexxhost + provider: my\-vexxhost\-config image: 4051139f\-750d\-4d72\-8ef0\-074f2ccc7e5a size: nb.2G .ft P @@ -27625,22 +28365,24 @@ set up in the cloud configuration at .ft C my\-vmware\-config: driver: vmware - user: "DOMAIN\euser" - password: "verybadpass" - url: "vcenter01.domain.com" + user: \(aqDOMAIN\euser\(aq + password: \(aqverybadpass\(aq + url: \(aq10.20.30.40\(aq -vmware\-vcenter02: +vcenter01: driver: vmware - user: "DOMAIN\euser" - password: "verybadpass" - url: "vcenter02.domain.com" + user: \(aqDOMAIN\euser\(aq + password: \(aqverybadpass\(aq + url: \(aqvcenter01.domain.com\(aq + protocol: \(aqhttps\(aq + port: 443 -vmware\-vcenter03: +vcenter02: driver: vmware - user: "DOMAIN\euser" - password: "verybadpass" - url: "vcenter03.domain.com" - protocol: "http" + user: \(aqDOMAIN\euser\(aq + password: \(aqverybadpass\(aq + url: \(aqvcenter02.domain.com\(aq + protocol: \(aqhttp\(aq port: 80 .ft P .fi @@ -27655,6 +28397,20 @@ server is not using the defaults. Default is \fBprotocol: https\fP and \fBport: 443\fP\&. .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or @@ -27665,7 +28421,7 @@ Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or .nf .ft C vmware\-centos6.5: - provider: vmware\-vcenter01 + provider: vcenter01 clonefrom: test\-vm ## Optional arguments @@ -27752,6 +28508,8 @@ vmware\-centos6.5: /path/to/local/custom/script: /path/to/remote/script /path/to/local/file: /path/to/remote/file /srv/salt/yum/epel.repo: /etc/yum.repos.d/epel.repo + + hardware_version: 10 .ft P .fi .UNINDENT @@ -28036,6 +28794,10 @@ Specify file/files you want to copy to the VM before the bootstrap script is run and salt is installed. A good example of using this would be if you need to put custom repo files on the server in case your server will be in a private network and cannot reach external networks. +.TP +.B \fBhardware_version\fP +Specify the virtual hardware version for the vm/template that is supported by the +host. .UNINDENT .SS Getting Started With vSphere .sp @@ -28092,6 +28854,20 @@ my\-vsphere\-config: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changed in version 2015.8.0. + +.sp +The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This +change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile +definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that +provides the underlying functionality to connect to a cloud host, while cloud profiles continue +to use \fBprovider\fP to refer to provider configurations that you define. +.UNINDENT +.UNINDENT .SS Profiles .SS Cloud Profiles .sp @@ -28194,7 +28970,7 @@ to pass arguments to the deploy script: .nf .ft C ec2\-amazon: - provider: ec2 + provider: my\-ec2\-config image: ami\-1624987f size: t1.micro ssh_username: ec2\-user @@ -28307,7 +29083,7 @@ master: .sp When Salt Cloud deploys an instance, the SSH pub key for the instance is added to the known_hosts file for the user that ran the salt\-cloud command. When an -instance is deployed, a cloud provider generally recycles the IP address for +instance is deployed, a cloud host generally recycles the IP address for the instance. When Salt Cloud attempts to deploy an instance using a recycled IP address that has previously been accessed from the same machine, the old key in the known_hosts file will cause a conflict. @@ -28383,7 +29159,7 @@ definition. .SS wait_for_ip_timeout .sp The amount of time Salt Cloud should wait for a VM to start and get an IP back -from the cloud provider. +from the cloud host. Default: varies by cloud provider ( between 5 and 25 minutes) .SS wait_for_ip_interval .sp @@ -28427,7 +29203,7 @@ setting can be True or False. .SS diff_cache_events .sp When the cloud cachedir is being managed, if differences are encountered -between the data that is returned live from the cloud provider and the data in +between the data that is returned live from the cloud host and the data in the cache, fire events which describe the changes. This setting can be True or False. .sp @@ -28450,16 +29226,16 @@ cache_event_strip_fields: The following are events that can be fired based on this data. .SS salt/cloud/minionid/cache_node_new .sp -A new node was found on the cloud provider which was not listed in the cloud +A new node was found on the cloud host which was not listed in the cloud cachedir. A dict describing the new node will be contained in the event. .SS salt/cloud/minionid/cache_node_missing .sp A node that was previously listed in the cloud cachedir is no longer available -on the cloud provider. +on the cloud host. .SS salt/cloud/minionid/cache_node_diff .sp One or more pieces of data in the cloud cachedir has changed on the cloud -provider. A dict containing both the old and the new data will be contained in +host. A dict containing both the old and the new data will be contained in the event. .SS SSH Known Hosts .sp @@ -28632,7 +29408,7 @@ By default, Salt Cloud will create a directory on the target instance called \fB/tmp/.saltcloud/\fP\&. This directory should be owned by the user that is to execute the deploy script, and should have permissions of \fB0700\fP\&. .sp -Most cloud providers are configured to use \fBroot\fP as the default initial user +Most cloud hosts are configured to use \fBroot\fP as the default initial user for deployment, and as such, this directory and all files in it should be owned by the \fBroot\fP user. .sp @@ -28653,14 +29429,14 @@ copied to the \fB/etc/salt/\fP directory. .UNINDENT .SS Unprivileged Primary Users .sp -Some providers, most notably EC2, are configured with a different primary user. +Some cloud hosts, most notably EC2, are configured with a different primary user. Some common examples are \fBec2\-user\fP, \fBubuntu\fP, \fBfedora\fP, and \fBbitnami\fP\&. In these cases, the \fB/tmp/.saltcloud/\fP directory and all files in it should be owned by this user. .sp -Some providers, such as EC2, are configured to not require these users to +Some cloud hosts, such as EC2, are configured to not require these users to provide a password when using the \fBsudo\fP command. Because it is more secure -to require \fBsudo\fP users to provide a password, other providers are configured +to require \fBsudo\fP users to provide a password, other hosts are configured that way. .sp If this instance is required to provide a password, it needs to be configured @@ -28679,7 +29455,7 @@ sudo_password: mypassword .SS \fB/tmp/\fP is Mounted as \fBnoexec\fP .sp It is more secure to mount the \fB/tmp/\fP directory with a \fBnoexec\fP option. -This is uncommon on most cloud providers, but very common in private +This is uncommon on most cloud hosts, but very common in private environments. To see if the \fB/tmp/\fP directory is mounted this way, run the following command: .INDENT 0.0 @@ -28754,24 +29530,24 @@ cd /tmp/.saltcloud/ .UNINDENT .UNINDENT .SS Extending Salt Cloud -.SS Writing Cloud Provider Modules +.SS Writing Cloud Driver Modules .sp Salt Cloud runs on a module system similar to the main Salt project. The modules inside saltcloud exist in the \fBsalt/cloud/clouds\fP directory of the salt source. .sp -There are two basic types of cloud modules. If a cloud provider is supported by +There are two basic types of cloud modules. If a cloud host is supported by libcloud, then using it is the fastest route to getting a module written. The Apache Libcloud project is located at: .sp \fI\%http://libcloud.apache.org/\fP .sp -Not every cloud provider is supported by libcloud. Additionally, not every -feature in a supported cloud provider is necessary supported by libcloud. In +Not every cloud host is supported by libcloud. Additionally, not every +feature in a supported cloud host is necessarily supported by libcloud. In either of these cases, a module can be created which does not rely on libcloud. -.SS All Modules +.SS All Driver Modules .sp -The following functions are required by all modules, whether or not they are +The following functions are required by all driver modules, whether or not they are based on libcloud. .SS The __virtual__() Function .sp @@ -28799,10 +29575,10 @@ project. .sp The most important function that does need to be manually written is the \fBcreate()\fP function. This is what is used to request a virtual machine to be -created by the cloud provider, wait for it to become available, and then +created by the cloud host, wait for it to become available, and then (optionally) log in and install Salt on it. .sp -A good example to follow for writing a cloud provider module based on libcloud +A good example to follow for writing a cloud driver module based on libcloud is the module provided for Linode: .sp \fI\%https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/linode.py\fP @@ -28810,7 +29586,7 @@ is the module provided for Linode: The basic flow of a \fBcreate()\fP function is as follows: .INDENT 0.0 .IP \(bu 2 -Send a request to the cloud provider to create a virtual machine. +Send a request to the cloud host to create a virtual machine. .IP \(bu 2 Wait for the virtual machine to become available. .IP \(bu 2 @@ -28834,20 +29610,20 @@ configuration and environment variables. The first thing the \fBcreate()\fP function must do is fire an event stating that it has started the create process. This event is tagged \fBsalt/cloud//creating\fP\&. The payload contains the names of the VM, -profile and provider. +profile, and provider. .sp A set of kwargs is then usually created, to describe the parameters required -by the cloud provider to request the virtual machine. +by the cloud host to request the virtual machine. .sp An event is then fired to state that a virtual machine is about to be requested. It is tagged as \fBsalt/cloud//requesting\fP\&. The payload contains most -or all of the parameters that will be sent to the cloud provider. Any private +or all of the parameters that will be sent to the cloud host. Any private information (such as passwords) should not be sent in the event. .sp After a request is made, a set of deploy kwargs will be generated. These will be used to install Salt on the target machine. Windows options are supported -at this point, and should be generated, even if the cloud provider does not -currently support Windows. This will save time in the future if the provider +at this point, and should be generated, even if the cloud host does not +currently support Windows. This will save time in the future if the host does eventually decide to support Windows. .sp An event is then fired to state that the deploy process is about to begin. This @@ -28872,12 +29648,12 @@ manager. These do not need to be handled by the developer in the cloud module. .sp The \fBsalt.utils.cloud.validate_windows_cred()\fP function has been extended to take the number of retries and retry_delay parameters in case a specific cloud -provider has a delay between providing the Windows credentials and the +host has a delay between providing the Windows credentials and the credentials being available for use. In their \fBcreate()\fP function, or as a a sub\-function called during the creation process, developers should use the \fBwin_deploy_auth_retries\fP and \fBwin_deploy_auth_retry_delay\fP parameters from the provider configuration to allow the end\-user the ability to customize the -number of tries and delay between tries for their particular provider. +number of tries and delay between tries for their particular host. .sp After the appropriate deploy function completes, a final event is fired which describes the virtual machine that has just been created. This event is @@ -28887,12 +29663,12 @@ VM, profile, and provider. Finally, a dict (queried from the provider) which describes the new virtual machine is returned to the user. Because this data is not fired on the event bus it can, and should, return any passwords that were returned by the cloud -provider. In some cases (for example, Rackspace), this is the only time that +host. In some cases (for example, Rackspace), this is the only time that the password can be queried by the user; post\-creation queries may not contain -password information (depending upon the provider). +password information (depending upon the host). .SS The libcloudfuncs Functions .sp -A number of other functions are required for all cloud providers. However, with +A number of other functions are required for all cloud hosts. However, with libcloud\-based modules, these are all provided for free by the libcloudfuncs library. The following two lines set up the imports: .INDENT 0.0 @@ -28944,7 +29720,7 @@ required by the developer. When this is the case, some or all of the functions in \fBlibcloudfuncs\fP may be replaced. If they are all replaced, the libcloud imports should be absent from the Salt Cloud module. .sp -A good example of a non\-libcloud provider is the DigitalOcean module: +A good example of a non\-libcloud driver is the DigitalOcean driver: .sp \fI\%https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/digital_ocean.py\fP .SS The \fBcreate()\fP Function @@ -28961,8 +29737,8 @@ This function is only necessary for libcloud\-based modules, and does not need to exist otherwise. .SS The avail_locations() Function .sp -This function returns a list of locations available, if the cloud provider uses -multiple data centers. It is not necessary if the cloud provider only uses one +This function returns a list of locations available, if the cloud host uses +multiple data centers. It is not necessary if the cloud host uses only one data center. It is normally called using the \fB\-\-list\-locations\fP option. .INDENT 0.0 .INDENT 3.5 @@ -29346,7 +30122,7 @@ start_action: state.highstate .UNINDENT .sp This is currently considered to be experimental functionality, and may not work -well with all providers. If you experience problems with Salt Cloud hanging +well with all cloud hosts. If you experience problems with Salt Cloud hanging after Salt is deployed, consider using Startup States instead: .sp \fI\%http://docs.saltstack.com/ref/states/startup.html\fP @@ -29399,7 +30175,7 @@ Or even on the VM\(aqs profile settings: .nf .ft C ubuntu_aws: - provider: ec2 + provider: my\-ec2\-config image: ami\-7e2da54e size: t1.micro deploy: False @@ -29473,7 +30249,7 @@ to pass arguments to the deploy script: .nf .ft C aws\-amazon: - provider: ec2 + provider: my\-ec2\-config image: ami\-1624987f size: t1.micro ssh_username: ec2\-user @@ -29795,7 +30571,7 @@ presence of the instance will be managed statefully. .ft C my\-instance\-name: cloud.present: - \- driver: my\-ec2\-config + \- provider: my\-ec2\-config \- image: ami\-1624987f \- size: \(aqt1.micro\(aq \- ssh_username: ec2\-user @@ -29904,34 +30680,34 @@ pprint.pprint(nodes) .SS Feature Comparison .SS Feature Matrix .sp -A number of features are available in most cloud providers, but not all are +A number of features are available in most cloud hosts, but not all are available everywhere. This may be because the feature isn\(aqt supported by the -cloud provider itself, or it may only be that the feature has not yet been +cloud host itself, or it may only be that the feature has not yet been added to Salt Cloud. In a handful of cases, it is because the feature does not make sense for a particular cloud provider (Saltify, for instance). .sp -This matrix shows which features are available in which cloud providers, as far +This matrix shows which features are available in which cloud hosts, as far as Salt Cloud is concerned. This is not a comprehensive list of all features -available in all cloud providers, and should not be used to make business -decisions concerning choosing a cloud provider. In most cases, adding support +available in all cloud hosts, and should not be used to make business +decisions concerning choosing a cloud host. In most cases, adding support for a feature to Salt Cloud requires only a little effort. .SS Legacy Drivers .sp Both AWS and Rackspace are listed as "Legacy". This is because those drivers have been replaced by other drivers, which are generally the preferred method -for working with those providers. +for working with those hosts. .sp The EC2 driver should be used instead of the AWS driver, when possible. The OpenStack driver should be used instead of the Rackspace driver, unless the user is dealing with instances in "the old cloud" in Rackspace. .SS Note for Developers .sp -When adding new features to a particular cloud provider, please make sure to +When adding new features to a particular cloud host, please make sure to add the feature to this table. Additionally, if you notice a feature that is not properly listed here, pull requests to fix them is appreciated. .SS Standard Features .sp -These are features that are available for almost every provider. +These are features that are available for almost every cloud host. .TS center; |l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|. @@ -31502,7 +32278,7 @@ using the \fBec2\-config\fP provider, the payload for this tag would look like: .ft C {\(aqname\(aq: \(aqweb1\(aq, \(aqprofile\(aq: \(aqec2\-centos\(aq, - \(aqprovider\(aq: \(aqec2\-config\(aq} + \(aqprovider\(aq: \(aqec2\-config:ec2\(aq} .ft P .fi .UNINDENT @@ -31668,11 +32444,11 @@ options that can be specified is \fBstartup_states\fP, which is commonly set to \fBhighstate\fP\&. This will tell the minion to immediately apply a highstate, as soon as it is able to do so. .sp -This can present a problem with some system images on some cloud providers. For +This can present a problem with some system images on some cloud hosts. For instance, Salt Cloud can be configured to log in as either the \fBroot\fP user, or -a user with \fBsudo\fP access. While some providers commonly use images that +a user with \fBsudo\fP access. While some hosts commonly use images that lock out remote \fBroot\fP access and require a user with \fBsudo\fP privileges to -log in (notably EC2, with their \fBec2\-user\fP login), most cloud providers fall +log in (notably EC2, with their \fBec2\-user\fP login), most cloud hosts fall back to \fBroot\fP as the default login on all images, including for operating systems (such as Ubuntu) which normally disallow remote \fBroot\fP login. .sp @@ -31811,96 +32587,6 @@ Salt\(aqs client interfaces expose executing functions by crafting a dictionary values that are mapped to function arguments. This allows calling functions simply by creating a data structure. (And this is exactly how much of Salt\(aqs own internals work!) -.INDENT 0.0 -.TP -.B class salt.netapi.NetapiClient(opts) -Provide a uniform method of accessing the various client interfaces in Salt -in the form of low\-data data structures. For example: -.sp -.nf -.ft C ->>> client = NetapiClient(__opts__) ->>> lowstate = {\(aqclient\(aq: \(aqlocal\(aq, \(aqtgt\(aq: \(aq*\(aq, \(aqfun\(aq: \(aqtest.ping\(aq, \(aqarg\(aq: \(aq\(aq} ->>> client.run(lowstate) -.ft P -.fi -.INDENT 7.0 -.TP -.B local(*args, **kwargs) -Run \fIexecution modules\fP synchronously -.sp -See \fBsalt.client.LocalClient.cmd()\fP for all available -parameters. -.sp -Sends a command from the master to the targeted minions. This is the -same interface that Salt\(aqs own CLI uses. Note the \fBarg\fP and \fBkwarg\fP -parameters are sent down to the minion(s) and the given function, -\fBfun\fP, is called with those parameters. -.INDENT 7.0 -.TP -.B Returns -Returns the result from the execution module -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B local_async(*args, **kwargs) -Run \fIexecution modules\fP asynchronously -.sp -Wraps \fBsalt.client.LocalClient.run_job()\fP\&. -.INDENT 7.0 -.TP -.B Returns -job ID -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B local_batch(*args, **kwargs) -Run \fIexecution modules\fP against batches of minions -.sp -New in version 0.8.4. - -.sp -Wraps \fBsalt.client.LocalClient.cmd_batch()\fP -.INDENT 7.0 -.TP -.B Returns -Returns the result from the exeuction module for each batch of -returns -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B runner(fun, timeout=None, **kwargs) -Run \fIrunner modules \fP synchronously -.sp -Wraps \fBsalt.runner.RunnerClient.cmd_sync()\fP\&. -.sp -Note that runner functions must be called using keyword arguments. -Positional arguments are not supported. -.INDENT 7.0 -.TP -.B Returns -Returns the result from the runner module -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B wheel(fun, **kwargs) -Run \fIwheel modules\fP synchronously -.sp -Wraps \fBsalt.wheel.WheelClient.master_call()\fP\&. -.sp -Note that wheel functions must be called using keyword arguments. -Positional arguments are not supported. -.INDENT 7.0 -.TP -.B Returns -Returns the result from the wheel module -.UNINDENT -.UNINDENT -.UNINDENT .SH SALT VIRT .sp The Salt Virt cloud controller capability was initially added to Salt in @@ -32725,7 +33411,6 @@ _ T{ \fBstormpath\fP T} T{ -Provide authentication using Stormpath. T} _ T{ @@ -33201,45 +33886,6 @@ external_auth: .UNINDENT .UNINDENT .UNINDENT -.SS salt.auth.stormpath -.sp -Provide authentication using Stormpath. -.sp -This driver requires some extra configuration beyond that which Stormpath -normally requires. -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C - -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B stormpath: -apiid: 1234567890 -apikey: 1234567890/ABCDEF -# Can use an application ID -application: 6789012345 -# Or can use a directory ID -directory: 3456789012 -# But not both -.UNINDENT -.UNINDENT -.UNINDENT -.sp -New in version 2015.8.0. - -.INDENT 0.0 -.TP -.B salt.auth.stormpath.auth(username, password) -Authenticate using a Stormpath directory or application -.UNINDENT .SS salt.auth.yubico .sp Provide authentication using YubiKey. @@ -33778,7 +34424,8 @@ using the Python \fBpprint\fP standard library module. .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. -Without the static option, you will get a JSON string for each minion. +Without the static option, you will get a separate JSON string per minion +which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT @@ -33875,8 +34522,10 @@ query the minions and check on running jobs. Default: 5 .B \-s, \-\-static By default as of version 0.9.8 the salt command returns data to the console as it is received from minions, but previous releases would return -data only after all data was received. To only return the data with a hard -timeout and after all minions have returned then use the static option. +data only after all data was received. Use the static option to only return +the data with a hard timeout and after all minions have returned. +Without the static option, you will get a separate JSON string per minion +which makes JSON output invalid as a whole. .UNINDENT .INDENT 0.0 .TP @@ -34073,7 +34722,8 @@ using the Python \fBpprint\fP standard library module. .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. -Without the static option, you will get a JSON string for each minion. +Without the static option, you will get a separate JSON string per minion +which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT @@ -34343,7 +34993,8 @@ using the Python \fBpprint\fP standard library module. .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. -Without the static option, you will get a JSON string for each minion. +Without the static option, you will get a separate JSON string per minion +which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT @@ -34699,7 +35350,8 @@ using the Python \fBpprint\fP standard library module. .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. -Without the static option, you will get a JSON string for each minion. +Without the static option, you will get a separate JSON string per minion +which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT @@ -35029,6 +35681,98 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fIsalt(1)\fP \fIsalt(7)\fP \fIsalt\-master(1)\fP +.SS salt\-proxy +.SS \fBsalt\-proxy\fP +.sp +Receives commands from a Salt master and proxies these commands to +devices that are unable to run a full minion. +.SS Synopsis +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-proxy [ options ] +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Description +.sp +The Salt proxy minion receives commands from a Salt master, transmits +appropriate commands to devices that are unable to run a minion, and replies +with the results of said commands. +.SS Options +.INDENT 0.0 +.TP +.B \-\-proxyid +The minion id that this proxy will assume. This is required. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-version +Print the version of Salt that is running. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-versions\-report +Show program\(aqs dependencies and version number, and then exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +Show the help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir +The location of the Salt configuration directory. This directory +contains the configuration files for Salt master and minions. +The default location on most systems is \fB/etc/salt\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-u USER, \-\-user=USER +Specify user to run salt\-proxy +.UNINDENT +.INDENT 0.0 +.TP +.B \-d, \-\-daemon +Run salt\-proxy as a daemon +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-pid\-file PIDFILE +Specify the location of the pidfile. Default: \fB/var/run/salt\-proxy\-.pid\fP +.UNINDENT +.SS Logging Options +.sp +Logging options which override any settings defined on the configuration files. +.INDENT 0.0 +.TP +.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL +Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, +\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: +\fBwarning\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-log\-file=LOG_FILE +Log file path. Default: /var/log/salt/minion\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE +Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, +\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: +\fBwarning\fP\&. +.UNINDENT +.SS See also +.sp +\fIsalt(1)\fP +\fIsalt(7)\fP +\fIsalt\-master(1)\fP +\fIsalt\-minion(1)\fP .SS salt\-run .SS \fBsalt\-run\fP .sp @@ -35311,7 +36055,8 @@ using the Python \fBpprint\fP standard library module. .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. -Without the static option, you will get a JSON string for each minion. +Without the static option, you will get a separate JSON string per minion +which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT @@ -35861,7 +36606,7 @@ testmod[\(aqtest.ping\(aq]() .UNINDENT .INDENT 0.0 .TP -.B salt.loader.states(opts, functions, whitelist=None) +.B salt.loader.states(opts, functions, utils, whitelist=None) Returns the state modules .INDENT 7.0 .TP @@ -35883,7 +36628,7 @@ import salt.config import salt.loader __opts__ = salt.config.minion_config(\(aq/etc/salt/minion\(aq) -statemods = salt.loader.states(__opts__, None) +statemods = salt.loader.states(__opts__, None, None) .ft P .fi .UNINDENT @@ -36342,7 +37087,7 @@ caller = salt.client.Caller(mopts=__opts__) .INDENT 7.0 .TP .B cmd(fun, *args, **kwargs) -Call an execution module with the given arguments and keword arguments +Call an execution module with the given arguments and keyword arguments .sp Changed in version 2015.8.0: Added the \fBcmd\fP method for consistency with the other Salt clients. The existing \fBfunction\fP and \fBsminion.functions\fP interfaces still @@ -36364,210 +37109,7 @@ caller.cmd(\(aqevent.send\(aq, \(aqmyco/myevent/something\(aq, .UNINDENT .UNINDENT .SS RunnerClient -.INDENT 0.0 -.TP -.B class salt.runner.RunnerClient(opts) -The interface used by the \fBsalt\-run\fP CLI tool on the Salt Master -.sp -It executes \fIrunner modules\fP which run on the Salt -Master. -.sp -Importing and using \fBRunnerClient\fP must be done on the same machine as -the Salt Master and it must be done using the same user that the Salt -Master is running as. -.sp -Salt\(aqs \fBexternal_auth\fP can be used to authenticate calls. The -eauth user must be authorized to execute runner modules: (\fB@runner\fP). -Only the \fBmaster_call()\fP below supports eauth. -.INDENT 7.0 -.TP -.B async(fun, low, user=\(aqUNKNOWN\(aq) -Execute the function in a multiprocess and return the event tag to use -to watch for the return -.UNINDENT -.INDENT 7.0 -.TP -.B cmd(fun, arg=None, pub_data=None, kwarg=None) -Execute a function -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C ->>> opts = salt.config.master_config(\(aq/etc/salt/master\(aq) ->>> runner = salt.runner.RunnerClient(opts) ->>> runner.cmd(\(aqjobs.list_jobs\(aq, []) -{ - \(aq20131219215650131543\(aq: { - \(aqArguments\(aq: [300], - \(aqFunction\(aq: \(aqtest.sleep\(aq, - \(aqStartTime\(aq: \(aq2013, Dec 19 21:56:50.131543\(aq, - \(aqTarget\(aq: \(aq*\(aq, - \(aqTarget\-type\(aq: \(aqglob\(aq, - \(aqUser\(aq: \(aqsaltdev\(aq - }, - \(aq20131219215921857715\(aq: { - \(aqArguments\(aq: [300], - \(aqFunction\(aq: \(aqtest.sleep\(aq, - \(aqStartTime\(aq: \(aq2013, Dec 19 21:59:21.857715\(aq, - \(aqTarget\(aq: \(aq*\(aq, - \(aqTarget\-type\(aq: \(aqglob\(aq, - \(aqUser\(aq: \(aqsaltdev\(aq - }, -} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B cmd_async(low) -Execute a runner function asynchronously; eauth is respected -.sp -This function requires that \fBexternal_auth\fP is configured -and the user is authorized to execute runner functions: (\fB@runner\fP). -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -runner.eauth_async({ - \(aqfun\(aq: \(aqjobs.list_jobs\(aq, - \(aqusername\(aq: \(aqsaltdev\(aq, - \(aqpassword\(aq: \(aqsaltdev\(aq, - \(aqeauth\(aq: \(aqpam\(aq, -}) -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B cmd_sync(low, timeout=None) -Execute a runner function synchronously; eauth is respected -.sp -This function requires that \fBexternal_auth\fP is configured -and the user is authorized to execute runner functions: (\fB@runner\fP). -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -runner.eauth_sync({ - \(aqfun\(aq: \(aqjobs.list_jobs\(aq, - \(aqusername\(aq: \(aqsaltdev\(aq, - \(aqpassword\(aq: \(aqsaltdev\(aq, - \(aqeauth\(aq: \(aqpam\(aq, -}) -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT .SS WheelClient -.INDENT 0.0 -.TP -.B class salt.wheel.WheelClient(opts=None) -An interface to Salt\(aqs wheel modules -.sp -\fIWheel modules\fP interact with various parts of the -Salt Master. -.sp -Importing and using \fBWheelClient\fP must be done on the same machine as the -Salt Master and it must be done using the same user that the Salt Master is -running as. Unless \fBexternal_auth\fP is configured and the user -is authorized to execute wheel functions: (\fB@wheel\fP). -.sp -Usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -import salt.config -import salt.wheel -opts = salt.config.master_config(\(aq/etc/salt/master\(aq) -wheel = salt.wheel.WheelClient(opts) -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B async(fun, low, user=\(aqUNKNOWN\(aq) -Execute the function in a multiprocess and return the event tag to use -to watch for the return -.UNINDENT -.INDENT 7.0 -.TP -.B cmd(fun, arg=None, pub_data=None, kwarg=None) -Execute a function -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C ->>> wheel.cmd(\(aqkey.finger\(aq, [\(aqjerry\(aq]) -{\(aqminions\(aq: {\(aqjerry\(aq: \(aq5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca\(aq}} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B cmd_async(low) -Execute a function asynchronously; eauth is respected -.sp -This function requires that \fBexternal_auth\fP is configured -and the user is authorized -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C ->>> wheel.cmd_async({ - \(aqfun\(aq: \(aqkey.finger\(aq, - \(aqmatch\(aq: \(aqjerry\(aq, - \(aqeauth\(aq: \(aqauto\(aq, - \(aqusername\(aq: \(aqsaltdev\(aq, - \(aqpassword\(aq: \(aqsaltdev\(aq, -}) -{\(aqjid\(aq: \(aq20131219224744416681\(aq, \(aqtag\(aq: \(aqsalt/wheel/20131219224744416681\(aq} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B cmd_sync(low, timeout=None) -Execute a wheel function synchronously; eauth is respected -.sp -This function requires that \fBexternal_auth\fP is configured -and the user is authorized to execute runner functions: (\fB@wheel\fP). -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C ->>> wheel.cmd_sync({ -\(aqfun\(aq: \(aqkey.finger\(aq, -\(aqmatch\(aq: \(aqjerry\(aq, -\(aqeauth\(aq: \(aqauto\(aq, -\(aqusername\(aq: \(aqsaltdev\(aq, -\(aqpassword\(aq: \(aqsaltdev\(aq, -}) -{\(aqminions\(aq: {\(aqjerry\(aq: \(aq5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca\(aq}} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT .SS CloudClient .INDENT 0.0 .TP @@ -36727,32 +37269,6 @@ Query select instance information .UNINDENT .UNINDENT .SS SSHClient -.INDENT 0.0 -.TP -.B class salt.client.ssh.client.SSHClient(c_path=\(aq/etc/salt/master\(aq, mopts=None) -Create a client object for executing routines via the salt\-ssh backend -.sp -New in version 2015.5.0. - -.INDENT 7.0 -.TP -.B cmd(tgt, fun, arg=(), timeout=None, expr_form=\(aqglob\(aq, kwarg=None, **kwargs) -Execute a single command via the salt\-ssh subsystem and return all -routines at once -.sp -New in version 2015.5.0. - -.UNINDENT -.INDENT 7.0 -.TP -.B cmd_iter(tgt, fun, arg=(), timeout=None, expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, **kwargs) -Execute a single command via the salt\-ssh subsystem and return a -generator -.sp -New in version 2015.5.0. - -.UNINDENT -.UNINDENT .SS Full list of Salt Cloud modules .TS center; @@ -36790,13 +37306,11 @@ _ T{ \fBec2\fP T} T{ -The EC2 Cloud Module T} _ T{ \fBgce\fP T} T{ -Copyright 2013 Google Inc. T} _ T{ @@ -36808,7 +37322,6 @@ _ T{ \fBjoyent\fP T} T{ -Joyent Cloud Module T} _ T{ @@ -36992,6 +37505,11 @@ Return the first configured instance. .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.aliyun.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.aliyun.get_image(vm_) Return the image object to use .UNINDENT @@ -37234,6 +37752,11 @@ salt\-cloud \-a enable_term_protect mymachine .B salt.cloud.clouds.botocore_aws.get_configured_provider() Return the first configured instance. .UNINDENT +.INDENT 0.0 +.TP +.B salt.cloud.clouds.botocore_aws.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT .SS salt.cloud.clouds.cloudstack .SS CloudStack Cloud Module .sp @@ -37328,6 +37851,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.cloudstack.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.cloudstack.get_image(conn, vm_) Return the image object to use .UNINDENT @@ -37500,6 +38028,11 @@ Return the first configured instance. .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.digital_ocean.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.digital_ocean.get_image(vm_) Return the image object to use .UNINDENT @@ -37584,1413 +38117,6 @@ salt\-cloud \-f show_pricing my\-digitalocean\-config profile=my\-profile .fi .UNINDENT .UNINDENT -.UNINDENT -.SS salt.cloud.clouds.ec2 -.SS The EC2 Cloud Module -.sp -The EC2 cloud module is used to interact with the Amazon Elastic Cloud -Computing. -.INDENT 0.0 -.TP -.B To use the EC2 cloud module, set up the cloud configuration at -\fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/ec2.conf\fP: -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-ec2\-config: - # The EC2 API authentication id, set this and/or key to - # \(aquse\-instance\-role\-credentials\(aq to use the instance role credentials - # from the meta\-data if running on an AWS instance - id: GKTADJGHEIQSXMKKRBJ08H - # The EC2 API authentication key, set this and/or id to - # \(aquse\-instance\-role\-credentials\(aq to use the instance role credentials - # from the meta\-data if running on an AWS instance - key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs - # The ssh keyname to use - keyname: default - # The amazon security group - securitygroup: ssh_open - # The location of the private key which corresponds to the keyname - private_key: /root/default.pem - - # Be default, service_url is set to amazonaws.com. If you are using this - # driver for something other than Amazon EC2, change it here: - service_url: amazonaws.com - - # The endpoint that is ultimately used is usually formed using the region - # and the service_url. If you would like to override that entirely, you - # can explicitly define the endpoint: - endpoint: myendpoint.example.com:1138/services/Cloud - - # SSH Gateways can be used with this provider. Gateways can be used - # when a salt\-master is not on the same private network as the instance - # that is being deployed. - - # Defaults to None - # Required - ssh_gateway: gateway.example.com - - # Defaults to port 22 - # Optional - ssh_gateway_port: 22 - - # Defaults to root - # Optional - ssh_gateway_username: root - - # One authentication method is required. If both - # are specified, Private key wins. - - # Private key defaults to None - ssh_gateway_private_key: /path/to/key.pem - - # Password defaults to None - ssh_gateway_password: ExamplePasswordHere - - driver: ec2 -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B depends -requests -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.attach_volume(name=None, kwargs=None, instance_id=None, call=None) -Attach a volume to an instance -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.avail_images(kwargs=None, call=None) -Return a dict of all available VM images on the cloud provider. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.avail_locations(call=None) -List all available locations -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.avail_sizes(call=None) -Return a dict of all available VM sizes on the cloud provider with -relevant data. Latest version can be found at: -.sp -\fI\%http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance\-types.html\fP -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.block_device_mappings(vm_) -Return the block device mapping: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -[{\(aqDeviceName\(aq: \(aq/dev/sdb\(aq, \(aqVirtualName\(aq: \(aqephemeral0\(aq}, - {\(aqDeviceName\(aq: \(aq/dev/sdc\(aq, \(aqVirtualName\(aq: \(aqephemeral1\(aq}] -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.copy_snapshot(kwargs=None, call=None) -Copy a snapshot -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.create(vm_=None, call=None) -Create a single VM from a data dict -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.create_attach_volumes(name, kwargs, call=None, wait_to_finish=True) -Create and attach volumes to created node -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.create_keypair(kwargs=None, call=None) -Create an SSH keypair -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.create_snapshot(kwargs=None, call=None, wait_to_finish=False) -Create a snapshot -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.create_volume(kwargs=None, call=None, wait_to_finish=False) -Create a volume -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_volume my\-ec2\-config zone=us\-east\-1b -salt\-cloud \-f create_volume my\-ec2\-config zone=us\-east\-1b tags=\(aq{"tag1": "val1", "tag2", "val2"}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.del_tags(name=None, kwargs=None, call=None, instance_id=None, resource_id=None) -Delete tags for a resource. Normally a VM name or instance_id is passed in, -but a resource_id may be passed instead. If both are passed in, the -instance_id will be used. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a del_tags mymachine tags=mytag, -salt\-cloud \-a del_tags mymachine tags=tag1,tag2,tag3 -salt\-cloud \-a del_tags resource_id=vol\-3267ab32 tags=tag1,tag2,tag3 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.delete_keypair(kwargs=None, call=None) -Delete an SSH keypair -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.delete_snapshot(kwargs=None, call=None) -Delete a snapshot -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.delete_volume(name=None, kwargs=None, instance_id=None, call=None) -Delete a volume -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.delvol_on_destroy(name, kwargs=None, call=None) -Delete all/specified EBS volumes upon instance termination -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a delvol_on_destroy mymachine -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.describe_snapshots(kwargs=None, call=None) -Describe a snapshot (or snapshots) -.INDENT 7.0 -.TP -.B snapshot_id -One or more snapshot IDs. Multiple IDs must be separated by ",". -.TP -.B owner -Return the snapshots owned by the specified owner. Valid values -include: self, amazon, . Multiple values must be -separated by ",". -.TP -.B restorable_by -One or more AWS accounts IDs that can create volumes from the snapshot. -Multiple aws account IDs must be separated by ",". -.UNINDENT -.sp -TODO: Add all of the filters. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.describe_volumes(kwargs=None, call=None) -Describe a volume (or volumes) -.INDENT 7.0 -.TP -.B volume_id -One or more volume IDs. Multiple IDs must be separated by ",". -.UNINDENT -.sp -TODO: Add all of the filters. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.destroy(name, call=None) -Destroy a node. Will check termination protection and warn if enabled. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-\-destroy mymachine -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.detach_volume(name=None, kwargs=None, instance_id=None, call=None) -Detach a volume from an instance -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.disable_term_protect(name, call=None) -Disable termination protection on a node -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a disable_term_protect mymachine -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.enable_term_protect(name, call=None) -Enable termination protection on a node -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a enable_term_protect mymachine -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_availability_zone(vm_) -Return the availability zone to use -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_configured_provider() -Return the first configured instance. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_console_output(name=None, location=None, instance_id=None, call=None, kwargs=None) -Show the console output from the instance. -.sp -By default, returns decoded data, not the Base64\-encoded data that is -actually returned from the EC2 API. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_location(vm_=None) -.INDENT 7.0 -.TP -.B Return the EC2 region to use, in this order: -.INDENT 7.0 -.IP \(bu 2 -CLI parameter -.IP \(bu 2 -VM parameter -.IP \(bu 2 -Cloud profile setting -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_password_data(name=None, kwargs=None, instance_id=None, call=None) -Return password data for a Windows instance. -.sp -By default only the encrypted password data will be returned. However, if a -key_file is passed in, then a decrypted password will also be returned. -.sp -Note that the key_file references the private key that was used to generate -the keypair associated with this instance. This private key will _not_ be -transmitted to Amazon; it is only used internally inside of Salt Cloud to -decrypt data _after_ it has been received from Amazon. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a get_password_data mymachine -salt\-cloud \-a get_password_data mymachine key_file=/root/ec2key.pem -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Note: PKCS1_v1_5 was added in PyCrypto 2.5 -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_placementgroup(vm_) -Returns the PlacementGroup to use -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_provider(vm_=None) -Extract the provider name from vm -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_spot_config(vm_) -Returns the spot instance configuration for the provided vm -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_ssh_gateway_config(vm_) -Return the ssh_gateway configuration. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_subnetid(vm_) -Returns the SubnetId to use -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_tags(name=None, instance_id=None, call=None, location=None, kwargs=None, resource_id=None) -Retrieve tags for a resource. Normally a VM name or instance_id is passed -in, but a resource_id may be passed instead. If both are passed in, the -instance_id will be used. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a get_tags mymachine -salt\-cloud \-a get_tags resource_id=vol\-3267ab32 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.get_tenancy(vm_) -Returns the Tenancy to use. -.sp -Can be "dedicated" or "default". Cannot be present for spot instances. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.iam_profile(vm_) -Return the IAM profile. -.sp -The IAM instance profile to associate with the instances. -This is either the Amazon Resource Name (ARN) of the instance profile -or the name of the role. -.sp -Type: String -.sp -Default: None -.sp -Required: No -.sp -Example: arn:aws:iam::111111111111:instance\-profile/s3access -.sp -Example: s3access -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.keepvol_on_destroy(name, kwargs=None, call=None) -Do not delete all/specified EBS volumes upon instance termination -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a keepvol_on_destroy mymachine -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.keyname(vm_) -Return the keyname -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.list_nodes(call=None) -Return a list of the VMs that are on the provider -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.list_nodes_full(location=None, call=None) -Return a list of the VMs that are on the provider -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.list_nodes_min(location=None, call=None) -Return a list of the VMs that are on the provider. Only a list of VM names, -and their state, is returned. This is the minimum amount of information -needed to check for existing VMs. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.list_nodes_select(call=None) -Return a list of the VMs that are on the provider, with select fields -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.optimize_providers(providers) -Return an optimized list of providers. -.sp -We want to reduce the duplication of querying -the same region. -.sp -If a provider is using the same credentials for the same region -the same data will be returned for each provider, thus causing -un\-wanted duplicate data and API calls to EC2. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.query(params=None, setname=None, requesturl=None, location=None, return_url=False, return_root=False) -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.query_instance(vm_=None, call=None) -Query an instance upon creation from the EC2 API -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.queue_instances(instances) -Queue a set of instances to be provisioned later. Expects a list. -.sp -Currently this only queries node data, and then places it in the cloud -cache (if configured). If the salt\-cloud\-reactor is being used, these -instances will be automatically provisioned using that. -.sp -For more information about the salt\-cloud\-reactor, see: -.sp -\fI\%https://github.com/saltstack\-formulas/salt\-cloud\-reactor\fP -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.reboot(name, call=None) -Reboot a node. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a reboot mymachine -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.rename(name, kwargs, call=None) -Properly rename a node. Pass in the new name as "new name". -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a rename mymachine newname=yourmachine -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.request_instance(vm_=None, call=None) -Put together all of the information necessary to request an instance on EC2, -and then fire off the request the instance. -.sp -Returns data about the instance -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.script(vm_) -Return the script deployment object -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.securitygroup(vm_) -Return the security group -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.securitygroupid(vm_) -Returns the SecurityGroupId -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.set_tags(name=None, tags=None, call=None, location=None, instance_id=None, resource_id=None, kwargs=None) -Set tags for a resource. Normally a VM name or instance_id is passed in, -but a resource_id may be passed instead. If both are passed in, the -instance_id will be used. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a set_tags mymachine tag1=somestuff tag2=\(aqOther stuff\(aq -salt\-cloud \-a set_tags resource_id=vol\-3267ab32 tag=somestuff -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.show_delvol_on_destroy(name, kwargs=None, call=None) -Do not delete all/specified EBS volumes upon instance termination -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a show_delvol_on_destroy mymachine -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.show_image(kwargs, call=None) -Show the details from EC2 concerning an AMI -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.show_instance(name=None, instance_id=None, call=None, kwargs=None) -Show the details from EC2 concerning an AMI. -.sp -Can be called as an action (which requires a name): -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a show_instance myinstance -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\&...or as a function (which requires either a name or instance_id): -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_instance my\-ec2 name=myinstance -salt\-cloud \-f show_instance my\-ec2 instance_id=i\-d34db33f -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.show_keypair(kwargs=None, call=None) -Show the details of an SSH keypair -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.show_pricing(kwargs=None, call=None) -Show pricing for a particular profile. This is only an estimate, based on -unofficial pricing sources. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_pricing my\-ec2\-config profile=my\-profile -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If pricing sources have not been cached, they will be downloaded. Once they -have been cached, they will not be updated automatically. To manually update -all prices, use the following command: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_pricing -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -New in version 2015.8.0. - -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.show_term_protect(name=None, instance_id=None, call=None, quiet=False) -Show the details from EC2 concerning an AMI -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.show_volume(kwargs=None, call=None) -Wrapper around describe_volumes. -Here just to keep functionality. -Might be depreciated later. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.sign(key, msg) -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.ssh_interface(vm_) -Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default) -or \(aqprivate_ips\(aq. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.start(name, call=None) -Start a node -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.stop(name, call=None) -Stop a node -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.update_pricing(kwargs=None, call=None) -Download most recent pricing information from AWS and convert to a local -JSON file. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_pricing my\-ec2\-config -salt\-cloud \-f update_pricing my\-ec2\-config type=linux -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -New in version 2015.8.0. - -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.ec2.wait_for_instance(vm_=None, data=None, ip_address=None, display_ssh_output=True, call=None) -Wait for an instance upon creation from the EC2 API, to become available -.UNINDENT -.SS salt.cloud.clouds.gce -.sp -Copyright 2013 Google Inc. All Rights Reserved. -.sp -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at -.INDENT 0.0 -.INDENT 3.5 -\fI\%http://www.apache.org/licenses/LICENSE\-2.0\fP -.UNINDENT -.UNINDENT -.sp -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -.SS Google Compute Engine Module -.sp -The Google Compute Engine module. This module interfaces with Google Compute -Engine. To authenticate to GCE, you will need to create a Service Account. -.INDENT 0.0 -.TP -.B Setting up Service Account Authentication: -.INDENT 7.0 -.IP \(bu 2 -Go to the Cloud Console at: \fI\%https://cloud.google.com/console\fP\&. -.IP \(bu 2 -Create or navigate to your desired Project. -.IP \(bu 2 -Make sure Google Compute Engine service is enabled under the Services -section. -.IP \(bu 2 -Go to "APIs and auth" section, and then the "Credentials" link. -.IP \(bu 2 -Click the "CREATE NEW CLIENT ID" button. -.IP \(bu 2 -Select "Service Account" and click "Create Client ID" button. -.IP \(bu 2 -This will automatically download a .json file; ignore it. -.IP \(bu 2 -Look for a new "Service Account" section in the page, click on the "Generate New P12 key" button -.IP \(bu 2 -Copy the Email Address for inclusion in your /etc/salt/cloud file -in the \(aqservice_account_email_address\(aq setting. -.IP \(bu 2 -Download the Private Key -.IP \(bu 2 -The key that you download is a PKCS12 key. It needs to be converted to -the PEM format. -.IP \(bu 2 -Convert the key using OpenSSL (the default password is \(aqnotasecret\(aq): -C{openssl pkcs12 \-in PRIVKEY.p12 \-passin pass:notasecret \-nodes \-nocerts | openssl rsa \-out ~/PRIVKEY.pem} -.IP \(bu 2 -Add the full path name of the converted private key to your -/etc/salt/cloud file as \(aqservice_account_private_key\(aq setting. -.IP \(bu 2 -Consider using a more secure location for your private key. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-gce\-config: - # The Google Cloud Platform Project ID - project: "my\-project\-id" - # The Service ACcount client ID - service_account_email_address: 1234567890@developer.gserviceaccount.com - # The location of the private key (PEM format) - service_account_private_key: /home/erjohnso/PRIVKEY.pem - driver: gce - # Specify whether to use public or private IP for deploy script. - # Valid options are: - # private_ips \- The salt\-master is also hosted with GCE - # public_ips \- The salt\-master is hosted outside of GCE - ssh_interface: public_ips -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -Eric Johnson <\fI\%erjohnso@google.com\fP> -.TP -.B maturity -new -.TP -.B depends -libcloud >= 0.14.1 -.TP -.B depends -pycrypto >= 2.1 -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.attach_disk(name=None, kwargs=None, call=None) -Attach an existing disk to an existing instance. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a attach_disk myinstance disk_name=mydisk mode=READ_WRITE -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.attach_lb(kwargs=None, call=None) -Add an existing node/member to an existing load\-balancer configuration. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f attach_lb gce name=lb member=myinstance -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.avail_images(conn=None) -Return a dict of all available VM images on the cloud provider with -relevant data -.sp -Note that for GCE, there are custom images within the project, but the -generic images are in other projects. This returns a dict of images in -the project plus images in \(aqdebian\-cloud\(aq and \(aqcentos\-cloud\(aq (If there is -overlap in names, the one in the current project is used.) -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.avail_locations(conn=None, call=None) -Return a dict of all available VM locations on the cloud provider with -relevant data -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.avail_sizes(conn=None) -Return a dict of available instances sizes (a.k.a machine types) and -convert them to something more serializable. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.create(vm_=None, call=None) -Create a single GCE instance from a data dict. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.create_address(kwargs=None, call=None) -Create a static address in a region. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_address gce name=my\-ip region=us\-central1 address=IP -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.create_disk(kwargs=None, call=None) -Create a new persistent disk. Must specify \fIdisk_name\fP and \fIlocation\fP\&. -Can also specify an \fIimage\fP or \fIsnapshot\fP but if neither of those are -specified, a \fIsize\fP (in GB) is required. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_disk gce disk_name=pd size=300 location=us\-central1\-b -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.create_fwrule(kwargs=None, call=None) -Create a GCE firewall rule. The \(aqdefault\(aq network is used if not specified. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_fwrule gce name=allow\-http allow=tcp:80 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.create_hc(kwargs=None, call=None) -Create an HTTP health check configuration. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_hc gce name=hc path=/healthy port=80 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.create_lb(kwargs=None, call=None) -Create a load\-balancer configuration. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_lb gce name=lb region=us\-central1 ports=80 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.create_network(kwargs=None, call=None) -Create a GCE network. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_network gce name=mynet cidr=10.10.10.0/24 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.create_snapshot(kwargs=None, call=None) -Create a new disk snapshot. Must specify \fIname\fP and \fIdisk_name\fP\&. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_snapshot gce name=snap1 disk_name=pd -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.delete_address(kwargs=None, call=None) -Permanently delete a static address. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_address gce name=my\-ip -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.delete_disk(kwargs=None, call=None) -Permanently delete a persistent disk. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_disk gce disk_name=pd -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.delete_fwrule(kwargs=None, call=None) -Permanently delete a firewall rule. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_fwrule gce name=allow\-http -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.delete_hc(kwargs=None, call=None) -Permanently delete a health check. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_hc gce name=hc -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.delete_lb(kwargs=None, call=None) -Permanently delete a load\-balancer. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_lb gce name=lb -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.delete_network(kwargs=None, call=None) -Permanently delete a network. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_network gce name=mynet -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.delete_snapshot(kwargs=None, call=None) -Permanently delete a disk snapshot. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_snapshot gce name=disk\-snap\-1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.destroy(vm_name, call=None) -Call \(aqdestroy\(aq on the instance. Can be called with "\-a destroy" or \-d -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a destroy myinstance1 myinstance2 ... -salt\-cloud \-d myinstance1 myinstance2 ... -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.detach_disk(name=None, kwargs=None, call=None) -Detach a disk from an instance. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a detach_disk myinstance disk_name=mydisk -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.detach_lb(kwargs=None, call=None) -Remove an existing node/member from an existing load\-balancer configuration. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f detach_lb gce name=lb member=myinstance -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.get_configured_provider() -Return the first configured instance. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.get_conn() -Return a conn object for the passed VM data -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.get_lb_conn(gce_driver=None) -Return a load\-balancer conn object -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.list_nodes(conn=None, call=None) -Return a list of the VMs that are on the provider -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.list_nodes_full(conn=None, call=None) -Return a list of the VMs that are on the provider, with all fields -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.list_nodes_select(conn=None, call=None) -Return a list of the VMs that are on the provider, with select fields -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.reboot(vm_name, call=None) -Call GCE \(aqreset\(aq on the instance. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a reboot myinstance -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.script(vm_) -Return the script deployment object -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.show_address(kwargs=None, call=None) -Show the details of an existing static address. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_address gce name=mysnapshot region=us\-central1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.show_disk(name=None, kwargs=None, call=None) -Show the details of an existing disk. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a show_disk myinstance disk_name=mydisk -salt\-cloud \-f show_disk gce disk_name=mydisk -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.show_fwrule(kwargs=None, call=None) -Show the details of an existing firewall rule. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_fwrule gce name=allow\-http -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.show_hc(kwargs=None, call=None) -Show the details of an existing health check. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_hc gce name=hc -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.show_instance(vm_name, call=None) -Show the details of the existing instance. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.show_lb(kwargs=None, call=None) -Show the details of an existing load\-balancer. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_lb gce name=lb -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.show_network(kwargs=None, call=None) -Show the details of an existing network. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_network gce name=mynet -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.show_pricing(kwargs=None, call=None) -Show pricing for a particular profile. This is only an estimate, based on -unofficial pricing sources. -.sp -New in version 2015.8.0. - -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_pricing my\-gce\-config profile=my\-profile -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.show_snapshot(kwargs=None, call=None) -Show the details of an existing snapshot. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_snapshot gce name=mysnapshot -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.gce.update_pricing(kwargs=None, call=None) -Download most recent pricing information from GCE and save locally -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_pricing my\-gce\-config -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -New in version 2015.8.0. - .UNINDENT .SS salt.cloud.clouds.gogrid .SS GoGrid Cloud Module @@ -39253,457 +38379,6 @@ salt\-cloud \-a stop vm_name .sp New in version 2015.8.0. -.UNINDENT -.SS salt.cloud.clouds.joyent -.SS Joyent Cloud Module -.sp -The Joyent Cloud module is used to interact with the Joyent cloud system. -.sp -Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or -\fB/etc/salt/cloud.providers.d/joyent.conf\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-joyent\-config: - driver: joyent - # The Joyent login user - user: fred - # The Joyent user\(aqs password - password: saltybacon - # The location of the ssh private key that can log into the new VM - private_key: /root/mykey.pem - # The name of the private key - private_key: mykey -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -When creating your profiles for the joyent cloud, add the location attribute to -the profile, this will automatically get picked up when performing tasks -associated with that vm. An example profile might look like: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -joyent_512: - provider: my\-joyent\-config - size: Extra Small 512 MB - image: centos\-6 - location: us\-east\-1 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This driver can also be used with the Joyent SmartDataCenter project. More -details can be found at: -.sp -Using SDC requires that an api_host_suffix is set. The default value for this is -\fI\&.api.joyentcloud.com\fP\&. All characters, including the leading \fI\&.\fP, should be -included: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -api_host_suffix: .api.myhostname.com -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B depends -PyCrypto -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.avail_images(call=None) -Get list of available images -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-\-list\-images -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Can use a custom URL for images. Default is: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -image_url: images.joyent.com/image -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.avail_locations(call=None) -List all available locations -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.avail_sizes(call=None) -get list of available packages -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-\-list\-sizes -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.create(vm_) -Create a single VM from a data dict -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-p profile_name vm_name -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.create_node(**kwargs) -convenience function to make the rest api call for node creation. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.delete_key(kwargs=None, call=None) -List the keys available -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_key joyent keyname=mykey -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.destroy(name, call=None) -destroy a machine by name -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- name given to the machine -.IP \(bu 2 -\fBcall\fP \-\- call value in this case is \(aqaction\(aq -.UNINDENT -.TP -.B Returns -array of booleans , true if successfully stopped and true if -successfully removed -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-d vm_name -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.get_configured_provider() -Return the first configured instance. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.get_image(vm_) -Return the image object to use -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.get_location(vm_=None) -.INDENT 7.0 -.TP -.B Return the joyent data center to use, in this order: -.INDENT 7.0 -.IP \(bu 2 -CLI parameter -.IP \(bu 2 -VM parameter -.IP \(bu 2 -Cloud profile setting -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.get_location_path(location=\(aqus\-east\-1\(aq, api_host_suffix=\(aq.api.joyentcloud.com\(aq) -create url from location variable -:param location: joyent data center location -:return: url -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.get_node(name) -gets the node from the full node list by name -:param name: name of the vm -:return: node object -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.get_size(vm_) -Return the VM\(aqs size object -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.has_method(obj, method_name) -Find if the provided object has a specific method -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.import_key(kwargs=None, call=None) -List the keys available -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f import_key joyent keyname=mykey keyfile=/tmp/mykey.pub -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.joyent_node_state(id_) -Convert joyent returned state to state common to other data center return -values for consistency -.INDENT 7.0 -.TP -.B Parameters -\fBid\fP \-\- joyent state value -.TP -.B Returns -state value -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.key_list(items=None) -convert list to dictionary using the key as the identifier -:param items: array to iterate over -:return: dictionary -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.list_keys(kwargs=None, call=None) -List the keys available -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.list_nodes(full=False, call=None) -list of nodes, keeping only a brief listing -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-Q -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.list_nodes_full(call=None) -list of nodes, maintaining all content provided from joyent listings -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-F -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.list_nodes_select(call=None) -Return a list of the VMs that are on the provider, with select fields -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.query(action=None, command=None, args=None, method=\(aqGET\(aq, location=None, data=None) -Make a web call to Joyent -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.query_instance(vm_=None, call=None) -Query an instance upon creation from the Joyent API -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.reboot(name, call=None) -reboot a machine by name -:param name: name given to the machine -:param call: call value in this case is \(aqaction\(aq -:return: true if successful -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a reboot vm_name -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.reformat_node(item=None, full=False) -Reformat the returned data from joyent, determine public/private IPs and -strip out fields if necessary to provide either full or brief content. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBitem\fP \-\- node dictionary -.IP \(bu 2 -\fBfull\fP \-\- full or brief output -.UNINDENT -.TP -.B Returns -dict -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.show_instance(name, call=None) -get details about a machine -:param name: name given to the machine -:param call: call value in this case is \(aqaction\(aq -:return: machine information -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a show_instance vm_name -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.show_key(kwargs=None, call=None) -List the keys available -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.ssh_interface(vm_) -Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default) -or \(aqprivate_ips\(aq. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.start(name, call=None) -start a machine by name -:param name: name given to the machine -:param call: call value in this case is \(aqaction\(aq -:return: true if successful -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a start vm_name -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.stop(name, call=None) -stop a machine by name -:param name: name given to the machine -:param call: call value in this case is \(aqaction\(aq -:return: true if successful -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a stop vm_name -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.joyent.take_action(name=None, call=None, command=None, data=None, method=\(aqGET\(aq, location=\(aqus\-east\-1\(aq) -take action call used by start,stop, reboot -:param name: name given to the machine -:param call: call value in this case is \(aqaction\(aq -:command: api path -:data: any data to be passed to the api, must be in json format -:method: GET,POST,or DELETE -:location: data center to execute the command on -:return: true if successful .UNINDENT .SS salt.cloud.clouds.libcloud_aws .SS The AWS Cloud Module @@ -39806,6 +38481,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.libcloud_aws.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.libcloud_aws.get_location(vm_=None) .INDENT 7.0 .TP @@ -39936,35 +38616,110 @@ minion gets new keys and the keys get pre\-seeded on the master, and the /etc/sa Cloning requires a post 2015\-02\-01 salt\-bootstrap. .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.avail_images() +.B salt.cloud.clouds.linode.avail_images(call=None) Return available Linode images. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-\-list\-images my\-linode\-config +salt\-cloud \-f avail_images my\-linode\-config +.ft P +.fi +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.avail_locations() +.B salt.cloud.clouds.linode.avail_locations(call=None) Return available Linode datacenter locations. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-\-list\-locations my\-linode\-config +salt\-cloud \-f avail_locations my\-linode\-config +.ft P +.fi +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.avail_sizes() +.B salt.cloud.clouds.linode.avail_sizes(call=None) Return available Linode sizes. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-\-list\-sizes my\-linode\-config +salt\-cloud \-f avail_sizes my\-linode\-config +.ft P +.fi +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.boot(linode_id, config_id) +.B salt.cloud.clouds.linode.boot(name=None, kwargs=None, call=None) Boot a Linode. .INDENT 7.0 .TP +.B name +The name of the Linode to boot. Can be used instead of \fBlinode_id\fP\&. +.TP .B linode_id -The ID of the Linode to boot. Required. +The ID of the Linode to boot. If provided, will be used as an +alternative to \fBname\fP and reduces the number of API calls to +Linode by one. Will be preferred over \fBname\fP\&. .TP .B config_id The ID of the Config to boot. Required. +.TP +.B check_running +Defaults to True. If set to False, overrides the call to check if +the VM is running before calling the linode.boot API call. Change +\fBcheck_running\fP to True is useful during the boot call in the +create function, since the new VM will not be running yet. +.UNINDENT +.sp +Can be called as an action (which requires a name): +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-a boot my\-instance config_id=10 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\&...or as a function (which requires either a name or linode_id): +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-f boot my\-linode\-config name=my\-instance config_id=10 +salt\-cloud \-f boot my\-linode\-config linode_id=1225876 config_id=10 +.ft P +.fi +.UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.clone(linode_id, datacenter_id, plan_id) +.B salt.cloud.clouds.linode.clone(kwargs=None, call=None) Clone a Linode. .INDENT 7.0 .TP @@ -39977,6 +38732,18 @@ The ID of the Datacenter where the Linode will be placed. Required. .B plan_id The ID of the plan (size) of the Linode. Required. .UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-f clone my\-linode\-config linode_id=1234567 datacenter_id=2 plan_id=5 +.ft P +.fi +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -39985,16 +38752,12 @@ Create a single Linode VM. .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.create_config(vm_, linode_id, root_disk_id, swap_disk_id, kernel_id=None) +.B salt.cloud.clouds.linode.create_config(kwargs=None, call=None) Creates a Linode Configuration Profile. .INDENT 7.0 .TP -.B -.nf -vm_ -.fi - -The VM profile to create the config for. +.B name +The name of the VM to create the config for. .TP .B linode_id The ID of the Linode to create the configuration for. @@ -40090,6 +38853,37 @@ salt\-cloud \-d vm_name .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.linode.get_config_id(kwargs=None, call=None) +Returns a config_id for a given linode. +.sp +New in version 2015.8.0. + +.INDENT 7.0 +.TP +.B name +The name of the Linode for which to get the config_id. Can be used instead +of \fBlinode_id\fP\&.h +.TP +.B linode_id +The ID of the Linode for which to get the config_id. Can be used instead +of \fBname\fP\&. +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-f get_config_id my\-linode\-config name=my\-linode +salt\-cloud \-f get_config_id my\-linode\-config linode_id=1234567 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.linode.get_configured_provider() Return the first configured instance. .UNINDENT @@ -40143,12 +38937,31 @@ Limits the IP addresses returned to the specified Linode ID. .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.get_linode(linode_id) +.B salt.cloud.clouds.linode.get_linode(kwargs=None, call=None) Returns data for a single named Linode. .INDENT 7.0 .TP +.B name +The name of the Linode for which to get data. Can be used instead +\fBlinode_id\fP\&. Note this will induce an additional API call +compared to using \fBlinode_id\fP\&. +.TP .B linode_id -The ID of the Linode to get data for. +The ID of the Linode for which to get data. Can be used instead of +\fBname\fP\&. +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-f get_linode my\-linode\-config name=my\-instance +salt\-cloud \-f get_linode my\-linode\-config linode_id=1234567 +.ft P +.fi +.UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 @@ -40177,13 +38990,25 @@ The configuration to obtain the password from. .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.get_plan_id(label) +.B salt.cloud.clouds.linode.get_plan_id(kwargs=None, call=None) Returns the Linode Plan ID. .INDENT 7.0 .TP .B label The label, or name, of the plan to get the ID from. .UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-f get_plan_id linode label="Linode 1024" +.ft P +.fi +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -40245,6 +39070,7 @@ CLI Example: .ft C salt\-cloud \-Q salt\-cloud \-\-query +salt\-cloud \-f list_nodes my\-linode\-config .ft P .fi .UNINDENT @@ -40261,7 +39087,7 @@ due to a limitation of the Linode API. .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.list_nodes_full() +.B salt.cloud.clouds.linode.list_nodes_full(call=None) List linodes, with all available information. .sp CLI Example: @@ -40271,7 +39097,8 @@ CLI Example: .nf .ft C salt\-cloud \-F - salt\-cloud \-\-full\-query +salt\-cloud \-\-full\-query +salt\-cloud \-f list_nodes_full my\-linode\-config .ft P .fi .UNINDENT @@ -40288,8 +39115,31 @@ due to a limitation of the Linode API. .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.reboot(name=None, linode_id=None, call=None) -Reboot a linode. Either a name or a linode_id must be provided. +.B salt.cloud.clouds.linode.list_nodes_min(call=None) +Return a list of the VMs that are on the provider. Only a list of VM names and +their state is returned. This is the minimum amount of information needed to +check for existing VMs. +.sp +New in version 2015.8.0. + +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-f list_nodes_min my\-linode\-config +salt\-cloud \-\-function list_nodes_min my\-linode\-config +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.cloud.clouds.linode.reboot(name, call=None) +Reboot a linode. .sp New in version 2015.8.0. @@ -40297,9 +39147,6 @@ New in version 2015.8.0. .TP .B name The name of the VM to reboot. -.TP -.B linode_id -The Linode ID of the VM to reboot. Can be provided instead of a name. .UNINDENT .sp CLI Example: @@ -40309,7 +39156,6 @@ CLI Example: .nf .ft C salt\-cloud \-a reboot vm_name -salt\-cloud \-a reboot linode_id .ft P .fi .UNINDENT @@ -40317,7 +39163,7 @@ salt\-cloud \-a reboot linode_id .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.show_instance(name=None, linode_id=None, call=None) +.B salt.cloud.clouds.linode.show_instance(name, call=None) Displays details about a particular Linode VM. Either a name or a linode_id must be provided. .sp @@ -40327,10 +39173,6 @@ New in version 2015.8.0. .TP .B name The name of the VM for which to display details. -.TP -.B linode_id -The Linode ID of the VM for which to display details. Can be provided instead -of a name. .UNINDENT .sp CLI Example: @@ -40340,7 +39182,6 @@ CLI Example: .nf .ft C salt\-cloud \-a show_instance vm_name -salt\-cloud \-a show_instance linode_id .ft P .fi .UNINDENT @@ -40378,15 +39219,12 @@ salt\-cloud \-f show_pricing my\-linode\-config profile=my\-linode\-profile .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.start(name=None, linode_id=None, call=None) -Start a VM in Linode. Either a name or a linode_id must be provided. +.B salt.cloud.clouds.linode.start(name, call=None) +Start a VM in Linode. .INDENT 7.0 .TP .B name The name of the VM to start. -.TP -.B linode_id -The Linode ID of the VM to start. Can be provided instead of name. .UNINDENT .sp CLI Example: @@ -40396,7 +39234,6 @@ CLI Example: .nf .ft C salt\-cloud \-a stop vm_name -salt\-cloud \-a stop linode_id .ft P .fi .UNINDENT @@ -40404,15 +39241,12 @@ salt\-cloud \-a stop linode_id .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.stop(name=None, linode_id=None, call=None) -Stop a VM in Linode. Either a name or a linode_id must be provided. +.B salt.cloud.clouds.linode.stop(name, call=None) +Stop a VM in Linode. .INDENT 7.0 .TP .B name The name of the VM to stop. -.TP -.B linode_id -The Linode ID of the VM to stop. Can be provided instead of name. .UNINDENT .sp CLI Example: @@ -40422,7 +39256,6 @@ CLI Example: .nf .ft C salt\-cloud \-a stop vm_name -salt\-cloud \-a stop linode_id .ft P .fi .UNINDENT @@ -40563,7 +39396,10 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f add_input_endpoint my\-azure service=myservice deployment=mydeployment role=myrole name=HTTP local_port=80 port=80 protocol=tcp enable_direct_server_return=False timeout_for_tcp_idle_connection=4 +salt\-cloud \-f add_input_endpoint my\-azure service=myservice \e + deployment=mydeployment role=myrole name=HTTP local_port=80 \e + port=80 protocol=tcp enable_direct_server_return=False \e + timeout_for_tcp_idle_connection=4 .ft P .fi .UNINDENT @@ -40583,7 +39419,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f add_management_certificate my\-azure public_key=\(aq...PUBKEY...\(aq thumbprint=0123456789ABCDEF data=\(aq...CERT_DATA...\(aq +salt\-cloud \-f add_management_certificate my\-azure public_key=\(aq...PUBKEY...\(aq \e + thumbprint=0123456789ABCDEF data=\(aq...CERT_DATA...\(aq .ft P .fi .UNINDENT @@ -40603,7 +39440,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f add_service_certificate my\-azure name=my_service_certificate data=\(aq...CERT_DATA...\(aq certificate_format=sha1 password=verybadpass +salt\-cloud \-f add_service_certificate my\-azure name=my_service_certificate \e + data=\(aq...CERT_DATA...\(aq certificate_format=sha1 password=verybadpass .ft P .fi .UNINDENT @@ -40808,7 +39646,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f delete_input_endpoint my\-azure service=myservice deployment=mydeployment role=myrole name=HTTP +salt\-cloud \-f delete_input_endpoint my\-azure service=myservice \e + deployment=mydeployment role=myrole name=HTTP .ft P .fi .UNINDENT @@ -40828,7 +39667,8 @@ CLI Examples: .sp .nf .ft C -salt\-cloud \-f delete_management_certificate my\-azure name=my_management_certificate thumbalgorithm=sha1 thumbprint=0123456789ABCDEF +salt\-cloud \-f delete_management_certificate my\-azure name=my_management_certificate \e + thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT @@ -40868,7 +39708,8 @@ CLI Examples: .sp .nf .ft C -salt\-cloud \-f delete_service_certificate my\-azure name=my_service_certificate thumbalgorithm=sha1 thumbprint=0123456789ABCDEF +salt\-cloud \-f delete_service_certificate my\-azure name=my_service_certificate \e + thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT @@ -40958,7 +39799,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f show_affinity_group my\-azure service=myservice deployment=mydeployment name=SSH +salt\-cloud \-f show_affinity_group my\-azure service=myservice \e + deployment=mydeployment name=SSH .ft P .fi .UNINDENT @@ -41091,6 +39933,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.msazure.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.msazure.get_deployment(kwargs=None, conn=None, call=None) New in version 2015.8.0. @@ -41143,7 +39990,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f show_input_endpoint my\-azure service=myservice deployment=mydeployment name=SSH +salt\-cloud \-f show_input_endpoint my\-azure service=myservice \e + deployment=mydeployment name=SSH .ft P .fi .UNINDENT @@ -41163,7 +40011,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f get_management_certificate my\-azure name=my_management_certificate thumbalgorithm=sha1 thumbprint=0123456789ABCDEF +salt\-cloud \-f get_management_certificate my\-azure name=my_management_certificate \e + thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT @@ -41203,7 +40052,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f show_service_certificate my\-azure name=my_service_certificate thumbalgorithm=sha1 thumbprint=0123456789ABCDEF +salt\-cloud \-f show_service_certificate my\-azure name=my_service_certificate \e + thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT @@ -41952,7 +40802,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f set_storage_container my\-azure name=mycontainer x_ms_meta_name_values=\(aq{"my_name": "my_value"}\(aq +salt\-cloud \-f set_storage_container my\-azure name=mycontainer \e + x_ms_meta_name_values=\(aq{"my_name": "my_value"}\(aq .ft P .fi .UNINDENT @@ -41985,7 +40836,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f show_affinity_group my\-azure service=myservice deployment=mydeployment name=SSH +salt\-cloud \-f show_affinity_group my\-azure service=myservice \e + deployment=mydeployment name=SSH .ft P .fi .UNINDENT @@ -42097,7 +40949,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f show_input_endpoint my\-azure service=myservice deployment=mydeployment name=SSH +salt\-cloud \-f show_input_endpoint my\-azure service=myservice \e + deployment=mydeployment name=SSH .ft P .fi .UNINDENT @@ -42122,7 +40975,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f get_management_certificate my\-azure name=my_management_certificate thumbalgorithm=sha1 thumbprint=0123456789ABCDEF +salt\-cloud \-f get_management_certificate my\-azure name=my_management_certificate \e + thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT @@ -42162,7 +41016,8 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f show_service_certificate my\-azure name=my_service_certificate thumbalgorithm=sha1 thumbprint=0123456789ABCDEF +salt\-cloud \-f show_service_certificate my\-azure name=my_service_certificate \e + thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT @@ -42347,7 +41202,10 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f update_input_endpoint my\-azure service=myservice deployment=mydeployment role=myrole name=HTTP local_port=80 port=80 protocol=tcp enable_direct_server_return=False timeout_for_tcp_idle_connection=4 +salt\-cloud \-f update_input_endpoint my\-azure service=myservice \e + deployment=mydeployment role=myrole name=HTTP local_port=80 \e + port=80 protocol=tcp enable_direct_server_return=False \e + timeout_for_tcp_idle_connection=4 .ft P .fi .UNINDENT @@ -42536,6 +41394,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.nova.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.nova.get_image(conn, vm_) Return the image object to use .UNINDENT @@ -42735,6 +41598,11 @@ Return the first configured instance. .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.opennebula.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.opennebula.get_image(vm_) Return the image object to use .UNINDENT @@ -42776,7 +41644,7 @@ providers, each of which have their own ways of using it. .INDENT 0.0 .TP .B depends -libcloud >\- 0.13.2 +libcloud >= 0.13.2 .UNINDENT .sp OpenStack provides a number of ways to authenticate. This module uses password\- @@ -42966,6 +41834,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.openstack.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.openstack.get_image(conn, vm_) Return the image object to use .UNINDENT @@ -43214,6 +42087,7 @@ my\-proxmox\-config: password: mypassword url: hypervisor.domain.tld driver: proxmox + verify_ssl: True .ft P .fi .UNINDENT @@ -43223,9 +42097,6 @@ my\-proxmox\-config: .B maintainer Frank Klaassen <\fI\%frank@cloudright.nl\fP> .TP -.B maturity -new -.TP .B depends requests >= 2.2.1 .TP @@ -43312,6 +42183,11 @@ Return the first configured instance. .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.proxmox.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.proxmox.get_resources_nodes(call=None, resFilter=None) Retrieve all hypervisors (nodes) available on this environment CLI Example: @@ -43504,6 +42380,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.pyrax.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.pyrax.queues_create(call, kwargs) .UNINDENT .INDENT 0.0 @@ -43597,6 +42478,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.rackspace.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.rackspace.get_image(conn, vm_) Return the image object to use .UNINDENT @@ -43761,6 +42647,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.softlayer.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.softlayer.get_location(vm_=None) .INDENT 7.0 .TP @@ -43892,6 +42783,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.softlayer_hw.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.softlayer_hw.get_location(vm_=None) .INDENT 7.0 .TP @@ -44022,22 +42918,24 @@ cloud configuration at .ft C my\-vmware\-config: driver: vmware - user: "DOMAIN\euser" - password: "verybadpass" - url: "vcenter01.domain.com" + user: \(aqDOMAIN\euser\(aq + password: \(aqverybadpass\(aq + url: \(aq10.20.30.40\(aq -vmware\-vcenter02: +vcenter01: driver: vmware - user: "DOMAIN\euser" - password: "verybadpass" - url: "vcenter02.domain.com" + user: \(aqDOMAIN\euser\(aq + password: \(aqverybadpass\(aq + url: \(aqvcenter01.domain.com\(aq + protocol: \(aqhttps\(aq + port: 443 -vmware\-vcenter03: +vcenter02: driver: vmware - user: "DOMAIN\euser" - password: "verybadpass" - url: "vcenter03.domain.com" - protocol: "http" + user: \(aqDOMAIN\euser\(aq + password: \(aqverybadpass\(aq + url: \(aqvcenter02.domain.com\(aq + protocol: \(aqhttp\(aq port: 80 .ft P .fi @@ -44071,17 +42969,17 @@ To use this function, you need to specify \fBesxi_host_user\fP and .sp .nf .ft C -vmware\-vcenter01: - provider: vmware - user: "DOMAIN\euser" - password: "verybadpass" - url: "vcenter01.domain.com" +vcenter01: + driver: vmware + user: \(aqDOMAIN\euser\(aq + password: \(aqverybadpass\(aq + url: \(aqvcenter01.domain.com\(aq # Required when adding a host system - esxi_host_user: "root" - esxi_host_password: "myhostpassword" + esxi_host_user: \(aqroot\(aq + esxi_host_password: \(aqmyhostpassword\(aq # Optional fields that can be specified when adding a host system - esxi_host_ssl_thumbprint: "12:A3:45:B6:CD:7E:F8:90:A1:BC:23:45:D6:78:9E:FA:01:2B:34:CD" + esxi_host_ssl_thumbprint: \(aq12:A3:45:B6:CD:7E:F8:90:A1:BC:23:45:D6:78:9E:FA:01:2B:34:CD\(aq .ft P .fi .UNINDENT @@ -44119,7 +43017,7 @@ salt\-cloud \-f add_host my\-vmware\-config host="myHostSystemName" datacenter=" .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.vmware.avail_images() +.B salt.cloud.clouds.vmware.avail_images(call=None) Return a list of all the templates present in this VMware environment with basic details .sp @@ -44137,6 +43035,48 @@ salt\-cloud \-\-list\-images my\-vmware\-config .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.vmware.avail_locations(call=None) +Return a list of all the available locations/datacenters in this VMware environment +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-\-list\-locations my\-vmware\-config +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.cloud.clouds.vmware.avail_sizes(call=None) +Return a list of all the available sizes in this VMware environment. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-\-list\-sizes my\-vmware\-config +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Since sizes are built into templates, this function will return +an empty dictionary. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.vmware.connect_host(kwargs=None, call=None) Connect the specified host system in this VMware environment .sp @@ -44375,6 +43315,11 @@ salt\-cloud \-f exit_maintenance_mode my\-vmware\-config host="myHostSystemName" .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.vmware.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.vmware.get_vcenter_version(kwargs=None, call=None) Show the vCenter Server version with build number. .sp @@ -44866,6 +43811,23 @@ salt\-cloud \-f list_snapshots my\-vmware\-config name="vmname" .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.vmware.list_templates(kwargs=None, call=None) +List all the templates present in this VMware environment +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-f list_templates my\-vmware\-config +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.vmware.list_vapps(kwargs=None, call=None) List all the vApps for this VMware environment .sp @@ -45197,11 +44159,8 @@ The vSphere cloud module is used to control access to VMWare vSphere. .INDENT 0.0 .TP .B depends -.INDENT 7.0 -.IP \(bu 2 PySphere Python module >= 0.1.8 .UNINDENT -.UNINDENT .sp Note: Ensure python pysphere module is installed by running following one\-liner check. The output should be 0. @@ -45402,6 +44361,11 @@ Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.vsphere.get_dependencies() +Warn if dependencies aren\(aqt met. +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.vsphere.list_clusters(kwargs=None, call=None) List the clusters for this VMware environment .UNINDENT @@ -45940,12 +44904,12 @@ salt\-cloud \-a suspend vmname # If this is set to True the first newline after a Jinja block is removed # (block, not variable tag!). Defaults to False, corresponds to the Jinja # environment init variable "trim_blocks". -# jinja_trim_blocks: False +#jinja_trim_blocks: False # # If this is set to True leading spaces and tabs are stripped from the start # of a line to a block. Defaults to False, corresponds to the Jinja # environment init variable "lstrip_blocks". -# jinja_lstrip_blocks: False +#jinja_lstrip_blocks: False # The failhard option tells the minions to stop immediately after the first # failure detected in the state execution, defaults to False @@ -45965,7 +44929,7 @@ salt\-cloud \-a suspend vmname #state_output: full # Automatically aggregate all states that have support for mod_aggregate by -# setting to True. Or pass a list of state module names to automatically +# setting to \(aqTrue\(aq. Or pass a list of state module names to automatically # aggregate just those types. # # state_aggregate: @@ -45973,6 +44937,11 @@ salt\-cloud \-a suspend vmname # #state_aggregate: False +# Send progress events as each function in a state run completes execution +# by setting to \(aqTrue\(aq. Progress events are in the format +# \(aqsalt/job//prog//\(aq. +#state_events: False + ##### File Server settings ##### ########################################## # Salt runs a lightweight file server written in zeromq to deliver files to @@ -45997,6 +44966,23 @@ salt\-cloud \-a suspend vmname #file_roots: # base: # \- /srv/salt +# + +# When using multiple environments, each with their own top file, the +# default behaviour is an unordered merge. To prevent top files from +# being merged together and instead to only use the top file from the +# requested environment, set this value to \(aqsame\(aq. +#top_file_merging_strategy: merge + +# To specify the order in which environments are merged, set the ordering +# in the env_order option. Given a conflict, the last matching value will +# win. +#env_order: [\(aqbase\(aq, \(aqdev\(aq, \(aqprod\(aq] + +# If top_file_merging_strategy is set to \(aqsame\(aq and an environment does not +# contain a top file, the top file in the environment specified by default_top +# will be used instead. +#default_top: base # The hash_type is the hash to use when discovering the hash of a file on # the master server. The default is md5, but sha1, sha224, sha256, sha384 @@ -46340,7 +45326,7 @@ salt\-cloud \-a suspend vmname .nf .ft C ##### Primary configuration settings ##### -########################################## +########################################## # This configuration file is used to manage the behavior of the Salt Minion. # With the exception of the location of the Salt Master Server, values that are # commented out but have an empty line after the comment are defaults that need @@ -46366,7 +45352,7 @@ salt\-cloud \-a suspend vmname # Minions can connect to multiple masters simultaneously (all masters # are "hot"), or can be configured to failover if a master becomes # unavailable. Multiple hot masters are configured by setting this -# value to "standard". Failover masters can be requested by setting +# value to "str". Failover masters can be requested by setting # to "failover". MAKE SURE TO SET master_alive_interval if you are # using failover. # master_type: str @@ -46823,9 +45809,9 @@ salt\-cloud \-a suspend vmname # will be shown for each state run. #state_output_profile: True -# Fingerprint of the master public key to double verify the master is valid, -# the master fingerprint can be found by running "salt\-key \-f master.pub" on the -# salt master. +# Fingerprint of the master public key to validate the identity of your Salt master +# before the initial key exchange. The master fingerprint can be found by running +# "salt\-key \-F master" on the Salt master. #master_finger: \(aq\(aq @@ -47124,6 +46110,45 @@ More information about running salt as a non\-privileged user can be found .sp There is also a full \fBtroubleshooting guide\fP available. +.SS Key Identity +.sp +Salt provides commands to validate the identity of your Salt master +and Salt minions before the initial key exchange. Validating key identity helps +avoid inadvertently connecting to the wrong Salt master, and helps prevent +a potential MiTM attack when establishing the initial connection. +.SS Master Key Fingerprint +.sp +Print the master key fingerprint by running the following command on the Salt master: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-key \-F master +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Copy the \fBmaster.pub\fP fingerprint from the \fILocal Keys\fP section, and then set this value +as the \fBmaster_finger\fP in the minion configuration file. Save the configuration +file and then restart the Salt minion. +.SS Minion Key Fingerprint +.sp +Run the following command on each Salt minion to view the minion key fingerprint: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-call \-\-local key.finger +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Compare this value to the value that is displayed when you run the +\fBsalt\-key \-\-finger \fP command on the Salt master. .SS Key Management .sp Salt uses AES encryption for all communication between the Master and @@ -48204,6 +47229,51 @@ state_output: full .fi .UNINDENT .UNINDENT +.SS \fBstate_aggregate\fP +.sp +Default: \fBFalse\fP +.sp +Automatically aggregate all states that have support for mod_aggregate by +setting to \fBTrue\fP\&. Or pass a list of state module names to automatically +aggregate just those types. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +state_aggregate: + \- pkg +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +state_aggregate: True +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBstate_events\fP +.sp +Default: \fBFalse\fP +.sp +Send progress events as each function in a state run completes execution +by setting to \fBTrue\fP\&. Progress events are in the format +\fBsalt/job//prog//\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +state_events: True +.ft P +.fi +.UNINDENT +.UNINDENT .SS \fByaml_utf8\fP .sp Default: \fBFalse\fP @@ -48335,6 +47405,17 @@ file_ignore_glob: .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Vim\(aqs .swp files are a common cause of Unicode errors in +\fBfile.recurse\fP states which use +templating. Unless there is a good reason to distribute them via the +fileserver, it is good practice to include \fB\(aq\e*.swp\(aq\fP in the +\fI\%file_ignore_glob\fP\&. +.UNINDENT +.UNINDENT .SS roots: Master\(aqs Local File Server .SS \fBfile_roots\fP .sp @@ -48420,10 +47501,12 @@ Walkthrough\fP\&. New in version 2014.7.0. .sp -Specify the provider to be used for gitfs. More information can be found in the -\fIGitFS Walkthrough\fP\&. +Optional parameter used to specify the provider to be used for gitfs. More +information can be found in the \fIGitFS Walkthrough\fP\&. .sp -Specify one value among valid values: \fBgitpython\fP, \fBpygit2\fP, \fBdulwich\fP +Must be one of the following: \fBpygit2\fP, \fBgitpython\fP, or \fBdulwich\fP\&. If +unset, then each will be tried in that same order, and the first one with a +compatible version installed will be the provider that is used. .INDENT 0.0 .INDENT 3.5 .sp @@ -48438,11 +47521,11 @@ gitfs_provider: dulwich .sp Default: \fBTrue\fP .sp -The \fBgitfs_ssl_verify\fP option specifies whether to ignore SSL certificate -errors when contacting the gitfs backend. You might want to set this to -\fBFalse\fP if you\(aqre using a git backend that uses a self\-signed certificate but -keep in mind that setting this flag to anything other than the default of -\fBTrue\fP is a security concern, you may want to try using the ssh transport. +Specifies whether or not to ignore SSL certificate errors when contacting the +remote repository. You might want to set this to \fBFalse\fP if you\(aqre using a +git repo that uses a self\-signed certificate. However, keep in mind that +setting this to anything other \fBTrue\fP is a considered insecure, and using an +SSH\-based transport (if available) may be a better option. .INDENT 0.0 .INDENT 3.5 .sp @@ -49343,6 +48426,25 @@ ext_pillar_first: False .UNINDENT .UNINDENT .SS Git External Pillar (git_pillar) Configuration Options +.SS \fBgit_pillar_provider\fP +.sp +New in version 2015.8.0. + +.sp +Specify the provider to be used for git_pillar. Must be either \fBpygit2\fP or +\fBgitpython\fP\&. If unset, then both will be tried in that same order, and the +first one with a compatible version installed will be the provider that is +used. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +git_pillar_provider: gitpython +.ft P +.fi +.UNINDENT +.UNINDENT .SS \fBgit_pillar_base\fP .sp New in version 2015.8.0. @@ -49492,10 +48594,10 @@ New in version 2015.8.0. Default: \fBTrue\fP .sp Specifies whether or not to ignore SSL certificate errors when contacting the -git_pillar remote repository. You might want to set this to \fBFalse\fP if you\(aqre -using a git backend that uses a self\-signed certificate but keep in mind that -setting this flag to anything other than the default of \fBTrue\fP is a security -concern, you may want to try using the ssh transport. +remote repository. You might want to set this to \fBFalse\fP if you\(aqre using a +git repo that uses a self\-signed certificate. However, keep in mind that +setting this to anything other \fBTrue\fP is a considered insecure, and using an +SSH\-based transport (if available) may be a better option. .INDENT 0.0 .INDENT 3.5 .sp @@ -49506,13 +48608,13 @@ git_pillar_ssl_verify: True .fi .UNINDENT .UNINDENT -.SS git_pillar Authentication Options +.SS Git External Pillar Authentication Options .sp -These parameters only currently apply to the pygit2 gitfs provider. -Authentication works the same as it does in gitfs, as outlined in the -\fIGitFS Walkthrough\fP, though the global -configuration options are named differently to reflect that they are for -git_pillar instead of gitfs. +These parameters only currently apply to the \fBpygit2\fP +\fI\%git_pillar_provider\fP\&. Authentication works the same as it does +in gitfs, as outlined in the \fIGitFS Walkthrough\fP, +though the global configuration options are named differently to reflect that +they are for git_pillar instead of gitfs. .SS \fBgit_pillar_user\fP .sp New in version 2015.8.0. @@ -49832,6 +48934,23 @@ syndic_master: masterofmasters .fi .UNINDENT .UNINDENT +.sp +You can optionally connect a syndic to multiple higher level masters by +setting the \(aqsyndic_master\(aq value to a list: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +syndic_master: + \- masterofmasters1 + \- masterofmasters2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Each higher level master must be set up in a multimaster configuration. .SS \fBsyndic_master_port\fP .sp Default: \fB4506\fP @@ -50205,68 +49324,271 @@ include: .UNINDENT .UNINDENT .SS Windows Software Repo Settings -.SS \fBwin_repo\fP +.SS \fBwinrepo_provider\fP +.sp +New in version 2015.8.0. + +.sp +Specify the provider to be used for winrepo. Must be either \fBpygit2\fP or +\fBgitpython\fP\&. If unset, then both will be tried in that same order, and the +first one with a compatible version installed will be the provider that is +used. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_provider: gitpython +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBwinrepo_dir\fP +.sp +Changed in version 2015.8.0: Renamed from \fBwin_repo\fP to \fBwinrepo_dir\fP + .sp Default: \fB/srv/salt/win/repo\fP .sp -Location of the repo on the master +Location on the master where the \fI\%winrepo_remotes\fP are checked +out. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -win_repo: \(aq/srv/salt/win/repo\(aq +winrepo_dir: /srv/salt/win/repo .ft P .fi .UNINDENT .UNINDENT -.SS \fBwin_repo_mastercachefile\fP +.SS \fBwinrepo_cachefile\fP .sp -Default: \fB/srv/salt/win/repo/winrepo.p\fP +Changed in version 2015.8.0: Renamed from \fBwin_repo_mastercachefile\fP to \fBwinrepo_cachefile\fP + +.sp +Default: \fBwinrepo.p\fP +.sp +Path relative to \fI\%winrepo_dir\fP where the winrepo cache should be +created. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -win_repo_mastercachefile: \(aq/srv/salt/win/repo/winrepo.p\(aq +winrepo_cachefile: winrepo.p .ft P .fi .UNINDENT .UNINDENT -.SS \fBwin_gitrepos\fP +.SS \fBwinrepo_remotes\fP .sp -Default: \fB\(aq\(aq\fP +Changed in version 2015.8.0: Renamed from \fBwin_gitrepos\fP to \fBwinrepo_remotes\fP + .sp -List of git repositories to include with the local repo. +Default: \fB[\(aqhttps://github.com/saltstack/salt\-winrepo.git\(aq]\fP +.sp +List of git repositories to checkout and include in the winrepo .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -win_gitrepos: - \- \(aqhttps://github.com/saltstack/salt\-winrepo.git\(aq +winrepo_remotes: + \- https://github.com/saltstack/salt\-winrepo.git .ft P .fi .UNINDENT .UNINDENT .sp -To specify a specific revision of the repository, preface the -repository location with a commit ID: +To specify a specific revision of the repository, prepend a commit ID to the +URL of the the repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -win_gitrepos: +winrepo_remotes: \- \(aq https://github.com/saltstack/salt\-winrepo.git\(aq .ft P .fi .UNINDENT .UNINDENT .sp -Replacing \fB\fP with the ID from GitHub. Specifying a commit -ID is useful if you need to revert to a previous version if an error -is introduced in the latest version. +Replace \fB\fP with the SHA1 hash of a commit ID. Specifying a commit +ID is useful in that it allows one to revert back to a previous version in the +event that an error is introduced in the latest revision of the repo. +.SS \fBwinrepo_branch\fP +.sp +New in version 2015.8.0. + +.sp +Default: \fBmaster\fP +.sp +If the branch is omitted from a winrepo remote, then this branch will be +used instead. For example, in the configuration below, the first two remotes +would use the \fBwinrepo\fP branch/tag, while the third would use the \fBfoo\fP +branch/tag. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_branch: winrepo + +ext_pillar: + \- git: + \- https://mygitserver/winrepo1.git + \- https://mygitserver/winrepo2.git: + \- foo https://mygitserver/winrepo3.git +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBwinrepo_ssl_verify\fP +.sp +New in version 2015.8.0. + +.sp +Default: \fBTrue\fP +.sp +Specifies whether or not to ignore SSL certificate errors when contacting the +remote repository. You might want to set this to \fBFalse\fP if you\(aqre using a +git repo that uses a self\-signed certificate. However, keep in mind that +setting this to anything other \fBTrue\fP is a considered insecure, and using an +SSH\-based transport (if available) may be a better option. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_ssl_verify: True +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Winrepo Authentication Options +.sp +These parameters only currently apply to the \fBpygit2\fP +\fI\%winrepo_provider\fP\&. Authentication works the same as it does in +gitfs, as outlined in the \fIGitFS Walkthrough\fP, +though the global configuration options are named differently to reflect that +they are for winrepo instead of gitfs. +.SS \fBwinrepo_user\fP +.sp +New in version 2015.8.0. + +.sp +Default: \fB\(aq\(aq\fP +.sp +Along with \fI\%winrepo_password\fP, is used to authenticate to HTTPS +remotes. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_user: git +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBwinrepo_password\fP +.sp +New in version 2015.8.0. + +.sp +Default: \fB\(aq\(aq\fP +.sp +Along with \fI\%winrepo_user\fP, is used to authenticate to HTTPS +remotes. This parameter is not required if the repository does not use +authentication. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_password: mypassword +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBwinrepo_insecure_auth\fP +.sp +New in version 2015.8.0. + +.sp +Default: \fBFalse\fP +.sp +By default, Salt will not authenticate to an HTTP (non\-HTTPS) remote. This +parameter enables authentication over HTTP. \fBEnable this at your own risk.\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_insecure_auth: True +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBwinrepo_pubkey\fP +.sp +New in version 2015.8.0. + +.sp +Default: \fB\(aq\(aq\fP +.sp +Along with \fI\%winrepo_privkey\fP (and optionally +\fI\%winrepo_passphrase\fP), is used to authenticate to SSH remotes. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_pubkey: /path/to/key.pub +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBwinrepo_privkey\fP +.sp +New in version 2015.8.0. + +.sp +Default: \fB\(aq\(aq\fP +.sp +Along with \fI\%winrepo_pubkey\fP (and optionally +\fI\%winrepo_passphrase\fP), is used to authenticate to SSH remotes. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_privkey: /path/to/key +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBwinrepo_passphrase\fP +.sp +New in version 2015.8.0. + +.sp +Default: \fB\(aq\(aq\fP +.sp +This parameter is optional, required only when the SSH key being used to +authenticate is protected by a passphrase. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_passphrase: mypassphrase +.ft P +.fi +.UNINDENT +.UNINDENT .SS Configuring the Salt Minion .sp The Salt system is amazingly simple and easy to configure. The two components @@ -50363,9 +49685,9 @@ master_type: failover New in version 2014.7.0. .sp -Default: \fBstandard\fP +Default: \fBstr\fP .sp -The type of the \fI\%master\fP variable. Can be \fBstandard\fP, \fBfailover\fP or +The type of the \fI\%master\fP variable. Can be \fBstr\fP, \fBfailover\fP or \fBfunc\fP\&. .INDENT 0.0 .INDENT 3.5 @@ -50915,7 +50237,7 @@ be able to execute a certain module. The sys module is built into the minion and cannot be disabled. .sp This setting can also tune the minion, as all modules are loaded into ram -disabling modules will lover the minion\(aqs ram footprint. +disabling modules will lower the minion\(aqs ram footprint. .INDENT 0.0 .INDENT 3.5 .sp @@ -51040,6 +50362,26 @@ cython_enable: False .fi .UNINDENT .UNINDENT +.SS \fBenable_zip_modules\fP +.sp +New in version 2015.8.0. + +.sp +Default: \fBFalse\fP +.sp +Set this value to true to enable loading of zip archives as extension modules. +This allows for packing module code with specific dependencies to avoid conflicts +and/or having to install specific modules\(aq dependencies in system libraries. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +enable_zip_modules: False +.ft P +.fi +.UNINDENT +.UNINDENT .SS \fBproviders\fP .sp Default: (empty) @@ -51299,6 +50641,23 @@ open_mode: False .fi .UNINDENT .UNINDENT +.SS \fBmaster_finger\fP +.sp +Default: \fB\(aq\(aq\fP +.sp +Fingerprint of the master public key to validate the identity of your Salt master +before the initial key exchange. The master fingerprint can be found by running +"salt\-key \-F master" on the Salt master. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +master_finger: \(aqba:30:65:2a:d6:9e:20:4f:d8:b2:f3:a7:d4:65:11:13\(aq +.ft P +.fi +.UNINDENT +.UNINDENT .SS \fBverify_master_pubkey_sign\fP .sp Default: \fBFalse\fP @@ -51635,6 +50994,96 @@ update_restart_services: [\(aqsalt\-minion\(aq] .fi .UNINDENT .UNINDENT +.SS Standalone Minion Windows Software Repo Settings +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +To use these config options, the minion must be running in masterless mode +(set \fI\%file_client\fP to \fBlocal\fP). +.UNINDENT +.UNINDENT +.SS \fBwinrepo_dir\fP +.sp +Changed in version 2015.8.0: Renamed from \fBwin_repo\fP to \fBwinrepo_dir\fP\&. Also, this option did not +have a default value until this version. + +.sp +Default: \fBC:\esalt\esrv\esalt\ewin\erepo\fP +.sp +Location on the minion where the \fI\%winrepo_remotes\fP are checked +out. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_dir: \(aqD:\ewinrepo\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBwinrepo_cachefile\fP +.sp +Changed in version 2015.8.0: Renamed from \fBwin_repo_cachefile\fP to \fBwinrepo_cachefile\fP\&. Also, +this option did not have a default value until this version. + +.sp +Default: \fBwinrepo.p\fP +.sp +Path relative to \fI\%winrepo_dir\fP where the winrepo cache should be +created. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_cachefile: winrepo.p +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBwinrepo_remotes\fP +.sp +Changed in version 2015.8.0: Renamed from \fBwin_gitrepos\fP to \fBwinrepo_remotes\fP\&. Also, this option did +not have a default value until this version. + +.sp +New in version 2015.8.0. + +.sp +Default: \fB[\(aqhttps://github.com/saltstack/salt\-winrepo.git\(aq]\fP +.sp +List of git repositories to checkout and include in the winrepo +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_remotes: + \- https://github.com/saltstack/salt\-winrepo.git +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To specify a specific revision of the repository, prepend a commit ID to the +URL of the the repository: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +winrepo_remotes: + \- \(aq https://github.com/saltstack/salt\-winrepo.git\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Replace \fB\fP with the SHA1 hash of a commit ID. Specifying a commit +ID is useful in that it allows one to revert back to a previous version in the +event that an error is introduced in the latest revision of the repo. .SS Running the Salt Master/Minion as an Unprivileged User .sp While the default setup runs the master and minion as the root user, some @@ -52133,7 +51582,8 @@ logging handler to be available. .UNINDENT .sp Configuring the python \fI\%Sentry\fP client, \fI\%Raven\fP, should be done under the -\fBsentry_handler\fP configuration key. +\fBsentry_handler\fP configuration key. Additional \fIcontext\fP may be provided +for coresponding grain item(s). At the bare minimum, you need to define the \fI\%DSN\fP\&. As an example: .INDENT 0.0 .INDENT 3.5 @@ -52160,6 +51610,12 @@ sentry_handler: project: app\-id public_key: deadbeefdeadbeefdeadbeefdeadbeef secret_key: beefdeadbeefdeadbeefdeadbeefdead + context: + \- os + \- master + \- saltversion + \- cpuarch + \- ec2.tags.environment .ft P .fi .UNINDENT @@ -53657,6 +53113,12 @@ Minion problems reading uris such as salt:// or http:// .UNINDENT .INDENT 0.0 .TP +.B exception salt.exceptions.NotImplemented(message=\(aq\(aq) +Used when a module runs a command which returns an error and wants +to show the user the output gracefully instead of dying +.UNINDENT +.INDENT 0.0 +.TP .B exception salt.exceptions.PkgParseError(message=\(aq\(aq) Used when of the pkg modules cannot correctly parse the output from the CLI tool (pacman, yum, apt, aptitude, etc) @@ -53886,6 +53348,12 @@ Minion problems reading uris such as salt:// or http:// .UNINDENT .INDENT 0.0 .TP +.B exception salt.exceptions.NotImplemented(message=\(aq\(aq) +Used when a module runs a command which returns an error and wants +to show the user the output gracefully instead of dying +.UNINDENT +.INDENT 0.0 +.TP .B exception salt.exceptions.PkgParseError(message=\(aq\(aq) Used when of the pkg modules cannot correctly parse the output from the CLI tool (pacman, yum, apt, aptitude, etc) @@ -54309,7 +53777,6 @@ _ T{ \fBcp\fP T} T{ -Minion side functions for salt\-cp T} _ T{ @@ -54667,7 +54134,6 @@ _ T{ \fBhipchat\fP T} T{ -Module for sending messages to hipchat. T} _ T{ @@ -54685,7 +54151,6 @@ _ T{ \fBhttp\fP T} T{ -Module for making various web calls. T} _ T{ @@ -54739,7 +54204,6 @@ _ T{ \fBiptables\fP T} T{ -Support for iptables T} _ T{ @@ -54979,7 +54443,6 @@ _ T{ \fBnagios_rpc\fP T} T{ -Check Host & Service status from Nagios via JSON RPC. T} _ T{ @@ -55020,7 +54483,6 @@ _ T{ \fBnftables\fP T} T{ -Support for nftables T} _ T{ @@ -55110,7 +54572,6 @@ _ T{ \fBpagerduty\fP T} T{ -Module for Firing Events via PagerDuty T} _ T{ @@ -55134,7 +54595,6 @@ _ T{ \fBpillar\fP T} T{ -Extract the pillar data for this minion T} _ T{ @@ -55217,7 +54677,6 @@ _ T{ \fBpushover_notify\fP T} T{ -Module for sending messages to Pushover (\fI\%https://www.pushover.net\fP) T} _ T{ @@ -55271,7 +54730,6 @@ _ T{ \fBrandom_org\fP T} T{ -Module for retrieving random information from Random.org T} _ T{ @@ -55295,7 +54753,6 @@ _ T{ \fBreg\fP T} T{ -Manage the registry on Windows T} _ T{ @@ -55379,7 +54836,6 @@ _ T{ \fBsaltutil\fP T} T{ -The Saltutil module is used to manage the state of the salt minion itself. T} _ T{ @@ -55451,7 +54907,7 @@ _ T{ \fBsmartos_vmadm\fP T} T{ -Module for managing VMs on SmartOS +Module for running vmadm command on SmartOS T} _ T{ @@ -55535,7 +54991,6 @@ _ T{ \fBstate\fP T} T{ -Control the state system on the minion. T} _ T{ @@ -55583,7 +55038,6 @@ _ T{ \fBsysmod\fP T} T{ -The sys module provides information about the available functions on the minion T} _ T{ @@ -55809,7 +55263,7 @@ _ T{ \fBwin_system\fP T} T{ -Support for reboot, shutdown, etc +Module for managing windows systems. T} _ T{ @@ -55833,7 +55287,6 @@ _ T{ \fBx509\fP T} T{ -Manage X509 certificates T} _ T{ @@ -67085,7 +66538,7 @@ salt \(aq*\(aq cmd.has_exec cat .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.retcode(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, umask=None, output_loglevel=\(aqdebug\(aq, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) +.B salt.modules.cmdmod.retcode(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, umask=None, output_loglevel=\(aqdebug\(aq, log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) Execute a shell command and return the command\(aqs return code. .INDENT 7.0 .TP @@ -67263,7 +66716,7 @@ salt \(aq*\(aq cmd.retcode "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.run(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) +.B salt.modules.cmdmod.run(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) Execute the passed command and return the output as a string .sp Note that \fBenv\fP represents the environment variables for the command, and @@ -67473,7 +66926,7 @@ salt \(aq*\(aq cmd.run cmd=\(aqsed \-e s/=/:/g\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.run_all(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) +.B salt.modules.cmdmod.run_all(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) Execute the passed command and return a dict of return data .INDENT 7.0 .TP @@ -67640,7 +67093,7 @@ salt \(aq*\(aq cmd.run_all "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.run_chroot(root, cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqquiet\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) +.B salt.modules.cmdmod.run_chroot(root, cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqquiet\(aq, log_callback=None, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) New in version 2014.7.0. .sp @@ -67783,7 +67236,7 @@ salt \(aq*\(aq cmd.run_chroot /var/lib/lxc/container_name/rootfs \(aqsh /tmp/boo .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.run_stderr(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) +.B salt.modules.cmdmod.run_stderr(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) Execute a command and only return the standard error .INDENT 7.0 .TP @@ -67950,7 +67403,7 @@ salt \(aq*\(aq cmd.run_stderr "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.run_stdout(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) +.B salt.modules.cmdmod.run_stdout(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, log_callback=None, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) Execute a command, and only return the standard out .INDENT 7.0 .TP @@ -68117,7 +67570,7 @@ salt \(aq*\(aq cmd.run_stdout "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.script(source, args=None, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, template=None, umask=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, reset_system_locale=True, __env__=None, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) +.B salt.modules.cmdmod.script(source, args=None, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, template=None, umask=None, output_loglevel=\(aqdebug\(aq, log_callback=None, quiet=False, timeout=None, reset_system_locale=True, __env__=None, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an HTTP/FTP server. @@ -68272,7 +67725,7 @@ salt \(aq*\(aq cmd.script salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\en .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.script_retcode(source, args=None, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, template=\(aqjinja\(aq, umask=None, timeout=None, reset_system_locale=True, __env__=None, saltenv=\(aqbase\(aq, output_loglevel=\(aqdebug\(aq, use_vt=False, **kwargs) +.B salt.modules.cmdmod.script_retcode(source, args=None, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=None, env=None, template=\(aqjinja\(aq, umask=None, timeout=None, reset_system_locale=True, __env__=None, saltenv=\(aqbase\(aq, output_loglevel=\(aqdebug\(aq, log_callback=None, use_vt=False, **kwargs) Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an HTTP/FTP server. @@ -68435,7 +67888,7 @@ salt \(aq*\(aq cmd.script_retcode salt://scripts/runme.sh stdin=\(aqone\entwo\en .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.shell(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) +.B salt.modules.cmdmod.shell(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, log_callback=None, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs) Execute the passed command and return the output as a string. .sp New in version 2015.5.0. @@ -69269,444 +68722,6 @@ salt myminion container_resource.run mycontainer \(aqps aux\(aq container_type=d .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.cp -.sp -Minion side functions for salt\-cp -.INDENT 0.0 -.TP -.B salt.modules.cp.cache_dir(path, saltenv=\(aqbase\(aq, include_empty=False, include_pat=None, exclude_pat=None, env=None) -Download and cache everything under a directory from the master -.INDENT 7.0 -.TP -.B include_pat -None -Glob or regex to narrow down the files cached from the given path. If -matching with a regex, the regex must be prefixed with \fBE@\fP, -otherwise the expression will be interpreted as a glob. -.sp -New in version 2014.7.0. - -.TP -.B exclude_pat -None -Glob or regex to exclude certain files from being cached from the given -path. If matching with a regex, the regex must be prefixed with \fBE@\fP, -otherwise the expression will be interpreted as a glob. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -If used with \fBinclude_pat\fP, files matching this pattern will be -excluded from the subset of files defined by \fBinclude_pat\fP\&. -.UNINDENT -.UNINDENT -.sp -New in version 2014.7.0. - -.UNINDENT -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.cache_dir salt://path/to/dir -salt \(aq*\(aq cp.cache_dir salt://path/to/dir include_pat=\(aqE@*.py$\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.cache_file(path, saltenv=\(aqbase\(aq, env=None) -Used to cache a single file on the salt\-minion -Returns the location of the new cached file on the minion -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.cache_file salt://path/to/file -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.cache_files(paths, saltenv=\(aqbase\(aq, env=None) -Used to gather many files from the master, the gathered files will be -saved in the minion cachedir reflective to the paths retrieved from the -master. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.cache_files salt://pathto/file1,salt://pathto/file1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.cache_local_file(path) -Cache a local file on the minion in the localfiles cache -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.cache_local_file /etc/hosts -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.cache_master(saltenv=\(aqbase\(aq, env=None) -Retrieve all of the files on the master and cache them locally -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.cache_master -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.get_dir(path, dest, saltenv=\(aqbase\(aq, template=None, gzip=None, env=None, **kwargs) -Used to recursively copy a directory from the salt master -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.get_dir salt://path/to/dir/ /minion/dest -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -get_dir supports the same template and gzip arguments as get_file. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.get_file(path, dest, saltenv=\(aqbase\(aq, makedirs=False, template=None, gzip=None, env=None, **kwargs) -Used to get a single file from the salt master -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.get_file salt://path/to/file /minion/dest -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Template rendering can be enabled on both the source and destination file -names like so: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.get_file "salt://{{grains.os}}/vimrc" /etc/vimrc template=jinja -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This example would instruct all Salt minions to download the vimrc from a -directory with the same name as their os grain and copy it to /etc/vimrc -.sp -For larger files, the cp.get_file module also supports gzip compression. -Because gzip is CPU\-intensive, this should only be used in scenarios where -the compression ratio is very high (e.g. pretty\-printed JSON or YAML -files). -.sp -Use the \fIgzip\fP named argument to enable it. Valid values are 1..9, where 1 -is the lightest compression and 9 the heaviest. 1 uses the least CPU on -the master (and minion), 9 uses the most. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.get_file_str(path, saltenv=\(aqbase\(aq, env=None) -Return the contents of a file from a URL -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.get_file_str salt://my/file -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.get_template(path, dest, template=\(aqjinja\(aq, saltenv=\(aqbase\(aq, env=None, makedirs=False, **kwargs) -Render a file as a template before setting it down. -Warning, order is not the same as in fileclient.cp for -non breaking old API. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.get_template salt://path/to/template /minion/dest -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.get_url(path, dest, saltenv=\(aqbase\(aq, env=None) -Used to get a single file from a URL. -.sp -The default behaviuor is to write the fetched file to the given -destination path. To simply return the text contents instead, set destination to -None. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.get_url salt://my/file /tmp/mine -salt \(aq*\(aq cp.get_url http://www.slashdot.org /tmp/index.html -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.hash_file(path, saltenv=\(aqbase\(aq, env=None) -Return the hash of a file, to get the hash of a file on the -salt master file server prepend the path with salt:// -otherwise, prepend the file with / for a local file. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.hash_file salt://path/to/file -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.is_cached(path, saltenv=\(aqbase\(aq, env=None) -Return a boolean if the given path on the master has been cached on the -minion -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.is_cached salt://path/to/file -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.list_master(saltenv=\(aqbase\(aq, prefix=\(aq\(aq, env=None) -List all of the files stored on the master -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.list_master -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.list_master_dirs(saltenv=\(aqbase\(aq, prefix=\(aq\(aq, env=None) -List all of the directories stored on the master -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.list_master_dirs -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.list_master_symlinks(saltenv=\(aqbase\(aq, prefix=\(aq\(aq, env=None) -List all of the symlinks stored on the master -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.list_master_symlinks -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.list_minion(saltenv=\(aqbase\(aq, env=None) -List all of the files cached on the minion -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.list_minion -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.list_states(saltenv=\(aqbase\(aq, env=None) -List all of the available state modules in an environment -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.list_states -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.push(path, keep_symlinks=False, upload_path=None) -Push a file from the minion up to the master, the file will be saved to -the salt master in the master\(aqs minion files cachedir -(defaults to \fB/var/cache/salt/master/minions/minion\-id/files\fP) -.sp -Since this feature allows a minion to push a file up to the master server -it is disabled by default for security purposes. To enable, set -\fBfile_recv\fP to \fBTrue\fP in the master configuration file, and restart the -master. -.INDENT 7.0 -.TP -.B keep_symlinks -Keep the path value without resolving its canonical form -.TP -.B upload_path -Provide a different path inside the master\(aqs minion files cachedir -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.push /etc/fstab -salt \(aq*\(aq cp.push /etc/system\-release keep_symlinks=True -salt \(aq*\(aq cp.push /etc/fstab upload_path=\(aq/new/path/fstab\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.push_dir(path, glob=None, upload_path=None) -Push a directory from the minion up to the master, the files will be saved -to the salt master in the master\(aqs minion files cachedir (defaults to -\fB/var/cache/salt/master/minions/minion\-id/files\fP). It also has a glob -for matching specific files using globbing. -.sp -New in version 2014.7.0. - -.sp -Since this feature allows a minion to push files up to the master server it -is disabled by default for security purposes. To enable, set \fBfile_recv\fP -to \fBTrue\fP in the master configuration file, and restart the master. -.INDENT 7.0 -.TP -.B upload_path -Provide a different path and directory name inside the master\(aqs minion -files cachedir -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cp.push /usr/lib/mysql -salt \(aq*\(aq cp.push /usr/lib/mysql upload_path=\(aq/newmysql/path\(aq -salt \(aq*\(aq cp.push_dir /etc/modprobe.d/ glob=\(aq*.conf\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cp.recv(files, dest) -Used with salt\-cp, pass the files dict, and the destination. -.sp -This function receives small fast copy files from the master via salt\-cp. -It does not work via the CLI. -.UNINDENT .SS salt.modules.cpan .sp Manage Perl modules using CPAN @@ -71338,7 +70353,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq ip.get_interface eth0 +salt \(aq*\(aq ip.get_routes eth0 .ft P .fi .UNINDENT @@ -71623,53 +70638,6 @@ salt \(aq*\(aq service.stop .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.defaults -.INDENT 0.0 -.TP -.B salt.modules.defaults.get(key, default=\(aq\(aq) -defaults.get is used much like pillar.get except that it will read -a default value for a pillar from defaults.json or defaults.yaml -files that are stored in the root of a salt formula. -.sp -When called from the CLI it works exactly like pillar.get. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq defaults.get core:users:root -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -When called from an SLS file, it works by first reading a defaults.json -and second a defaults.yaml file. If the key exists in these files and -does not exist in a pillar named after the formula, the value from the -defaults file is used. -.sp -Example core/defaults.json file for the \(aqcore\(aq formula: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -{ - "users": { - "root": 0 - } -} -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -With this, from a state file you can use salt[\(aqdefaults.get\(aq](\(aqusers:root\(aq) -to read the \(aq0\(aq value from defaults.json if a core:users:root pillar -key is not defined. -.UNINDENT .SS salt.modules.devmap .sp Device\-Mapper module @@ -73799,11 +72767,10 @@ option. This will give users a couple release cycles to modify their scripts, SLS files, etc. to use the new functionality, rather than forcing users to change everything immediately. .sp -In the \fBCarbon\fP release of Salt (slated for late summer/early fall 2015), -this execution module will take the place of the default Docker execution -module, and backwards\-compatible naming will be maintained for a couple -releases after that to allow users time to replace references to \fBdockerng\fP -with \fBdocker\fP\&. +In the \fBCarbon\fP release of Salt (due early 2016), this execution module will +take the place of the default Docker execution module, and backwards\-compatible +naming will be maintained for a couple releases after that to allow users time +to replace references to \fBdockerng\fP with \fBdocker\fP\&. .SS Installation Prerequisites .sp This execution module requires at least version 1.0.0 of both \fI\%docker\-py\fP and @@ -73900,6 +72867,30 @@ bar\-docker\-registries: .sp Both methods can be combined; any registry configured under \fBdocker\-registries\fP or \fB*\-docker\-registries\fP will be detected. +.SS Configuration Options +.sp +The following options can be set in the \fIminion config\fP: +.INDENT 0.0 +.IP \(bu 2 +\fBdocker.url\fP: URL to the docker service (default: local socket). +.IP \(bu 2 +\fBdocker.version\fP: API version to use (default: currently 1.4 API). +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fBdocker.exec_driver\fP: Execution driver to use, one of the following: +.INDENT 7.0 +.IP \(bu 2 +nsenter +.IP \(bu 2 +lxc\-attach +.IP \(bu 2 +docker\-exec +.UNINDENT +.sp +See \fI\%Executing Commands Within a Running Container\fP\&. +.UNINDENT +.UNINDENT .SS Functions .INDENT 0.0 .IP \(bu 2 @@ -76860,7 +75851,7 @@ CLI Example: .sp .nf .ft C -salt dell drac.getniccfg +salt dell drac.network_info .ft P .fi .UNINDENT @@ -77062,7 +76053,7 @@ CLI Example: .sp .nf .ft C -salt dell drac.getsysinfo +salt dell drac.system_info .ft P .fi .UNINDENT @@ -79125,7 +78116,7 @@ salt \(aq*\(aq file.blockreplace /etc/hosts \(aq#\-\- start managed zone foobar .UNINDENT .INDENT 0.0 .TP -.B salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, saltenv, template=None, contents=None) +.B salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, saltenv, contents=None) Check for the changes in the file metadata. .sp CLI Example: @@ -79147,6 +78138,45 @@ Supported hash types include sha512, sha384, sha256, sha224, sha1, and md5. .UNINDENT .UNINDENT +.INDENT 7.0 +.TP +.B name +Path to file destination +.TP +.B sfn +Template\-processed source file contents +.TP +.B source +URL to file source +.TP +.B source_sum +File checksum information as a dictionary +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +{hash_type: md5, hsum: } +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B user +Destination file user owner +.TP +.B group +Destination file group owner +.TP +.B mode +Destination file permissions mode +.TP +.B saltenv +Salt environment used to resolve source files +.TP +.B contents +File contents +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -79335,6 +78365,89 @@ salt \(aq*\(aq file.comment /etc/modules pcspkr .UNINDENT .INDENT 0.0 .TP +.B salt.modules.file.comment_line(path, regex, char=\(aq#\(aq, cmnt=True, backup=\(aq.bak\(aq) +Comment or Uncomment a line in a text file. +.INDENT 7.0 +.TP +.B Parameters +\fBpath\fP \-\- string +.UNINDENT +.sp +The full path to the text file. +.INDENT 7.0 +.TP +.B Parameters +\fBregex\fP \-\- string +.UNINDENT +.sp +A regex expression that begins with \fB^\fP that will find the line you wish +to comment. Can be as simple as \fB^color =\fP +.INDENT 7.0 +.TP +.B Parameters +\fBchar\fP \-\- string +.UNINDENT +.sp +The character used to comment a line in the type of file you\(aqre referencing. +Default is \fB#\fP +.INDENT 7.0 +.TP +.B Parameters +\fBcmnt\fP \-\- boolean +.UNINDENT +.sp +True to comment the line. False to uncomment the line. Default is True. +.INDENT 7.0 +.TP +.B Parameters +\fBbackup\fP \-\- string +.UNINDENT +.sp +The file extension to give the backup file. Default is \fB\&.bak\fP +.INDENT 7.0 +.TP +.B Returns +boolean +.UNINDENT +.sp +Returns True if successful, False if not +.sp +CLI Example: +.sp +The following example will comment out the \fBpcspkr\fP line in the +\fB/etc/modules\fP file using the default \fB#\fP character and create a backup +file named \fBmodules.bak\fP +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq file.comment_line \(aq/etc/modules\(aq \(aq^pcspkr\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +CLI Example: +.sp +The following example will uncomment the \fBlog_level\fP setting in \fBminion\fP +config file if it is set to either \fBwarning\fP, \fBinfo\fP, or \fBdebug\fP using +the \fB#\fP character and create a backup file named \fBminion.bk\fP +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +salt \(aq*\(aq file.comment_line \(aqC:saltconfminion\(aq \(aq^log_level: (warning|info|debug)\(aq \(aq#\(aq False \(aq.bk\(aq +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.file.contains(path, text) Deprecated since version 0.17.0: Use \fI\%search()\fP instead. @@ -84486,32 +83599,52 @@ salt \(aq*\(aq gentoolkit.revdep_rebuild Support for the Git SCM .INDENT 0.0 .TP -.B salt.modules.git.add(cwd, file_name, user=None, opts=None) -add a file to git +.B salt.modules.git.add(cwd, filename, opts=\(aq\(aq, user=None, ignore_retcode=False) +Changed in version 2015.8.0: The \fB\-\-verbose\fP command line argument is now implied + +.sp +Interface to \fI\%git\-add(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout .TP -.B file_name -Path to the file in the cwd +.B filename +The location of the file/directory to add, relative to \fBcwd\fP .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp -CLI Example: +CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -salt \(aq*\(aq git.add /path/to/git/repo /path/to/file +salt myminion git.add /path/to/repo foo/bar.py +salt myminion git.add /path/to/repo foo/bar.py opts=\(aq\-\-dry\-run\(aq .ft P .fi .UNINDENT @@ -84519,33 +83652,101 @@ salt \(aq*\(aq git.add /path/to/git/repo /path/to/file .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.archive(cwd, output, rev=\(aqHEAD\(aq, fmt=None, prefix=None, user=None) -Export a tarball from the repository +.B salt.modules.git.archive(cwd, output, rev=\(aqHEAD\(aq, fmt=None, prefix=None, user=None, ignore_retcode=False, **kwargs) +Changed in version 2015.8.0: Returns \fBTrue\fP if successful, raises an error if not. + +.sp +Interface to \fI\%git\-archive(1)\fP, exports a tarball/zip file of the +repository .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to be archived +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fBgit archive\fP permits a partial archive to be created. Thus, this +path does not need to be the root of the git repository. Only the +files within the directory specified by \fBcwd\fP (and its +subdirectories) will be in the resulting archive. For example, if +there is a git checkout at \fB/tmp/foo\fP, then passing +\fB/tmp/foo/bar\fP as the \fBcwd\fP will result in just the files +underneath \fB/tmp/foo/bar\fP to be exported as an archive. +.UNINDENT +.UNINDENT .TP .B output -The path to the archive tarball +The path of the archive to be created .TP -.B rev: HEAD -The revision to create an archive from +.B overwrite +False +Unless set to \fBTrue\fP, Salt will over overwrite an existing archive at +the path specified by the \fBoutput\fP argument. +.sp +New in version 2015.8.0. + .TP -.B fmt: None -Format of the resulting archive, zip and tar are commonly used +.B rev +HEAD +The revision from which to create the archive +.TP +.B format +Manually specify the file format of the resulting archive. This +argument can be omitted, and \fBgit archive\fP will attempt to guess the +archive type (and compression) from the filename. \fBzip\fP, \fBtar\fP, +\fBtar.gz\fP, and \fBtgz\fP are extensions that are recognized +automatically, and git can be configured to support other archive types +with the addition of git configuration keys. +.sp +See the \fI\%git\-archive(1)\fP manpage explanation of the +\fB\-\-format\fP argument (as well as the \fBCONFIGURATION\fP section of the +manpage) for further information. +.sp +New in version 2015.8.0. + +.TP +.B fmt +Replaced by \fBformat\fP in version 2015.8.0 +.sp +Deprecated since version 2015.8.0. + .TP .B prefix -None -Prepend / to every filename in the archive -.TP -.B user -None -Run git as a user other than what the minion runs as +Prepend \fB\fP to every filename in the archive. If unspecified, +the name of the directory at the top level of the repository will be +used as the prefix (e.g. if \fBcwd\fP is set to \fB/foo/bar/baz\fP, the +prefix will be \fBbaz\fP, and the resulting archive will contain a +top\-level directory by that name). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The default behavior if the \fB\-\-prefix\fP option for \fBgit archive\fP +is not specified is to not prepend a prefix, so Salt\(aqs behavior +differs slightly from \fBgit archive\fP in this respect. Use +\fBprefix=\(aq\(aq\fP to create an archive with no prefix. +.UNINDENT .UNINDENT .sp -If \fBprefix\fP is not specified it defaults to the basename of the repo -directory. +Changed in version 2015.8.0: The behavior of this argument has been changed slightly. As of +this version, it is necessary to include the trailing slash when +specifying a prefix, if the prefix is intended to create a +top\-level directory. + +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -84553,7 +83754,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.archive /path/to/repo /path/to/archive.tar.gz +salt myminion git.archive /path/to/repo /path/to/archive.tar .ft P .fi .UNINDENT @@ -84561,32 +83762,62 @@ salt \(aq*\(aq git.archive /path/to/repo /path/to/archive.tar.gz .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.branch(cwd, rev, opts=None, user=None) -Interacts with branches. +.B salt.modules.git.branch(cwd, name=None, opts=\(aq\(aq, user=None, ignore_retcode=False) +Interface to \fI\%git\-branch(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout .TP -.B rev -The branch/revision to be used in the command. +.B name +Name of the branch on which to operate. If not specified, the current +branch will be assumed. .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +To create a branch based on something other than HEAD, pass the +name of the revision as \fBopts\fP\&. If the revision is in the format +\fBremotename/branch\fP, then this will also set the remote tracking +branch. +.sp +Additionally, on the Salt CLI, if the opts are preceded with a +dash, it is necessary to precede them with \fBopts=\fP (as in the CLI +examples below) to avoid causing errors with Salt\(aqs own argument +parsing. +.UNINDENT +.UNINDENT .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp -CLI Example: +CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -salt \(aq*\(aq git.branch mybranch \-\-set\-upstream\-to=origin/mybranch +# Set remote tracking branch +salt myminion git.branch /path/to/repo mybranch opts=\(aq\-\-set\-upstream\-to origin/mybranch\(aq +# Create new branch +salt myminion git.branch /path/to/repo mybranch upstream/somebranch +# Delete branch +salt myminion git.branch /path/to/repo mybranch opts=\(aq\-d\(aq +# Rename branch (2015.8.0 and later) +salt myminion git.branch /path/to/repo newbranch opts=\(aq\-m oldbranch\(aq .ft P .fi .UNINDENT @@ -84594,27 +83825,46 @@ salt \(aq*\(aq git.branch mybranch \-\-set\-upstream\-to=origin/mybranch .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.checkout(cwd, rev, force=False, opts=None, user=None) -Checkout a given revision +.B salt.modules.git.checkout(cwd, rev=None, force=False, opts=\(aq\(aq, user=None, ignore_retcode=False) +Interface to \fI\%git\-checkout(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout +.TP +.B opts +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT .TP .B rev -The remote branch or revision to checkout +The remote branch or revision to checkout. +.sp +Changed in version 2015.8.0: Optional when using \fB\-b\fP or \fB\-B\fP in \fBopts\fP\&. + .TP .B force False Force a checkout even if there might be overwritten changes .TP -.B opts -None -Any additional options to add to the command line -.TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Examples: @@ -84623,11 +83873,14 @@ CLI Examples: .sp .nf .ft C -salt \(aq*\(aq git.checkout /path/to/repo somebranch user=jeff - -salt \(aq*\(aq git.checkout /path/to/repo opts=\(aqtestbranch \-\- conf/file1 file2\(aq - -salt \(aq*\(aq git.checkout /path/to/repo rev=origin/mybranch opts=\-\-track +# Checking out local local revisions +salt myminion git.checkout /path/to/repo somebranch user=jeff +salt myminion git.checkout /path/to/repo opts=\(aqtestbranch \-\- conf/file1 file2\(aq +salt myminion git.checkout /path/to/repo rev=origin/mybranch opts=\(aq\-\-track\(aq +# Checking out remote revision into new branch +salt myminion git.checkout /path/to/repo upstream/master opts=\(aq\-b newbranch\(aq +# Checking out current revision into new branch (2015.8.0 and later) +salt myminion git.checkout /path/to/repo opts=\(aq\-b newbranch\(aq .ft P .fi .UNINDENT @@ -84635,41 +83888,71 @@ salt \(aq*\(aq git.checkout /path/to/repo rev=origin/mybranch opts=\-\-track .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.clone(cwd, repository, opts=None, user=None, identity=None, https_user=None, https_pass=None) -Clone a new repository +.B salt.modules.git.clone(cwd, url=None, name=None, opts=\(aq\(aq, user=None, identity=None, https_user=None, https_pass=None, ignore_retcode=False, repository=None) +Interface to \fI\%git\-clone(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +Location of git clone +.sp +Changed in version 2015.8.0: If \fBname\fP is passed, then the clone will be made \fIwithin\fP this +directory. + .TP -.B repository -The git URI of the repository +.B url +The URL of the repository to be cloned +.sp +Changed in version 2015.8.0: Argument renamed from \fBrepository\fP to \fBurl\fP + +.TP +.B name +Optional alternate name for the top\-level directory to be created by +the clone +.sp +New in version 2015.8.0. + .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string .TP .B user -None +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.sp Run git as a user other than what the minion runs as .TP .B identity -None -A path to a private key to use over SSH +Path to a private key to use for ssh URLs +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Key must be passphraseless to allow for non\-interactive login. For +greater security with passphraseless private keys, see the +\fI\%sshd(8)\fP manpage for information on securing the keypair from the +remote side in the \fBauthorized_keys\fP file. +.UNINDENT +.UNINDENT .TP .B https_user -None -HTTP Basic Auth username for HTTPS (only) clones +Set HTTP Basic Auth username. Only accepted for HTTPS URLs. .sp New in version 20515.5.0. .TP .B https_pass -None -HTTP Basic Auth password for HTTPS (only) clones +Set HTTP Basic Auth password. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -84678,10 +83961,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.clone /path/to/repo git://github.com/saltstack/salt.git - -salt \(aq*\(aq git.clone /path/to/repo.git\e - git://github.com/saltstack/salt.git \(aq\-\-bare \-\-origin github\(aq +salt myminion git.clone /path/to/repo_parent_dir git://github.com/saltstack/salt.git .ft P .fi .UNINDENT @@ -84689,148 +83969,58 @@ salt \(aq*\(aq git.clone /path/to/repo.git\e .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.commit(cwd, message, user=None, opts=None) -create a commit +.B salt.modules.git.commit(cwd, message, opts=\(aq\(aq, user=None, filename=None, ignore_retcode=False) +Interface to \fI\%git\-commit(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout .TP .B message -The commit message +Commit message .TP .B opts -None -Any additional options to add to the command line -.TP -.B user -None -Run git as a user other than what the minion runs as -.UNINDENT +Any additional options to add to the command line, in a single string .sp -CLI Example: +\fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. .sp -.nf -.ft C -salt \(aq*\(aq git.commit /path/to/git/repo \(aqThe commit message\(aq -.ft P -.fi +The \fB\-m\fP option should not be passed here, as the commit message +will be defined by the \fBmessage\fP argument. .UNINDENT .UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.git.config_get(cwd=None, setting_name=None, user=None) -Get a key or keys from the git configuration file (.git/config). -.INDENT 7.0 -.TP -.B cwd -None -Optional path to a Git repository -.sp -Changed in version 2014.7.0: Made \fBcwd\fP optional - -.TP -.B setting_name -None -The name of the configuration key to get. Required. .TP .B user -None -Run git as a user other than what the minion runs as -.UNINDENT +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B filename +The location of the file/directory to commit, relative to \fBcwd\fP\&. +This argument is optional, and can be used to commit a file without +first staging it. .sp -CLI Example: +\fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 +This argument only works on files which are already tracked by the +git repository. +.UNINDENT +.UNINDENT .sp -.nf -.ft C -salt \(aq*\(aq git.config_get setting_name=user.email -salt \(aq*\(aq git.config_get /path/to/repo user.name arthur -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.git.config_set(cwd=None, setting_name=None, setting_value=None, user=None, is_global=False) -Set a key in the git configuration file (.git/config) of the repository or -globally. -.INDENT 7.0 -.TP -.B cwd -None -Options path to the Git repository -.sp -Changed in version 2014.7.0: Made \fBcwd\fP optional +New in version 2015.8.0. .TP -.B setting_name -None -The name of the configuration key to set. Required. -.TP -.B setting_value -None -The (new) value to set. Required. -.TP -.B user -None -Run git as a user other than what the minion runs as -.TP -.B is_global +.B ignore_retcode False -Set to True to use the \(aq\-\-global\(aq flag with \(aqgit config\(aq -.UNINDENT +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. .sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq git.config_set /path/to/repo user.email me@example.com -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.git.current_branch(cwd, user=None) -Returns the current branch name, if on a branch. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq git.current_branch /path/to/repo -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.git.describe(cwd, rev=\(aqHEAD\(aq, user=None) -Returns the git describe string (or the SHA hash if there are no tags) for -the given revision -.INDENT 7.0 -.TP -.B cwd -The path to the Git repository -.TP -.B rev: HEAD -The revision to describe -.TP -.B user -None -Run git as a user other than what the minion runs as +New in version 2015.8.0. + .UNINDENT .sp CLI Examples: @@ -84839,9 +84029,8 @@ CLI Examples: .sp .nf .ft C -salt \(aq*\(aq git.describe /path/to/repo - -salt \(aq*\(aq git.describe /path/to/repo develop +salt myminion git.commit /path/to/repo \(aqThe commit message\(aq +salt myminion git.commit /path/to/repo \(aqThe commit message\(aq filename=foo/bar.py .ft P .fi .UNINDENT @@ -84849,24 +84038,192 @@ salt \(aq*\(aq git.describe /path/to/repo develop .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.fetch(cwd, opts=None, user=None, identity=None) -Perform a fetch on the given repository +.B salt.modules.git.config_get(key, cwd=None, user=None, ignore_retcode=False, **kwargs) +Get the value of a key in the git configuration file +.INDENT 7.0 +.TP +.B key +The name of the configuration key to get +.sp +Changed in version 2015.8.0: Argument renamed from \fBsetting_name\fP to \fBkey\fP + +.TP +.B cwd +The path to the git checkout +.sp +Changed in version 2015.8.0: Now optional if \fBglobal\fP is set to \fBTrue\fP + +.TP +.B global +False +If \fBTrue\fP, query the global git configuraton. Otherwise, only the +local git configuration will be queried. +.sp +New in version 2015.8.0. + +.TP +.B all +False +If \fBTrue\fP, return a list of all values set for \fBkey\fP\&. If the key +does not exist, \fBNone\fP will be returned. +.sp +New in version 2015.8.0. + +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.config_get user.name cwd=/path/to/repo +salt myminion git.config_get user.email global=True +salt myminion git.config_get core.gitproxy cwd=/path/to/repo all=True +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.config_get_regexp(key, value_regex=None, cwd=None, user=None, ignore_retcode=False, **kwargs) +Get the value of a key or keys in the git configuration file using regexes +for more flexible matching. The return data is a dictionary mapping keys to +lists of values matching the \fBvalue_regex\fP\&. If no values match, an empty +dictionary will be returned. +.INDENT 7.0 +.TP +.B key +Regex on which key names will be matched +.TP +.B value_regex +If specified, return all values matching this regex. The return data +will be a dictionary mapping keys to lists of values matching the +regex. +.sp +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +Only values matching the \fBvalue_regex\fP will be part of the return +data. So, if \fBkey\fP matches a multivar, then it is possible that +not all of the values will be returned. To get all values set for a +multivar, simply omit the \fBvalue_regex\fP argument. +.UNINDENT +.UNINDENT +.TP +.B cwd +The path to the git checkout +.TP +.B global +False +If \fBTrue\fP, query the global git configuraton. Otherwise, only the +local git configuration will be queried. +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Matches any values for key \(aqfoo.bar\(aq +salt myminion git.config_get_regexp /path/to/repo foo.bar +# Matches any value starting with \(aqbaz\(aq set for key \(aqfoo.bar\(aq +salt myminion git.config_get_regexp /path/to/repo foo.bar \(aqbaz.*\(aq +# Matches any key starting with \(aquser.\(aq +salt myminion git.config_get_regexp \(aq^user\e.\(aq global=True +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.config_set(key, value=None, multivar=None, cwd=None, user=None, ignore_retcode=False, **kwargs) +Changed in version 2015.8.0: Return the value(s) of the key being set + +.sp +Set a key in the git configuration file .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout. Must be an absolute path, or the word +\fBglobal\fP to indicate that a global key should be set. +.sp +Changed in version 2014.7.0: Made \fBcwd\fP argument optional if \fBis_global=True\fP + .TP -.B opts -None -Any additional options to add to the command line +.B key +The name of the configuration key to set +.sp +Changed in version 2015.8.0: Argument renamed from \fBsetting_name\fP to \fBkey\fP + +.TP +.B value +The value to set for the specified key. Incompatible with the +\fBmultivar\fP argument. +.sp +Changed in version 2015.8.0: Argument renamed from \fBsetting_value\fP to \fBvalue\fP + +.TP +.B add +False +Add a value to a key, creating/updating a multivar +.sp +New in version 2015.8.0. + +.TP +.B multivar +Set a multivar all at once. Values can be comma\-separated or passed as +a Python list. Incompatible with the \fBvalue\fP argument. +.sp +New in version 2015.8.0. + .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. .TP -.B identity -None -A path to a private key to use over SSH +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.TP +.B global +False +If \fBTrue\fP, set a global variable +.TP +.B is_global +False +If \fBTrue\fP, set a global variable +.sp +Deprecated since version 2015.8.0: Use \fBglobal\fP instead + .UNINDENT .sp CLI Example: @@ -84875,9 +84232,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.fetch /path/to/repo \(aq\-\-all\(aq - -salt \(aq*\(aq git.fetch cwd=/path/to/repo opts=\(aq\-\-all\(aq user=johnny +salt myminion git.config_set user.email me@example.com cwd=/path/to/repo +salt myminion git.config_set user.email foo@bar.com global=True .ft P .fi .UNINDENT @@ -84885,20 +84241,42 @@ salt \(aq*\(aq git.fetch cwd=/path/to/repo opts=\(aq\-\-all\(aq user=johnny .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.init(cwd, opts=None, user=None) -Initialize a new git repository +.B salt.modules.git.config_unset(key, value_regex=None, cwd=None, user=None, ignore_retcode=False, **kwargs) +New in version 2015.8.0. + +.sp +Unset a key in the git configuration file .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout. Must be an absolute path, or the word +\fBglobal\fP to indicate that a global key should be unset. .TP -.B opts -None -Any additional options to add to the command line +.B key +The name of the configuration key to unset +.TP +.B value_regex +Regular expression that matches exactly one key, used to delete a +single value from a multivar. Ignored if \fBall\fP is set to \fBTrue\fP\&. +.TP +.B all +False +If \fBTrue\fP unset all values for a multivar. If \fBFalse\fP, and \fBkey\fP +is a multivar, an error will be raised. +.TP +.B global +False +If \fBTrue\fP, unset set a global variable. Otherwise, a local variable +will be unset. .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. .UNINDENT .sp CLI Example: @@ -84907,7 +84285,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.init /path/to/repo.git opts=\(aq\-\-bare\(aq +salt myminion git.config_unset /path/to/repo foo.bar +salt myminion git.config_unset /path/to/repo foo.bar all=True .ft P .fi .UNINDENT @@ -84915,41 +84294,475 @@ salt \(aq*\(aq git.init /path/to/repo.git opts=\(aq\-\-bare\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.ls_remote(cwd, repository=\(aqorigin\(aq, branch=\(aqmaster\(aq, user=None, identity=None, https_user=None, https_pass=None) -Returns the upstream hash for any given URL and branch. +.B salt.modules.git.current_branch(cwd, user=None, ignore_retcode=False) +Returns the current branch name of a local checkout. If HEAD is detached, +return the SHA1 of the revision which is currently checked out. .INDENT 7.0 .TP .B cwd -The path to the Git repository -.TP -.B repository: origin -The name of the repository to get the revision from. Can be the name of -a remote, an URL, etc. -.TP -.B branch: master -The name of the branch to get the revision from. +The path to the git checkout .TP .B user -none -run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.current_branch /path/to/repo +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.describe(cwd, rev=\(aqHEAD\(aq, user=None, ignore_retcode=False) +Returns the \fI\%git\-describe(1)\fP string (or the SHA1 hash if there are no +tags) for the given revision. +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B rev +HEAD +The revision to describe +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.describe /path/to/repo +salt myminion git.describe /path/to/repo develop +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.fetch(cwd, remote=None, force=False, refspecs=None, opts=\(aq\(aq, user=None, identity=None, ignore_retcode=False) +Interface to \fI\%git\-fetch(1)\fP +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B remote +Optional remote name to fetch. If not passed, then git will use its +default behavior (as detailed in \fI\%git\-fetch(1)\fP). +.sp +New in version 2015.8.0. + +.TP +.B force +Force the fetch even when it is not a fast\-forward. +.sp +New in version 2015.8.0. + +.TP +.B refspecs +Override the refspec(s) configured for the remote with this argument. +Multiple refspecs can be passed, comma\-separated. +.sp +New in version 2015.8.0. + +.TP +.B opts +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. .TP .B identity -none -a path to a private key to use over ssh +Path to a private key to use for ssh URLs +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Key must be passphraseless to allow for non\-interactive login. For +greater security with passphraseless private keys, see the +\fI\%sshd(8)\fP manpage for information on securing the keypair from the +remote side in the \fBauthorized_keys\fP file. +.UNINDENT +.UNINDENT +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.fetch /path/to/repo upstream +salt myminion git.fetch /path/to/repo identity=/root/.ssh/id_rsa +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.init(cwd, bare=False, template=None, separate_git_dir=None, shared=None, opts=\(aq\(aq, user=None, ignore_retcode=False) +Interface to \fI\%git\-init(1)\fP +.INDENT 7.0 +.TP +.B cwd +The path to the directory to be initialized +.TP +.B bare +False +If \fBTrue\fP, init a bare repository +.sp +New in version 2015.8.0. + +.TP +.B template +Set this argument to specify an alternate \fI\%template directory\fP +.sp +New in version 2015.8.0. + +.TP +.B separate_git_dir +Set this argument to specify an alternate \fB$GIT_DIR\fP +.sp +New in version 2015.8.0. + +.TP +.B shared +Set sharing permissions on git repo. See \fI\%git\-init(1)\fP for more +details. +.sp +New in version 2015.8.0. + +.TP +.B opts +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.init /path/to/repo +# Init a bare repo (before 2015.8.0) +salt myminion git.init /path/to/bare/repo.git opts=\(aq\-\-bare\(aq +# Init a bare repo (2015.8.0 and later) +salt myminion git.init /path/to/bare/repo.git bare=True +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.is_worktree(cwd, user=None) +New in version 2015.8.0. + +.sp +This function will attempt to determine if \fBcwd\fP is part of a +worktree by checking its \fB\&.git\fP to see if it is a file containing a +reference to another gitdir. +.INDENT 7.0 +.TP +.B cwd +path to the worktree to be removed +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.is_worktree /path/to/repo +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.list_branches(cwd, remote=False, user=None, ignore_retcode=False) +New in version 2015.8.0. + +.sp +Return a list of branches +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B remote +False +If \fBTrue\fP, list remote branches. Otherwise, local branches will be +listed. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This option will only return remote branches of which the local +checkout is aware, use \fI\%git.fetch\fP to update remotes. +.UNINDENT +.UNINDENT +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.list_branches /path/to/repo +salt myminion git.list_branches /path/to/repo remote=True +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.list_tags(cwd, user=None, ignore_retcode=False) +New in version 2015.8.0. + +.sp +Return a list of tags +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.list_tags /path/to/repo +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.list_worktrees(cwd, stale=False, user=None, **kwargs) +New in version 2015.8.0. + +.sp +Return a dictionary mapping worktrees to their locations. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This information is compiled by analyzing the administrative data in +$GIT_DIR/worktrees. By default, only worktrees for which the gitdir is +still present are returned, but this can be changed using the \fBall\fP +and \fBstale\fP arguments (described below). +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B all +False +If \fBTrue\fP, then return all worktrees, including ones whose gitdir is +no longer present. +.TP +.B stale +False +If \fBTrue\fP, return only worktrees whose gitdir is no longer present. +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.list_worktrees /path/to/repo +salt myminion git.list_worktrees /path/to/repo all=True +salt myminion git.list_worktrees /path/to/repo stale=True +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.ls_remote(cwd=None, remote=\(aqorigin\(aq, ref=\(aqmaster\(aq, opts=\(aq\(aq, user=None, identity=None, https_user=None, https_pass=None, ignore_retcode=False) +Interface to \fI\%git\-ls\-remote(1)\fP\&. Returns the upstream hash for a remote +reference. +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout. Optional (and ignored if present) when +\fBremote\fP is set to a URL instead of a remote name. +.TP +.B remote +origin +The name of the remote to query. Can be the name of a git remote +(which exists in the git checkout defined by the \fBcwd\fP parameter), +or the URL of a remote repository. +.sp +Changed in version 2015.8.0: Argument renamed from \fBrepository\fP to \fBremote\fP + +.TP +.B ref +master +The name of the ref to query. Can be a branch or tag name, or the full +name of the reference (for example, to get the hash for a Github pull +request number 1234, \fBref\fP can be set to \fBrefs/pull/1234/head\fP +.sp +Changed in version 2015.8.0: Argument renamed from \fBbranch\fP to \fBref\fP + +.TP +.B opts +Any additional options to add to the command line, in a single string +.sp +New in version 2015.8.0. + +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B identity +Path to a private key to use for ssh URLs +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Key must be passphraseless to allow for non\-interactive login. For +greater security with passphraseless private keys, see the +\fI\%sshd(8)\fP manpage for information on securing the keypair from the +remote side in the \fBauthorized_keys\fP file. +.UNINDENT +.UNINDENT .TP .B https_user -None -HTTP Basic Auth username for HTTPS (only) clones +Set HTTP Basic Auth username. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. .TP .B https_pass -None -HTTP Basic Auth password for HTTPS (only) clones +Set HTTP Basic Auth password. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -84958,7 +84771,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.ls_remote /pat/to/repo origin master +salt myminion git.ls_remote /path/to/repo origin master +salt myminion git.ls_remote remote=https://mydomain.tld/repo.git ref=mytag opts=\(aq\-\-tags\(aq .ft P .fi .UNINDENT @@ -84966,24 +84780,50 @@ salt \(aq*\(aq git.ls_remote /pat/to/repo origin master .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.merge(cwd, branch=\(aq@{upstream}\(aq, opts=None, user=None) -Merge a given branch +.B salt.modules.git.merge(cwd, rev=None, opts=\(aq\(aq, user=None, branch=None, ignore_retcode=False) +Interface to \fI\%git\-merge(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout +.TP +.B rev +Revision to merge into the current branch. If not specified, the remote +tracking branch will be merged. +.sp +New in version 2015.8.0. + .TP .B branch -@{upstream} The remote branch or revision to merge into the current branch +Revision to merge into the current branch +.sp +Deprecated since version 2015.8.0: Use \fBrev\fP instead. + .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -84992,8 +84832,12 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.fetch /path/to/repo -salt \(aq*\(aq git.merge /path/to/repo @{upstream} +# Fetch first... +salt myminion git.fetch /path/to/repo +# ... then merge the remote tracking branch +salt myminion git.merge /path/to/repo +# .. or merge another rev +salt myminion git.merge /path/to/repo rev=upstream/foo .ft P .fi .UNINDENT @@ -85001,24 +84845,199 @@ salt \(aq*\(aq git.merge /path/to/repo @{upstream} .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.pull(cwd, opts=None, user=None, identity=None) -Perform a pull on the given repository +.B salt.modules.git.merge_base(cwd, refs=None, octopus=False, is_ancestor=False, independent=False, fork_point=None, opts=\(aq\(aq, user=None, ignore_retcode=False, **kwargs) +New in version 2015.8.0. + +.sp +Interface to \fI\%git\-merge\-base(1)\fP\&. .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout +.TP +.B refs +Any refs/commits to check for a merge base. Can be passed as a +comma\-separated list or a Python list. +.TP +.B all +False +Return a list of all matching merge bases. Not compatible with any of +the below options except for \fBoctopus\fP\&. +.TP +.B octopus +False +If \fBTrue\fP, then this function will determine the best common +ancestors of all specified commits, in preparation for an n\-way merge. +See \fI\%here\fP for a description of how these bases are determined. +.sp +Set \fBall\fP to \fBTrue\fP with this option to return all computed merge +bases, otherwise only the "best" will be returned. +.TP +.B is_ancestor +False +If \fBTrue\fP, then instead of returning the merge base, return a +boolean telling whether or not the first commit is an ancestor of the +second commit. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This option requires two commits to be passed. +.UNINDENT +.UNINDENT +.TP +.B independent +False +If \fBTrue\fP, this function will return the IDs of the refs/commits +passed which cannot be reached by another commit. +.TP +.B fork_point +If passed, then this function will return the commit where the +commit diverged from the ref specified by \fBfork_point\fP\&. If no fork +point is found, \fBNone\fP is returned. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +At most one commit is permitted to be passed if a \fBfork_point\fP is +specified. If no commits are passed, then \fBHEAD\fP is assumed. +.UNINDENT +.UNINDENT .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.sp +This option should not be necessary unless new CLI arguments are +added to \fI\%git\-merge\-base(1)\fP and are not yet supported in Salt. +.UNINDENT +.UNINDENT .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +if \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.merge_base /path/to/repo HEAD upstream/mybranch +salt myminion git.merge_base /path/to/repo 8f2e542,4ad8cab,cdc9886 octopus=True +salt myminion git.merge_base /path/to/repo refs=8f2e542,4ad8cab,cdc9886 independent=True +salt myminion git.merge_base /path/to/repo refs=8f2e542,4ad8cab is_ancestor=True +salt myminion git.merge_base /path/to/repo fork_point=upstream/master +salt myminion git.merge_base /path/to/repo refs=mybranch fork_point=upstream/master +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.merge_tree(cwd, ref1, ref2, base=None, user=None, ignore_retcode=False) +New in version 2015.8.0. + +.sp +Interface to \fI\%git\-merge\-tree(1)\fP, shows the merge results and conflicts +from a 3\-way merge without touching the index. +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B ref1 +First ref/commit to compare +.TP +.B ref2 +Second ref/commit to compare +.TP +.B base +The base tree to use for the 3\-way\-merge. If not provided, then +\fI\%git.merge_base\fP will be invoked +on \fBref1\fP and \fBref2\fP to determine the merge base to use. +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +if \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.merge_tree /path/to/repo HEAD upstream/dev +salt myminion git.merge_tree /path/to/repo HEAD upstream/dev base=aaf3c3d +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.pull(cwd, opts=\(aq\(aq, user=None, identity=None, ignore_retcode=False) +Interface to \fI\%git\-pull(1)\fP +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B opts +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. .TP .B identity -None -A path to a private key to use over SSH +Path to a private key to use for ssh URLs +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Key must be passphraseless to allow for non\-interactive login. For +greater security with passphraseless private keys, see the +\fI\%sshd(8)\fP manpage for information on securing the keypair from the +remote side in the \fBauthorized_keys\fP file. +.UNINDENT +.UNINDENT +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -85027,7 +85046,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.pull /path/to/repo opts=\(aq\-\-rebase origin master\(aq +salt myminion git.pull /path/to/repo opts=\(aq\-\-rebase origin master\(aq .ft P .fi .UNINDENT @@ -85035,31 +85054,73 @@ salt \(aq*\(aq git.pull /path/to/repo opts=\(aq\-\-rebase origin master\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.push(cwd, remote_name, branch=\(aqmaster\(aq, user=None, opts=None, identity=None) -Push to remote +.B salt.modules.git.push(cwd, remote=None, ref=None, opts=\(aq\(aq, user=None, identity=None, ignore_retcode=False, branch=None) +Interface to \fI\%git\-push(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout .TP -.B remote_name -Name of the remote to push to +.B remote +Name of the remote to which the ref should being pushed +.sp +New in version 2015.8.0. + +.TP +.B ref +master +Name of the ref to push +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Being a \fI\%refspec\fP, this argument can include a colon to define local +and remote ref names. +.UNINDENT +.UNINDENT .TP .B branch -master -Name of the branch to push +Name of the ref to push +.sp +Deprecated since version 2015.8.0: Use \fBref\fP instead + .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. .TP .B identity -None -A path to a private key to use over SSH +Path to a private key to use for ssh URLs +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Key must be passphraseless to allow for non\-interactive login. For +greater security with passphraseless private keys, see the +\fI\%sshd(8)\fP manpage for information on securing the keypair from the +remote side in the \fBauthorized_keys\fP file. +.UNINDENT +.UNINDENT +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -85068,7 +85129,12 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.push /path/to/git/repo remote\-name +# Push master as origin/master +salt myminion git.push /path/to/repo origin master +# Push issue21 as upstream/develop +salt myminion git.push /path/to/repo upstream issue21:develop +# Delete remote branch \(aqupstream/temp\(aq +salt myminion git.push /path/to/repo upstream :temp .ft P .fi .UNINDENT @@ -85076,24 +85142,40 @@ salt \(aq*\(aq git.push /path/to/git/repo remote\-name .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.rebase(cwd, rev=\(aqmaster\(aq, opts=None, user=None) -Rebase the current branch +.B salt.modules.git.rebase(cwd, rev=\(aqmaster\(aq, opts=\(aq\(aq, user=None, ignore_retcode=False) +Interface to \fI\%git\-rebase(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout .TP .B rev master The revision to rebase onto the current branch .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -85102,21 +85184,9 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.rebase /path/to/repo master -salt \(aq*\(aq git.rebase /path/to/repo \(aqorigin master\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -That is the same as: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -git rebase master -git rebase origin master +salt myminion git.rebase /path/to/repo master +salt myminion git.rebase /path/to/repo \(aqorigin master\(aq +salt myminion git.rebase /path/to/repo origin/master opts=\(aq\-\-onto newbranch\(aq .ft P .fi .UNINDENT @@ -85124,17 +85194,108 @@ git rebase origin master .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.remote_get(cwd, remote=\(aqorigin\(aq, user=None) -get the fetch and push URL for a specified remote name +.B salt.modules.git.remote_get(cwd, remote=\(aqorigin\(aq, user=None, redact_auth=True, ignore_retcode=False) +Get the fetch and push URL for a specific remote .INDENT 7.0 .TP +.B cwd +The path to the git checkout +.TP .B remote origin -the remote name used to define the fetch and push URL +Name of the remote to query .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B redact_auth +True +Set to \fBFalse\fP to include the username/password if the remote uses +HTTPS Basic Auth. Otherwise, this information will be redacted. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Setting this to \fBFalse\fP will not only reveal any HTTPS Basic Auth +that is configured, but the return data will also be written to the +job cache. When possible, it is recommended to use SSH for +authentication. +.UNINDENT +.UNINDENT +.sp +New in version 2015.5.6. + +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.remote_get /path/to/repo +salt myminion git.remote_get /path/to/repo upstream +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.remote_refs(url, heads=False, tags=False, user=None, identity=None, https_user=None, https_pass=None, ignore_retcode=False) +New in version 2015.8.0. + +.sp +Return the remote refs for the specified URL +.INDENT 7.0 +.TP +.B url +URL of the remote repository +.TP +.B heads +False +Restrict output to heads. Can be combined with \fBtags\fP\&. +.TP +.B tags +False +Restrict output to tags. Can be combined with \fBheads\fP\&. +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B identity +Path to a private key to use for ssh URLs +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Key must be passphraseless to allow for non\-interactive login. For +greater security with passphraseless private keys, see the +\fI\%sshd(8)\fP manpage for information on securing the keypair from the +remote side in the \fBauthorized_keys\fP file. +.UNINDENT +.UNINDENT +.TP +.B https_user +Set HTTP Basic Auth username. Only accepted for HTTPS URLs. +.TP +.B https_pass +Set HTTP Basic Auth password. Only accepted for HTTPS URLs. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. .UNINDENT .sp CLI Example: @@ -85143,8 +85304,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.remote_get /path/to/repo -salt \(aq*\(aq git.remote_get /path/to/repo upstream +salt myminion git.remote_refs https://github.com/saltstack/salt.git .ft P .fi .UNINDENT @@ -85152,35 +85312,117 @@ salt \(aq*\(aq git.remote_get /path/to/repo upstream .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.remote_set(cwd, name=\(aqorigin\(aq, url=None, user=None, https_user=None, https_pass=None) -sets a remote with name and URL like git remote add +.B salt.modules.git.remote_set(cwd, url, remote=\(aqorigin\(aq, user=None, https_user=None, https_pass=None, push_url=None, push_https_user=None, push_https_pass=None, ignore_retcode=False) .INDENT 7.0 .TP -.B remote_name -origin -defines the remote name +.B cwd +The path to the git checkout .TP -.B remote_url -None -defines the remote URL; should not be None! +.B url +Remote URL to set +.TP +.B remote +origin +Name of the remote to set +.TP +.B push_url +If unset, the push URL will be identical to the fetch URL. +.sp +New in version 2015.8.0. + .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. .TP .B https_user -None -HTTP Basic Auth username for HTTPS (only) clones +Set HTTP Basic Auth username. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. .TP .B https_pass -None -HTTP Basic Auth password for HTTPS (only) clones +Set HTTP Basic Auth password. Only accepted for HTTPS URLs. .sp New in version 2015.5.0. +.TP +.B push_https_user +Set HTTP Basic Auth user for \fBpush_url\fP\&. Ignored if \fBpush_url\fP is +unset. Only accepted for HTTPS URLs. +.sp +New in version 2015.8.0. + +.TP +.B push_https_pass +Set HTTP Basic Auth password for \fBpush_url\fP\&. Ignored if \fBpush_url\fP +is unset. Only accepted for HTTPS URLs. +.sp +New in version 2015.8.0. + +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.remote_set /path/to/repo git@github.com:user/repo.git +salt myminion git.remote_set /path/to/repo git@github.com:user/repo.git remote=upstream +salt myminion git.remote_set /path/to/repo https://github.com/user/repo.git remote=upstream push_url=git@github.com:user/repo.git +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.remotes(cwd, user=None, redact_auth=True, ignore_retcode=False) +Get fetch and push URLs for each remote in a git checkout +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B redact_auth +True +Set to \fBFalse\fP to include the username/password for authenticated +remotes in the return data. Otherwise, this information will be +redacted. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Setting this to \fBFalse\fP will not only reveal any HTTPS Basic Auth +that is configured, but the return data will also be written to the +job cache. When possible, it is recommended to use SSH for +authentication. +.UNINDENT +.UNINDENT +.sp +New in version 2015.5.6. + +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -85189,8 +85431,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.remote_set /path/to/repo remote_url=git@github.com:saltstack/salt.git -salt \(aq*\(aq git.remote_set /path/to/repo origin git@github.com:saltstack/salt.git +salt myminion git.remotes /path/to/repo .ft P .fi .UNINDENT @@ -85198,55 +85439,48 @@ salt \(aq*\(aq git.remote_set /path/to/repo origin git@github.com:saltstack/salt .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.remotes(cwd, user=None) -Get remotes like git remote \-v +.B salt.modules.git.reset(cwd, opts=\(aq\(aq, user=None, ignore_retcode=False) +Interface to \fI\%git\-reset(1)\fP, returns the stdout from the git command .INDENT 7.0 .TP .B cwd -The path to the Git repository -.TP -.B user -None -Run git as a user other than what the minion runs as -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq git.remotes /path/to/repo -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.git.reset(cwd, opts=None, user=None) -Reset the repository checkout -.INDENT 7.0 -.TP -.B cwd -The path to the Git repository +The path to the git checkout .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp -CLI Example: +CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -salt \(aq*\(aq git.reset /path/to/repo master +# Soft reset to a specific commit ID +salt myminion git.reset /path/to/repo ac3ee5c +# Hard reset +salt myminion git.reset /path/to/repo opts=\(aq\-\-hard origin/master\(aq .ft P .fi .UNINDENT @@ -85254,22 +85488,85 @@ salt \(aq*\(aq git.reset /path/to/repo master .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.revision(cwd, rev=\(aqHEAD\(aq, short=False, user=None) -Returns the long hash of a given identifier (hash, branch, tag, HEAD, etc) +.B salt.modules.git.rev_parse(cwd, rev=None, opts=\(aq\(aq, user=None, ignore_retcode=False) +New in version 2015.8.0. + +.sp +Interface to \fI\%git\-rev\-parse(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout .TP -.B rev: HEAD +.B rev +Revision to parse. See the \fI\%SPECIFYING REVISIONS\fP section of the +\fI\%git\-rev\-parse(1)\fP manpage for details on how to format this argument. +.sp +This argument is optional when using the options in the \fIOptions for +Files\fP section of the \fI\%git\-rev\-parse(1)\fP manpage. +.TP +.B opts +Any additional options to add to the command line, in a single string +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Get the full SHA1 for HEAD +salt myminion git.rev_parse /path/to/repo HEAD +# Get the short SHA1 for HEAD +salt myminion git.rev_parse /path/to/repo HEAD opts=\(aq\-\-short\(aq +# Get the develop branch\(aqs upstream tracking branch +salt myminion git.rev_parse /path/to/repo \(aqdevelop@{upstream}\(aq opts=\(aq\-\-abbrev\-ref\(aq +# Get the SHA1 for the commit corresponding to tag v1.2.3 +salt myminion git.rev_parse /path/to/repo \(aqv1.2.3^{commit}\(aq +# Find out whether or not the repo at /path/to/repo is a bare repository +salt myminion git.rev_parse /path/to/repo opts=\(aq\-\-is\-bare\-repository\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.revision(cwd, rev=\(aqHEAD\(aq, short=False, user=None, ignore_retcode=False) +Returns the SHA1 hash of a given identifier (hash, branch, tag, HEAD, etc.) +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B rev +HEAD The revision .TP -.B short: False -Return an abbreviated SHA1 git hash +.B short +False +If \fBTrue\fP, return an abbreviated SHA1 git hash .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -85278,7 +85575,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.revision /path/to/repo mybranch +salt myminion git.revision /path/to/repo mybranch .ft P .fi .UNINDENT @@ -85286,32 +85583,58 @@ salt \(aq*\(aq git.revision /path/to/repo mybranch .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.rm(cwd, file_name, user=None, opts=None) -Remove a file from git +.B salt.modules.git.rm(cwd, filename, opts=\(aq\(aq, user=None, ignore_retcode=False) +Interface to \fI\%git\-rm(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout .TP -.B file_name -Path to the file in the cwd +.B filename +The location of the file/directory to remove, relative to \fBcwd\fP +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +To remove a directory, \fB\-r\fP must be part of the \fBopts\fP +parameter. +.UNINDENT +.UNINDENT .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. +.UNINDENT +.UNINDENT .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp -CLI Example: +CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -salt \(aq*\(aq git.rm /path/to/git/repo /path/to/file +salt myminion git.rm /path/to/repo foo/bar.py +salt myminion git.rm /path/to/repo foo/bar.py opts=\(aq\-\-dry\-run\(aq +salt myminion git.rm /path/to/repo foo/baz opts=\(aq\-r\(aq .ft P .fi .UNINDENT @@ -85319,20 +85642,71 @@ salt \(aq*\(aq git.rm /path/to/git/repo /path/to/file .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.stash(cwd, opts=None, user=None) -Stash changes in the repository checkout +.B salt.modules.git.stash(cwd, action=\(aqsave\(aq, opts=\(aq\(aq, user=None, ignore_retcode=False) +Interface to \fI\%git\-stash(1)\fP, returns the stdout from the git command .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the git checkout .TP .B opts -None -Any additional options to add to the command line +Any additional options to add to the command line, in a single string. +Use this to complete the \fBgit stash\fP command by adding the remaining +arguments (i.e. \fB\(aqsave \(aq\fP, \fB\(aqapply stash@{2}\(aq\fP, +\fB\(aqshow\(aq\fP, etc.). Omitting this argument will simply run \fBgit +stash\fP\&. .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.stash /path/to/repo save opts=\(aqwork in progress\(aq +salt myminion git.stash /path/to/repo apply opts=\(aqstash@{1}\(aq +salt myminion git.stash /path/to/repo drop opts=\(aqstash@{1}\(aq +salt myminion git.stash /path/to/repo list +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.status(cwd, user=None, ignore_retcode=False) +Changed in version 2015.8.0: Return data has changed from a list of lists to a dictionary + +.sp +Returns the changes to the repository +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -85341,7 +85715,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.stash /path/to/repo master +salt myminion git.status /path/to/repo .ft P .fi .UNINDENT @@ -85349,55 +85723,72 @@ salt \(aq*\(aq git.stash /path/to/repo master .UNINDENT .INDENT 0.0 .TP -.B salt.modules.git.status(cwd, user=None) -Return the status of the repository. The returned format uses the status -codes of git\(aqs \(aqporcelain\(aq output mode +.B salt.modules.git.submodule(cwd, command, opts=\(aq\(aq, user=None, identity=None, init=False, ignore_retcode=False) +Changed in version 2015.8.0: Added the \fBcommand\fP argument to allow for operations other than +\fBupdate\fP to be run on submodules, and deprecated the \fBinit\fP +argument. To do a submodule update with \fBinit=True\fP moving forward, +use \fBcommand=update opts=\(aq\-\-init\(aq\fP + +.sp +Interface to \fI\%git\-submodule(1)\fP .INDENT 7.0 .TP .B cwd -The path to the Git repository +The path to the submodule .TP -.B user -None -Run git as a user other than what the minion runs as -.UNINDENT +.B command +Submodule command to run, see \fIgit\-submodule(1) \fP for +more information. Any additional arguments after the command (such as +the URL when adding a submodule) must be passed in the \fBopts\fP +parameter. .sp -CLI Example: +New in version 2015.8.0. + +.TP +.B opts +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq git.status /path/to/git/repo -.ft P -.fi +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP (as in the CLI examples +below) to avoid causing errors with Salt\(aqs own argument parsing. .UNINDENT .UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.git.submodule(cwd, init=True, opts=None, user=None, identity=None) -Initialize git submodules -.INDENT 7.0 -.TP -.B cwd -The path to the Git repository .TP .B init -True -Ensure that new submodules are initialized -.TP -.B opts -None -Any additional options to add to the command line +False +If \fBTrue\fP, ensures that new submodules are initialized +.sp +Deprecated since version 2015.8.0: Pass \fBinit\fP as the \fBcommand\fP parameter, or include \fB\-\-init\fP +in the \fBopts\fP param with \fBcommand\fP set to update. + .TP .B user -None -Run git as a user other than what the minion runs as +User under which to run the git command. By default, the command is run +by the user under which the minion is running. .TP .B identity -None -A path to a private key to use over SSH +Path to a private key to use for ssh URLs +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Key must be passphraseless to allow for non\-interactive login. For +greater security with passphraseless private keys, see the +\fI\%sshd(8)\fP manpage for information on securing the keypair from the +remote side in the \fBauthorized_keys\fP file. +.UNINDENT +.UNINDENT +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + .UNINDENT .sp CLI Example: @@ -85406,7 +85797,302 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq git.submodule /path/to/repo.git/sub/repo +# Update submodule and ensure it is initialized (before 2015.8.0) +salt myminion git.submodule /path/to/repo/sub/repo init=True +# Update submodule and ensure it is initialized (2015.8.0 and later) +salt myminion git.submodule /path/to/repo/sub/repo update opts=\(aq\-\-init\(aq + +# Rebase submodule (2015.8.0 and later) +salt myminion git.submodule /path/to/repo/sub/repo update opts=\(aq\-\-rebase\(aq + +# Add submodule (2015.8.0 and later) +salt myminion git.submodule /path/to/repo/sub/repo add opts=\(aqhttps://mydomain.tld/repo.git\(aq + +# Unregister submodule (2015.8.0 and later) +salt myminion git.submodule /path/to/repo/sub/repo deinit +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.symbolic_ref(cwd, ref, value=None, opts=\(aq\(aq, user=None, ignore_retcode=False) +New in version 2015.8.0. + +.sp +Interface to \fI\%git\-symbolic\-ref(1)\fP +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B ref +Symbolic ref to read/modify +.TP +.B value +If passed, then the symbolic ref will be set to this value and an empty +string will be returned. +.sp +If not passed, then the ref to which \fBref\fP points will be returned, +unless \fB\-\-delete\fP is included in \fBopts\fP (in which case the symbolic +ref will be deleted). +.TP +.B opts +Any additional options to add to the command line, in a single string +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Get ref to which HEAD is pointing +salt myminion git.symbolic_ref /path/to/repo HEAD +# Set/overwrite symbolic ref \(aqFOO\(aq to local branch \(aqfoo\(aq +salt myminion git.symbolic_ref /path/to/repo FOO refs/heads/foo +# Delete symbolic ref \(aqFOO\(aq +salt myminion git.symbolic_ref /path/to/repo FOO opts=\(aq\-\-delete\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.version(versioninfo=False) +New in version 2015.8.0. + +.sp +Returns the version of Git installed on the minion +.INDENT 7.0 +.TP +.B versioninfo +False +If \fBTrue\fP, return the version in a versioninfo list (e.g. \fB[2, 5, +0]\fP) +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.version +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.worktree_add(cwd, worktree_path, branch=None, ref=None, reset_branch=None, force=None, detach=False, opts=\(aq\(aq, user=None, ignore_retcode=False) +New in version 2015.8.0. + +.sp +Interface to \fI\%git\-worktree(1)\fP, adds a worktree +.INDENT 7.0 +.TP +.B cwd +The path to the git checkout +.TP +.B worktree_path +Path to the new worktree. Can be either absolute, or relative to +\fBcwd\fP\&. +.TP +.B branch +Name of new branch to create. If omitted, will be set to the basename +of the \fBworktree_path\fP\&. For example, if the \fBworktree_path\fP is +\fB/foo/bar/baz\fP, then \fBbranch\fP will be \fBbaz\fP\&. +.TP +.B ref +Name of the ref on which to base the new worktree. If omitted, then +\fBHEAD\fP is use, and a new branch will be created, named for the +basename of the \fBworktree_path\fP\&. For example, if the +\fBworktree_path\fP is \fB/foo/bar/baz\fP then a new branch \fBbaz\fP will be +created, and pointed at \fBHEAD\fP\&. +.TP +.B reset_branch +False +If \fBFalse\fP, then \fI\%git\-worktree(1)\fP will fail to create the worktree +if the targeted branch already exists. Set this argument to \fBTrue\fP to +reset the targeted branch to point at \fBref\fP, and checkout the +newly\-reset branch into the new worktree. +.TP +.B force +False +By default, \fI\%git\-worktree(1)\fP will not permit the same branch to be +checked out in more than one worktree. Set this argument to \fBTrue\fP to +override this. +.TP +.B opts +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP to avoid causing errors +with Salt\(aqs own argument parsing. +.sp +All CLI options for adding worktrees as of Git 2.5.0 are already +supported by this function as of Salt 2015.8.0, so using this +argument is unnecessary unless new CLI arguments are added to +\fI\%git\-worktree(1)\fP and are not yet supported in Salt. +.UNINDENT +.UNINDENT +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.worktree_add /path/to/repo/main ../hotfix ref=origin/master +salt myminion git.worktree_add /path/to/repo/main ../hotfix branch=hotfix21 ref=v2.1.9.3 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.worktree_prune(cwd, dry_run=False, verbose=True, expire=None, opts=\(aq\(aq, user=None, ignore_retcode=False) +New in version 2015.8.0. + +.sp +Interface to \fI\%git\-worktree(1)\fP, prunes stale worktree administrative data +from the gitdir +.INDENT 7.0 +.TP +.B cwd +The path to the main git checkout or a linked worktree +.TP +.B dry_run +False +If \fBTrue\fP, then this function will report what would have been +pruned, but no changes will be made. +.TP +.B verbose +True +Report all changes made. Set to \fBFalse\fP to suppress this output. +.TP +.B expire +Only prune unused worktree data older than a specific period of time. +The date format for this parameter is described in the documentation +for the \fBgc.pruneWorktreesExpire\fP config param in the + +.nf +\(gagit\-config(1)\(ga_ +.fi + manpage. +.TP +.B opts +Any additional options to add to the command line, in a single string +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +On the Salt CLI, if the opts are preceded with a dash, it is +necessary to precede them with \fBopts=\fP to avoid causing errors +with Salt\(aqs own argument parsing. +.sp +All CLI options for pruning worktrees as of Git 2.5.0 are already +supported by this function as of Salt 2015.8.0, so using this +argument is unnecessary unless new CLI arguments are added to +\fI\%git\-worktree(1)\fP and are not yet supported in Salt. +.UNINDENT +.UNINDENT +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.TP +.B ignore_retcode +False +If \fBTrue\fP, do not log an error to the minion log if the git command +returns a nonzero exit status. +.sp +New in version 2015.8.0. + +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.worktree_prune /path/to/repo +salt myminion git.worktree_prune /path/to/repo dry_run=True +salt myminion git.worktree_prune /path/to/repo expire=1.day.ago +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.git.worktree_rm(cwd, user=None) +New in version 2015.8.0. + +.sp +Recursively removes the worktree located at \fBcwd\fP, returning \fBTrue\fP if +successful. This function will attempt to determine if \fBcwd\fP is actually +a worktree by invoking \fI\%git.is_worktree\fP\&. If the path does not correspond to a +worktree, then an error will be raised and no action will be taken. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +There is no undoing this action. Be \fBVERY\fP careful before running +this function. +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B cwd +Path to the worktree to be removed +.TP +.B user +User under which to run the git command. By default, the command is run +by the user under which the minion is running. +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt myminion git.worktree_rm /path/to/worktree .ft P .fi .UNINDENT @@ -85431,11 +86117,11 @@ either in a pillar or in the minion\(aqs config file: .sp .nf .ft C -glance.user: admin -glance.password: verybadpass -glance.tenant: admin -glance.insecure: False #(optional) -glance.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq +keystone.user: admin +keystone.password: verybadpass +keystone.tenant: admin +keystone.insecure: False #(optional) +keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq .ft P .fi .UNINDENT @@ -85450,23 +86136,23 @@ For example: .nf .ft C openstack1: - glance.user: admin - glance.password: verybadpass - glance.tenant: admin - glance.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq + keystone.user: admin + keystone.password: verybadpass + keystone.tenant: admin + keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq openstack2: - glance.user: admin - glance.password: verybadpass - glance.tenant: admin - glance.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq + keystone.user: admin + keystone.password: verybadpass + keystone.tenant: admin + keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq .ft P .fi .UNINDENT .UNINDENT .sp -With this configuration in place, any of the keystone functions can make use -of a configuration profile by declaring it explicitly. +With this configuration in place, any of the glance functions can +make use of a configuration profile by declaring it explicitly. For example: .INDENT 7.0 .INDENT 3.5 @@ -85481,24 +86167,24 @@ salt \(aq*\(aq glance.image_list profile=openstack1 .UNINDENT .INDENT 0.0 .TP -.B salt.modules.glance.image_create(name, location, profile=None, visibility=\(aqpublic\(aq, container_format=\(aqbare\(aq, disk_format=\(aqraw\(aq) +.B salt.modules.glance.image_create(name, location=None, profile=None, visibility=None, container_format=\(aqbare\(aq, disk_format=\(aqraw\(aq, protected=None, copy_from=None, is_public=None) Create an image (glance image\-create) .sp -CLI Example: +CLI Example, old format: +.sp +CLI Example, new format resembling Glance API v2: .INDENT 7.0 .INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq glance.image_create name=f16\-jeos visibility=public \e - disk_format=qcow2 container_format=ovf \e - copy_from=http://berrange.fedorapeople.org/ images/2012\-02\-29/f16\-x86_64\-openstack\-sda.qcow2 -.ft P -.fi +.INDENT 0.0 +.TP +.B salt \(aq*\(aq glance.image_create name=f16\-jeos visibility=public +disk_format=qcow2 container_format=ovf copy_from=http://berrange.fedorapeople.org/ images/2012\-02\-29/f16\-x86_64\-openstack\-sda.qcow2 +.UNINDENT .UNINDENT .UNINDENT .sp -For all possible values, run \fBglance help image\-create\fP on the minion. +The parameter \(aqvisibility\(aq defaults to \(aqpublic\(aq if neither +\(aqvisibility\(aq nor \(aqis_public\(aq is specified. .UNINDENT .INDENT 0.0 .TP @@ -85521,7 +86207,7 @@ salt \(aq*\(aq glance.image_delete name=f16\-jeos .UNINDENT .INDENT 0.0 .TP -.B salt.modules.glance.image_list(id=None, profile=None) +.B salt.modules.glance.image_list(id=None, profile=None, name=None) Return a list of available images (glance image\-list) .sp CLI Example: @@ -85561,6 +86247,24 @@ salt \(aq*\(aq glance.image_show .UNINDENT .INDENT 0.0 .TP +.B salt.modules.glance.image_update(id=None, name=None, profile=None, **kwargs) +Update properties of given image. +Known to work for: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +min_ram (in MB) +.IP \(bu 2 +protected (bool) +.IP \(bu 2 +visibility (\(aqpublic\(aq or \(aqprivate\(aq) +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.glance.schema_get(name, profile=None) .INDENT 7.0 .TP @@ -87472,6 +88176,8 @@ haproxy backend .B socket haproxy stats socket .UNINDENT +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp @@ -87498,6 +88204,8 @@ haproxy backend .B socket haproxy stats socket .UNINDENT +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp @@ -87524,6 +88232,8 @@ haproxy backend .B socket haproxy stats socket .UNINDENT +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp @@ -87547,6 +88257,8 @@ haproxy backend .B socket haproxy stats socket .UNINDENT +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp @@ -87576,6 +88288,8 @@ Server Weight .B socket haproxy stats socket .UNINDENT +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp @@ -87596,6 +88310,8 @@ Show HaProxy Backends .B socket haproxy stats socket .UNINDENT +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp @@ -87616,6 +88332,8 @@ Show HaProxy frontends .B socket haproxy stats socket .UNINDENT +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp @@ -87973,160 +88691,6 @@ salt devserver1 hg.update /path/to/repo somebranch .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.hipchat -.sp -Module for sending messages to hipchat. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.TP -.B configuration -This module can be used by either passing an api key and version -directly or by specifying both in a configuration profile in the salt -master/minion config. -.sp -For example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -hipchat: - api_key: peWcBiMOS9HrZG15peWcBiMOS9HrZG15 - api_version: v1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.hipchat.find_room(name, api_key=None, api_version=None) -Find a room by name and return it. -:param name: The room name. -:param api_key: The HipChat admin api key. -:param api_version: The HipChat api version, if not specified in the configuration. -:return: The room object. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq hipchat.find_room name="Development Room" - -salt \(aq*\(aq hipchat.find_room name="Development Room" api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_version=v1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.hipchat.find_user(name, api_key=None, api_version=None) -Find a user by name and return it. -:param name: The user name. -:param api_key: The HipChat admin api key. -:param api_version: The HipChat api version, if not specified in the configuration. -:return: The user object. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq hipchat.find_user name="Thomas Hatch" - -salt \(aq*\(aq hipchat.find_user name="Thomas Hatch" api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_version=v1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.hipchat.list_rooms(api_key=None, api_version=None) -List all HipChat rooms. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBapi_key\fP \-\- The HipChat admin api key. -.IP \(bu 2 -\fBapi_version\fP \-\- The HipChat api version, if not specified in the configuration. -.UNINDENT -.TP -.B Returns -The room list. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq hipchat.list_rooms - -salt \(aq*\(aq hipchat.list_rooms api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_version=v1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.hipchat.list_users(api_key=None, api_version=None) -List all HipChat users. -:param api_key: The HipChat admin api key. -:param api_version: The HipChat api version, if not specified in the configuration. -:return: The user list. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq hipchat.list_users - -salt \(aq*\(aq hipchat.list_users api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_version=v1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.hipchat.send_message(room_id, message, from_name, api_key=None, api_version=None, color=\(aqyellow\(aq, notify=False) -Send a message to a HipChat room. -:param room_id: The room id or room name, either will work. -:param message: The message to send to the HipChat room. -:param from_name: Specify who the message is from. -:param api_key: The HipChat api key, if not specified in the configuration. -:param api_version: The HipChat api version, if not specified in the configuration. -:param color: The color for the message, default: yellow. -:param notify: Whether to notify the room, default: False. -:return: Boolean if message was sent successfully. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq hipchat.send_message room_id="Development Room" message="Build is done" from_name="Build Server" - -salt \(aq*\(aq hipchat.send_message room_id="Development Room" message="Build failed" from_name="Build Server" color="red" notify=True -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.hosts .sp Manage the information in the hosts file @@ -88402,82 +88966,6 @@ salt \(aq*\(aq webutil.userdel /etc/httpd/htpasswd larry .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.http -.sp -Module for making various web calls. Primarily designed for webhooks and the -like, but also useful for basic http testing. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.TP -.B salt.modules.http.query(url, **kwargs) -Query a resource, and decode the return data -.sp -New in version 2015.5.0. - -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq http.query http://somelink.com/ -salt \(aq*\(aq http.query http://somelink.com/ method=POST params=\(aqkey1=val1&key2=val2\(aq -salt \(aq*\(aq http.query http://somelink.com/ method=POST data=\(aqsomecontent\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.http.update_ca_bundle(target=None, source=None, merge_files=None) -Update the local CA bundle file from a URL -.sp -New in version 2015.5.0. - -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq http.update_ca_bundle -salt \(aq*\(aq http.update_ca_bundle target=/path/to/cacerts.pem -salt \(aq*\(aq http.update_ca_bundle source=https://example.com/cacerts.pem -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If the \fBtarget\fP is not specified, it will be pulled from the \fBca_cert\fP -configuration variable available to the minion. If it cannot be found there, -it will be placed at \fB<>/cacerts.pem\fP\&. -.sp -If the \fBsource\fP is not specified, it will be pulled from the -\fBca_cert_url\fP configuration variable available to the minion. If it cannot -be found, it will be downloaded from the cURL website, using an http (not -https) URL. USING THE DEFAULT URL SHOULD BE AVOIDED! -.sp -\fBmerge_files\fP may also be specified, which includes a string or list of -strings representing a file or files to be appended to the end of the CA -bundle, once it is downloaded. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq http.update_ca_bundle merge_files=/path/to/mycert.pem -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.ilo .sp Manage HP ILO @@ -91155,6 +91643,18 @@ salt \(aq*\(aq ipset.add setname 192.168.0.3,AA:BB:CC:DD:EE:FF .TP .B salt.modules.ipset.check(set=None, entry=None, family=\(aqipv4\(aq) Check that an entry exists in the specified set. +.INDENT 7.0 +.TP +.B set +The ipset name +.TP +.B entry +An entry in the ipset. This parameter can be a single IP address, a +range of IP addresses, or a subnet block. Example: +.TP +.B family +IP protocol version: ipv4 or ipv6 +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -91358,428 +91858,6 @@ salt \(aq*\(aq ipset.version .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.iptables -.sp -Support for iptables -.INDENT 0.0 -.TP -.B salt.modules.iptables.append(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) -Append a rule to the specified table/chain. -.INDENT 7.0 -.TP -.B This function accepts a rule in a standard iptables command format, -starting with the chain. Trying to force users to adapt to a new -method of creating rules would be irritating at best, and we -already have a parser that can handle it. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.append filter INPUT \e - rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq - -IPv6: -salt \(aq*\(aq iptables.append filter INPUT \e - rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.build_rule(table=\(aqfilter\(aq, chain=None, command=None, position=\(aq\(aq, full=None, family=\(aqipv4\(aq, **kwargs) -Build a well\-formatted iptables rule based on kwargs. A \fItable\fP and \fIchain\fP -are not required, unless \fIfull\fP is True. -.sp -If \fIfull\fP is \fITrue\fP, then \fItable\fP, \fIchain\fP and \fIcommand\fP are required. -\fIcommand\fP may be specified as either a short option (\(aqI\(aq) or a long option -(\fI\-\-insert\fP). This will return the iptables command, exactly as it would -be used from the command line. -.sp -If a position is required (as with \fI\-I\fP or \fI\-D\fP), it may be specified as -\fIposition\fP\&. This will only be useful if \fIfull\fP is True. -.sp -If \fIconnstate\fP is passed in, it will automatically be changed to \fIstate\fP\&. -.sp -To pass in jump options that doesn\(aqt take arguments, pass in an empty -string. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.build_rule match=state \e - connstate=RELATED,ESTABLISHED jump=ACCEPT - -salt \(aq*\(aq iptables.build_rule filter INPUT command=I position=3 \e - full=True match=state state=RELATED,ESTABLISHED jump=ACCEPT - -salt \(aq*\(aq iptables.build_rule filter INPUT command=A \e - full=True match=state state=RELATED,ESTABLISHED \e - source=\(aq127.0.0.1\(aq jump=ACCEPT - -\&.. Invert Rules -salt \(aq*\(aq iptables.build_rule filter INPUT command=A \e - full=True match=state state=RELATED,ESTABLISHED \e - source=\(aq! 127.0.0.1\(aq jump=ACCEPT - -salt \(aq*\(aq iptables.build_rule filter INPUT command=A \e - full=True match=state state=RELATED,ESTABLISHED \e - destination=\(aqnot 127.0.0.1\(aq jump=ACCEPT - -IPv6: -salt \(aq*\(aq iptables.build_rule match=state \e - connstate=RELATED,ESTABLISHED jump=ACCEPT \e - family=ipv6 -salt \(aq*\(aq iptables.build_rule filter INPUT command=I position=3 \e - full=True match=state state=RELATED,ESTABLISHED jump=ACCEPT \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.check(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) -Check for the existence of a rule in the table and chain -.INDENT 7.0 -.TP -.B This function accepts a rule in a standard iptables command format, -starting with the chain. Trying to force users to adapt to a new -method of creating rules would be irritating at best, and we -already have a parser that can handle it. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.check filter INPUT \e - rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq - -IPv6: -salt \(aq*\(aq iptables.check filter INPUT \e - rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.check_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) -New in version 2014.1.0. - -.sp -Check for the existence of a chain in the table -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.check_chain filter INPUT - -IPv6: -salt \(aq*\(aq iptables.check_chain filter INPUT family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.delete(table, chain=None, position=None, rule=None, family=\(aqipv4\(aq) -.INDENT 7.0 -.TP -.B Delete a rule from the specified table/chain, specifying either the rule -in its entirety, or the rule\(aqs position in the chain. -.TP -.B This function accepts a rule in a standard iptables command format, -starting with the chain. Trying to force users to adapt to a new -method of creating rules would be irritating at best, and we -already have a parser that can handle it. -.UNINDENT -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.delete filter INPUT position=3 -salt \(aq*\(aq iptables.delete filter INPUT \e - rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq - -IPv6: -salt \(aq*\(aq iptables.delete filter INPUT position=3 family=ipv6 -salt \(aq*\(aq iptables.delete filter INPUT \e - rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.delete_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) -New in version 2014.1.0. - -.sp -Delete custom chain to the specified table. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.delete_chain filter CUSTOM_CHAIN - -IPv6: -salt \(aq*\(aq iptables.delete_chain filter CUSTOM_CHAIN family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.flush(table=\(aqfilter\(aq, chain=\(aq\(aq, family=\(aqipv4\(aq) -Flush the chain in the specified table, flush all chains in the specified -table if not specified chain. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.flush filter INPUT - -IPv6: -salt \(aq*\(aq iptables.flush filter INPUT family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.get_policy(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) -Return the current policy for the specified table/chain -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.get_policy filter INPUT - -IPv6: -salt \(aq*\(aq iptables.get_policy filter INPUT family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.get_rules(family=\(aqipv4\(aq) -Return a data structure of the current, in\-memory rules -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.get_rules - -IPv6: -salt \(aq*\(aq iptables.get_rules family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.get_saved_policy(table=\(aqfilter\(aq, chain=None, conf_file=None, family=\(aqipv4\(aq) -Return the current policy for the specified table/chain -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.get_saved_policy filter INPUT -salt \(aq*\(aq iptables.get_saved_policy filter INPUT \e - conf_file=/etc/iptables.saved - -IPv6: -salt \(aq*\(aq iptables.get_saved_policy filter INPUT family=ipv6 -salt \(aq*\(aq iptables.get_saved_policy filter INPUT \e - conf_file=/etc/iptables.saved family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.get_saved_rules(conf_file=None, family=\(aqipv4\(aq) -Return a data structure of the rules in the conf file -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.get_saved_rules - -IPv6: -salt \(aq*\(aq iptables.get_saved_rules family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.insert(table=\(aqfilter\(aq, chain=None, position=None, rule=None, family=\(aqipv4\(aq) -Insert a rule into the specified table/chain, at the specified position. -.INDENT 7.0 -.TP -.B This function accepts a rule in a standard iptables command format, -starting with the chain. Trying to force users to adapt to a new -method of creating rules would be irritating at best, and we -already have a parser that can handle it. -.TP -.B If the position specified is a negative number, then the insert will be -performed counting from the end of the list. For instance, a position -of \-1 will insert the rule as the second to last rule. To insert a rule -in the last position, use the append function instead. -.UNINDENT -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.insert filter INPUT position=3 \e - rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq - -IPv6: -salt \(aq*\(aq iptables.insert filter INPUT position=3 \e - rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.new_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) -New in version 2014.1.0. - -.sp -Create new custom chain to the specified table. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.new_chain filter CUSTOM_CHAIN - -IPv6: -salt \(aq*\(aq iptables.new_chain filter CUSTOM_CHAIN family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.save(filename=None, family=\(aqipv4\(aq) -Save the current in\-memory rules to disk -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.save /etc/sysconfig/iptables - -IPv6: -salt \(aq*\(aq iptables.save /etc/sysconfig/iptables family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.set_policy(table=\(aqfilter\(aq, chain=None, policy=None, family=\(aqipv4\(aq) -Set the current policy for the specified table/chain -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.set_policy filter INPUT ACCEPT - -IPv6: -salt \(aq*\(aq iptables.set_policy filter INPUT ACCEPT family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.iptables.version(family=\(aqipv4\(aq) -Return version from iptables \-\-version -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq iptables.version - -IPv6: -salt \(aq*\(aq iptables.version family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.jboss7 .sp Module for managing JBoss AS 7 through the CLI interface. @@ -92312,6 +92390,10 @@ Module for interfacing to Junos devices ALPHA QUALITY code. .INDENT 0.0 .TP +.B salt.modules.junos.call_rpc() +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.junos.commit() .UNINDENT .INDENT 0.0 @@ -102746,85 +102828,6 @@ salt \(aq*\(aq nagios.run webserver .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.nagios_rpc -.sp -Check Host & Service status from Nagios via JSON RPC. -.sp -New in version 2015.8.0. - -.INDENT 0.0 -.TP -.B salt.modules.nagios_rpc.host_status(hostname=None, **kwargs) -Check status of a particular host By default -statuses are returned in a numeric format. -.sp -Parameters: -.INDENT 7.0 -.TP -.B hostname -The hostname to check the status of the service in Nagios. -.TP -.B numeric -Turn to false in order to return status in text format -(\(aqOK\(aq instead of 0, \(aqWarning\(aq instead of 1 etc) -.UNINDENT -.INDENT 7.0 -.TP -.B Returns -status: \(aqOK\(aq, \(aqWarning\(aq, \(aqCritical\(aq or \(aqUnknown\(aq -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nagios_rpc.host_status hostname=webserver.domain.com -salt \(aq*\(aq nagios_rpc.host_status hostname=webserver.domain.com numeric=False -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nagios_rpc.service_status(hostname=None, service=None, **kwargs) -Check status of a particular service on a host on it in Nagios. -By default statuses are returned in a numeric format. -.sp -Parameters: -.INDENT 7.0 -.TP -.B hostname -The hostname to check the status of the service in Nagios. -.TP -.B service -The service to check the status of in Nagios. -.TP -.B numeric -Turn to false in order to return status in text format -(\(aqOK\(aq instead of 0, \(aqWarning\(aq instead of 1 etc) -.UNINDENT -.INDENT 7.0 -.TP -.B Returns -status: \(aqOK\(aq, \(aqWarning\(aq, \(aqCritical\(aq or \(aqUnknown\(aq -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nagios_rpc.service_status hostname=webserver.domain.com service=\(aqHTTP\(aq -salt \(aq*\(aq nagios_rpc.service_status hostname=webserver.domain.com service=\(aqHTTP\(aq numeric=False -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.netbsd_sysctl .sp Module for viewing and modifying sysctl parameters @@ -103683,6 +103686,9 @@ salt \(aq*\(aq network.active_tcp .TP .B salt.modules.network.arp() Return the arp table from the minion +.sp +Changed in version 2015.8.0: Added support for SunOS + .sp CLI Example: .INDENT 7.0 @@ -103750,6 +103756,9 @@ salt \(aq*\(aq network.connect google\-public\-dns\-a.google.com port=53 proto=u .TP .B salt.modules.network.default_route(family=None) Return default route(s) from routing table +.sp +Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS) + .sp CLI Example: .INDENT 7.0 @@ -103821,6 +103830,10 @@ Return routing information for given destination ip .sp New in version 2015.5.3. +.sp +Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS) +Added support for OpenBSD + .sp CLI Example: .INDENT 7.0 @@ -104110,6 +104123,9 @@ salt \(aq*\(aq network.getBuffers .TP .B salt.modules.network.mod_hostname(hostname) Modify hostname +.sp +Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS) + .sp CLI Example: .INDENT 7.0 @@ -104138,6 +104154,9 @@ netstat entry, fetched from sockstat/fstat output. .sp Changed in version 2014.1.4: Added support for OpenBSD, FreeBSD, and NetBSD +.sp +Changed in version 2015.8.0: Added support for SunOS + .sp CLI Example: .INDENT 7.0 @@ -104154,7 +104173,10 @@ salt \(aq*\(aq network.netstat .INDENT 0.0 .TP .B salt.modules.network.ping(host, timeout=False, return_boolean=False) -Performs a ping to a host +Performs an ICMP ping to a host +.sp +Changed in version 2015.8.0: Added support for SunOS + .sp CLI Example: .INDENT 7.0 @@ -104219,6 +104241,9 @@ salt \(aq*\(aq network.reverse_ip 172.17.0.4 .TP .B salt.modules.network.routes(family=None) Return currently configured routes from routing table +.sp +Changed in version 2015.8.0: Added support for SunOS (Solaris 10, Illumos, SmartOS) + .sp CLI Example: .INDENT 7.0 @@ -104271,6 +104296,9 @@ salt \(aq*\(aq network.subnets .TP .B salt.modules.network.traceroute(host) Performs a traceroute to a 3rd party host +.sp +Changed in version 2015.8.0: Added support for SunOS + .sp CLI Example: .INDENT 7.0 @@ -106380,452 +106408,6 @@ salt \(aq*\(aq nfs.list_exports .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.nftables -.sp -Support for nftables -.INDENT 0.0 -.TP -.B salt.modules.nftables.append(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) -Append a rule to the specified table & chain. -.INDENT 7.0 -.TP -.B This function accepts a rule in a standard nftables command format, -starting with the chain. Trying to force users to adapt to a new -method of creating rules would be irritating at best, and we -already have a parser that can handle it. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.append filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq - -IPv6: -salt \(aq*\(aq nftables.append filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.build_rule(table=None, chain=None, command=None, position=\(aq\(aq, full=None, family=\(aqipv4\(aq, **kwargs) -Build a well\-formatted nftables rule based on kwargs. -A \fItable\fP and \fIchain\fP are not required, unless \fIfull\fP is True. -.sp -If \fIfull\fP is \fITrue\fP, then \fItable\fP, \fIchain\fP and \fIcommand\fP are required. -\fIcommand\fP may be specified as either insert, append, or delete. -This will return the nftables command, exactly as it would -be used from the command line. -.sp -If a position is required (as with \fIinsert\fP or \fIdelete\fP), it may be specified as -\fIposition\fP\&. This will only be useful if \fIfull\fP is True. -.sp -If \fIconnstate\fP is passed in, it will automatically be changed to \fIstate\fP\&. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.build_rule match=state \e - connstate=RELATED,ESTABLISHED jump=ACCEPT -salt \(aq*\(aq nftables.build_rule filter input command=insert position=3 \e - full=True match=state state=related,established jump=accept - -IPv6: -salt \(aq*\(aq nftables.build_rule match=state \e - connstate=related,established jump=accept \e - family=ipv6 -salt \(aq*\(aq nftables.build_rule filter input command=insert position=3 \e - full=True match=state state=related,established jump=accept \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.check(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) -Check for the existence of a rule in the table and chain -.INDENT 7.0 -.TP -.B This function accepts a rule in a standard nftables command format, -starting with the chain. Trying to force users to adapt to a new -method of creating rules would be irritating at best, and we -already have a parser that can handle it. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.check filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq - -IPv6: -salt \(aq*\(aq nftables.check filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.check_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) -New in version 2014.7.0. - -.sp -Check for the existence of a chain in the table -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.check_chain filter input - -IPv6: -salt \(aq*\(aq nftables.check_chain filter input family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.check_table(table=None, family=\(aqipv4\(aq) -Check for the existence of a table -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.check_table nat -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.delete(table, chain=None, position=None, rule=None, family=\(aqipv4\(aq) -.INDENT 7.0 -.TP -.B Delete a rule from the specified table & chain, specifying either the rule -in its entirety, or the rule\(aqs position in the chain. -.TP -.B This function accepts a rule in a standard nftables command format, -starting with the chain. Trying to force users to adapt to a new -method of creating rules would be irritating at best, and we -already have a parser that can handle it. -.UNINDENT -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.delete filter input position=3 - -salt \(aq*\(aq nftables.delete filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq - -IPv6: -salt \(aq*\(aq nftables.delete filter input position=3 family=ipv6 - -salt \(aq*\(aq nftables.delete filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.delete_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq) -New in version 2014.7.0. - -.sp -Delete the chain from the specified table. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.delete_chain filter input - -salt \(aq*\(aq nftables.delete_chain filter foo - -IPv6: -salt \(aq*\(aq nftables.delete_chain filter input family=ipv6 - -salt \(aq*\(aq nftables.delete_chain filter foo family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.delete_table(table, family=\(aqipv4\(aq) -New in version 2014.7.0. - -.sp -Create new custom table. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.delete_table filter - -IPv6: -salt \(aq*\(aq nftables.delete_table filter family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.flush(table=\(aqfilter\(aq, chain=\(aq\(aq, family=\(aqipv4\(aq) -Flush the chain in the specified table, flush all chains in the specified -table if chain is not specified. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.flush filter - -salt \(aq*\(aq nftables.flush filter input - -IPv6: -salt \(aq*\(aq nftables.flush filter input family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.get_rule_handle(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq) -Get the handle for a particular rule -.INDENT 7.0 -.TP -.B This function accepts a rule in a standard nftables command format, -starting with the chain. Trying to force users to adapt to a new -method of creating rules would be irritating at best, and we -already have a parser that can handle it. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.get_rule_handle filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq - -IPv6: -salt \(aq*\(aq nftables.get_rule_handle filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.get_rules(family=\(aqipv4\(aq) -Return a data structure of the current, in\-memory rules -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.get_rules - -salt \(aq*\(aq nftables.get_rules family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.get_saved_rules(conf_file=None, family=\(aqipv4\(aq) -Return a data structure of the rules in the conf file -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.get_saved_rules -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.insert(table=\(aqfilter\(aq, chain=None, position=None, rule=None, family=\(aqipv4\(aq) -Insert a rule into the specified table & chain, at the specified position. -.sp -If position is not specified, rule will be inserted in first position. -.INDENT 7.0 -.TP -.B This function accepts a rule in a standard nftables command format, -starting with the chain. Trying to force users to adapt to a new -method of creating rules would be irritating at best, and we -already have a parser that can handle it. -.UNINDENT -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.insert filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq - -salt \(aq*\(aq nftables.insert filter input position=3 \e - rule=\(aqinput tcp dport 22 log accept\(aq - -IPv6: -salt \(aq*\(aq nftables.insert filter input \e - rule=\(aqinput tcp dport 22 log accept\(aq \e - family=ipv6 - -salt \(aq*\(aq nftables.insert filter input position=3 \e - rule=\(aqinput tcp dport 22 log accept\(aq \e - family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.new_chain(table=\(aqfilter\(aq, chain=None, table_type=None, hook=None, priority=None, family=\(aqipv4\(aq) -New in version 2014.7.0. - -.sp -Create new chain to the specified table. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.new_chain filter input - -salt \(aq*\(aq nftables.new_chain filter input \e - table_type=filter hook=input priority=0 - -salt \(aq*\(aq nftables.new_chain filter foo - -IPv6: -salt \(aq*\(aq nftables.new_chain filter input family=ipv6 - -salt \(aq*\(aq nftables.new_chain filter input \e - table_type=filter hook=input priority=0 family=ipv6 - -salt \(aq*\(aq nftables.new_chain filter foo family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.new_table(table, family=\(aqipv4\(aq) -New in version 2014.7.0. - -.sp -Create new custom table. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.new_table filter - -IPv6: -salt \(aq*\(aq nftables.new_table filter family=ipv6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.save(filename=None, family=\(aqipv4\(aq) -Save the current in\-memory rules to disk -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.save /etc/nftables -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.nftables.version() -Return version from nftables \-\-version -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq nftables.version -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.nginx .sp Support for nginx @@ -111384,167 +110966,6 @@ salt \(aq*\(aq pkg.version ... .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.pagerduty -.sp -Module for Firing Events via PagerDuty -.sp -New in version 2014.1.0. - -.INDENT 0.0 -.TP -.B configuration -This module can be used by specifying the name of a -configuration profile in the minion config, minion pillar, or master -config. -.sp -For example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-pagerduty\-account: - pagerduty.api_key: F3Rbyjbve43rfFWf2214 - pagerduty.subdomain: mysubdomain -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pagerduty.create_event(service_key=None, description=None, details=None, incident_key=None, profile=None) -Create an event in PagerDuty. Designed for use in states. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt myminion pagerduty.create_event
profile=my\-pagerduty\-account -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The following parameters are required: -.INDENT 7.0 -.TP -.B service_key -This key can be found by using pagerduty.list_services. -.TP -.B description -This is a short description of the event. -.TP -.B details -This can be a more detailed description of the event. -.TP -.B profile -This refers to the configuration profile to use to connect to the -PagerDuty service. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pagerduty.list_escalation_policies(profile=None, api_key=None) -List escalation policies belonging to this account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -salt myminion pagerduty.list_policies my\-pagerduty\-account -salt myminion pagerduty.list_escalation_policies my\-pagerduty\-account -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pagerduty.list_incidents(profile=None, api_key=None) -List incidents belonging to this account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -salt myminion pagerduty.list_incidents my\-pagerduty\-account -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pagerduty.list_maintenance_windows(profile=None, api_key=None) -List maintenance windows belonging to this account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -salt myminion pagerduty.list_windows my\-pagerduty\-account -salt myminion pagerduty.list_maintenance_windows my\-pagerduty\-account -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pagerduty.list_policies(profile=None, api_key=None) -List escalation policies belonging to this account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -salt myminion pagerduty.list_policies my\-pagerduty\-account -salt myminion pagerduty.list_escalation_policies my\-pagerduty\-account -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pagerduty.list_schedules(profile=None, api_key=None) -List schedules belonging to this account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -salt myminion pagerduty.list_schedules my\-pagerduty\-account -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pagerduty.list_services(profile=None, api_key=None) -List services belonging to this account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -salt myminion pagerduty.list_services my\-pagerduty\-account -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pagerduty.list_users(profile=None, api_key=None) -List users belonging to this account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -salt myminion pagerduty.list_users my\-pagerduty\-account -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pagerduty.list_windows(profile=None, api_key=None) -List maintenance windows belonging to this account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -salt myminion pagerduty.list_windows my\-pagerduty\-account -salt myminion pagerduty.list_maintenance_windows my\-pagerduty\-account -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.pam .sp Support for pam @@ -112135,295 +111556,6 @@ salt \(aq*\(aq pecl.update fuse .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.pillar -.sp -Extract the pillar data for this minion -.INDENT 0.0 -.TP -.B salt.modules.pillar.ext(external, pillar=None) -Generate the pillar and apply an explicit external pillar -.sp -CLI Example: -.INDENT 7.0 -.TP -.B pillar -None -If specified, allows for a dictionary of pillar data to be made -available to pillar and ext_pillar rendering. These pillar variables -will also override any variables of the same name in pillar or -ext_pillar. -.sp -New in version 2015.5.0. - -.UNINDENT -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pillar.ext \(aq{libvirt: _}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pillar.get(key, default=, merge=False, delimiter=\(aq:\(aq) -New in version 0.14. - -.sp -Attempt to retrieve the named value from pillar, if the named value is not -available return the passed default. The default return is an empty string -except __opts__[\(aqpillar_raise_on_missing\(aq] is set to True, in which case a -KeyError will be raised. -.sp -If the merge parameter is set to \fBTrue\fP, the default will be recursively -merged into the returned pillar data. -.sp -The value can also represent a value in a nested dict using a ":" delimiter -for the dict. This means that if a dict in pillar looks like this: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -{\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}} -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To retrieve the value associated with the apache key in the pkg dict this -key can be passed: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -pkg:apache -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B merge -Specify whether or not the retrieved values should be recursively -merged into the passed default. -.sp -New in version 2014.7.0. - -.TP -.B delimiter -Specify an alternate delimiter to use when traversing a nested dict -.sp -New in version 2014.7.0. - -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pillar.get pkg:apache -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pillar.item(*args, **kwargs) -New in version 0.16.2. - -.sp -Return one or more pillar entries -.INDENT 7.0 -.TP -.B pillar -none -if specified, allows for a dictionary of pillar data to be made -available to pillar and ext_pillar rendering. these pillar variables -will also override any variables of the same name in pillar or -ext_pillar. -.sp -New in version 2015.5.0. - -.UNINDENT -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pillar.item foo -salt \(aq*\(aq pillar.item foo bar baz -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pillar.items(*args, **kwargs) -Calls the master for a fresh pillar and generates the pillar data on the -fly -.sp -Contrast with \fI\%raw()\fP which returns the pillar data that is -currently loaded into the minion. -.INDENT 7.0 -.TP -.B pillar -none -if specified, allows for a dictionary of pillar data to be made -available to pillar and ext_pillar rendering. these pillar variables -will also override any variables of the same name in pillar or -ext_pillar. -.sp -New in version 2015.5.0. - -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pillar.items -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pillar.keys(key, delimiter=\(aq:\(aq) -New in version 2015.8.0. - -.sp -Attempt to retrieve a list of keys from the named value from the pillar. -.sp -The value can also represent a value in a nested dict using a ":" delimiter -for the dict, similar to how pillar.get works. -.INDENT 7.0 -.TP -.B delimiter -Specify an alternate delimiter to use when traversing a nested dict -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pillar.keys web:sites -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pillar.ls(*args) -New in version 2015.8.0. - -.sp -Calls the master for a fresh pillar, generates the pillar data on the -fly (same as \fI\%items()\fP), but only shows the available main keys. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pillar.ls -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pillar.obfuscate(*args) -New in version 2015.8.0. - -.sp -Same as \fI\%items()\fP, but replace pillar values with a simple type indication. -.sp -This is useful to avoid displaying sensitive information on console or -flooding the console with long output, such as certificates. -For many debug or control purposes, the stakes lie more in dispatching than in -actual values. -.sp -In case the value is itself a collection type, obfuscation occurs within the value. -For mapping types, keys are not obfuscated. -Here are some examples: -.INDENT 7.0 -.IP \(bu 2 -\fB\(aqsecret password\(aq\fP becomes \fB\(aq\(aq\fP -.IP \(bu 2 -\fB[\(aqsecret\(aq, 1]\fP becomes -.nf -\(ga\(ga -.fi -[\(aq\(aq, \(aq\(aq] -.IP \(bu 2 -\fB{\(aqlogin\(aq: \(aqsomelogin\(aq, \(aqpwd\(aq: \(aqsecret\(aq}\fP becomes -\fB{\(aqlogin\(aq: \(aq\(aq, \(aqpwd\(aq: \(aq\(aq}\fP -.UNINDENT -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pillar.obfuscate -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pillar.raw(key=None) -Return the raw pillar data that is currently loaded into the minion. -.sp -Contrast with \fI\%items()\fP which calls the master to fetch the most -up\-to\-date Pillar. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pillar.raw -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -With the optional key argument, you can select a subtree of the -pillar raw data.: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pillar.raw key=\(aqroles\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.pip .sp Install Python packages with pip to either the system or a virtualenv @@ -112436,8 +111568,8 @@ Salt now uses a portable python. As a result the entire pip module is now functional on the salt installation itself. You can pip install dependencies for your custom modules. You can even upgrade salt itself using pip. For this to work properly, you must specify the Current Working Directory (\fBcwd\fP) and -the Pip Binary (\fBbin_env\fP) salt should use. The variable \fBpip_bin\fP can -be either a virtualenv path or the path to the pip binary itself. +the Pip Binary (\fBbin_env\fP) salt should use. The variable \fBpip_bin\fP can be +either a virtualenv path or the path to the pip binary itself. .sp For example, the following command will list all software installed using pip to your current salt environment: @@ -112567,8 +111699,14 @@ Path to requirements Path to pip bin or path to virtualenv. If doing a system install, and want to use a specific pip bin (pip\-2.7, pip\-2.6, etc..) just specify the pip bin you want. -If installing into a virtualenv, just use the path to the virtualenv -(/home/code/path/to/virtualenv/) +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If installing into a virtualenv, just use the path to the +virtualenv (e.g. \fB/home/code/path/to/virtualenv/\fP) +.UNINDENT +.UNINDENT .TP .B env Deprecated, use bin_env now @@ -112583,22 +111721,20 @@ Force to not use wheel archives (requires pip>=1.4) Log file where a complete (maximum verbosity) record will be kept .TP .B proxy -Specify a proxy in the form -user:passwd@proxy.server:port. Note that the -user:password@ is optional and required only if you -are behind an authenticated proxy. If you provide -user@proxy.server:port then you will be prompted for a -password. +Specify a proxy in the form \fBuser:passwd@proxy.server:port\fP\&. Note +that the \fBuser:password@\fP is optional and required only if you are +behind an authenticated proxy. If you provide +\fBuser@proxy.server:port\fP then you will be prompted for a password. .TP .B timeout Set the socket timeout (default 15 seconds) .TP .B editable -install something editable (i.e. -git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed) +install something editable (e.g. +\fBgit+https://github.com/worldcompany/djangoembed.git#egg=djangoembed\fP) .TP .B find_links -URL to look for packages at +URL to search for packages .TP .B index_url Base URL of Python Package Index @@ -112648,17 +111784,15 @@ Ignore package dependencies Download and unpack all packages, but don\(aqt actually install them .TP .B no_download -Don\(aqt download any packages, just install the ones -already downloaded (completes an install run with -\-\-no\-install) +Don\(aqt download any packages, just install the ones already downloaded +(completes an install run with \fB\-\-no\-install\fP) .TP .B install_options -Extra arguments to be supplied to the setup.py install -command (use like \-\-install\-option="\-\-install\- -scripts=/usr/local/bin"). Use multiple \-\-install\- -option options to pass multiple options to setup.py -install. If you are using an option with a directory -path, be sure to use absolute path. +Extra arguments to be supplied to the setup.py install command (e.g. +like \fB\-\-install\-option=\(aq\-\-install\-scripts=/usr/local/bin\(aq\fP). Use +multiple \-\-install\-option options to pass multiple options to setup.py +install. If you are using an option with a directory path, be sure to +use absolute path. .TP .B global_options Extra global options to be supplied to the setup.py call before the @@ -112668,15 +111802,15 @@ install command. The user under which to run pip .TP .B no_chown -When user is given, do not attempt to copy and chown -a requirements file +When user is given, do not attempt to copy and chown a requirements +file .TP .B cwd Current working directory to run pip from .TP .B activate -Activates the virtual environment, if given via bin_env, -before running install. +Activates the virtual environment, if given via bin_env, before running +install. .sp Deprecated since version 2014.7.2: If \fIbin_env\fP is given, pip will already be sourced from that virualenv, making \fIactivate\fP effectively a noop. @@ -112692,10 +111826,12 @@ Provide a path to an alternate CA bundle Allow the installation of all externally hosted files .TP .B allow_external -Allow the installation of externally hosted files (comma separated list) +Allow the installation of externally hosted files (comma separated +list) .TP .B allow_unverified -Allow the installation of insecure and unverifiable files (comma separated list) +Allow the installation of insecure and unverifiable files (comma +separated list) .TP .B process_dependency_links Enable the processing of dependency links @@ -117091,71 +116227,6 @@ salt \(aq*\(aq puppet.summary .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.pushover_notify -.sp -Module for sending messages to Pushover (\fI\%https://www.pushover.net\fP) -.sp -New in version Boron. - -.INDENT 0.0 -.TP -.B configuration -This module can be used by either passing an api key and version -directly or by specifying both in a configuration profile in the salt -master/minion config. -.sp -For example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -pushover: - token: abAHuZyCLtdH8P4zhmFZmgUHUsv1ei8 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pushover_notify.post_message(user=None, device=None, message=None, title=None, priority=None, expire=None, retry=None, sound=None, api_version=1, token=None) -Send a message to a Pushover user or group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBuser\fP \-\- The user or group to send to, must be key of user or group not email address. -.IP \(bu 2 -\fBmessage\fP \-\- The message to send to the PushOver user or group. -.IP \(bu 2 -\fBtitle\fP \-\- Specify who the message is from. -.UNINDENT -.UNINDENT -.sp -:param priority The priority of the message, defaults to 0. -:param expire The message should expire after N number of seconds. -:param retry The number of times the message should be retried. -:param sound The sound to associate with the message. -:param api_version: The PushOver API version, if not specified in the configuration. -:param token: The PushOver token, if not specified in the configuration. -:return: Boolean if message was sent successfully. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq pushover.post_message user=\(aqxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\(aq title=\(aqMessage from Salt\(aq message=\(aqBuild is done\(aq - -salt \(aq*\(aq pushover.post_message user=\(aqxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\(aq title=\(aqMessage from Salt\(aq message=\(aqBuild is done\(aq priority=\(aq2\(aq expire=\(aq720\(aq retry=\(aq5\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.pw_group .sp Manage groups on FreeBSD @@ -117244,6 +116315,26 @@ salt \(aq*\(aq group.info foo .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pw_group.members(name, members_list) +Replaces members of the group with a provided list. +.sp +New in version 2015.5.4. + +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +salt \(aq*\(aq group.members foo \(aquser1,user2,user3,...\(aq +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B Replaces a membership list for a local group \(aqfoo\(aq. +foo:x:1234:user1,user2,user3,... +.UNINDENT +.UNINDENT .SS salt.modules.pw_user .sp Manage users with the useradd command @@ -118630,326 +117721,6 @@ salt publish.runner manage.down .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.random_org -.sp -Module for retrieving random information from Random.org -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.TP -.B configuration -This module can be used by either passing an api key and version -directly or by specifying both in a configuration profile in the salt -master/minion config. -.sp -For example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -random_org: - api_key: 7be1402d\-5719\-5bd3\-a306\-3def9f135da5 - api_version: 1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.random_org.generateBlobs(api_key=None, api_version=None, **kwargs) -List all Slack users. -:param api_key: The Random.org api key. -:param api_version: The Random.org api version. -:param format: Specifies the format in which the -.INDENT 7.0 -.INDENT 3.5 -blobs will be returned. Values -allowed are base64 and hex. -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B Returns -The user list. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq get_integers number=5 min=1 max=6 - -salt \(aq*\(aq get_integers number=5 min=1 max=6 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.random_org.generateDecimalFractions(api_key=None, api_version=None, **kwargs) -Generates true random decimal fractions -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBapi_key\fP \-\- The Random.org api key. -.IP \(bu 2 -\fBapi_version\fP \-\- The Random.org api version. -.IP \(bu 2 -\fBnumber\fP \-\- How many random decimal fractions -you need. Must be within the [1,1e4] range. -.IP \(bu 2 -\fBdecimalPlaces\fP \-\- The number of decimal places -to use. Must be within the [1,20] range. -.IP \(bu 2 -\fBreplacement\fP \-\- Specifies whether the random numbers should -be picked with replacement. The default (true) -will cause the numbers to be picked with replacement, -i.e., the resulting numbers may contain duplicate -values (like a series of dice rolls). If you want the -numbers picked to be unique (like raffle tickets drawn -from a container), set this value to false. -.UNINDENT -.TP -.B Returns -A list of decimal fraction -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq random_org.generateDecimalFractions number=10 decimalPlaces=4 - -salt \(aq*\(aq random_org.generateDecimalFractions number=10 decimalPlaces=4 replacement=True -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.random_org.generateGaussians(api_key=None, api_version=None, **kwargs) -This method generates true random numbers from a -Gaussian distribution (also known as a normal distribution). -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBapi_key\fP \-\- The Random.org api key. -.IP \(bu 2 -\fBapi_version\fP \-\- The Random.org api version. -.IP \(bu 2 -\fBnumber\fP \-\- How many random numbers you need. -Must be within the [1,1e4] range. -.IP \(bu 2 -\fBmean\fP \-\- The distribution\(aqs mean. Must be -within the [\-1e6,1e6] range. -.IP \(bu 2 -\fBstandardDeviation\fP \-\- The distribution\(aqs standard -deviation. Must be within -the [\-1e6,1e6] range. -.IP \(bu 2 -\fBsignificantDigits\fP \-\- The number of significant digits -to use. Must be within the [2,20] range. -.UNINDENT -.TP -.B Returns -The user list. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq random_org.generateGaussians number=10 mean=0.0 standardDeviation=1.0 significantDigits=8 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.random_org.generateIntegers(api_key=None, api_version=None, **kwargs) -Generate random integers -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBapi_key\fP \-\- The Random.org api key. -.IP \(bu 2 -\fBapi_version\fP \-\- The Random.org api version. -.IP \(bu 2 -\fBnumber\fP \-\- The number of integers to generate -.IP \(bu 2 -\fBminimum\fP \-\- The lower boundary for the range from which the -random numbers will be picked. Must be within -the [\-1e9,1e9] range. -.IP \(bu 2 -\fBmaximum\fP \-\- The upper boundary for the range from which the -random numbers will be picked. Must be within -the [\-1e9,1e9] range. -.IP \(bu 2 -\fBreplacement\fP \-\- Specifies whether the random numbers should -be picked with replacement. The default (true) -will cause the numbers to be picked with replacement, -i.e., the resulting numbers may contain duplicate -values (like a series of dice rolls). If you want the -numbers picked to be unique (like raffle tickets drawn -from a container), set this value to false. -.IP \(bu 2 -\fBbase\fP \-\- Specifies the base that will be used to display the numbers. -Values allowed are 2, 8, 10 and 16. This affects the JSON -types and formatting of the resulting data as discussed below. -.UNINDENT -.TP -.B Returns -A list of integers. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq random_org.generateIntegers number=5 minimum=1 maximum=6 - -salt \(aq*\(aq random_org.generateIntegers number=5 minimum=2 maximum=255 base=2 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.random_org.generateStrings(api_key=None, api_version=None, **kwargs) -Generate random strings. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBapi_key\fP \-\- The Random.org api key. -.IP \(bu 2 -\fBapi_version\fP \-\- The Random.org api version. -.IP \(bu 2 -\fBnumber\fP \-\- The number of strings to generate. -.IP \(bu 2 -\fBlength\fP \-\- The length of each string. Must be -within the [1,20] range. All strings -will be of the same length -.IP \(bu 2 -\fBcharacters\fP \-\- A string that contains the set of -characters that are allowed to occur -in the random strings. The maximum number -of characters is 80. -.IP \(bu 2 -\fBreplacement\fP \-\- Specifies whether the random strings should be picked -with replacement. The default (true) will cause the -strings to be picked with replacement, i.e., the -resulting list of strings may contain duplicates (like -a series of dice rolls). If you want the strings to be -unique (like raffle tickets drawn from a container), set -this value to false. -.UNINDENT -.TP -.B Returns -A list of strings. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq random_org.generateStrings number=5 length=8 characters=\(aqabcdefghijklmnopqrstuvwxyz\(aq - -salt \(aq*\(aq random_org.generateStrings number=10 length=16 characters\(aqabcdefghijklmnopqrstuvwxyz\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.random_org.generateUUIDs(api_key=None, api_version=None, **kwargs) -Generate a list of random UUIDs -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBapi_key\fP \-\- The Random.org api key. -.IP \(bu 2 -\fBapi_version\fP \-\- The Random.org api version. -.IP \(bu 2 -\fBnumber\fP \-\- How many random UUIDs you need. -Must be within the [1,1e3] range. -.UNINDENT -.TP -.B Returns -A list of UUIDs -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq random_org.generateUUIDs number=5 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.random_org.getUsage(api_key=None, api_version=None) -Show current usages statistics -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBapi_key\fP \-\- The Random.org api key. -.IP \(bu 2 -\fBapi_version\fP \-\- The Random.org api version. -.UNINDENT -.TP -.B Returns -The current usage statistics. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq random_org.getUsage - -salt \(aq*\(aq random_org.getUsage api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_version=1 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.rbenv .sp Manage ruby installations with rbenv. Rbenv is supported on Linux and Mac OS X. @@ -119763,8 +118534,24 @@ salt \(aq*\(aq redis.zrange foo_sorted 0 10 .UNINDENT .UNINDENT .SS salt.modules.reg +.SS Manage the Windows registry .sp -Manage the registry on Windows +The read_key and set_key functions will be updated in Boron to reflect proper +registry usage. The registry has three main components. Hives, Keys, and Values. +.SS Hives +.sp +Hives are the main sections of the registry and all begin with the word HKEY. +\- HKEY_LOCAL_MACHINE +\- HKEY_CURRENT_USER +\- HKEY_USER +.SS Keys +.sp +Keys are the folders in the registry. Keys can have many nested subkeys. Keys +can have a value assigned to them under the (Default) +.SS Values or Entries +.sp +Values/Entries are name/data pairs. There can be many values in a key. The +(Default) value corresponds to the Key, the rest are their own value pairs. .INDENT 0.0 .TP .B depends @@ -119780,7 +118567,31 @@ Delay \(aq_winreg\(aq usage until this module is used .UNINDENT .INDENT 0.0 .TP -.B salt.modules.reg.create_key(hkey, path, key, value=None, reflection=True) +.B salt.modules.reg.create_key(hkey, path, key=None, value=None, reflection=True) +\fB* Incorrect Usage *\fP +The name of this function is misleading and will be changed to reflect +proper usage in the Boron release of Salt. The path option will be removed +and the key will be the actual key. See the following issue: +.sp +\fI\%https://github.com/saltstack/salt/issues/25618\fP +.sp +In order to not break existing state files this function will call the +set_value function if key is passed. Key will be passed as the value name. +If key is not passed, this function will return the default value for the +key. +.sp +In the Boron release path will be removed and key will be the path. You will +not pass value. + +.nf +** +.fi + +.nf +* +.fi + +.sp Create a registry key .sp CLI Example: @@ -119797,10 +118608,32 @@ salt \(aq*\(aq reg.create_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.reg.delete_key(hkey, path, key, reflection=True) -Delete a registry key +.B salt.modules.reg.delete_key(hkey, path, key=None, reflection=True, force=False) +\fB* Incorrect Usage *\fP +The name of this function is misleading and will be changed to reflect +proper usage in the Boron release of Salt. The path option will be removed +and the key will be the actual key. See the following issue: .sp -Note: This cannot delete a key with subkeys +\fI\%https://github.com/saltstack/salt/issues/25618\fP +.sp +In order to not break existing state files this function will call the +delete_value function if a key is passed. Key will be passed as the value +name. If key is not passed, this function will return the default value for +the key. +.sp +In the Boron release path will be removed and key will be the path. +reflection will also be removed. + +.nf +** +.fi + +.nf +* +.fi + +.sp +Delete a registry key .sp CLI Example: .INDENT 7.0 @@ -119808,7 +118641,117 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq reg.delete_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq +salt \(aq*\(aq reg.delete_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhkey\fP (\fI\%str\fP) \-\- (will be changed to hive) +The name of the hive. Can be one of the following +\- HKEY_LOCAL_MACHINE or HKLM +\- HKEY_CURRENT_USER or HKCU +\- HKEY_USER or HKU +.IP \(bu 2 +\fBpath\fP (\fI\%str\fP) \-\- (will be changed to key) +The key (looks like a path) to remove. +.IP \(bu 2 +\fBkey\fP (\fI\%str\fP) \-\- (used incorrectly) +Will be removed in Boron +.IP \(bu 2 +\fBreflection\fP (\fI\%bool\fP) \-\- +.sp +A boolean value indicating that the value should also be removed from +the Wow6432Node portion of the registry. Only applies to 64 bit Windows. +This setting is ignored for 32 bit Windows. +.sp +Only applies to delete value. If the key parameter is passed, this +function calls delete_value instead. Will be changed in Boron. + +.IP \(bu 2 +\fBforce\fP (\fI\%bool\fP) \-\- A boolean value indicating that all subkeys should be removed as well. +If this is set to False (default) and there are subkeys, the delete_key +function will fail. +.UNINDENT +.TP +.B Returns +Returns True if successful, False if not +If force=True, the results of delete_key_recursive are returned. +.TP +.B Return type +\fI\%bool\fP +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.reg.delete_key_recursive(hive, key) +New in version 2015.5.4. + +.sp +Delete a registry key to include all subkeys. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhive\fP \-\- The name of the hive. Can be one of the following +\- HKEY_LOCAL_MACHINE or HKLM +\- HKEY_CURRENT_USER or HKCU +\- HKEY_USER or HKU +.IP \(bu 2 +\fBkey\fP \-\- The key to remove (looks like a path) +.UNINDENT +.TP +.B Returns +A dictionary listing the keys that deleted successfully as well as those +that failed to delete. +.TP +.B Return type +\fI\%dict\fP +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.reg.delete_value(hive, key, vname=None, reflection=True) +Delete a registry value entry or the default value for a key. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhive\fP (\fI\%str\fP) \-\- The name of the hive. Can be one of the following +\- HKEY_LOCAL_MACHINE or HKLM +\- HKEY_CURRENT_USER or HKCU +\- HKEY_USER or HKU +.IP \(bu 2 +\fBkey\fP (\fI\%str\fP) \-\- The key (looks like a path) to the value name. +.IP \(bu 2 +\fBvname\fP (\fI\%str\fP) \-\- The value name. These are the individual name/data pairs under the key. +If not passed, the key (Default) value will be deleted. +.IP \(bu 2 +\fBreflection\fP (\fI\%bool\fP) \-\- A boolean value indicating that the value should also be set in the +Wow6432Node portion of the registry. Only applies to 64 bit Windows. +This setting is ignored for 32 bit Windows. +.UNINDENT +.TP +.B Returns +Returns True if successful, False if not +.TP +.B Return type +\fI\%bool\fP +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq reg.delete_value HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq .ft P .fi .UNINDENT @@ -119816,9 +118759,36 @@ salt \(aq*\(aq reg.delete_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.reg.read_key(hkey, path, key, reflection=True) +.B salt.modules.reg.read_key(hkey, path, key=None) +\fB* Incorrect Usage *\fP +The name of this function is misleading and will be changed to reflect +proper usage in the Boron release of Salt. The path option will be removed +and the key will be the actual key. See the following issue: +.sp +\fI\%https://github.com/saltstack/salt/issues/25618\fP +.sp +In order to not break existing state files this function will call the +read_value function if a key is passed. Key will be passed as the value +name. If key is not passed, this function will return the default value for +the key. +.sp +In the Boron release this function will be removed in favor of read_value. + +.nf +** +.fi + +.nf +* +.fi + +.sp Read registry key value .sp +Returns the first unnamed value (Default) as a string. +Returns none if first unnamed value is empty. +Returns False if key not found. +.sp CLI Example: .INDENT 7.0 .INDENT 3.5 @@ -119833,8 +118803,78 @@ salt \(aq*\(aq reg.read_key HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqversio .UNINDENT .INDENT 0.0 .TP -.B salt.modules.reg.set_key(hkey, path, key, value, vtype=\(aqREG_DWORD\(aq, reflection=True) +.B salt.modules.reg.read_value(hive, key, vname=None) +Reads a registry value entry or the default value for a key. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhive\fP (\fI\%str\fP) \-\- The name of the hive. Can be one of the following +\- HKEY_LOCAL_MACHINE or HKLM +\- HKEY_CURRENT_USER or HKCU +\- HKEY_USER or HKU +.IP \(bu 2 +\fBkey\fP (\fI\%str\fP) \-\- The key (looks like a path) to the value name. +.IP \(bu 2 +\fBvname\fP (\fI\%str\fP) \-\- The value name. These are the individual name/data pairs under the key. +If not passed, the key (Default) value will be returned +.UNINDENT +.TP +.B Returns +A dictionary containing the passed settings as well as the value_data if +successful. If unsuccessful, sets success to False +.sp +If vname is not passed: +\- Returns the first unnamed value (Default) as a string. +\- Returns none if first unnamed value is empty. +\- Returns False if key not found. + +.TP +.B Return type +\fI\%dict\fP +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq reg.read_value HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.reg.set_key(hkey, path, value, key=None, vtype=\(aqREG_DWORD\(aq, reflection=True) +\fB* Incorrect Usage *\fP +The name of this function is misleading and will be changed to reflect +proper usage in the Boron release of Salt. The path option will be removed +and the key will be the actual key. See the following issue: +.sp +\fI\%https://github.com/saltstack/salt/issues/25618\fP +.sp +In order to not break existing state files this function will call the +set_value function if a key is passed. Key will be passed as the value +name. If key is not passed, this function will return the default value for +the key. +.sp +In the Boron release this function will be removed in favor of set_value. + +.nf +** +.fi + +.nf +* +.fi + +.sp Set a registry key +.sp vtype: \fI\%http://docs.python.org/2/library/_winreg.html#value\-types\fP .sp CLI Example: @@ -119849,6 +118889,58 @@ salt \(aq*\(aq reg.set_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversion\ .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.reg.set_value(hive, key, vname=None, vdata=None, vtype=\(aqREG_SZ\(aq, reflection=True) +Sets a registry value entry or the default value for a key. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBhive\fP (\fI\%str\fP) \-\- The name of the hive. Can be one of the following +\- HKEY_LOCAL_MACHINE or HKLM +\- HKEY_CURRENT_USER or HKCU +\- HKEY_USER or HKU +.IP \(bu 2 +\fBkey\fP (\fI\%str\fP) \-\- The key (looks like a path) to the value name. +.IP \(bu 2 +\fBvname\fP (\fI\%str\fP) \-\- The value name. These are the individual name/data pairs under the key. +If not passed, the key (Default) value will be set. +.IP \(bu 2 +\fBvdata\fP (\fI\%str\fP) \-\- The value data to be set. +.IP \(bu 2 +\fBvtype\fP (\fI\%str\fP) \-\- The value type. Can be one of the following: +\- REG_BINARY +\- REG_DWORD +\- REG_EXPAND_SZ +\- REG_MULTI_SZ +\- REG_SZ +.IP \(bu 2 +\fBreflection\fP (\fI\%bool\fP) \-\- A boolean value indicating that the value should also be set in the +Wow6432Node portion of the registry. Only applies to 64 bit Windows. +This setting is ignored for 32 bit Windows. +.UNINDENT +.TP +.B Returns +Returns True if successful, False if not +.TP +.B Return type +\fI\%bool\fP +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq reg.set_value HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq \(aq2015.5.2\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT .SS salt.modules.rest_package .sp Service support for the REST example @@ -121676,13 +120768,25 @@ The service_url will form the basis for the final endpoint that is used to query the service. .sp SSL verification may also be turned off in the configuration: -.sp +.INDENT 7.0 +.INDENT 3.5 s3.verify_ssl: False +.UNINDENT +.UNINDENT .sp This is required if using S3 bucket names that contain a period, as these will not match Amazon\(aqs S3 wildcard certificates. Certificate verification is enabled by default. .sp +AWS region may be specified in the configuration: +.INDENT 7.0 +.INDENT 3.5 +s3.location: eu\-central\-1 +.UNINDENT +.UNINDENT +.sp +Default is us\-east\-1. +.sp This module should be usable to query other S3\-like services, such as Eucalyptus. .TP @@ -121691,7 +120795,7 @@ requests .UNINDENT .INDENT 0.0 .TP -.B salt.modules.s3.delete(bucket, path=None, action=None, key=None, keyid=None, service_url=None, verify_ssl=None) +.B salt.modules.s3.delete(bucket, path=None, action=None, key=None, keyid=None, service_url=None, verify_ssl=None, location=None) Delete a bucket, or delete an object from a bucket. .sp CLI Example to delete a bucket: @@ -121720,7 +120824,7 @@ salt myminion s3.delete mybucket remoteobject .UNINDENT .INDENT 0.0 .TP -.B salt.modules.s3.get(bucket=None, path=None, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None) +.B salt.modules.s3.get(bucket=None, path=None, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None, location=None) List the contents of a bucket, or return an object from a bucket. Set return_bin to True in order to retrieve an object wholesale. Otherwise, Salt will attempt to parse an XML response. @@ -121811,7 +120915,7 @@ salt myminion s3.get mybucket myfile.png action=acl .UNINDENT .INDENT 0.0 .TP -.B salt.modules.s3.head(bucket, path=None, key=None, keyid=None, service_url=None, verify_ssl=None) +.B salt.modules.s3.head(bucket, path=None, key=None, keyid=None, service_url=None, verify_ssl=None, location=None) Return the metadata for a bucket, or an object in a bucket. .sp CLI Examples: @@ -121829,7 +120933,7 @@ salt myminion s3.head mybucket myfile.png .UNINDENT .INDENT 0.0 .TP -.B salt.modules.s3.put(bucket, path=None, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None) +.B salt.modules.s3.put(bucket, path=None, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None, location=None) Create a new bucket, or upload an object to a bucket. .sp CLI Example to create a bucket: @@ -121876,657 +120980,6 @@ salt saltcloud.create webserver rackspace_centos_512 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.saltutil -.sp -The Saltutil module is used to manage the state of the salt minion itself. It -is used to manage minion modules as well as automate updates to the salt -minion. -.INDENT 0.0 -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -esky Python module for update functionality -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.clear_cache() -Forcibly removes all caches on a minion. -.sp -New in version 2014.7.0. - -.sp -WARNING: The safest way to clear a minion cache is by first stopping -the minion and then deleting the cache files before restarting it. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.clear_cache -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.cmd(tgt, fun, arg=(), timeout=None, expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, ssh=False, **kwargs) -Assuming this minion is a master, execute a salt command -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.cmd -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.cmd_iter(tgt, fun, arg=(), timeout=None, expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, ssh=False, **kwargs) -Assuming this minion is a master, execute a salt command -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.cmd_iter -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.find_cached_job(jid) -Return the data for a specific cached job id -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.find_cached_job -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.find_job(jid) -Return the data for a specific job id -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.find_job -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.is_running(fun) -If the named function is running return the data associated with it/them. -The argument can be a glob -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.is_running state.highstate -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.kill_job(jid) -Sends a kill signal (SIGKILL 9) to the named salt job\(aqs process -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.kill_job -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.mmodule(saltenv, fun, *args, **kwargs) -Loads minion modules from an environment so that they can be used in pillars -for that environment -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.mmodule base test.ping -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.refresh_beacons() -Signal the minion to refresh the beacons. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.refresh_beacons -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.refresh_modules(async=True) -Signal the minion to refresh the module and grain data -.sp -The default is to refresh module asynchronously. To block -until the module refresh is complete, set the \(aqasync\(aq flag -to False. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.refresh_modules -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.refresh_pillar() -Signal the minion to refresh the pillar data. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.refresh_pillar -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.regen_keys() -Used to regenerate the minion keys. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.regen_keys -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.revoke_auth(preserve_minion_cache=False) -The minion sends a request to the master to revoke its own key. -Note that the minion session will be revoked and the minion may -not be able to return the result of this command back to the master. -.sp -If the \(aqpreserve_minion_cache\(aq flag is set to True, the master -cache for this minion will not be removed. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.revoke_auth -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.runner(fun, **kwargs) -Execute a runner module (this function must be run on the master) -.sp -New in version 2014.7. - -.INDENT 7.0 -.TP -.B name -The name of the function to run -.TP -.B kwargs -Any keyword arguments to pass to the runner function -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.runner jobs.list_jobs -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.running() -Return the data on all running salt processes on the minion -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.running -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.signal_job(jid, sig) -Sends a signal to the named salt job\(aqs process -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.signal_job 15 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_all(saltenv=None, refresh=True) -Sync down all of the dynamic modules from the file server for a specific -environment -.INDENT 7.0 -.TP -.B refresh -True -Also refresh the execution modules available to the minion. -.UNINDENT -.sp -\fBIMPORTANT:\fP -.INDENT 7.0 -.INDENT 3.5 -If this function is executed using a \fBmodule.run\fP state, the SLS file will not have access to -newly synced execution modules unless a \fBrefresh\fP argument is -added to the state, like so: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -load_my_custom_module: - module.run: - \- name: saltutil.sync_all - \- refresh: True -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -See \fIhere\fP for a more detailed explanation of -why this is necessary. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_all -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_beacons(saltenv=None, refresh=True) -Sync the beacons from the _beacons directory on the salt master file -server. This function is environment aware, pass the desired environment -to grab the contents of the _beacons directory, base is the default -environment. -.sp -New in version 2015.5.1. - -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_beacons -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_grains(saltenv=None, refresh=True) -Sync the grains from the _grains directory on the salt master file -server. This function is environment aware, pass the desired environment -to grab the contents of the _grains directory, base is the default -environment. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_grains -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_log_handlers(saltenv=None, refresh=True) -New in version 2015.8.0. - -.sp -Sync utility source files from the _log_handlers directory on the salt master file -server. This function is environment aware, pass the desired environment -to grab the contents of the _log_handlers directory, base is the default -environment. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_log_handlers -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_modules(saltenv=None, refresh=True) -Sync the modules from the _modules directory on the salt master file -server. This function is environment aware, pass the desired environment -to grab the contents of the _modules directory, base is the default -environment. -.sp -\fBIMPORTANT:\fP -.INDENT 7.0 -.INDENT 3.5 -If this function is executed using a \fBmodule.run\fP state, the SLS file will not have access to -newly synced execution modules unless a \fBrefresh\fP argument is -added to the state, like so: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -load_my_custom_module: - module.run: - \- name: saltutil.sync_modules - \- refresh: True -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -See \fIhere\fP for a more detailed explanation of -why this is necessary. -.UNINDENT -.UNINDENT -.sp -New in version 2015.5.1. - -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_modules -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_outputters(saltenv=None, refresh=True) -Sync the outputters from the _outputters directory on the salt master file -server. This function is environment aware, pass the desired environment -to grab the contents of the _outputters directory, base is the default -environment. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_outputters -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_renderers(saltenv=None, refresh=True) -Sync the renderers from the _renderers directory on the salt master file -server. This function is environment aware, pass the desired environment -to grab the contents of the _renderers directory, base is the default -environment. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_renderers -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_returners(saltenv=None, refresh=True) -Sync the returners from the _returners directory on the salt master file -server. This function is environment aware, pass the desired environment -to grab the contents of the _returners directory, base is the default -environment. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_returners -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_states(saltenv=None, refresh=True) -Sync the states from the _states directory on the salt master file -server. This function is environment aware, pass the desired environment -to grab the contents of the _states directory, base is the default -environment. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_states -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.sync_utils(saltenv=None, refresh=True) -Sync utility source files from the _utils directory on the salt master file -server. This function is environment aware, pass the desired environment -to grab the contents of the _utils directory, base is the default -environment. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.sync_utils -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.term_job(jid) -Sends a termination signal (SIGTERM 15) to the named salt job\(aqs process -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.term_job -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.update(version=None) -Update the salt minion from the URL defined in opts[\(aqupdate_url\(aq] -SaltStack, Inc provides the latest builds here: -update_url: \fI\%http://docs.saltstack.com/downloads/\fP -.sp -Be aware that as of 2014\-8\-11 there\(aqs a bug in esky such that only the -latest version available in the update_url can be downloaded and installed. -.sp -This feature requires the minion to be running a bdist_esky build. -.sp -The version number is optional and will default to the most recent version -available at opts[\(aqupdate_url\(aq]. -.sp -Returns details about the transaction upon completion. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.update -salt \(aq*\(aq saltutil.update 0.10.3 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.saltutil.wheel(fun, **kwargs) -Execute a wheel module (this function must be run on the master) -.sp -New in version 2014.7. - -.INDENT 7.0 -.TP -.B name -The name of the function to run -.TP -.B kwargs -Any keyword arguments to pass to the wheel function -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq saltutil.wheel key.accept match=jerry -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.schedule .sp Module for managing the Salt schedule on a minion @@ -123791,8 +122244,18 @@ salt \(aq*\(aq slack.post_message channel="Development Room" message="Build is d Module for running imgadm command on SmartOS .INDENT 0.0 .TP -.B salt.modules.smartos_imgadm.avail(search=None) +.B salt.modules.smartos_imgadm.avail(search=None, verbose=False) Return a list of available images +.INDENT 7.0 +.TP +.B search +string +Specifies search keyword +.TP +.B verbose +boolean (False) +Specifies verbose output +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -123801,6 +122264,7 @@ CLI Example: .nf .ft C salt \(aq*\(aq imgadm.avail [percona] +salt \(aq*\(aq imgadm.avail verbose=True .ft P .fi .UNINDENT @@ -123810,6 +122274,12 @@ salt \(aq*\(aq imgadm.avail [percona] .TP .B salt.modules.smartos_imgadm.delete(uuid=None) Remove an installed image +.INDENT 7.0 +.TP +.B uuid +string +Specifies uuid to import +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -123842,8 +122312,18 @@ salt \(aq*\(aq imgadm.get e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_imgadm.import_image(uuid=None) +.B salt.modules.smartos_imgadm.import(uuid=None, verbose=False) Import an image from the repository +.INDENT 7.0 +.TP +.B uuid +string +Specifies uuid to import +.TP +.B verbose +boolean (False) +Specifies verbose output +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -123851,7 +122331,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq imgadm.import_image e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f +salt \(aq*\(aq imgadm.import e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f [verbose=True] .ft P .fi .UNINDENT @@ -123859,8 +122339,14 @@ salt \(aq*\(aq imgadm.import_image e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_imgadm.list_installed() +.B salt.modules.smartos_imgadm.list(verbose=False) Return a list of installed images +.INDENT 7.0 +.TP +.B verbose +boolean (False) +Specifies verbose output +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -123868,7 +122354,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq imgadm.list_installed +salt \(aq*\(aq imgadm.list [verbose=True] .ft P .fi .UNINDENT @@ -123893,8 +122379,14 @@ salt \(aq*\(aq imgadm.show e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_imgadm.update_installed() -Gather info on unknown images (locally installed) +.B salt.modules.smartos_imgadm.update(uuid=\(aq\(aq) +Gather info on unknown image(s) (locally installed) +.INDENT 7.0 +.TP +.B uuid +string +Specifies uuid of image +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -123902,7 +122394,30 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq imgadm.update_installed() +salt \(aq*\(aq imgadm.update [uuid] +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.smartos_imgadm.vacuum(verbose=False) +Remove unused images +.INDENT 7.0 +.TP +.B verbose +boolean (False) +Specifies verbose output +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq imgadm.vacuum [verbose=True] .ft P .fi .UNINDENT @@ -123927,11 +122442,32 @@ salt \(aq*\(aq imgadm.version .UNINDENT .SS salt.modules.smartos_vmadm .sp -Module for managing VMs on SmartOS +Module for running vmadm command on SmartOS .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.destroy(uuid=None) -Hard power down the virtual machine, this is equivalent to pulling the power +.B salt.modules.smartos_vmadm.create(**kwargs) +Create a new vm +.INDENT 7.0 +.TP +.B from_file +string +Specifies the json file to create the vm from. +Note: when this is present all other options will be ignored. +.UNINDENT +.INDENT 7.0 +.IP \(bu 2 +.INDENT 2.0 +.TP +.B : string|int|... +Specifies options to set for the vm. +Example: image_uuid=UUID, will specify the image_uuid for the vm to be created. +.INDENT 7.0 +.INDENT 3.5 +nics=\(aq[{"nic_tag": "admin", "ip": "198.51.100.123", "netmask": "255.255.255.0"}]\(aq, adds 1 nic over the admin tag +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -123939,7 +122475,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.destroy +salt \(aq*\(aq vmadm.create from_file=/tmp/new_vm.json +salt \(aq*\(aq vmadm.create image_uuid=\(aq...\(aq alias=\(aq...\(aq nics=\(aq[{ "nic_tag": "admin", "ip": "198.51.100.123", ...}, {...}]\(aq [...] .ft P .fi .UNINDENT @@ -123947,8 +122484,25 @@ salt \(aq*\(aq virt.destroy .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.get_macs(uuid=None) -Return a list off MAC addresses from the named VM +.B salt.modules.smartos_vmadm.create_snapshot(vm=None, name=None, key=\(aquuid\(aq) +Create snapshot of a vm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm +.TP +.B name +string +Name of snapshot. +The snapname must be 64 characters or less +and must only contain alphanumeric characters and +characters in the set [\-_.:%] to comply with ZFS restrictions. +.TP +.B key +string +Specifies what \(aqvm\(aq is. Value = uuid|alias|hostname +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -123956,7 +122510,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.get_macs +salt \(aq*\(aq vmadm.create_snapshot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 baseline +salt \(aq*\(aq vmadm.create_snapshot nacl baseline key=alias .ft P .fi .UNINDENT @@ -123964,8 +122519,18 @@ salt \(aq*\(aq virt.get_macs .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.init(**kwargs) -Initialize a new VM +.B salt.modules.smartos_vmadm.delete(vm=None, key=\(aquuid\(aq) +Delete a vm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm +.TP +.B key +string +Specifies what \(aqvm\(aq is. Value = uuid|alias|hostname +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -123973,7 +122538,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.init image_uuid=\(aq...\(aq alias=\(aq...\(aq [...] +salt \(aq*\(aq vmadm.delete 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 +salt \(aq*\(aq vmadm.delete nacl key=alias .ft P .fi .UNINDENT @@ -123981,8 +122547,25 @@ salt \(aq*\(aq virt.init image_uuid=\(aq...\(aq alias=\(aq...\(aq [...] .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.list_active_vms() -Return a list of uuids for active virtual machine on the minion +.B salt.modules.smartos_vmadm.delete_snapshot(vm=None, name=None, key=\(aquuid\(aq) +Delete snapshot of a vm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm +.TP +.B name +string +Name of snapshot. +The snapname must be 64 characters or less +and must only contain alphanumeric characters and +characters in the set [\-_.:%] to comply with ZFS restrictions. +.TP +.B key +string +Specifies what \(aqvm\(aq is. Value = uuid|alias|hostname +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -123990,7 +122573,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.list_active_vms +salt \(aq*\(aq vmadm.delete_snapshot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 baseline +salt \(aq*\(aq vmadm.delete_snapshot nacl baseline key=alias .ft P .fi .UNINDENT @@ -123998,8 +122582,18 @@ salt \(aq*\(aq virt.list_active_vms .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.list_inactive_vms() -Return a list of uuids for inactive virtual machine on the minion +.B salt.modules.smartos_vmadm.get(vm=None, key=\(aquuid\(aq) +Output the JSON object describing a VM +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm +.TP +.B key +string +Specifies what \(aqvm\(aq is. Value = uuid|alias|hostname +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -124007,7 +122601,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.list_inactive_vms +salt \(aq*\(aq vmadm.get 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 +salt \(aq*\(aq vmadm.get nacl key=alias .ft P .fi .UNINDENT @@ -124015,8 +122610,23 @@ salt \(aq*\(aq virt.list_inactive_vms .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.list_vms() -Return a list of virtual machine names on the minion +.B salt.modules.smartos_vmadm.info(vm=None, info_type=\(aqall\(aq, key=\(aquuid\(aq) +Lookup info on running kvm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm +.TP +.B info_type +string +Specifies what info to return. +Value = all|block|blockstats|chardev|cpus|kvm|pci|spice|version|vnc +.TP +.B key +string +Specifies what \(aqvm\(aq is. Value = uuid|alias|hostname +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -124024,7 +122634,10 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.list_vms +salt \(aq*\(aq vmadm.info 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 +salt \(aq*\(aq vmadm.info 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 vnc +salt \(aq*\(aq vmadm.info nacl key=alias +salt \(aq*\(aq vmadm.info nacl vnc key=alias .ft P .fi .UNINDENT @@ -124032,8 +122645,31 @@ salt \(aq*\(aq virt.list_vms .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.reboot(uuid=None) -Reboot a domain via ACPI request +.B salt.modules.smartos_vmadm.list(search=None, sort=None, order=\(aquuid, type, ram, state, alias\(aq, keyed=False) +Return a list of VMs +.INDENT 7.0 +.TP +.B search +string +Specifies the vmadm filter property +.TP +.B sort +string +Specifies the vmadm sort (\-s) property +.TP +.B order +string +Specifies the vmadm order (\-o) property +Default: uuid,type,ram,state,alias +.TP +.B keyed +boolean.INDENT 7.0 +.TP +.B Specified if the output should be an array (False) or dict (True) +Dict key is first field from order parameter +Note: if key is not unique last vm wins. +.UNINDENT +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -124041,7 +122677,9 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.reboot +salt \(aq*\(aq vmadm.list +salt \(aq*\(aq vmadm.list order=alias,ram,cpu_cap sort=\-ram,\-cpu_cap +salt \(aq*\(aq vmadm.list search=\(aqtype=KVM\(aq .ft P .fi .UNINDENT @@ -124049,11 +122687,23 @@ salt \(aq*\(aq virt.reboot .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.setmem(uuid, memory) -Change the amount of memory allocated to VM. - is to be specified in MB. -.sp -Note for KVM : this would require a restart of the VM. +.B salt.modules.smartos_vmadm.lookup(search=None, order=None, one=False) +Return a list of VMs using lookup +.INDENT 7.0 +.TP +.B search +string +Specifies the vmadm filter property +.TP +.B order +string +Specifies the vmadm order (\-o) property +Default: uuid,type,ram,state,alias +.TP +.B one +boolean +Specifies if you to one result only (\-1) +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -124061,7 +122711,9 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.setmem 512 +salt \(aq*\(aq vmadm.lookup search=\(aqstate=running\(aq +salt \(aq*\(aq vmadm.lookup search=\(aqstate=running\(aq order=uuid,alias,hostname +salt \(aq*\(aq vmadm.lookup search=\(aqalias=nacl\(aq one=True .ft P .fi .UNINDENT @@ -124069,8 +122721,22 @@ salt \(aq*\(aq virt.setmem 512 .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.shutdown(uuid=None) -Send a soft shutdown signal to the named vm +.B salt.modules.smartos_vmadm.reboot(vm=None, force=False, key=\(aquuid\(aq) +Reboot a vm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm to be rebooted +.TP +.B force +boolean +Specifies if the vm should be force rebooted +.TP +.B key +string +Specifies if \(aqvm\(aq is a uuid, alias or hostname. +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -124078,7 +122744,10 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.shutdown +salt \(aq*\(aq vmadm.reboot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 +salt \(aq*\(aq vmadm.reboot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 True +salt \(aq*\(aq vmadm.reboot vm=nacl key=alias +salt \(aq*\(aq vmadm.reboot vm=nina.example.org key=hostname .ft P .fi .UNINDENT @@ -124086,8 +122755,18 @@ salt \(aq*\(aq virt.shutdown .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.start(uuid=None) -Start a defined domain +.B salt.modules.smartos_vmadm.receive(uuid=None, source=None) +Receive a vm from a directory +.INDENT 7.0 +.TP +.B uuid +string +Specifies uuid of vm to receive +.TP +.B source +string +Specifies the target. Can be a directory path. +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -124095,7 +122774,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.start +salt \(aq*\(aq vmadm.receive 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 /opt/backups .ft P .fi .UNINDENT @@ -124103,8 +122782,22 @@ salt \(aq*\(aq virt.start .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.vm_info(uuid=None) -Return a dict with information about the specified VM on this CN +.B salt.modules.smartos_vmadm.reprovision(vm=None, image=None, key=\(aquuid\(aq) +Reprovision a vm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm +.TP +.B image +string +uuid of new image +.TP +.B key +string +Specifies what \(aqvm\(aq is. Value = uuid|alias|hostname +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -124112,7 +122805,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.vm_info +salt \(aq*\(aq vmadm.reprovision 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 c02a2044\-c1bd\-11e4\-bd8c\-dfc1db8b0182 +salt \(aq*\(aq vmadm.reprovision nacl c02a2044\-c1bd\-11e4\-bd8c\-dfc1db8b0182 key=alias .ft P .fi .UNINDENT @@ -124120,8 +122814,25 @@ salt \(aq*\(aq virt.vm_info .UNINDENT .INDENT 0.0 .TP -.B salt.modules.smartos_vmadm.vm_virt_type(uuid=None) -Return VM virtualization type : OS or KVM +.B salt.modules.smartos_vmadm.rollback_snapshot(vm=None, name=None, key=\(aquuid\(aq) +Rollback snapshot of a vm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm +.TP +.B name +string +Name of snapshot. +The snapname must be 64 characters or less +and must only contain alphanumeric characters and +characters in the set [\-_.:%] to comply with ZFS restrictions. +.TP +.B key +string +Specifies what \(aqvm\(aq is. Value = uuid|alias|hostname +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -124129,7 +122840,190 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq virt.vm_virt_type +salt \(aq*\(aq vmadm.rollback_snapshot 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 baseline +salt \(aq*\(aq vmadm.rollback_snapshot nacl baseline key=alias +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.smartos_vmadm.send(vm=None, target=None, key=\(aquuid\(aq) +Send a vm to a directory +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm to be started +.TP +.B target +string +Specifies the target. Can be a directory path. +.TP +.B key +string +Specifies if \(aqvm\(aq is a uuid, alias or hostname. +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vmadm.send 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 /opt/backups +salt \(aq*\(aq vmadm.send vm=nacl target=/opt/backups key=alias +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.smartos_vmadm.start(vm=None, options=None, key=\(aquuid\(aq) +Start a vm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm to be started +.TP +.B options +string +Specifies additional options +.TP +.B key +string +Specifies if \(aqvm\(aq is a uuid, alias or hostname. +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vmadm.start 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 +salt \(aq*\(aq vmadm.start 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 \(aqorder=c,once=d cdrom=/path/to/image.iso,ide\(aq +salt \(aq*\(aq vmadm.start vm=nacl key=alias +salt \(aq*\(aq vmadm.start vm=nina.example.org key=hostname +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.smartos_vmadm.stop(vm=None, force=False, key=\(aquuid\(aq) +Stop a vm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm to be stopped +.TP +.B force +boolean +Specifies if the vm should be force stopped +.TP +.B key +string +Specifies if \(aqvm\(aq is a uuid, alias or hostname. +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vmadm.stop 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 +salt \(aq*\(aq vmadm.stop 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 True +salt \(aq*\(aq vmadm.stop vm=nacl key=alias +salt \(aq*\(aq vmadm.stop vm=nina.example.org key=hostname +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.smartos_vmadm.sysrq(vm=None, action=\(aqnmi\(aq, key=\(aquuid\(aq) +Send non\-maskable interupt to vm or capture a screenshot +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm +.TP +.B action +string +Specifies the action nmi or screenshot +.TP +.B key +string +Specifies what \(aqvm\(aq is. Value = uuid|alias|hostname +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vmadm.sysrq 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 nmi +salt \(aq*\(aq vmadm.sysrq 186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 screenshot +salt \(aq*\(aq vmadm.sysrq nacl nmi key=alias +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.smartos_vmadm.update(**kwargs) +Update a new vm +.INDENT 7.0 +.TP +.B vm +string +Specifies the vm to be updated +.TP +.B key +string +Specifies if \(aqvm\(aq is a uuid, alias or hostname. +.TP +.B from_file +string +Specifies the json file to update the vm with. +Note: when this is present all other options except \(aqvm\(aq and \(aqkey\(aq will be ignored. +.UNINDENT +.INDENT 7.0 +.IP \(bu 2 +.INDENT 2.0 +.TP +.B : string|int|... +Specifies options to updte for the vm. +Example: image_uuid=UUID, will specify the image_uuid for the vm to be created. +.INDENT 7.0 +.INDENT 3.5 +add_nics=\(aq[{"nic_tag": "admin", "ip": "198.51.100.123", "netmask": "255.255.255.0"}]\(aq, adds 1 nic over the admin tag +remove_nics=\(aq[ "12:ae:d3:28:98:b8" ], remove nics with mac 12:ae:d3:28:98:b8 +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vmadm.update vm=186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 from_file=/tmp/new_vm.json +salt \(aq*\(aq vmadm.update vm=nacl key=alias from_file=/tmp/new_vm.json +salt \(aq*\(aq vmadm.update vm=186da9ab\-7392\-4f55\-91a5\-b8f1fe770543 max_physical_memory=1024 .ft P .fi .UNINDENT @@ -127837,604 +126731,6 @@ As you can see you can tell Salt not to read from the user\(aqs private (or publ file path to \fBFalse\fP\&. This can be useful to prevent Salt from publishing private data via Salt Mine or others. .UNINDENT -.SS salt.modules.state -.sp -Control the state system on the minion. -.SS State Caching -.sp -When a highstate is called, the minion automatically caches a copy of the last high data. -If you then run a highstate with cache=True it will use that cached highdata and won\(aqt hit the fileserver -except for \fBsalt://\fP links in the states themselves. -.INDENT 0.0 -.TP -.B salt.modules.state.apply(mods=None, **kwargs) -New in version 2015.5.0. - -.sp -Apply states! This function will call highstate or state.sls based on the -arguments passed in, state.apply is intended to be the main gateway for -all state executions. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.apply -salt \(aq*\(aq state.apply test -salt \(aq*\(aq state.apply test,pkgs -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.check_request(name=None) -New in version 2015.5.0. - -.sp -Return the state request information, if any -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.check_request -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.clear_cache() -Clear out cached state files, forcing even cache runs to refresh the cache -on the next state execution. -.sp -Remember that the state cache is completely disabled by default, this -execution only applies if cache=True is used in states -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.clear_cache -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.clear_request(name=None) -New in version 2015.5.0. - -.sp -Clear out the state execution request without executing it -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.clear_request -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.disable(states) -Disable state runs. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.disable highstate - -salt \(aq*\(aq state.disable highstate,test.succeed_without_changes -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -To disable a state file from running provide the same name that would -be passed in a state.sls call. -.sp -salt \(aq*\(aq state.disable bind.config -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.enable(states) -Enable state function or sls run -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.enable highstate - -salt \(aq*\(aq state.enable test.succeed_without_changes -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -To enable a state file from running provide the same name that would -be passed in a state.sls call. -.sp -salt \(aq*\(aq state.disable bind.config -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.high(data, test=False, queue=False, **kwargs) -Execute the compound calls stored in a single set of high data -This function is mostly intended for testing the state system -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.high \(aq{"vim": {"pkg": ["installed"]}}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.highstate(test=None, queue=False, **kwargs) -Retrieve the state data from the salt master for this minion and execute it -.INDENT 7.0 -.TP -.B test -Notify states to execute in test\-only (dry\-run) mode. -.sp -Sets the \fBtest\fP variable in the minion \fBopts\fP for the duration of -the state run. -.TP -.B pillar -Custom Pillar data can be passed with the \fBpillar\fP kwarg. Values -passed here will override hard\-coded Pillar values. -.TP -.B queue -\fBFalse\fP -Instead of failing immediately when another state run is in progress, -queue the new state run to begin running once the other has finished. -.sp -This option starts a new thread for each queued state run so use this -option sparingly. -.TP -.B localconfig: -Instead of using running minion opts, load \fBlocalconfig\fP and merge that -with the running minion opts. This functionality is intended for using -"roots" of salt directories (with their own minion config, pillars, -file_roots) to run highstate out of. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.highstate - -salt \(aq*\(aq state.highstate whitelist=sls1_to_run,sls2_to_run -salt \(aq*\(aq state.highstate exclude=sls_to_exclude -salt \(aq*\(aq state.highstate exclude="[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]" - -salt \(aq*\(aq state.highstate pillar="{foo: \(aqFoo!\(aq, bar: \(aqBar!\(aq}" -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.list_disabled() -List the states which are currently disabled -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.list_disabled -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.low(data, queue=False, **kwargs) -Execute a single low data call -This function is mostly intended for testing the state system -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.low \(aq{"state": "pkg", "fun": "installed", "name": "vi"}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.pkg(pkg_path, pkg_sum, hash_type, test=False, **kwargs) -Execute a packaged state run, the packaged state run will exist in a -tarball available locally. This packaged state -can be generated using salt\-ssh. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.pkg /tmp/state_pkg.tgz -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.request(mods=None, **kwargs) -New in version 2015.5.0. - -.sp -Request that the local admin execute a state run via -\fIsalt\-call state.run_request\fP -All arguments match state.apply -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.request -salt \(aq*\(aq state.request test -salt \(aq*\(aq state.request test,pkgs -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.run_request(name=\(aqdefault\(aq, **kwargs) -New in version 2015.5.0. - -.sp -Execute the pending state request -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.run_request -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.running(concurrent=False) -Return a dict of state return data if a state function is already running. -This function is used to prevent multiple state calls from being run at -the same time. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.running -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.show_highstate(queue=False, **kwargs) -Retrieve the highstate data from the salt master and display it -.sp -Custom Pillar data can be passed with the \fBpillar\fP kwarg. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.show_highstate -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.show_low_sls(mods, saltenv=\(aqbase\(aq, test=None, queue=False, env=None, **kwargs) -Display the low data from a specific sls. The default environment is -\fBbase\fP, use \fBsaltenv\fP (\fBenv\fP in Salt 0.17.x and older) to specify a -different environment. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.show_low_sls foo -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.show_lowstate(queue=False, **kwargs) -List out the low data that will be applied to this minion -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.show_lowstate -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.show_sls(mods, saltenv=\(aqbase\(aq, test=None, queue=False, env=None, **kwargs) -Display the state data from a specific sls or list of sls files on the -master. The default environment is \fBbase\fP, use \fBsaltenv\fP (\fBenv\fP in -Salt 0.17.x and older) to specify a different environment. -.sp -This function does not support topfiles. For \fBtop.sls\fP please use -\fBshow_top\fP instead. -.sp -Custom Pillar data can be passed with the \fBpillar\fP kwarg. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.show_sls core,edit.vim dev -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.show_top(queue=False, **kwargs) -Return the top data that the minion will use for a highstate -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.show_top -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.single(fun, name, test=None, queue=False, **kwargs) -Execute a single state function with the named kwargs, returns False if -insufficient data is sent to the command -.sp -By default, the values of the kwargs will be parsed as YAML. So, you can -specify lists values, or lists of single entry key\-value maps, as you -would in a YAML salt file. Alternatively, JSON format of keyword values -is also supported. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.single pkg.installed name=vim -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.sls(mods, saltenv=None, test=None, exclude=None, queue=False, env=None, pillarenv=None, **kwargs) -Execute a set list of state files from an environment. -.INDENT 7.0 -.TP -.B test -Notify states to execute in test\-only (dry\-run) mode. -.sp -Sets the \fBtest\fP variable in the minion \fBopts\fP for the duration of -the state run. -.TP -.B pillar -Custom Pillar data can be passed with the \fBpillar\fP kwarg. Values -passed here will override hard\-coded Pillar values. -.TP -.B queue -\fBFalse\fP -Instead of failing immediately when another state run is in progress, -queue the new state run to begin running once the other has finished. -.sp -This option starts a new thread for each queued state run so use this -option sparingly. -.TP -.B saltenv -None -Specify a \fBfile_roots\fP environment. -.sp -Changed in version 0.17.0: Argument name changed from \fBenv\fP to \fBsaltenv\fP\&. - -.sp -Changed in version 2014.7: Defaults to None. If no saltenv is specified, the minion config will -be checked for a saltenv and if found, it will be used. If none is found, -base will be used. - -.TP -.B pillarenv -None -Specify a \fBpillar_roots\fP environment. By default all pillar environments -merged together will be used. -.TP -.B concurrent: -WARNING: This flag is potentially dangerous. It is designed -for use when multiple state runs can safely be run at the same -Do not use this flag for performance optimization. -.TP -.B localconfig: -Instead of using running minion opts, load \fBlocalconfig\fP and merge that -with the running minion opts. This functionality is intended for using -"roots" of salt directories (with their own minion config, pillars, -file_roots) to run highstate out of. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.sls core,edit.vim dev -salt \(aq*\(aq state.sls core exclude="[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]" - -salt \(aq*\(aq state.sls myslsfile pillar="{foo: \(aqFoo!\(aq, bar: \(aqBar!\(aq}" -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.sls_id(id_, mods, saltenv=\(aqbase\(aq, test=None, queue=False, **kwargs) -Call a single ID from the named module(s) and handle all requisites -.sp -New in version 2014.7.0. - -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.sls_id apache http -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.template(tem, queue=False, **kwargs) -Execute the information stored in a template file on the minion. -.sp -This function does not ask a master for a SLS file to render but -instead directly processes the file at the provided path on the minion. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.template \(aq\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.state.template_str(tem, queue=False, **kwargs) -Execute the information stored in a string from an sls template -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.template_str \(aq