API Documentation

Overview

The AsyncSSH API is modeled after the new Python asyncio framework, with a create_connection() coroutine to create an SSH client and a create_server() coroutine to create an SSH server. Like the asyncio framework, these calls take a parameter of a factory which creates protocol objects to manage the connections once they are open. For AsyncSSH, create_connection() should be passed a client_factory which returns objects derived from SSHClient and create_server() should be passed a server_factory which returns objects derived from SSHServer. In addition, each connection will have an associated SSHClientConnection or SSHServerConnection object passed to the protocol objects which can be used to perform actions on the connection.

For client connections, authentication can be performed by passing in a username and password or SSH keys as arguments to create_connection() or by implementing handler methods on the SSHClient object which return credentials when the server requests them. If no credentials are provided, AsyncSSH automatically attempts to send the username of the local user and the keys found in their .ssh subdirectory. A list of expected server host keys can also be specified, with AsyncSSH defaulting to looking for matching lines in the user’s .ssh/known_hosts file.

For server connections, handlers can be implemented on the SSHServer object to return which authentication methods are supported and to validate credentials provided by clients.

Once an SSH client connection is established and authentication is successful, multiple simultaneous channels can be opened on it. This is accomplished calling methods such as create_session(), create_connection(), and create_unix_connection() on the SSHClientConnection object. The client can also set up listeners on remote TCP ports and UNIX domain sockets by calling create_server() and create_unix_server(). All of these methods take session_factory arguments that return SSHClientSession, SSHTCPSession, or SSHUNIXSession objects used to manage the channels once they are open. Alternately, channels can be opened using open_session(), open_connection(), or open_unix_connection(), which return SSHReader and SSHWriter objects that can be used to perform I/O on the channel. The methods start_server() and start_unix_server() can be used to set up listeners on remote TCP ports or UNIX domain sockets and get back these SSHReader and SSHWriter objects in a callback when new connections are opened.

SSH client sessions can also be opened by calling create_process(). This returns a SSHClientProcess object which has members stdin, stdout, and stderr which are SSHReader and SSHWriter objects. This API also makes it very easy to redirect input and output from the remote process to local files, pipes, sockets, or other SSHReader and SSHWriter objects. In cases where you just want to run a remote process to completion and get back an object containing captured output and exit status, the run() method can be used. It returns an SSHCompletedProcess with the results of the run, or can be set up to raise ProcessError if the process exits with a non-zero exit status. It can also raise TimeoutError if a specified timeout expires before the process exits.

The client can also set up TCP port forwarding by calling forward_local_port() or forward_remote_port() and UNIX domain socket forwarding by calling forward_local_path() or forward_remote_path(). In these cases, data transfer on the channels is managed automatically by AsyncSSH whenever new connections are opened, so custom session objects are not required.

Dynamic TCP port forwarding can be set up by calling forward_socks(). The SOCKS listener set up by AsyncSSH on the requested port accepts SOCKS connect requests and is compatible with SOCKS versions 4, 4a, and 5.

When an SSH server receives a new connection and authentication is successful, handlers such as session_requested(), connection_requested(), unix_connection_requested(), server_requested(), and unix_server_requested() on the associated SSHServer object will be called when clients attempt to open channels or set up listeners. These methods return coroutines which can set up the requested sessions or connections, returning SSHServerSession or SSHTCPSession objects or handler functions that accept SSHReader and SSHWriter objects as arguments which manage the channels once they are open.

To better support interactive server applications, AsyncSSH defaults to providing echoing of input and basic line editing capabilities when an inbound SSH session requests a pseudo-terminal. This behavior can be disabled by setting the line_editor argument to False when starting up an SSH server. When this feature is enabled, server sessions can enable or disable line mode using the set_line_mode() method of SSHLineEditorChannel. They can also enable or disable input echoing using the set_echo() method. Handling of specific keys during line editing can be customized using the register_key() and unregister_key() methods.

Each session object also has an associated SSHClientChannel, SSHServerChannel, or SSHTCPChannel object passed to it which can be used to perform actions on the channel. These channel objects provide a superset of the functionality found in asyncio transport objects.

In addition to the above functions and classes, helper functions for importing public and private keys can be found below under Public Key Support, exceptions can be found under Exceptions, supported algorithms can be found under Supported Algorithms, and some useful constants can be found under Constants.

Main Functions

connect

asyncssh.connect(host, port=22, *, tunnel=None, family=0, flags=0, local_addr=None, options=None, **kwargs)

Make 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:

1. The connection is established and an instance of SSHClientConnection is created to represent it.

2. The client_factory is called without arguments and should return an instance of SSHClient or a subclass.

3. The client object is tied to the connection and its connection_made() method is called.

4. The SSH handshake and authentication process is initiated, calling methods on the client object if needed.

5. When authentication completes successfully, the client’s auth_completed() method is called.

6. The coroutine returns the SSHClientConnection. 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.

Note

Unlike socket.create_connection(), asyncio calls to create a connection do not support a timeout parameter. However, asyncio calls can be wrapped in a call to asyncio.wait_for() or asyncio.wait() which takes a timeout and provides equivalent functionality.

Parameters

• host (str) – The hostname or address to connect to.

• port (int) – (optional) The port number to connect to. If not specified, the default SSH port is used.

• tunnel (SSHClientConnection) – (optional) An existing SSH client connection that this new connection should be tunneled over. If set, a direct TCP/IP tunnel will be opened over this connection to the requested host and port rather than connecting directly via TCP.

• 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 str and int) – (optional) The host and port to bind the socket to before connecting

• options (SSHClientConnectionOptions) – (optional) Options to use when establishing the SSH client connection. These options can be specified either through this parameter or as direct keyword arguments to this function.

Returns

SSHClientConnection

connect_reverse

asyncssh.connect_reverse(host, port=22, *, tunnel=None, family=0, flags=0, local_addr=None, options=None, **kwargs)

Create a reverse direction SSH connection

This function is a coroutine which behaves similar to connect(), making an outbound TCP connection to a remote server. However, instead of starting up an SSH client which runs on that outbound connection, this function starts up an SSH server, expecting the remote system to start up a reverse-direction SSH client.

Arguments to this function are the same as connect(), except that the options are of type SSHServerConnectionOptions instead of SSHClientConnectionOptions.

Parameters

• host (str) – The hostname or address to connect to.

• port (int) – (optional) The port number to connect to. If not specified, the default SSH port is used.

• tunnel (SSHClientConnection) – (optional) An existing SSH client connection that this new connection should be tunneled over. If set, a direct TCP/IP tunnel will be opened over this connection to the requested host and port rather than connecting directly via TCP.

• 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 str and int) – (optional) The host and port to bind the socket to before connecting

• options (SSHServerConnectionOptions) – (optional) Options to use when starting the reverse-direction SSH server. These options can be specified either through this parameter or as direct keyword arguments to this function.

Returns

SSHServerConnection

listen

asyncssh.listen(host=None, port=22, tunnel=None, family=0, flags=<AddressInfo.AI_PASSIVE: 1>, backlog=100, reuse_address=None, reuse_port=None, acceptor=None, error_handler=None, options=None, **kwargs)

Start an SSH server

This function is a coroutine which can be run to create an SSH server listening on the specified host and port. The return value is an asyncio.Server which can be used to shut down the listener.

Parameters

• host (str) – (optional) The hostname or address to listen on. If not specified, listeners are created for all addresses.

• port (int) – (optional) The port number to listen on. If not specified, the default SSH port is used.

• tunnel (SSHClientConnection) – (optional) An existing SSH client connection that this new listener should be forwarded over. If set, a remote TCP/IP listener will be opened on this connection on the requested host and port rather than listening directly via TCP.

• 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 (int) – (optional) The maximum number of queued connections allowed on listeners

