Struct makiko::Session

pub struct Session { /* private fields */ }

Handle to an SSH session.

SSH session (RFC 4254, section 6) corresponds to the execution of a single process. The Session is used to send requests and data to the server, and SessionReceiver will receive the requests and data from the server. To open the session, use Client::open_session().

Once the session is open, you will typically go through three stages:

• prepare the execution environment: env(), request_pty(),
• start the execution: shell(), exec(), subsystem(),
• interact with the process: send_stdin(), send_eof(), signal().

In parallel, you will handle the events produced by SessionReceiver.

An SSH session is a particular type of an SSH channel. However, this object provides higher level API than a raw Channel.

You can cheaply clone this object and safely share the clones between tasks.

Implementations

impl Session

pub fn client(&self) -> Client

Get the Client that this session belongs to.

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

Close the session.

We won’t send any further requests or data to the server and the session will be closed once the server acknowledges our request.

This method is idempotent: if the session is already closed or closing, we do nothing.

impl Session

Preparing the execution environment

Use these methods to configure the session before starting the process.

pub fn env(&self, name: &[u8], value: &[u8]) -> Result<SessionResp>

Pass an environment variable to the future process.

This will set an environment variable for the process that will be started later.

This method returns immediately without any blocking, but you may use the returned SessionResp to wait for the server response.

pub fn request_pty(&self, request: &PtyRequest) -> Result<SessionResp>

Request a pseudo-terminal (pty) for the future process.

This will allocate a pseudo-terminal according to the request.

This method returns immediately without any blocking, but you may use the returned SessionResp to wait for the server response.

impl Session

Starting the process

Use one of these methods to start the remote process. Only one of them can succeed, you cannot start multiple processes with a single session (but you may open multiple sessions).

pub fn shell(&self) -> Result<SessionResp>

Start the user’s default shell on the server.

This method returns immediately without any blocking, but you may use the returned SessionResp to wait for the server response.

pub fn exec(&self, command: &[u8]) -> Result<SessionResp>

Start a command on the server.

This method returns immediately without any blocking, but you may use the returned SessionResp to wait for the server response.

pub fn subsystem(&self, subsystem_name: &str) -> Result<SessionResp>

Start an SSH subsystem on the server.

Subsystems are described in RFC 4254, section 6.5.

This method returns immediately without any blocking, but you may use the returned SessionResp to wait for the server response.

impl Session

Interacting with a running process

pub async fn send_stdin(&self, data: Bytes) -> Result<()>

Send data to the standard input of the running process.

This method returns after all bytes have been accepted by the flow control mechanism and written to the internal send buffer, but before we send them to the socket (or other I/O stream that backs this SSH connection).

pub async fn send_eof(&self) -> Result<()>

Close the standard input of the running process.

This method returns after all bytes previously sent to this session have been accepted by the flow control mechanism, but before we write the message to the socket (or other I/O stream that backs this SSH connection).

If the session is closed before you call this method, or if it closes before this method returns, we quietly ignore this error and return Ok.

pub fn signal(&self, signal_name: &str) -> Result<()>

Deliver a signal to the running process.

Signal names are described in RFC 4254, section 6.10. codes::signal lists the signal names defined by SSH.

This method returns immediately without any blocking, it is not possible to get a reply from the server.

pub fn window_change(&self, change: &WindowChange) -> Result<()>

Notify the process that the terminal window size has changed.

This method returns immediately without any blocking, it is not possible to get a reply from the server.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

Returns a copy of the value.

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

Performs copy-assignment from source.