index.rst 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260
  1. .. _salt-ssh:
  2. ========
  3. Salt SSH
  4. ========
  5. .. raw:: html
  6. :file: index.html
  7. Getting Started
  8. ===============
  9. Salt SSH is very easy to use, simply set up a basic :ref:`roster <ssh-roster>` file of the
  10. systems to connect to and run ``salt-ssh`` commands in a similar way as
  11. standard ``salt`` commands.
  12. - Salt ssh is considered production ready in version 2014.7.0
  13. - Python is required on the remote system (unless using the ``-r`` option to send raw ssh commands)
  14. - On many systems, the ``salt-ssh`` executable will be in its own package, usually named
  15. ``salt-ssh``
  16. - The Salt SSH system does not supersede the standard Salt communication
  17. systems, it simply offers an SSH-based alternative that does not require
  18. ZeroMQ and a remote agent. Be aware that since all communication with Salt SSH is
  19. executed via SSH it is substantially slower than standard Salt with ZeroMQ.
  20. - At the moment fileserver operations must be wrapped to ensure that the
  21. relevant files are delivered with the ``salt-ssh`` commands.
  22. The state module is an exception, which compiles the state run on the
  23. master, and in the process finds all the references to ``salt://`` paths and
  24. copies those files down in the same tarball as the state run.
  25. However, needed fileserver wrappers are still under development.
  26. Salt SSH Roster
  27. ===============
  28. The roster system in Salt allows for remote minions to be easily defined.
  29. .. note::
  30. See the :ref:`SSH roster docs <ssh-roster>` for more details.
  31. Simply create the roster file, the default location is `/etc/salt/roster`:
  32. .. code-block:: yaml
  33. web1: 192.168.42.1
  34. This is a very basic roster file where a Salt ID is being assigned to an IP
  35. address. A more elaborate roster can be created:
  36. .. code-block:: yaml
  37. web1:
  38. host: 192.168.42.1 # The IP addr or DNS hostname
  39. user: fred # Remote executions will be executed as user fred
  40. passwd: foobarbaz # The password to use for login, if omitted, keys are used
  41. sudo: True # Whether to sudo to root, not enabled by default
  42. web2:
  43. host: 192.168.42.2
  44. .. note::
  45. sudo works only if NOPASSWD is set for user in /etc/sudoers:
  46. ``fred ALL=(ALL) NOPASSWD: ALL``
  47. Deploy ssh key for salt-ssh
  48. ===========================
  49. By default, salt-ssh will generate key pairs for ssh, the default path will be
  50. ``/etc/salt/pki/master/ssh/salt-ssh.rsa``. The key generation happens when you run
  51. ``salt-ssh`` for the first time.
  52. You can use ssh-copy-id, (the OpenSSH key deployment tool) to deploy keys to your servers.
  53. .. code-block:: bash
  54. ssh-copy-id -i /etc/salt/pki/master/ssh/salt-ssh.rsa.pub user@server.demo.com
  55. One could also create a simple shell script, named salt-ssh-copy-id.sh as follows:
  56. .. code-block:: bash
  57. #!/bin/bash
  58. if [ -z $1 ]; then
  59. echo $0 user@host.com
  60. exit 0
  61. fi
  62. ssh-copy-id -i /etc/salt/pki/master/ssh/salt-ssh.rsa.pub $1
  63. .. note::
  64. Be certain to chmod +x salt-ssh-copy-id.sh.
  65. .. code-block:: bash
  66. ./salt-ssh-copy-id.sh user@server1.host.com
  67. ./salt-ssh-copy-id.sh user@server2.host.com
  68. Once keys are successfully deployed, salt-ssh can be used to control them.
  69. Alternatively ssh agent forwarding can be used by setting the priv to agent-forwarding.
  70. Calling Salt SSH
  71. ================
  72. .. note:: ``salt-ssh`` on RHEL/CentOS 5
  73. The ``salt-ssh`` command requires at least python 2.6, which is not
  74. installed by default on RHEL/CentOS 5. An easy workaround in this
  75. situation is to use the ``-r`` option to run a raw shell command that
  76. installs python26:
  77. .. code-block:: bash
  78. salt-ssh centos-5-minion -r 'yum -y install epel-release ; yum -y install python26'
  79. .. note:: ``salt-ssh`` on systems with Python 3.x
  80. Salt, before the 2017.7.0 release, does not support Python 3.x which is the
  81. default on for example the popular 16.04 LTS release of Ubuntu. An easy
  82. workaround for this scenario is to use the ``-r`` option similar to the
  83. example above:
  84. .. code-block:: bash
  85. salt-ssh ubuntu-1604-minion -r 'apt update ; apt install -y python-minimal'
  86. The ``salt-ssh`` command can be easily executed in the same way as a salt
  87. command:
  88. .. code-block:: bash
  89. salt-ssh '*' test.version
  90. Commands with ``salt-ssh`` follow the same syntax as the ``salt`` command.
  91. The standard salt functions are available! The output is the same as ``salt``
  92. and many of the same flags are available. Please see
  93. http://docs.saltstack.com/ref/cli/salt-ssh.html for all of the available
  94. options.
  95. Raw Shell Calls
  96. ---------------
  97. By default ``salt-ssh`` runs Salt execution modules on the remote system,
  98. but ``salt-ssh`` can also execute raw shell commands:
  99. .. code-block:: bash
  100. salt-ssh '*' -r 'ifconfig'
  101. States Via Salt SSH
  102. ===================
  103. The Salt State system can also be used with ``salt-ssh``. The state system
  104. abstracts the same interface to the user in ``salt-ssh`` as it does when using
  105. standard ``salt``. The intent is that Salt Formulas defined for standard
  106. ``salt`` will work seamlessly with ``salt-ssh`` and vice-versa.
  107. The standard Salt States walkthroughs function by simply replacing ``salt``
  108. commands with ``salt-ssh``.
  109. Targeting with Salt SSH
  110. =======================
  111. Due to the fact that the targeting approach differs in salt-ssh, only glob
  112. and regex targets are supported as of this writing, the remaining target
  113. systems still need to be implemented.
  114. .. note::
  115. By default, Grains are settable through ``salt-ssh``. By
  116. default, these grains will *not* be persisted across reboots.
  117. See the "thin_dir" setting in :ref:`Roster documentation <ssh-roster>`
  118. for more details.
  119. Configuring Salt SSH
  120. ====================
  121. Salt SSH takes its configuration from a master configuration file. Normally, this
  122. file is in ``/etc/salt/master``. If one wishes to use a customized configuration file,
  123. the ``-c`` option to Salt SSH facilitates passing in a directory to look inside for a
  124. configuration file named ``master``.
  125. Minion Config
  126. -------------
  127. .. versionadded:: 2015.5.1
  128. Minion config options can be defined globally using the master configuration
  129. option ``ssh_minion_opts``. It can also be defined on a per-minion basis with
  130. the ``minion_opts`` entry in the roster.
  131. Running Salt SSH as non-root user
  132. =================================
  133. By default, Salt read all the configuration from /etc/salt/. If you are running
  134. Salt SSH with a regular user you have to modify some paths or you will get
  135. "Permission denied" messages. You have to modify two parameters: ``pki_dir``
  136. and ``cachedir``. Those should point to a full path writable for the user.
  137. It's recommended not to modify /etc/salt for this purpose. Create a private copy
  138. of /etc/salt for the user and run the command with ``-c /new/config/path``.
  139. Define CLI Options with Saltfile
  140. ================================
  141. If you are commonly passing in CLI options to ``salt-ssh``, you can create
  142. a ``Saltfile`` to automatically use these options. This is common if you're
  143. managing several different salt projects on the same server.
  144. So you can ``cd`` into a directory that has a ``Saltfile`` with the following
  145. YAML contents:
  146. .. code-block:: yaml
  147. salt-ssh:
  148. config_dir: path/to/config/dir
  149. ssh_log_file: salt-ssh.log
  150. ssh_max_procs: 30
  151. ssh_wipe: True
  152. Instead of having to call
  153. ``salt-ssh --config-dir=path/to/config/dir --max-procs=30 --wipe \* test.version`` you
  154. can call ``salt-ssh \* test.version``.
  155. Boolean-style options should be specified in their YAML representation.
  156. .. note::
  157. The option keys specified must match the destination attributes for the
  158. options specified in the parser
  159. :py:class:`salt.utils.parsers.SaltSSHOptionParser`. For example, in the
  160. case of the ``--wipe`` command line option, its ``dest`` is configured to
  161. be ``ssh_wipe`` and thus this is what should be configured in the
  162. ``Saltfile``. Using the names of flags for this option, being ``wipe:
  163. True`` or ``w: True``, will not work.
  164. .. note::
  165. For the `Saltfile` to be automatically detected it needs to be named
  166. `Saltfile` with a capital `S` and be readable by the user running
  167. salt-ssh.
  168. At last you can create ``~/.salt/Saltfile`` and ``salt-ssh``
  169. will automatically load it by default.
  170. Debugging salt-ssh
  171. ==================
  172. One common approach for debugging ``salt-ssh`` is to simply use the tarball that salt
  173. ships to the remote machine and call ``salt-call`` directly.
  174. To determine the location of ``salt-call``, simply run ``salt-ssh`` with the ``-ltrace``
  175. flag and look for a line containing the string, ``SALT_ARGV``. This contains the ``salt-call``
  176. command that ``salt-ssh`` attempted to execute.
  177. It is recommended that one modify this command a bit by removing the ``-l quiet``,
  178. ``--metadata`` and ``--output json`` to get a better idea of what's going on the target system.
  179. .. toctree::
  180. roster