• reuse_address (bool) – (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.

• reuse_port (bool) – (optional) Whether or not to allow this socket to be bound to the same port other existing sockets are bound to, so long as they all set this flag when being created. If not specified, the default is to not allow this. This option is not supported on Windows or Python versions prior to 3.4.4.

• acceptor – (optional) A callable or coroutine which will be called when the SSH handshake completes on an accepted connection, taking the SSHServerConnection as an argument.

• error_handler – (optional) A callable which will be called whenever the SSH handshake fails on an accepted connection. It is called with the failed SSHServerConnection and an exception object describing the failure. If not specified, failed handshakes result in the connection object being silently cleaned up.

• options (SSHServerConnectionOptions) – (optional) Options to use when accepting SSH server connections. These options can be specified either through this parameter or as direct keyword arguments to this function.

Returns

asyncio.Server

listen_reverse

asyncssh.listen_reverse(host=None, port=22, *, tunnel=None, family=0, flags=<AddressInfo.AI_PASSIVE: 1>, backlog=100, reuse_address=None, reuse_port=None, acceptor=None, error_handler=None, options=None, **kwargs)

Create a reverse-direction SSH listener

This function is a coroutine which behaves similar to listen(), creating a listener which accepts inbound connections on the specified host and port. However, instead of starting up an SSH server on each inbound connection, it starts up a reverse-direction SSH client, expecting the remote system making the connection to start up a reverse-direction SSH server.

Arguments to this function are the same as listen(), except that the options are of type SSHClientConnectionOptions instead of SSHServerConnectionOptions.

The return value is an asyncio.Server which can be used to shut down the reverse listener.

Parameters

• host (str) – (optional) The hostname or address to listen on. If not specified, listeners are created for all addresses.

• port (int) – (optional) The port number to listen on. If not specified, the default SSH port is used.

• tunnel (SSHClientConnection) – (optional) An existing SSH client connection that this new listener should be forwarded over. If set, a remote TCP/IP listener will be opened on this connection on the requested host and port rather than listening directly via TCP.

• 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 (int) – (optional) The maximum number of queued connections allowed on listeners

• reuse_address (bool) – (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.

• reuse_port (bool) – (optional) Whether or not to allow this socket to be bound to the same port other existing sockets are bound to, so long as they all set this flag when being created. If not specified, the default is to not allow this. This option is not supported on Windows or Python versions prior to 3.4.4.

• acceptor – (optional) A callable or coroutine which will be called when the SSH handshake completes on an accepted connection, taking the SSHClientConnection as an argument.

• error_handler – (optional) A callable which will be called whenever the SSH handshake fails on an accepted connection. It is called with the failed SSHClientConnection and an exception object describing the failure. If not specified, failed handshakes result in the connection object being silently cleaned up.

• options (SSHClientConnectionOptions) – (optional) Options to use when starting reverse-direction SSH clients. These options can be specified either through this parameter or as direct keyword arguments to this function.

Returns

asyncio.Server

create_connection

async asyncssh.create_connection(client_factory, host, port=22, **kwargs)

Create an SSH client connection

This is a coroutine which wraps around connect(), providing backward compatibility with older AsyncSSH releases. The only differences are that the client_factory argument is the first positional argument in this call rather than being a keyword argument or specified via an SSHClientConnectionOptions object and the return value is a tuple of an SSHClientConnection and SSHClient rather than just the connection, mirroring asyncio.BaseEventLoop.create_connection().

Returns

An SSHClientConnection and SSHClient

create_server

asyncssh.create_server(server_factory, host=None, port=22, **kwargs)

Create an SSH server

This is a coroutine which wraps around listen(), providing backward compatibility with older AsyncSSH releases. The only difference is that the server_factory argument is the first positional argument in this call rather than being a keyword argument or specified via an SSHServerConnectionOptions object, mirroring asyncio.BaseEventLoop.create_server().

get_server_host_key

async asyncssh.get_server_host_key(host, port=22, *, tunnel=None, family=0, flags=0, local_addr=None, client_version=(), kex_algs=(), server_host_key_algs=())

Retrieve an SSH server’s host key

This is a coroutine which can be run to connect to an SSH server and return the server host key presented during the SSH handshake.

A list of server host key algorithms can be provided to specify which host key types the server is allowed to choose from. If the key exchange is successful, the server host key sent during the handshake is returned.

Note

Not all key exchange methods involve the server presenting a host key. If something like GSS key exchange is used without a server host key, this method may return None even when the handshake completes.

Parameters

• host (str) – The hostname or address to connect to

• port (int) – (optional) The port number to connect to. If not specified, the default SSH port is used.

• tunnel (SSHClientConnection) – (optional) An existing SSH client connection that this new connection should be tunneled over. If set, a direct TCP/IP tunnel will be opened over this connection to the requested host and port rather than connecting directly via TCP.

• 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 str and int) – (optional) The host and port to bind the socket to before connecting

• client_version (str) – (optional) An ASCII string to advertise to the SSH server as the version of this client, defaulting to 'AsyncSSH' and its version number.

• kex_algs (list of str) – (optional) A list of allowed key exchange algorithms in the SSH handshake, taken from key exchange algorithms

• server_host_key_algs (list of str) – (optional) A list of server host key algorithms to allow during the SSH handshake, taken from server host key algorithms.

Returns

An SSHKey public key or None

scp

async asyncssh.scp(srcpaths, dstpath=None, *, preserve=False, recurse=False, block_size=16384, progress_handler=None, error_handler=None, **kwargs)

Copy files using SCP

This function is a coroutine which copies one or more files or directories using the SCP protocol. Source and destination paths can be str or bytes values to reference local files or can be a tuple of the form (conn, path) where conn is an open SSHClientConnection to reference files and directories on a remote system.

For convenience, a host name or tuple of the form (host, port) can be provided in place of the SSHClientConnection to request that a new SSH connection be opened to a host using default connect arguments. A str or bytes value of the form 'host:path' may also be used in place of the (conn, path) tuple to make a new connection to the requested host on the default SSH port.

Either a single source path or a sequence of source paths can be provided, and each path can contain ‘*’ and ‘?’ wildcard characters which can be used to match multiple source files or directories.

When copying a single file or directory, the destination path can be either the full path to copy data into or the path to an existing directory where the data should be placed. In the latter case, the base file name from the source path will be used as the destination name.

When copying multiple files, the destination path must refer to a directory. If it doesn’t already exist, a directory will be created with that name.

If the destination path is an SSHClientConnection without a path or the path provided is empty, files are copied into the default destination working directory.

If preserve is True, the access and modification times and permissions of the original files and directories are set on the copied files. However, do to the timing of when this information is sent, the preserved access time will be what was set on the source file before the copy begins. So, the access time on the source file will no longer match the destination after the transfer completes.

If recurse is True and the source path points at a directory, the entire subtree under that directory is copied.

Symbolic links found on the source will have the contents of their target copied rather than creating a destination symbolic link. When using this option during a recursive copy, one needs to watch out for links that result in loops. SCP does not provide a mechanism for preserving links. If you need this, consider using SFTP instead.

The block_size value controls the size of read and write operations issued to copy the files. It defaults to 16 KB.

If progress_handler is specified, it will be called after each block of a file is successfully copied. The arguments passed to this handler will be the relative path of the file being copied, bytes copied so far, and total bytes in the file being copied. If multiple source paths are provided or recurse is set to True, the progress_handler will be called consecutively on each file being copied.

If error_handler is specified and an error occurs during the copy, this handler will be called with the exception instead of it being raised. This is intended to primarily be used when multiple source paths are provided or when recurse is set to True, to allow error information to be collected without aborting the copy of the remaining files. The error handler can raise an exception if it wants the copy to completely stop. Otherwise, after an error, the copy will continue starting with the next file.

If any other keyword arguments are specified, they will be passed to the AsyncSSH connect() call when attempting to open any new SSH connections needed to perform the file transfer.

Parameters

• srcpaths – The paths of the source files or directories to copy

• dstpath – (optional) The path of the destination file or directory to copy into

• preserve (bool) – (optional) Whether or not to preserve the original file attributes

• recurse (bool) – (optional) Whether or not to recursively copy directories

• block_size (int) – (optional) The block size to use for file reads and writes

• progress_handler (callable) – (optional) The function to call to report copy progress

• error_handler (callable) – (optional) The function to call when an error occurs

Raises

OSError if a local file I/O error occurs

SFTPError if the server returns an error

ValueError if both source and destination are local

Main Classes

SSHClient

class asyncssh.SSHClient

SSH client protocol handler

Applications may subclass this when implementing an SSH client to receive callbacks when certain events occur on the SSH connection.

For simple password or public key based authentication, nothing needs to be defined here if the password or client keys are passed in when the connection is created. However, to prompt interactively or otherwise dynamically select these values, the methods password_auth_requested() and/or public_key_auth_requested() can be defined. Keyboard-interactive authentication is also supported via kbdint_auth_requested() and kbdint_challenge_received().

If the server sends an authentication banner, the method auth_banner_received() will be called.

If the server requires a password change, the method password_change_requested() will be called, followed by either password_changed() or password_change_failed() depending on whether the password change is successful.

Note

The authentication callbacks described here can be defined as coroutines. However, they may be cancelled if they are running when the SSH connection is closed by the server. If they attempt to catch the CancelledError exception to perform cleanup, they should make sure to re-raise it to allow AsyncSSH to finish its own cleanup.

General connection handlers
connection_made(conn) Called when a connection is made This method is called as soon as the TCP connection completes. The conn parameter should be stored if needed for later use. Parameters conn (SSHClientConnection) – The connection which was successfully opened
connection_lost(exc) Called when a connection is lost or closed This method is called when a connection is closed. If the connection is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason for the disconnect. Parameters exc (Exception) – The exception which caused the connection to close, or None if the connection closed cleanly
debug_msg_received(msg, lang, always_display) A debug message was received on this connection This method is called when the other end of the connection sends a debug message. Applications should implement this method if they wish to process these debug messages. Parameters msg (str) – The debug message sent lang (str) – The language the message is in always_display (bool) – Whether or not to display the message

Host key validation handlers
validate_host_public_key(host, addr, port, key) Return whether key is an authorized key for this host Server host key validation can be supported by passing known host keys in the known_hosts argument of create_connection(). However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid host key for the server being connected to. By default, this method returns False for all host keys. Note This function only needs to report whether the public key provided is a valid key for this host. If it is, AsyncSSH will verify that the server possesses the corresponding private key before allowing the validation to succeed. Parameters host (str) – The hostname of the target host addr (str) – The IP address of the target host port (int) – The port number on the target host key (SSHKey public key) – The public key sent by the server Returns A bool indicating if the specified key is a valid key for the target host
validate_host_ca_key(host, addr, port, key) Return whether key is an authorized CA key for this host Server host certificate validation can be supported by passing known host CA keys in the known_hosts argument of create_connection(). However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid certificate authority key for the server being connected to. By default, this method returns False for all CA keys. Note This function only needs to report whether the public key provided is a valid CA key for this host. If it is, AsyncSSH will verify that the certificate is valid, that the host is one of the valid principals for the certificate, and that the server possesses the private key corresponding to the public key in the certificate before allowing the validation to succeed. Parameters host (str) – The hostname of the target host addr (str) – The IP address of the target host port (int) – The port number on the target host key (SSHKey public key) – The public key which signed the certificate sent by the server Returns A bool indicating if the specified key is a valid CA key for the target host

General authentication handlers
auth_banner_received(msg, lang) An incoming authentication banner was received This method is called when the server sends a banner to display during authentication. Applications should implement this method if they wish to do something with the banner. Parameters msg (str) – The message the server wanted to display lang (str) – The language the message is in
auth_completed() Authentication was completed successfully This method is called when authentication has completed succesfully. Applications may use this method to create whatever client sessions and direct TCP/IP or UNIX domain connections are needed and/or set up listeners for incoming TCP/IP or UNIX domain connections coming from the server. However, create_connection() now blocks until authentication is complete, so any code which wishes to use the SSH connection can simply follow that call and doesn’t need to be performed in a callback.

Public key authentication handlers

public_key_auth_requested() Public key authentication has been requested This method should return a private key corresponding to the user that authentication is being attempted for. This method may be called multiple times and can return a different key to try each time it is called. When there are no keys left to try, it should return None to indicate that some other authentication method should be tried. If client keys were provided when the connection was opened, they will be tried before this method is called. If blocking operations need to be performed to determine the key to authenticate with, this method may be defined as a coroutine. Returns A key as described in Specifying private keys or None to move on to another authentication method

Password authentication handlers
password_auth_requested() Password authentication has been requested This method should return a string containing the password corresponding to the user that authentication is being attempted for. It may be called multiple times and can return a different password to try each time, but most servers have a limit on the number of attempts allowed. When there’s no password left to try, this method should return None to indicate that some other authentication method should be tried. If a password was provided when the connection was opened, it will be tried before this method is called. If blocking operations need to be performed to determine the password to authenticate with, this method may be defined as a coroutine. Returns A string containing the password to authenticate with or None to move on to another authentication method
password_change_requested(prompt, lang) A password change has been requested This method is called when password authentication was attempted and the user’s password was expired on the server. To request a password change, this method should return a tuple or two strings containing the old and new passwords. Otherwise, it should return NotImplemented. If blocking operations need to be performed to determine the passwords to authenticate with, this method may be defined as a coroutine. By default, this method returns NotImplemented. Parameters prompt (str) – The prompt requesting that the user enter a new password lang (str) – The language that the prompt is in Returns A tuple of two strings containing the old and new passwords or NotImplemented if password changes aren’t supported
password_changed() The requested password change was successful This method is called to indicate that a requested password change was successful. It is generally followed by a call to auth_completed() since this means authentication was also successful.
password_change_failed() The requested password change has failed This method is called to indicate that a requested password change failed, generally because the requested new password doesn’t meet the password criteria on the remote system. After this method is called, other forms of authentication will automatically be attempted.

Keyboard-interactive authentication handlers
kbdint_auth_requested() Keyboard-interactive authentication has been requested This method should return a string containing a comma-separated list of submethods that the server should use for keyboard-interactive authentication. An empty string can be returned to let the server pick the type of keyboard-interactive authentication to perform. If keyboard-interactive authentication is not supported, None should be returned. By default, keyboard-interactive authentication is supported if a password was provided when the SSHClient was created and it hasn’t been sent yet. If the challenge is not a password challenge, this authentication will fail. This method and the kbdint_challenge_received() method can be overridden if other forms of challenge should be supported. If blocking operations need to be performed to determine the submethods to request, this method may be defined as a coroutine. Returns A string containing the submethods the server should use for authentication or None to move on to another authentication method
kbdint_challenge_received(name, instructions, lang, prompts) A keyboard-interactive auth challenge has been received This method is called when the server sends a keyboard-interactive authentication challenge. The return value should be a list of strings of the same length as the number of prompts provided if the challenge can be answered, or None to indicate that some other form of authentication should be attempted. If blocking operations need to be performed to determine the responses to authenticate with, this method may be defined as a coroutine. By default, this method will look for a challenge consisting of a single ‘Password:’ prompt, and call the method password_auth_requested() to provide the response. It will also ignore challenges with no prompts (generally used to provide instructions). Any other form of challenge will cause this method to return None to move on to another authentication method. Parameters name (str) – The name of the challenge instructions (str) – Instructions to the user about how to respond to the challenge lang (str) – The language the challenge is in prompts (list of tuples of str and bool) – The challenges the user should respond to and whether or not the responses should be echoed when they are entered Returns List of string responses to the challenge or None to move on to another authentication method

SSHServer

class asyncssh.SSHServer

SSH server protocol handler

Applications may subclass this when implementing an SSH server to provide custom authentication and request handlers.

The method begin_auth() can be overridden decide whether or not authentication is required, and additional callbacks are provided for each form of authentication in cases where authentication information is not provided in the call to create_server().

In addition, the methods session_requested(), connection_requested(), server_requested(), unix_connection_requested(), or unix_server_requested() can be overridden to handle requests to open sessions or direct connections or set up listeners for forwarded connections.

Note

The authentication callbacks described here can be defined as coroutines. However, they may be cancelled if they are running when the SSH connection is closed by the client. If they attempt to catch the CancelledError exception to perform cleanup, they should make sure to re-raise it to allow AsyncSSH to finish its own cleanup.

General connection handlers
connection_made(conn) Called when a connection is made This method is called when a new TCP connection is accepted. The conn parameter should be stored if needed for later use. Parameters conn (SSHServerConnection) – The connection which was successfully opened
connection_lost(exc) Called when a connection is lost or closed This method is called when a connection is closed. If the connection is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason for the disconnect.
debug_msg_received(msg, lang, always_display) A debug message was received on this connection This method is called when the other end of the connection sends a debug message. Applications should implement this method if they wish to process these debug messages. Parameters msg (str) – The debug message sent lang (str) – The language the message is in always_display (bool) – Whether or not to display the message

General authentication handlers
begin_auth(username) Authentication has been requested by the client This method will be called when authentication is attempted for the specified user. Applications should use this method to prepare whatever state they need to complete the authentication, such as loading in the set of authorized keys for that user. If no authentication is required for this user, this method should return False to cause the authentication to immediately succeed. Otherwise, it should return True to indicate that authentication should proceed. If blocking operations need to be performed to prepare the state needed to complete the authentication, this method may be defined as a coroutine. Parameters username (str) – The name of the user being authenticated Returns A bool indicating whether authentication is required
auth_completed() Authentication was completed successfully This method is called when authentication has completed succesfully. Applications may use this method to perform processing based on the authenticated username or options in the authorized keys list or certificate associated with the user before any sessions are opened or forwarding requests are handled.

GSSAPI authentication handlers

validate_gss_principal(username, user_principal, host_principal) Return whether a GSS principal is valid for this user This method should return True if the specified user principal is valid for the user being authenticated. It can be overridden by applications wishing to perform their own authentication. If blocking operations need to be performed to determine the validity of the principal, this method may be defined as a coroutine. By default, this method will return True only when the name in the user principal exactly matches the username and the domain of the user principal matches the domain of the host principal. Parameters username (str) – The user being authenticated user_principal (str) – The user principal sent by the client host_principal (str) – The host principal sent by the server Returns A bool indicating if the specified user principal is valid for the user being authenticated

Host-based authentication handlers
host_based_auth_supported() Return whether or not host-based authentication is supported This method should return True if client host-based authentication is supported. Applications wishing to support it must have this method return True and implement validate_host_public_key() and/or validate_host_ca_key() to return whether or not the key provided by the client is valid for the client host being authenticated. By default, it returns False indicating the client host based authentication is not supported. Returns A bool indicating if host-based authentication is supported or not
validate_host_public_key(client_host, client_addr, client_port, key) Return whether key is an authorized host key for this client host Host key based client authentication can be supported by passing authorized host keys in the known_client_hosts argument of create_server(). However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid host key for the client host being authenticated. This method may be called multiple times with different keys provided by the client. Applications should precompute as much as possible in the begin_auth() method so that this function can quickly return whether the key provided is in the list. By default, this method returns False for all client host keys. Note This function only needs to report whether the public key provided is a valid key for this client host. If it is, AsyncSSH will verify that the client possesses the corresponding private key before allowing the authentication to succeed. Parameters client_host (str) – The hostname of the client host client_addr (str) – The IP address of the client host client_port (int) – The port number on the client host key (SSHKey public key) – The host public key sent by the client Returns A bool indicating if the specified key is a valid key for the client host being authenticated
validate_host_ca_key(client_host, client_addr, client_port, key) Return whether key is an authorized CA key for this client host Certificate based client host authentication can be supported by passing authorized host CA keys in the known_client_hosts argument of create_server(). However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid certificate authority key for the client host being authenticated. This method may be called multiple times with different keys provided by the client. Applications should precompute as much as possible in the begin_auth() method so that this function can quickly return whether the key provided is in the list. By default, this method returns False for all CA keys. Note This function only needs to report whether the public key provided is a valid CA key for this client host. If it is, AsyncSSH will verify that the certificate is valid, that the client host is one of the valid principals for the certificate, and that the client possesses the private key corresponding to the public key in the certificate before allowing the authentication to succeed. Parameters client_host (str) – The hostname of the client host client_addr (str) – The IP address of the client host client_port (int) – The port number on the client host key (SSHKey public key) – The public key which signed the certificate sent by the client Returns A bool indicating if the specified key is a valid CA key for the client host being authenticated
validate_host_based_user(username, client_host, client_username) Return whether remote host and user is authorized for this user This method should return True if the specified client host and user is valid for the user being authenticated. It can be overridden by applications wishing to enforce restrictions on which remote users are allowed to authenticate as particular local users. If blocking operations need to be performed to determine the validity of the client host and user, this method may be defined as a coroutine. By default, this method will return True when the client username matches the name of the user being authenticated. Parameters username (str) – The user being authenticated client_host (str) – The hostname of the client host making the request client_username (str) – The username of the user on the client host Returns A bool indicating if the specified client host and user is valid for the user being authenticated

Public key authentication handlers
public_key_auth_supported() Return whether or not public key authentication is supported This method should return True if client public key authentication is supported. Applications wishing to support it must have this method return True and implement validate_public_key() and/or validate_ca_key() to return whether or not the key provided by the client is valid for the user being authenticated. By default, it returns False indicating the client public key authentication is not supported. Returns A bool indicating if public key authentication is supported or not
validate_public_key(username, key) Return whether key is an authorized client key for this user Key based client authentication can be supported by passing authorized keys in the authorized_client_keys argument of create_server(), or by calling set_authorized_keys on the server connection from the begin_auth() method. However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid client key for the user being authenticated. This method may be called multiple times with different keys provided by the client. Applications should precompute as much as possible in the begin_auth() method so that this function can quickly return whether the key provided is in the list. If blocking operations need to be performed to determine the validity of the key, this method may be defined as a coroutine. By default, this method returns False for all client keys. Note This function only needs to report whether the public key provided is a valid client key for this user. If it is, AsyncSSH will verify that the client possesses the corresponding private key before allowing the authentication to succeed. Parameters username (str) – The user being authenticated key (SSHKey public key) – The public key sent by the client Returns A bool indicating if the specified key is a valid client key for the user being authenticated
validate_ca_key(username, key) Return whether key is an authorized CA key for this user Certificate based client authentication can be supported by passing authorized CA keys in the authorized_client_keys argument of create_server(), or by calling set_authorized_keys on the server connection from the begin_auth() method. However, for more flexibility in matching on the allowed set of keys, this method can be implemented by the application to do the matching itself. It should return True if the specified key is a valid certificate authority key for the user being authenticated. This method may be called multiple times with different keys provided by the client. Applications should precompute as much as possible in the begin_auth() method so that this function can quickly return whether the key provided is in the list. If blocking operations need to be performed to determine the validity of the key, this method may be defined as a coroutine. By default, this method returns False for all CA keys. Note This function only needs to report whether the public key provided is a valid CA key for this user. If it is, AsyncSSH will verify that the certificate is valid, that the user is one of the valid principals for the certificate, and that the client possesses the private key corresponding to the public key in the certificate before allowing the authentication to succeed. Parameters username (str) – The user being authenticated key (SSHKey public key) – The public key which signed the certificate sent by the client Returns A bool indicating if the specified key is a valid CA key for the user being authenticated

Password authentication handlers
password_auth_supported() Return whether or not password authentication is supported This method should return True if password authentication is supported. Applications wishing to support it must have this method return True and implement validate_password() to return whether or not the password provided by the client is valid for the user being authenticated. By default, this method returns False indicating that password authentication is not supported. Returns A bool indicating if password authentication is supported or not
validate_password(username, password) Return whether password is valid for this user This method should return True if the specified password is a valid password for the user being authenticated. It must be overridden by applications wishing to support password authentication. If the password provided is valid but expired, this method may raise PasswordChangeRequired to request that the client provide a new password before authentication is allowed to complete. In this case, the application must override change_password() to handle the password change request. This method may be called multiple times with different passwords provided by the client. Applications may wish to limit the number of attempts which are allowed. This can be done by having password_auth_supported() begin returning False after the maximum number of attempts is exceeded. If blocking operations need to be performed to determine the validity of the password, this method may be defined as a coroutine. By default, this method returns False for all passwords. Parameters username (str) – The user being authenticated password (str) – The password sent by the client Returns A bool indicating if the specified password is valid for the user being authenticated Raises PasswordChangeRequired if the password provided is expired and needs to be changed
change_password(username, old_password, new_password) Handle a request to change a user’s password This method is called when a user makes a request to change their password. It should first validate that the old password provided is correct and then attempt to change the user’s password to the new value. If the old password provided is valid and the change to the new password is successful, this method should return True. If the old password is not valid or password changes are not supported, it should return False. It may also raise PasswordChangeRequired to request that the client try again if the new password is not acceptable for some reason. If blocking operations need to be performed to determine the validity of the old password or to change to the new password, this method may be defined as a coroutine. By default, this method returns False, rejecting all password changes. Parameters username (str) – The user whose password should be changed old_password (str) – The user’s current password new_password (str) – The new password being requested Returns A bool indicating if the password change is successful or not Raises PasswordChangeRequired if the new password is not acceptable and the client should be asked to provide another

Keyboard-interactive authentication handlers
kbdint_auth_supported() Return whether or not keyboard-interactive authentication is supported This method should return True if keyboard-interactive authentication is supported. Applications wishing to support it must have this method return True and implement get_kbdint_challenge() and validate_kbdint_response() to generate the apporiate challenges and validate the responses for the user being authenticated. By default, this method returns NotImplemented tying this authentication to password authentication. If the application implements password authentication and this method is not overridden, keyboard-interactive authentication will be supported by prompting for a password and passing that to the password authentication callbacks. Returns A bool indicating if keyboard-interactive authentication is supported or not
get_kbdint_challenge(username, lang, submethods) Return a keyboard-interactive auth challenge This method should return True if authentication should succeed without any challenge, False if authentication should fail without any challenge, or an auth challenge consisting of a challenge name, instructions, a language tag, and a list of tuples containing prompt strings and booleans indicating whether input should be echoed when a value is entered for that prompt. If blocking operations need to be performed to determine the challenge to issue, this method may be defined as a coroutine. Parameters username (str) – The user being authenticated lang (str) – The language requested by the client for the challenge submethods (str) – A comma-separated list of the types of challenges the client can support, or the empty string if the server should choose Returns An authentication challenge as described above
validate_kbdint_response(username, responses) Return whether the keyboard-interactive response is valid for this user This method should validate the keyboard-interactive responses provided and return True if authentication should succeed with no further challenge, False if authentication should fail, or an additional auth challenge in the same format returned by get_kbdint_challenge(). Any series of challenges can be returned this way. To print a message in the middle of a sequence of challenges without prompting for additional data, a challenge can be returned with an empty list of prompts. After the client acknowledges this message, this function will be called again with an empty list of responses to continue the authentication. If blocking operations need to be performed to determine the validity of the response or the next challenge to issue, this method may be defined as a coroutine. Parameters username (str) – The user being authenticated responses (list of str) – A list of responses to the last challenge Returns True, False, or the next challenge

Channel session open handlers
session_requested() Handle an incoming session request This method is called when a session open request is received from the client, indicating it wishes to open a channel to be used for running a shell, executing a command, or connecting to a subsystem. If the application wishes to accept the session, it must override this method to return either an SSHServerSession object to use to process the data received on the channel or a tuple consisting of an SSHServerChannel object created with create_server_channel and an SSHServerSession, if the application wishes to pass non-default arguments when creating the channel. If blocking operations need to be performed before the session can be created, a coroutine which returns an SSHServerSession object can be returned instead of the session iself. This can be either returned directly or as a part of a tuple with an SSHServerChannel object. To reject this request, this method should return False to send back a “Session refused” response or raise a ChannelOpenError exception with the reason for the failure. The details of what type of session the client wants to start will be delivered to methods on the SSHServerSession object which is returned, along with other information such as environment variables, terminal type, size, and modes. By default, all session requests are rejected. Returns One of the following: An SSHServerSession object or a coroutine which returns an SSHServerSession A tuple consisting of an SSHServerChannel and the above A callable or coroutine handler function which takes AsyncSSH stream objects for stdin, stdout, and stderr as arguments A tuple consisting of an SSHServerChannel and the above False to refuse the request Raises ChannelOpenError if the session shouldn’t be accepted
connection_requested(dest_host, dest_port, orig_host, orig_port) Handle a direct TCP/IP connection request This method is called when a direct TCP/IP connection request is received by the server. Applications wishing to accept such connections must override this method. To allow standard port forwarding of data on the connection to the requested destination host and port, this method should return True. To reject this request, this method should return False to send back a “Connection refused” response or raise an ChannelOpenError exception with the reason for the failure. If the application wishes to process the data on the connection itself, this method should return either an SSHTCPSession object which can be used to process the data received on the channel or a tuple consisting of of an SSHTCPChannel object created with create_tcp_channel() and an SSHTCPSession, if the application wishes to pass non-default arguments when creating the channel. If blocking operations need to be performed before the session can be created, a coroutine which returns an SSHTCPSession object can be returned instead of the session iself. This can be either returned directly or as a part of a tuple with an SSHTCPChannel object. By default, all connection requests are rejected. Parameters dest_host (str) – The address the client wishes to connect to dest_port (int) – The port the client wishes to connect to orig_host (str) – The address the connection was originated from orig_port (int) – The port the connection was originated from Returns One of the following: An SSHTCPSession object or a coroutine which returns an SSHTCPSession A tuple consisting of an SSHTCPChannel and the above A callable or coroutine handler function which takes AsyncSSH stream objects for reading from and writing to the connection A tuple consisting of an SSHTCPChannel and the above True to request standard port forwarding False to refuse the connection Raises ChannelOpenError if the connection shouldn’t be accepted
unix_connection_requested(dest_path) Handle a direct UNIX domain socket connection request This method is called when a direct UNIX domain socket connection request is received by the server. Applications wishing to accept such connections must override this method. To allow standard path forwarding of data on the connection to the requested destination path, this method should return True. To reject this request, this method should return False to send back a “Connection refused” response or raise an ChannelOpenError exception with the reason for the failure. If the application wishes to process the data on the connection itself, this method should return either an SSHUNIXSession object which can be used to process the data received on the channel or a tuple consisting of of an SSHUNIXChannel object created with create_unix_channel() and an SSHUNIXSession, if the application wishes to pass non-default arguments when creating the channel. If blocking operations need to be performed before the session can be created, a coroutine which returns an SSHUNIXSession object can be returned instead of the session iself. This can be either returned directly or as a part of a tuple with an SSHUNIXChannel object. By default, all connection requests are rejected. Parameters dest_path (str) – The path the client wishes to connect to Returns One of the following: An SSHUNIXSession object or a coroutine which returns an SSHUNIXSession A tuple consisting of an SSHUNIXChannel and the above A callable or coroutine handler function which takes AsyncSSH stream objects for reading from and writing to the connection A tuple consisting of an SSHUNIXChannel and the above True to request standard path forwarding False to refuse the connection Raises ChannelOpenError if the connection shouldn’t be accepted
server_requested(listen_host, listen_port) Handle a request to listen on a TCP/IP address and port This method is called when a client makes a request to listen on an address and port for incoming TCP connections. The port to listen on may be 0 to request a dynamically allocated port. Applications wishing to allow TCP/IP connection forwarding must override this method. To set up standard port forwarding of connections received on this address and port, this method should return True. If the application wishes to manage listening for incoming connections itself, this method should return an SSHListener object that listens for new connections and calls create_connection on each of them to forward them back to the client or return None if the listener can’t be set up. If blocking operations need to be performed to set up the listener, a coroutine which returns an SSHListener can be returned instead of the listener itself. To reject this request, this method should return False. By default, this method rejects all server requests. Parameters listen_host (str) – The address the server should listen on listen_port (int) – The port the server should listen on, or the value 0 to request that the server dynamically allocate a port Returns One of the following: An SSHListener object True to set up standard port forwarding False to reject the request A coroutine object which returns one of the above
unix_server_requested(listen_path) Handle a request to listen on a UNIX domain socket This method is called when a client makes a request to listen on a path for incoming UNIX domain socket connections. Applications wishing to allow UNIX domain socket forwarding must override this method. To set up standard path forwarding of connections received on this path, this method should return True. If the application wishes to manage listening for incoming connections itself, this method should return an SSHListener object that listens for new connections and calls create_unix_connection on each of them to forward them back to the client or return None if the listener can’t be set up. If blocking operations need to be performed to set up the listener, a coroutine which returns an SSHListener can be returned instead of the listener itself. To reject this request, this method should return False. By default, this method rejects all server requests. Parameters listen_path (str) – The path the server should listen on Returns One of the following: An SSHListener object or a coroutine which returns an SSHListener or False if the listener can’t be opened True to set up standard path forwarding False to reject the request

Connection Classes

SSHClientConnection

class asyncssh.SSHClientConnection

SSH client connection

This class represents an SSH client connection.

Once authentication is successful on a connection, new client sessions can be opened by calling create_session().

Direct TCP connections can be opened by calling create_connection().

Remote listeners for forwarded TCP connections can be opened by calling create_server().

Direct UNIX domain socket connections can be opened by calling create_unix_connection().

Remote listeners for forwarded UNIX domain socket connections can be opened by calling create_unix_server().

TCP port forwarding can be set up by calling forward_local_port() or forward_remote_port().

UNIX domain socket forwarding can be set up by calling forward_local_path() or forward_remote_path().

Connection attributes
logger A logger associated with this connection

General connection methods
get_extra_info(name, default=None) Get additional information about the connection This method returns extra information about the connection once it is established. Supported values include everything supported by a socket transport plus: username client_version server_version send_cipher send_mac send_compression recv_cipher recv_mac recv_compression See get_extra_info() in asyncio.BaseTransport for more information. Additional information stored on the connection by calling set_extra_info() can also be returned here.
set_extra_info(**kwargs) Store additional information associated with the connection This method allows extra information to be associated with the connection. The information to store should be passed in as keyword parameters and can later be returned by calling get_extra_info() with one of the keywords as the name to retrieve.
set_keepalive(interval=None, count_max=None) Set keep-alive timer on this connection This method sets the parameters of the keepalive timer on the connection. If interval is set to a non-zero value, keep-alive requests will be sent whenever the connection is idle, and if a response is not received after count_max attempts, the connection is closed. Parameters interval (int or float) – (optional) The time in seconds to wait before sending a keep-alive message if no data has been received. This defaults to 0, which disables sending these messages. count_max (int) – (optional) The maximum number of keepalive messages which will be sent without getting a response before closing the connection. This defaults to 3, but only applies when interval is non-zero.
get_server_host_key() Return the server host key used in the key exchange This method returns the server host key used to complete the key exchange with the server. If GSS key exchange is used, None is returned. Returns An SSHKey public key or None
send_debug(msg, lang='en-US', always_display=False) Send a debug message on this connection This method can be called to send a debug message to the other end of the connection. Parameters msg (str) – The debug message to send lang (str) – The language the message is in always_display (bool) – Whether or not to display the message

Client session open methods
async create_session(session_factory, command=None, *, subsystem=None, env={}, term_type=None, term_size=None, term_modes={}, x11_forwarding=False, x11_display=None, x11_auth_path=None, x11_single_connection=False, encoding='utf-8', errors='strict', window=2097152, max_pktsize=32768) Create an SSH client session This method is a coroutine which can be called to create an SSH client session used to execute a command, start a subsystem such as sftp, or if no command or subsystem is specified run an interactive shell. Optional arguments allow terminal and environment information to be provided. By default, this class expects string data in its send and receive functions, which it encodes on the SSH connection in UTF-8 (ISO 10646) format. An optional encoding argument can be passed in to select a different encoding, or None can be passed in if the application wishes to send and receive raw bytes. When an encoding is set, an optional errors argument can be passed in to select what Unicode error handling strategy to use. Other optional arguments include the SSH receive window size and max packet size which default to 2 MB and 32 KB, respectively. Parameters session_factory (callable) – A callable which returns an SSHClientSession object that will be created to handle activity on this session command (str) – (optional) The remote command to execute. By default, an interactive shell is started if no command or subsystem is provided. subsystem (str) – (optional) The name of a remote subsystem to start up env (dict) – (optional) The set of environment variables to set for this session. Keys and values passed in here will be converted to Unicode strings encoded as UTF-8 (ISO 10646) for transmission. Note Many SSH servers restrict which environment variables a client is allowed to set. The server’s configuration may need to be edited before environment variables can be successfully set in the remote environment. term_type (str) – (optional) The terminal type to set for this session. If this is not set, a pseudo-terminal will not be requested for this session. term_size (tuple of 2 or 4 int values) – (optional) The terminal width and height in characters and optionally the width and height in pixels term_modes (dict) – (optional) POSIX terminal modes to set for this session, where keys are taken from POSIX terminal modes with values defined in section 8 of RFC 4254. x11_forwarding (bool) – (optional) Whether or not to request X11 forwarding for this session, defaulting to False x11_display (str) – (optional) The display that X11 connections should be forwarded to, defaulting to the value in the environment variable DISPLAY x11_auth_path (str) – (optional) The path to the Xauthority file to read X11 authentication data from, defaulting to the value in the environment variable XAUTHORITY or the file .Xauthority in the user’s home directory if that’s not set x11_single_connection (bool) – (optional) Whether or not to limit X11 forwarding to a single connection, defaulting to False encoding (str) – (optional) The Unicode encoding to use for data exchanged on the connection errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns an SSHClientChannel and SSHClientSession Raises ChannelOpenError if the session can’t be opened
async open_session(*args, **kwargs) Open an SSH client session This method is a coroutine wrapper around create_session() designed to provide a “high-level” stream interface for creating an SSH client session. Instead of taking a session_factory argument for constructing an object which will handle activity on the session via callbacks, it returns an SSHWriter and two SSHReader objects representing stdin, stdout, and stderr which can be used to perform I/O on the session. With the exception of session_factory, all of the arguments to create_session() are supported and have the same meaning.
create_process(*args, bufsize=io.DEFAULT_BUFFER_SIZE, input=None, stdin=PIPE, stdout=PIPE, stderr=PIPE, **kwargs) Create a process on the remote system This method is a coroutine wrapper around create_session() which can be used to execute a command, start a subsystem, or start an interactive shell, optionally redirecting stdin, stdout, and stderr to and from files or pipes attached to other local and remote processes. By default, the stdin, stdout, and stderr arguments default to the special value PIPE which means that they can be read and written interactively via stream objects which are members of the SSHClientProcess object this method returns. If other file-like objects are provided as arguments, input or output will automatically be redirected to them. The special value DEVNULL can be used to provide no input or discard all output, and the special value STDOUT can be provided as stderr to send its output to the same stream as stdout. In addition to the arguments below, all arguments to create_session() except for session_factory are supported and have the same meaning. Parameters bufsize (int) – (optional) Buffer size to use when feeding data from a file to stdin input (str or bytes) – (optional) Input data to feed to standard input of the remote process. If specified, this argument takes precedence over stdin. Data should be a str if encoding is set, or bytes if not. stdin – (optional) A filename, file-like object, file descriptor, socket, or SSHReader to feed to standard input of the remote process, or DEVNULL to provide no input. stdout – (optional) A filename, file-like object, file descriptor, socket, or SSHWriter to feed standard output of the remote process to, or DEVNULL to discard this output. stderr – (optional) A filename, file-like object, file descriptor, socket, or SSHWriter to feed standard error of the remote process to, DEVNULL to discard this output, or STDOUT to feed standard error to the same place as stdout. Returns SSHClientProcess Raises ChannelOpenError if the channel can’t be opened
async create_subprocess(protocol_factory, *args, bufsize=io.DEFAULT_BUFFER_SIZE, input=None, stdin=PIPE, stdout=PIPE, stderr=PIPE, **kwargs) Create a subprocess on the remote system This method is a coroutine wrapper around create_session() which can be used to execute a command, start a subsystem, or start an interactive shell, optionally redirecting stdin, stdout, and stderr to and from files or pipes attached to other local and remote processes similar to create_process(). However, instead of performing interactive I/O using SSHReader and SSHWriter objects, the caller provides a function which returns an object which conforms to the asyncio.SubprocessProtocol and this call returns that and an SSHSubprocessTransport object which conforms to asyncio.SubprocessTransport. With the exception of the addition of protocol_factory, all of the arguments are the same as create_process(). Parameters protocol_factory (callable) – A callable which returns an SSHSubprocessProtocol object that will be created to handle activity on this session. Returns an SSHSubprocessTransport and SSHSubprocessProtocol Raises ChannelOpenError if the channel can’t be opened
async run(*args, check=False, timeout=None, **kwargs) Run a command on the remote system and collect its output This method is a coroutine wrapper around create_process() which can be used to run a process to completion when no interactivity is needed. All of the arguments to create_process() can be passed in to provide input or redirect stdin, stdout, and stderr, but this method waits until the process exits and returns an SSHCompletedProcess object with the exit status or signal information and the output to stdout and stderr (if not redirected). If the check argument is set to True, a non-zero exit status from the remote process will trigger the ProcessError exception to be raised. In addition to the argument below, all arguments to create_process() are supported and have the same meaning. If a timeout is specified and it expires before the process exits, the TimeoutError exception will be raised. By default, no timeout is set and this call will wait indefinitely. Parameters check (bool) – (optional) Whether or not to raise ProcessError when a non-zero exit status is returned timeout (int, float, or None) – Amount of time in seconds to wait for process to exit or None to wait indefinitely Returns SSHCompletedProcess Raises ChannelOpenError if the session can’t be opened ProcessError if checking non-zero exit status TimeoutError if the timeout expires before exit
start_sftp_client(env=None, path_encoding='utf-8', path_errors='strict') Start an SFTP client This method is a coroutine which attempts to start a secure file transfer session. If it succeeds, it returns an SFTPClient object which can be used to copy and access files on the remote host. An optional Unicode encoding can be specified for sending and receiving pathnames, defaulting to UTF-8 with strict error checking. If an encoding of None is specified, pathnames will be left as bytes rather than being converted to & from strings. Parameters env – (optional) The set of environment variables to set for this SFTP session. Keys and values passed in here will be converted to Unicode strings encoded as UTF-8 (ISO 10646) for transmission. Note Many SSH servers restrict which environment variables a client is allowed to set. The server’s configuration may need to be edited before environment variables can be successfully set in the remote environment. path_encoding (str) – The Unicode encoding to apply when sending and receiving remote pathnames path_errors (str) – The error handling strategy to apply on encode/decode errors Returns SFTPClient Raises SFTPError if the session can’t be opened
async create_ssh_connection(client_factory, host, port=22, **kwargs) Create a tunneled SSH client connection This method is a coroutine which can be called to open an SSH client connection to the requested host and port tunneled inside this already established connection. It takes all the same arguments as create_connection() but requests that the upstream SSH server open the connection rather than connecting directly.
connect_ssh(host, port=22, **kwargs) Make a tunneled SSH client connection This method is a coroutine which can be called to open an SSH client connection to the requested host and port tunneled inside this already established connection. It takes all the same arguments as connect() but requests that the upstream SSH server open the connection rather than connecting directly.
connect_reverse_ssh(host, port=22, **kwargs) Make a tunneled reverse direction SSH connection This method is a coroutine which can be called to open an SSH client connection to the requested host and port tunneled inside this already established connection. It takes all the same arguments as connect() but requests that the upstream SSH server open the connection rather than connecting directly.
listen_ssh(host='', port=22, **kwargs) Create a tunneled SSH listener This method is a coroutine which can be called to open a remote SSH listener on the requested host and port tunneled inside this already established connection. It takes all the same arguments as listen() but requests that the upstream SSH server open the listener rather than listening directly via TCP/IP.
listen_reverse_ssh(host='', port=22, **kwargs) Create a tunneled reverse direction SSH listener This method is a coroutine which can be called to open a remote SSH listener on the requested host and port tunneled inside this already established connection. It takes all the same arguments as listen_reverse() but requests that the upstream SSH server open the listener rather than listening directly via TCP/IP.

Client connection open methods
async create_connection(session_factory, remote_host, remote_port, orig_host='', orig_port=0, *, encoding=None, errors='strict', window=2097152, max_pktsize=32768) Create an SSH TCP direct connection This method is a coroutine which can be called to request that the server open a new outbound TCP connection to the specified destination host and port. If the connection is successfully opened, a new SSH channel will be opened with data being handled by a SSHTCPSession object created by session_factory. Optional arguments include the host and port of the original client opening the connection when performing TCP port forwarding. By default, this class expects data to be sent and received as raw bytes. However, an optional encoding argument can be passed in to select the encoding to use, allowing the application send and receive string data. When encoding is set, an optional errors argument can be passed in to select what Unicode error handling strategy to use. Other optional arguments include the SSH receive window size and max packet size which default to 2 MB and 32 KB, respectively. Parameters session_factory (callable) – A callable which returns an SSHClientSession object that will be created to handle activity on this session remote_host (str) – The remote hostname or address to connect to remote_port (int) – The remote port number to connect to orig_host (str) – (optional) The hostname or address of the client requesting the connection orig_port (int) – (optional) The port number of the client requesting the connection encoding (str) – (optional) The Unicode encoding to use for data exchanged on the connection errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns an SSHTCPChannel and SSHTCPSession Raises ChannelOpenError if the connection can’t be opened
async open_connection(*args, **kwargs) Open an SSH TCP direct connection This method is a coroutine wrapper around create_connection() designed to provide a “high-level” stream interface for creating an SSH TCP direct connection. Instead of taking a session_factory argument for constructing an object which will handle activity on the session via callbacks, it returns SSHReader and SSHWriter objects which can be used to perform I/O on the connection. With the exception of session_factory, all of the arguments to create_connection() are supported and have the same meaning here. Returns an SSHReader and SSHWriter Raises ChannelOpenError if the connection can’t be opened
create_server(session_factory, listen_host, listen_port, *, encoding=None, errors='strict', window=2097152, max_pktsize=32768) Create a remote SSH TCP listener This method is a coroutine which can be called to request that the server listen on the specified remote address and port for incoming TCP connections. If the request is successful, the return value is an SSHListener object which can be used later to shut down the listener. If the request fails, None is returned. Parameters session_factory (callable or coroutine) – A callable or coroutine which takes arguments of the original host and port of the client and decides whether to accept the connection or not, either returning an SSHTCPSession object used to handle activity on that connection or raising ChannelOpenError to indicate that the connection should not be accepted listen_host (str) – The hostname or address on the remote host to listen on listen_port (int) – The port number on the remote host to listen on encoding (str) – (optional) The Unicode encoding to use for data exchanged on the connection errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns SSHListener Raises ChannelListenError if the listener can’t be opened
start_server(handler_factory, *args, **kwargs) Start a remote SSH TCP listener This method is a coroutine wrapper around create_server() designed to provide a “high-level” stream interface for creating remote SSH TCP listeners. Instead of taking a session_factory argument for constructing an object which will handle activity on the session via callbacks, it takes a handler_factory which returns a callable or coroutine that will be passed SSHReader and SSHWriter objects which can be used to perform I/O on each new connection which arrives. Like create_server(), handler_factory can also raise ChannelOpenError if the connection should not be accepted. With the exception of handler_factory replacing session_factory, all of the arguments to create_server() are supported and have the same meaning here. Parameters handler_factory (callable or coroutine) – A callable or coroutine which takes arguments of the original host and port of the client and decides whether to accept the connection or not, either returning a callback or coroutine used to handle activity on that connection or raising ChannelOpenError to indicate that the connection should not be accepted Returns SSHListener Raises ChannelListenError if the listener can’t be opened
async create_unix_connection(session_factory, remote_path, *, encoding=None, errors='strict', window=2097152, max_pktsize=32768) Create an SSH UNIX domain socket direct connection This method is a coroutine which can be called to request that the server open a new outbound UNIX domain socket connection to the specified destination path. If the connection is successfully opened, a new SSH channel will be opened with data being handled by a SSHUNIXSession object created by session_factory. By default, this class expects data to be sent and received as raw bytes. However, an optional encoding argument can be passed in to select the encoding to use, allowing the application to send and receive string data. When encoding is set, an optional errors argument can be passed in to select what Unicode error handling strategy to use. Other optional arguments include the SSH receive window size and max packet size which default to 2 MB and 32 KB, respectively. Parameters session_factory (callable) – A callable which returns an SSHClientSession object that will be created to handle activity on this session remote_path (str) – The remote path to connect to encoding (str) – (optional) The Unicode encoding to use for data exchanged on the connection errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns an SSHUNIXChannel and SSHUNIXSession Raises ChannelOpenError if the connection can’t be opened
async open_unix_connection(*args, **kwargs) Open an SSH UNIX domain socket direct connection This method is a coroutine wrapper around create_unix_connection() designed to provide a “high-level” stream interface for creating an SSH UNIX domain socket direct connection. Instead of taking a session_factory argument for constructing an object which will handle activity on the session via callbacks, it returns SSHReader and SSHWriter objects which can be used to perform I/O on the connection. With the exception of session_factory, all of the arguments to create_unix_connection() are supported and have the same meaning here. Returns an SSHReader and SSHWriter Raises ChannelOpenError if the connection can’t be opened
create_unix_server(session_factory, listen_path, *, encoding=None, errors='strict', window=2097152, max_pktsize=32768) Create a remote SSH UNIX domain socket listener This method is a coroutine which can be called to request that the server listen on the specified remote path for incoming UNIX domain socket connections. If the request is successful, the return value is an SSHListener object which can be used later to shut down the listener. If the request fails, None is returned. Parameters session_factory (callable or coroutine) – A callable or coroutine which takes arguments of the original host and port of the client and decides whether to accept the connection or not, either returning an SSHUNIXSession object used to handle activity on that connection or raising ChannelOpenError to indicate that the connection should not be accepted listen_path (str) – The path on the remote host to listen on encoding (str) – (optional) The Unicode encoding to use for data exchanged on the connection errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns SSHListener Raises ChannelListenError if the listener can’t be opened
start_unix_server(handler_factory, *args, **kwargs) Start a remote SSH UNIX domain socket listener This method is a coroutine wrapper around create_unix_server() designed to provide a “high-level” stream interface for creating remote SSH UNIX domain socket listeners. Instead of taking a session_factory argument for constructing an object which will handle activity on the session via callbacks, it takes a handler_factory which returns a callable or coroutine that will be passed SSHReader and SSHWriter objects which can be used to perform I/O on each new connection which arrives. Like create_unix_server(), handler_factory can also raise ChannelOpenError if the connection should not be accepted. With the exception of handler_factory replacing session_factory, all of the arguments to create_unix_server() are supported and have the same meaning here. Parameters handler_factory (callable or coroutine) – A callable or coroutine which takes arguments of the original host and port of the client and decides whether to accept the connection or not, either returning a callback or coroutine used to handle activity on that connection or raising ChannelOpenError to indicate that the connection should not be accepted Returns SSHListener Raises ChannelListenError if the listener can’t be opened

Client forwarding methods
async forward_connection(dest_host, dest_port) Forward a tunneled TCP connection This method is a coroutine which can be returned by a session_factory to forward connections tunneled over SSH to the specified destination host and port. Parameters dest_host (str) – The hostname or address to forward the connections to dest_port (int) – The port number to forward the connections to Returns SSHTCPSession
forward_local_port(listen_host, listen_port, dest_host, dest_port) Set up local port forwarding This method is a coroutine which attempts to set up port forwarding from a local listening port to a remote host and port via the SSH connection. If the request is successful, the return value is an SSHListener object which can be used later to shut down the port forwarding. Parameters listen_host (str) – The hostname or address on the local host to listen on listen_port (int) – The port number on the local host to listen on dest_host (str) – The hostname or address to forward the connections to dest_port (int) – The port number to forward the connections to Returns SSHListener Raises OSError if the listener can’t be opened
forward_local_path(listen_path, dest_path) Set up local UNIX domain socket forwarding This method is a coroutine which attempts to set up UNIX domain socket forwarding from a local listening path to a remote path via the SSH connection. If the request is successful, the return value is an SSHListener object which can be used later to shut down the UNIX domain socket forwarding. Parameters listen_path (str) – The path on the local host to listen on dest_path (str) – The path on the remote host to forward the connections to Returns SSHListener Raises OSError if the listener can’t be opened
forward_remote_port(listen_host, listen_port, dest_host, dest_port) Set up remote port forwarding This method is a coroutine which attempts to set up port forwarding from a remote listening port to a local host and port via the SSH connection. If the request is successful, the return value is an SSHListener object which can be used later to shut down the port forwarding. If the request fails, None is returned. Parameters listen_host (str) – The hostname or address on the remote host to listen on listen_port (int) – The port number on the remote host to listen on dest_host (str) – The hostname or address to forward connections to dest_port (int) – The port number to forward connections to Returns SSHListener Raises ChannelListenError if the listener can’t be opened
forward_remote_path(listen_path, dest_path) Set up remote UNIX domain socket forwarding This method is a coroutine which attempts to set up UNIX domain socket forwarding from a remote listening path to a local path via the SSH connection. If the request is successful, the return value is an SSHListener object which can be used later to shut down the port forwarding. If the request fails, None is returned. Parameters listen_path (str) – The path on the remote host to listen on dest_path (str) – The path on the local host to forward connections to Returns SSHListener Raises ChannelListenError if the listener can’t be opened
forward_socks(listen_host, listen_port) Set up local port forwarding via SOCKS This method is a coroutine which attempts to set up dynamic port forwarding via SOCKS on the specified local host and port. Each SOCKS request contains the destination host and port to connect to and triggers a request to tunnel traffic to the requested host and port via the SSH connection. If the request is successful, the return value is an SSHListener object which can be used later to shut down the port forwarding. Parameters listen_host (str) – The hostname or address on the local host to listen on listen_port (int) – The port number on the local host to listen on Returns SSHListener Raises OSError if the listener can’t be opened

Connection close methods
abort() Forcibly close the SSH connection This method closes the SSH connection immediately, without waiting for pending operations to complete and wihtout sending an explicit SSH disconnect message. Buffered data waiting to be sent will be lost and no more data will be received. When the the connection is closed, connection_lost() on the associated SSHClient object will be called with the value None.
close() Cleanly close the SSH connection This method calls disconnect() with the reason set to indicate that the connection was closed explicitly by the application.
disconnect(code, reason, lang='en-US') Disconnect the SSH connection This method sends a disconnect message and closes the SSH connection after buffered data waiting to be written has been sent. No more data will be received. When the connection is fully closed, connection_lost() on the associated SSHClient or SSHServer object will be called with the value None. Parameters code (int) – The reason for the disconnect, from disconnect reason codes reason (str) – A human readable reason for the disconnect lang (str) – The language the reason is in
async wait_closed() Wait for this connection to close This method is a coroutine which can be called to block until this connection has finished closing.

SSHServerConnection

class asyncssh.SSHServerConnection

SSH server connection

This class represents an SSH server connection.

During authentication, send_auth_banner() can be called to send an authentication banner to the client.

Once authenticated, SSHServer objects wishing to create session objects with non-default channel properties can call create_server_channel() from their session_requested() method and return a tuple of the SSHServerChannel object returned from that and either an SSHServerSession object or a coroutine which returns an SSHServerSession.

Similarly, SSHServer objects wishing to create TCP connection objects with non-default channel properties can call create_tcp_channel() from their connection_requested() method and return a tuple of the SSHTCPChannel object returned from that and either an SSHTCPSession object or a coroutine which returns an SSHTCPSession.

SSHServer objects wishing to create UNIX domain socket connection objects with non-default channel properties can call create_unix_channel() from the unix_connection_requested() method and return a tuple of the SSHUNIXChannel object returned from that and either an SSHUNIXSession object or a coroutine which returns an SSHUNIXSession.

Connection attributes
logger A logger associated with this connection

General connection methods
get_extra_info(name, default=None) Get additional information about the connection This method returns extra information about the connection once it is established. Supported values include everything supported by a socket transport plus: username client_version server_version send_cipher send_mac send_compression recv_cipher recv_mac recv_compression See get_extra_info() in asyncio.BaseTransport for more information. Additional information stored on the connection by calling set_extra_info() can also be returned here.
set_extra_info(**kwargs) Store additional information associated with the connection This method allows extra information to be associated with the connection. The information to store should be passed in as keyword parameters and can later be returned by calling get_extra_info() with one of the keywords as the name to retrieve.
set_keepalive(interval=None, count_max=None) Set keep-alive timer on this connection This method sets the parameters of the keepalive timer on the connection. If interval is set to a non-zero value, keep-alive requests will be sent whenever the connection is idle, and if a response is not received after count_max attempts, the connection is closed. Parameters interval (int or float) – (optional) The time in seconds to wait before sending a keep-alive message if no data has been received. This defaults to 0, which disables sending these messages. count_max (int) – (optional) The maximum number of keepalive messages which will be sent without getting a response before closing the connection. This defaults to 3, but only applies when interval is non-zero.
send_debug(msg, lang='en-US', always_display=False) Send a debug message on this connection This method can be called to send a debug message to the other end of the connection. Parameters msg (str) – The debug message to send lang (str) – The language the message is in always_display (bool) – Whether or not to display the message

Server authentication methods
send_auth_banner(msg, lang='en-US') Send an authentication banner to the client This method can be called to send an authentication banner to the client, displaying information while authentication is in progress. It is an error to call this method after the authentication is complete. Parameters msg (str) – The message to display lang (str) – The language the message is in Raises OSError if authentication is already completed
set_authorized_keys(authorized_keys) Set the keys trusted for client public key authentication This method can be called to set the trusted user and CA keys for client public key authentication. It should generally be called from the begin_auth method of SSHServer to set the appropriate keys for the user attempting to authenticate. Parameters authorized_keys (see Specifying authorized keys) – The keys to trust for client public key authentication
get_key_option(option, default=None) Return option from authorized_keys If a client key or certificate was presented during authentication, this method returns the value of the requested option in the corresponding authorized_keys entry if it was set. Otherwise, it returns the default value provided. The following standard options are supported: command (string) environment (dictionary of name/value pairs) from (list of host patterns) no-touch-required (boolean) permitopen (list of host/port tuples) principals (list of usernames) Non-standard options are also supported and will return the value True if the option is present without a value or return a list of strings containing the values associated with each occurrence of that option name. If the option is not present, the specified default value is returned. Parameters option (str) – The name of the option to look up. default – The default value to return if the option is not present. Returns The value of the option in authorized_keys, if set
check_key_permission(permission) Check permissions in authorized_keys If a client key or certificate was presented during authentication, this method returns whether the specified permission is allowed by the corresponding authorized_keys entry. By default, all permissions are granted, but they can be revoked by specifying an option starting with ‘no-‘ without a value. The following standard options are supported: X11-forwarding agent-forwarding port-forwarding pty user-rc AsyncSSH internally enforces X11-forwarding, agent-forwarding, port-forwarding and pty permissions but ignores user-rc since it does not implement that feature. Non-standard permissions can also be checked, as long as the option follows the convention of starting with ‘no-‘. Parameters permission (str) – The name of the permission to check (without the ‘no-‘). Returns A bool indicating if the permission is granted.
get_certificate_option(option, default=None) Return option from user certificate If a user certificate was presented during authentication, this method returns the value of the requested option in the certificate if it was set. Otherwise, it returns the default value provided. The following options are supported: force-command (string) no-touch-required (boolean) source-address (list of CIDR-style IP network addresses) Parameters option (str) – The name of the option to look up. default – The default value to return if the option is not present. Returns The value of the option in the user certificate, if set
check_certificate_permission(permission) Check permissions in user certificate If a user certificate was presented during authentication, this method returns whether the specified permission was granted in the certificate. Otherwise, it acts as if all permissions are granted and returns True. The following permissions are supported: X11-forwarding agent-forwarding port-forwarding pty user-rc AsyncSSH internally enforces agent-forwarding, port-forwarding and pty permissions but ignores the other values since it does not implement those features. Parameters permission (str) – The name of the permission to check (without the ‘permit-‘). Returns A bool indicating if the permission is granted.

Server connection open methods
async create_connection(session_factory, remote_host, remote_port, orig_host='', orig_port=0, *, encoding=None, errors='strict', window=2097152, max_pktsize=32768) Create an SSH TCP forwarded connection This method is a coroutine which can be called to notify the client about a new inbound TCP connection arriving on the specified remote host and port. If the connection is successfully opened, a new SSH channel will be opened with data being handled by a SSHTCPSession object created by session_factory. Optional arguments include the host and port of the original client opening the connection when performing TCP port forwarding. By default, this class expects data to be sent and received as raw bytes. However, an optional encoding argument can be passed in to select the encoding to use, allowing the application to send and receive string data. When encoding is set, an optional errors argument can be passed in to select what Unicode error handling strategy to use. Other optional arguments include the SSH receive window size and max packet size which default to 2 MB and 32 KB, respectively. Parameters session_factory (callable) – A callable which returns an SSHClientSession object that will be created to handle activity on this session remote_host (str) – The hostname or address the connection was received on remote_port (int) – The port number the connection was received on orig_host (str) – (optional) The hostname or address of the client requesting the connection orig_port (int) – (optional) The port number of the client requesting the connection encoding (str) – (optional) The Unicode encoding to use for data exchanged on the connection errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns an SSHTCPChannel and SSHTCPSession
async open_connection(*args, **kwargs) Open an SSH TCP forwarded connection This method is a coroutine wrapper around create_connection() designed to provide a “high-level” stream interface for creating an SSH TCP forwarded connection. Instead of taking a session_factory argument for constructing an object which will handle activity on the session via callbacks, it returns SSHReader and SSHWriter objects which can be used to perform I/O on the connection. With the exception of session_factory, all of the arguments to create_connection() are supported and have the same meaning here. Returns an SSHReader and SSHWriter
async create_unix_connection(session_factory, remote_path, *, encoding=None, errors='strict', window=2097152, max_pktsize=32768) Create an SSH UNIX domain socket forwarded connection This method is a coroutine which can be called to notify the client about a new inbound UNIX domain socket connection arriving on the specified remote path. If the connection is successfully opened, a new SSH channel will be opened with data being handled by a SSHUNIXSession object created by session_factory. By default, this class expects data to be sent and received as raw bytes. However, an optional encoding argument can be passed in to select the encoding to use, allowing the application to send and receive string data. When encoding is set, an optional errors argument can be passed in to select what Unicode error handling strategy to use. Other optional arguments include the SSH receive window size and max packet size which default to 2 MB and 32 KB, respectively. Parameters session_factory (callable) – A callable which returns an SSHClientSession object that will be created to handle activity on this session remote_path (str) – The path the connection was received on encoding (str) – (optional) The Unicode encoding to use for data exchanged on the connection errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns an SSHTCPChannel and SSHUNIXSession
async open_unix_connection(*args, **kwargs) Open an SSH UNIX domain socket forwarded connection This method is a coroutine wrapper around create_unix_connection() designed to provide a “high-level” stream interface for creating an SSH UNIX domain socket forwarded connection. Instead of taking a session_factory argument for constructing an object which will handle activity on the session via callbacks, it returns SSHReader and SSHWriter objects which can be used to perform I/O on the connection. With the exception of session_factory, all of the arguments to create_unix_connection() are supported and have the same meaning here. Returns an SSHReader and SSHWriter

Server forwarding methods
async forward_connection(dest_host, dest_port) Forward a tunneled TCP connection This method is a coroutine which can be returned by a session_factory to forward connections tunneled over SSH to the specified destination host and port. Parameters dest_host (str) – The hostname or address to forward the connections to dest_port (int) – The port number to forward the connections to Returns SSHTCPSession
async forward_unix_connection(dest_path) Forward a tunneled UNIX domain socket connection This method is a coroutine which can be returned by a session_factory to forward connections tunneled over SSH to the specified destination path. Parameters dest_path (str) – The path to forward the connection to Returns SSHUNIXSession

Server channel creation methods
create_server_channel(encoding='utf-8', errors='strict', window=2097152, max_pktsize=32768) Create an SSH server channel for a new SSH session This method can be called by session_requested() to create an SSHServerChannel with the desired encoding, Unicode error handling strategy, window, and max packet size for a newly created SSH server session. Parameters encoding (str) – (optional) The Unicode encoding to use for data exchanged on the session, defaulting to UTF-8 (ISO 10646) format. If None is passed in, the application can send and receive raw bytes. errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns SSHServerChannel
create_tcp_channel(encoding=None, errors='strict', window=2097152, max_pktsize=32768) Create an SSH TCP channel for a new direct TCP connection This method can be called by connection_requested() to create an SSHTCPChannel with the desired encoding, Unicode error handling strategy, window, and max packet size for a newly created SSH direct connection. Parameters encoding (str) – (optional) The Unicode encoding to use for data exchanged on the connection. This defaults to None, allowing the application to send and receive raw bytes. errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns SSHTCPChannel
create_unix_channel(encoding=None, errors='strict', window=2097152, max_pktsize=32768) Create an SSH UNIX channel for a new direct UNIX domain connection This method can be called by unix_connection_requested() to create an SSHUNIXChannel with the desired encoding, Unicode error handling strategy, window, and max packet size for a newly created SSH direct UNIX domain socket connection. Parameters encoding (str) – (optional) The Unicode encoding to use for data exchanged on the connection. This defaults to None, allowing the application to send and receive raw bytes. errors (str) – (optional) The error handling strategy to apply on encode/decode errors window (int) – (optional) The receive window size for this session max_pktsize (int) – (optional) The maximum packet size for this session Returns SSHUNIXChannel

Connection close methods
abort() Forcibly close the SSH connection This method closes the SSH connection immediately, without waiting for pending operations to complete and wihtout sending an explicit SSH disconnect message. Buffered data waiting to be sent will be lost and no more data will be received. When the the connection is closed, connection_lost() on the associated SSHClient object will be called with the value None.
close() Cleanly close the SSH connection This method calls disconnect() with the reason set to indicate that the connection was closed explicitly by the application.
disconnect(code, reason, lang='en-US') Disconnect the SSH connection This method sends a disconnect message and closes the SSH connection after buffered data waiting to be written has been sent. No more data will be received. When the connection is fully closed, connection_lost() on the associated SSHClient or SSHServer object will be called with the value None. Parameters code (int) – The reason for the disconnect, from disconnect reason codes reason (str) – A human readable reason for the disconnect lang (str) – The language the reason is in
async wait_closed() Wait for this connection to close This method is a coroutine which can be called to block until this connection has finished closing.

SSHClientConnectionOptions

class asyncssh.SSHClientConnectionOptions

SSH client connection options

The following options are available to control the establishment of SSH client connections:

Parameters

• client_factory (callable) – (optional) A callable which returns an SSHClient object that will be created for each new connection.

• 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.

• server_host_key_algs (list of str) – (optional) A list of server host key algorithms to add to those present in known_hosts when performing the SSH handshake, taken from server host key algorithms. This is useful when using the validate_host_public_key callback to validate server host keys.

• x509_trusted_certs (see Specifying certificates) –

  (optional) A list of certificates which should be trusted for X.509 server certificate authentication. If no trusted certificates are specified, an attempt will be made to load them from the file .ssh/ca-bundle.crt. If this argument is explicitly set to None, X.509 server certificate authentication will not be performed.

  Note

  X.509 certificates to trust can also be provided through a known_hosts file if they are converted into OpenSSH format. This allows their trust to be limited to only specific host names.

• x509_trusted_cert_paths (list of str) – (optional) A list of path names to “hash directories” containing certificates which should be trusted for X.509 server certificate authentication. Each certificate should be in a separate file with a name of the form hash.number, where hash is the OpenSSL hash value of the certificate subject name and number is an integer counting up from zero if multiple certificates have the same hash. If no paths are specified, an attempt with be made to use the directory .ssh/crt as a certificate hash directory.

• x509_purposes (see Specifying X.509 purposes) – (optional) A list of purposes allowed in the ExtendedKeyUsage of a certificate used for X.509 server certificate authentication, defulting to ‘secureShellServer’. If this argument is explicitly set to None, the server certificate’s ExtendedKeyUsage will not be checked.

• username (str) – (optional) Username to authenticate as on the server. If not specified, the currently logged in user on the local machine will be used.

• password (str) – (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.

• client_host_keysign (bool or str) – (optional) Whether or not to use ssh-keysign to sign host-based authentication requests. If set to True, an attempt will be made to find ssh-keysign in its typical locations. If set to a string, that will be used as the ssh-keysign path. When set, client_host_keys should be a list of public keys. Otherwise, client_host_keys should be a list of private keys with optional paired certificates.

• client_host_keys (see Specifying private keys or Specifying public keys) – (optional) A list of keys to use to authenticate this client via host-based authentication. If client_host_keysign is set and no host keys or certificates are specified, an attempt will be made to find them in their typical locations. If client_host_keysign is not set, host private keys must be specified explicitly or host-based authentication will not be performed.

• client_host (str) – (optional) The local hostname to use when performing host-based authentication. If not specified, the hostname associated with the local IP address of the SSH connection will be used.

• client_username (str) – (optional) The local username to use when performing host-based authentication. If not specified, the username of the currently logged in user 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 get them from an ssh-agent process and/or load them from the files .ssh/id_ed25519_sk, .ssh/id_ecdsa_sk, .ssh/id_ed448, .ssh/id_ed25519, .ssh/id_ecdsa, .ssh/id_rsa, and .ssh/id_dsa in the user’s home directory, with optional certificates loaded from the files .ssh/id_ed25519_sk-cert.pub, .ssh/id_ecdsa_sk-cert.pub, .ssh/id_ed448-cert.pub, .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.

• passphrase (str) – (optional) The passphrase to use to decrypt client keys when loading them, if they are encrypted. If this is not specified, only unencrypted client keys can be loaded. If the keys passed into client_keys are already loaded, this argument is ignored.

• gss_host (str) – (optional) The principal name to use for the host in GSS key exchange and authentication. If not specified, this value will be the same as the host argument. If this argument is explicitly set to None, GSS key exchange and authentication will not be performed.

• gss_delegate_creds (bool) – (optional) Whether or not to forward GSS credentials to the server being accessed. By default, GSS credential delegation is disabled.

• agent_path (str or SSHServerConnection) – (optional) The path of a UNIX domain socket to use to contact an ssh-agent process which will perform the operations needed for client public key authentication, or the SSHServerConnection to use to forward ssh-agent requests over. If this is not specified and the environment variable SSH_AUTH_SOCK is set, its value will be used as the path. If client_keys is specified or this argument is explicitly set to None, an ssh-agent will not be used.

• agent_forwarding (bool) – (optional) Whether or not to allow forwarding of ssh-agent requests from processes running on the server. By default, ssh-agent forwarding requests from the server are not allowed.

• client_version (str) – (optional) An ASCII string to advertise to the SSH server as the version of this client, defaulting to 'AsyncSSH' and its version number.

• kex_algs (list of str) – (optional) A list of allowed key exchange algorithms in the SSH handshake, taken from key exchange algorithms.

• encryption_algs (list of str) – (optional) A list of encryption algorithms to use during the SSH handshake, taken from encryption algorithms.

• mac_algs (list of str) – (optional) A list of MAC algorithms to use during the SSH handshake, taken from MAC algorithms.

• compression_algs (list of str) – (optional) A list of compression algorithms to use during the SSH handshake, taken from compression algorithms, or None to disable compression.

• signature_algs (list of str) – (optional) A list of public key signature algorithms to use during the SSH handshake, taken from signature algorithms.

• rekey_bytes (int) – (optional) The number of bytes which can be sent before the SSH session key is renegotiated. This defaults to 1 GB.

• rekey_seconds (int) – (optional) The maximum time in seconds before the SSH session key is renegotiated. This defaults to 1 hour.

• login_timeout (int or float) – (optional) The maximum time in seconds allowed for authentication to complete, defaulting to 2 minutes

• keepalive_interval (int or float) – (optional) The time in seconds to wait before sending a keepalive message if no data has been received from the server. This defaults to 0, which disables sending these messages.

• keepalive_count_max (int) – (optional) The maximum number of keepalive messages which will be sent without getting a response before disconnecting from the server. This defaults to 3, but only applies when keepalive_interval is non-zero.

SSHServerConnectionOptions

class asyncssh.SSHServerConnectionOptions

SSH server connection options

The following options are available to control the acceptance of SSH server connections:

Parameters

• server_factory (callable) – A callable which returns an SSHServer object that will be created for each new connection.

• server_host_keys (see Specifying private keys) – (optional) A list of private keys and optional certificates which can be used by the server as a host key. Either this argument or gss_host must be specified. If this is not specified, only GSS-based key exchange will be supported.

• passphrase (str) – (optional) The passphrase to use to decrypt server host keys when loading them, if they are encrypted. If this is not specified, only unencrypted server host keys can be loaded. If the keys passed into server_host_keys are already loaded, this argument is ignored.

• known_client_hosts (see Specifying known hosts) – (optional) A list of client hosts which should be trusted to perform host-based client authentication. If this is not specified, host-based client authentication will be not be performed.

• trust_client_host (bool) – (optional) Whether or not to use the hostname provided by the client when performing host-based authentication. By default, the client-provided hostname is not trusted and is instead determined by doing a reverse lookup of the IP address the client connected from.

• 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.

• x509_trusted_certs (see Specifying certificates) –

  (optional) A list of certificates which should be trusted for X.509 client certificate authentication. If this argument is explicitly set to None, X.509 client certificate authentication will not be performed.

  Note

  X.509 certificates to trust can also be provided through an authorized_keys file if they are converted into OpenSSH format. This allows their trust to be limited to only specific client IPs or user names and allows SSH functions to be restricted when these certificates are used.

• x509_trusted_cert_paths (list of str) – (optional) A list of path names to “hash directories” containing certificates which should be trusted for X.509 client certificate authentication. Each certificate should be in a separate file with a name of the form hash.number, where hash is the OpenSSL hash value of the certificate subject name and number is an integer counting up from zero if multiple certificates have the same hash.

• x509_purposes (see Specifying X.509 purposes) – (optional) A list of purposes allowed in the ExtendedKeyUsage of a certificate used for X.509 client certificate authentication, defulting to ‘secureShellClient’. If this argument is explicitly set to None, the client certificate’s ExtendedKeyUsage will not be checked.

• gss_host (str) – (optional) The principal name to use for the host in GSS key exchange and authentication. If not specified, the value returned by socket.gethostname() will be used if it is a fully qualified name. Otherwise, the value used by socket.getfqdn() will be used. If this argument is explicitly set to None, GSS key exchange and authentication will not be performed.

• allow_pty (bool) – (optional) Whether or not to allow allocation of a pseudo-tty in sessions, defaulting to True

• line_editor (bool) – (optional) Whether or not to enable input line editing on sessions which have a pseudo-tty allocated, defaulting to True

• line_history (bool) – (int) The number of lines of input line history to store in the line editor when it is enabled, defaulting to 1000

• x11_forwarding (bool) – (optional) Whether or not to allow forwarding of X11 connections back to the client when the client supports it, defaulting to False

• x11_auth_path (str) – (optional) The path to the Xauthority file to write X11 authentication data to, defaulting to the value in the environment variable XAUTHORITY or the file .Xauthority in the user’s home directory if that’s not set

• agent_forwarding (bool) – (optional) Whether or not to allow forwarding of ssh-agent requests back to the client when the client supports it, defaulting to True

• process_factory (callable) – (optional) A callable or coroutine handler function which takes an AsyncSSH SSHServerProcess argument that will be called each time a new shell, exec, or subsystem other than SFTP is requested by the client. If set, this takes precedence over the session_factory argument.

• 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 subsystem 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.

• encoding (str) – (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.

• errors (str) – (optional) The error handling strategy to apply on Unicode encode/decode errors of data exchanged on sessions on this server, defaulting to ‘strict’.

• 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.

• allow_scp (bool) – (optional) Whether or not to allow incoming scp requests to be accepted. This option can only be used in conjunction with sftp_factory. If not specified, scp requests will be passed as regular commands to the process_factory or session_factory. to the client when the client supports it, defaulting to True

• window (int) – (optional) The receive window size for sessions on this server

• max_pktsize (int) – (optional) The maximum packet size for sessions on this server

• server_version (str) – (optional) An ASCII string to advertise to SSH clients as the version of this server, defaulting to 'AsyncSSH' and its version number.

• kex_algs (list of str) – (optional) A list of allowed key exchange algorithms in the SSH handshake, taken from key exchange algorithms

• encryption_algs (list of str) – (optional) A list of encryption algorithms to use during the SSH handshake, taken from encryption algorithms

• mac_algs (list of str) – (optional) A list of MAC algorithms to use during the SSH handshake, taken from MAC algorithms

• compression_algs (list of str) – (optional) A list of compression algorithms to use during the SSH handshake, taken from compression algorithms, or None to disable compression

• signature_algs (list of str) – (optional) A list of public key signature algorithms to use during the SSH handshake, taken from signature algorithms

• rekey_bytes (int) – (optional) The number of bytes which can be sent before the SSH session key is renegotiated, defaulting to 1 GB

• rekey_seconds (int) – (optional) The maximum time in seconds before the SSH session key is renegotiated, defaulting to 1 hour

• login_timeout (int or float) – (optional) The maximum time in seconds allowed for authentication to complete, defaulting to 2 minutes

• keepalive_interval (int or float) – (optional) The time in seconds to wait before sending a keepalive message if no data has been received from the client. This defaults to 0, which disables sending these messages.

• keepalive_count_max (int) – (optional) The maximum number of keepalive messages which will be sent without getting a response before disconnecting a client. This defaults to 3, but only applies when keepalive_interval is non-zero.

Process Classes

SSHClientProcess

class asyncssh.SSHClientProcess

SSH client process handler

Client process attributes
channel The channel associated with the process
logger The logger associated with the process
env The environment set by the client for the process This method returns the environment set by the client when the session was opened. Returns A dictionary containing the environment variables set by the client
command The command the client requested to execute, if any This method returns the command the client requested to execute when the process was started, if any. If the client did not request that a command be executed, this method will return None. Returns A str containing the command or None if no command was specified
subsystem The subsystem the client requested to open, if any This method returns the subsystem the client requested to open when the process was started, if any. If the client did not request that a subsystem be opened, this method will return None. Returns A str containing the subsystem name or None if no subsystem was specified
stdin The SSHWriter to use to write to stdin of the process
stdout The SSHReader to use to read from stdout of the process
stderr The SSHReader to use to read from stderr of the process
exit_status The exit status of the process
exit_signal Exit signal information for the process
returncode The exit status or negative exit signal number for the process

Other client process methods
get_extra_info(name, default=None) Return additional information about this process This method returns extra information about the channel associated with this process. See get_extra_info() on SSHClientChannel for additional information.
async redirect(stdin=None, stdout=None, stderr=None, bufsize=8192, send_eof=True) Perform I/O redirection for the process This method redirects data going to or from any or all of standard input, standard output, and standard error for the process. The stdin argument can be any of the following: An SSHReader object An asyncio.StreamReader object A file object open for read An int file descriptor open for read A connected socket object A string or PurePath containing the name of a file or device to open DEVNULL to provide no input to standard input PIPE to interactively write standard input The stdout and stderr arguments can be any of the following: An SSHWriter object An asyncio.StreamWriter object A file object open for write An int file descriptor open for write A connected socket object A string or PurePath containing the name of a file or device to open DEVNULL to discard standard error output PIPE to interactively read standard error output The stderr argument also accepts the value STDOUT to request that standard error output be delivered to stdout. File objects passed in can be associated with plain files, pipes, sockets, or ttys. The default value of None means to not change redirection for that stream. Note When passing in asyncio streams, it is the responsibility of the caller to close the associated transport when it is no longer needed. Parameters stdin – Source of data to feed to standard input stdout – Target to feed data from standard output to stderr – Target to feed data from standard error to bufsize (int) – Buffer size to use when forwarding data from a file send_eof (bool) – Whether or not to send EOF to the channel when redirection is complete, defaulting to True. If set to False, multiple sources can be sequentially fed to the channel.
collect_output() Collect output from the process without blocking This method returns a tuple of the output that the process has written to stdout and stderr which has not yet been read. It is intended to be called instead of read() by callers that want to collect received data without blocking. Returns A tuple of output to stdout and stderr
async communicate(input=None) Send input to and/or collect output from the process This method is a coroutine which optionally provides input to the process and then waits for the process to exit, returning a tuple of the data written to stdout and stderr. Parameters input (str or bytes) – Input data to feed to standard input of the process. Data should be a str if encoding is set, or bytes if not. Returns A tuple of output to stdout and stderr
async wait(check=False, timeout=None) Wait for process to exit This method is a coroutine which waits for the process to exit. It returns an SSHCompletedProcess object with the exit status or signal information and the output sent to stdout and stderr if those are redirected to pipes. If the check argument is set to True, a non-zero exit status from the process with trigger the ProcessError exception to be raised. If a timeout is specified and it expires before the process exits, the TimeoutError exception will be raised. By default, no timeout is set and this call will wait indefinitely. Parameters check (bool) – Whether or not to raise an error on non-zero exit status timeout (int, float, or None) – Amount of time in seconds to wait for process to exit, or None to wait indefinitely Returns SSHCompletedProcess Raises ProcessError if check is set to True and the process returns a non-zero exit status TimeoutError if the timeout expires before the process exits
change_terminal_size(width, height, pixwidth=0, pixheight=0) Change the terminal window size for this process This method changes the width and height of the terminal associated with this process. Parameters width (int) – The width of the terminal in characters height (int) – The height of the terminal in characters pixwidth (int) – (optional) The width of the terminal in pixels pixheight (int) – (optional) The height of the terminal in pixels Raises OSError if the SSH channel is not open
send_break(msec) Send a break to the process Parameters msec (int) – The duration of the break in milliseconds Raises OSError if the SSH channel is not open
send_signal(signal) Send a signal to the process Parameters signal (str) – The signal to deliver Raises OSError if the SSH channel is not open

Client process close methods
terminate() Terminate the process Raises OSError if the SSH channel is not open
kill() Forcibly kill the process Raises OSError if the SSH channel is not open
close() Shut down the process
is_closing() Return if the channel is closing or is closed
async wait_closed() Wait for the process to finish shutting down

SSHServerProcess

class asyncssh.SSHServerProcess(process_factory, sftp_factory, allow_scp)

SSH server process handler

Server process attributes
channel The channel associated with the process
logger The logger associated with the process
env The environment set by the client for the process This method returns the environment set by the client when the session was opened. Returns A dictionary containing the environment variables set by the client
command The command the client requested to execute, if any This method returns the command the client requested to execute when the process was started, if any. If the client did not request that a command be executed, this method will return None. Returns A str containing the command or None if no command was specified
subsystem The subsystem the client requested to open, if any This method returns the subsystem the client requested to open when the process was started, if any. If the client did not request that a subsystem be opened, this method will return None. Returns A str containing the subsystem name or None if no subsystem was specified
stdin The SSHReader to use to read from stdin of the process
stdout The SSHWriter to use to write to stdout of the process
stderr The SSHWriter to use to write to stderr of the process

Other server process methods
get_extra_info(name, default=None) Return additional information about this process This method returns extra information about the channel associated with this process. See get_extra_info() on SSHClientChannel for additional information.
get_terminal_type() Return the terminal type set by the client for the process This method returns the terminal type set by the client when the process was started. If the client didn’t request a pseudo-terminal, this method will return None. Returns A str containing the terminal type or None if no pseudo-terminal was requested
get_terminal_size() Return the terminal size set by the client for the process This method returns the latest terminal size information set by the client. If the client didn’t set any terminal size information, all values returned will be zero. Returns A tuple of four int values containing the width and height of the terminal in characters and the width and height of the terminal in pixels
get_terminal_mode(mode) Return the requested TTY mode for this session This method looks up the value of a POSIX terminal mode set by the client when the process was started. If the client didn’t request a pseudo-terminal or didn’t set the requested TTY mode opcode, this method will return None. Parameters mode (int) – POSIX terminal mode taken from POSIX terminal modes to look up Returns An int containing the value of the requested POSIX terminal mode or None if the requested mode was not set
async redirect(stdin=None, stdout=None, stderr=None, bufsize=8192, send_eof=True) Perform I/O redirection for the process This method redirects data going to or from any or all of standard input, standard output, and standard error for the process. The stdin argument can be any of the following: An SSHWriter object An asyncio.StreamWriter object A file object open for write An int file descriptor open for write A connected socket object A string or PurePath containing the name of a file or device to open DEVNULL to discard standard error output PIPE to interactively read standard error output The stdout and stderr arguments can be any of the following: An SSHReader object An asyncio.StreamReader object A file object open for read An int file descriptor open for read A connected socket object A string or PurePath containing the name of a file or device to open DEVNULL to provide no input to standard input PIPE to interactively write standard input File objects passed in can be associated with plain files, pipes, sockets, or ttys. The default value of None means to not change redirection for that stream. Note When passing in asyncio streams, it is the responsibility of the caller to close the associated transport when it is no longer needed. Parameters stdin – Target to feed data from standard input to stdout – Source of data to feed to standard output stderr – Source of data to feed to standard error bufsize (int) – Buffer size to use when forwarding data from a file send_eof (bool) – Whether or not to send EOF to the channel when redirection is complete, defaulting to True. If set to False, multiple sources can be sequentially fed to the channel.

Server process close methods
exit(status) Send exit status and close the channel This method can be called to report an exit status for the process back to the client and close the channel. Parameters status (int) – The exit status to report to the client
exit_with_signal(signal, core_dumped=False, msg='', lang='en-US') Send exit signal and close the channel This method can be called to report that the process terminated abnormslly with a signal. A more detailed error message may also provided, along with an indication of whether or not the process dumped core. After reporting the signal, the channel is closed. Parameters signal (str) – The signal which caused the process to exit core_dumped (bool) – (optional) Whether or not the process dumped core msg (str) – (optional) Details about what error occurred lang (str) – (optional) The language the error message is in
close() Shut down the process
is_closing() Return if the channel is closing or is closed
async wait_closed() Wait for the process to finish shutting down

SSHCompletedProcess

class asyncssh.SSHCompletedProcess

Results from running an SSH process

This object is returned by the run method on SSHClientConnection when the requested command has finished running. It contains the following fields:

Field	Description	Type
env	The environment the client requested to be set for the process	str or None
command	The command the client requested the process to execute (if any)	str or None
subsystem	The subsystem the client requested the process to open (if any)	str or None
exit_status	The exit status returned, or -1 if an exit signal is sent	int
exit_signal	The exit signal sent (if any) in the form of a tuple containing the signal name, a bool for whether a core dump occurred, a message associated with the signal, and the language the message was in	tuple or None
returncode	The exit status returned, or negative of the signal number when an exit signal is sent	int
stdout	The output sent by the process to stdout (if not redirected)	str or bytes
stderr	The output sent by the process to stderr (if not redirected)	str or bytes

SSHSubprocessReadPipe

class asyncssh.SSHSubprocessReadPipe

SSH subprocess pipe reader

General subprocess pipe info methods
get_extra_info(name, default=None) Return additional information about the remote process This method returns extra information about the channel associated with this subprocess. See get_extra_info() on SSHClientChannel for additional information.

Subprocess pipe read methods
pause_reading() Pause delivery of incoming data from the remote process
resume_reading() Resume delivery of incoming data from the remote process

General subprocess pipe close methods
close() Shut down the remote process

SSHSubprocessWritePipe

class asyncssh.SSHSubprocessWritePipe

SSH subprocess pipe writer

General subprocess pipe info methods
get_extra_info(name, default=None) Return additional information about the remote process This method returns extra information about the channel associated with this subprocess. See get_extra_info() on SSHClientChannel for additional information.

Subprocess pipe write methods
can_write_eof() Return whether the pipe supports write_eof()
get_write_buffer_size() Return the current size of the pipe’s output buffer
set_write_buffer_limits(high=None, low=None) Set the high- and low-water limits for write flow control
write(data) Write data on this pipe
writelines(list_of_data) Write a list of data bytes on this pipe
write_eof() Write EOF on this pipe

General subprocess pipe close methods
abort() Forcibly close the channel to the remote process
close() Shut down the remote process

SSHSubprocessProtocol

class asyncssh.SSHSubprocessProtocol

SSH subprocess protocol

This class conforms to asyncio.SubprocessProtocol, but with the following enhancement:

• If encoding is set when the subprocess is created, all data passed to pipe_data_received() will be string values containing Unicode data. However, for compatibility with asyncio.SubprocessProtocol, encoding defaults to None, in which case all data is delivered as bytes.

General subprocess protocol handlers
connection_made(transport) Called when a remote process is successfully started This method is called when a a remote process is successfully started. The transport parameter should be stored if needed for later use. Parameters transport (SSHSubprocessTransport) – The transport to use to communicate with the remote process.
pipe_connection_lost(fd, exc) Called when the pipe to a remote process is closed This method is called when a pipe to a remote process is closed. If the channel is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason the pipe was closed. Parameters fd (int) – The integer file descriptor of the pipe which was closed. This will be 1 for stdout or 2 for stderr. exc (Exception or None) – The exception which caused the channel to close, or None if the channel closed cleanly.

Subprocess protocol read handlers

pipe_data_received(fd, data) Called when data is received from the remote process This method is called when data is received from the remote process. If an encoding was specified when the process was started, the data will be delivered as a string after decoding with the requested encoding. Otherwise, the data will be delivered as bytes. Parameters fd (int) – The integer file descriptor of the pipe data was received on. This will be 1 for stdout or 2 for stderr. data (str or bytes) – The data received from the remote process

Other subprocess protocol handlers
process_exited() Called when a remote process has exited This method is called when the remote process has exited. Exit status information can be retrieved by calling get_returncode() on the transport provided in connection_made().

SSHSubprocessTransport

class asyncssh.SSHSubprocessTransport(protocol_factory)

SSH subprocess transport

This class conforms to asyncio.SubprocessTransport, but with the following enhancements:

• All functionality available through SSHClientProcess is also available here, such as the ability to dynamically redirect stdin, stdout, and stderr at any time during the lifetime of the process.

• If encoding is set when the subprocess is created, all data written to the transports created by get_pipe_transport() should be strings containing Unicode data. The encoding defaults to None, though, to preserve compatibility with asyncio.SubprocessTransport, which expects data to be written as bytes.

General subprocess transport methods
get_extra_info(name, default=None) Return additional information about this process This method returns extra information about the channel associated with this process. See get_extra_info() on SSHClientChannel for additional information.
get_pid() Return the PID of the remote process This method always returns None, since SSH doesn’t report remote PIDs.
get_pipe_transport(fd) Return a transport for the requested stream Parameters fd (int) – The integer file descriptor (0-2) to return the transport for, where 0 means stdin, 1 means stdout, and 2 means stderr. Returns an SSHSubprocessReadPipe or SSHSubprocessWritePipe
get_returncode() Return the exit status or signal for the remote process This method returns the exit status of the session if one has been sent. If an exit signal was sent, this method returns the negative of the numeric value of that signal, matching the behavior of asyncio.SubprocessTransport.get_returncode(). If neither has been sent, this method returns None. Returns int or None
change_terminal_size(width, height, pixwidth=0, pixheight=0) Change the terminal window size for this process This method changes the width and height of the terminal associated with this process. Parameters width (int) – The width of the terminal in characters height (int) – The height of the terminal in characters pixwidth (int) – (optional) The width of the terminal in pixels pixheight (int) – (optional) The height of the terminal in pixels Raises OSError if the SSH channel is not open
send_break(msec) Send a break to the process Parameters msec (int) – The duration of the break in milliseconds Raises OSError if the SSH channel is not open
send_signal(signal) Send a signal to the process Parameters signal (str) – The signal to deliver Raises OSError if the SSH channel is not open

Subprocess transport close methods
terminate() Terminate the process Raises OSError if the SSH channel is not open
kill() Forcibly kill the process Raises OSError if the SSH channel is not open
close() Shut down the process
is_closing() Return if the channel is closing or is closed
async wait_closed() Wait for the process to finish shutting down

Session Classes

SSHClientSession

class asyncssh.SSHClientSession

SSH client session handler

Applications should subclass this when implementing an SSH client session handler. The functions listed below should be implemented to define application-specific behavior. In particular, the standard asyncio protocol methods such as connection_made(), connection_lost(), data_received(), eof_received(), pause_writing(), and resume_writing() are all supported. In addition, session_started() is called as soon as the SSH session is fully started, xon_xoff_requested() can be used to determine if the server wants the client to support XON/XOFF flow control, and exit_status_received() and exit_signal_received() can be used to receive session exit information.

General session handlers
connection_made(chan) Called when a channel is opened successfully This method is called when a channel is opened successfully. The channel parameter should be stored if needed for later use. Parameters chan (SSHClientChannel) – The channel which was successfully opened.
connection_lost(exc) Called when a channel is closed This method is called when a channel is closed. If the channel is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason for the channel close. Parameters exc (Exception) – The exception which caused the channel to close, or None if the channel closed cleanly.
session_started() Called when the session is started This method is called when a session has started up. For client and server sessions, this will be called once a shell, exec, or subsystem request has been successfully completed. For TCP and UNIX domain socket sessions, it will be called immediately after the connection is opened.

General session read handlers
data_received(data, datatype) Called when data is received on the channel This method is called when data is received on the channel. If an encoding was specified when the channel was created, the data will be delivered as a string after decoding with the requested encoding. Otherwise, the data will be delivered as bytes. Parameters data (str or bytes) – The data received on the channel datatype – The extended data type of the data, from extended data types
eof_received() Called when EOF is received on the channel This method is called when an end-of-file indication is received on the channel, after which no more data will be received. If this method returns True, the channel remains half open and data may still be sent. Otherwise, the channel is automatically closed after this method returns. This is the default behavior for classes derived directly from SSHSession, but not when using the higher-level streams API. Because input is buffered in that case, streaming sessions enable half-open channels to allow applications to respond to input read after an end-of-file indication is received.

General session write handlers
pause_writing() Called when the write buffer becomes full This method is called when the channel’s write buffer becomes full and no more data can be sent until the remote system adjusts its window. While data can still be buffered locally, applications may wish to stop producing new data until the write buffer has drained.
resume_writing() Called when the write buffer has sufficiently drained This method is called when the channel’s send window reopens and enough data has drained from the write buffer to allow the application to produce more data.

Other client session handlers
xon_xoff_requested(client_can_do) XON/XOFF flow control has been enabled or disabled This method is called to notify the client whether or not to enable XON/XOFF flow control. If client_can_do is True and output is being sent to an interactive terminal the application should allow input of Control-S and Control-Q to pause and resume output, respectively. If client_can_do is False, Control-S and Control-Q should be treated as normal input and passed through to the server. Non-interactive applications can ignore this request. By default, this message is ignored. Parameters client_can_do (bool) – Whether or not to enable XON/XOFF flow control
exit_status_received(status) A remote exit status has been received for this session This method is called when the shell, command, or subsystem running on the server terminates and returns an exit status. A zero exit status generally means that the operation was successful. This call will generally be followed by a call to connection_lost(). By default, the exit status is ignored. Parameters status (int) – The exit status returned by the remote process
exit_signal_received(signal, core_dumped, msg, lang) A remote exit signal has been received for this session This method is called when the shell, command, or subsystem running on the server terminates abnormally with a signal. A more detailed error may also be provided, along with an indication of whether the remote process dumped core. This call will generally be followed by a call to connection_lost(). By default, exit signals are ignored. Parameters signal (str) – The signal which caused the remote process to exit core_dumped (bool) – Whether or not the remote process dumped core msg (str) – Details about what error occurred lang (str) – The language the error message is in

SSHServerSession

class asyncssh.SSHServerSession

SSH server session handler

Applications should subclass this when implementing an SSH server session handler. The functions listed below should be implemented to define application-specific behavior. In particular, the standard asyncio protocol methods such as connection_made(), connection_lost(), data_received(), eof_received(), pause_writing(), and resume_writing() are all supported. In addition, pty_requested() is called when the client requests a pseudo-terminal, one of shell_requested(), exec_requested(), or subsystem_requested() is called depending on what type of session the client wants to start, session_started() is called once the SSH session is fully started, terminal_size_changed() is called when the client’s terminal size changes, signal_received() is called when the client sends a signal, and break_received() is called when the client sends a break.

General session handlers
connection_made(chan) Called when a channel is opened successfully This method is called when a channel is opened successfully. The channel parameter should be stored if needed for later use. Parameters chan (SSHServerChannel) – The channel which was successfully opened.
connection_lost(exc) Called when a channel is closed This method is called when a channel is closed. If the channel is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason for the channel close. Parameters exc (Exception) – The exception which caused the channel to close, or None if the channel closed cleanly.
session_started() Called when the session is started This method is called when a session has started up. For client and server sessions, this will be called once a shell, exec, or subsystem request has been successfully completed. For TCP and UNIX domain socket sessions, it will be called immediately after the connection is opened.

Server session open handlers
pty_requested(term_type, term_size, term_modes) A psuedo-terminal has been requested This method is called when the client sends a request to allocate a pseudo-terminal with the requested terminal type, size, and POSIX terminal modes. This method should return True if the request for the pseudo-terminal is accepted. Otherwise, it should return False to reject the request. By default, requests to allocate a pseudo-terminal are accepted but nothing is done with the associated terminal information. Applications wishing to use this information should implement this method and have it return True, or call get_terminal_type(), get_terminal_size(), or get_terminal_mode() on the SSHServerChannel to get the information they need after a shell, command, or subsystem is started. Parameters term_type (str) – Terminal type to set for this session term_size (tuple of 4 int values) – Terminal size to set for this session provided as a tuple of four int values: the width and height of the terminal in characters followed by the width and height of the terminal in pixels term_modes (dict) – POSIX terminal modes to set for this session, where keys are taken from POSIX terminal modes with values defined in section 8 of RFC 4254. Returns A bool indicating if the request for a pseudo-terminal was allowed or not
shell_requested() The client has requested a shell This method should be implemented by the application to perform whatever processing is required when a client makes a request to open an interactive shell. It should return True to accept the request, or False to reject it. If the application returns True, the session_started() method will be called once the channel is fully open. No output should be sent until this method is called. By default this method returns False to reject all requests. Returns A bool indicating if the shell request was allowed or not
exec_requested(command) The client has requested to execute a command This method should be implemented by the application to perform whatever processing is required when a client makes a request to execute a command. It should return True to accept the request, or False to reject it. If the application returns True, the session_started() method will be called once the channel is fully open. No output should be sent until this method is called. By default this method returns False to reject all requests. Parameters command (str) – The command the client has requested to execute Returns A bool indicating if the exec request was allowed or not
subsystem_requested(subsystem) The client has requested to start a subsystem This method should be implemented by the application to perform whatever processing is required when a client makes a request to start a subsystem. It should return True to accept the request, or False to reject it. If the application returns True, the session_started() method will be called once the channel is fully open. No output should be sent until this method is called. By default this method returns False to reject all requests. Parameters subsystem (str) – The subsystem to start Returns A bool indicating if the request to open the subsystem was allowed or not

General session read handlers
data_received(data, datatype) Called when data is received on the channel This method is called when data is received on the channel. If an encoding was specified when the channel was created, the data will be delivered as a string after decoding with the requested encoding. Otherwise, the data will be delivered as bytes. Parameters data (str or bytes) – The data received on the channel datatype – The extended data type of the data, from extended data types
eof_received() Called when EOF is received on the channel This method is called when an end-of-file indication is received on the channel, after which no more data will be received. If this method returns True, the channel remains half open and data may still be sent. Otherwise, the channel is automatically closed after this method returns. This is the default behavior for classes derived directly from SSHSession, but not when using the higher-level streams API. Because input is buffered in that case, streaming sessions enable half-open channels to allow applications to respond to input read after an end-of-file indication is received.

General session write handlers
pause_writing() Called when the write buffer becomes full This method is called when the channel’s write buffer becomes full and no more data can be sent until the remote system adjusts its window. While data can still be buffered locally, applications may wish to stop producing new data until the write buffer has drained.
resume_writing() Called when the write buffer has sufficiently drained This method is called when the channel’s send window reopens and enough data has drained from the write buffer to allow the application to produce more data.

Other server session handlers
break_received(msec) The client has sent a break This method is called when the client requests that the server perform a break operation on the terminal. If the break is performed, this method should return True. Otherwise, it should return False. By default, this method returns False indicating that no break was performed. Parameters msec (int) – The duration of the break in milliseconds Returns A bool to indicate if the break operation was performed or not
signal_received(signal) The client has sent a signal This method is called when the client delivers a signal on the channel. By default, signals from the client are ignored.
terminal_size_changed(width, height, pixwidth, pixheight) The terminal size has changed This method is called when a client requests a pseudo-terminal and again whenever the the size of he client’s terminal window changes. By default, this information is ignored, but applications wishing to use the terminal size can implement this method to get notified whenever it changes. Parameters width (int) – The width of the terminal in characters height (int) – The height of the terminal in characters pixwidth (int) – (optional) The width of the terminal in pixels pixheight (int) – (optional) The height of the terminal in pixels

SSHTCPSession

class asyncssh.SSHTCPSession

SSH TCP session handler

Applications should subclass this when implementing a handler for SSH direct or forwarded TCP connections.

SSH client applications wishing to open a direct connection should call create_connection() on their SSHClientConnection, passing in a factory which returns instances of this class.

Server applications wishing to allow direct connections should implement the coroutine connection_requested() on their SSHServer object and have it return instances of this class.

Server applications wishing to allow connection forwarding back to the client should implement the coroutine server_requested() on their SSHServer object and call create_connection() on their SSHServerConnection for each new connection, passing it a factory which returns instances of this class.

When a connection is successfully opened, session_started() will be called, after which the application can begin sending data. Received data will be passed to the data_received() method.

General session handlers
connection_made(chan) Called when a channel is opened successfully This method is called when a channel is opened successfully. The channel parameter should be stored if needed for later use. Parameters chan (SSHTCPChannel) – The channel which was successfully opened.
connection_lost(exc) Called when a channel is closed This method is called when a channel is closed. If the channel is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason for the channel close. Parameters exc (Exception) – The exception which caused the channel to close, or None if the channel closed cleanly.
session_started() Called when the session is started This method is called when a session has started up. For client and server sessions, this will be called once a shell, exec, or subsystem request has been successfully completed. For TCP and UNIX domain socket sessions, it will be called immediately after the connection is opened.

General session read handlers
data_received(data, datatype) Called when data is received on the channel This method is called when data is received on the channel. If an encoding was specified when the channel was created, the data will be delivered as a string after decoding with the requested encoding. Otherwise, the data will be delivered as bytes. Parameters data (str or bytes) – The data received on the channel datatype – The extended data type of the data, from extended data types
eof_received() Called when EOF is received on the channel This method is called when an end-of-file indication is received on the channel, after which no more data will be received. If this method returns True, the channel remains half open and data may still be sent. Otherwise, the channel is automatically closed after this method returns. This is the default behavior for classes derived directly from SSHSession, but not when using the higher-level streams API. Because input is buffered in that case, streaming sessions enable half-open channels to allow applications to respond to input read after an end-of-file indication is received.

General session write handlers
pause_writing() Called when the write buffer becomes full This method is called when the channel’s write buffer becomes full and no more data can be sent until the remote system adjusts its window. While data can still be buffered locally, applications may wish to stop producing new data until the write buffer has drained.
resume_writing() Called when the write buffer has sufficiently drained This method is called when the channel’s send window reopens and enough data has drained from the write buffer to allow the application to produce more data.

SSHUNIXSession

class asyncssh.SSHUNIXSession

SSH UNIX domain socket session handler

Applications should subclass this when implementing a handler for SSH direct or forwarded UNIX domain socket connections.

SSH client applications wishing to open a direct connection should call create_unix_connection() on their SSHClientConnection, passing in a factory which returns instances of this class.

Server applications wishing to allow direct connections should implement the coroutine unix_connection_requested() on their SSHServer object and have it return instances of this class.

Server applications wishing to allow connection forwarding back to the client should implement the coroutine unix_server_requested() on their SSHServer object and call create_unix_connection() on their SSHServerConnection for each new connection, passing it a factory which returns instances of this class.

When a connection is successfully opened, session_started() will be called, after which the application can begin sending data. Received data will be passed to the data_received() method.

General session handlers
connection_made(chan) Called when a channel is opened successfully This method is called when a channel is opened successfully. The channel parameter should be stored if needed for later use. Parameters chan (SSHUNIXChannel) – The channel which was successfully opened.
connection_lost(exc) Called when a channel is closed This method is called when a channel is closed. If the channel is shut down cleanly, exc will be None. Otherwise, it will be an exception explaining the reason for the channel close. Parameters exc (Exception) – The exception which caused the channel to close, or None if the channel closed cleanly.
session_started() Called when the session is started This method is called when a session has started up. For client and server sessions, this will be called once a shell, exec, or subsystem request has been successfully completed. For TCP and UNIX domain socket sessions, it will be called immediately after the connection is opened.

General session read handlers
data_received(data, datatype) Called when data is received on the channel This method is called when data is received on the channel. If an encoding was specified when the channel was created, the data will be delivered as a string after decoding with the requested encoding. Otherwise, the data will be delivered as bytes. Parameters data (str or bytes) – The data received on the channel datatype – The extended data type of the data, from extended data types
eof_received() Called when EOF is received on the channel This method is called when an end-of-file indication is received on the channel, after which no more data will be received. If this method returns True, the channel remains half open and data may still be sent. Otherwise, the channel is automatically closed after this method returns. This is the default behavior for classes derived directly from SSHSession, but not when using the higher-level streams API. Because input is buffered in that case, streaming sessions enable half-open channels to allow applications to respond to input read after an end-of-file indication is received.

General session write handlers
pause_writing() Called when the write buffer becomes full This method is called when the channel’s write buffer becomes full and no more data can be sent until the remote system adjusts its window. While data can still be buffered locally, applications may wish to stop producing new data until the write buffer has drained.
resume_writing() Called when the write buffer has sufficiently drained This method is called when the channel’s send window reopens and enough data has drained from the write buffer to allow the application to produce more data.

Channel Classes

SSHClientChannel

class asyncssh.SSHClientChannel

SSH client channel

Channel attributes
logger A logger associated with this channel

General channel info methods
get_extra_info(name, default=None) Get additional information about the channel This method returns extra information about the channel once it is established. Supported values include 'connection' to return the SSH connection this channel is running over plus all of the values supported on that connection. For TCP channels, the values 'local_peername' and 'remote_peername' are added to return the local and remote host and port information for the tunneled TCP connection. For UNIX channels, the values 'local_peername' and 'remote_peername' are added to return the local and remote path information for the tunneled UNIX domain socket connection. Since UNIX domain sockets provide no “source” address, only one of these will be filled in. See get_extra_info() on SSHClientConnection for more information. Additional information stored on the channel by calling set_extra_info() can also be returned here.
set_extra_info(**kwargs) Store additional information associated with the channel This method allows extra information to be associated with the channel. The information to store should be passed in as keyword parameters and can later be returned by calling get_extra_info() with one of the keywords as the name to retrieve.
get_environment() Return the environment for this session This method returns the environment set by the client when the session was opened. On the server, calls to this method should only be made after session_started has been called on the SSHServerSession. When using the stream-based API, calls to this can be made at any time after the handler function has started up. Returns A dictionary containing the environment variables set by the client
get_command() Return the command the client requested to execute, if any This method returns the command the client requested to execute when the session was opened, if any. If the client did not request that a command be executed, this method will return None. On the server, alls to this method should only be made after session_started has been called on the SSHServerSession. When using the stream-based API, calls to this can be made at any time after the handler function has started up.
get_subsystem() Return the subsystem the client requested to open, if any This method returns the subsystem the client requested to open when the session was opened, if any. If the client did not request that a subsystem be opened, this method will return None. On the server, calls to this method should only be made after session_started has been called on the SSHServerSession. When using the stream-based API, calls to this can be made at any time after the handler function has started up.

Client channel read methods
pause_reading() Pause delivery of incoming data This method is used to temporarily suspend delivery of incoming channel data. After this call, incoming data will no longer be delivered until resume_reading() is called. Data will be buffered locally up to the configured SSH channel window size, but window updates will no longer be sent, eventually causing back pressure on the remote system. Note Channel close notifications are not suspended by this call. If the remote system closes the channel while delivery is suspended, the channel will be closed even though some buffered data may not have been delivered.
resume_reading() Resume delivery of incoming data This method can be called to resume delivery of incoming data which was suspended by a call to pause_reading(). As soon as this method is called, any buffered data will be delivered immediately. A pending end-of-file notication may also be delivered if one was queued while reading was paused.

Client channel write methods
can_write_eof() Return whether the channel supports write_eof() This method always returns True.
get_write_buffer_size() Return the current size of the channel’s output buffer This method returns how many bytes are currently in the channel’s output buffer waiting to be written.
set_write_buffer_limits(high=None, low=None) Set the high- and low-water limits for write flow control This method sets the limits used when deciding when to call the pause_writing() and resume_writing() methods on SSH sessions. Writing will be paused when the write buffer size exceeds the high-water mark, and resumed when the write buffer size equals or drops below the low-water mark.
write(data, datatype=None) Write data on the channel This method can be called to send data on the channel. If an encoding was specified when the channel was created, the data should be provided as a string and will be converted using that encoding. Otherwise, the data should be provided as bytes. An extended data type can optionally be provided. For instance, this is used from a SSHServerSession to write data to stderr. Parameters data (str or bytes) – The data to send on the channel datatype (int) – (optional) The extended data type of the data, from extended data types Raises OSError if the channel isn’t open for sending or the extended data type is not valid for this type of channel
writelines(list_of_data, datatype=None) Write a list of data bytes on the channel This method can be called to write a list (or any iterable) of data bytes to the channel. It is functionality equivalent to calling write() on each element in the list. Parameters list_of_data (iterable of str or bytes) – The data to send on the channel datatype (int) – (optional) The extended data type of the data, from extended data types Raises OSError if the channel isn’t open for sending or the extended data type is not valid for this type of channel
write_eof() Write EOF on the channel This method sends an end-of-file indication on the channel, after which no more data can be sent. The channel remains open, though, and data may still be sent in the other direction. Raises OSError if the channel isn’t open for sending

Other client channel methods
get_exit_status() Return the session’s exit status This method returns the exit status of the session if one has been sent. If an exit signal was sent, this method returns -1 and the exit signal information can be collected by calling get_exit_signal(). If neither has been sent, this method returns None.
get_exit_signal() Return the session’s exit signal, if one was sent This method returns information about the exit signal sent on this session. If an exit signal was sent, a tuple is returned containing the signal name, a boolean for whether a core dump occurred, a message associated with the signal, and the language the message was in. Otherwise, this method returns None.
get_returncode() Return the session’s exit status or signal This method returns the exit status of the session if one has been sent. If an exit signal was sent, this method returns the negative of the numeric value of that signal, matching the behavior of asyncio.SubprocessTransport.get_returncode(). If neither has been sent, this method returns None. Returns int or None
change_terminal_size(width, height, pixwidth=0, pixheight=0) Change the terminal window size for this session This method changes the width and height of the terminal associated with this session. Parameters width (int) – The width of the terminal in characters height (int) – The height of the terminal in characters pixwidth (int) – (optional) The width of the terminal in pixels pixheight (int) – (optional) The height of the terminal in pixels
send_break(msec) Send a break to the remote process This method requests that the server perform a break operation on the remote process or service as described in RFC 4335. Parameters msec (int) – The duration of the break in milliseconds Raises OSError if the channel is not open
send_signal(signal) Send a signal to the remote process This method can be called to deliver a signal to the remote process or service. Signal names should be as described in section 6.10 of RFC 4254, or can be integer values as defined in the signal module, in which case they will be translated to their corresponding signal name before being sent. Note OpenSSH’s SSH server implementation prior to version 7.9 does not support this message, so attempts to use send_signal(), terminate(), or kill() with an older OpenSSH SSH server will end up being ignored. This was tracked in OpenSSH bug 1424. Parameters signal (str or int) – The signal to deliver Raises OSError if the channel is not open ValueError if the signal number is unknown
kill() Forcibly kill the remote process This method can be called to forcibly stop the remote process or service by sending it a KILL signal. Raises OSError if the channel is not open Note If your server-side runs on OpenSSH, this might be ineffective; for more details, see the note in send_signal()
terminate() Terminate the remote process This method can be called to terminate the remote process or service by sending it a TERM signal. Raises OSError if the channel is not open Note If your server-side runs on OpenSSH, this might be ineffective; for more details, see the note in send_signal()

General channel close methods
abort() Forcibly close the channel This method can be called to forcibly close the channel, after which no more data can be sent or received. Any unsent buffered data and any incoming data in flight will be discarded.
close() Cleanly close the channel This method can be called to cleanly close the channel, after which no more data can be sent or received. Any unsent buffered data will be flushed asynchronously before the channel is closed.
is_closing() Return if the channel is closing or is closed
async wait_closed() Wait for this channel to close This method is a coroutine which can be called to block until this channel has finished closing.

SSHServerChannel

class asyncssh.SSHServerChannel

SSH server channel

Channel attributes
logger A logger associated with this channel

General channel info methods
get_extra_info(name, default=None) Get additional information about the channel This method returns extra information about the channel once it is established. Supported values include 'connection' to return the SSH connection this channel is running over plus all of the values supported on that connection. For TCP channels, the values 'local_peername' and 'remote_peername' are added to return the local and remote host and port information for the tunneled TCP connection. For UNIX channels, the values 'local_peername' and 'remote_peername' are added to return the local and remote path information for the tunneled UNIX domain socket connection. Since UNIX domain sockets provide no “source” address, only one of these will be filled in. See get_extra_info() on SSHClientConnection for more information. Additional information stored on the channel by calling set_extra_info() can also be returned here.
set_extra_info(**kwargs) Store additional information associated with the channel This method allows extra information to be associated with the channel. The information to store should be passed in as keyword parameters and can later be returned by calling get_extra_info() with one of the keywords as the name to retrieve.
get_environment() Return the environment for this session This method returns the environment set by the client when the session was opened. On the server, calls to this method should only be made after session_started has been called on the SSHServerSession. When using the stream-based API, calls to this can be made at any time after the handler function has started up. Returns A dictionary containing the environment variables set by the client
get_command() Return the command the client requested to execute, if any This method returns the command the client requested to execute when the session was opened, if any. If the client did not request that a command be executed, this method will return None. On the server, alls to this method should only be made after session_started has been called on the SSHServerSession. When using the stream-based API, calls to this can be made at any time after the handler function has started up.
get_subsystem() Return the subsystem the client requested to open, if any This method returns the subsystem the client requested to open when the session was opened, if any. If the client did not request that a subsystem be opened, this method will return None. On the server, calls to this method should only be made after session_started has been called on the SSHServerSession. When using the stream-based API, calls to this can be made at any time after the handler function has started up.

Server channel info methods
get_terminal_type() Return the terminal type for this session This method returns the terminal type set by the client when the session was opened. If the client didn’t request a pseudo-terminal, this method will return None. Calls to this method should only be made after session_started has been called on the SSHServerSession. When using the stream-based API, calls to this can be made at any time after the handler function has started up. Returns A str containing the terminal type or None if no pseudo-terminal was requested
get_terminal_size() Return terminal size information for this session This method returns the latest terminal size information set by the client. If the client didn’t set any terminal size information, all values returned will be zero. Calls to this method should only be made after session_started has been called on the SSHServerSession. When using the stream-based API, calls to this can be made at any time after the handler function has started up. Also see terminal_size_changed() or the TerminalSizeChanged exception for how to get notified when the terminal size changes. Returns A tuple of four int values containing the width and height of the terminal in characters and the width and height of the terminal in pixels
get_terminal_mode(mode) Return the requested TTY mode for this session This method looks up the value of a POSIX terminal mode set by the client when the session was opened. If the client didn’t request a pseudo-terminal or didn’t set the requested TTY mode opcode, this method will return None. Calls to this method should only be made after session_started has been called on the SSHServerSession. When using the stream-based API, calls to this can be made at any time after the handler function has started up. Parameters mode (int) – POSIX terminal mode taken from POSIX terminal modes to look up Returns An int containing the value of the requested POSIX terminal mode or None if the requested mode was not set
get_x11_display() Return the display to use for X11 forwarding When X11 forwarding has been requested by the client, this method returns the X11 display which should be used to open a forwarded connection. If the client did not request X11 forwarding, this method returns None. Returns A str containing the X11 display or None if X11 fowarding was not requested
get_agent_path() Return the path of the ssh-agent listening socket When agent forwarding has been requested by the client, this method returns the path of the listening socket which should be used to open a forwarded agent connection. If the client did not request agent forwarding, this method returns None. Returns A str containing the ssh-agent socket path or None if agent fowarding was not requested

Server channel read methods
pause_reading() Pause delivery of incoming data This method is used to temporarily suspend delivery of incoming channel data. After this call, incoming data will no longer be delivered until resume_reading() is called. Data will be buffered locally up to the configured SSH channel window size, but window updates will no longer be sent, eventually causing back pressure on the remote system. Note Channel close notifications are not suspended by this call. If the remote system closes the channel while delivery is suspended, the channel will be closed even though some buffered data may not have been delivered.
resume_reading() Resume delivery of incoming data This method can be called to resume delivery of incoming data which was suspended by a call to pause_reading(). As soon as this method is called, any buffered data will be delivered immediately. A pending end-of-file notication may also be delivered if one was queued while reading was paused.

Server channel write methods
can_write_eof() Return whether the channel supports write_eof() This method always returns True.
get_write_buffer_size() Return the current size of the channel’s output buffer This method returns how many bytes are currently in the channel’s output buffer waiting to be written.
set_write_buffer_limits(high=None, low=None) Set the high- and low-water limits for write flow control This method sets the limits used when deciding when to call the pause_writing() and resume_writing() methods on SSH sessions. Writing will be paused when the write buffer size exceeds the high-water mark, and resumed when the write buffer size equals or drops below the low-water mark.
write(data, datatype=None) Write data on the channel This method can be called to send data on the channel. If an encoding was specified when the channel was created, the data should be provided as a string and will be converted using that encoding. Otherwise, the data should be provided as bytes. An extended data type can optionally be provided. For instance, this is used from a SSHServerSession to write data to stderr. Parameters data (str or bytes) – The data to send on the channel datatype (int) – (optional) The extended data type of the data, from extended data types Raises OSError if the channel isn’t open for sending or the extended data type is not valid for this type of channel
writelines(list_of_data, datatype=None) Write a list of data bytes on the channel This method can be called to write a list (or any iterable) of data bytes to the channel. It is functionality equivalent to calling write() on each element in the list. Parameters list_of_data (iterable of str or bytes) – The data to send on the channel datatype (int) – (optional) The extended data type of the data, from extended data types Raises OSError if the channel isn’t open for sending or the extended data type is not valid for this type of channel
write_stderr(data) Write output to stderr This method can be called to send output to the client which is intended to be displayed on stderr. If an encoding was specified when the channel was created, the data should be provided as a string and will be converted using that encoding. Otherwise, the data should be provided as bytes. Parameters data (str or bytes) – The data to send to stderr Raises OSError if the channel isn’t open for sending
writelines_stderr(list_of_data) Write a list of data bytes to stderr This method can be called to write a list (or any iterable) of data bytes to the channel. It is functionality equivalent to calling write_stderr() on each element in the list.
write_eof() Write EOF on the channel This method sends an end-of-file indication on the channel, after which no more data can be sent. The channel remains open, though, and data may still be sent in the other direction. Raises OSError if the channel isn’t open for sending

Other server channel methods
set_xon_xoff(client_can_do) Set whether the client should enable XON/XOFF flow control This method can be called to tell the client whether or not to enable XON/XOFF flow control, indicating that it should intercept Control-S and Control-Q coming from its local terminal to pause and resume output, respectively. Applications should set client_can_do to True to enable this functionality or to False to tell the client to forward Control-S and Control-Q through as normal input. Parameters client_can_do (bool) – Whether or not the client should enable XON/XOFF flow control
exit(status) Send exit status and close the channel This method can be called to report an exit status for the process back to the client and close the channel. A zero exit status is generally returned when the operation was successful. After reporting the status, the channel is closed. Parameters status (int) – The exit status to report to the client Raises OSError if the channel isn’t open
exit_with_signal(signal, core_dumped=False, msg='', lang='en-US') Send exit signal and close the channel This method can be called to report that the process terminated abnormslly with a signal. A more detailed error message may also provided, along with an indication of whether or not the process dumped core. After reporting the signal, the channel is closed. Parameters signal (str) – The signal which caused the process to exit core_dumped (bool) – (optional) Whether or not the process dumped core msg (str) – (optional) Details about what error occurred lang (str) – (optional) The language the error message is in Raises OSError if the channel isn’t open

General channel close methods
abort() Forcibly close the channel This method can be called to forcibly close the channel, after which no more data can be sent or received. Any unsent buffered data and any incoming data in flight will be discarded.
close() Cleanly close the channel This method can be called to cleanly close the channel, after which no more data can be sent or received. Any unsent buffered data will be flushed asynchronously before the channel is closed.
is_closing() Return if the channel is closing or is closed
async wait_closed() Wait for this channel to close This method is a coroutine which can be called to block until this channel has finished closing.

SSHLineEditorChannel

class asyncssh.SSHLineEditorChannel

Input line editor channel wrapper

When creating server channels with line_editor set to True, this class is wrapped around the channel, providing the caller with the ability to enable and disable input line editing and echoing.

Note

Line editing is only available when a psuedo-terminal is requested on the server channel and the character encoding on the channel is not set to None.

Line editor methods
register_key(key, handler) Register a handler to be called when a key is pressed This method registers a handler function which will be called when a user presses the specified key while inputting a line. The handler will be called with arguments of the current input line and cursor position, and updated versions of these two values should be returned as a tuple. The handler can also return a tuple of a signal name and negative cursor position to cause a signal to be delivered on the channel. In this case, the current input line is left unchanged but the signal is delivered before processing any additional input. This can be used to define “hot keys” that trigger actions unrelated to editing the input. If the registered key is printable text, returning True will insert that text at the current cursor position, acting as if no handler was registered for that key. This is useful if you want to perform a special action in some cases but not others, such as based on the current cursor position. Returning False will ring the bell and leave the input unchanged, indicating the requested action could not be performed. Parameters key (str) – The key sequence to look for handler (callable) – The handler function to call when the key is pressed
unregister_key(key) Remove the handler associated with a key This method removes a handler function associated with the specified key. If the key sequence is printable, this will cause it to return to being inserted at the current position when pressed. Otherwise, it will cause the bell to ring to signal the key is not understood. Parameters key (str) – The key sequence to look for
set_line_mode(line_mode) Enable/disable input line editing This method enabled or disables input line editing. When set, only full lines of input are sent to the session, and each line of input can be edited before it is sent. Parameters line_mode (bool) – Whether or not to process input a line at a time
set_echo(echo) Enable/disable echoing of input in line mode This method enables or disables echoing of input data when input line editing is enabled. Parameters echo (bool) – Whether or not input to echo input as it is entered

SSHTCPChannel

class asyncssh.SSHTCPChannel

SSH TCP channel

Channel attributes
logger A logger associated with this channel

General channel info methods
get_extra_info(name, default=None) Get additional information about the channel This method returns extra information about the channel once it is established. Supported values include 'connection' to return the SSH connection this channel is running over plus all of the values supported on that connection. For TCP channels, the values 'local_peername' and 'remote_peername' are added to return the local and remote host and port information for the tunneled TCP connection. For UNIX channels, the values 'local_peername' and 'remote_peername' are added to return the local and remote path information for the tunneled UNIX domain socket connection. Since UNIX domain sockets provide no “source” address, only one of these will be filled in. See get_extra_info() on SSHClientConnection for more information. Additional information stored on the channel by calling set_extra_info() can also be returned here.
set_extra_info(**kwargs) Store additional information associated with the channel This method allows extra information to be associated with the channel. The information to store should be passed in as keyword parameters and can later be returned by calling get_extra_info() with one of the keywords as the name to retrieve.

General channel read methods
pause_reading() Pause delivery of incoming data This method is used to temporarily suspend delivery of incoming channel data. After this call, incoming data will no longer be delivered until resume_reading() is called. Data will be buffered locally up to the configured SSH channel window size, but window updates will no longer be sent, eventually causing back pressure on the remote system. Note Channel close notifications are not suspended by this call. If the remote system closes the channel while delivery is suspended, the channel will be closed even though some buffered data may not have been delivered.
resume_reading() Resume delivery of incoming data This method can be called to resume delivery of incoming data which was suspended by a call to pause_reading(). As soon as this method is called, any buffered data will be delivered immediately. A pending end-of-file notication may also be delivered if one was queued while reading was paused.

General channel write methods
can_write_eof() Return whether the channel supports write_eof() This method always returns True.
get_write_buffer_size() Return the current size of the channel’s output buffer This method returns how many bytes are currently in the channel’s output buffer waiting to be written.
set_write_buffer_limits(high=None, low=None) Set the high- and low-water limits for write flow control This method sets the limits used when deciding when to call the pause_writing() and resume_writing() methods on SSH sessions. Writing will be paused when the write buffer size exceeds the high-water mark, and resumed when the write buffer size equals or drops below the low-water mark.
write(data, datatype=None) Write data on the channel This method can be called to send data on the channel. If an encoding was specified when the channel was created, the data should be provided as a string and will be converted using that encoding. Otherwise, the data should be provided as bytes. An extended data type can optionally be provided. For instance, this is used from a SSHServerSession to write data to stderr. Parameters data (str or bytes) – The data to send on the channel datatype (int) – (optional) The extended data type of the data, from extended data types Raises OSError if the channel isn’t open for sending or the extended data type is not valid for this type of channel
writelines(list_of_data, datatype=None) Write a list of data bytes on the channel This method can be called to write a list (or any iterable) of data bytes to the channel. It is functionality equivalent to calling write() on each element in the list. Parameters list_of_data (iterable of str or bytes) – The data to send on the channel datatype (int) – (optional) The extended data type of the data, from extended data types Raises OSError if the channel isn’t open for sending or the extended data type is not valid for this type of channel
write_eof() Write EOF on the channel This method sends an end-of-file indication on the channel, after which no more data can be sent. The channel remains open, though, and data may still be sent in the other direction. Raises OSError if the channel isn’t open for sending

General channel close methods
abort() Forcibly close the channel This method can be called to forcibly close the channel, after which no more data can be sent or received. Any unsent buffered data and any incoming data in flight will be discarded.
close() Cleanly close the channel This method can be called to cleanly close the channel, after which no more data can be sent or received. Any unsent buffered data will be flushed asynchronously before the channel is closed.
is_closing() Return if the channel is closing or is closed
async wait_closed() Wait for this channel to close This method is a coroutine which can be called to block until this channel has finished closing.

SSHUNIXChannel

class asyncssh.SSHUNIXChannel

SSH UNIX channel

Channel attributes
logger A logger associated with this channel

General channel info methods
get_extra_info(name, default=None) Get additional information about the channel This method returns extra information about the channel once it is established. Supported values include 'connection' to return the SSH connection this channel is running over plus all of the values supported on that connection. For TCP channels, the values 'local_peername' and 'remote_peername' are added to return the local and remote host and port information for the tunneled TCP connection. For UNIX channels, the values 'local_peername' and 'remote_peername' are added to return the local and remote path information for the tunneled UNIX domain socket connection. Since UNIX domain sockets provide no “source” address, only one of these will be filled in. See get_extra_info() on SSHClientConnection for more information. Additional information stored on the channel by calling set_extra_info() can also be returned here.
set_extra_info(**kwargs) Store additional information associated with the channel This method allows extra information to be associated with the channel. The information to store should be passed in as keyword parameters and can later be returned by calling get_extra_info() with one of the keywords as the name to retrieve.

General channel read methods
pause_reading() Pause delivery of incoming data This method is used to temporarily suspend delivery of incoming channel data. After this call, incoming data will no longer be delivered until resume_reading() is called. Data will be buffered locally up to the configured SSH channel window size, but window updates will no longer be sent, eventually causing back pressure on the remote system. Note Channel close notifications are not suspended by this call. If the remote system closes the channel while delivery is suspended, the channel will be closed even though some buffered data may not have been delivered.
resume_reading() Resume delivery of incoming data This method can be called to resume delivery of incoming data which was suspended by a call to pause_reading(). As soon as this method is called, any buffered data will be delivered immediately. A pending end-of-file notication may also be delivered if one was queued while reading was paused.

General channel write methods
can_write_eof() Return whether the channel supports write_eof() This method always returns True.
get_write_buffer_size() Return the current size of the channel’s output buffer This method returns how many bytes are currently in the channel’s output buffer waiting to be written.
set_write_buffer_limits(high=None, low=None) Set the high- and low-water limits for write flow control This method sets the limits used when deciding when to call the pause_writing() and resume_writing() methods on SSH sessions. Writing will be paused when the write buffer size exceeds the high-water mark, and resumed when the write buffer size equals or drops below the low-water mark.
write(data, datatype=None) Write data on the channel This method can be called to send data on the channel. If an encoding was specified when the channel was created, the data should be provided as a string and will be converted using that encoding. Otherwise, the data should be provided as bytes. An extended data type can optionally be provided. For instance, this is used from a SSHServerSession to write data to stderr. Parameters data (str or bytes) – The data to send on the channel datatype (int) – (optional) The extended data type of the data, from extended data types Raises OSError if the channel isn’t open for sending or the extended data type is not valid for this type of channel
writelines(list_of_data, datatype=None) Write a list of data bytes on the channel This method can be called to write a list (or any iterable) of data bytes to the channel. It is functionality equivalent to calling write() on each element in the list. Parameters list_of_data (iterable of str or bytes) – The data to send on the channel datatype (int) – (optional) The extended data type of the data, from extended data types Raises OSError if the channel isn’t open for sending or the extended data type is not valid for this type of channel
write_eof() Write EOF on the channel This method sends an end-of-file indication on the channel, after which no more data can be sent. The channel remains open, though, and data may still be sent in the other direction. Raises OSError if the channel isn’t open for sending

General channel close methods
abort() Forcibly close the channel This method can be called to forcibly close the channel, after which no more data can be sent or received. Any unsent buffered data and any incoming data in flight will be discarded.
close() Cleanly close the channel This method can be called to cleanly close the channel, after which no more data can be sent or received. Any unsent buffered data will be flushed asynchronously before the channel is closed.
is_closing() Return if the channel is closing or is closed
async wait_closed() Wait for this channel to close This method is a coroutine which can be called to block until this channel has finished closing.

Listener Classes

SSHListener

class asyncssh.SSHListener

SSH listener for inbound connections

get_port() Return the port number being listened on This method returns the port number that the remote listener was bound to. When the requested remote listening port is 0 to indicate a dynamic port, this method can be called to determine what listening port was selected. This function only applies to TCP listeners. Returns The port number being listened on
close() Stop listening for new connections This method can be called to stop listening for connections. Existing connections will remain open.
async wait_closed() Wait for the listener to close This method is a coroutine which waits for the associated listeners to be closed.

Stream Classes

SSHReader

class asyncssh.SSHReader

SSH read stream handler

channel The SSH channel associated with this stream
logger The SSH logger associated with this stream
get_extra_info(name, default=None) Return additional information about this stream This method returns extra information about the channel associated with this stream. See get_extra_info() on SSHClientChannel for additional information.
at_eof() Return whether the stream is at EOF This method returns True when EOF has been received and all data in the stream has been read.
async read(n=-1) Read data from the stream This method is a coroutine which reads up to n bytes or characters from the stream. If n is not provided or set to -1, it reads until EOF or a signal is received. If EOF is received and the receive buffer is empty, an empty bytes or str object is returned. If the next data in the stream is a signal, the signal is delivered as a raised exception. Note Unlike traditional asyncio stream readers, the data will be delivered as either bytes or a str depending on whether an encoding was specified when the underlying channel was opened.
async readline() Read one line from the stream This method is a coroutine which reads one line, ending in 'n'. If EOF is received before 'n' is found, the partial line is returned. If EOF is received and the receive buffer is empty, an empty bytes or str object is returned. If the next data in the stream is a signal, the signal is delivered as a raised exception. Note In Python 3.5 and later, SSHReader objects can also be used as async iterators, returning input data one line at a time.
async readuntil(separator) Read data from the stream until separator is seen This method is a coroutine which reads from the stream until the requested separator is seen. If a match is found, the returned data will include the separator at the end. The separator argument can be either a single bytes or str value or a sequence of multiple values to match against, returning data as soon as any of the separators are found in the stream. If EOF or a signal is received before a match occurs, an IncompleteReadError is raised and its partial attribute will contain the data in the stream prior to the EOF or signal. If the next data in the stream is a signal, the signal is delivered as a raised exception.
async readexactly(n) Read an exact amount of data from the stream This method is a coroutine which reads exactly n bytes or characters from the stream. If EOF or a signal is received in the stream before n bytes are read, an IncompleteReadError is raised and its partial attribute will contain the data before the EOF or signal. If the next data in the stream is a signal, the signal is delivered as a raised exception.

SSHWriter

class asyncssh.SSHWriter

SSH write stream handler

channel The SSH channel associated with this stream
logger The SSH logger associated with this stream
get_extra_info(name, default=None) Return additional information about this stream This method returns extra information about the channel associated with this stream. See get_extra_info() on SSHClientChannel for additional information.
can_write_eof() Return whether the stream supports write_eof()
async drain() Wait until the write buffer on the channel is flushed This method is a coroutine which blocks the caller if the stream is currently paused for writing, returning when enough data has been sent on the channel to allow writing to resume. This can be used to avoid buffering an excessive amount of data in the channel’s send buffer.
write(data) Write data to the stream This method writes bytes or characters to the stream. Note Unlike traditional asyncio stream writers, the data must be supplied as either bytes or a str depending on whether an encoding was specified when the underlying channel was opened.
writelines(list_of_data) Write a collection of data to the stream
write_eof() Write EOF on the channel This method sends an end-of-file indication on the channel, after which no more data can be written. Note On an SSHServerChannel where multiple output streams are created, writing EOF on one stream signals EOF for all of them, since it applies to the channel as a whole.
close() Close the channel Note After this is called, no data can be read or written from any of the streams associated with this channel.
is_closing() Return if the stream is closing or is closed
async wait_closed() Wait until the stream is closed This should be called after close() to wait until the underlying connection is closed.

SFTP Support

SFTPClient

class asyncssh.SFTPClient

SFTP client

This class represents the client side of an SFTP session. It is started by calling the start_sftp_client() method on the SSHClientConnection class.

SFTP client attributes
logger A logger associated with this SFTP client

File transfer methods
async get(remotepaths, localpath=None, *, preserve=False, recurse=False, follow_symlinks=False, block_size=16384, max_requests=128, progress_handler=None, error_handler=None) Download remote files This method downloads one or more files or directories from the remote system. Either a single remote path or a sequence of remote paths to download can be provided. When downloading a single file or directory, the local path can be either the full path to download data into or the path to an existing directory where the data should be placed. In the latter case, the base file name from the remote path will be used as the local name. When downloading multiple files, the local path must refer to an existing directory. If no local path is provided, the file is downloaded into the current local working directory. If preserve is True, the access and modification times and permissions of the original file are set on the downloaded file. If recurse is True and the remote path points at a directory, the entire subtree under that directory is downloaded. If follow_symlinks is set to True, symbolic links found on the remote system will have the contents of their target downloaded rather than creating a local symbolic link. When using this option during a recursive download, one needs to watch out for links that result in loops. The block_size argument specifies the size of read and write requests issued when downloading the files, defaulting to 16 KB. The max_requests argument specifies the maximum number of parallel read or write requests issued, defaulting to 128. If progress_handler is specified, it will be called after each block of a file is successfully downloaded. The arguments passed to this handler will be the source path, destination path, bytes downloaded so far, and total bytes in the file being downloaded. If multiple source paths are provided or recurse is set to True, the progress_handler will be called consecutively on each file being downloaded. If error_handler is specified and an error occurs during the download, this handler will be called with the exception instead of it being raised. This is intended to primarily be used when multiple remote paths are provided or when recurse is set to True, to allow error information to be collected without aborting the download of the remaining files. The error handler can raise an exception if it wants the download to completely stop. Otherwise, after an error, the download will continue starting with the next file. Parameters remotepaths (PurePath, str, or bytes, or a sequence of these) – The paths of the remote files or directories to download localpath (PurePath, str, or bytes) – (optional) The path of the local file or directory to download into preserve (bool) – (optional) Whether or not to preserve the original file attributes recurse (bool) – (optional) Whether or not to recursively copy directories follow_symlinks (bool) – (optional) Whether or not to follow symbolic links block_size (int) – (optional) The block size to use for file reads and writes max_requests (int) – (optional) The maximum number of parallel read or write requests progress_handler (callable) – (optional) The function to call to report download progress error_handler (callable) – (optional) The function to call when an error occurs Raises OSError if a local file I/O error occurs SFTPError if the server returns an error
async put(localpaths, remotepath=None, *, preserve=False, recurse=False, follow_symlinks=False, block_size=16384, max_requests=128, progress_handler=None, error_handler=None) Upload local files This method uploads one or more files or directories to the remote system. Either a single local path or a sequence of local paths to upload can be provided. When uploading a single file or directory, the remote path can be either the full path to upload data into or the path to an existing directory where the data should be placed. In the latter case, the base file name from the local path will be used as the remote name. When uploading multiple files, the remote path must refer to an existing directory. If no remote path is provided, the file is uploaded into the current remote working directory. If preserve is True, the access and modification times and permissions of the original file are set on the uploaded file. If recurse is True and the local path points at a directory, the entire subtree under that directory is uploaded. If follow_symlinks is set to True, symbolic links found on the local system will have the contents of their target uploaded rather than creating a remote symbolic link. When using this option during a recursive upload, one needs to watch out for links that result in loops. The block_size argument specifies the size of read and write requests issued when uploading the files, defaulting to 16 KB. The max_requests argument specifies the maximum number of parallel read or write requests issued, defaulting to 128. If progress_handler is specified, it will be called after each block of a file is successfully uploaded. The arguments passed to this handler will be the source path, destination path, bytes uploaded so far, and total bytes in the file being uploaded. If multiple source paths are provided or recurse is set to True, the progress_handler will be called consecutively on each file being uploaded. If error_handler is specified and an error occurs during the upload, this handler will be called with the exception instead of it being raised. This is intended to primarily be used when multiple local paths are provided or when recurse is set to True, to allow error information to be collected without aborting the upload of the remaining files. The error handler can raise an exception if it wants the upload to completely stop. Otherwise, after an error, the upload will continue starting with the next file. Parameters localpaths (PurePath, str, or bytes, or a sequence of these) – The paths of the local files or directories to upload remotepath (PurePath, str, or bytes) – (optional) The path of the remote file or directory to upload into preserve (bool) – (optional) Whether or not to preserve the original file attributes recurse (bool) – (optional) Whether or not to recursively copy directories follow_symlinks (bool) – (optional) Whether or not to follow symbolic links block_size (int) – (optional) The block size to use for file reads and writes max_requests (int) – (optional) The maximum number of parallel read or write requests progress_handler (callable) – (optional) The function to call to report upload progress error_handler (callable) – (optional) The function to call when an error occurs Raises OSError if a local file I/O error occurs SFTPError if the server returns an error
async copy(srcpaths, dstpath=None, *, preserve=False, recurse=False, follow_symlinks=False, block_size=16384, max_requests=128, progress_handler=None, error_handler=None) Copy remote files to a new location This method copies one or more files or directories on the remote system to a new location. Either a single source path or a sequence of source paths to copy can be provided. When copying a single file or directory, the destination path can be either the full path to copy data into or the path to an existing directory where the data should be placed. In the latter case, the base file name from the source path will be used as the destination name. When copying multiple files, the destination path must refer to an existing remote directory. If no destination path is provided, the file is copied into the current remote working directory. If preserve is True, the access and modification times and permissions of the original file are set on the copied file. If recurse is True and the source path points at a directory, the entire subtree under that directory is copied. If follow_symlinks is set to True, symbolic links found in the source will have the contents of their target copied rather than creating a copy of the symbolic link. When using this option during a recursive copy, one needs to watch out for links that result in loops. The block_size argument specifies the size of read and write requests issued when copying the files, defaulting to 16 KB. The max_requests argument specifies the maximum number of parallel read or write requests issued, defaulting to 128. If progress_handler is specified, it will be called after each block of a file is successfully copied. The arguments passed to this handler will be the source path, destination path, bytes copied so far, and total bytes in the file being copied. If multiple source paths are provided or recurse is set to True, the progress_handler will be called consecutively on each file being copied. If error_handler is specified and an error occurs during the copy, this handler will be called with the exception instead of it being raised. This is intended to primarily be used when multiple source paths are provided or when recurse is set to True, to allow error information to be collected without aborting the copy of the remaining files. The error handler can raise an exception if it wants the copy to completely stop. Otherwise, after an error, the copy will continue starting with the next file. Parameters srcpaths (PurePath, str, or bytes, or a sequence of these) – The paths of the remote files or directories to copy dstpath (PurePath, str, or bytes) – (optional) The path of the remote file or directory to copy into preserve (bool) – (optional) Whether or not to preserve the original file attributes recurse (bool) – (optional) Whether or not to recursively copy directories follow_symlinks (bool) – (optional) Whether or not to follow symbolic links block_size (int) – (optional) The block size to use for file reads and writes max_requests (int) – (optional) The maximum number of parallel read or write requests progress_handler (callable) – (optional) The function to call to report copy progress error_handler (callable) – (optional) The function to call when an error occurs Raises OSError if a local file I/O error occurs SFTPError if the server returns an error
async mget(remotepaths, localpath=None, *, preserve=False, recurse=False, follow_symlinks=False, block_size=16384, max_requests=128, progress_handler=None, error_handler=None) Download remote files with glob pattern match This method downloads files and directories from the remote system matching one or more glob patterns. The arguments to this method are identical to the get() method, except that the remote paths specified can contain wildcard patterns.
async mput(localpaths, remotepath=None, *, preserve=False, recurse=False, follow_symlinks=False, block_size=16384, max_requests=128, progress_handler=None, error_handler=None) Upload local files with glob pattern match This method uploads files and directories to the remote system matching one or more glob patterns. The arguments to this method are identical to the put() method, except that the local paths specified can contain wildcard patterns.
async mcopy(srcpaths, dstpath=None, *, preserve=False, recurse=False, follow_symlinks=False, block_size=16384, max_requests=128, progress_handler=None, error_handler=None) Download remote files with glob pattern match This method copies files and directories on the remote system matching one or more glob patterns. The arguments to this method are identical to the copy() method, except that the source paths specified can contain wildcard patterns.

File access methods
open(path, mode='r', attrs=SFTPAttrs(), encoding='utf-8', errors='strict', block_size=16384, max_requests=128) Open a remote file This method opens a remote file and returns an SFTPClientFile object which can be used to read and write data and get and set file attributes. The path can be either a str or bytes value. If it is a str, it will be encoded using the file encoding specified when the SFTPClient was started. The following open mode flags are supported: Mode Description FXF_READ Open the file for reading. FXF_WRITE Open the file for writing. If both this and FXF_READ are set, open the file for both reading and writing. FXF_APPEND Force writes to append data to the end of the file regardless of seek position. FXF_CREAT Create the file if it doesn’t exist. Without this, attempts to open a non-existent file will fail. FXF_TRUNC Truncate the file to zero length if it already exists. FXF_EXCL Return an error when trying to open a file which already exists. By default, file data is read and written as strings in UTF-8 format with strict error checking, but this can be changed using the encoding and errors parameters. To read and write data as bytes in binary format, an encoding value of None can be used. Instead of these flags, a Python open mode string can also be provided. Python open modes map to the above flags as follows: Mode Flags r FXF_READ w FXF_WRITE | FXF_CREAT | FXF_TRUNC a FXF_WRITE | FXF_CREAT | FXF_APPEND x FXF_WRITE | FXF_CREAT | FXF_EXCL r+ FXF_READ | FXF_WRITE w+ FXF_READ | FXF_WRITE | FXF_CREAT | FXF_TRUNC a+ FXF_READ | FXF_WRITE | FXF_CREAT | FXF_APPEND x+ FXF_READ | FXF_WRITE | FXF_CREAT | FXF_EXCL Including a ‘b’ in the mode causes the encoding to be set to None, forcing all data to be read and written as bytes in binary format. The attrs argument is used to set initial attributes of the file if it needs to be created. Otherwise, this argument is ignored. The block_size argument specifies the size of parallel read and write requests issued on the file. If set to None, each read or write call will become a single request to the SFTP server. Otherwise, read or write calls larger than this size will be turned into parallel requests to the server of the requested size, defaulting to 16 KB. Note The OpenSSH SFTP server will close the connection if it receives a message larger than 256 KB, and limits read requests to returning no more than 64 KB. So, when connecting to an OpenSSH SFTP server, it is recommended that the block_size be set below these sizes. The max_requests argument specifies the maximum number of parallel read or write requests issued, defaulting to 128. Parameters path (PurePath, str, or bytes) – The name of the remote file to open pflags_or_mode (int or str) – (optional) The access mode to use for the remote file (see above) attrs (SFTPAttrs) – (optional) File attributes to use if the file needs to be created encoding (str) – (optional) The Unicode encoding to use for data read and written to the remote file errors (str) – (optional) The error-handling mode if an invalid Unicode byte sequence is detected, defaulting to ‘strict’ which raises an exception block_size (int or None) – (optional) The block size to use for read and write requests max_requests (int) – (optional) The maximum number of parallel read or write requests Returns An SFTPClientFile to use to access the file Raises ValueError if the mode is not valid SFTPError if the server returns an error
async truncate(path, size) Truncate a remote file to the specified size This method truncates a remote file to the specified size. If the path provided is a symbolic link, the target of the link will be truncated. Parameters path (PurePath, str, or bytes) – The path of the remote file to be truncated size (int) – The desired size of the file, in bytes Raises SFTPError if the server returns an error
async rename(oldpath, newpath) Rename a remote file, directory, or link This method renames a remote file, directory, or link. Note This requests the standard SFTP version of rename which will not overwrite the new path if it already exists. To request POSIX behavior where the new path is removed before the rename, use posix_rename(). Parameters oldpath (PurePath, str, or bytes) – The path of the remote file, directory, or link to rename newpath (PurePath, str, or bytes) – The new name for this file, directory, or link Raises SFTPError if the server returns an error
async posix_rename(oldpath, newpath) Rename a remote file, directory, or link with POSIX semantics This method renames a remote file, directory, or link, removing the prior instance of new path if it previously existed. This method may not be supported by all SFTP servers. Parameters oldpath (PurePath, str, or bytes) – The path of the remote file, directory, or link to rename newpath (PurePath, str, or bytes) – The new name for this file, directory, or link Raises SFTPError if the server doesn’t support this extension or returns an error
async remove(path) Remove a remote file This method removes a remote file or symbolic link. Parameters path (PurePath, str, or bytes) – The path of the remote file or link to remove Raises SFTPError if the server returns an error
async unlink(path) Remove a remote file (see remove())
async readlink(path) Return the target of a remote symbolic link This method returns the target of a symbolic link. Parameters path (PurePath, str, or bytes) – The path of the remote symbolic link to follow Returns The target path of the link as a str or bytes Raises SFTPError if the server returns an error
async symlink(oldpath, newpath) Create a remote symbolic link This method creates a symbolic link. The argument order here matches the standard Python os.symlink() call. The argument order sent on the wire is automatically adapted depending on the version information sent by the server, as a number of servers (OpenSSH in particular) did not follow the SFTP standard when implementing this call. Parameters oldpath (PurePath, str, or bytes) – The path the link should point to newpath (PurePath, str, or bytes) – The path of where to create the remote symbolic link Raises SFTPError if the server returns an error
async link(oldpath, newpath) Create a remote hard link This method creates a hard link to the remote file specified by oldpath at the location specified by newpath. This method may not be supported by all SFTP servers. Parameters oldpath (PurePath, str, or bytes) – The path of the remote file the hard link should point to newpath (PurePath, str, or bytes) – The path of where to create the remote hard link Raises SFTPError if the server doesn’t support this extension or returns an error
async realpath(path) Return the canonical version of a remote path This method returns a canonical version of the requested path. Parameters path (PurePath, str, or bytes) – (optional) The path of the remote directory to canonicalize Returns The canonical path as a str or bytes, matching the type used to pass in the path Raises SFTPError if the server returns an error

File attribute access methods
async stat(path) Get attributes of a remote file or directory, following symlinks This method queries the attributes of a remote file or directory. If the path provided is a symbolic link, the returned attributes will correspond to the target of the link. Parameters path (PurePath, str, or bytes) – The path of the remote file or directory to get attributes for Returns An SFTPAttrs containing the file attributes Raises SFTPError if the server returns an error
async lstat(path) Get attributes of a remote file, directory, or symlink This method queries the attributes of a remote file, directory, or symlink. Unlike stat(), this method returns the attributes of a symlink itself rather than the target of that link. Parameters path (PurePath, str, or bytes) – The path of the remote file, directory, or link to get attributes for Returns An SFTPAttrs containing the file attributes Raises SFTPError if the server returns an error
async setstat(path, attrs) Set attributes of a remote file or directory This method sets attributes of a remote file or directory. If the path provided is a symbolic link, the attributes will be set on the target of the link. A subset of the fields in attrs can be initialized and only those attributes will be changed. Parameters path (PurePath, str, or bytes) – The path of the remote file or directory to set attributes for attrs (SFTPAttrs) – File attributes to set Raises SFTPError if the server returns an error
async statvfs(path) Get attributes of a remote file system This method queries the attributes of the file system containing the specified path. Parameters path (PurePath, str, or bytes) – The path of the remote file system to get attributes for Returns An SFTPVFSAttrs containing the file system attributes Raises SFTPError if the server doesn’t support this extension or returns an error
async chown(path, uid, gid) Change the owner user and group id of a remote file or directory This method changes the user and group id of a remote file or directory. If the path provided is a symbolic link, the target of the link will be changed. Parameters path (PurePath, str, or bytes) – The path of the remote file to change uid (int) – The new user id to assign to the file gid (int) – The new group id to assign to the file Raises SFTPError if the server returns an error
async chmod(path, mode) Change the file permissions of a remote file or directory This method changes the permissions of a remote file or directory. If the path provided is a symbolic link, the target of the link will be changed. Parameters path (PurePath, str, or bytes) – The path of the remote file to change mode (int) – The new file permissions, expressed as an int Raises SFTPError if the server returns an error
async utime(path, times=None) Change the access and modify times of a remote file or directory This method changes the access and modify times of a remote file or directory. If times is not provided, the times will be changed to the current time. If the path provided is a symbolic link, the target of the link will be changed. Parameters path (PurePath, str, or bytes) – The path of the remote file to change times (tuple of two int or float values) – (optional) The new access and modify times, as seconds relative to the UNIX epoch Raises SFTPError if the server returns an error
async exists(path) Return if the remote path exists and isn’t a broken symbolic link Parameters path (PurePath, str, or bytes) – The remote path to check Raises SFTPError if the server returns an error
async lexists(path) Return if the remote path exists, without following symbolic links Parameters path (PurePath, str, or bytes) – The remote path to check Raises SFTPError if the server returns an error
async getatime(path) Return the last access time of a remote file or directory Parameters path (PurePath, str, or bytes) – The remote path to check Raises SFTPError if the server returns an error
async getmtime(path) Return the last modification time of a remote file or directory Parameters path (PurePath, str, or bytes) – The remote path to check Raises SFTPError if the server returns an error
async getsize(path) Return the size of a remote file or directory Parameters path (PurePath, str, or bytes) – The remote path to check Raises SFTPError if the server returns an error
async isdir(path) Return if the remote path refers to a directory Parameters path (PurePath, str, or bytes) – The remote path to check Raises SFTPError if the server returns an error
async isfile(path) Return if the remote path refers to a regular file Parameters path (PurePath, str, or bytes) – The remote path to check Raises SFTPError if the server returns an error
async islink(path) Return if the remote path refers to a symbolic link Parameters path (PurePath, str, or bytes) – The remote path to check Raises SFTPError if the server returns an error

Directory access methods
async chdir(path) Change the current remote working directory Parameters path (PurePath, str, or bytes) – The path to set as the new remote working directory Raises SFTPError if the server returns an error
async getcwd() Return the current remote working directory Returns The current remote working directory, decoded using the specified path encoding Raises SFTPError if the server returns an error
async mkdir(path, attrs=SFTPAttrs()) Create a remote directory with the specified attributes This method creates a new remote directory at the specified path with the requested attributes. Parameters path (PurePath, str, or bytes) – The path of where the new remote directory should be created attrs (SFTPAttrs) – (optional) The file attributes to use when creating the directory Raises SFTPError if the server returns an error
async rmdir(path) Remove a remote directory This method removes a remote directory. The directory must be empty for the removal to succeed. Parameters path (PurePath, str, or bytes) – The path of the remote directory to remove Raises SFTPError if the server returns an error
async readdir(path='.') Read the contents of a remote directory This method reads the contents of a directory, returning the names and attributes of what is contained there. If no path is provided, it defaults to the current remote working directory. Parameters path (PurePath, str, or bytes) – (optional) The path of the remote directory to read Returns A list of SFTPName entries, with path names matching the type used to pass in the path Raises SFTPError if the server returns an error
async listdir(path='.') Read the names of the files in a remote directory This method reads the names of files and subdirectories in a remote directory. If no path is provided, it defaults to the current remote working directory. Parameters path (PurePath, str, or bytes) – (optional) The path of the remote directory to read Returns A list of file/subdirectory names, matching the type used to pass in the path Raises SFTPError if the server returns an error
async glob(patterns, error_handler=None) Match remote files against glob patterns This method matches remote files against one or more glob patterns. Either a single pattern or a sequence of patterns can be provided to match against. Supported wildcard characters include ‘*’, ‘?’, and character ranges in square brackets. In addition, ‘**’ can be used to trigger a recursive directory search at that point in the pattern, and a trailing slash can be used to request that only directories get returned. If error_handler is specified and an error occurs during the match, this handler will be called with the exception instead of it being raised. This is intended to primarily be used when multiple patterns are provided to allow error information to be collected without aborting the match against the remaining patterns. The error handler can raise an exception if it wants to completely abort the match. Otherwise, after an error, the match will continue starting with the next pattern. An error will be raised if any of the patterns completely fail to match, and this can either stop the match against the remaining patterns or be handled by the error_handler just like other errors. Parameters patterns (PurePath, str, or bytes, or a sequence of these) – Glob patterns to try and match remote files against error_handler (callable) – (optional) The function to call when an error occurs Raises SFTPError if the server returns an error or no match is found

Cleanup methods
exit() Exit the SFTP client session This method exits the SFTP client session, closing the corresponding channel opened on the server.
async wait_closed() Wait for this SFTP client session to close

SFTPClientFile

class asyncssh.SFTPClientFile

SFTP client remote file object

This class represents an open file on a remote SFTP server. It is opened with the open() method on the SFTPClient class and provides methods to read and write data and get and set attributes on the open file.

async read(size=-1, offset=None) Read data from the remote file This method reads and returns up to size bytes of data from the remote file. If size is negative, all data up to the end of the file is returned. If offset is specified, the read will be performed starting at that offset rather than the current file position. This argument should be provided if you want to issue parallel reads on the same file, since the file position is not predictable in that case. Data will be returned as a string if an encoding was set when the file was opened. Otherwise, data is returned as bytes. An empty str or bytes object is returned when at EOF. Parameters size (int) – The number of bytes to read offset (int) – (optional) The offset from the beginning of the file to begin reading Returns data read from the file, as a str or bytes Raises ValueError if the file has been closed UnicodeDecodeError if the data can’t be decoded using the requested encoding SFTPError if the server returns an error
async write(data, offset=None) Write data to the remote file This method writes the specified data at the current position in the remote file. Parameters data (str or bytes) – The data to write to the file offset (int) – (optional) The offset from the beginning of the file to begin writing If offset is specified, the write will be performed starting at that offset rather than the current file position. This argument should be provided if you want to issue parallel writes on the same file, since the file position is not predictable in that case. Returns number of bytes written Raises ValueError if the file has been closed UnicodeEncodeError if the data can’t be encoded using the requested encoding SFTPError if the server returns an error
async seek(offset, from_what=SEEK_SET) Seek to a new position in the remote file This method changes the position in the remote file. The offset passed in is treated as relative to the beginning of the file if from_what is set to SEEK_SET (the default), relative to the current file position if it is set to SEEK_CUR, or relative to the end of the file if it is set to SEEK_END. Parameters offset (int) – The amount to seek from_what (SEEK_SET, SEEK_CUR, or SEEK_END) – (optional) The reference point to use Returns The new byte offset from the beginning of the file
async tell() Return the current position in the remote file This method returns the current position in the remote file. Returns The current byte offset from the beginning of the file
async stat() Return file attributes of the remote file This method queries file attributes of the currently open file. Returns An SFTPAttrs containing the file attributes Raises SFTPError if the server returns an error
async setstat(attrs) Set attributes of the remote file This method sets file attributes of the currently open file. Parameters attrs (SFTPAttrs) – File attributes to set on the file Raises SFTPError if the server returns an error
async statvfs() Return file system attributes of the remote file This method queries attributes of the file system containing the currently open file. Returns An SFTPVFSAttrs containing the file system attributes Raises SFTPError if the server doesn’t support this extension or returns an error
async truncate(size=None) Truncate the remote file to the specified size This method changes the remote file’s size to the specified value. If a size is not provided, the current file position is used. Parameters size (int) – (optional) The desired size of the file, in bytes Raises SFTPError if the server returns an error
async chown(uid, gid) Change the owner user and group id of the remote file This method changes the user and group id of the currently open file. Parameters uid (int) – The new user id to assign to the file gid (int) – The new group id to assign to the file Raises SFTPError if the server returns an error
async chmod(mode) Change the file permissions of the remote file This method changes the permissions of the currently open file. Parameters mode (int) – The new file permissions, expressed as an int Raises SFTPError if the server returns an error
async utime(times=None) Change the access and modify times of the remote file This method changes the access and modify times of the currently open file. If times is not provided, the times will be changed to the current time. Parameters times (tuple of two int or float values) – (optional) The new access and modify times, as seconds relative to the UNIX epoch Raises SFTPError if the server returns an error
async fsync() Force the remote file data to be written to disk
async close() Close the remote file

SFTPServer

class asyncssh.SFTPServer(chan, chroot=None)

SFTP server

Applications should subclass this when implementing an SFTP server. The methods listed below should be implemented to provide the desired application behavior.

Note

Any method can optionally be defined as a coroutine if that method needs to perform blocking opertions to determine its result.

The chan object provided here is the SSHServerChannel instance this SFTP server is associated with. It can be queried to determine which user the client authenticated as, environment variables set on the channel when it was opened, and key and certificate options or permissions associated with this session.

Note

In AsyncSSH 1.x, this first argument was an SSHServerConnection, not an SSHServerChannel. When moving to AsyncSSH 2.x, subclasses of SFTPServer which implement an __init__ method will need to be updated to account for this change, and pass this through to the parent.

If the chroot argument is specified when this object is created, the default map_path() and reverse_map_path() methods will enforce a virtual root directory starting in that location, limiting access to only files within that directory tree. This will also affect path names returned by the realpath() and readlink() methods.

SFTP server attributes
channel The channel associated with this SFTP server session
connection The channel associated with this SFTP server session
env The environment associated with this SFTP server session This method returns the environment set by the client when this SFTP session was opened. Returns A dictionary containing the environment variables set by the client
logger A logger associated with this SFTP server

Path remapping and display methods
format_user(uid) Return the user name associated with a uid This method returns a user name string to insert into the longname field of an SFTPName object. By default, it calls the Python pwd.getpwuid() function if it is available, or returns the numeric uid as a string if not. If there is no uid, it returns an empty string. Parameters uid (int or None) – The uid value to look up Returns The formatted user name string
format_group(gid) Return the group name associated with a gid This method returns a group name string to insert into the longname field of an SFTPName object. By default, it calls the Python grp.getgrgid() function if it is available, or returns the numeric gid as a string if not. If there is no gid, it returns an empty string. Parameters gid (int or None) – The gid value to look up Returns The formatted group name string
format_longname(name) Format the long name associated with an SFTP name This method fills in the longname field of a SFTPName object. By default, it generates something similar to UNIX “ls -l” output. The filename and attrs fields of the SFTPName should already be filled in before this method is called. Parameters name (SFTPName) – The SFTPName instance to format the long name for
map_path(path) Map the path requested by the client to a local path This method can be overridden to provide a custom mapping from path names requested by the client to paths in the local filesystem. By default, it will enforce a virtual “chroot” if one was specified when this server was created. Otherwise, path names are left unchanged, with relative paths being interpreted based on the working directory of the currently running process. Parameters path (bytes) – The path name to map Returns bytes containing the local path name to operate on
reverse_map_path(path) Reverse map a local path into the path reported to the client This method can be overridden to provide a custom reverse mapping for the mapping provided by map_path(). By default, it hides the portion of the local path associated with the virtual “chroot” if one was specified. Parameters path (bytes) – The local path name to reverse map Returns bytes containing the path name to report to the client

File access methods
open(path, pflags, attrs) Open a file to serve to a remote client This method returns a file object which can be used to read and write data and get and set file attributes. The possible open mode flags and their meanings are: Mode Description FXF_READ Open the file for reading. If neither FXF_READ nor FXF_WRITE are set, this is the default. FXF_WRITE Open the file for writing. If both this and FXF_READ are set, open the file for both reading and writing. FXF_APPEND Force writes to append data to the end of the file regardless of seek position. FXF_CREAT Create the file if it doesn’t exist. Without this, attempts to open a non-existent file will fail. FXF_TRUNC Truncate the file to zero length if it already exists. FXF_EXCL Return an error when trying to open a file which already exists. The attrs argument is used to set initial attributes of the file if it needs to be created. Otherwise, this argument is ignored. Parameters path (bytes) – The name of the file to open pflags (int) – The access mode to use for the file (see above) attrs (SFTPAttrs) – File attributes to use if the file needs to be created Returns A file object to use to access the file Raises SFTPError to return an error to the client
close(file_obj) Close an open file or directory Parameters file_obj (file) – The file or directory object to close Raises SFTPError to return an error to the client
read(file_obj, offset, size) Read data from an open file Parameters file_obj (file) – The file to read from offset (int) – The offset from the beginning of the file to begin reading size (int) – The number of bytes to read Returns bytes read from the file Raises SFTPError to return an error to the client
write(file_obj, offset, data) Write data to an open file Parameters file_obj (file) – The file to write to offset (int) – The offset from the beginning of the file to begin writing data (bytes) – The data to write to the file Returns number of bytes written Raises SFTPError to return an error to the client
rename(oldpath, newpath) Rename a file, directory, or link This method renames a file, directory, or link. Note This is a request for the standard SFTP version of rename which will not overwrite the new path if it already exists. The posix_rename() method will be called if the client requests the POSIX behavior where an existing instance of the new path is removed before the rename. Parameters oldpath (bytes) – The path of the file, directory, or link to rename newpath (bytes) – The new name for this file, directory, or link Raises SFTPError to return an error to the client
posix_rename(oldpath, newpath) Rename a file, directory, or link with POSIX semantics This method renames a file, directory, or link, removing the prior instance of new path if it previously existed. Parameters oldpath (bytes) – The path of the file, directory, or link to rename newpath (bytes) – The new name for this file, directory, or link Raises SFTPError to return an error to the client
remove(path) Remove a file or symbolic link Parameters path (bytes) – The path of the file or link to remove Raises SFTPError to return an error to the client
readlink(path) Return the target of a symbolic link Parameters path (bytes) – The path of the symbolic link to follow Returns bytes containing the target path of the link Raises SFTPError to return an error to the client
symlink(oldpath, newpath) Create a symbolic link Parameters oldpath (bytes) – The path the link should point to newpath (bytes) – The path of where to create the symbolic link Raises SFTPError to return an error to the client
link(oldpath, newpath) Create a hard link Parameters oldpath (bytes) – The path of the file the hard link should point to newpath (bytes) – The path of where to create the hard link Raises SFTPError to return an error to the client
realpath(path) Return the canonical version of a path Parameters path (bytes) – The path of the directory to canonicalize Returns bytes containing the canonical path Raises SFTPError to return an error to the client

File attribute access methods
stat(path) Get attributes of a file or directory, following symlinks This method queries the attributes of a file or directory. If the path provided is a symbolic link, the returned attributes should correspond to the target of the link. Parameters path (bytes) – The path of the remote file or directory to get attributes for Returns An SFTPAttrs or an os.stat_result containing the file attributes Raises SFTPError to return an error to the client
lstat(path) Get attributes of a file, directory, or symlink This method queries the attributes of a file, directory, or symlink. Unlike stat(), this method should return the attributes of a symlink itself rather than the target of that link. Parameters path (bytes) – The path of the file, directory, or link to get attributes for Returns An SFTPAttrs or an os.stat_result containing the file attributes Raises SFTPError to return an error to the client
fstat(file_obj) Get attributes of an open file Parameters file_obj (file) – The file to get attributes for Returns An SFTPAttrs or an os.stat_result containing the file attributes Raises SFTPError to return an error to the client
setstat(path, attrs) Set attributes of a file or directory This method sets attributes of a file or directory. If the path provided is a symbolic link, the attributes should be set on the target of the link. A subset of the fields in attrs can be initialized and only those attributes should be changed. Parameters path (bytes) – The path of the remote file or directory to set attributes for attrs (SFTPAttrs) – File attributes to set Raises SFTPError to return an error to the client
fsetstat(file_obj, attrs) Set attributes of an open file Parameters file_obj (file) – The file to set attributes for attrs (SFTPAttrs) – File attributes to set on the file Raises SFTPError to return an error to the client
statvfs(path) Get attributes of the file system containing a file Parameters path (bytes) – The path of the file system to get attributes for Returns An SFTPVFSAttrs or an os.statvfs_result containing the file system attributes Raises SFTPError to return an error to the client
fstatvfs(file_obj) Return attributes of the file system containing an open file Parameters file_obj (file) – The open file to get file system attributes for Returns An SFTPVFSAttrs or an os.statvfs_result containing the file system attributes Raises SFTPError to return an error to the client

Directory access methods
listdir(path) List the contents of a directory Parameters path (bytes) – The path of the directory to open Returns A list of names of files in the directory Raises SFTPError to return an error to the client
mkdir(path, attrs) Create a directory with the specified attributes Parameters path (bytes) – The path of where the new directory should be created attrs (SFTPAttrs) – The file attributes to use when creating the directory Raises SFTPError to return an error to the client
rmdir(path) Remove a directory Parameters path (bytes) – The path of the directory to remove Raises SFTPError to return an error to the client

Cleanup methods
exit() Shut down this SFTP server

SFTPAttrs

class asyncssh.SFTPAttrs

SFTP file attributes

SFTPAttrs is a simple record class with the following fields:

Field	Description	Type
size	File size in bytes	uint64
uid	User id of file owner	uint32
gid	Group id of file owner	uint32
permissions	Bit mask of POSIX file permissions,	uint32
atime	Last access time, UNIX epoch seconds	uint32
mtime	Last modification time, UNIX epoch seconds	uint32

In addition to the above, an nlink field is provided which stores the number of links to this file, but it is not encoded in the SFTP protocol. It’s included here only so that it can be used to create the default longname string in SFTPName objects.

Extended attributes can also be added via a field named extended which is a list of string name/value pairs.

When setting attributes using an SFTPAttrs, only fields which have been initialized will be changed on the selected file.

SFTPVFSAttrs

class asyncssh.SFTPVFSAttrs

SFTP file system attributes

SFTPVFSAttrs is a simple record class with the following fields:

Field	Description	Type
bsize	File system block size (I/O size)	uint64
frsize	Fundamental block size (allocation size)	uint64
blocks	Total data blocks (in frsize units)	uint64
bfree	Free data blocks	uint64
bavail	Available data blocks (for non-root)	uint64
files	Total file inodes	uint64
ffree	Free file inodes	uint64
favail	Available file inodes (for non-root)	uint64
fsid	File system id	uint64
flags	File system flags (read-only, no-setuid)	uint64
namemax	Maximum filename length	uint64

SFTPName

class asyncssh.SFTPName

SFTP file name and attributes

SFTPName is a simple record class with the following fields:

Field	Description	Type
filename	Filename	str or bytes
longname	Expanded form of filename & attrs	str or bytes
attrs	File attributes	SFTPAttrs

A list of these is returned by readdir() in SFTPClient when retrieving the contents of a directory.

Public Key Support

AsyncSSH has extensive public key and certificate support.

Supported public key types include DSA, RSA, and ECDSA. In addition, Ed25519 and Ed448 keys are supported if OpenSSL 1.1.1b or later is installed. Alternately, Ed25519 support is available when the libnacl package and libsodium library are installed.

Supported certificate types include OpenSSH version 01 certificates for DSA, RSA, ECDSA, Ed25519, and Ed448 keys and X.509 certificates for DSA, RSA, and ECDSA keys.

Support is also available for the certificate critical options of force-command and source-address and the extensions permit-X11-forwarding, permit-agent-forwarding, permit-port-forwarding, and permit-pty in OpenSSH certificates.

Several public key and certificate formats are supported including PKCS#1 and PKCS#8 DER and PEM, OpenSSH, RFC4716, and X.509 DER and PEM formats.

PEM and PKCS#8 password-based encryption of private keys is supported, as is OpenSSH private key encryption when the bcrypt package is installed.

Specifying private keys

Private keys may be passed into AsyncSSH in a variety of forms. The simplest option is to pass the name of a file to read one or more private keys from.

An alternate form involves passing in a list of values which can be either a reference to a private key or a tuple containing a reference to a private key and a reference to a corresponding certificate or certificate chain.

Key references can either be the name of a file to load a key from, a byte string to import as a key, or an already loaded SSHKey private key. See the function import_private_key() for the list of supported private key formats.

Certificate references can be the name of a file to load a certificate from, a byte string to import as a certificate, an already loaded SSHCertificate, or None if no certificate should be associated with the key.

Whenever a filename is provided to read the private key from, an attempt is made to load a corresponding certificate or certificate chain from a file constructed by appending ‘-cert.pub’ to the end of the name. X.509 certificates may also be provided in the same file as the private key, when using DER or PEM format.

When using X.509 certificates, a list of certificates can also be provided. These certificates should form a trust chain from a user or host certificate up to some self-signed root certificate authority which is trusted by the remote system.

New private keys can be generated using the generate_private_key() function. The resulting SSHKey objects have methods which can then be used to export the generated keys in several formats for consumption by other tools, as well as methods for generating new OpenSSH or X.509 certificates.

Specifying public keys

Public keys may be passed into AsyncSSH in a variety of forms. The simplest option is to pass the name of a file to read one or more public keys from.

An alternate form involves passing in a list of values each of which can be either the name of a file to load a key from, a byte string to import it from, or an already loaded SSHKey public key. See the function import_public_key() for the list of supported public key formats.

Specifying certificates

Certificates may be passed into AsyncSSH in a variety of forms. The simplest option is to pass the name of a file to read one or more certificates from.

An alternate form involves passing in a list of values each of which can be either the name of a file to load a certificate from, a byte string to import it from, or an already loaded SSHCertificate object. See the function import_certificate() for the list of supported certificate formats.

Specifying X.509 subject names

X.509 certificate subject names may be specified in place of public keys or certificates in authorized_keys and known_hosts files, allowing any X.509 certificate which matches that subject name to be considered a known host or authorized key. The syntax supported for this is compatible with PKIX-SSH, which adds X.509 certificate support to OpenSSH.

To specify a subject name pattern instead of a specific certificate, base64-encoded certificate data should be replaced with the string ‘Subject:’ followed by a a comma-separated list of X.509 relative distinguished name components.

AsyncSSH extends the PKIX-SSH syntax to also support matching on a prefix of a subject name. To indicate this, a partial subject name can be specified which ends in ‘,*’. Any subject which matches the relative distinguished names listed before the “,*” will be treated as a match, even if the certificate provided has additional relative distinguished names following what was matched.

Specifying X.509 purposes

When performing X.509 certificate authentication, AsyncSSH can be passed in an allowed set of ExtendedKeyUsage purposes. Purposes are matched in X.509 certificates as OID values, but AsyncSSH also allows the following well-known purpose values to be specified by name:

Name	OID
serverAuth	1.3.6.1.5.5.7.3.1
clientAuth	1.3.6.1.5.5.7.3.2
secureShellClient	1.3.6.1.5.5.7.3.20
secureShellServer	1.3.6.1.5.5.7.3.21

Values not in the list above can be specified directly by OID as a dotted numeric string value. Either a single value or a list of values can be provided.

The check succeeds if any of the specified values are present in the certificate’s ExtendedKeyUsage. It will also succeed if the certificate does not contain an ExtendedKeyUsage or if the ExtendedKeyUsage contains the OID 2.5.29.37.0, which indicates the certificate can be used for any purpose.

This check defaults to requiring a purpose of ‘secureShellCient’ for client certificates and ‘secureShellServer’ for server certificates and should not normally need to be changed. However, certificates which contain other purposes can be supported by providing alternate values to match against, or by passing in the purpose ‘any’ to disable this checking.

Specifying time values

When generating certificates, an optional validity interval can be specified using the valid_after and valid_before parameters to the generate_user_certificate() and generate_host_certificate() methods. These values can be specified in any of the following ways:

• An int or float UNIX epoch time, such as what is returned by time.time().

• A datetime.datetime value.

• A string value of now to request the current time.

• A string value in the form YYYYMMDD to specify an absolute date.

• A string value in the form YYYYMMDDHHMMSS to specify an absolute date and time.

• A relative time made up of a mix of positive or negative numbers and the letters ‘w’, ‘d’, ‘h’, ‘m’, and ‘s’, representing an offset from the current time in weeks, days, hours, minutes, or seconds, respectively. Multiple of these values can be included. For instance, ‘+1w2d3h’ means 1 week, 2 days, and 3 hours in the future.

SSHKey

class asyncssh.SSHKey

Parent class which holds an asymmetric encryption key

get_algorithm() Return the algorithm associated with this key
get_comment_bytes() Return the comment associated with this key as a byte string Returns bytes or None
get_comment(encoding='utf-8', errors='strict') Return the comment associated with this key as a Unicode string Parameters encoding (str) – The encoding to use to decode the comment as a Unicode string, defaulting to UTF-8 errors (str) – The error handling scheme to use for Unicode decode errors Returns str or None Raises UnicodeDecodeError if the comment cannot be decoded using the specified encoding
set_comment(comment, encoding='utf-8', errors='strict') Set the comment associated with this key Parameters comment (str, bytes, or None) – The new comment to associate with this key encoding (str) – The Unicode encoding to use to encode the comment, defaulting to UTF-8 errors (str) – The error handling scheme to use for Unicode encode errors Raises UnicodeEncodeError if the comment cannot be encoded using the specified encoding
get_fingerprint(hash_name='sha256') Get the fingerprint of this key Available hashes include: md5, sha1, sha256, sha384, sha512 Parameters hash_name (str) – (optional) The hash algorithm to use to construct the fingerprint. Returns str Raises ValueError if the hash name is invalid
convert_to_public() Return public key corresponding to this key This method converts an SSHKey object which contains a private key into one which contains only the corresponding public key. If it is called on something which is already a public key, it has no effect.
generate_user_certificate(user_key, key_id, version=1, serial=0, principals=(), valid_after=0, valid_before=18446744073709551615, force_command=None, source_address=None, permit_x11_forwarding=True, permit_agent_forwarding=True, permit_port_forwarding=True, permit_pty=True, permit_user_rc=True, touch_required=True, comment=()) Generate a new SSH user certificate This method returns an SSH user certifcate with the requested attributes signed by this private key. Parameters user_key (SSHKey) – The user’s public key. key_id (str) – The key identifier associated with this certificate. version (int) – (optional) The version of certificate to create, defaulting to 1. serial (int) – (optional) The serial number of the certificate, defaulting to 0. principals (list of str) – (optional) The user names this certificate is valid for. By default, it can be used with any user name. valid_after – (optional) The earliest time the certificate is valid for, defaulting to no restriction on when the certificate starts being valid. See Specifying time values for allowed time specifications. valid_before – (optional) The latest time the certificate is valid for, defaulting to no restriction on when the certificate stops being valid. See Specifying time values for allowed time specifications. force_command (str or None) – (optional) The command (if any) to force a session to run when this certificate is used. source_address (list of ip_address and ip_network values) – (optional) A list of source addresses and networks for which the certificate is valid, defaulting to all addresses. permit_x11_forwarding (bool) – (optional) Whether or not to allow this user to use X11 forwarding, defaulting to True. permit_agent_forwarding (bool) – (optional) Whether or not to allow this user to use agent forwarding, defaulting to True. permit_port_forwarding (bool) – (optional) Whether or not to allow this user to use port forwarding, defaulting to True. permit_pty (bool) – (optional) Whether or not to allow this user to allocate a pseudo-terminal, defaulting to True. permit_user_rc (bool) – (optional) Whether or not to run the user rc file when this certificate is used, defaulting to True. touch_required (bool) – (optional) Whether or not to require the user to touch the security key when authenticating with it, defaulting to True. comment (str, bytes, or None) – The comment to associate with this certificate. By default, the comment will be set to the comment currently set on user_key. Returns SSHCertificate Raises ValueError if the validity times are invalid KeyGenerationError if the requested certificate parameters are unsupported
generate_host_certificate(host_key, key_id, version=1, serial=0, principals=(), valid_after=0, valid_before=18446744073709551615, comment=()) Generate a new SSH host certificate This method returns an SSH host certifcate with the requested attributes signed by this private key. Parameters host_key (SSHKey) – The host’s public key. key_id (str) – The key identifier associated with this certificate. version (int) – (optional) The version of certificate to create, defaulting to 1. serial (int) – (optional) The serial number of the certificate, defaulting to 0. principals (list of str) – (optional) The host names this certificate is valid for. By default, it can be used with any host name. valid_after – (optional) The earliest time the certificate is valid for, defaulting to no restriction on when the certificate starts being valid. See Specifying time values for allowed time specifications. valid_before – (optional) The latest time the certificate is valid for, defaulting to no restriction on when the certificate stops being valid. See Specifying time values for allowed time specifications. comment (str, bytes, or None) – The comment to associate with this certificate. By default, the comment will be set to the comment currently set on host_key. Returns SSHCertificate Raises ValueError if the validity times are invalid KeyGenerationError if the requested certificate parameters are unsupported
generate_x509_user_certificate(user_key, subject, issuer=None, serial=None, principals=(), valid_after=0, valid_before=18446744073709551615, purposes='secureShellClient', hash_alg='sha256', comment=()) Generate a new X.509 user certificate This method returns an X.509 user certifcate with the requested attributes signed by this private key. Parameters user_key (SSHKey) – The user’s public key. subject (str) – The subject name in the certificate, expresed as a comma-separated list of X.509 name=value pairs. issuer (str) – (optional) The issuer name in the certificate, expresed as a comma-separated list of X.509 name=value pairs. If not specified, the subject name will be used, creating a self-signed certificate. serial (int) – (optional) The serial number of the certificate, defaulting to a random 64-bit value. principals (list of str) – (optional) The user names this certificate is valid for. By default, it can be used with any user name. valid_after – (optional) The earliest time the certificate is valid for, defaulting to no restriction on when the certificate starts being valid. See Specifying time values for allowed time specifications. valid_before – (optional) The latest time the certificate is valid for, defaulting to no restriction on when the certificate stops being valid. See Specifying time values for allowed time specifications. purposes (list of str or None) – (optional) The allowed purposes for this certificate or None to not restrict the certificate’s purpose, defaulting to ‘secureShellClient’ hash_alg (str) – (optional) The hash algorithm to use when signing the new certificate, defaulting to SHA256. comment (str, bytes, or None) – (optional) The comment to associate with this certificate. By default, the comment will be set to the comment currently set on user_key. Returns SSHCertificate Raises ValueError if the validity times are invalid KeyGenerationError if the requested certificate parameters are unsupported
generate_x509_host_certificate(host_key, subject, issuer=None, serial=None, principals=(), valid_after=0, valid_before=18446744073709551615, purposes='secureShellServer', hash_alg='sha256', comment=()) Generate a new X.509 host certificate This method returns a X.509 host certifcate with the requested attributes signed by this private key. Parameters host_key (SSHKey) – The host’s public key. subject (str) – The subject name in the certificate, expresed as a comma-separated list of X.509 name=value pairs. issuer (str) – (optional) The issuer name in the certificate, expresed as a comma-separated list of X.509 name=value pairs. If not specified, the subject name will be used, creating a self-signed certificate. serial (int) – (optional) The serial number of the certificate, defaulting to a random 64-bit value. principals (list of str) – (optional) The host names this certificate is valid for. By default, it can be used with any host name. valid_after – (optional) The earliest time the certificate is valid for, defaulting to no restriction on when the certificate starts being valid. See Specifying time values for allowed time specifications. valid_before – (optional) The latest time the certificate is valid for, defaulting to no restriction on when the certificate stops being valid. See Specifying time values for allowed time specifications. purposes (list of str or None) – (optional) The allowed purposes for this certificate or None to not restrict the certificate’s purpose, defaulting to ‘secureShellServer’ hash_alg (str) – (optional) The hash algorithm to use when signing the new certificate, defaulting to SHA256. comment (str, bytes, or None) – (optional) The comment to associate with this certificate. By default, the comment will be set to the comment currently set on host_key. Returns SSHCertificate Raises ValueError if the validity times are invalid KeyGenerationError if the requested certificate parameters are unsupported
generate_x509_ca_certificate(ca_key, subject, issuer=None, serial=None, valid_after=0, valid_before=18446744073709551615, ca_path_len=None, hash_alg='sha256', comment=()) Generate a new X.509 CA certificate This method returns a X.509 CA certifcate with the requested attributes signed by this private key. Parameters ca_key (SSHKey) – The new CA’s public key. subject (str) – The subject name in the certificate, expresed as a comma-separated list of X.509 name=value pairs. issuer (str) – (optional) The issuer name in the certificate, expresed as a comma-separated list of X.509 name=value pairs. If not specified, the subject name will be used, creating a self-signed certificate. serial (int) – (optional) The serial number of the certificate, defaulting to a random 64-bit value. valid_after – (optional) The earliest time the certificate is valid for, defaulting to no restriction on when the certificate starts being valid. See Specifying time values for allowed time specifications. valid_before – (optional) The latest time the certificate is valid for, defaulting to no restriction on when the certificate stops being valid. See Specifying time values for allowed time specifications. ca_path_len (int or None) – (optional) The maximum number of levels of intermediate CAs allowed below this new CA or None to not enforce a limit, defaulting to no limit. hash_alg (str) – (optional) The hash algorithm to use when signing the new certificate, defaulting to SHA256. comment (str, bytes, or None) – (optional) The comment to associate with this certificate. By default, the comment will be set to the comment currently set on ca_key. Returns SSHCertificate Raises ValueError if the validity times are invalid KeyGenerationError if the requested certificate parameters are unsupported
export_private_key(format_name='openssh', passphrase=None, cipher_name='aes256-cbc', hash_name='sha256', pbe_version=2, rounds=128, ignore_few_rounds=False) Export a private key in the requested format This method returns this object’s private key encoded in the requested format. If a passphrase is specified, the key will be exported in encrypted form. Available formats include: pkcs1-der, pkcs1-pem, pkcs8-der, pkcs8-pem, openssh By default, openssh format will be used. Encryption is supported in pkcs1-pem, pkcs8-der, pkcs8-pem, and openssh formats. For pkcs1-pem, only the cipher can be specified. For pkcs8-der and pkcs-8, cipher, hash and PBE version can be specified. For openssh, cipher and rounds can be specified. Available ciphers for pkcs1-pem are: aes128-cbc, aes192-cbc, aes256-cbc, des-cbc, des3-cbc Available ciphers for pkcs8-der and pkcs8-pem are: aes128-cbc, aes192-cbc, aes256-cbc, blowfish-cbc, cast128-cbc, des-cbc, des2-cbc, des3-cbc, rc4-40, rc4-128 Available ciphers for openssh format include the following encryption algorithms. Available hashes include: md5, sha1, sha256, sha384, sha512 Available PBE versions include 1 for PBES1 and 2 for PBES2. Not all combinations of cipher, hash, and version are supported. The default cipher is aes256. In the pkcs8 formats, the default hash is sha256 and default version is PBES2. In openssh format, the default number of rounds is 128. Note The openssh format uses bcrypt for encryption, but unlike the traditional bcrypt cost factor used in password hashing which scales logarithmically, the encryption strength here scales linearly with the rounds value. Since the cipher is rekeyed 64 times per round, the default rounds value of 128 corresponds to 8192 total iterations, which is the equivalent of a bcrypt cost factor of 13. Parameters format_name (str) – (optional) The format to export the key in. passphrase (str or bytes) – (optional) A passphrase to encrypt the private key with. cipher_name (str) – (optional) The cipher to use for private key encryption. hash_name (str) – (optional) The hash to use for private key encryption. pbe_version (int) – (optional) The PBE version to use for private key encryption. rounds (int) – (optional) The number of KDF rounds to apply to the passphrase. Returns bytes representing the exported private key
export_public_key(format_name='openssh') Export a public key in the requested format This method returns this object’s public key encoded in the requested format. Available formats include: pkcs1-der, pkcs1-pem, pkcs8-der, pkcs8-pem, openssh, rfc4716 By default, openssh format will be used. Parameters format_name (str) – (optional) The format to export the key in. Returns bytes representing the exported public key
write_private_key(filename, *args, **kwargs) Write a private key to a file in the requested format This method is a simple wrapper around export_private_key() which writes the exported key data to a file. Parameters filename (PurePath or str) – The filename to write the private key to. *args,**kwargs – Additional arguments to pass through to export_private_key().
write_public_key(filename, *args, **kwargs) Write a public key to a file in the requested format This method is a simple wrapper around export_public_key() which writes the exported key data to a file. Parameters filename (PurePath or str) – The filename to write the public key to. *args,**kwargs – Additional arguments to pass through to export_public_key().
append_private_key(filename, *args, **kwargs) Append a private key to a file in the requested format This method is a simple wrapper around export_private_key() which appends the exported key data to an existing file. Parameters filename (PurePath or str) – The filename to append the private key to. *args,**kwargs – Additional arguments to pass through to export_private_key().
append_public_key(filename, *args, **kwargs) Append a public key to a file in the requested format This method is a simple wrapper around export_public_key() which appends the exported key data to an existing file. Parameters filename (PurePath or str) – The filename to append the public key to. *args,**kwargs – Additional arguments to pass through to export_public_key().

SSHKeyPair

class asyncssh.SSHKeyPair

Parent class which represents an asymmetric key pair

This is an abstract class which provides a method to sign data with a private key and members to access the corresponding algorithm and public key or certificate information needed to identify what key was used for signing.

get_key_type() Return what type of key pair this is This method returns ‘local’ for locally loaded keys, and ‘agent’ for keys managed by an SSH agent.
get_algorithm() Return the algorithm associated with this key pair
set_certificate(cert) Set certificate to use with this key This method allows you to change the certificate associated with a key pair. This is particularly useful for specifying certificates to use with smart card keys as there’s no way to load an SSH certificate onto the smart card. Parameters cert (SSHCertificate) – The new certificate to associate with this key Raises ValueError if the certificate doesn’t match the key
get_comment_bytes() Return the comment associated with this key pair as a byte string Returns bytes or None
get_comment(encoding='utf-8', errors='strict') Return the comment associated with this key pair as a Unicode string Parameters encoding (str) – The encoding to use to decode the comment as a Unicode string, defaulting to UTF-8 errors (str) – The error handling scheme to use for Unicode decode errors Returns str or None Raises UnicodeDecodeError if the comment cannot be decoded using the specified encoding
set_comment(comment, encoding='utf-8', errors='strict') Set the comment associated with this key pair Parameters comment (str, bytes, or None) – The new comment to associate with this key encoding (str) – The Unicode encoding to use to encode the comment, defaulting to UTF-8 errors (str) – The error handling scheme to use for Unicode encode errors Raises UnicodeEncodeError if the comment cannot be encoded using the specified encoding

SSHCertificate

class asyncssh.SSHCertificate

Parent class which holds an SSH certificate

get_algorithm() Return the algorithm associated with this certificate
get_comment_bytes() Return the comment associated with this certificate as a byte string Returns bytes or None
get_comment(encoding='utf-8', errors='strict') Return the comment associated with this certificate as a Unicode string Parameters encoding (str) – The encoding to use to decode the comment as a Unicode string, defaulting to UTF-8 errors (str) – The error handling scheme to use for Unicode decode errors Returns str or None Raises UnicodeDecodeError if the comment cannot be decoded using the specified encoding
set_comment(comment, encoding='utf-8', errors='strict') Set the comment associated with this certificate Parameters comment (str, bytes, or None) – The new comment to associate with this key encoding (str) – The Unicode encoding to use to encode the comment, defaulting to UTF-8 errors (str) – The error handling scheme to use for Unicode encode errors Raises UnicodeEncodeError if the comment cannot be encoded using the specified encoding
export_certificate(format_name='openssh') Export a certificate in the requested format This function returns this certificate encoded in the requested format. Available formats include: der, pem, openssh, rfc4716 By default, OpenSSH format will be used. Parameters format_name (str) – (optional) The format to export the certificate in. Returns bytes representing the exported certificate
write_certificate(filename, *args, **kwargs) Write a certificate to a file in the requested format This function is a simple wrapper around export_certificate which writes the exported certificate to a file. Parameters filename (PurePath or str) – The filename to write the certificate to. *args,**kwargs – Additional arguments to pass through to export_certificate().
append_certificate(filename, *args, **kwargs) Append a certificate to a file in the requested format This function is a simple wrapper around export_certificate which appends the exported certificate to an existing file. Parameters filename (PurePath or str) – The filename to append the certificate to. *args,**kwargs – Additional arguments to pass through to export_certificate().

generate_private_key

asyncssh.generate_private_key(alg_name, comment=None, **kwargs)

Generate a new private key

This function generates a new private key of a type matching the requested SSH algorithm. Depending on the algorithm, additional parameters can be passed which affect the generated key.

Available algorithms include:

ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ecdsa-sha2-1.3.132.0.10, ssh-ed25519, ssh-ed448, sk-ecdsa-sha2-nistp256@openssh.com, sk-ssh-ed25519@openssh.com

For dss keys, no parameters are supported. The key size is fixed at 1024 bits due to the use of SHA1 signatures.

For rsa keys, the key size can be specified using the key_size parameter, and the RSA public exponent can be changed using the exponent parameter. By default, generated keys are 2048 bits with a public exponent of 65537.

For ecdsa keys, the curve to use is part of the SSH algorithm name and that determines the key size. No other parameters are supported.

For ed25519 and ed448 keys, no parameters are supported. The key size is fixed by the algorithms at 256 bits and 448 bits, respectively.

For sk keys, the application name to associate with the generated key can be specified using the application parameter. It defaults to 'ssh:'. The user name to associate with the generated key can be specified using the user parameter. It defaults to 'AsyncSSH'.

When generating an sk key, a PIN can be provided via the pin parameter if the security key requires it.

The resident parameter can be set to True to request that a resident key be created on the security key. This allows the key handle and public key information to later be retrieved so that the generated key can be used without having to store any information on the client system. It defaults to False.

You can enable or disable the security key touch requirement by setting the touch_required parameter. It defaults to True, requiring that the user confirm their presence by touching the security key each time they use it to authenticate.

Parameters

• alg_name (str) – The SSH algorithm name corresponding to the desired type of key.

• comment (str, bytes, or None) – (optional) A comment to associate with this key.

• key_size (int) – (optional) The key size in bits for RSA keys.

• exponent (int) – (optional) The public exponent for RSA keys.

• application (str) – (optional) The application name to associate with the generated SK key, defaulting to 'ssh:'.

• user (str) – (optional) The user name to associate with the generated SK key, defaulting to 'AsyncSSH'.

• pin (str) – (optional) The PIN to use to access the security key, defaulting to None.

• resident (bool) – (optional) Whether or not to create a resident key on the security key, defaulting to False.

• touch_required (bool) – (optional) Whether or not to require the user to touch the security key when authenticating with it, defaulting to True.

Returns

An SSHKey private key

Raises

KeyGenerationError if the requested key parameters are unsupported

import_private_key

asyncssh.import_private_key(data, passphrase=None)

Import a private key

This function imports a private key encoded in PKCS#1 or PKCS#8 DER or PEM format or OpenSSH format. Encrypted private keys can be imported by specifying the passphrase needed to decrypt them.

Parameters

• data (bytes or ASCII str) – The data to import.

• passphrase (str or bytes) – (optional) The passphrase to use to decrypt the key.

Returns

An SSHKey private key

import_public_key

asyncssh.import_public_key(data)

Import a public key

This function imports a public key encoded in OpenSSH, RFC4716, or PKCS#1 or PKCS#8 DER or PEM format.

Parameters

data (bytes or ASCII str) – The data to import.

Returns

An SSHKey public key

import_certificate

asyncssh.import_certificate(data)

Import a certificate

This function imports an SSH certificate in DER, PEM, OpenSSH, or RFC4716 format.

Parameters

data (bytes or ASCII str) – The data to import.

Returns

An SSHCertificate object

read_private_key

asyncssh.read_private_key(filename, passphrase=None)

Read a private key from a file

This function reads a private key from a file. See the function import_private_key() for information about the formats supported.

Parameters

• filename (PurePath or str) – The file to read the key from.

• passphrase (str or bytes) – (optional) The passphrase to use to decrypt the key.

Returns

An SSHKey private key

read_public_key

asyncssh.read_public_key(filename)

Read a public key from a file

This function reads a public key from a file. See the function import_public_key() for information about the formats supported.

Parameters

filename (PurePath or str) – The file to read the key from.

Returns

An SSHKey public key

read_certificate

asyncssh.read_certificate(filename)

Read a certificate from a file

This function reads an SSH certificate from a file. See the function import_certificate() for information about the formats supported.

Parameters

filename (PurePath or str) – The file to read the certificate from.

Returns

An SSHCertificate object

read_private_key_list

asyncssh.read_private_key_list(filename, passphrase=None)

Read a list of private keys from a file

This function reads a list of private keys from a file. See the function import_private_key() for information about the formats supported. If any of the keys are encrypted, they must all be encrypted with the same passphrase.

Parameters

• filename (PurePath or str) – The file to read the keys from.

• passphrase (str or bytes) – (optional) The passphrase to use to decrypt the keys.

Returns

A list of SSHKey private keys

read_public_key_list

asyncssh.read_public_key_list(filename)

Read a list of public keys from a file

This function reads a list of public keys from a file. See the function import_public_key() for information about the formats supported.

Parameters

filename (PurePath or str) – The file to read the keys from.

Returns

A list of SSHKey public keys

read_certificate_list

asyncssh.read_certificate_list(filename)

Read a list of certificates from a file

This function reads a list of SSH certificates from a file. See the function import_certificate() for information about the formats supported.

Parameters

filename (PurePath or str) – The file to read the certificates from.

Returns

A list of SSHCertificate certificates

load_keypairs

asyncssh.load_keypairs(keylist, passphrase=None)

Load SSH private keys and optional matching certificates

This function loads a list of SSH keys and optional matching certificates.

When certificates are specified, the private key is added to the list both with and without the certificate.

Parameters

• keylist (see Specifying private keys) – The list of private keys and certificates to load.

• passphrase (str or bytes) – (optional) The passphrase to use to decrypt private keys.

Returns

A list of SSHKeyPair objects

load_public_keys

asyncssh.load_public_keys(keylist)

Load public keys

This function loads a list of SSH public keys.

Parameters

keylist (see Specifying public keys) – The list of public keys to load.

Returns

A list of SSHKey objects

load_certificates

asyncssh.load_certificates(certlist)

Load certificates

This function loads a list of OpenSSH or X.509 certificates.

Parameters

certlist (see Specifying certificates) – The list of certificates to load.

Returns

A list of SSHCertificate objects

load_resident_keys

asyncssh.load_resident_keys(pin, *, application='ssh:', user=None, touch_required=True)

Load keys resident on attached FIDO2 security keys

This function loads keys resident on any FIDO2 security keys currently attached to the system. The user name associated with each key is returned in the key’s comment field.

Parameters

• pin (str) – The PIN to use to access the security keys, defaulting to None.

• application (str) – (optional) The application name associated with the keys to load, defaulting to 'ssh:'.

• user (str) – (optional) The user name associated with the keys to load. By default, keys for all users are loaded.

• touch_required (bool) – (optional) Whether or not to require the user to touch the security key when authenticating with it, defaulting to True.

SSH Agent Support

AsyncSSH supports the ability to use private keys managed by the OpenSSH ssh-agent on UNIX systems. It can connect via a UNIX domain socket to the agent and offload all private key operations to it, avoiding the need to read these keys into AsyncSSH itself. An ssh-agent is automatically used in create_connection() when a valid SSH_AUTH_SOCK is set in the environment. An alternate path to the agent can be specified via the agent_path argument to this function.

An ssh-agent can also be accessed directly from AsyncSSH by calling connect_agent(). When successful, this function returns an SSHAgentClient which can be used to get a list of available keys, add and remove keys, and lock and unlock access to this agent.

SSH agent forwarding may be enabled when making outbound SSH connections by specifying the agent_forwarding argument when calling create_connection(), allowing processes running on the server to tunnel requests back over the SSH connection to the client’s ssh-agent.

Agent forwarding can be enabled when starting an SSH server by specifying the agent_forwarding argument when calling create_server(). In this case, the client’s ssh-agent can be accessed from the server by passing the SSHServerConnection as the argument to connect_agent() instead of a local path. Alternately, when an SSHServerChannel has been opened, the get_agent_path() method may be called on it to get a path to a UNIX domain socket which can be passed as the SSH_AUTH_SOCK to local applications which need this access. Any requests sent to this socket are forwarded over the SSH connection to the client’s ssh-agent.

SSHAgentClient

class asyncssh.SSHAgentClient

SSH agent client

async get_keys() Request the available client keys This method is a coroutine which returns a list of client keys available in the ssh-agent. Returns A list of SSHKeyPair objects
async add_keys(keylist=(), passphrase=None, lifetime=None, confirm=False) Add keys to the agent This method adds a list of local private keys and optional matching certificates to the agent. Parameters keylist (see Specifying private keys) – (optional) The list of keys to add. If not specified, an attempt will be made to load keys from the files .ssh/id_ed25519_sk, .ssh/id_ecdsa_sk, .ssh/id_ed448, .ssh/id_ed25519, .ssh/id_ecdsa, .ssh/id_rsa and .ssh/id_dsa in the user’s home directory with optional matching certificates loaded from the files .ssh/id_ed25519_sk-cert.pub, .ssh/id_ecdsa_sk-cert.pub, .ssh/id_ed448-cert.pub, .ssh/id_ed25519-cert.pub, .ssh/id_ecdsa-cert.pub, .ssh/id_rsa-cert.pub, and .ssh/id_dsa-cert.pub. Failures when adding keys are ignored in this case, as the agent may not recognize some of these key types. passphrase (str) – (optional) The passphrase to use to decrypt the keys. lifetime (int or None) – (optional) The time in seconds after which the keys should be automatically deleted, or None to store these keys indefinitely (the default). confirm (bool) – (optional) Whether or not to require confirmation for each private key operation which uses these keys, defaulting to False. Raises ValueError if the keys cannot be added
async add_smartcard_keys(provider, pin=None, lifetime=None, confirm=False) Store keys associated with a smart card in the agent Parameters provider (str) – The name of the smart card provider pin (str or None) – (optional) The PIN to use to unlock the smart card lifetime (int or None) – (optional) The time in seconds after which the keys should be automatically deleted, or None to store these keys indefinitely (the default). confirm (bool) – (optional) Whether or not to require confirmation for each private key operation which uses these keys, defaulting to False. Raises ValueError if the keys cannot be added
async remove_keys(keylist) Remove a key stored in the agent Parameters keylist (list of SSHKeyPair) – The list of keys to remove. Raises ValueError if any keys are not found
async remove_smartcard_keys(provider, pin=None) Remove keys associated with a smart card stored in the agent Parameters provider (str) – The name of the smart card provider pin (str or None) – (optional) The PIN to use to unlock the smart card Raises ValueError if the keys are not found
async remove_all() Remove all keys stored in the agent Raises ValueError if the keys can’t be removed
async lock(passphrase) Lock the agent using the specified passphrase Note The lock and unlock actions don’t appear to be supported on the Windows 10 OpenSSH agent. Parameters passphrase (str) – The passphrase required to later unlock the agent Raises ValueError if the agent can’t be locked
async unlock(passphrase) Unlock the agent using the specified passphrase Note The lock and unlock actions don’t appear to be supported on the Windows 10 OpenSSH agent. Parameters passphrase (str) – The passphrase to use to unlock the agent Raises ValueError if the agent can’t be unlocked
async query_extensions() Return a list of extensions supported by the agent Returns A list of strings of supported extension names
close() Close the SSH agent connection This method closes the connection to the ssh-agent. Any attempts to use this SSHAgentClient or the key pairs it previously returned will result in an error.
async wait_closed() Wait for this agent connection to close This method is a coroutine which can be called to block until the connection to the agent has finished closing.

SSHAgentKeyPair

class asyncssh.SSHAgentKeyPair

Surrogate for a key managed by the SSH agent

get_key_type() Return what type of key pair this is This method returns ‘local’ for locally loaded keys, and ‘agent’ for keys managed by an SSH agent.
get_algorithm() Return the algorithm associated with this key pair
get_comment_bytes() Return the comment associated with this key pair as a byte string Returns bytes or None
get_comment(encoding='utf-8', errors='strict') Return the comment associated with this key pair as a Unicode string Parameters encoding (str) – The encoding to use to decode the comment as a Unicode string, defaulting to UTF-8 errors (str) – The error handling scheme to use for Unicode decode errors Returns str or None Raises UnicodeDecodeError if the comment cannot be decoded using the specified encoding
set_comment(comment, encoding='utf-8', errors='strict') Set the comment associated with this key pair Parameters comment (str, bytes, or None) – The new comment to associate with this key encoding (str) – The Unicode encoding to use to encode the comment, defaulting to UTF-8 errors (str) – The error handling scheme to use for Unicode encode errors Raises UnicodeEncodeError if the comment cannot be encoded using the specified encoding
async remove() Remove this key pair from the agent

connect_agent

asyncssh.connect_agent(agent_path=None)

Make a connection to the SSH agent

This function attempts to connect to an ssh-agent process listening on a UNIX domain socket at agent_path. If not provided, it will attempt to get the path from the SSH_AUTH_SOCK environment variable.

If the connection is successful, an SSHAgentClient object is returned that has methods on it you can use to query the ssh-agent. If no path is specified and the environment variable is not set or the connection to the agent fails, an error is raised.

Parameters

agent_path (str or SSHServerConnection) – (optional) The path to use to contact the ssh-agent process, or the SSHServerConnection to forward the agent request over.

Returns

An SSHAgentClient

Raises

OSError or ChannelOpenError if the connection to the agent can’t be opened

Known Hosts

AsyncSSH supports OpenSSH-style known_hosts files, including both plain and hashed host entries. Regular and negated host patterns are supported in plain entries. AsyncSSH also supports the @cert_authority marker to indicate keys and certificates which should be trusted as certificate authorities and the @revoked marker to indicate keys and certificates which should be explicitly reported as no longer trusted.

Specifying known hosts

Known hosts may be passed into AsyncSSH via the known_hosts argument to create_connection(). This can be the name of a file containing a list of known hosts, a byte string containing a list of known hosts, or an SSHKnownHosts object which was previously imported from a string by calling import_known_hosts() or read from a file by calling read_known_hosts(). In all of these cases, the host patterns in the list will be compared against the target host, address, and port being connected to and the matching trusted host keys, trusted CA keys, revoked keys, trusted X.509 certificates, revoked X.509 certificates, trusted X.509 subject names, and revoked X.509 subject names will be returned.

Alternately, a function can be passed in as the known_hosts argument that accepts a target host, address, and port and returns lists containing trusted host keys, trusted CA keys, revoked keys, trusted X.509 certificates, revoked X.509 certificates, trusted X.509 subject names, and revoked X.509 subject names.

If no matching is required and the caller already knows exactly what the above values should be, these seven lists can also be provided directly in the known_hosts argument.

See Specifying public keys for the allowed form of public key values which can be provided, Specifying certificates for the allowed form of certificates, and Specifying X.509 subject names for the allowed form of X.509 subject names.

SSHKnownHosts

class asyncssh.SSHKnownHosts

An SSH known hosts list

match(host, addr, port) Match a host, IP address, and port against known_hosts patterns If the port is not the default port and no match is found for it, the lookup is attempted again without a port number. Parameters host (str) – The hostname of the target host addr (str) – The IP address of the target host port (int) – The port number on the target host, or None for the default Returns A tuple of matching host keys, CA keys, and revoked keys

import_known_hosts

asyncssh.import_known_hosts(data)

Import SSH known hosts

This function imports known host patterns and keys in OpenSSH known hosts format.

Parameters

data (str) – The known hosts data to import

Returns

An SSHKnownHosts object

read_known_hosts

asyncssh.read_known_hosts(filename)

Read SSH known hosts from a file

This function reads known host patterns and keys in OpenSSH known hosts format from a file.

Parameters

filename (str) – The file to read the known hosts from

Returns

An SSHKnownHosts object

match_known_hosts

asyncssh.match_known_hosts(known_hosts, host, addr, port)

Match a host, IP address, and port against a known_hosts list

This function looks up a host, IP address, and port in a list of host patterns in OpenSSH known_hosts format and returns the host keys, CA keys, and revoked keys which match.

The known_hosts argument can be any of the following:

• a string containing the filename to load host patterns from

• a byte string containing host pattern data to load

• an already loaded SSHKnownHosts object containing host patterns to match against

• an alternate matching function which accepts a host, address, and port and returns lists of trusted host keys, trusted CA keys, and revoked keys to load

• lists of trusted host keys, trusted CA keys, and revoked keys to load without doing any matching

If the port is not the default port and no match is found for it, the lookup is attempted again without a port number.

Parameters

• known_hosts – The host patterns to match against

• host (str) – The hostname of the target host

• addr (str) – The IP address of the target host

• port (int) – The port number on the target host, or None for the default

Returns

A tuple of matching host keys, CA keys, and revoked keys

Authorized Keys

AsyncSSH supports OpenSSH-style authorized_keys files, including the cert-authority option to validate user certificates, enforcement of from and principals options to restrict key matching, enforcement of no-X11-forwarding, no-agent-forwarding, no-pty, no-port-forwarding, and permitopen options, and support for command and environment options.

Specifying authorized keys

Authorized keys may be passed into AsyncSSH via the authorized_client_keys argument to create_server() or by calling set_authorized_keys() on the SSHServerConnection from within the begin_auth() method in SSHServer.

Authorized keys can be provided as either the name of a file to read the keys from or an SSHAuthorizedKeys object which was previously imported from a string by calling import_authorized_keys() or read from a file by calling read_authorized_keys().

An authorized keys file may contain public keys or X.509 certificates in OpenSSH format or X.509 certificate subject names. See Specifying X.509 subject names for more information on using subject names in place of specific X.509 certificates.

SSHAuthorizedKeys

class asyncssh.SSHAuthorizedKeys

An SSH authorized keys list

import_authorized_keys

asyncssh.import_authorized_keys(data)

Import SSH authorized keys

This function imports public keys and associated options in OpenSSH authorized keys format.

Parameters

data (str) – The key data to import.

Returns

An SSHAuthorizedKeys object

read_authorized_keys

asyncssh.read_authorized_keys(filename)

Read SSH authorized keys from a file

This function reads public keys and associated options in OpenSSH authorized_keys format from a file.

Parameters

filename (str) – The file to read the keys from.

Returns

An SSHAuthorizedKeys object

Logging

AsyncSSH supports logging through the standard Python logging package. Logging is done under the logger named 'asyncssh' as well as a child logger named 'asyncssh.sftp' to allow different log levels to be set for SFTP related log messages.

The base AsyncSSH log level can be set using the set_log_level() function and the SFTP log level can be set using the set_sftp_log_level() function. In addition, when either of these loggers is set to level DEBUG, AsyncSSH provides fine-grained control over the level of debug logging via the set_debug_level() function.

AsyncSSH also provides logger objects as members of connection, channel, stream, and process objects that automatically log additional context about the connection or channel the logger is a member of. These objects can be used by application code to output custom log information associated with a particular connection or channel. Logger objects are also provided as members of SFTP client and server objects.

set_log_level

asyncssh.set_log_level(level)

Set the AsyncSSH log level

This function sets the log level of the AsyncSSH logger. It defaults to 'NOTSET’, meaning that it will track the debug level set on the root Python logger.

For additional control over the level of debug logging, see the function set_debug_level() for additional information.

Parameters

level (int or str) – The log level to set, as defined by the logging module

set_sftp_log_level

asyncssh.set_sftp_log_level(level)

Set the AsyncSSH SFTP/SCP log level

This function sets the log level of the AsyncSSH SFTP/SCP logger. It defaults to 'NOTSET’, meaning that it will track the debug level set on the main AsyncSSH logger.

For additional control over the level of debug logging, see the function set_debug_level() for additional information.

Parameters

level (int or str) – The log level to set, as defined by the logging module

set_debug_level

asyncssh.set_debug_level(level)

Set the AsyncSSH debug log level

This function sets the level of debugging logging done by the AsyncSSH logger, from the following options:

Level	Description
1	Minimal debug logging
2	Full debug logging
3	Full debug logging with packet dumps

The debug level defaults to level 1 (minimal debug logging).

Note

For this setting to have any effect, the effective log level of the AsyncSSH logger must be set to DEBUG.

Warning

Extreme caution should be used when setting debug level to 3, as this can expose user passwords in clear text. This level should generally only be needed when tracking down issues with malformed or incomplete packets.

Parameters

level (int) – The debug level to set, as defined above.

Exceptions

PasswordChangeRequired

exception asyncssh.PasswordChangeRequired(prompt, lang='en-US')

SSH password change required

This exception is raised during password validation on the server to indicate that a password change is required. It should be raised when the password provided is valid but expired, to trigger the client to provide a new password.

Parameters

• prompt (str) – The prompt requesting that the user enter a new password

• lang (str) – The language that the prompt is in

BreakReceived

exception asyncssh.BreakReceived(msec)

SSH break request received

This exception is raised on an SSH server stdin stream when the client sends a break on the channel.

Parameters

msec (int) – The duration of the break in milliseconds

SignalReceived

exception asyncssh.SignalReceived(signal)

SSH signal request received

This exception is raised on an SSH server stdin stream when the client sends a signal on the channel.

Parameters

signal (str) – The name of the signal sent by the client

TerminalSizeChanged

exception asyncssh.TerminalSizeChanged(width, height, pixwidth, pixheight)

SSH terminal size change notification received

This exception is raised on an SSH server stdin stream when the client sends a terminal size change on the channel.

Parameters

• width (int) – The new terminal width

• height (int) – The new terminal height

• pixwidth (int) – The new terminal width in pixels

• pixheight (int) – The new terminal height in pixels

DisconnectError

exception asyncssh.DisconnectError(code, reason, lang='en-US')

SSH disconnect error

This exception is raised when a serious error occurs which causes the SSH connection to be disconnected. Exception codes should be taken from disconnect reason codes. See below for exception subclasses tied to specific disconnect reasons if you want to customize your handling by reason.

Parameters

• code (int) – Disconnect reason, taken from disconnect reason codes

• reason (str) – A human-readable reason for the disconnect

• lang (str) – (optional) The language the reason is in

exception asyncssh.CompressionError(reason, lang='en-US')

SSH compression error

This exception is raised when an error occurs while compressing or decompressing data sent on the SSH connection.

Parameters

• reason (str) – Details about the compression error

• lang (str) – (optional) The language the reason is in

exception asyncssh.ConnectionLost(reason, lang='en-US')

SSH connection lost

This exception is raised when the SSH connection to the remote system is unexpectedly lost. It can also occur as a result of the remote system failing to respond to keepalive messages or as a result of a login timeout, when those features are enabled.

Parameters

• reason (str) – Details about the connection failure

• lang (str) – (optional) The language the reason is in

exception asyncssh.HostKeyNotVerifiable(reason, lang='en-US')

SSH host key not verifiable

This exception is raised when the SSH server’s host key or certificate is not verifiable.

Parameters

• reason (str) – Details about the host key verification failure

• lang (str) – (optional) The language the reason is in

exception asyncssh.IllegalUserName(reason, lang='en-US')

SSH illegal user name

This exception is raised when an error occurs while processing the username sent during the SSL handshake.

Parameters

• reason (str) – Details about the illegal username

• lang (str) – (optional) The language the reason is in

exception asyncssh.KeyExchangeFailed(reason, lang='en-US')

SSH key exchange failed

This exception is raised when the SSH key exchange fails.

Parameters

• reason (str) – Details about the connection failure

• lang (str) – (optional) The language the reason is in

exception asyncssh.MACError(reason, lang='en-US')

SSH MAC error

This exception is raised when an error occurs while processing the message authentication code (MAC) of a message on the SSH connection.

Parameters

• reason (str) – Details about the MAC error

• lang (str) – (optional) The language the reason is in

exception asyncssh.PermissionDenied(reason, lang='en-US')

SSH permission denied

This exception is raised when there are no authentication methods remaining to complete SSH client authentication.

Parameters

• reason (str) – Details about the SSH protocol error detected

• lang (str) – (optional) The language the reason is in

exception asyncssh.ProtocolError(reason, lang='en-US')

SSH protocol error

This exception is raised when the SSH connection is disconnected due to an SSH protocol error being detected.

Parameters

• reason (str) – Details about the SSH protocol error detected

• lang (str) – (optional) The language the reason is in

exception asyncssh.ProtocolNotSupported(reason, lang='en-US')

SSH protocol not supported

This exception is raised when the remote system sends an SSH protocol version which is not supported.

Parameters

• reason (str) – Details about the unsupported SSH protocol version

• lang (str) – (optional) The language the reason is in

exception asyncssh.ServiceNotAvailable(reason, lang='en-US')

SSH service not available

This exception is raised when an unexpected service name is received during the SSH handshake.

Parameters

• reason (str) – Details about the unexpected SSH service

• lang (str) – (optional) The language the reason is in

ChannelOpenError

exception asyncssh.ChannelOpenError(code, reason, lang='en-US')

SSH channel open error

This exception is raised by connection handlers to report channel open failures.

Parameters

• code (int) – Channel open failure reason, taken from channel open failure reason codes

• reason (str) – A human-readable reason for the channel open failure

• lang (str) – The language the reason is in

ChannelListenError

exception asyncssh.ChannelListenError

SSH channel listen error

This exception is raised to report failures in setting up remote SSH connection listeners.

Parameters

details (str) – Details of the listen failure

ProcessError

exception asyncssh.ProcessError(env, command, subsystem, exit_status, exit_signal, returncode, stdout, stderr, reason='', lang='en-US')

SSH Process error

This exception is raised when an SSHClientProcess exits with a non-zero exit status and error checking is enabled. In addition to the usual error code, reason, and language, it contains the following fields:

Field	Description	Type
env	The environment the client requested to be set for the process	str or None
command	The command the client requested the process to execute (if any)	str or None
subsystem	The subsystem the client requested the process to open (if any)	str or None
exit_status	The exit status returned, or -1 if an exit signal is sent	int or None
exit_signal	The exit signal sent (if any) in the form of a tuple containing the signal name, a bool for whether a core dump occurred, a message associated with the signal, and the language the message was in	tuple or None
returncode	The exit status returned, or negative of the signal number when an exit signal is sent	int or None
stdout	The output sent by the process to stdout (if not redirected)	str or bytes
stderr	The output sent by the process to stderr (if not redirected)	str or bytes

TimeoutError

exception asyncssh.TimeoutError(env, command, subsystem, exit_status, exit_signal, returncode, stdout, stderr, reason='', lang='en-US')

SSH Process timeout error

This exception is raised when a timeout occurs when calling the wait method on SSHClientProcess or the run method on SSHClientConnection. It is a subclass of ProcessError and contains all of the fields documented there, including any output received on stdout and stderr prior to when the timeout occurred. It is also a subclass of asyncio.TimeoutError, for code that might be expecting that.

SFTPError

exception asyncssh.SFTPError(code, reason, lang='en-US')

SFTP error

This exception is raised when an error occurs while processing an SFTP request. Exception codes should be taken from SFTP error codes.

Parameters

• code (int) – Disconnect reason, taken from disconnect reason codes

• reason (str) – A human-readable reason for the disconnect

• lang (str) – (optional) The language the reason is in

exception asyncssh.SFTPEOFError(reason='', lang='en-US')

SFTP EOF error

This exception is raised when end of file is reached when reading a file or directory.

Parameters

• reason (str) – (optional) Details about the EOF

• lang (str) – (optional) The language the reason is in

exception asyncssh.SFTPNoSuchFile(reason, lang='en-US')

SFTP no such file

This exception is raised when the requested file is not found.

Parameters

• reason (str) – Details about the missing file

• lang (str) – (optional) The language the reason is in

exception asyncssh.SFTPPermissionDenied(reason, lang='en-US')

SFTP permission denied

This exception is raised when the permissions are not available to perform the requested operation.

Parameters

• reason (str) – Details about the invalid permissions

• lang (str) – (optional) The language the reason is in

exception asyncssh.SFTPFailure(reason, lang='en-US')

SFTP failure

This exception is raised when an unexpected SFTP failure occurs.

Parameters

• reason (str) – Details about the failure

• lang (str) – (optional) The language the reason is in

exception asyncssh.SFTPBadMessage(reason, lang='en-US')

SFTP bad message

This exception is raised when an invalid SFTP message is received.

Parameters

• reason (str) – Details about the invalid message

• lang (str) – (optional) The language the reason is in

exception asyncssh.SFTPNoConnection(reason, lang='en-US')

SFTP no connection

This exception is raised when an SFTP request is made on a closed SSH connection.

Parameters

• reason (str) – Details about the closed connection

• lang (str) – (optional) The language the reason is in

exception asyncssh.SFTPConnectionLost(reason, lang='en-US')

SFTP connection lost

This exception is raised when the SSH connection is lost or closed while making an SFTP request.

Parameters

• reason (str) – Details about the connection failure

• lang (str) – (optional) The language the reason is in

exception asyncssh.SFTPOpUnsupported(reason, lang='en-US')

SFTP operation unsupported

This exception is raised when the requested SFTP operation is not supported.

Parameters

• reason (str) – Details about the unsupported operation

• lang (str) – (optional) The language the reason is in

KeyImportError

exception asyncssh.KeyImportError

Key import error

This exception is raised by key import functions when the data provided cannot be imported as a valid key.

KeyExportError

exception asyncssh.KeyExportError

Key export error

This exception is raised by key export functions when the requested format is unknown or encryption is requested for a format which doesn’t support it.

KeyEncryptionError

exception asyncssh.KeyEncryptionError

Key encryption error

This exception is raised by key decryption functions when the data provided is not a valid encrypted private key.

KeyGenerationError

exception asyncssh.KeyGenerationError

Key generation error

This exception is raised by generate_private_key(), generate_user_certificate() or generate_host_certificate() when the requested parameters are unsupported.

Supported Algorithms

Key exchange algorithms

The following are the key exchange algorithms currently supported by AsyncSSH:

gss-curve25519-sha256

gss-curve448-sha512

gss-nistp521-sha512

gss-nistp384-sha256

gss-nistp256-sha256

gss-1.3.132.0.10-sha256

gss-gex-sha256

gss-gex-sha1

gss-group14-sha256

gss-group15-sha512

gss-group16-sha512

gss-group17-sha512

gss-group18-sha512

gss-group14-sha1

gss-group1-sha1

curve25519-sha256

curve25519-sha256@libssh.org

curve448-sha512

ecdh-sha2-nistp521

ecdh-sha2-nistp384

ecdh-sha2-nistp256

ecdh-sha2-1.3.132.0.10

diffie-hellman-group-exchange-sha256

diffie-hellman-group-exchange-sha1

diffie-hellman-group14-sha256

diffie-hellman-group15-sha512

diffie-hellman-group16-sha512

diffie-hellman-group17-sha512

diffie-hellman-group18-sha512

diffie-hellman-group14-sha1

diffie-hellman-group1-sha1

rsa2048-sha256

rsa1024-sha1

GSS authentication support is only available when the gssapi package is installed on UNIX or the pywin32 package is installed on Windows.

Curve25519 and Curve448 support is available when OpenSSL 1.1.1 or later is installed. Alternately, Curve25519 is available when the libnacl package and libsodium library are installed.

Encryption algorithms

The following are the encryption algorithms currently supported by AsyncSSH:

chacha20-poly1305@openssh.com

aes256-ctr

aes192-ctr

aes128-ctr

aes256-gcm@openssh.com

aes128-gcm@openssh.com

aes256-cbc

aes192-cbc

aes128-cbc

3des-cbc

blowfish-cbc

cast128-cbc

arcfour256

arcfour128

arcfour

Chacha20-Poly1305 support is available when either OpenSSL 1.1.1b or later or the libnacl package and libsodium library are installed.

MAC algorithms

The following are the MAC algorithms currently supported by AsyncSSH:

umac-64-etm@openssh.com

umac-128-etm@openssh.com

hmac-sha2-256-etm@openssh.com

hmac-sha2-512-etm@openssh.com

hmac-sha1-etm@openssh.com

hmac-md5-etm@openssh.com

hmac-sha2-256-96-etm@openssh.com

hmac-sha2-512-96-etm@openssh.com

hmac-sha1-96-etm@openssh.com

hmac-md5-96-etm@openssh.com

umac-64@openssh.com

umac-128@openssh.com

hmac-sha2-256

hmac-sha2-512

hmac-sha1

hmac-md5

hmac-sha2-256-96

hmac-sha2-512-96

hmac-sha1-96

hmac-md5-96

UMAC support is only available when the nettle library is installed.

Compression algorithms

The following are the compression algorithms currently supported by AsyncSSH:

zlib@openssh.com

zlib

none

Signature algorithms

The following are the public key signature algorithms currently supported by AsyncSSH:

x509v3-ecdsa-sha2-nistp521

x509v3-ecdsa-sha2-nistp384

x509v3-ecdsa-sha2-nistp256

x509v3-ecdsa-sha2-1.3.132.0.10

x509v3-rsa2048-sha256

x509v3-ssh-rsa

x509v3-ssh-dss

sk-ssh-ed25519@openssh.com

sk-ecdsa-sha2-nistp256@openssh.com

ssh-ed25519

ssh-ed448

ecdsa-sha2-nistp521

ecdsa-sha2-nistp384

ecdsa-sha2-nistp256

ecdsa-sha2-1.3.132.0.10

rsa-sha2-256

rsa-sha2-512

ssh-rsa

ssh-dss

Public key & certificate algorithms

The following are the public key and certificate algorithms currently supported by AsyncSSH:

x509v3-ecdsa-sha2-nistp521

x509v3-ecdsa-sha2-nistp384

x509v3-ecdsa-sha2-nistp256

x509v3-ecdsa-sha2-1.3.132.0.10

x509v3-rsa2048-sha256

x509v3-ssh-rsa

x509v3-ssh-dss

sk-ssh-ed25519-cert-v01@openssh.com

sk-ecdsa-sha2-nistp256-cert-v01@openssh.com

ssh-ed25519-cert-v01@openssh.com

ssh-ed448-cert-v01@openssh.com

ecdsa-sha2-nistp521-cert-v01@openssh.com

ecdsa-sha2-nistp384-cert-v01@openssh.com

ecdsa-sha2-nistp256-cert-v01@openssh.com

ecdsa-sha2-1.3.132.0.10-cert-v01@openssh.com

ssh-rsa-cert-v01@openssh.com

ssh-dss-cert-v01@openssh.com

sk-ssh-ed25519@openssh.com

sk-ecdsa-sha2-nistp256@openssh.com

ssh-ed25519

ssh-ed448

ecdsa-sha2-nistp521

ecdsa-sha2-nistp384

ecdsa-sha2-nistp256

ecdsa-sha2-1.3.132.0.10

rsa-sha2-256

rsa-sha2-512

ssh-rsa

ssh-dss

Ed25519 and Ed448 support is available when OpenSSL 1.1.1b or later is installed. Alternately, Ed25519 is available when the libnacl package and libsodium library are installed.

Constants

Disconnect reasons

The following values defined in section 11.1 of RFC 4253#section-11.1 can be specified as disconnect reason codes:

DISC_HOST_NOT_ALLOWED_TO_CONNECT

DISC_PROTOCOL_ERROR

DISC_KEY_EXCHANGE_FAILED

DISC_RESERVED

DISC_MAC_ERROR

DISC_COMPRESSION_ERROR

DISC_SERVICE_NOT_AVAILABLE

DISC_PROTOCOL_VERSION_NOT_SUPPORTED

DISC_HOST_KEY_NOT_VERIFIABLE

DISC_CONNECTION_LOST

DISC_BY_APPLICATION

DISC_TOO_MANY_CONNECTIONS

DISC_AUTH_CANCELLED_BY_USER

DISC_NO_MORE_AUTH_METHODS_AVAILABLE

DISC_ILLEGAL_USER_NAME

Channel open failure reasons

The following values defined in section 5.1 of RFC 4254#section-5.1 can be specified as channel open failure reason codes:

OPEN_ADMINISTRATIVELY_PROHIBITED

OPEN_CONNECT_FAILED

OPEN_UNKNOWN_CHANNEL_TYPE

OPEN_RESOURCE_SHORTAGE

In addition, AsyncSSH defines the following channel open failure reason codes:

OPEN_REQUEST_X11_FORWARDING_FAILED

OPEN_REQUEST_PTY_FAILED

OPEN_REQUEST_SESSION_FAILED

SFTP error codes

The following values defined in the SSH File Transfer Internet Draft can be specified as SFTP error codes:

FX_OK

FX_EOF

FX_NO_SUCH_FILE

FX_PERMISSION_DENIED

FX_FAILURE

FX_BAD_MESSAGE

FX_NO_CONNECTION

FX_CONNECTION_LOST

FX_OP_UNSUPPORTED

Extended data types

The following values defined in section 5.2 of RFC 4254#section-5.2 can be specified as SSH extended channel data types:

EXTENDED_DATA_STDERR

POSIX terminal modes

The following values defined in section 8 of RFC 4254#section-8 can be specified as PTY mode opcodes:

PTY_OP_END

PTY_VINTR

PTY_VQUIT

PTY_VERASE

PTY_VKILL

PTY_VEOF

PTY_VEOL

PTY_VEOL2

PTY_VSTART

PTY_VSTOP

PTY_VSUSP

PTY_VDSUSP

PTY_VREPRINT

PTY_WERASE

PTY_VLNEXT

PTY_VFLUSH

PTY_VSWTCH

PTY_VSTATUS

PTY_VDISCARD

PTY_IGNPAR

PTY_PARMRK

PTY_INPCK

PTY_ISTRIP

PTY_INLCR

PTY_IGNCR

PTY_ICRNL

PTY_IUCLC

PTY_IXON

PTY_IXANY

PTY_IXOFF

PTY_IMAXBEL

PTY_ISIG

PTY_ICANON

PTY_XCASE

PTY_ECHO

PTY_ECHOE

PTY_ECHOK

PTY_ECHONL

PTY_NOFLSH

PTY_TOSTOP

PTY_IEXTEN

PTY_ECHOCTL

PTY_ECHOKE

PTY_PENDIN

PTY_OPOST

PTY_OLCUC

PTY_ONLCR

PTY_OCRNL

PTY_ONOCR

PTY_ONLRET

PTY_CS7

PTY_CS8

PTY_PARENB

PTY_PARODD

PTY_OP_ISPEED

PTY_OP_OSPEED