Struct Client 

pub struct Client {
    pub session: Arc<Handle<ClientHandler>>,
    /* private fields */
}

A ssh connection to a remote server.

After creating a Client by connecting to a remote host, use execute to send commands and receive results through the connections.

Examples

use bssh::ssh::tokio_client::{Client, AuthMethod, ServerCheckMethod};
#[tokio::main]
async fn main() -> Result<(), bssh::ssh::tokio_client::Error> {
    let mut client = Client::connect(
        ("10.10.10.2", 22),
        "root",
        AuthMethod::with_password("root"),
        ServerCheckMethod::NoCheck,
    ).await?;

    let result = client.execute("echo Hello SSH").await?;
    assert_eq!(result.stdout, "Hello SSH\n");
    assert_eq!(result.exit_status, 0);

    Ok(())
}

Fields

session: Arc<Handle<ClientHandler>>

Public access to the SSH session for jump host operations

Implementations

impl Client

pub async fn get_channel(&self) -> Result<Channel<Msg>, Error>

Get a new SSH channel for communication.

pub async fn open_direct_tcpip_channel<T: ToSocketAddrsWithHostname, S: Into<Option<SocketAddr>>>( &self, target: T, src: S, ) -> Result<Channel<Msg>, Error>

Open a TCP/IP forwarding channel.

This opens a direct-tcpip channel to the given target.

pub async fn execute_streaming( &self, command: &str, sender: Sender<CommandOutput>, ) -> Result<u32, Error>

Execute a remote command via the ssh connection with streaming output.

This method sends command output in real-time to the provided sender channel. Output is sent as CommandOutput::StdOut or CommandOutput::StdErr variants.

Returns only the exit status of the command. Stdout and stderr are streamed through the sender channel.

Make sure your commands don’t read from stdin and exit after bounded time.

Can be called multiple times, but every invocation is a new shell context. Thus cd, setting variables and alike have no effect on future invocations.

Backpressure Handling

If the channel fills up (receiver is slower than output production), this method will apply backpressure by blocking until space is available. This prevents unbounded memory growth but may slow down command execution for high-throughput commands.

Error Handling

• If the receiver drops the channel, this method will stop processing output and return the last known exit status.
• Command sanitization errors are propagated as CommandValidationFailed.

Arguments

• command - The command to execute
• sender - Channel sender for streaming output

Returns

The exit status of the command

pub async fn execute_with_sudo( &self, command: &str, sender: Sender<CommandOutput>, sudo_password: &SudoPassword, ) -> Result<u32, Error>

Execute a remote command with sudo password support.

This method handles automatic sudo password injection when sudo prompts are detected in the command output. It monitors both stdout and stderr for sudo password prompts and automatically sends the password when detected.

Arguments

• command - The command to execute (typically starts with sudo)
• sender - Channel sender for streaming output
• sudo_password - The sudo password to inject when prompted

Returns

The exit status of the command

Security

• Password is only sent when a sudo prompt is detected
• Password is never logged or included in error messages
• Detects sudo authentication failures and reports them appropriately

pub async fn execute( &self, command: &str, ) -> Result<CommandExecutedResult, Error>

Execute a remote command via the ssh connection.

Returns stdout, stderr and the exit code of the command, packaged in a CommandExecutedResult struct. If you need the stderr output interleaved within stdout, you should postfix the command with a redirection, e.g. echo foo 2>&1. If you dont want any output at all, use something like echo foo >/dev/null 2>&1.

Make sure your commands don’t read from stdin and exit after bounded time.

Can be called multiple times, but every invocation is a new shell context. Thus cd, setting variables and alike have no effect on future invocations.

pub async fn request_interactive_shell( &self, _term_type: &str, _width: u32, _height: u32, ) -> Result<Channel<Msg>, Error>

Request an interactive shell channel.

This method opens a new SSH channel suitable for interactive shell sessions. Note: This method no longer requests PTY directly. The PTY should be requested by the caller (e.g., PtySession) with appropriate terminal modes.

Arguments

• _term_type - Terminal type (unused, kept for API compatibility)
• _width - Terminal width (unused, kept for API compatibility)
• _height - Terminal height (unused, kept for API compatibility)

Returns

A Channel that can be used for bidirectional communication with the remote shell.

Note

The caller is responsible for:

1. Requesting PTY with proper terminal modes via channel.request_pty()
2. Requesting shell via channel.request_shell()

This change fixes issue #40: PTY should be requested once with proper terminal modes by PtySession::initialize() rather than twice with empty modes.

pub async fn resize_pty( &self, channel: &mut Channel<Msg>, width: u32, height: u32, ) -> Result<(), Error>

Request window size change for an existing PTY channel.

This should be called when the local terminal is resized to update the remote PTY dimensions.

impl Client

pub async fn connect( addr: impl ToSocketAddrsWithHostname, username: &str, auth: AuthMethod, server_check: ServerCheckMethod, ) -> Result<Self, Error>

Open a ssh connection to a remote host with default keepalive settings.

addr is an address of the remote host. Anything which implements ToSocketAddrsWithHostname trait can be supplied for the address; ToSocketAddrsWithHostname reimplements all of [ToSocketAddrs]; see this trait’s documentation for concrete examples.

