# salt.modules.ssh

Manage client ssh components

Note

This module requires the use of MD5 hashing. Certain security audits may not permit the use of MD5. For those cases, this module should be disabled or removed.

salt.modules.ssh.auth_keys(user=None, config='.ssh/authorized_keys', fingerprint_hash_type=None)

  Return the authorized keys for users

  CLI Example:

      salt '*' ssh.auth_keys
      salt '*' ssh.auth_keys root
      salt '*' ssh.auth_keys user=root
      salt '*' ssh.auth_keys user="[user1, user2]"

salt.modules.ssh.check_key(user, key, enc, comment, options, config='.ssh/authorized_keys', cache_keys=None, fingerprint_hash_type=None)

  Check to see if a key needs updating, returns "update", "add" or "exists"

  CLI Example:

      salt '*' ssh.check_key <user> <key> <enc> <comment> <options>

salt.modules.ssh.check_key_file(user, source, config='.ssh/authorized_keys', saltenv='base', fingerprint_hash_type=None)

  Check a keyfile from a source destination against the local keys and return the keys to change

  CLI Example:

      salt '*' ssh.check_key_file root salt://ssh/keyfile

salt.modules.ssh.check_known_host(user=None, hostname=None, key=None, fingerprint=None, config=None, port=None, fingerprint_hash_type=None)

  Check the record in known_hosts file, either by its value or by fingerprint (it's enough to set up either key or fingerprint, you don't need to set up both).

  If provided key or fingerprint doesn't match with stored value, return "update", if no value is found for a given host, return "add", otherwise return "exists".

  If neither key, nor fingerprint is defined, then additional validation is not performed.

  CLI Example:

      salt '*' ssh.check_known_host <user> <hostname> key='AAAA...FAaQ=='

salt.modules.ssh.get_known_host_entries(user, hostname, config=None, port=None, fingerprint_hash_type=None)

  Added in version 2018.3.0.

  Return information about known host entries from the configfile, if any. If there are no entries for a matching hostname, return None.

  CLI Example:

      salt '*' ssh.get_known_host_entries <user> <hostname>

salt.modules.ssh.hash_known_hosts(user=None, config=None)

  Hash all the hostnames in the known hosts file.

  Added in version 2014.7.0.

  user

    hash known hosts of this user

  config

    path to known hosts file: can be absolute or relative to user's home directory

  CLI Example:

      salt '*' ssh.hash_known_hosts

salt.modules.ssh.host_keys(keydir=None, private=True, certs=True)

  Return the minion's host keys

  CLI Example:

      salt '*' ssh.host_keys
      salt '*' ssh.host_keys keydir=/etc/ssh
      salt '*' ssh.host_keys keydir=/etc/ssh private=False
      salt '*' ssh.host_keys keydir=/etc/ssh certs=False

salt.modules.ssh.key_is_encrypted(key)

  Added in version 2015.8.7.

  Function to determine whether or not a private key is encrypted with a passphrase.

  Checks key for a `Proc-Type` header with `ENCRYPTED` in the value. If found, returns `True`, otherwise returns `False`.

  CLI Example:

      salt '*' ssh.key_is_encrypted /root/id_rsa

salt.modules.ssh.recv_known_host_entries(hostname, enc=None, port=None, hash_known_hosts=True, timeout=5, fingerprint_hash_type=None)

  Added in version 2018.3.0.

  Retrieve information about host public keys from remote server

  hostname

    The name of the remote host (e.g. "github.com")

  enc

    Defines what type of key is being used, can be ed25519, ecdsa, ssh-rsa, ssh-dss or any other type as of openssh server version 8.7.

  port

    Optional parameter, denoting the port of the remote host on which an SSH daemon is running. By default the port 22 is used.

  hash_known_hostsTrue

    Hash all hostnames and addresses in the known hosts file.

  timeoutint

    Set the timeout for connection attempts. If `timeout` seconds have elapsed since a connection was initiated to a host or since the last time anything was read from that host, then the connection is closed and the host in question considered unavailable. Default is 5 seconds.

  fingerprint_hash_type

    The fingerprint hash type that the public key fingerprints were originally hashed with. This defaults to `sha256` if not specified.

    Added in version 2016.11.4.

    Changed in version 2017.7.0: default changed from `md5` to `sha256`

  CLI Example:

      salt '*' ssh.recv_known_host_entries <hostname> enc=<enc> port=<port>

