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)
- Any key we can find through an SSH agent
- Any “id_rsa”, “id_dsa” or “id_ecdsa” key discoverable in
~/.ssh/
- 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.
| Parameters: |
- 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) – a password to use for authentication or for unlocking a private key
- pkey (.PKey) – an optional private key to use for authentication
- key_filename (str) – the filename, or list of filenames, of optional private key(s) 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
- banner_timeout (float) – an optional timeout (in seconds) to wait
for the SSH banner to be presented.
|
|---|
| Raises: |
- 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.