Salt SSH#

Managing systems with Salt SSH#

Salt SSH was added in Salt as an alternative means to communicate with minions. The Salt SSH system can be used in tandem with or as an alternative to the standard Salt system.

The Salt SSH system does not supersede the standard Salt communication systems. It simply offers an SSH-based alternative that does not require a remote agent.

Be aware that since all communication with Salt SSH is executed via the SSH protocol, it is substantially slower than the standard Salt master-minion model.

Salt master-minion model

Salt SSH concepts#

Salt SSH requires a few things to be setup on the remote system in order for Salt SSH to be able to manage it:

  • Python is required on the remote system (unless using the -r option to send raw ssh commands)

  • The SSH service must be running on the remote system

  • Network/Firewall must be available/open to remote system

Salt SSH creates a tar-ball containing a system referred to internally to Salt as Salt Thin. Salt SSH keeps track of the deployed version of Salt Thin on target systems and will update minions dynamically.

Install Salt SSH#

Salt SSH is installed on the Salt Master as a Linux package:

salt-call pkg.install salt-ssh

No installation is necessary on the managed system. It just needs to have SSH enabled.

Configuring the Salt SSH roster#

Configuring Salt SSH to access remote systems requires a Salt SSH roster file.

Roster file#

Each system to manage Salt SSH must have an entry defined in the Salt SSH roster file. The roster is defined as a regular Salt configuration file. The default location for the roster file is /etc/salt/roster.

The file is rendered using the Salt render system and can therefore be written in YAML, JSON, Python, etc. as well as contain Jinja templating. Roster file format:

<minion ID>:    # The ID to reference the target system
  host:         # The IP or DNS name of the remote host
  user:         # The user to login as (unless the same as user
                # issuing salt-ssh command)

  passwd:       # The password for the login user
  port:         # Port the target system is listening for SSH
  sudo:         # Boolean to run commands via sudo, default:
                # False
                # sudo only works if NOPASSWD is set for user
                # in /etc/sudoers: fred ALL=(ALL) NOPASSWD: ALL

  tty:          # Boolean: Set this option to True if sudo is
                # also set to True and requiretty is also set on
                # the target system

  priv:         # File path to ssh private key
  priv_passwd:  # Passphrase for ssh private key
  timeout:      # Number of seconds to wait for response when
                # establishing an SSH connection

  minion_opts:  # Dictionary of minion opts
  thin_dir:     # The target system's storage directory for Salt
                # components. Defaults to /var/tmp/salt-<hash>.

  cmd_umask:    # umask to enforce the salt-call command.
                # Should be in octal (so for 0o077 in YAML you
                # would do 0077, or 63)

The roster_defaults can be defined in the master config to set the default login variables for targets in the roster so that the same arguments do not need to be defined or passed with command line arguments.

/etc/salt/roster#
roster_defaults:
  user: tom
  sudo: True
  priv: /root/.ssh/id_rsa
  tty:  True

Example roster:

/etc/salt/roster#
web1: 192.0.2.1    # Use the roster_defaults (or current user) info

web2:
  user: dave
  passwd: Salt4Me!
  host: 192.0.2.2
  port: 2222
  sudo: True
  minion_opts:
    retry_dns: 30
    module_dirs:
      - /opt/lib/salt/modules
      - /mnt/other/salt/modules

web3:
  host: 198.51.100.103
  priv: /etc/salt/trusted-admin.pem
web4:
  host: 198.51.100.104
  priv: /etc/salt/trusted-admin.pem

Deploying a Salt SSH key#

By default, salt-ssh will generate key pairs for ssh, the default path will be /etc/salt/pki/master/ssh/salt-ssh.rsa

You can use ssh-copy-id, (the OpenSSH key deployment tool) to deploy keys to your servers.

ssh-copy-id -i /etc/salt/pki/master/salt-ssh.rsa.pub tom@srv1.domain.com

Calling salt-ssh#

Calling Salt SSH is meant to be simple. The command line has been made to mimic the salt command with a target, function and arguments in the same way.

Examples of salt-ssh#

A simple example using test.ping for all Salt SSH minions:

salt-ssh \* test.ping

The -i option approves the host key on the remote system(s) and prevents manual acceptance of each key:

salt-ssh -i 'web*' network.interfaces

The salt-ssh command line can use alternate targeting (RegEx):

salt-ssh -E 'web[1-5]' status.uptime

Apply Salt States using salt-ssh:

salt-ssh 'web*' state.sls httpd

Run raw shell commands using salt-ssh:

$ salt-ssh 'web*' -r 'rm -rf /tmp/*'

Note

Python is not required when using the -r option to send raw commands. This can be useful to connect/test non-*nix system.

Scan the Salt SSH roster#

The scan roster uses a simple port scanning algorithm to scan for an open ssh port on a remote system or on an entire subnet.

Then salt-ssh will attempt to execute the given routine on all found systems.

salt-ssh --roster scan 198.51.100.104 test.ping

salt-ssh --roster scan 192.0.2.0/24 test.ping