Struct libssh_rs::Channel

pub struct Channel { /* fields omitted */ }

Represents a channel in a Session.

A Session can have multiple channels; there is typically one for the shell/program being run, but additional channels can be opened to forward TCP or other connections.

open_session is often the first thing you will call on the Channel after creating it; this establishes the channel for executing commands.

Then you will typically use either request_exec to run a non-interactive command, or request_pty followed request_shell to set up an interactive remote shell.

Thread Safety

Channel is strongly associated with the Session to which it belongs. libssh doesn’t allow using anything associated with a given Session from multiple threads concurrently. These Rust bindings encapsulate the underlying Session in an internal mutex, which allows you to safely operate on the various elements of the session and even move them to other threads, but you need to be aware that calling methods on any of those structs will attempt to lock the underlying session, and this can lead to blocking in surprising situations.

Implementations

impl Channel

pub fn accept_x11(&self, timeout: Duration) -> Option<Self>

Accept an X11 forwarding channel. Returns a newly created Channel, or None if no X11 request from the server.

pub fn close(&self) -> SshResult<()>

Close a channel. This sends an end of file and then closes the channel. You won’t be able to recover any data the server was going to send or was in buffers.

pub fn get_exit_status(&self) -> Option<c_int>

Get the exit status of the channel (error code from the executed instruction). This function may block until a timeout (or never) if the other side is not willing to close the channel.

pub fn is_closed(&self) -> bool

Check if the channel is closed or not.

pub fn is_eof(&self) -> bool

Check if remote has sent an EOF.

pub fn send_eof(&self) -> SshResult<()>

Send an end of file on the channel.

You should call this when you have no additional data to send to the channel to signal that information to the remote host.

This doesn’t close the channel. You may still read from it but not write.

pub fn is_open(&self) -> bool

Check if the channel is open or not.

pub fn open_auth_agent(&self) -> SshResult<()>

Open an agent authentication forwarding channel. This type of channel can be opened by a server towards a client in order to provide SSH-Agent services to the server-side process. This channel can only be opened if the client claimed support by sending a channel request beforehand.

pub fn request_auth_agent(&self) -> SshResult<()>

Send an "auth-agent-req" channel request over an existing session channel.

This client-side request will enable forwarding the agent over a secure tunnel. When the server is ready to open one authentication agent channel, an ssh_channel_open_request_auth_agent_callback event will be generated.

pub fn request_env(&self, name: &str, value: &str) -> SshResult<()>

Set environment variable. Some environment variables may be refused by security reasons.

pub fn request_shell(&self) -> SshResult<()>

Requests a shell; asks the server to spawn the user’s shell, rather than directly executing a command specified by the client.

The channel must be a session channel; you need to have called open_session before this will succeed.

pub fn request_exec(&self, command: &str) -> SshResult<()>

Run a shell command without an interactive shell. This is similar to ‘sh -c command’.

The channel must be a session channel; you need to have called open_session before this will succeed.

pub fn request_subsystem(&self, subsys: &str) -> SshResult<()>

Request a subsystem.

You probably don’t need this unless you know what you are doing!

pub fn request_pty(&self, term: &str, columns: u32, rows: u32) -> SshResult<()>

Request a PTY with a specific type and size. A PTY is useful when you want to run an interactive program on the remote host.

term is the initial value for the TERM environment variable. If you’re not sure what to fill for the values, term = "xterm", columns = 80 and rows = 24 are reasonable defaults.

pub fn change_pty_size(&self, columns: u32, rows: u32) -> SshResult<()>

Informs the server that the local size of the PTY has changed

pub fn request_send_break(&self, length: Duration) -> SshResult<()>

Send a break signal to the server (as described in RFC 4335). Sends a break signal to the remote process. Note, that remote system may not support breaks. In such a case this request will be silently ignored.

pub fn request_send_signal(&self, signal: &str) -> SshResult<()>

Send a signal to remote process (as described in RFC 4254, section 6.9). Sends a signal to the remote process. Note, that remote system may not support signals concept. In such a case this request will be silently ignored.

signal is the name of the signal, without the "SIG" prefix. For example, "ABRT", "INT", "KILL" and so on.

The OpenSSH server has only supported signals since OpenSSH version 8.1, released in 2019. https://bugzilla.mindrot.org/show_bug.cgi?id=1424

pub fn open_forward(
    &self,
    remote_host: &str,
    remote_port: u16,
    source_host: &str,
    source_port: u16
) -> SshResult<()>

Open a TCP/IP forwarding channel. remote_host, remote_port identify the destination for the connection. source_host, source_port identify the origin of the connection on the client side; these are used primarily for logging purposes.

This function does not bind the source port and does not automatically forward the content of a socket to the channel. You still have to read/write this channel object to achieve that.

pub fn open_forward_unix(
    &self,
    remote_path: &str,
    source_host: &str,
    source_port: u16
) -> SshResult<()>

Open a UNIX domain socket forwarding channel. remote_path is the path to the unix socket to open on the remote machine. source_host and source_port identify the originating connection from the client machine and are used for logging purposes.

This function does not bind the source and does not automatically forward the content of a socket to the channel. You still have to read/write this channel object to achieve that.

pub fn request_x11(
    &self,
    single_connection: bool,
    protocol: Option<&str>,
    cookie: Option<&str>,
    screen_number: c_int
) -> SshResult<()>

Sends the "x11-req" channel request over an existing session channel. This will enable redirecting the display of the remote X11 applications to local X server over an secure tunnel.

pub fn open_session(&self) -> SshResult<()>

Open a session channel (suited for a shell, not TCP forwarding).

pub fn poll_timeout(
    &self,
    is_stderr: bool,
    timeout: Option<Duration>
) -> SshResult<PollStatus>

Polls a channel for data to read. Returns the number of bytes available for reading. If timeout is None, then blocks until data is available.

pub fn read_timeout(
    &self,
    buf: &mut [u8],
    is_stderr: bool,
    timeout: Option<Duration>
) -> SshResult<usize>

Reads data from a channel. This function may fewer bytes than the buf size.

pub fn window_size(&self) -> usize

Get the remote window size. This is the maximum amounts of bytes the remote side expects us to send before growing the window again. A nonzero return value does not guarantee the socket is ready to send that much data. Buffering may happen in the local SSH packet buffer, so beware of really big window sizes. A zero return value means that a write will block (if the session is in blocking mode) until the window grows back.

pub fn stdout(&self) -> impl Read + '_

Returns a struct that implements std::io::Read and that will read data from the stdout channel.

pub fn stderr(&self) -> impl Read + '_

Returns a struct that implements std::io::Read and that will read data from the stderr channel.

pub fn stdin(&self) -> impl Write + '_

Returns a struct that implements std::io::Write and that will write data to the stdin channel

Trait Implementations

impl Drop for Channel

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Channel