Russh Documentation

Russh is a low-level Tokio-based SSH2 client and server implementation. It supports a wide range of SSH primitives including:

Port Forwarding

• direct-tcpip (local port forwarding)
• forward-tcpip (remote port forwarding)
• direct-streamlocal (local UNIX socket forwarding, client only)
• forward-streamlocal (remote UNIX socket forwarding)

Supported Ciphers

• chacha20-poly1305@openssh.com
• aes128-gcm@openssh.com, aes256-gcm@openssh.com
• aes128-ctr, aes192-ctr, aes256-ctr
• aes128-cbc, aes192-cbc, aes256-cbc, 3des-cbc

Key Exchanges

• curve25519-sha256@libssh.org
• diffie-hellman-group-sha1 (GEX)
• diffie-hellman-group1-sha1, diffie-hellman-group14-sha1
• diffie-hellman-group-sha256 (GEX), diffie-hellman-group14-sha256, diffie-hellman-group16-sha512
• ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521

MACs

• hmac-sha1, hmac-sha2-256, hmac-sha2-512
• hmac-sha1-etm@openssh.com, hmac-sha2-256-etm@openssh.com, hmac-sha2-512-etm@openssh.com

Authentication

• Host keys & Public key auth: ssh-ed25519, rsa-sha2-256, rsa-sha2-512, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521
• Methods: password, publickey, keyboard-interactive, none, and OpenSSH certificates.

To build an SSH server with Russh, you must implement the Server trait. This trait defines how new client handlers are created and how session errors are managed. Once implemented, you can use run_on_socket or run_on_address to start the server loop.

There are two primary patterns for accepting connections:

1. Automatic Management: Implement Server and use run_on_socket (if you have a TcpListener) or run_on_address (to bind to an address). Russh will handle the listener loop and connection lifecycle.
2. Manual Management: Accept connections yourself and pass them to run_stream to handle the SSH protocol for that specific stream.

#[async_trait::async_trait]
pub trait Server {
    type Handler: Handler + Send + 'static;

    /// Called when a new client connects.
    fn new_client(&mut self, peer_addr: Option<std::net::SocketAddr>) -> Self::Handler;

    /// Called when an active connection fails.
    fn handle_session_error(&mut self, _error: <Self::Handler as Handler>::Error) {}

    // ... run_on_socket and run_on_address methods
}

The Handler trait is the core of your SSH server logic. Each connected client gets its own instance of a type implementing Handler. You must implement this trait to respond to various SSH protocol events, such as authentication requests, channel openings, and data transfers.

Key event categories include:

• Authentication: auth_none, auth_password, auth_publickey, auth_openssh_certificate, and auth_keyboard_interactive.
• Channel Management: channel_open_session, channel_open_direct_tcpip, channel_close, and channel_eof.
• Data Handling: data (for incoming packets) and extended_data (for stderr/other streams).
• Requests: pty_request, shell_request, exec_request, and subsystem_request.

Note: For many request types (like pty_request or shell_request), you must explicitly communicate success or failure to the client by calling session.channel_success(channel) or session.channel_failure(channel) within the handler method.

#[cfg_attr(feature = "async-trait", async_trait::async_trait)]
pub trait Handler: Sized {
    type Error: From<crate::Error> + Send;

    // Example authentication method
    fn auth_password(
        &mut self,
        user: &str,
        password: &str,
    ) -> impl Future<Output = Result<Auth, Self::Error>> + Send;

    // Example channel request
    fn shell_request(
        &mut self,
        channel: ChannelId,
        session: &mut Session,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;

    // ... other methods
}