# 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=(), *, tunnel=(), family=(), flags=0, local_addr=(), config=(), 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.

  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` or `str`) – (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. A string of the form [user@]host[:port] may also be specified, in which case a connection will first be made to that host and it will then be used as a tunnel.

    - 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

    - config (`list` of `str`) – (optional) Paths to OpenSSH client configuration files to load. This configuration will be used as a fallback to override the defaults for settings which are not explcitly specified using AsyncSSH’s configuration options. If no paths are specified and no config paths were set when constructing the `options` argument (if any), an attempt will be made to load the configuration from the file `.ssh/config`. If this argument is explicitly set to `None`, no new configuration files will be loaded, but any configuration loaded when constructing the `options` argument will still apply. See Supported client config options for details on what configuration options are currently supported.

    - 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=(), *, tunnel=(), family=(), flags=0, local_addr=(), config=(), 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` or `str`) – (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. A string of the form [user@]host[:port] may also be specified, in which case a connection will first be made to that host and it will then be used as a tunnel.

    - 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

    - config (`list` of `str`) – (optional) Paths to OpenSSH server configuration files to load. This configuration will be used as a fallback to override the defaults for settings which are not explcitly specified using AsyncSSH’s configuration options. By default, no OpenSSH configuration files will be loaded. See Supported server config options for details on what configuration options are currently supported.

    - 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='', port=(), *, tunnel=(), family=(), flags=AddressInfo.AI_PASSIVE, backlog=100, reuse_address=False, reuse_port=False, acceptor=None, error_handler=None, config=(), 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 `SSHAcceptor` 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` or `str`) – (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. A string of the form [user@]host[:port] may also be specified, in which case a connection will first be made to that host and it will then be used as a tunnel.

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

    - config (`list` of `str`) – (optional) Paths to OpenSSH server configuration files to load. This configuration will be used as a fallback to override the defaults for settings which are not explcitly specified using AsyncSSH’s configuration options. By default, no OpenSSH configuration files will be loaded. See Supported server config options for details on what configuration options are currently supported.

    - 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

    `SSHAcceptor`

### listen_reverse

asyncssh.listen_reverse(host='', port=(), *, tunnel=(), family=(), flags=AddressInfo.AI_PASSIVE, backlog=100, reuse_address=False, reuse_port=False, acceptor=None, error_handler=None, config=(), 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 `SSHAcceptor` 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` or `str`) – (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. A string of the form [user@]host[:port] may also be specified, in which case a connection will first be made to that host and it will then be used as a tunnel.

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

    - config (`list` of `str`) – (optional) Paths to OpenSSH client configuration files to load. This configuration will be used as a fallback to override the defaults for settings which are not explcitly specified using AsyncSSH’s configuration options. If no paths are specified and no config paths were set when constructing the `options` argument (if any), an attempt will be made to load the configuration from the file `.ssh/config`. If this argument is explicitly set to `None`, no new configuration files will be loaded, but any configuration loaded when constructing the `options` argument will still apply. See Supported client config options for details on what configuration options are currently supported.

    - 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

    `SSHAcceptor`

### create_connection

async asyncssh.create_connection(client_factory, host, port=(), **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.AbstractEventLoop.create_connection()`.

  Returns

    An `SSHClientConnection` and `SSHClient`

### create_server

asyncssh.create_server(server_factory, host='', port=(), **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.AbstractEventLoop.create_server()`.

### get_server_host_key

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

  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` or `str`) – (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. A string of the form [user@]host[:port] may also be specified, in which case a connection will first be made to that host and it will then be used as a tunnel.

    - proxy_command (`str` or `list` of `str`) – (optional) A string or list of strings specifying a command and arguments to run to make a connection to the SSH server. Data will be forwarded to this process over stdin/stdout instead of opening a TCP connection. If specified as a string, standard shell quoting will be applied when splitting the command and its arguments.

    - 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 (`str` or `list` of `str`) – (optional) A list of allowed key exchange algorithms in the SSH handshake, taken from key exchange algorithms

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

    - config (`list` of `str`) – (optional) Paths to OpenSSH client configuration files to load. This configuration will be used as a fallback to override the defaults for settings which are not explcitly specified using AsyncSSH’s configuration options. If no paths are specified and no config paths were set when constructing the `options` argument (if any), an attempt will be made to load the configuration from the file `.ssh/config`. If this argument is explicitly set to `None`, no new configuration files will be loaded, but any configuration loaded when constructing the `options` argument will still apply. See Supported client config options for details on what configuration options are currently supported.

    - options (`SSHClientConnectionOptions`) – (optional) Options to use when establishing the SSH client connection used to retrieve the server host key. These options can be specified either through this parameter or as direct keyword arguments to this function.

  Returns

    An `SSHKey` public key or `None`

### get_server_auth_methods

async asyncssh.get_server_auth_methods(host, port=(), username=(), *, tunnel=(), proxy_command=(), family=(), flags=0, local_addr=(), client_version=(), kex_algs=(), server_host_key_algs=(), config=(), options=None)

  Retrieve an SSH server’s allowed auth methods

  This is a coroutine which can be run to connect to an SSH server and return the auth methods available to authenticate to it.

  > Note

  > The key exchange with the server must complete successfully before the list of available auth methods can be returned, so be sure to specify any arguments needed to complete the key exchange. Also, auth methods may vary by user, so you may want to specify the specific user you would like to get auth methods for.

  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.

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

    - tunnel (`SSHClientConnection` or `str`) – (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. A string of the form [user@]host[:port] may also be specified, in which case a connection will first be made to that host and it will then be used as a tunnel.

    - proxy_command (`str` or `list` of `str`) – (optional) A string or list of strings specifying a command and arguments to run to make a connection to the SSH server. Data will be forwarded to this process over stdin/stdout instead of opening a TCP connection. If specified as a string, standard shell quoting will be applied when splitting the command and its arguments.

    - 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 (`str` or `list` of `str`) – (optional) A list of allowed key exchange algorithms in the SSH handshake, taken from key exchange algorithms

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

    - config (`list` of `str`) – (optional) Paths to OpenSSH client configuration files to load. This configuration will be used as a fallback to override the defaults for settings which are not explcitly specified using AsyncSSH’s configuration options. If no paths are specified and no config paths were set when constructing the `options` argument (if any), an attempt will be made to load the configuration from the file `.ssh/config`. If this argument is explicitly set to `None`, no new configuration files will be loaded, but any configuration loaded when constructing the `options` argument will still apply. See Supported client config options for details on what configuration options are currently supported.

    - options (`SSHClientConnectionOptions`) – (optional) Options to use when establishing the SSH client connection used to retrieve the server host key. These options can be specified either through this parameter or as direct keyword arguments to this function.

  Returns

    a `list` of `str`

### 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`, `float`, or `str`) – (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=(), *, subsystem=(), env=(), send_env=(), request_pty=(), term_type=(), term_size=(), term_modes=(), x11_forwarding=(), x11_display=(), x11_auth_path=(), x11_single_connection=(), encoding=(), errors=(), window=(), max_pktsize=())

    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` with `str` keys and values) –

        (optional) The 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.

      - send_env (`list` of `str`) – (optional) A list of environment variable names to pull from `os.environ` and set for this session. Wildcards patterns using `'*'` and `'?'` are allowed, and all variables with matching names will be sent with whatever value is set in the local environment. If a variable is present in both env and send_env, the value from env will be used.

      - request_pty (`bool`, `'force'`, or `'auto'`) – (optional) Whether or not to request a pseudo-terminal (PTY) for this session. This defaults to `True`, which means to request a PTY whenever the `term_type` is set. Other possible values include `False` to never request a PTY, `'force'` to always request a PTY even without `term_type` being set, or `'auto'` to request a TTY when `term_type` is set but only when starting an interactive shell.

      - term_type (`str`) – (optional) The terminal type to set 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` with `int` keys and values) – (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` or `'ignore_failure'`) – (optional) Whether or not to request X11 forwarding for this session, defaulting to `False`. If set to `True`, X11 forwarding will be requested and a failure will raise `ChannelOpenError`. It can also be set to `'ignore_failure'` to attempt X11 forwarding but ignore failures.

      - 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` or `None`) – (optional) The Unicode encoding to use for data exchanged on this session.

      - errors (`str`) – (optional) The error handling strategy to apply on Unicode 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=(), send_env=(), path_encoding='utf-8', path_errors='strict', sftp_version=3)

    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 (`dict` with `str` keys and values) –

        (optional) The 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.

      - send_env (`list` of `str`) – (optional) A list of environment variable names to pull from `os.environ` and set for this SFTP session. Wildcards patterns using `'*'` and `'?'` are allowed, and all variables with matching names will be sent with whatever value is set in the local environment. If a variable is present in both env and send_env, the value from env will be used.

      - path_encoding (`str` or `None`) – The Unicode encoding to apply when sending and receiving remote pathnames

      - path_errors (`str`) – The error handling strategy to apply on encode/decode errors

      - sftp_version (`int`) – (optional) The maximum version of the SFTP protocol to support, currently either 3 or 4, defaulting to 3.

    Returns

      `SFTPClient`

    Raises

      `SFTPError` if the session can’t be opened

  async create_ssh_connection(client_factory, host, port=(), **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=(), **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=(), **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=(), **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=(), **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 `SSHTCPSession` 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` or `None`) – (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`) – 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` or `None`) – (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 `SSHUNIXSession` object that will be created to handle activity on this session

      - remote_path (`str`) – The remote path to connect to

      - encoding (`str` or `None`) – (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`) – A `callable` or coroutine which 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` or `None`) – (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 decides whether to accept the UNIX domain socket 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` or `None`) – The hostname or address to forward the connections to

      - dest_port (`int`) – The port number to forward the connections to

    Returns

      `asyncio.BaseProtocol`

  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`, `float`, or `str`) – (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 `SSHTCPSession` 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` or `None`) – (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 `SSHUNIXSession` object that will be created to handle activity on this session

      - remote_path (`str`) – The path the connection was received on

      - encoding (`str` or `None`) – (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` or `None`) – The hostname or address to forward the connections to

      - dest_port (`int`) – The port number to forward the connections to

    Returns

      `asyncio.BaseProtocol`

  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

      `asyncio.BaseProtocol`

  Server channel creation methods |
  --- | ---

  create_server_channel(encoding='', errors='', window=0, max_pktsize=0)

    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` or `None`) – (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` or `None`) – (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` or `None`) – (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` returning `SSHClientConnection`) – (optional) A `callable` which returns an `SSHClient` object that will be created for each new connection.

    - proxy_command (`str` or `list` of `str`) – (optional) A string or list of strings specifying a command and arguments to run to make a connection to the SSH server. Data will be forwarded to this process over stdin/stdout instead of opening a TCP connection. If specified as a string, standard shell quoting will be applied when splitting the command and its arguments.

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

    - host_key_alias (`str`) – (optional) An alias to use instead of the real host name when looking up a host key in known_hosts and when validating host certificates.

    - server_host_key_algs (`str` or `list` of `str`) –

      (optional) A list of server host key algorithms to use instead of the default of 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, since AsyncSSH can not determine which server host key algorithms are preferred. This argument can also be set to ‘default’ to specify that the client should always send its default list of supported algorithms to avoid leaking information about what algorithms are present for the server in known_hosts.

      > Note

      > The ‘default’ keyword should be used with caution, as it can result in a host key mismatch if the client trusts only a subset of the host keys the server might return.

    - 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_certs (see Specifying certificates) – (optional) A list of optional certificates which can be paired with the provided client host keys.

    - 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. These keys will be used after trying keys from a PKCS11 provider or an ssh-agent, if either of those are configured. If no client keys are specified, an attempt will be made to 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.

    - client_certs (see Specifying certificates) – (optional) A list of optional certificates which can be paired with the provided client keys.

    - passphrase (`str` or `bytes`) – (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.

    - ignore_encrypted (`bool`) – (optional) Whether or not to ignore encrypted keys when no passphrase is provided. This is intended to allow encrypted keys specified via the IdentityFile config option to be ignored if a passphrase is not specified, loading only unencrypted local keys. Note that encrypted keys loaded into an SSH agent can still be used when this option is set.

    - host_based_auth (`bool`) – (optional) Whether or not to allow host-based authentication. By default, host-based authentication is enabled if client host keys are made available.

    - public_key_auth (`bool`) – (optional) Whether or not to allow public key authentication. By default, public key authentication is enabled if client keys are made available.

    - kbdint_auth (`bool`) – (optional) Whether or not to allow keyboard-interactive authentication. By default, keyboard-interactive authentication is enabled if a password is specified or if callbacks to respond to challenges are made available.

    - password_auth (`bool`) – (optional) Whether or not to allow password authentication. By default, password authentication is enabled if a password is specified or if callbacks to provide a password are made availble.

    - 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_kex (`bool`) – (optional) Whether or not to allow GSS key exchange. By default, GSS key exchange is enabled.

    - gss_auth (`bool`) – (optional) Whether or not to allow GSS authentication. By default, GSS authentication is enabled.

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

    - preferred_auth (`str` or `list` of `str`) – A list of authentication methods the client should attempt to use in order of preference. By default, the preferred list is gssapi-keyex, gssapi-with-mic, hostbased, publickey, keyboard-interactive, and then password. This list may be limited by which auth methods are implemented by the client and which methods the server accepts.

    - disable_trivial_auth (`bool`) – (optional) Whether or not to allow “trivial” forms of auth where the client is not actually challenged for credentials. Setting this will cause the connection to fail if a server does not perform some non-trivial form of auth during the initial SSH handshake. If not specified, all forms of auth supported by the server are allowed, including none.

    - agent_path (`str`) – (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 this argument is explicitly set to `None`, an ssh-agent will not be used.

    - agent_identities (see Specifying public keys and Specifying certificates) – (optional) A list of identities used to restrict which SSH agent keys may be used. These may be specified as byte strings in binary SSH format or as public keys or certificates (see Specifying public keys and Specifying certificates). If set to `None`, all keys loaded into the SSH agent will be made available for use. This is the default.

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

    - pkcs11_provider (`str`) – (optional) The path of a shared library which should be used as a PKCS#11 provider for accessing keys on PIV security tokens. By default, no local security tokens will be accessed.

    - pkcs11_pin (`str`) –

      (optional) The PIN to use when accessing security tokens via PKCS#11.

      > Note

      > If your application opens multiple SSH connections using PKCS#11 keys, you should consider calling `load_pkcs11_keys()` explicitly instead of using these arguments. This allows you to pay the cost of loading the key information from the security tokens only once. You can then pass the returned keys via the `client_keys` argument to any calls that need them.

      > Calling `load_pkcs11_keys()` explicitly also gives you the ability to load keys from multiple tokens with different PINs and to select which tokens to load keys from and which keys on those tokens to load.

    - 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 (`str` or `list` of `str`) – (optional) A list of allowed key exchange algorithms in the SSH handshake, taken from key exchange algorithms.

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

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

    - compression_algs (`str` or `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 (`str` or `list` of `str`) – (optional) A list of public key signature algorithms to use during the SSH handshake, taken from signature algorithms.

    - rekey_bytes (see Specifying byte counts) – (optional) The number of bytes which can be sent before the SSH session key is renegotiated. This defaults to 1 GB.

    - rekey_seconds (see Specifying time intervals) – (optional) The maximum time in seconds before the SSH session key is renegotiated. This defaults to 1 hour.

    - connect_timeout (see Specifying time intervals) – (optional) The maximum time in seconds allowed to complete an outbound SSH connection. This includes the time to establish the TCP connection and the time to perform the initial SSH protocol handshake, key exchange, and authentication. This is disabled by default, relying on the system’s default TCP connect timeout and AsyncSSH’s login timeout.

    - login_timeout (see Specifying time intervals) –

      (optional) The maximum time in seconds allowed for authentication to complete, defaulting to 2 minutes. Setting this to 0 will disable the login timeout.

      > Note

      > This timeout only applies after the SSH TCP connection is established. To set a timeout which includes establishing the TCP connection, use the `connect_timeout` argument above.

    - keepalive_interval (see Specifying time intervals) – (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.

    - command (`str`) – (optional) The default remote command to execute on client sessions. An interactive shell is started if no command or subsystem is specified.

    - subsystem (`str`) – (optional) The default remote subsystem to start on client sessions.

    - env (`dict` with `str` keys and values) –

      (optional) The default environment variables to set for client sessions. 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.

    - send_env (`list` of `str`) – (optional) A list of environment variable names to pull from `os.environ` and set by default for client sessions. Wildcards patterns using `'*'` and `'?'` are allowed, and all variables with matching names will be sent with whatever value is set in the local environment. If a variable is present in both env and send_env, the value from env will be used.

    - request_pty (`bool`, `'force'`, or `'auto'`) – (optional) Whether or not to request a pseudo-terminal (PTY) by default for client sessions. This defaults to `True`, which means to request a PTY whenever the `term_type` is set. Other possible values include `False` to never request a PTY, `'force'` to always request a PTY even without `term_type` being set, or `'auto'` to request a TTY when `term_type` is set but only when starting an interactive shell.

    - term_type (`str`) – (optional) The default terminal type to set for client sessions.

    - 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 to set for client sessions.

    - term_modes (`dict` with `int` keys and values) – (optional) POSIX terminal modes to set for client sessions, where keys are taken from POSIX terminal modes with values defined in section 8 of RFC 4254.

    - x11_forwarding (`bool` or `'ignore_failure'`) – (optional) Whether or not to request X11 forwarding for client sessions, defaulting to `False`. If set to `True`, X11 forwarding will be requested and a failure will raise `ChannelOpenError`. It can also be set to `'ignore_failure'` to attempt X11 forwarding but ignore failures.

    - 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` or `None`) – (optional) The default Unicode encoding to use for data exchanged on client sessions.

    - errors (`str`) – (optional) The default error handling strategy to apply on Unicode encode/decode errors.

    - window (`int`) – (optional) The default receive window size to set for client sessions.

    - max_pktsize (`int`) – (optional) The default maximum packet size to set for client sessions.

    - config (`list` of `str`) –

      (optional) Paths to OpenSSH client configuration files to load. This configuration will be used as a fallback to override the defaults for settings which are not explcitly specified using AsyncSSH’s configuration options.

      > Note

      > Specifying configuration files when creating an `SSHClientConnectionOptions` object will cause the config file to be read and parsed at the time of creation of the object, including evaluation of any conditional blocks. If you want the config to be parsed for every new connection, this argument should be added to the connect or listen calls instead. However, if you want to save the parsing overhead and your configuration doesn’t depend on conditions that would change between calls, this argument may be an option.

    - options (`SSHClientConnectionOptions`) – (optional) A previous set of options to use as the base to incrementally build up a configuration. When an option is not explicitly specified, its value will be pulled from this options object (if present) before falling back to the default value.

### 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` returning `SSHServerConnection`) – A `callable` which returns an `SSHServer` object that will be created for each new connection.

    - proxy_command (`str` or `list` of `str`) – (optional) A string or list of strings specifying a command and arguments to run when using `connect_reverse()` to make a reverse direction connection to an SSH client. Data will be forwarded to this process over stdin/stdout instead of opening a TCP connection. If specified as a string, standard shell quoting will be applied when splitting the command and its arguments.

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

    - server_host_certs (see Specifying certificates) – (optional) A list of optional certificates which can be paired with the provided server host keys.

    - passphrase (`str` or `bytes`) – (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.

    - host_based_auth (`bool`) – (optional) Whether or not to allow host-based authentication. By default, host-based authentication is enabled if known client host keys are specified or if callbacks to validate client host keys are made available.

    - public_key_auth (`bool`) – (optional) Whether or not to allow public key authentication. By default, public key authentication is enabled if authorized client keys are specified or if callbacks to validate client keys are made available.

    - kbdint_auth (`bool`) – (optional) Whether or not to allow keyboard-interactive authentication. By default, keyboard-interactive authentication is enabled if the callbacks to generate challenges are made available.

    - password_auth (`bool`) – (optional) Whether or not to allow password authentication. By default, password authentication is enabled if callbacks to validate a password are made available.

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

    - gss_kex (`bool`) – (optional) Whether or not to allow GSS key exchange. By default, GSS key exchange is enabled.

    - gss_auth (`bool`) – (optional) Whether or not to allow GSS authentication. By default, GSS authentication is enabled.

    - 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_echo (`bool`) – (bool) Whether or not to echo completed input lines when they are entered, rather than waiting for the application to read and echo them, defaulting to `True`. Setting this to `False` and performing the echo in the application can better synchronize input and output, especially when there are input prompts.

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

    - max_line_length (`int`) – (int) The maximum number of characters allowed in an input line when the line editor is enabled, defaulting to 1024

    - rdns_lookup (`bool`) – (optional) Whether or not to perform reverse DNS lookups on the client’s IP address to enable hostname-based matches in authorized key file “from” options and “Match Host” config options, defaulting to `False`.

    - 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` or `None`) – (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.

    - sftp_version (`int`) – (optional) The maximum version of the SFTP protocol to support, currently either 3 or 4, defaulting to 3.

    - 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 (`str` or `list` of `str`) – (optional) A list of allowed key exchange algorithms in the SSH handshake, taken from key exchange algorithms

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

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

    - compression_algs (`str` or `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 (`str` or `list` of `str`) – (optional) A list of public key signature algorithms to use during the SSH handshake, taken from signature algorithms

    - rekey_bytes (see Specifying byte counts) – (optional) The number of bytes which can be sent before the SSH session key is renegotiated, defaulting to 1 GB

    - rekey_seconds (see Specifying time intervals) – (optional) The maximum time in seconds before the SSH session key is renegotiated, defaulting to 1 hour

    - connect_timeout (see Specifying time intervals) – (optional) The maximum time in seconds allowed to complete an outbound SSH connection. This includes the time to establish the TCP connection and the time to perform the initial SSH protocol handshake, key exchange, and authentication. This is disabled by default, relying on the system’s default TCP connect timeout and AsyncSSH’s login timeout.

    - login_timeout (see Specifying time intervals) –

      (optional) The maximum time in seconds allowed for authentication to complete, defaulting to 2 minutes. Setting this to 0 will disable the login timeout.

      > Note

      > This timeout only applies after the SSH TCP connection is established. To set a timeout which includes establishing the TCP connection, use the `connect_timeout` argument above.

    - keepalive_interval (see Specifying time intervals) – (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.

    - tcp_keepalive – (optional) Whether or not to enable keepalive probes at the TCP level to detect broken connections, defaulting to `True`

    - config (`list` of `str`) –

      (optional) Paths to OpenSSH server configuration files to load. This configuration will be used as a fallback to override the defaults for settings which are not explcitly specified using AsyncSSH’s configuration options.

      > Note

      > Specifying configuration files when creating an `SSHServerConnectionOptions` object will cause the config file to be read and parsed at the time of creation of the object, including evaluation of any conditional blocks. If you want the config to be parsed for every new connection, this argument should be added to the connect or listen calls instead. However, if you want to save the parsing overhead and your configuration doesn’t depend on conditions that would change between calls, this argument may be an option.

    - options (`SSHServerConnectionOptions`) – (optional) A previous set of options to use as the base to incrementally build up a configuration. When an option is not explicitly specified, its value will be pulled from this options object (if present) before falling back to the default value.

## 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

    A mapping containing the environment set by the client

  command

    The command the client requested to execute, if any

    If the client did not request that a command be executed, this property will be set to `None`.

  subsystem

    The subsystem the client requested to open, if any

    If the client did not request that a subsystem be opened, this property will be set to `None`.

  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, sftp_version, allow_scp)

  SSH server process handler

  Server process attributes |
  --- | ---

  channel

    The channel associated with the process

  logger

    The logger associated with the process

  command

    The command the client requested to execute, if any

    If the client did not request that a command be executed, this property will be set to `None`.

  subsystem

    The subsystem the client requested to open, if any

    If the client did not request that a subsystem be opened, this property will be set to `None`.

  env

    A mapping containing the environment set by the client

  term_type

    The terminal type set by the client

    If the client didn’t request a pseudo-terminal, this property will be set to `None`.

  term_size

    The terminal size set by the client

    This property contains a tuple of four `int` values representing the width and height of the terminal in characters followed by the width and height of the terminal in pixels. If the client hasn’t set terminal size information, the values will be set to zero.

  term_modes

    A mapping containing the TTY modes set by the client

    If the client didn’t request a pseudo-terminal, this property will be set to an empty mapping.

  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.

  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 | `dict` 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.

    Parameters

      signal (`str`) – The name of the signal received

  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_terminal_modes()

    Return the TTY modes for this session

    This method returns a mapping of all the POSIX terminal modes set by the client when the session was opened. If the client didn’t request a pseudo-terminal, this method will return an empty mapping. 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 mapping containing all the POSIX terminal modes set by the client or an empty mapping if no pseudo-terminal was requested

  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

### SSHAcceptor

class asyncssh.SSHAcceptor

  SSH acceptor

  This class in a wrapper around an `asyncio.Server` listener which provides the ability to update the the set of SSH client or server connection options associated wtih that listener. This is accomplished by calling the `update()` method, which takes the same keyword arguments as the `SSHClientConnectionOptions` and `SSHServerConnectionOptions` classes.

  In addition, this class supports all of the methods supported by `asyncio.Server` to control accepting of new connections.

  update(**kwargs)

    Update options on an SSH listener

    Acceptors started by `listen()` support options defined in `SSHServerConnectionOptions`. Acceptors started by `listen_reverse()` support options defined in `SSHClientConnectionOptions`.

    Changes apply only to SSH client/server connections accepted after the change is made. Previously accepted connections will continue to use the options set when they were accepted.

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

  feed_data(data)

    Feed data to the associated session

    This method feeds data to the SSH session associated with this stream, providing compatibility with the `feed_data()` method on `asyncio.StreamReader`. This is mostly useful for testing.

  feed_eof()

    Feed EOF to the associated session

    This method feeds an end-of-file indication to the SSH session associated with this stream, providing compatibility with the `feed_eof()` method on `asyncio.StreamReader`. This is mostly useful for testing.

  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

  version

    SFTP version associated with this SFTP session

  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=SFTP_BLOCK_SIZE, max_requests=_MAX_SFTP_REQUESTS)

    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.

    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.

    Most applications should be able to use this method regardless of the version of the SFTP protocol negotiated with the SFTP server. A conversion from the pflags_or_mode values to the SFTPv5/v6 flag values will happen automaitcally. However, if an application wishes to set flags only available in SFTPv5/v6, the `open56()` method may be used to specify these flags explicitly.

    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

  open56(path, desired_access=ACE4_READ_DATA | ACE4_READ_ATTRIBUTES, flags=FXF_OPEN_EXISTING, attrs=SFTPAttrs(), encoding='utf-8', errors='strict', block_size=SFTP_BLOCK_SIZE, max_requests=_MAX_SFTP_REQUESTS)

    Open a remote file using SFTP v5/v6 flags

    This method is very similar to `open()`, but the pflags_or_mode argument is replaced with SFTPv5/v6 desired_access and flags arguments. Most applications can continue to use `open()` even when talking to an SFTPv5/v6 server and the translation of the flags will happen automatically. However, if an application wishes to set flags only available in SFTPv5/v6, this method provides that capability.

    The following desired_access flags can be specified:

    > ACE4_READ_DATA
    > ACE4_WRITE_DATA
    > ACE4_APPEND_DATA
    > ACE4_READ_ATTRIBUTES
    > ACE4_WRITE_ATTRIBUTES

    The following flags can be specified:

    > FXF_CREATE_NEW
    > FXF_CREATE_TRUNCATE
    > FXF_OPEN_EXISTING
    > FXF_OPEN_OR_CREATE
    > FXF_TRUNCATE_EXISTING
    > FXF_APPEND_DATA
    > FXF_APPEND_DATA_ATOMIC
    > FXF_BLOCK_READ
    > FXF_BLOCK_WRITE
    > FXF_BLOCK_DELETE
    > FXF_BLOCK_ADVISORY (SFTPv6)
    > FXF_NOFOLLOW (SFTPv6)
    > FXF_DELETE_ON_CLOSE (SFTPv6)
    > FXF_ACCESS_AUDIT_ALARM_INFO (SFTPv6)
    > FXF_ACCESS_BACKUP (SFTPv6)
    > FXF_BACKUP_STREAM (SFTPv6)
    > FXF_OVERRIDE_OWNER (SFTPv6)

    At this time, FXF_TEXT_MODE is not supported. Also, servers may support only a subset of these flags. For example, the AsyncSSH SFTP server doesn’t currently support ACLs, file locking, or most of the SFTPv6 open flags, but support for some of these may be added over time.

    Parameters

      - path (`PurePath`, `str`, or `bytes`) – The name of the remote file to open

      - desired_access (int) – (optional) The access mode to use for the remote file (see above)

      - flags (int) – (optional) The access flags 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, flags=0)

    Rename a remote file, directory, or link

    This method renames a remote file, directory, or link.

    Note

    By default, this version of rename will not overwrite the new path if it already exists. However, this can be controlled using the `flags` argument, available in SFTPv5 and later. Whan a connection is negotiated to use an earliler version of SFTP and `flags` is set, this method will attempt to fall back to the OpenSSH “posix-rename” extension if it is available. That can also be invoked directly by calling `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

      - flags (`int`) – (optional) A combination of the `FXR_OVERWRITE`, `FXR_ATOMIC`, and `FXR_NATIVE` flags to specify what happens when `newpath` already exists, defaulting to not allowing the overwrite (SFTPv5 and later)

    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. If it is not available but the server supports SFTPv5 or later, this method will attempt to send the standard SFTP rename request with the `FXR_OVERWRITE` flag set.

    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, *compose_paths, check=1)

    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

      - compose_paths (`PurePath`, `str`, or `bytes`) – (optional) A list of additional paths that the server should compose with `path` before canonicalizing it

      - check (int) – (optional) One of `FXRP_NO_CHECK`, `FXRP_STAT_IF_EXISTS`, and `FXRP_STAT_ALWAYS`, specifying when to perform a stat operation on the resulting path, defaulting to `FXRP_NO_CHECK`

    Returns

      The canonical path as a `str` or `bytes`, matching the type used to pass in the path if `check` is set to `FXRP_NO_CHECK`, or an `SFTPName` containing the canonical path name and attributes otherwise

    Raises

      `SFTPError` if the server returns an error

  File attribute access methods |
  --- | ---

  async stat(path, flags=2147484157)

    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

      - flags (`int`) – (optional) Flags indicating attributes of interest (SFTPv4 only)

    Returns

      An `SFTPAttrs` containing the file attributes

    Raises

      `SFTPError` if the server returns an error

  async lstat(path, flags=2147484157)

    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

      - flags (`int`) – (optional) Flags indicating attributes of interest (SFTPv4 only)

    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 or owner, gid or group)

    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

      - owner (`str`) – The new owner to assign to the file (SFTPv4 only)

      - group (`str`) – The new group to assign to the file (SFTPv4 only)

    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, ns=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 neither `times` nor ‘`ns` is 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

      - ns (tuple of two `int` values) – (optional) The new access and modify times, as nanoseconds 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 getatime_ns(path)

    Return the last access time of a remote file or directory

    The time returned is nanoseconds since the epoch.

    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 getcrtime_ns(path)

    Return the creation time of a remote file or directory

    The time returned is nanoseconds since the epoch.

    Parameters

      path (`PurePath`, `str`, or `bytes`) – The remote path to check

    Raises

      `SFTPError` if the server returns an error

  async getcrtime(path)

    Return the creation time of a remote file or directory (SFTPv4 only)

    Parameters

      path (`PurePath`, `str`, or `bytes`) – The remote path to check

    Raises

      `SFTPError` if the server returns an error

  async getmtime_ns(path)

    Return the last modification time of a remote file or directory

    The time returned is nanoseconds since the epoch.

    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 makedirs(path, attrs=SFTPAttrs())

    Create a remote directory with the specified attributes

    This method creates a remote directory at the specified path similar to `mkdir()`, but it will also create any intermediate directories which don’t yet exist.

    If the target directory already exists and exist_ok is set to `False`, this method will raise an error.

    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 or any intermediate directories

      - exist_ok (`bool`) – (optional) Whether or not to raise an error if thet target directory already exists

    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 rmtree(path, ignore_errors=False, onerror=None)

    Recursively delete a directory tree

    This method removes all the files in a directory tree.

    If ignore_errors is set, errors are ignored. Otherwise, if onerror is set, it will be called with arguments of the function which failed, the path it failed on, and exception information returns by `sys.exc_info()`.

    If follow_symlinks is set, files or directories pointed at by symlinks (and their subdirectories, if any) will be removed in addition to the links pointing at them.

    Parameters

      - path (`PurePath`, `str`, or `bytes`) – The path of the parent directory to remove

      - ignore_errors (`bool`) – (optional) Whether or not to ignore errors during the remove

      - onerror (`callable`) – (optional) A function to call when errors occur

    Raises

      `SFTPError` if the server returns an error

  async scandir(path='.')

    Return an async iterator of the contents of a remote directory

    This method reads the contents of a directory, returning the names and attributes of what is contained there as an async iterator. 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

      An async iterator of `SFTPName` entries, with path names matching the type used to pass in the path

    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, as a `str` or `bytes` 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(flags=2147484157)

    Return file attributes of the remote file

    This method queries file attributes of the currently open file.

    Parameters

      flags (`int`) – (optional) Flags indicating attributes of interest (SFTPv4 or later)

    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 or owner, gid or group)

    Change the owner user and group of the remote file

    This method changes the user and group 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

      - owner (`str`) – The new owner to assign to the file (SFTPv4 only)

      - group (`str`) – The new group to assign to the file (SFTPv4 only)

    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, ns=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

      - ns (tuple of two `int` values) – (optional) The new access and modify times, as nanoseconds relative to the UNIX epoch

    Raises

      `SFTPError` if the server returns an error

  async lock(offset, length, flags)

    Acquire a byte range lock on the remote file

  async unlock(offset, length)

    Release a byte range lock on the remote file

  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

  open56(path, desired_access, flags, attrs)

    Open a file to serve to a remote client (SFTPv5 and later)

    This method returns a file object which can be used to read and write data and get and set file attributes.

    Supported desired_access bits include `ACE4_READ_DATA`, `ACE4_WRITE_DATA`, `ACE4_APPEND_DATA`, `ACE4_READ_ATTRIBUTES`, and `ACE4_WRITE_ATTRIBUTES`.

    Supported disposition bits in flags and their meanings are:

    > Disposition | Description
    > --- | ---
    > FXF_OPEN_EXISTING | Open an existing file
    > FXF_OPEN_OR_CREATE | Open an existing file or create a new one
    > FXF_CREATE_NEW | Create a new file
    > FXF_CREATE_TRUNCATE | Create a new file or truncate an existing one
    > FXF_TRUNCATE_EXISTING | Truncate an existing file

    Other supported flag bits are:

    > Flag | Description
    > --- | ---
    > FXF_APPEND_DATA | Append data writes to the end of the file

    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

      - desired_access (`int`) – The access mode to use for the file (see above)

      - flags (`int`) – The access flags 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

  lock(file_obj, offset, length, flags)

    Acquire a byte range lock on an open file

  unlock(file_obj, offset, length)

    Release a byte range lock on an open file

  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 or `SFTPName` objects containing file names and attributes

    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
  > --- | --- | ---
  > type | File type (SFTPv4+) | byte
  > size | File size in bytes | uint64
  > alloc_size | Allocation file size in bytes (SFTPv6+) | uint64
  > uid | User id of file owner | uint32
  > gid | Group id of file owner | uint32
  > owner | User name of file owner (SFTPv4+) | string
  > group | Group name of file owner (SFTPv4+) | string
  > permissions | Bit mask of POSIX file permissions | uint32
  > atime | Last access time, UNIX epoch seconds | uint64
  > atime_ns | Last access time, nanoseconds (SFTPv4+) | uint32
  > crtime | Creation time, UNIX epoch seconds (SFTPv4+) | uint64
  > crtime_ns | Creation time, nanoseconds (SFTPv4+) | uint32
  > mtime | Last modify time, UNIX epoch seconds | uint64
  > mtime_ns | Last modify time, nanoseconds (SFTPv4+) | uint32
  > ctime | Last change time, UNIX epoch seconds (SFTPv6+) | uint64
  > ctime_ns | Last change time, nanoseconds (SFTPv6+) | uint32
  > acl | Access control list for file (SFTPv4+) | bytes
  > attrib_bits | Attribute bits set for file (SFTPv5+) | uint32
  > attrib_valid | Valid attribute bits for file (SFTPv5+) | uint32
  > text_hint | Text/binary hint for file (SFTPv6+) | byte
  > mime_type | MIME type for file (SFTPv6+) | string
  > nlink | Link count for file (SFTPv6+) | uint32
  > untrans_name | Untranslated name for file (SFTPv6+) | bytes

  Extended attributes can also be added via a field named `extended` which is a list of bytes 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.

Instead of passing tuples of keys and certificates or relying on file naming conventions for certificates, you also have the option of providing a list of keys and a seperate list of certificates. In this case, AsyncSSH will automatically match up the keys with their associated certificates when they are present.

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 time interval described in Specifying time intervals which is interpreted as a relative time from now. This value can be negative to refer to times in the past or positive to refer to times 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 (`str` or `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 (`str` or `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=(), 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 (`str` or `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 (`str`, `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=(), 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 (`str` or `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 (`str`, `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=(), 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

  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, format_name='openssh')

    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.

      - format_name (`str`) – (optional) The format to export the certificate in.

  append_certificate(filename, format_name='openssh')

    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.

      - format_name (`str`) – (optional) The format to export the certificate in.

### 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, certlist=(), skip_public=False, ignore_encrypted=False)

  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.

    - certlist (see Specifying certificates) – (optional) A list of certificates to attempt to pair with the provided list of private keys.

    - skip_public (`bool`) – (optional) An internal parameter used to skip public keys and certificates when IdentitiesOnly and IdentityFile are used to specify a mixture of private and public 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_pkcs11_keys

asyncssh.load_pkcs11_keys(provider, pin=None, *, load_certs=True, token_label=None, token_serial=None, key_label=None, key_id=None)

  Report that PKCS#11 support is not available

### 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(identities=None)

    Request the available client keys

    This method is a coroutine which returns a list of client keys available in the ssh-agent.

    Parameters

      identities – (optional) A list of allowed byte string identities to return. If empty, all identities on the SSH agent will be returned.

    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

## Config File Support

AsyncSSH has partial support for parsing OpenSSH client and server configuration files (documented in the “ssh_config” and “sshd_config” UNIX man pages, respectively). Not all OpenSSH configuration options are applicable, so unsupported options are simply ignored. See below for the OpenSSH config options that AsyncSSH supports.

AsyncSSH also supports “Host” and “Match” conditional blocks. As with the config options themselves, not all match criteria are supported, but the supported criteria should function similar to OpenSSH.

AsyncSSH also supports the “Include” directive, to allow one config file trigger the loading of others.

### Supported client config options

The following OpenSSH client config options are currently supported:

> AddressFamily
> BindAddress
> CASignatureAlgorithms
> CertificateFile
> ChallengeResponseAuthentication
> Ciphers
> Compression
> ConnectTimeout
> EnableSSHKeySign
> ForwardAgent
> ForwardX11Trusted
> GlobalKnownHostsFile
> GSSAPIAuthentication
> GSSAPIDelegateCredentials
> GSSAPIKeyExchange
> HostbasedAuthentication
> HostKeyAlgorithms
> HostKeyAlias
> Hostname
> IdentityAgent
> IdentityFile
> KbdInteractiveAuthentication
> KexAlgorithms
> MACs
> PasswordAuthentication
> PreferredAuthentications
> Port
> ProxyCommand
> ProxyJump
> PubkeyAuthentication
> RekeyLimit
> RemoteCommand
> RequestTTY
> SendEnv
> ServerAliveCountMax
> ServerAliveInterval
> SetEnv
> TCPKeepAlive
> User
> UserKnownHostsFile

For the “Match” conditional, the following criteria are currently supported:

> All
> Exec
> Host
> LocalUser
> OriginalHost
> User

> Warning

> When instantiating `SSHClientConnectionOptions` objects manually within an asyncio task, you may block the event loop if the options refer to a config file with “Match Exec” directives which don’t return immediate results. In such cases, the asyncio `run_in_executor()` function should be used. This is taken care of automatically when options objects are created by AsyncSSH APIs such as `connect()` and `listen()`.

The following client config token expansions are currently supported:

Token | Expansion
--- | ---
%% | Literal ‘%’
%C | SHA-1 Hash of connection info (local host, host, port, user)
%d | Local user’s home directory
%h | Remote host
%i | Local uid (UNIX-only)
%L | Short local hostname (without the domain)
%l | Local hostname (including the domain)
%n | Original remote host
%p | Remote port
%r | Remote username
%u | Local username

These expansions are available in the values of the following config options:

> CertificateFile
> IdentityAgent
> IdentityFile
> RemoteCommand

### Supported server config options

The following OpenSSH server config options are currently supported:

> AddressFamily
> AuthorizedKeysFile
> AllowAgentForwarding
> BindAddress
> CASignatureAlgorithms
> ChallengeResponseAuthentication
> Ciphers
> ClientAliveCountMax
> ClientAliveInterval
> Compression
> GSSAPIAuthentication
> GSSAPIKeyExchange
> HostbasedAuthentication
> HostCertificate
> HostKey
> KbdInteractiveAuthentication
> KexAlgorithms
> LoginGraceTime
> MACs
> PasswordAuthentication
> PermitTTY
> Port
> ProxyCommand
> PubkeyAuthentication
> RekeyLimit
> TCPKeepAlive
> UseDNS

For the “Match” conditional, the following criteria are currently supported:

> All
> Exec
> Address
> Host
> LocalAddress
> LocalPort
> User

> Warning

> When instantiating `SSHServerConnectionOptions` objects manually within an asyncio task, you may block the event loop if the options refer to a config file with “Match Exec” directives which don’t return immediate results. In such cases, the asyncio `run_in_executor()` function should be used. This is taken care of automatically when options objects are created by AsyncSSH APIs such as `connect()` and `listen()`.

The following server config token expansions are currently supported:

Token | Expansion
--- | ---
%% | Literal ‘%’
%u | Username

These expansions are available in the values of the following config options:

> AuthorizedKeysFile

### Specifying byte counts

A byte count may be passed into AsyncSSH as an integer value, or as a string made up of a mix of numbers followed by an optional letter of ‘k’, ‘m’, or ‘g’, indicating kilobytes, megabytes, or gigabytes, respectively. Multiple of these values can be included. For instance, ‘2.5m’ means 2.5 megabytes. This could also be expressed as ‘2m512k’ or ‘2560k’.

### Specifying time intervals

A time interval may be passed into AsyncSSH as an integer or float value, or as a string made up of a mix of positive or negative numbers and the letters ‘w’, ‘d’, ‘h’, ‘m’, and ‘s’, indicating 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.

## 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 or list of files containing known hosts, a byte string containing data in known hosts format, or an `SSHKnownHosts` object which was previously imported from a string by calling `import_known_hosts()` or read from files 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(filelist)

  Read SSH known hosts from a file or list of files

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

  Parameters

    filelist (`str` or `list` of `str`) – The file or list of files 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 or list of files to read authorized keys from or an `SSHAuthorizedKeys` object which was previously imported from a string by calling `import_authorized_keys()` or read from files 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(filelist)

  Read SSH authorized keys from a file or list of files

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

  Parameters

    filelist – The file or list of files 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

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

  SFTP invalid handle (SFTPv4+)

  This exception is raised when the handle provided is invalid.

  Parameters

    - reason (`str`) – Details about the invalid handle

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

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

  SFTP no such path (SFTPv4+)

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

  Parameters

    - reason (`str`) – Details about the missing path

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

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

  SFTP file already exists (SFTPv4+)

  This exception is raised when the requested file already exists.

  Parameters

    - reason (`str`) – Details about the existing file

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

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

  SFTP write protect (SFTPv4+)

  This exception is raised when a write is attempted to a file on read-only or write protected media.

  Parameters

    - reason (`str`) – Details about the requested file

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

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

  SFTP no media (SFTPv4+)

  This exception is raised when there is no media in the requested drive.

  Parameters

    - reason (`str`) – Details about the requested drive

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

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

  SFTP no space on filesystem (SFTPv5+)

  This exception is raised when there is no space available on the filesystem a file is being written to.

  Parameters

    - reason (`str`) – Details about the filesystem which has filled up

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

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

  SFTP quota exceeded (SFTPv5+)

  This exception is raised when the user’s storage quota is exceeded.

  Parameters

    - reason (`str`) – Details about the exceeded quota

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

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

  SFTP unknown principal (SFTPv5+)

  This exception is raised when a file owner or group is not reocgnized.

  Parameters

    - reason (`str`) – Details about the unknown principal

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

    - unknown_names (list of `str`) – (optional) A list of unknown principal names

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

  SFTP lock conflict (SFTPv5+)

  This exception is raised when a requested lock is held by another process.

  Parameters

    - reason (`str`) – Details about the conflicting lock

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

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

  SFTP directory not empty (SFTPv6+)

  This exception is raised when a directory is not empty.

  Parameters

    - reason (`str`) – Details about the non-empty directory

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

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

  SFTP not a directory (SFTPv6+)

  This exception is raised when a specified file is not a directory where one was expected.

  Parameters

    - reason (`str`) – Details about the file expected to be a directory

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

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

  SFTP invalid filename (SFTPv6+)

  This exception is raised when a filename is not valid.

  Parameters

    - reason (`str`) – Details about the invalid filename

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

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

  SFTP link loop (SFTPv6+)

  This exception is raised when a symbolic link loop is detected.

  Parameters

    - reason (`str`) – Details about the link loop

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

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

  SFTP cannot delete (SFTPv6+)

  This exception is raised when a file cannot be deleted.

  Parameters

    - reason (`str`) – Details about the undeletable file

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

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

  SFTP invalid parameter (SFTPv6+)

  This exception is raised when paramters in a request are out of range or incompatible with one another.

  Parameters

    - reason (`str`) – Details about the invalid paramter

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

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

  SFTP file is a directory (SFTPv6+)

  This exception is raised when a specified file is a directory where one isn’t allowed.

  Parameters

    - reason (`str`) – Details about the unexpected directory

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

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

  SFTP byte range lock conflict (SFTPv6+)

  This exception is raised when a read or write request overlaps a byte range lock held by another process.

  Parameters

    - reason (`str`) – Details about the conflicting byte range lock

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

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

  SFTP byte range lock refused (SFTPv6+)

  This exception is raised when a request for a byte range lock was refused.

  Parameters

    - reason (`str`) – Details about the refused byte range lock

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

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

  SFTP delete pending (SFTPv6+)

  This exception is raised when an operation was attempted on a file for which a delete operation is pending. another process.

  Parameters

    - reason (`str`) – Details about the file being deleted

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

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

  SFTP file corrupt (SFTPv6+)

  This exception is raised when filesystem corruption is detected.

  Parameters

    - reason (`str`) – Details about the corrupted filesystem

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

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

  SFTP owner invalid (SFTPv6+)

  This exception is raised when a principal cannot be assigned as the owner of a file.

  Parameters

    - reason (`str`) – Details about the principal being set as a file’s owner

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

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

  SFTP group invalid (SFTPv6+)

  This exception is raised when a principal cannot be assigned as the primary group of a file.

  Parameters

    - reason (`str`) – Details about the principal being set as a file’s group

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

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

  SFTP no matching byte range lock (SFTPv6+)

  This exception is raised when an unlock is requested for a byte range lock which is not currently held.

  Parameters

    - reason (`str`) – Details about the byte range lock being released

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

### ConfigParseError

exception asyncssh.ConfigParseError

  Configuration parsing exception

## Supported Algorithms

Algorithms can be specified as either an list of exact algorithm names or as a string of comma-separated algorithm names that may optionally include wildcards. A ‘*’ in a name matches zero or more characters and a ‘?’ matches exactly one character.

When specifying algorithms as a string, it can also be prefixed with ‘^’ to insert the matching algorithms in front of the default algorithms of that type, a ‘+’ to insert the matching algorithms after the default algorithms, or a ‘-’ to return the default algorithms with the matching algorithms removed.

### Key exchange algorithms

The following are the default 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-group14-sha256
> gss-group15-sha512
> gss-group16-sha512
> gss-group17-sha512
> gss-group18-sha512
> gss-group14-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-group14-sha256
> diffie-hellman-group15-sha512
> diffie-hellman-group16-sha512
> diffie-hellman-group17-sha512
> diffie-hellman-group18-sha512
> diffie-hellman-group14-sha256@ssh.com
> diffie-hellman-group14-sha1
> rsa2048-sha256

The following key exchange algorithms are supported by AsyncSSH, but disabled by default:

> gss-gex-sha1
> gss-group1-sha1
> diffie-hellman-group-exchange-sha224@ssh.com
> diffie-hellman-group-exchange-sha384@ssh.com
> diffie-hellman-group-exchange-sha512@ssh.com
> diffie-hellman-group-exchange-sha1
> diffie-hellman-group14-sha224@ssh.com
> diffie-hellman-group15-sha256@ssh.com
> diffie-hellman-group15-sha384@ssh.com
> diffie-hellman-group16-sha384@ssh.com
> diffie-hellman-group16-sha512@ssh.com
> diffie-hellman-group18-sha512@ssh.com
> diffie-hellman-group1-sha1
> 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 default encryption algorithms currently supported by AsyncSSH:

> chacha20-poly1305@openssh.com
> aes256-gcm@openssh.com
> aes128-gcm@openssh.com
> aes256-ctr
> aes192-ctr
> aes128-ctr

The following encryption algorithms are supported by AsyncSSH, but disabled by default:

> aes256-cbc
> aes192-cbc
> aes128-cbc
> 3des-cbc
> blowfish-cbc
> cast128-cbc
> seed-cbc@ssh.com
> 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 default 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
> umac-64@openssh.com
> umac-128@openssh.com
> hmac-sha2-256
> hmac-sha2-512
> hmac-sha1
> hmac-sha256-2@ssh.com
> hmac-sha224@ssh.com
> hmac-sha256@ssh.com
> hmac-sha384@ssh.com
> hmac-sha512@ssh.com

The following MAC algorithms are supported by AsyncSSH, but disabled by default:

> 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
> 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 default compression algorithms currently supported by AsyncSSH:

> zlib@openssh.com
> none

The following compression algorithms are supported by AsyncSSH, but disabled by default:

> zlib

### Signature algorithms

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

> x509v3-ssh-ed25519
> x509v3-ssh-ed448
> 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
> 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-sha224@ssh.com
> ssh-rsa-sha256@ssh.com
> ssh-rsa-sha384@ssh.com
> ssh-rsa-sha512@ssh.com
> ssh-rsa

The following public key signature algorithms are supported by AsyncSSH, but disabled by default:

> x509v3-ssh-dss
> ssh-dss

### Public key & certificate algorithms

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

> x509v3-ssh-ed25519
> x509v3-ssh-ed448
> 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
> 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
> rsa-sha2-256-cert-v01@openssh.com
> rsa-sha2-512-cert-v01@openssh.com
> ssh-rsa-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-sha224@ssh.com
> ssh-rsa-sha256@ssh.com
> ssh-rsa-sha384@ssh.com
> ssh-rsa-sha512@ssh.com
> ssh-rsa

The following public key and certificate algorithms are supported by AsyncSSH, but disabled by default:

> x509v3-ssh-dss
> ssh-dss-cert-v01@openssh.com
> 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 section 9.1 of the SSH File Transfer Protocol Internet Draft can be specified as SFTP error codes:

Error code | Minimum SFTP version
--- | ---
FX_OK | 3
FX_EOF | 3
FX_NO_SUCH_FILE | 3
FX_PERMISSION_DENIED | 3
FX_FAILURE | 3
FX_BAD_MESSAGE | 3
FX_NO_CONNECTION | 3
FX_CONNECTION_LOST | 3
FX_OP_UNSUPPORTED | 3
FX_INVALID_HANDLE | 4
FX_NO_SUCH_PATH | 4
FX_FILE_ALREADY_EXISTS | 4
FX_WRITE_PROTECT | 4
FX_NO_MEDIA | 4
FX_NO_SPACE_ON_FILESYSTEM | 5
FX_QUOTA_EXCEEDED | 5
FX_UNKNOWN_PRINCIPAL | 5
FX_LOCK_CONFLICT | 5
FX_DIR_NOT_EMPTY | 6
FX_NOT_A_DIRECTORY | 6
FX_INVALID_FILENAME | 6
FX_LINK_LOOP | 6
FX_CANNOT_DELETE | 6
FX_INVALID_PARAMETER | 6
FX_FILE_IS_A_DIRECTORY | 6
FX_BYTE_RANGE_LOCK_CONFLICT | 6
FX_BYTE_RANGE_LOCK_REFUSED | 6
FX_DELETE_PENDING | 6
FX_FILE_CORRUPT | 6
FX_OWNER_INVALID | 6
FX_GROUP_INVALID | 6
FX_NO_MATCHING_BYTE_RANGE_LOCK | 6

### 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