salt.modules.ssh.rm_auth_key(user, key, config='.ssh/authorized_keys', fingerprint_hash_type=None)

  Remove an authorized key from the specified user's authorized key file

  CLI Example:

      salt '*' ssh.rm_auth_key <user> <key>

salt.modules.ssh.rm_auth_key_from_file(user, source, config='.ssh/authorized_keys', saltenv='base', fingerprint_hash_type=None)

  Remove an authorized key from the specified user's authorized key file, using a file as source

  CLI Example:

      salt '*' ssh.rm_auth_key_from_file <user> salt://ssh_keys/<user>.id_rsa.pub

salt.modules.ssh.rm_known_host(user=None, hostname=None, config=None, port=None)

  Remove all keys belonging to hostname from a known_hosts file.

  CLI Example:

      salt '*' ssh.rm_known_host <user> <hostname>

salt.modules.ssh.set_auth_key(user, key, enc='ssh-rsa', comment='', options=None, config='.ssh/authorized_keys', cache_keys=None, fingerprint_hash_type=None)

  Add a key to the authorized_keys file. The "key" parameter must only be the string of text that is the encoded key. If the key begins with "ssh-rsa" or ends with user@host, remove those from the key before passing it to this function.

  CLI Example:

      salt '*' ssh.set_auth_key <user> '<key>' enc='dsa'

salt.modules.ssh.set_auth_key_from_file(user, source, config='.ssh/authorized_keys', saltenv='base', fingerprint_hash_type=None, **kwargs)

  Add a key to the authorized_keys file, using a file as the source.

  CLI Example:

      salt '*' ssh.set_auth_key_from_file <user> salt://ssh_keys/<user>.id_rsa.pub

salt.modules.ssh.set_known_host(user=None, hostname=None, fingerprint=None, key=None, port=None, enc=None, config=None, hash_known_hosts=True, timeout=5, fingerprint_hash_type=None)

  Download SSH public key from remote host "hostname", optionally validate its fingerprint against "fingerprint" variable and save the record in the known_hosts file.

  If such a record does already exists in there, do nothing.

  user

    The user who owns the ssh authorized keys file to modify

  hostname

    The name of the remote host (e.g. "github.com")

  fingerprint

    The fingerprint of the key which must be present in the known_hosts file (optional if key specified)

  key

    The public key which must be presented in the known_hosts file (optional if fingerprint specified)

  port

    optional parameter, denoting the port of the remote host, which will be used in case, if the public key will be requested from it. By default the port 22 is used.

  enc

    Defines what type of key is being used, can be ed25519, ecdsa, ssh-rsa, ssh-dss or any other type as of openssh server version 8.7.

  config

    The location of the authorized keys file relative to the user's home directory, defaults to ".ssh/known_hosts". If no user is specified, defaults to "/etc/ssh/ssh_known_hosts". If present, must be an absolute path when a user is not specified.

  hash_known_hostsTrue

    Hash all hostnames and addresses in the known hosts file.

  timeoutint

    Set the timeout for connection attempts. If `timeout` seconds have elapsed since a connection was initiated to a host or since the last time anything was read from that host, then the connection is closed and the host in question considered unavailable. Default is 5 seconds.

    Added in version 2016.3.0.

  fingerprint_hash_type

    The public key fingerprint hash type that the public key fingerprint was originally hashed with. This defaults to `sha256` if not specified.

    Added in version 2016.11.4.

    Changed in version 2017.7.0: default changed from `md5` to `sha256`

  CLI Example:

      salt '*' ssh.set_known_host <user> fingerprint='xx:xx:..:xx' enc='ssh-rsa' config='.ssh/known_hosts'

salt.modules.ssh.user_keys(user=None, pubfile=None, prvfile=None)

  Return the user's ssh keys on the minion

  Added in version 2014.7.0.

  CLI Example:

      salt '*' ssh.user_keys
      salt '*' ssh.user_keys user=user1
      salt '*' ssh.user_keys user=user1 pubfile=/home/user1/.ssh/id_rsa.pub prvfile=/home/user1/.ssh/id_rsa
      salt '*' ssh.user_keys user=user1 prvfile=False
      salt '*' ssh.user_keys user="['user1','user2'] pubfile=id_rsa.pub prvfile=id_rsa

  As you can see you can tell Salt not to read from the user's private (or public) key file by setting the file path to `False`. This can be useful to prevent Salt from publishing private data via Salt Mine or others.