123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260 |
- .. _salt-ssh:
- ========
- Salt SSH
- ========
- .. raw:: html
- :file: index.html
- Getting Started
- ===============
- Salt SSH is very easy to use, simply set up a basic :ref:`roster <ssh-roster>` file of the
- systems to connect to and run ``salt-ssh`` commands in a similar way as
- standard ``salt`` commands.
- - Salt ssh is considered production ready in version 2014.7.0
- - Python is required on the remote system (unless using the ``-r`` option to send raw ssh commands)
- - On many systems, the ``salt-ssh`` executable will be in its own package, usually named
- ``salt-ssh``
- - The Salt SSH system does not supersede the standard Salt communication
- systems, it simply offers an SSH-based alternative that does not require
- ZeroMQ and a remote agent. Be aware that since all communication with Salt SSH is
- executed via SSH it is substantially slower than standard Salt with ZeroMQ.
- - At the moment fileserver operations must be wrapped to ensure that the
- relevant files are delivered with the ``salt-ssh`` commands.
- The state module is an exception, which compiles the state run on the
- master, and in the process finds all the references to ``salt://`` paths and
- copies those files down in the same tarball as the state run.
- However, needed fileserver wrappers are still under development.
- Salt SSH Roster
- ===============
- The roster system in Salt allows for remote minions to be easily defined.
- .. note::
- See the :ref:`SSH roster docs <ssh-roster>` for more details.
- Simply create the roster file, the default location is `/etc/salt/roster`:
- .. code-block:: yaml
- web1: 192.168.42.1
- This is a very basic roster file where a Salt ID is being assigned to an IP
- address. A more elaborate roster can be created:
- .. code-block:: yaml
- web1:
- host: 192.168.42.1 # The IP addr or DNS hostname
- user: fred # Remote executions will be executed as user fred
- passwd: foobarbaz # The password to use for login, if omitted, keys are used
- sudo: True # Whether to sudo to root, not enabled by default
- web2:
- host: 192.168.42.2
- .. note::
- sudo works only if NOPASSWD is set for user in /etc/sudoers:
- ``fred ALL=(ALL) NOPASSWD: ALL``
- Deploy ssh key for salt-ssh
- ===========================
- By default, salt-ssh will generate key pairs for ssh, the default path will be
- ``/etc/salt/pki/master/ssh/salt-ssh.rsa``. The key generation happens when you run
- ``salt-ssh`` for the first time.
- You can use ssh-copy-id, (the OpenSSH key deployment tool) to deploy keys to your servers.
- .. code-block:: bash
- ssh-copy-id -i /etc/salt/pki/master/ssh/salt-ssh.rsa.pub user@server.demo.com
- One could also create a simple shell script, named salt-ssh-copy-id.sh as follows:
- .. code-block:: bash
- #!/bin/bash
- if [ -z $1 ]; then
- echo $0 user@host.com
- exit 0
- fi
- ssh-copy-id -i /etc/salt/pki/master/ssh/salt-ssh.rsa.pub $1
- .. note::
- Be certain to chmod +x salt-ssh-copy-id.sh.
- .. code-block:: bash
- ./salt-ssh-copy-id.sh user@server1.host.com
- ./salt-ssh-copy-id.sh user@server2.host.com
- Once keys are successfully deployed, salt-ssh can be used to control them.
- Alternatively ssh agent forwarding can be used by setting the priv to agent-forwarding.
- Calling Salt SSH
- ================
- .. note:: ``salt-ssh`` on RHEL/CentOS 5
- The ``salt-ssh`` command requires at least python 2.6, which is not
- installed by default on RHEL/CentOS 5. An easy workaround in this
- situation is to use the ``-r`` option to run a raw shell command that
- installs python26:
- .. code-block:: bash
- salt-ssh centos-5-minion -r 'yum -y install epel-release ; yum -y install python26'
- .. note:: ``salt-ssh`` on systems with Python 3.x
- Salt, before the 2017.7.0 release, does not support Python 3.x which is the
- default on for example the popular 16.04 LTS release of Ubuntu. An easy
- workaround for this scenario is to use the ``-r`` option similar to the
- example above:
- .. code-block:: bash
- salt-ssh ubuntu-1604-minion -r 'apt update ; apt install -y python-minimal'
- The ``salt-ssh`` command can be easily executed in the same way as a salt
- command:
- .. code-block:: bash
- salt-ssh '*' test.version
- Commands with ``salt-ssh`` follow the same syntax as the ``salt`` command.
- The standard salt functions are available! The output is the same as ``salt``
- and many of the same flags are available. Please see
- http://docs.saltstack.com/ref/cli/salt-ssh.html for all of the available
- options.
- Raw Shell Calls
- ---------------
- By default ``salt-ssh`` runs Salt execution modules on the remote system,
- but ``salt-ssh`` can also execute raw shell commands:
- .. code-block:: bash
- salt-ssh '*' -r 'ifconfig'
- States Via Salt SSH
- ===================
- The Salt State system can also be used with ``salt-ssh``. The state system
- abstracts the same interface to the user in ``salt-ssh`` as it does when using
- standard ``salt``. The intent is that Salt Formulas defined for standard
- ``salt`` will work seamlessly with ``salt-ssh`` and vice-versa.
- The standard Salt States walkthroughs function by simply replacing ``salt``
- commands with ``salt-ssh``.
- Targeting with Salt SSH
- =======================
- Due to the fact that the targeting approach differs in salt-ssh, only glob
- and regex targets are supported as of this writing, the remaining target
- systems still need to be implemented.
- .. note::
- By default, Grains are settable through ``salt-ssh``. By
- default, these grains will *not* be persisted across reboots.
- See the "thin_dir" setting in :ref:`Roster documentation <ssh-roster>`
- for more details.
- Configuring Salt SSH
- ====================
- Salt SSH takes its configuration from a master configuration file. Normally, this
- file is in ``/etc/salt/master``. If one wishes to use a customized configuration file,
- the ``-c`` option to Salt SSH facilitates passing in a directory to look inside for a
- configuration file named ``master``.
- Minion Config
- -------------
- .. versionadded:: 2015.5.1
- Minion config options can be defined globally using the master configuration
- option ``ssh_minion_opts``. It can also be defined on a per-minion basis with
- the ``minion_opts`` entry in the roster.
- Running Salt SSH as non-root user
- =================================
- By default, Salt read all the configuration from /etc/salt/. If you are running
- Salt SSH with a regular user you have to modify some paths or you will get
- "Permission denied" messages. You have to modify two parameters: ``pki_dir``
- and ``cachedir``. Those should point to a full path writable for the user.
- It's recommended not to modify /etc/salt for this purpose. Create a private copy
- of /etc/salt for the user and run the command with ``-c /new/config/path``.
- Define CLI Options with Saltfile
- ================================
- If you are commonly passing in CLI options to ``salt-ssh``, you can create
- a ``Saltfile`` to automatically use these options. This is common if you're
- managing several different salt projects on the same server.
- So you can ``cd`` into a directory that has a ``Saltfile`` with the following
- YAML contents:
- .. code-block:: yaml
- salt-ssh:
- config_dir: path/to/config/dir
- ssh_log_file: salt-ssh.log
- ssh_max_procs: 30
- ssh_wipe: True
- Instead of having to call
- ``salt-ssh --config-dir=path/to/config/dir --max-procs=30 --wipe \* test.version`` you
- can call ``salt-ssh \* test.version``.
- Boolean-style options should be specified in their YAML representation.
- .. note::
- The option keys specified must match the destination attributes for the
- options specified in the parser
- :py:class:`salt.utils.parsers.SaltSSHOptionParser`. For example, in the
- case of the ``--wipe`` command line option, its ``dest`` is configured to
- be ``ssh_wipe`` and thus this is what should be configured in the
- ``Saltfile``. Using the names of flags for this option, being ``wipe:
- True`` or ``w: True``, will not work.
- .. note::
- For the `Saltfile` to be automatically detected it needs to be named
- `Saltfile` with a capital `S` and be readable by the user running
- salt-ssh.
- At last you can create ``~/.salt/Saltfile`` and ``salt-ssh``
- will automatically load it by default.
- Debugging salt-ssh
- ==================
- One common approach for debugging ``salt-ssh`` is to simply use the tarball that salt
- ships to the remote machine and call ``salt-call`` directly.
- To determine the location of ``salt-call``, simply run ``salt-ssh`` with the ``-ltrace``
- flag and look for a line containing the string, ``SALT_ARGV``. This contains the ``salt-call``
- command that ``salt-ssh`` attempted to execute.
- It is recommended that one modify this command a bit by removing the ``-l quiet``,
- ``--metadata`` and ``--output json`` to get a better idea of what's going on the target system.
- .. toctree::
- roster
|