.TH "SALT" "7" "August 27, 2011" "0.9.0" "Salt" .SH NAME salt \- Salt Documentation . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .\" Man page generated from reStructeredText. . Salt is a powerful remote execution manager that can be used to administer servers in a fast and efficient way. .sp Salt allows commands to be executed across large groups of servers. This means systems can be easily managed, but data can also be easily gathered. Quick introspection into running systems becomes a reality. .sp Remote execution is usually used to set up a certain state on a remote system. Salt addresses this problem as well, the salt state system uses salt state files to define the state a server needs to be in. .sp Between the remote execution system, and state management Salt addresses the backbone of cloud and data center management. .sp 0.8.9 released! .sp Release announcement: .SH SALT 0.8.9 RELEASE NOTES .sp Salt 0.8.9 has finally arrived! Unfortunately this is much later than I had hoped to release 0.8.9, life has been very crazy over the last month. But despite challenges, Salt has moved forward! .sp This release, as expected, adds few new features and many refinements. One of the most exciting aspect of this release is that the development community for salt has grown a great deal and much of the code is from contributors. .sp Also, I have filled out the documentation a great deal. So information on States is properly documented, and much of the documentation that was out of date has been filled in. .SS Download! .sp The Salt source can be downloaded from the salt github site: .sp \fI\%https://github.com/downloads/thatch45/salt/salt-0.8.9.tar.gz\fP .sp Or from PiPy: .sp \fI\%http://pypi.python.org/packages/source/s/salt/salt-0.8.9.tar.gz\fP .sp Here s the md5sum: .sp 7d5aca4633bc22f59045f59e82f43b56 .sp For instructions on how to set up Salt please see the tutorial .SS Tutorial .sp The Salt system setup is amazingly simple, as this is one of the central design goals of Salt. Setting up Salt only requires that the Salt \fImaster\fP be running and the Salt \fIminions\fP point to the master. .INDENT 0.0 .TP .B master The Salt master is the central server that all minions connect to. You run commands on the minions through the master and minions send data back to the master (unless otherwise redirected with a \fBreturner\fP). It is started with the \fBsalt\-master\fP program. .TP .B minion Salt minions are the potentially hundreds or thousands of servers that you query and control from the master. .UNINDENT .SS Installing Salt .sp As of this writing packages for Salt only exist for Arch Linux, but rpms and debs will be available in the future (contributions welcome). .SS Instructions by operating system .INDENT 0.0 .IP \(bu 2 \fI\%Installing on Arch Linux\fP .IP \(bu 2 \fI\%Installing on Debian or Ubuntu\fP .IP \(bu 2 \fI\%Installing from the source tarball\fP .UNINDENT .SS Installing on Arch Linux .sp The Arch Linux Salt package is available in the Arch Linux AUR (if you like Salt vote for it on the Arch Linux AUR): .sp \fI\%https://aur.archlinux.org/packages.php?ID=47512\fP .sp For help using packages in the Arch Linux AUR: .sp \fI\%https://wiki.archlinux.org/index.php/AUR\fP .SS Installing on Debian or Ubuntu .sp Providing a .deb installer is on our short\-list of things to do; until then this is the best way to install Salt on Debian and Ubuntu systems: .INDENT 0.0 .IP 1. 3 Install the prerequisite packages: .sp .nf .ft C aptitude install python\-setuptools python\-yaml python\-crypto python\-m2crypto cython libzmq\-dev .ft P .fi .IP Note Installing on Ubuntu Lucid (10.04 LTS) .sp The ZeroMQ package is available starting with Maverick but it is not yet available in Lucid backports. Fortunately, Chris Lea has made a \fI\%ZeroMQ PPA\fP available. Install it before installing Salt: .sp .nf .ft C aptitude install python\-software\-properties add\-apt\-repository ppa:chris\-lea/zeromq aptitude update aptitude install libzmq\-dev .ft P .fi .RE .IP 2. 3 Grab the latest Python ZeroMQ bindings: .sp .nf .ft C easy_install pyzmq .ft P .fi .IP 3. 3 Install Salt: .sp .nf .ft C easy_install \-\-install\-layout=deb https://github.com/downloads/thatch45/salt/salt\-0.9.0\&.tar.gz .ft P .fi .sp Please take note of the \fB\-\-install\-layout=deb\fP flag. This is important for a functioning installation of Salt. .UNINDENT .SS Installing from the source tarball .INDENT 0.0 .IP 1. 3 Download the latest source tarball from the GitHub downloads directory for the Salt project: \fI\%https://github.com/thatch45/salt/downloads\fP .IP 2. 3 Untar the tarball and run the \fBsetup.py\fP as root: .UNINDENT .sp .nf .ft C tar xvf salt\-0.9.0\&.tar.gz cd salt\-0.9.0 python2 setup.py install .ft P .fi .SS Salt dependencies .sp This is a basic Python setup, nothing fancy. Salt does require a number of dependencies though, all of which should be available in your distribution\(aqs packages. .INDENT 0.0 .IP \(bu 2 \fI\%Python 2.6\fP .IP \(bu 2 \fI\%pyzmq\fP \- ZeroMQ Python bindings .IP \(bu 2 \fI\%M2Crypto\fP \- Python OpenSSL wrapper .IP \(bu 2 \fI\%YAML\fP \- Python YAML bindings .IP \(bu 2 \fI\%PyCrypto\fP \- The Python cryptography toolkit .UNINDENT .sp Optional Dependencies: .INDENT 0.0 .IP \(bu 2 gcc \- dynamic \fI\%Cython\fP module compiling .UNINDENT .SS Configuring Salt .sp Salt configuration is very simple. The default configuration for the \fImaster\fP will work for most installations and the only requirement for setting up a \fIminion\fP is to set the location of the master in the minion configuration file. The configuration files will be installed to \fB/etc/salt\fP and are named after the respective components, \fB/etc/salt/master\fP and \fB/etc/salt/minion\fP. .sp To make a minion check into the correct master simply edit the \fBmaster\fP variable in the minion configuration file to reference the master DNS name or IPv4 address. .IP "See also" .sp For further information consult the \fBconfiguration guide\fP. .RE .SS Running Salt .INDENT 0.0 .IP 1. 3 Start the \fImaster\fP in the foreground (to daemonize the process, pass the \fI\-d flag\fP): .sp .nf .ft C salt\-master .ft P .fi .IP 2. 3 Start the \fIminion\fP in the foreground (to daemonize the process, pass the \fI\-d flag\fP): .sp .nf .ft C salt\-minion .ft P .fi .UNINDENT .IP "See also" .sp \fBsalt\-master manpage\fP and \fBsalt\-minion manpage\fP .RE .SS Arch Linux init scripts .sp .nf .ft C /etc/rc.d/salt\-master start /etc/rc.d/salt\-minion start .ft P .fi .SS Manage Salt public keys .sp Salt manages authentication with RSA public keys. The keys are managed on the \fImaster\fP via the \fBsalt\-key\fP command. Once a \fIminion\fP checks into the master the master will save a copy of the minion key. Before the master can send commands to the minion the key needs to be "accepted". .INDENT 0.0 .IP 1. 3 List the accepted and unaccepted salt keys: .sp .nf .ft C salt\-key \-L .ft P .fi .IP 2. 3 Accept a minion key: .sp .nf .ft C salt\-key \-a .ft P .fi .sp or accept all unaccepted minion keys: .sp .nf .ft C salt\-key \-A .ft P .fi .UNINDENT .IP "See also" .sp \fBsalt\-key manpage\fP .RE .SS Order your minions around .sp Now that you have a \fImaster\fP and at least one \fIminion\fP communicating with each other you can perform commands on the minion via the \fBsalt\fP command. Salt calls are comprised of three main components: .sp .nf .ft C salt \(aq\(aq [arguments] .ft P .fi .IP "See also" .sp \fBsalt manpage\fP .RE .SS target .sp The target component allows you to filter which minions should run the following function. The default filter is a glob on the minion id. E.g.: .sp .nf .ft C salt \(aq*\(aq test.ping salt \(aq*.example.org\(aq test.ping .ft P .fi .sp Targets can be based on minion system information using the grains system: .sp .nf .ft C salt \-G \(aqos:Ubuntu\(aq test.ping .ft P .fi .IP "See also" .sp \fBGrains system\fP .RE .sp Targets can be filtered by regular expression: .sp .nf .ft C salt \-E \(aqvirtmach[0\-9]\(aq test.ping .ft P .fi .sp Finally, targets can be explicitly specified in a list: .sp .nf .ft C salt \-L foo,bar,baz,quo test.ping .ft P .fi .SS function .sp A function is some functionality provided by a module. Salt ships with a large collection of available functions. List all available functions on your minions: .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .sp Here are some examples: .sp Show all currently available minions: .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .sp Run an arbitrary shell command: .sp .nf .ft C salt \(aq*\(aq cmd.run \(aquname \-a\(aq .ft P .fi .IP "See also" .sp \fBthe full list of modules\fP .RE .SS arguments .sp Space\-delimited arguments to the function: .sp .nf .ft C salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq .ft P .fi .SS New Features .SS Salt Run .sp A big feature is the addition of Salt run, the \fBsalt\-run\fP command allows for master side execution modules to be made that gather specific information or execute custom routines from the master. .sp Documentation for salt\-run can be found here: .sp \fI\%http://saltstack.org/ref/runners.html\fP .SS Refined Outputters .sp One problem often complained about in salt was the fact that the output was so messy. Thanks to help from Jeff Schroeder a cleaner interface for the command output for the Salt cli has been made. This new interface makes adding new printout formats easy and additions to the capabilities of minion modules makes it possible to set the printout mode or \fBoutputter\fP for functions in minion modules. .SS Cross Calling Salt Modules .sp Salt modules can now call each other, the \fB__salt__\fP dict has been added to the predefined references in minion modules. This new feature is documented in the modules documentation: .sp \fI\%http://saltstack.org/ref/modules/index.html\fP .SS Watch Option Added to Salt State System .sp Now in Salt states you can set the watch option, this will allow watch enabled states to change based on a change in the other defined states. This is similar to subscribe and notify statements in puppet. .SS Root Dir Option .sp Travis Cline has added the ability to define the option \fBroot_dir\fP which allows the salt minion to operate in a subdir. This is a strong move in supporting the minion running as an unprivileged user .SS Config Files Defined in Variables .sp Thanks again to Travis Cline, the master and minion configuration file locations can be defined in environment variables now. .SS New Modules .sp Quite a few new modules, states, returners and runners have been made. .SS New Minion Modules .SS apt .sp Support for apt\-get has been added, this adds greatly improved Debian and Ubuntu support to Salt! .SS useradd and groupadd .sp Support for manipulating users and groups on Unix\-like systems. .SS moosefs .sp Initial support for reporting on aspects of the distributed file system, MooseFS. For more information on MooseFS please see: \fI\%http://moosefs.org\fP .sp Thanks to Joseph Hall for his work on MooseFS support. .SS mount .sp Manage mounts and the fstab. .SS puppet .sp Execute puppet on remote systems. .SS shadow .sp Manipulate and manage the user password file. .SS ssh .sp Interact with ssh keys. .SS New States .SS user and group .sp Support for managing users and groups in Salt States. .SS mount .sp Enforce mounts and the fstab. .SS New Returners .SS mongo_return .sp Send the return information to a mongodb server. .SS New Runners .SS manage .sp Display minions that are up or down. .sp The latest Salt is 0.8.9: .sp \fI\%https://github.com/downloads/thatch45/salt/salt-0.8.9.tar.gz\fP .sp Additional packages can be downloaded from the download page: .SH DOWNLOAD SALT .sp Packages and dependencies for Salt can be downloaded here for specific operating systems. Please follow and specific instructions for your system. .SS Salt From Source .sp The Salt source can be downloaded and installed directly from git: .sp .nf .ft C # git clone git://github.com/thatch45/salt.git .ft P .fi .sp The latest source tarball can be downloaded as well: .sp \fI\%https://github.com/downloads/thatch45/salt/salt-0.8.9.tar.gz\fP .sp Salt should run on any Unix like platform so long as the dependencies are met. .SS Salt for Red Hat .sp Salt rpms have been prepared for Red Hat Enterprise Linux 6 and Fedora 15. While Fedora 15 only requires the Salt rpm Red Hat Enterprise Linux 6 requires that a newer version of ZeroMQ be installed than what is available in the EPEL repositories. .SS Fedora rpms .sp Salt noarch rpm for Fedora 15: .sp \fI\%https://github.com/downloads/thatch45/salt/salt-0.8.9-1.fc15.noarch.rpm\fP .SS Red Hat Enterprise Linux 6 rpms .sp The EPEL repository is required for Salt as well as updated ZeroMQ packages. .sp The Salt rpm can be downloaded here: .sp \fI\%https://github.com/downloads/thatch45/salt/salt-0.8.9-1.el6.noarch.rpm\fP .sp ZeroMQ backport: .sp \fI\%https://github.com/downloads/thatch45/salt/zeromq-2.1.7-1.el6.x86_64.rpm\fP .sp PyZMQ bindings backport: .sp \fI\%https://github.com/downloads/thatch45/salt/python-zmq-2.1.7-1.el6.src.rpm\fP .sp Package to set up EPEL repository (provided by the EPEL project): .sp \fI\%http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-5.noarch.rpm\fP .SS Red Hat Enterprise Linux 5 rpms .sp Red Hat Enterprise Linux 5 requires more backports and the use of the python 2.6 stack provided in the EPEL repository. All of the listed packages need to be installed and the EPEL repository enabled to bring in the needed dependencies: .sp Salt rpm: .sp \fI\%https://github.com/downloads/thatch45/salt/salt-0.8.9-1.el5.noarch.rpm\fP .sp YAML bindings for python 2.6: .sp \fI\%https://github.com/downloads/thatch45/salt/python26-PyYAML-3.08-4.el5.x86_64.rpm\fP .sp ZeroMQ backport: .sp \fI\%https://github.com/downloads/thatch45/salt/zeromq-2.1.7-1.el5.x86_64.rpm\fP .sp PyZMQ bindings backport: .sp \fI\%https://github.com/downloads/thatch45/salt/python26-zmq-2.1.7-1.el5.x86_64.rpm\fP .SS Salt for Arch Linux .sp Salt can be easily installed on Arch Linux, install the package from the Arch Linux AUR: .sp \fI\%https://aur.archlinux.org/packages.php?ID=47512\fP .sp Or install directly from git on Arch Linux: .sp \fI\%https://aur.archlinux.org/packages.php?ID=47513\fP .SH GETTING STARTED .sp A number of resources are available to get going with Salt. .sp If you want to get set up quickly and try out Salt, follow the tutorial. .SH TUTORIAL .sp The Salt system setup is amazingly simple, as this is one of the central design goals of Salt. Setting up Salt only requires that the Salt \fImaster\fP be running and the Salt \fIminions\fP point to the master. .INDENT 0.0 .TP .B master The Salt master is the central server that all minions connect to. You run commands on the minions through the master and minions send data back to the master (unless otherwise redirected with a \fBreturner\fP). It is started with the \fBsalt\-master\fP program. .TP .B minion Salt minions are the potentially hundreds or thousands of servers that you query and control from the master. .UNINDENT .SS Installing Salt .sp As of this writing packages for Salt only exist for Arch Linux, but rpms and debs will be available in the future (contributions welcome). .SS Instructions by operating system .INDENT 0.0 .IP \(bu 2 \fI\%Installing on Arch Linux\fP .IP \(bu 2 \fI\%Installing on Debian or Ubuntu\fP .IP \(bu 2 \fI\%Installing from the source tarball\fP .UNINDENT .SS Installing on Arch Linux .sp The Arch Linux Salt package is available in the Arch Linux AUR (if you like Salt vote for it on the Arch Linux AUR): .sp \fI\%https://aur.archlinux.org/packages.php?ID=47512\fP .sp For help using packages in the Arch Linux AUR: .sp \fI\%https://wiki.archlinux.org/index.php/AUR\fP .SS Installing on Debian or Ubuntu .sp Providing a .deb installer is on our short\-list of things to do; until then this is the best way to install Salt on Debian and Ubuntu systems: .INDENT 0.0 .IP 1. 3 Install the prerequisite packages: .sp .nf .ft C aptitude install python\-setuptools python\-yaml python\-crypto python\-m2crypto cython libzmq\-dev .ft P .fi .IP Note Installing on Ubuntu Lucid (10.04 LTS) .sp The ZeroMQ package is available starting with Maverick but it is not yet available in Lucid backports. Fortunately, Chris Lea has made a \fI\%ZeroMQ PPA\fP available. Install it before installing Salt: .sp .nf .ft C aptitude install python\-software\-properties add\-apt\-repository ppa:chris\-lea/zeromq aptitude update aptitude install libzmq\-dev .ft P .fi .RE .IP 2. 3 Grab the latest Python ZeroMQ bindings: .sp .nf .ft C easy_install pyzmq .ft P .fi .IP 3. 3 Install Salt: .sp .nf .ft C easy_install \-\-install\-layout=deb https://github.com/downloads/thatch45/salt/salt\-0.9.0\&.tar.gz .ft P .fi .sp Please take note of the \fB\-\-install\-layout=deb\fP flag. This is important for a functioning installation of Salt. .UNINDENT .SS Installing from the source tarball .INDENT 0.0 .IP 1. 3 Download the latest source tarball from the GitHub downloads directory for the Salt project: \fI\%https://github.com/thatch45/salt/downloads\fP .IP 2. 3 Untar the tarball and run the \fBsetup.py\fP as root: .UNINDENT .sp .nf .ft C tar xvf salt\-0.9.0\&.tar.gz cd salt\-0.9.0 python2 setup.py install .ft P .fi .SS Salt dependencies .sp This is a basic Python setup, nothing fancy. Salt does require a number of dependencies though, all of which should be available in your distribution\(aqs packages. .INDENT 0.0 .IP \(bu 2 \fI\%Python 2.6\fP .IP \(bu 2 \fI\%pyzmq\fP \- ZeroMQ Python bindings .IP \(bu 2 \fI\%M2Crypto\fP \- Python OpenSSL wrapper .IP \(bu 2 \fI\%YAML\fP \- Python YAML bindings .IP \(bu 2 \fI\%PyCrypto\fP \- The Python cryptography toolkit .UNINDENT .sp Optional Dependencies: .INDENT 0.0 .IP \(bu 2 gcc \- dynamic \fI\%Cython\fP module compiling .UNINDENT .SS Configuring Salt .sp Salt configuration is very simple. The default configuration for the \fImaster\fP will work for most installations and the only requirement for setting up a \fIminion\fP is to set the location of the master in the minion configuration file. The configuration files will be installed to \fB/etc/salt\fP and are named after the respective components, \fB/etc/salt/master\fP and \fB/etc/salt/minion\fP. .sp To make a minion check into the correct master simply edit the \fBmaster\fP variable in the minion configuration file to reference the master DNS name or IPv4 address. .IP "See also" .sp For further information consult the \fBconfiguration guide\fP. .RE .SS Running Salt .INDENT 0.0 .IP 1. 3 Start the \fImaster\fP in the foreground (to daemonize the process, pass the \fI\-d flag\fP): .sp .nf .ft C salt\-master .ft P .fi .IP 2. 3 Start the \fIminion\fP in the foreground (to daemonize the process, pass the \fI\-d flag\fP): .sp .nf .ft C salt\-minion .ft P .fi .UNINDENT .IP "See also" .sp \fBsalt\-master manpage\fP and \fBsalt\-minion manpage\fP .RE .SS Arch Linux init scripts .sp .nf .ft C /etc/rc.d/salt\-master start /etc/rc.d/salt\-minion start .ft P .fi .SS Manage Salt public keys .sp Salt manages authentication with RSA public keys. The keys are managed on the \fImaster\fP via the \fBsalt\-key\fP command. Once a \fIminion\fP checks into the master the master will save a copy of the minion key. Before the master can send commands to the minion the key needs to be "accepted". .INDENT 0.0 .IP 1. 3 List the accepted and unaccepted salt keys: .sp .nf .ft C salt\-key \-L .ft P .fi .IP 2. 3 Accept a minion key: .sp .nf .ft C salt\-key \-a .ft P .fi .sp or accept all unaccepted minion keys: .sp .nf .ft C salt\-key \-A .ft P .fi .UNINDENT .IP "See also" .sp \fBsalt\-key manpage\fP .RE .SS Order your minions around .sp Now that you have a \fImaster\fP and at least one \fIminion\fP communicating with each other you can perform commands on the minion via the \fBsalt\fP command. Salt calls are comprised of three main components: .sp .nf .ft C salt \(aq\(aq [arguments] .ft P .fi .IP "See also" .sp \fBsalt manpage\fP .RE .SS target .sp The target component allows you to filter which minions should run the following function. The default filter is a glob on the minion id. E.g.: .sp .nf .ft C salt \(aq*\(aq test.ping salt \(aq*.example.org\(aq test.ping .ft P .fi .sp Targets can be based on minion system information using the grains system: .sp .nf .ft C salt \-G \(aqos:Ubuntu\(aq test.ping .ft P .fi .IP "See also" .sp \fBGrains system\fP .RE .sp Targets can be filtered by regular expression: .sp .nf .ft C salt \-E \(aqvirtmach[0\-9]\(aq test.ping .ft P .fi .sp Finally, targets can be explicitly specified in a list: .sp .nf .ft C salt \-L foo,bar,baz,quo test.ping .ft P .fi .SS function .sp A function is some functionality provided by a module. Salt ships with a large collection of available functions. List all available functions on your minions: .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .sp Here are some examples: .sp Show all currently available minions: .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .sp Run an arbitrary shell command: .sp .nf .ft C salt \(aq*\(aq cmd.run \(aquname \-a\(aq .ft P .fi .IP "See also" .sp \fBthe full list of modules\fP .RE .SS arguments .sp Space\-delimited arguments to the function: .sp .nf .ft C salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq .ft P .fi .SH SALT IN DEPTH .sp While using and setting up Salt is a simple task, the capabilities of Salt run much deeper. .sp Gaining a better understanding of how Salt works will allow you to get much more out of Salt. .sp Presentation at SLLUG in May 2011 \fI\%video\fP | \fI\%slides\fP (PDF) .SH CONFIGURATION GUIDE .sp The Salt system is amazingly simple and easy to configure, the two components of the Salt system each have a respective configuration file. The \fBsalt\-master\fP is configured via the master configuration file, and the \fBsalt\-minion\fP is configured via the minion configuration file. .SS Configuration file examples .INDENT 0.0 .IP \(bu 2 \fI\%Example master configuration file\fP .IP \(bu 2 \fI\%Example minion configuration file\fP .UNINDENT .SS Example master configuration file .sp .nf .ft C ##### Primary configuration settings ##### ########################################## # The address of the interface to bind to #interface: 0.0.0.0 # The port used by the publisher #publish_port: 4505 # The number of worker threads to start, these threads are used to manage # return calls made from minions to the master, if the master seems to be # running slowly, increase the number of threads #worker_threads: 5 # The port used by the communication interface #ret_port: 4506 # The root directory prepended to these options: pki_dir, cachedir, log_file. #root_dir: / # Directory used to store public key data #pki_dir: /etc/salt/pki # Directory to store job and cache data #cachedir: /var/cache/salt # Set the number of hours to keep old job information #keep_jobs: 24 # Set the directory used to hold unix sockets #sock_dir: /tmp/salt\-unix ##### Security settings ##### ########################################## # Enable "open mode", this mode still maintains encryption, but turns off # authentication, this is only intended for highly secure environments or for # the situation where your keys end up in a bad state. If you run in open more # you do so at your own risk! #open_mode: False # Enable auto_accept, this setting will automatically accept all incoming # public keys from the minions #auto_accept: False ##### State System settings ##### ########################################## # The state system uses a "top" file to tell the minions what environment to # use and what modules to use. The state_top file is defined relative to the # root of the base environment #state_top: top.yml # # The renderer to use on the minions to render the state data #renderer: yaml_jinja ##### File Server settings ##### ########################################## # Salt runs a lightweight file server written in zeromq to deliver files to # minions. This file server is built into the master daemon and does not # require a dedicated port. # The file server works on environments passed to the master, each environment # can have multiple root directories, the subdirectories in the multiple file # roots cannot match, otherwise the downloaded files will not be able to be # reliably ensured. A base environment is required to house the top file # Example: # file_roots: # base: # \- /srv/salt/ # dev: # \- /srv/salt/dev/services # \- /srv/salt/dev/states # prod: # \- /srv/salt/prod/services # \- /srv/salt/prod/states # # Default: #file_roots: # base: # \- /srv/salt # The hash_type is the hash to use when discovering the hash of a file on # the master server, the default is md5, but sha1, sha224, sha256, sha384 # and sha512 are also supported. #hash_type: md5 # The buffer size in the file server can be adjusted here: #file_buffer_size: 1048576 ##### Syndic settings ##### ########################################## # The Salt syndic is used to pass commands through a master from a higher # master. Using the syndic is simple, if this is a master that will have # syndic servers(s) below it set the "order_masters" setting to True, if this # is a master that will be running a syndic daemon for passthrough the # "syndic_master" setting needs to be set to the location of the master server # to recieve commands from # # Set the order_masters setting to True if this master will command lower # masters\(aq syndic interfaces #order_masters: False # # If this master will be running a salt syndic daemon, then the syndic needs # to know where the master it is recieving commands from is, set it with the # syndic_master value #syndic_master: masterofmaster ##### Peer Publish settings ##### ########################################## # Salt minions can send commands to other minions, but only if the minion is # allowed to. By default "Peer Publication" is disabled, and when enabled it # is enabled for specific minions and specific commands. This allows secure # compartmentalization of commands based on individual minions. # # The configuration uses regular expressions to match minions and then a list # of regular expressions to match functions, the following will allow the # minion authenticated as foo.example.com to execute functions from the test # and pkg modules # peer: # foo.example.com: # \- test.* # \- pkg.* # # This will allow all minions to execute all commands: # peer: # .*: # \- .* # This is not recomanded, since it would allow anyone who gets root on any # single minion to instantly have root on all of the minions! # ##### Cluster settings ##### ########################################## # Salt supports automatic clustering, salt creates a single ip address which # is shared among the individual salt components using ucarp. The private key # and all of the minion keys are maintained across the defined cluster masters # The failover service is automatically managed via these settings # List the identifiers for the other cluster masters in this manner: # [saltmaster\-01.foo.com,saltmaster\-02.foo.com,saltmaster\-03.foo.com] # The members of this master array must be running as salt minions to # facilitate the distribution of cluster information #cluster_masters: [] # The cluster modes are "paranoid" and "full" # paranoid will only distribute the accepted minion public keys. # full will also distribute the master private key. #cluster_mode: paranoid ##### Logging settings ##### ########################################## # The location of the master log file #log_file: /var/log/salt/master # The level of messages to send to the log file. # One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq. # Default: \(aqwarning\(aq #log_level: warning # # Logger levels can be used to tweak specific loggers logging levels. # Imagine you want to have the salt library at the \(aqwarning\(aq level, but, you # still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level: # log_granular_levels: { # \(aqsalt\(aq: \(aqwarning\(aq, # \(aqsalt.modules\(aq: \(aqdebug\(aq # } # #log_granular_levels: {} .ft P .fi .SS Example minion configuration file .sp .nf .ft C ##### Primary configuration settings ##### ########################################## # Set the location of the salt master server, if the master server cannot be # resolved, then the minion will fail to start #master: salt # Set the post used by the master reply and authentication server #master_port: 4506 # The root directory prepended to these options: pki_dir, cachedir, log_file. #root_dir: / # The directory to store the pki information in #pki_dir: /etc/salt/pki # Explicitly declare the id for this minion to use, if left commented the id # will be the hostname as returned by the python call: socket.getfqdn() # Since salt uses detached ids it is possible to run multiple minions on the # same machine but with different ids, this can be useful for salt compute # clusters. #id: # Where cache data goes #cachedir: /var/cache/salt ##### Minion module management ##### ########################################## # Disable specific modules, this will allow the admin to limit the level os # access the master has to the minion #disable_modules: [cmd,test] #disable_returners: [] # Modules can be loaded from arbitrary paths, this enables the easy deployment # of third party modules, modules for returners and minions can be loaded. # Specify a list of extra directories to search for minion modules and # returners. These paths must be fully qualified! #module_dirs: [] #returner_dirs: [] #states_dirs: [] #render_dirs: [] # Enable Cython modules searching and loading. (Default: True) #cython_enable: true ##### State Management Settings ##### ########################################### # The state management system executes all of the state templates on the minion # to enable more granular control of system state management. The type of # template and serialization used for state management needs to be configured # on the minion, the default renderer is yaml_jinja. This is a yaml file # rendered from a jinja template, the available options are: # yaml_jinja # yaml_mako # json_jinja # json_mako # #renderer: yaml_jinja # # Test allows for the state runs to only be test runs #test: False ###### Security settings ##### ########################################### # Enable "open mode", this mode still maintains encryption, but turns off # authentication, this is only intended for highly secure environments or for # the situation where your keys end up in a bad state. If you run in open mode # you do so at your own risk! #open_mode: False ###### Thread settings ##### ########################################### # Disable multiprocessing support, by default when a minion receives a # publication a new process is spawned and the command is executed therein. #multiprocessing: True ###### Logging settings ##### ########################################### # The location of the minion log file #log_file: /var/log/salt/minion # The level of messages to send to the log file. # One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq. # Default: \(aqwarning\(aq #log_level: warning # # Logger levels can be used to tweak specific loggers logging levels. # Imagine you want to have the salt library at the \(aqwarning\(aq level, but, you # still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level: # log_granular_levels: { # \(aqsalt\(aq: \(aqwarning\(aq, # \(aqsalt.modules\(aq: \(aqdebug\(aq # } # #log_granular_levels: {} ###### Module configuration ##### ########################################### # Salt allows for modules to be passed arbitrary configuration data, any data # passed here in valid yaml format will be passed on to the salt minion modules # for use. It is STRONGLY recommended that a naming convention be used in which # the module name is followed by a . and then the value. Also, all top level # data must be allied via the yaml dict construct, some examples: # # A simple value for the test module: #test.foo: foo # # A list for the test module: #test.bar: [baz,quo] # # A dict for the test module: #test.baz: {spam: sausage, cheese: bread} .ft P .fi .IP "See also" .sp \fIexample master configuration file\fP | \fIexample minion configuration file\fP .RE .SS Configuring the Salt Master .sp The configuration file for the salt\-master is located at \fB/etc/salt/master\fP. The available options are as follows: .SS Primary Master Configuration .SS \fBinterface\fP .sp Default: \fB0.0.0.0\fP (all interfaces) .sp The local interface to bind to. .sp .nf .ft C interface: 192.168.0.1 .ft P .fi .SS \fBpublish_port\fP .sp Default: \fB4505\fP .sp The network port to set up the publication interface .sp .nf .ft C publish_port: 4505 .ft P .fi .SS \fBpublish_pull_port\fP .sp Default: \fB45055\fP .sp The port used to communicate to the local publisher .sp .nf .ft C publish_pull_port: 45055 .ft P .fi .SS \fBworker_threads\fP .sp Default: \fB5\fP .sp The number of threads to start for receiving commands and replies from minions. If minions are stalling on replies because you have many minions, raise the worker_threads value. .sp .nf .ft C worker_threads: 5 .ft P .fi .SS \fBworker_start_port\fP .sp Default: \fB5\fP .sp The port to begin binding workers on, the workers will be created on increasingly higher ports .sp .nf .ft C worker_start_port: 45056 .ft P .fi .SS \fBret_port\fP .sp Default: \fB4506\fP .sp The port used by the return server, this is the server used by Salt to receive execution returns and command executions. .sp .nf .ft C ret_port: 4506 .ft P .fi .SS \fBpki_dir\fP .sp Default: \fB/etc/salt/pki\fP .sp The directory to store the pki authentication keys. .sp .nf .ft C pki_dir: /etc/salt/pki .ft P .fi .SS \fBcachedir\fP .sp Default: \fB/var/cache/salt\fP .sp The location used to store cache information, particularly the job information for executed salt commands. .sp .nf .ft C cachedir: /var/cache/salt .ft P .fi .SS \fBkeep_jobs\fP .sp Default: \fB24\fP .sp Set the number of hours to keep old job information .SS Master Security Settings .SS \fBopen_mode\fP .sp Default: \fBFalse\fP .sp Open mode is a dangerous security feature. One problem encountered with pki authentication systems is that keys can become "mixed up" and authentication begins to fail. Open mode turns off authentication and tells the master to accept all authentication. This will clean up the pki keys received from the minions. Open mode should not be turned on for general use, open mode should only be used for a short period of time to clean up pki keys. To turn on open mode the value passed must be \fBTrue\fP. .sp .nf .ft C open_mode: False .ft P .fi .SS \fBauto_accept\fP .sp Default: \fBFalse\fP .sp Enable auto_accept, this setting will automatically accept all incoming public keys from the minions .sp .nf .ft C auto_accept: False .ft P .fi .SS Master State System Settings .SS \fBstate_top\fP .sp Default: \fBtop.yml\fP .sp The state system uses a "top" file to tell the minions what environment to use and what modules to use. The state_top file is defined relative to the root of the base environment .sp .nf .ft C state_top: top.yml .ft P .fi .SS \fBrenderer\fP .sp Default: \fByaml_jinja\fP .sp The renderer to use on the minions to render the state data .sp .nf .ft C renderer: yaml_jinja .ft P .fi .SS Master File Server Settings .SS \fBfile_roots\fP .sp Default: \fBbase: [/srv/salt]\fP .sp Salt runs a lightweight file server written in zeromq to deliver files to minions. This file server is built into the master daemon and does not require a dedicated port. The file server works on environments passed to the master, each environment can have multiple root directories, the subdirectories in the multiple file roots cannot match, otherwise the downloaded files will not be able to be reliably ensured. A base environment is required to house the top file Example: .sp .nf .ft C file_roots: base: \- /srv/salt/ dev: \- /srv/salt/dev/services \- /srv/salt/dev/states prod: \- /srv/salt/prod/services \- /srv/salt/prod/states .ft P .fi .sp .nf .ft C base: \- /srv/salt .ft P .fi .SS \fBhash_type\fP .sp Default: \fBmd5\fP .sp The hash_type is the hash to use when discovering the hash of a file on the master server, the default is md5, but sha1, sha224, sha256, sha384 and sha512 are also supported. .sp .nf .ft C hash_type: md5 .ft P .fi .SS \fBfile_buffer_size\fP .sp Default: \fB1048576\fP .sp The buffer size in the file server in bytes .sp .nf .ft C file_buffer_size: 1048576 .ft P .fi .SS Master Logging Settings .SS \fBlog_file\fP .sp Default: \fB/etc/salt/pki\fP .sp The location of the master log file .sp .nf .ft C log_file: /var/log/salt/master .ft P .fi .SS \fBlog_level\fP .sp Default: \fBwarning\fP .sp The level of messages to send to the log file. One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq. .sp .nf .ft C log_level: warning .ft P .fi .SS \fBlog_granular_levels\fP .sp Default: \fB{}\fP .sp Logger levels can be used to tweak specific loggers logging levels. Imagine you want to have the salt library at the \(aqwarning\(aq level, but, you still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level: .sp .nf .ft C log_granular_levels: { \(aqsalt\(aq: \(aqwarning\(aq, \(aqsalt.modules\(aq: \(aqdebug\(aq } .ft P .fi .SS Configuring the Salt Minion .sp The Salt Minion configuration is very simple, typically the only value that needs to be set is the master value so the minion can find its master. .SS Minion Primary Configuration .SS \fBmaster\fP .sp Default: \fBsalt\fP .sp The hostname or ipv4 of the master. .sp .nf .ft C master: salt .ft P .fi .SS \fBmaster_port\fP .sp Default: \fB4506\fP .sp The port of the master ret server, this needs to coincide with the ret_port option on the salt master. .sp .nf .ft C master_port: 4506 .ft P .fi .SS \fBpki_dir\fP .sp Default: \fB/etc/salt/pki\fP .sp The directory used to store the minion\(aqs public and private keys. .sp .nf .ft C pki_dir: /etc/salt/pki .ft P .fi .SS \fBid\fP .sp Default: hostname (as returned by the Python call: \fBsocket.getfqdn()\fP) .sp Explicitly declare the id for this minion to use, if left commented the id will be the hostname as returned by the python call: socket.getfqdn() Since salt uses detached ids it is possible to run multiple minions on the same machine but with different ids, this can be useful for salt compute clusters. .sp .nf .ft C id: foo.bar.com .ft P .fi .SS \fBcachedir\fP .sp Default: \fB/var/cache/salt\fP .sp The location for minion cache data. .sp .nf .ft C cachedir: /var/cache/salt .ft P .fi .SS Minion Module Management .SS \fBdisable_modules\fP .sp Default: \fB[]\fP (all modules are enabled by default) .sp The event may occur in which the administrator desires that a minion should not be able to execute a certain module. The sys module is built into the minion and cannot be disabled. .sp .nf .ft C disable_modules: [cmd,virt,test] .ft P .fi .SS \fBopen_mode\fP .sp Default: \fBFalse\fP .sp Open mode can be used to clean out the pki key received from the salt master, turn on open mode, restart the minion, then turn off open mode and restart the minion to clean the keys. .sp .nf .ft C open_mode: False .ft P .fi .SH COMMAND LINE REFERENCE .SS \fBsalt\fP .SS Synopsis .INDENT 0.0 .INDENT 3.5 salt \(aq*\(aq [ options ] sys.doc .sp salt \-E \(aq.*\(aq [ options ] sys.doc cmd .sp salt \-F \(aqoperatingsystem:Arch.*\(aq [ options ] test.ping .sp salt \-Q test.ping .UNINDENT .UNINDENT .SS Description .sp Salt allows for commands to be executed across a swath of remote systems in parallel. This means that remote systems can be both controlled and queried with ease. .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options .UNINDENT .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT The timeout in seconds to wait for replies from the salt minions. .UNINDENT .INDENT 0.0 .TP .B \-E, \-\-pcre The target expression will be interpreted as a pcre regular expression rather than a shell glob. .UNINDENT .INDENT 0.0 .TP .B \-L, \-\-list The target expression will be interpreted as a comma delimited list, example: server1.foo.bar,server2.foo.bar,example7.quo.qux .UNINDENT .INDENT 0.0 .TP .B \-G, \-\-grain The target expression matches values returned by the salt grains system on the minions. The target expression is in the format of \(aq:\(aq; example: \(aqos:Arch.*\(aq .UNINDENT .INDENT 0.0 .TP .B \-Q, \-\-query Execute a salt command query, this can be used to find the results os a previous function call: \-Q test.echo\(aq) .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The location of the salt master configuration file, the salt master settings are required to know where the connections are; default=/etc/salt/master .UNINDENT .SS See also .sp \fIsalt(7)\fP \fIsalt\-master(1)\fP \fIsalt\-minion(1)\fP .SS \fBsalt\-master\fP .sp The salt master daemon, used to control the salt minions .SS Synopsis .sp salt\-master [ options ] .SS Description .sp The master daemon controls the salt minions .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run the salt master as a daemon .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The master configuration file to use, the default is /etc/salt/master .UNINDENT .SS \fBsalt\-minion\fP .sp The salt minion daemon, receives commands from a remote salt master. .SS Synopsis .sp salt\-minion [ options ] .SS Description .sp The salt minion receives commands from the central salt master and replies with the results of said commands. .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run the salt minion as a daemon .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The minion configuration file to use, the default is /etc/salt/minion .UNINDENT .SS \fBsalt\-key\fP .SS Synopsis .sp salt\-key [ options ] .SS Description .sp Salt\-key executes simple management of salt server public keys used for authentication. .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options. .UNINDENT .INDENT 0.0 .TP .B \-l, \-\-list List the unaccepted minion public keys. .UNINDENT .INDENT 0.0 .TP .B \-L, \-\-list\-all List all public keys on this salt master, both accepted and pending acceptance. .UNINDENT .INDENT 0.0 .TP .B \-a ACCEPT, \-\-accept=ACCEPT Accept the named minion public key for command execution. .UNINDENT .INDENT 0.0 .TP .B \-A, \-\-accept\-all Accepts all pending public keys. .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The master configuration file needs to be read to determine where the salt keys are stored via the pki_dir configuration value; default=/etc/salt/master .UNINDENT .SS \fBsalt\-cp\fP .sp Copy a file to a set of systems .SS Synopsis .sp .nf .ft C salt\-cp \(aq*\(aq [ options ] SOURCE DEST salt\-cp \-E \(aq.*\(aq [ options ] SOURCE DEST salt\-cp \-G \(aqos:Arch.*\(aq [ options ] SOURCE DEST .ft P .fi .SS Description .sp Salt copy copies a local file out to all of the salt minions matched by the given target. .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options .UNINDENT .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT The timeout in seconds to wait for replies from the salt minions. .UNINDENT .INDENT 0.0 .TP .B \-E, \-\-pcre The target expresion will be interpereted as a pcre regular expression rather than a shell glob. .UNINDENT .INDENT 0.0 .TP .B \-L, \-\-list The target expression will be interpereted as a comma delimited list, example: server1.foo.bar,server2.foo.bar,example7.quo.qux .UNINDENT .INDENT 0.0 .TP .B \-G, \-\-grain The target expression matches values returned by the salt grains system on the minions. The target expresion is in the format of \(aq:\(aq; example: \(aqos:Arch.*\(aq .UNINDENT .INDENT 0.0 .TP .B \-Q, \-\-query Execute a salt command query, this can be used to find the results os a previous function call: \-Q test.echo\(aq) .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The location of the salt master configuration file, the salt master settings are required to know where the connections are; default=/etc/salt/master .UNINDENT .SS \fBsalt\-call\fP .SS Synopsis .sp .nf .ft C salt\-call [options] .ft P .fi .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options .UNINDENT .INDENT 0.0 .TP .B \-g, \-\-grains Return the information generated by the salt grains .UNINDENT .INDENT 0.0 .TP .B \-m MODULE_DIRS, \-\-module\-dirs=MODULE_DIRS Specify an additional directories to pull modules from, multiple directories can be delimited by commas .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-doc Return the documentation for the specified module of for all modules if none are specified .UNINDENT .sp Salt can be controlled by a command line client by the root user on the Salt master. The Salt command line client uses the Salt client API to communicate with the Salt master server. The Salt client is straightforward and simple to use. .sp Using the Salt client commands can be easily sent to the minions. .sp Each of these commands accepts an explicit \fI\-\-config\fP option to point to either the master or minion configuration file. If this option is not provided and the default configuration file does not exist then Salt falls back to use the environment variables \fBSALT_MASTER_CONFIG\fP and \fBSALT_MINION_CONFIG\fP. .IP "See also" .sp \fB../configuration/index\fP .RE .SS Using the Salt Command .sp The Salt command needs a few components to send information to the salt minions. The target minions need to be defined, the function to call and any arguments the function requires. .SS Defining the Target Minions .sp The first argument passed to salt, defines the target minions, the target minions are accessed via their hostname. The default target type is a bash glob: .sp .nf .ft C salt \(aq*foo.com\(aq sys.doc .ft P .fi .sp Salt can also define the target minions with regular expressions: .sp .nf .ft C salt \-E \(aq.*\(aq cmd.run \(aqls \-l | grep foo\(aq .ft P .fi .sp Or to explicitly list hosts, salt can take a list: .sp .nf .ft C salt \-L foo.bar.baz,quo.qux cmd.run \(aqps aux | grep foo\(aq .ft P .fi .SS More Powerful Targets .sp The simple target specifications, glob, regex and list will cover many use cases, and for some will cover all use cases, but more powerful options exist. .SS Targeting with Grains .sp The Grains interface was built into Salt to allow minions to be targeted by system properties. So minions running on a particular operating system can be called to execute a function, or a specific kernel. .sp Calling via a grain is done by passing the \-G option to salt, specifying a grain and a regular expression to match the value of the grain. .sp .nf .ft C salt \-G \(aqos:Fedora\(aq test.ping .ft P .fi .sp Will return True from all of the minions running Fedora. .sp To discover what grains are available and what the values are, execute the grains.item salt function: .sp .nf .ft C salt \(aq*\(aq grains.items .ft P .fi .SS Targeting with Executions .sp As of 0.8.8 targeting with executions is still under heavy development and this documentation is written to refernce the behavior of execution matching in the future. .sp Execution matching allows for a primary function to be executed, and then based on the return of the primary function the main function is executed. .sp Execution matching allows for matching minions based on any arbitrairy running data on tne minions. .SS Calling the Function .sp The function to call on the specified target is placed after the target specification. .SS Finding available minion functions .sp The Salt functions are self documenting, all of the function documentation can be retried from the minions via the \fBsys.doc()\fP function: .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .SS Compound Command Execution .sp If a series of commands need to be sent to a single target specification then the multiple commands can be send in a single publish. This can make gathering groups of information faster, and lowers the stress on the network for repeated commands. .sp Compound command execution works by sending a list of functions and arguments instead of sending a single function and argument. The functions are executed on the minion in the order they are defined on the command line, and then the data from all of the commands are returned in a dictionary. This means that the set of commands are called in a predictable way, and the returned data can be easily interpreted. .sp Executing compound commands if done by passing a comma delimited list of functions, followed by a comma delimited list of arguments: .sp .nf .ft C salt \(aq*\(aq cmd.run,test.ping,test.echo \(aqcat /proc/cpuinfo\(aq,,foo .ft P .fi .sp The trick to look out for here, is that if a function is being passed no arguments, then there needs to be a placeholder for the absent arguments. This is why in the above example, there are two commas right next to each other. \fBtest.ping\fP takes no arguments, so we need to add another comma, otherwise Salt would attempt to pass "foo" to \fBtest.ping\fP. .SH EXTENDING SALT .sp Writing your own customizations on top of Salt .SS Introduction to Extending Salt .sp Salt is made to be used, and made to be extended. The primary goal of Salt is to provide a foundation which can be used to solve problems. And the goal of Salt is to not assume what those problems might be. .sp One of the greatest benefit of developing Salt has been the vast array of ways in which people have wanted to use it, while the original intention was as a communication layer for a cloud controller Salt has been extended to facilitate so much more. .SS Client API .sp The primary interface used to extend salt, is to simply use it. Salt executions can be called via the Salt client api, making programming master side solutions with Salt is easy. .SS Adding Loadable Plugins .sp Salt is comprised of a core platform that loads many types of easy to write plugins. The idea is to enable all of the breaking points in the salt processes to have a point of pluggable interaction. This means that all of the main features of Salt can be extended, modified or used. .sp The breaking points and helping interfaces span from convenience master side executions to manipulating the flow of how data is handled by Salt. .SS Minion Execution Modules .sp The minion execution modules or just \fBmodules\fP are the core to what salt is and does. These modules are found in: .sp \fI\%https://github.com/thatch45/salt/tree/master/salt/modules\fP .sp These modules are what is called by the salt command line and the salt client api. Adding modules is done by simply adding additional python modules to the modules directory and restarting the minion. .SS Grains .sp Salt grains, or "grains of truth" are bits of static information that are generated when the minion starts. This information is useful when determining what package manager to default to, or where certain configuration files are stored on the minion. .sp The Salt grains are the interface used for auto detection and dynamic assignment of execution modules and types to specific salt minions. .sp The code used to generate the Salt grains can be found here: .sp \fI\%https://github.com/thatch45/salt/tree/master/salt/grains\fP .SS States .sp Salt supports state enforcement, this makes Salt a high speed and very efficient solution for system configuration management. .sp States can be easily added to Salt by dropping a new state module in: .sp \fI\%https://github.com/thatch45/salt/tree/master/salt/states\fP .SS Renderers .sp Salt states are controlled by simple data structures, these structures can be abstracted in a number of ways. While the default is to be in a yaml file wrapped in a jinja template, any abstraction can be used. This means that any format that can be dreamed is possible, so long as a renderer is written for it. .sp The existing renderers can be found here: .sp \fI\%https://github.com/thatch45/salt/tree/master/salt/renderers\fP .SS Returners .sp The salt commands all produce a return value, that return value is sent to the salt master by default, but it can be sent anywhere. The returner interface makes it programmatically possible for the information to be sent to anything from an SQL or NOSQL database, to a custom application made to use Salt. .sp The existing returners can be found here: .sp \fI\%https://github.com/thatch45/salt/tree/master/salt/returners\fP .SS Runners .sp Sometimes a certain application can be made to execute and run from the existing salt command line. This is where the salt runners come into play. The Salt Runners what is called by the salt\-run command and are meant to act as a generic interface for encapsulating master side executions. .sp Existing Salt runners are located here: .sp \fI\%https://github.com/thatch45/salt/tree/master/salt/runners\fP .SS Modules .sp Salt modules are the functions called by the \fBsalt\fP command. .SS Full list of builtin modules .SS Contents .INDENT 0.0 .IP \(bu 2 \fI\%salt.modules.butterkvm\fP .IP \(bu 2 \fI\%salt.modules.cluster\fP .IP \(bu 2 \fI\%salt.modules.cmd\fP .IP \(bu 2 \fI\%salt.modules.cp\fP .IP \(bu 2 \fI\%salt.modules.disk\fP .IP \(bu 2 \fI\%salt.modules.grains\fP .IP \(bu 2 \fI\%salt.modules.network\fP .IP \(bu 2 \fI\%salt.modules.pacman\fP .IP \(bu 2 \fI\%salt.modules.service\fP .IP \(bu 2 \fI\%salt.modules.state\fP .IP \(bu 2 \fI\%salt.modules.status\fP .IP \(bu 2 \fI\%salt.modules.sysctl\fP .IP \(bu 2 \fI\%salt.modules.test\fP .IP \(bu 2 \fI\%salt.modules.virt\fP .IP \(bu 2 \fI\%salt.modules.yum\fP .UNINDENT .SS \fBsalt.modules.butterkvm\fP .sp Specialized routines used by the butter cloud component .INDENT 0.0 .TP .B salt.modules.butterkvm.create(instance, vda, image, pin) Create a virtual machine, this is part of the butter vm system and assumes that the files prepared by butter are available via shared storage. AKA \- don\(aqt call this from the command line! .sp Arguments: instance \- string, The path to the instance directory for the given vm on shared storage vda \- The location where the virtual machine image needs to be placed image \- The image to move into place pin \- a "pin" data structure defining the myriad of possible vdb\-vbz disk images to generate. .sp CLI Example: salt \(aq*\(aq butterkvm.create .UNINDENT .INDENT 0.0 .TP .B salt.modules.butterkvm.full_butter_data(local_path) Return the full virt info, but add butter data! .sp CLI Example: salt \(aq*\(aq buttervm.full_butter_data .UNINDENT .INDENT 0.0 .TP .B salt.modules.butterkvm.libvirt_creds() Returns the user and group that the disk images should be owned by .sp CLI Example: salt \(aq*\(aq butterkvm.libvirt_creds .UNINDENT .INDENT 0.0 .TP .B salt.modules.butterkvm.local_images(local_path) return the virtual machine names for all of the images located in the butter cloud\(aqs local_path in a list: .sp [\(aqvm1.boo.com\(aq, \(aqvm2.foo.com\(aq] .sp CLI Example: salt \(aq*\(aq buttervm.local_images .UNINDENT .SS \fBsalt.modules.cluster\fP .sp The cluster module is used to distribute and activate salt HA cluster components .INDENT 0.0 .TP .B salt.modules.cluster.distrib(minions, master_conf, master_pem, conf_file) Set up this minion as a failover master \- only intended for use by the cluster interface .UNINDENT .SS \fBsalt.modules.cmd\fP .sp A module for shelling out .sp Keep in mind that this module is insecure, in that it can give whomever has access to the master root execution access to all salt minions .INDENT 0.0 .TP .B salt.modules.cmd.exec_code(lang, code) Pass in two strings, the first naming the executable language, aka \- python2, python3, ruby, perl, lua, etc. the second string containing the code you wish to execute. The stdout and stderr will be returned .sp CLI Example: salt \(aq*\(aq cmd.exec_code ruby \(aqputs "cheese"\(aq .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmd.has_exec(cmd) Returns true if the executable is available on the minion, false otherwise .sp CLI Example: salt \(aq*\(aq cat .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmd.retcode(cmd, cwd=\(aq/home/thatch\(aq) Execute a shell command and return the command\(aqs return code. .sp CLI Example: salt \(aq*\(aq cmd.retcode "file /bin/bash" .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmd.run(cmd, cwd=\(aq/home/thatch\(aq) Execute the passed command and return the output as a string .sp CLI Example: salt \(aq*\(aq cmd.run "ls \-l | grep foo | awk \(aq{print $2}\(aq" .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmd.run_all(cmd, cwd=\(aq/home/thatch\(aq) Execute the passed command and return a dict of return data .sp CLI Example: salt \(aq*\(aq cmd.run_all "ls \-l | grep foo | awk \(aq{print $2}\(aq" .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmd.run_stderr(cmd, cwd=\(aq/home/thatch\(aq) Execute a command and only return the standard error .sp CLI Example: salt \(aq*\(aq cmd.run "ls \-l | grep foo | awk \(aq{print $2}\(aq" .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmd.run_stdout(cmd, cwd=\(aq/home/thatch\(aq) Execute a command, and only return the standard out .sp CLI Example: salt \(aq*\(aq cmd.run "ls \-l | grep foo | awk \(aq{print $2}\(aq" .UNINDENT .SS \fBsalt.modules.cp\fP .sp Minion side functions for salt\-cp .INDENT 0.0 .TP .B salt.modules.cp.cache_file(path, env=\(aqbase\(aq) Used to cache a single file in the local salt\-master file cache. .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_files(paths, env=\(aqbase\(aq) 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. .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_file(path, dest, env=\(aqbase\(aq) Used to get a single file from the salt master .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.hash_file(path, env=\(aqbase\(aq) 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: .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 .UNINDENT .SS \fBsalt.modules.disk\fP .sp Module for gathering disk information .INDENT 0.0 .TP .B salt.modules.disk.usage() Return usage information for volumes mounted on this minion .sp CLI Example: salt \(aq*\(aq disk.usage .UNINDENT .SS \fBsalt.modules.grains\fP .sp Control aspects of the grains data .INDENT 0.0 .TP .B salt.modules.grains.item(key) Return a singe component of the grains data .sp CLI Example: salt \(aq*\(aq grains.item os .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.items() Return the grains data .sp CLI Example: salt \(aq*\(aq grains.items .UNINDENT .SS \fBsalt.modules.network\fP .sp Module for gathering and managing network information .INDENT 0.0 .TP .B salt.modules.network.dig(host) Performs a DNS lookup with dig .sp CLI Example: salt \(aq*\(aq network.dig archlinux.org .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.isportopen(host, port) Return status of a port .sp CLI Example: salt \(aq*\(aq network.isportopen 127.0.0.1 22 .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.netstat() Return information on open ports and states .sp CLI Example: salt \(aq*\(aq network.netstat .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ping(host) Performs a ping to a host .sp CLI Example: salt \(aq*\(aq network.ping archlinux.org \-c 4 .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.traceroute(host) Performs a traceroute to a 3rd party host .sp CLI Example: salt \(aq*\(aq network.traceroute archlinux.org .UNINDENT .SS \fBsalt.modules.pacman\fP .sp A module to wrap pacman calls, since Arch is the best (\fI\%https://wiki.archlinux.org/index.php/Arch_is_the_best\fP) .INDENT 0.0 .TP .B salt.modules.pacman.available_version(name) The available version of the package in the repository .sp CLI Example: salt \(aq*\(aq pkg.available_version .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.install(name, refresh=False) Install the passed package, add refresh=True to install with an \-Sy .sp Return a dict containing the new package names and versions: {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, .INDENT 7.0 .INDENT 3.5 \(aqnew\(aq: \(aq\(aq]} .UNINDENT .UNINDENT .sp CLI Example: salt \(aq*\(aq pkg.install .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.list_pkgs() List the packages currently installed in a dict: {\(aq\(aq: \(aq\(aq} .sp CLI Example: salt \(aq*\(aq pkg.list_pkgs .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.purge(name) Recursively remove a package and all dependencies which were installed with it, this will call a pacman \-Rsc .sp Return a list containing the removed packages: .sp CLI Example: salt \(aq*\(aq pkg.purge .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.refresh_db() Just run a pacman \-Sy, return a dict: {\(aq\(aq: Bool} .sp CLI Example: salt \(aq*\(aq pkg.refresh_db .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.remove(name) Remove a single package with pacman \-R .sp Return a list containing the removed packages: .sp CLI Example: salt \(aq*\(aq pkg.remove .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.upgrade() Run a full system upgrade, a pacman \-Syu .sp Return a dict containing the new package names and versions: {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, .INDENT 7.0 .INDENT 3.5 \(aqnew\(aq: \(aq\(aq]} .UNINDENT .UNINDENT .sp CLI Example: salt \(aq*\(aq pkg.upgrade .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.version(name) Returns a version if the package is installed, else returns an empty string .sp CLI Example: salt \(aq*\(aq pkg.version .UNINDENT .SS \fBsalt.modules.service\fP .sp Top level package command wrapper, used to translate the os detected by the grains to the correct service manager .INDENT 0.0 .TP .B salt.modules.service.restart(name) Restart the named service .sp CLI Example: salt \(aq*\(aq service.restart .UNINDENT .INDENT 0.0 .TP .B salt.modules.service.start(name) Start the specified service .sp CLI Example: salt \(aq*\(aq service.start .UNINDENT .INDENT 0.0 .TP .B salt.modules.service.status(name, sig=None) Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps .sp CLI Example: salt \(aq*\(aq service.status [service signature] .UNINDENT .INDENT 0.0 .TP .B salt.modules.service.stop(name) Stop the specified service .sp CLI Example: salt \(aq*\(aq service.stop .UNINDENT .SS \fBsalt.modules.state\fP .sp Control the state system on the minion .INDENT 0.0 .TP .B salt.modules.state.high(data) 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: salt \(aq*\(aq state.high \(aq{"vim": {"pkg": ["installed"]}}\(aq .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.highstate() Retrive the state data from the salt master for this minion and execute it .sp CLI Example: salt \(aq*\(aq state.highstate .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.low(data) Execute a single low data call This function is mostly intended for testing the state system .sp CLI Example: salt \(aq*\(aq state.low \(aq{"state": "pkg", "fun": "installed", "name": "vim"}\(aq .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.template(tem) Execute the information stored in a template file on the minion .sp CLI Example: salt \(aq*\(aq state.template \(aq\(aq .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.template_str(tem) Execute the information stored in a template file on the minion .sp CLI Example: salt \(aq*\(aq state.template_str \(aq