If addr yields multiple addresses, connect will be attempted with each of the addresses until a connection is successful. Authentification is tried on the first successful connection and the whole process aborted if this fails.

This method uses default keepalive settings (60s interval, 3 max attempts) to prevent idle connection timeouts.

pub async fn connect_with_ssh_config( addr: impl ToSocketAddrsWithHostname, username: &str, auth: AuthMethod, server_check: ServerCheckMethod, ssh_config: &SshConnectionConfig, ) -> Result<Self, Error>

Connect with custom SSH connection configuration.

This method allows specifying keepalive settings and other connection parameters through SshConnectionConfig.

Example

use bssh::ssh::tokio_client::{Client, AuthMethod, ServerCheckMethod, SshConnectionConfig};

#[tokio::main]
async fn main() -> Result<(), bssh::ssh::tokio_client::Error> {
    let ssh_config = SshConnectionConfig::new()
        .with_keepalive_interval(Some(30))
        .with_keepalive_max(5);

    let client = Client::connect_with_ssh_config(
        ("example.com", 22),
        "user",
        AuthMethod::with_key_file("~/.ssh/id_rsa", None),
        ServerCheckMethod::DefaultKnownHostsFile,
        &ssh_config,
    ).await?;

    Ok(())
}

pub async fn connect_with_config( addr: impl ToSocketAddrsWithHostname, username: &str, auth: AuthMethod, server_check: ServerCheckMethod, config: Config, ) -> Result<Self, Error>

Same as connect, but with the option to specify a non default russh::client::Config.

For most use cases, prefer [connect_with_ssh_config] which provides a higher-level API with sensible defaults.

pub fn from_handle_and_address( handle: Arc<Handle<ClientHandler>>, username: String, address: SocketAddr, ) -> Self

Create a Client from an existing russh handle and address.

This is used internally for jump host connections where we already have an authenticated russh handle from connect_stream.

pub fn get_connection_username(&self) -> &String

A debugging function to get the username this client is connected as.

pub fn get_connection_address(&self) -> &SocketAddr

A debugging function to get the address this client is connected to.

pub async fn disconnect(&self) -> Result<(), Error>

Disconnect from the remote host.

pub fn is_closed(&self) -> bool

Check if the connection is closed.

pub async fn request_port_forward( &self, _bind_address: String, _bind_port: u32, ) -> Result<u32, Error>

Request remote port forwarding (tcpip-forward) - Future Implementation Placeholder

TODO: This method needs to be implemented once russh provides global request functionality or we find the appropriate API.

This sends a global request to the SSH server to bind a port on the remote end and forward connections back to the client. This is used for remote port forwarding (-R).

Arguments

• bind_address - Address to bind on the remote server (e.g., “localhost”, “0.0.0.0”)
• bind_port - Port to bind on the remote server (0 to let server choose)

Returns

The actual port number that was bound by the server (useful when bind_port is 0)

pub async fn cancel_port_forward( &self, _bind_address: String, _bind_port: u32, ) -> Result<(), Error>

Cancel remote port forwarding (cancel-tcpip-forward) - Future Implementation Placeholder

TODO: This method needs to be implemented once russh provides global request functionality or we find the appropriate API.

This sends a global request to cancel a previously established remote port forward.

Arguments

• bind_address - Address that was bound on the remote server
• bind_port - Port that was bound on the remote server

impl Client

pub async fn upload_file<T: AsRef<Path>, U: Into<String>>( &self, src_file_path: T, dest_file_path: U, ) -> Result<(), Error>

Upload a file with sftp to the remote server.

src_file_path is the path to the file on the local machine. dest_file_path is the path to the file on the remote machine. Some sshd_config does not enable sftp by default, so make sure it is enabled. A config line like a Subsystem sftp internal-sftp or Subsystem sftp /usr/lib/openssh/sftp-server is needed in the sshd_config in remote machine.

pub async fn download_file<T: AsRef<Path>, U: Into<String>>( &self, remote_file_path: U, local_file_path: T, ) -> Result<(), Error>

Download a file from the remote server using sftp.

remote_file_path is the path to the file on the remote machine. local_file_path is the path to the file on the local machine. Some sshd_config does not enable sftp by default, so make sure it is enabled. A config line like a Subsystem sftp internal-sftp or Subsystem sftp /usr/lib/openssh/sftp-server is needed in the sshd_config in remote machine.

pub async fn upload_dir<T: AsRef<Path>, U: Into<String>>( &self, local_dir_path: T, remote_dir_path: U, ) -> Result<(), Error>

Upload a directory to the remote server using sftp recursively.

local_dir_path is the path to the directory on the local machine. remote_dir_path is the path to the directory on the remote machine. All files and subdirectories will be uploaded recursively.

pub async fn download_dir<T: AsRef<Path>, U: Into<String>>( &self, remote_dir_path: U, local_dir_path: T, ) -> Result<(), Error>

Download a directory from the remote server using sftp recursively.

remote_dir_path is the path to the directory on the remote machine. local_dir_path is the path to the directory on the local machine. All files and subdirectories will be downloaded recursively.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.