pyinfra.api.connectors.sshuserclient.client module

This file as originally part of the “sshuserclient” pypi package. The GitHub source has now vanished (

class pyinfra.api.connectors.sshuserclient.client.SSHClient

Bases: paramiko.client.SSHClient

An SSHClient which honors ssh_config and supports proxyjumping original idea at

connect(hostname, **kwargs)

Connect to an SSH server and authenticate to it. The server’s host key is checked against the system host keys (see load_system_host_keys) and any local host keys (load_host_keys). If the server’s hostname is not found in either set of host keys, the missing host key policy is used (see set_missing_host_key_policy). The default policy is to reject the key and raise an .SSHException.

Authentication is attempted in the following order of priority:

  • The pkey or key_filename passed in (if any)
    • key_filename may contain OpenSSH public certificate paths as well as regular private-key paths; when files ending in are found, they are assumed to match a private key, and both components will be loaded. (The private key itself does not need to be listed in key_filename for this to occur - just the certificate.)
  • Any key we can find through an SSH agent
  • Any “id_rsa”, “id_dsa” or “id_ecdsa” key discoverable in ~/.ssh/
    • When OpenSSH-style public certificates exist that match an existing such private key (so e.g. one has id_rsa and the certificate will be loaded alongside the private key and used for authentication.
  • Plain username/password auth, if a password was given

If a private key requires a password to unlock it, and a password is passed in, that password will be used to attempt to unlock the key.

  • hostname (str) – the server to connect to
  • port (int) – the server port to connect to
  • username (str) – the username to authenticate as (defaults to the current local username)
  • password (str) – Used for password authentication; is also used for private key decryption if passphrase is not given.
  • passphrase (str) – Used for decrypting private keys.
  • pkey (PKey) – an optional private key to use for authentication
  • key_filename (str) – the filename, or list of filenames, of optional private key(s) and/or certs to try for authentication
  • timeout (float) – an optional timeout (in seconds) for the TCP connect
  • allow_agent (bool) – set to False to disable connecting to the SSH agent
  • look_for_keys (bool) – set to False to disable searching for discoverable private key files in ~/.ssh/
  • compress (bool) – set to True to turn on compression
  • sock (socket) – an open socket or socket-like object (such as a .Channel) to use for communication to the target host
  • gss_auth (bool) – True if you want to use GSS-API authentication
  • gss_kex (bool) – Perform GSS-API Key Exchange and user authentication
  • gss_deleg_creds (bool) – Delegate GSS-API client credentials or not
  • gss_host (str) – The targets name in the kerberos database. default: hostname
  • gss_trust_dns (bool) – Indicates whether or not the DNS is trusted to securely canonicalize the name of the host being connected to (default True).
  • banner_timeout (float) – an optional timeout (in seconds) to wait for the SSH banner to be presented.
  • auth_timeout (float) – an optional timeout (in seconds) to wait for an authentication response.
  • disabled_algorithms (dict) – an optional dict passed directly to .Transport and its keyword argument of the same name.

.BadHostKeyException – if the server’s host key could not be verified


.AuthenticationException – if authentication failed


.SSHException – if there was any other error connecting or establishing an SSH session


socket.error – if a socket error occurred while connecting

Changed in version 1.15: Added the banner_timeout, gss_auth, gss_kex, gss_deleg_creds and gss_host arguments.

Changed in version 2.3: Added the gss_trust_dns argument.

Changed in version 2.4: Added the passphrase argument.

Changed in version 2.6: Added the disabled_algorithms argument.

gateway(target, target_port)