From fc2a6ab09c411b475e0e39ad4a90eb402e957676 Mon Sep 17 00:00:00 2001 From: Chip Senkbeil Date: Sat, 16 Oct 2021 15:38:07 -0500 Subject: [PATCH] Bump to v0.15.0 release and add readme for distant-ssh2 --- Cargo.lock | 8 ++-- Cargo.toml | 6 +-- README.md | 14 ++++++- distant-core/Cargo.toml | 2 +- distant-lua/Cargo.toml | 6 +-- distant-lua/README.md | 2 +- distant-ssh2/Cargo.toml | 4 +- distant-ssh2/README.md | 91 +++++++++++++++++++++++++++++++++++++++++ 8 files changed, 117 insertions(+), 16 deletions(-) create mode 100644 distant-ssh2/README.md diff --git a/Cargo.lock b/Cargo.lock index b44225a..61339e5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -427,7 +427,7 @@ dependencies = [ [[package]] name = "distant" -version = "0.15.0-alpha.22" +version = "0.15.0" dependencies = [ "assert_cmd", "assert_fs", @@ -451,7 +451,7 @@ dependencies = [ [[package]] name = "distant-core" -version = "0.15.0-alpha.22" +version = "0.15.0" dependencies = [ "assert_fs", "bytes", @@ -476,7 +476,7 @@ dependencies = [ [[package]] name = "distant-lua" -version = "0.15.0-alpha.22" +version = "0.15.0" dependencies = [ "distant-core", "distant-ssh2", @@ -510,7 +510,7 @@ dependencies = [ [[package]] name = "distant-ssh2" -version = "0.15.0-alpha.22" +version = "0.15.0" dependencies = [ "assert_cmd", "assert_fs", diff --git a/Cargo.toml b/Cargo.toml index 306e803..0a49df5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "distant" description = "Operate on a remote computer through file and process manipulation" categories = ["command-line-utilities"] keywords = ["cli"] -version = "0.15.0-alpha.22" +version = "0.15.0" authors = ["Chip Senkbeil "] edition = "2018" homepage = "https://github.com/chipsenkbeil/distant" @@ -25,7 +25,7 @@ ssh2 = ["distant-ssh2"] [dependencies] derive_more = { version = "0.99.16", default-features = false, features = ["display", "from", "error", "is_variant"] } -distant-core = { version = "=0.15.0-alpha.22", path = "distant-core", features = ["structopt"] } +distant-core = { version = "=0.15.0", path = "distant-core", features = ["structopt"] } flexi_logger = "0.18.0" log = "0.4.14" once_cell = "1.8.0" @@ -37,7 +37,7 @@ strum = { version = "0.21.0", features = ["derive"] } whoami = "1.1.2" # Optional native SSH functionality -distant-ssh2 = { version = "=0.15.0-alpha.22", path = "distant-ssh2", optional = true } +distant-ssh2 = { version = "=0.15.0", path = "distant-ssh2", optional = true } [target.'cfg(unix)'.dependencies] fork = "0.1.18" diff --git a/README.md b/README.md index 23df8cd..8a77d0d 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,11 @@ talk to the server. encryption scheme via [RustCrypto/ChaCha20Poly1305](https://github.com/RustCrypto/AEADs/tree/master/chacha20poly1305) +Additionally, the core of the distant client and server codebase can be pulled +in to be used with your own Rust crates via the `distant-core` crate. +Separately, Lua bindings can be found within `distant-lua`, exported as a +shared library that can be imported into lua using `require("distant_lua")`. + ## Installation ### Prebuilt Binaries @@ -58,8 +63,13 @@ the [build guide](./BUILDING.md). ## Examples -Launch a remote instance of `distant` by SSHing into another machine and -starting the `distant` executable: +Launch a remote instance of `distant`. Calling `launch` will do the following: + +1. Ssh into the specified host (in the below example, `my.example.com`) +2. Execute `distant listen --host ssh` on the remote machine +3. Receive on the local machine the credentials needed to connect to the server +4. Depending on the options specified, store/use the session settings so + future calls to `distant action` can connect ```bash # Connects to my.example.com on port 22 via SSH to start a new session diff --git a/distant-core/Cargo.toml b/distant-core/Cargo.toml index f1afc70..973821f 100644 --- a/distant-core/Cargo.toml +++ b/distant-core/Cargo.toml @@ -3,7 +3,7 @@ name = "distant-core" description = "Core library for distant, enabling operation on a remote computer through file and process manipulation" categories = ["network-programming"] keywords = ["api", "async"] -version = "0.15.0-alpha.22" +version = "0.15.0" authors = ["Chip Senkbeil "] edition = "2018" homepage = "https://github.com/chipsenkbeil/distant" diff --git a/distant-lua/Cargo.toml b/distant-lua/Cargo.toml index f43ab3a..a0e1570 100644 --- a/distant-lua/Cargo.toml +++ b/distant-lua/Cargo.toml @@ -3,7 +3,7 @@ name = "distant-lua" description = "Lua bindings to the distant Rust crates" categories = ["api-bindings", "network-programming"] keywords = ["api", "async"] -version = "0.15.0-alpha.22" +version = "0.15.0" authors = ["Chip Senkbeil "] edition = "2018" homepage = "https://github.com/chipsenkbeil/distant" @@ -24,8 +24,8 @@ luajit = ["mlua/luajit"] vendored = ["mlua/vendored"] [dependencies] -distant-core = { version = "=0.15.0-alpha.22", path = "../distant-core" } -distant-ssh2 = { version = "=0.15.0-alpha.22", features = ["serde"], path = "../distant-ssh2" } +distant-core = { version = "=0.15.0", path = "../distant-core" } +distant-ssh2 = { version = "=0.15.0", features = ["serde"], path = "../distant-ssh2" } futures = "0.3.17" log = "0.4.14" mlua = { version = "0.6.6", features = ["async", "macros", "module", "serialize"] } diff --git a/distant-lua/README.md b/distant-lua/README.md index 7dd4d5a..92e0833 100644 --- a/distant-lua/README.md +++ b/distant-lua/README.md @@ -13,7 +13,7 @@ including: directory.* ```bash -# Outputs a library file (*.so for Linux, *.dylib for MacOS) +# Outputs a library file (*.so for Linux, *.dylib for MacOS, *.dll for Windows) cargo build --release ``` diff --git a/distant-ssh2/Cargo.toml b/distant-ssh2/Cargo.toml index 9ae61c3..f7728bb 100644 --- a/distant-ssh2/Cargo.toml +++ b/distant-ssh2/Cargo.toml @@ -2,7 +2,7 @@ name = "distant-ssh2" description = "Library to enable native ssh-2 protocol for use with distant sessions" categories = ["network-programming"] -version = "0.15.0-alpha.22" +version = "0.15.0" authors = ["Chip Senkbeil "] edition = "2018" homepage = "https://github.com/chipsenkbeil/distant" @@ -12,7 +12,7 @@ license = "MIT OR Apache-2.0" [dependencies] async-compat = "0.2.1" -distant-core = { version = "=0.15.0-alpha.22", path = "../distant-core" } +distant-core = { version = "=0.15.0", path = "../distant-core" } futures = "0.3.16" log = "0.4.14" rand = { version = "0.8.4", features = ["getrandom"] } diff --git a/distant-ssh2/README.md b/distant-ssh2/README.md new file mode 100644 index 0000000..19f908e --- /dev/null +++ b/distant-ssh2/README.md @@ -0,0 +1,91 @@ +# distant ssh2 + +[![Crates.io][distant_crates_img]][distant_crates_lnk] [![Docs.rs][distant_doc_img]][distant_doc_lnk] [![Rustc 1.51.0][distant_rustc_img]][distant_rustc_lnk] + +[distant_crates_img]: https://img.shields.io/crates/v/distant-ssh2.svg +[distant_crates_lnk]: https://crates.io/crates/distant-ssh2 +[distant_doc_img]: https://docs.rs/distant-ssh2/badge.svg +[distant_doc_lnk]: https://docs.rs/distant-ssh2 +[distant_rustc_img]: https://img.shields.io/badge/distant_ssh2-rustc_1.51+-lightgray.svg +[distant_rustc_lnk]: https://blog.rust-lang.org/2021/03/25/Rust-1.51.0.html + +Library provides native ssh integration into the +[`distant`](https://github.com/chipsenkbeil/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`](https://tokio.rs/) +- Data is serialized to send across the wire via [`CBOR`](https://cbor.io/) +- Encryption & authentication are handled via + [XChaCha20Poly1305](https://tools.ietf.org/html/rfc8439) for an authenticated + encryption scheme via + [RustCrypto/ChaCha20Poly1305](https://github.com/RustCrypto/AEADs/tree/master/chacha20poly1305) + +## Installation + +You can import the dependency by adding the following to your `Cargo.toml`: + +```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: + +```rust +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: + +```rust +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][apache-license]) MIT license (LICENSE-MIT or +[mit-license][mit-license]) at your option. + +[apache-license]: http://www.apache.org/licenses/LICENSE-2.0 +[mit-license]: http://opensource.org/licenses/MIT