distant/distant-ssh2/README.md

distant ssh2

Library provides native ssh integration into the distant binary.

🚧 (Alpha stage software) This library is in rapid development and may break or change frequently! 🚧

Details

The distant-ssh2 library supplies functionality to

• Asynchronous in nature, powered by tokio
• Data is serialized to send across the wire via CBOR
• Encryption & authentication are handled via XChaCha20Poly1305 for an authenticated encryption scheme via RustCrypto/ChaCha20Poly1305

Installation

You can import the dependency by adding the following to your Cargo.toml:

[dependencies]
distant-ssh2 = "0.15"

Examples

Below is an example of connecting to an ssh server and producing a distant session that uses ssh without a distant server binary:

use distant_ssh2::Ssh2Session;

// Using default ssh session arguments to establish a connection
let mut ssh_session = Ssh2Session::connect("example.com", Default::default()).expect("Failed to connect");

// Authenticating with the server is a separate step
// 1. You can pass defaults and authentication and host verification will
//    be done over stderr
// 2. You can provide your own handlers for programmatic engagement
ssh_session.authenticate(Default::default()).await.expect("Failed to authenticate");

// Convert into an ssh client session (no distant server required)
let session = ssh_session.into_ssh_client_session().await.expect("Failed to convert session");

Below is an example of connecting to an ssh server and producing a distant session that spawns a distant server binary and then connects to it:

use distant_ssh2::Ssh2Session;

// Using default ssh session arguments to establish a connection
let mut ssh_session = Ssh2Session::connect("example.com", Default::default()).expect("Failed to connect");

// Authenticating with the server is a separate step
// 1. You can pass defaults and authentication and host verification will
//    be done over stderr
// 2. You can provide your own handlers for programmatic engagement
ssh_session.authenticate(Default::default()).await.expect("Failed to authenticate");

// Convert into a distant session, which involves spawning a distant server
// using the current ssh connection and then establishing a new connection
// to the distant server
//
// This takes in `IntoDistantSessionOpts` to specify the server's bin path,
// arguments, timeout, and whether or not to spawn using a login shell
let session = ssh_session.into_distant_session(Default::default()).await.expect("Failed to convert session");

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or apache-license) MIT license (LICENSE-MIT or mit-license) at your option.