Main Functions¶
create_connection¶
- asyncssh.create_connection(client_factory, host, port=22, *, loop=None, family=0, flags=0, local_addr=None, known_hosts=(), username=None, client_keys=(), password=None, kex_algs=(), encryption_algs=(), mac_algs=(), compression_algs=(), rekey_bytes=1073741824, rekey_seconds=3600)¶
Create an SSH client connection
This function is a coroutine which can be run to create an outbound SSH client connection to the specified host and port.
When successful, the following steps occur:
- The connection is established and an SSHClientConnection object is created to represent it.
- The client_factory is called without arguments and should return an SSHClient object.
- The client object is tied to the connection and its connection_made() method is called.
- The SSH handshake and authentication process is initiated, calling methods on the client object if needed.
- When authentication completes successfully, the client’s auth_completed() method is called.
- The coroutine returns the (connection, client) pair. At this point, the connection is ready for sessions to be opened or port forwarding to be set up.
If an error occurs, it will be raised as an exception and the partially open connection and client objects will be cleaned up.
Parameters: - client_factory (callable) – A callable which returns an SSHClient object that will be tied to the connection
- host (string) – The hostname or address to connect to
- port (integer) – (optional) The port number to connect to. If not specified, the default SSH port is used.
- loop – (optional) The event loop to use when creating the connection. If not specified, the default event loop is used.
- family (socket.AF_UNSPEC, socket.AF_INET, or socket.AF_INET6) – (optional) The address family to use when creating the socket. By default, the address family is automatically selected based on the host.
- flags (flags to pass to getaddrinfo()) – (optional) The flags to pass to getaddrinfo() when looking up the host address
- local_addr (tuple of string and integer) – (optional) The host and port to bind the socket to before connecting
- known_hosts (see Specifying known hosts) – (optional) The list of keys which will be used to validate the server host key presented during the SSH handshake. If this is not specified, the keys will be looked up in the file .ssh/known_hosts. If this is explicitly set to None, server host key validation will be disabled.
- username (string) – (optional) Username to authenticate as on the server. If not specified, the currently logged in user on the local machine will be used.
- client_keys (see Specifying private keys) – (optional) A list of keys which will be used to authenticate this client via public key authentication. If no client keys are specified, an attempt will be made to load them from the files .ssh/id_ed25519, .ssh/id_ecdsa, .ssh/id_rsa, and .ssh/id_dsa, with optional certificates loaded from the files .ssh/id_ed25519-cert.pub, .ssh/id_ecdsa-cert.pub, .ssh/id_rsa-cert.pub, and .ssh/id_dsa-cert.pub. If this argument is explicitly set to None, client public key authentication will not be performed.
- password (string) – (optional) The password to use for client password authentication or keyboard-interactive authentication which prompts for a password. If this is not specified, client password authentication will not be performed.
- kex_algs (list of strings) – (optional) A list of allowed key exchange algorithms in the SSH handshake, taken from key exchange algorithms
- encryption_algs (list of strings) – (optional) A list of encryption algorithms to use during the SSH handshake, taken from encryption algorithms
- mac_algs (list of strings) – (optional) A list of MAC algorithms to use during the SSH handshake, taken from MAC algorithms
- compression_algs (list of strings) – (optional) A list of compression algorithms to use during the SSH handshake, taken from compression algorithms, or None to disable compression
- rekey_bytes (integer) – (optional) The number of bytes which can be sent before the SSH session key is renegotiated. This defaults to 1 GB.
- rekey_seconds (integer) – (optional) The maximum time in seconds before the SSH session key is renegotiated. This defaults to 1 hour.
Returns: An SSHClientConnection and SSHClient
create_server¶
- asyncssh.create_server(server_factory, host=None, port=22, *, loop=None, family=0, flags=1, backlog=100, reuse_address=None, server_host_keys, authorized_client_keys=None, kex_algs=(), encryption_algs=(), mac_algs=(), compression_algs=(), allow_pty=True, session_factory=None, session_encoding='utf-8', sftp_factory=None, window=2097152, max_pktsize=32768, rekey_bytes=1073741824, rekey_seconds=3600)¶
Create an SSH server
This function is a coroutine which can be run to create an SSH server bound to the specified host and port. The return value is an AbstractServer object which can be used later to shut down the server.
Parameters: - server_factory (callable) – A callable which returns an SSHServer object that will be created for each new inbound connection
- host (string) – (optional) The hostname or address to listen on. If not specified, listeners are created for all addresses.
- port (integer) – (optional) The port number to listen on. If not specified, the default SSH port is used.
- loop – (optional) The event loop to use when creating the server. If not specified, the default event loop is used.
- family (socket.AF_UNSPEC, socket.AF_INET, or socket.AF_INET6) – (optional) The address family to use when creating the server. By default, the address families are automatically selected based on the host.
- flags (flags to pass to getaddrinfo()) – (optional) The flags to pass to getaddrinfo() when looking up the host
- backlog (integer) – (optional) The maximum number of queued connections allowed on listeners
- reuse_address (boolean) – (optional) Whether or not to reuse a local socket in the TIME_WAIT state without waiting for its natural timeout to expire. If not specified, this will be automatically set to True on UNIX.
- server_host_keys (see Specifying private keys) – A list of private keys and optional certificates which can be used by the server as a host key. This argument must be specified.
- authorized_client_keys (see Specifying authorized keys) – (optional) A list of authorized user and CA public keys which should be trusted for certifcate-based client public key authentication.
- kex_algs (list of strings) – (optional) A list of allowed key exchange algorithms in the SSH handshake, taken from key exchange algorithms
- encryption_algs (list of strings) – (optional) A list of encryption algorithms to use during the SSH handshake, taken from encryption algorithms
- mac_algs (list of strings) – (optional) A list of MAC algorithms to use during the SSH handshake, taken from MAC algorithms
- compression_algs (list of strings) – (optional) A list of compression algorithms to use during the SSH handshake, taken from compression algorithms, or None to disable compression
- allow_pty (boolean) – (optional) Whether or not to allow allocation of a pseudo-tty in sessions, defaulting to True
- session_factory (callable) – (optional) A callable or coroutine handler function which takes AsyncSSH stream objects for stdin, stdout, and stderr that will be called each time a new shell, exec, or subsytem other than SFTP is requested by the client. If not specified, sessions are rejected by default unless the session_requested() method is overridden on the SSHServer object returned by server_factory to make this decision.
- session_encoding (string) – (optional) The Unicode encoding to use for data exchanged on sessions on this server, defaulting to UTF-8 (ISO 10646) format. If None is passed in, the application can send and receive raw bytes.
- sftp_factory (callable) – (optional) A callable which returns an SFTPServer object that will be created each time an SFTP session is requested by the client, or True to use the base SFTPServer class to handle SFTP requests. If not specified, SFTP sessions are rejected by default.
- window (integer) – (optional) The receive window size for sessions on this server
- max_pktsize (integer) – (optional) The maximum packet size for sessions on this server
- rekey_bytes (integer) – (optional) The number of bytes which can be sent before the SSH session key is renegotiated, defaulting to 1 GB
- rekey_seconds (integer) – (optional) The maximum time in seconds before the SSH session key is renegotiated, defaulting to 1 hour
Returns: AbstractServer
connect¶
- asyncssh.connect(host, port=22, **kwargs)¶
Make an SSH client connection
This function is a coroutine wrapper around create_connection() which can be used when a custom SSHClient instance is not needed. It takes all the same arguments as create_connection() except for client_factory and returns only the SSHClientConnection object rather than a tuple of an SSHClientConnection and SSHClient.
When using this call, the following restrictions apply:
- No callbacks are called when the connection is successfully opened, when it is closed, or when authentication completes.
- Any authentication information must be provided as arguments to this call, as any authentication callbacks will deny other authentication attempts. Also, authentication banner information will be ignored.
- Any debug messages sent by the server will be ignored.
listen¶
- asyncssh.listen(host, port=22, *, server_host_keys, **kwargs)¶
Start an SSH server
This function is a coroutine wrapper around create_server() which can be used when a custom SSHServer instance is not needed. It takes all the same arguments as create_server() except for server_factory.
When using this call, the following restrictions apply:
- No callbacks are called when a new connection arrives, when a connection is closed, or when authentication completes.
- Any authentication information must be provided as arguments to this call, as any authentication callbacks will deny other authentication attempts. Currently, this allows only public key authentication to be used, by passing in the authorized_client_keys argument.
- Only handlers using the streams API are supported and the same handlers must be used for all clients. These handlers must be provided in the session_factory and/or sftp_factory arguments to this call.
- Any debug messages sent by the client will be ignored.