remotefs_ssh/
lib.rs

1#![crate_name = "remotefs_ssh"]
2#![crate_type = "lib"]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4
5//! # remotefs-ssh
6//!
7//! remotefs-ssh is a client implementation for [remotefs](https://github.com/remotefs-rs/remotefs-rs), providing support for the SCP/SFTP protocols.
8//!
9//! ## Get started
10//!
11//! First of all you need to add **remotefs** and the client to your project dependencies:
12//!
13//! ```toml
14//! remotefs = "^0.3"
15//! remotefs-ssh = "^0.8"
16//! ```
17//!
18//! > The library supports multiple ssh backends.
19//! > Currently `libssh2`, `libssh`, and `russh` are supported.
20//! >
21//! > By default the library is using `libssh2`.
22//!
23//! ### Available backends
24//!
25//! Each backend can be set as a feature in your `Cargo.toml`. Multiple backends can be enabled at the same time.
26//!
27//! - `libssh2`: The default backend, using the `libssh2` library for SSH connections.
28//! - `libssh`: An alternative backend, using the `libssh` library for SSH connections.
29//! - `russh`: A pure-Rust backend, using the `russh` library for SSH connections. Does not require any system C libraries.
30//!
31//! Each C backend can be built with the vendored version, using the vendored feature instead:
32//!
33//! - `libssh-vendored`: Build the `libssh` backend with the vendored version of the library.
34//! - `libssh2-vendored`: Build the `libssh2` backend with the vendored version of the library.
35//!
36//! If the vendored feature is **NOT** provided, you will need to have the corresponding system libraries installed on your machine.
37//!
38//! > If you need SftpFs to be `Sync` YOU MUST use `libssh2` or `russh`. The `libssh` backend does not support `Sync`.
39//!
40//! ### Other features
41//!
42//! these features are supported:
43//!
44//! - `find`: enable `find()` method on client (*enabled by default*)
45//! - `no-log`: disable logging. By default, this library will log via the `log` crate.
46//!
47//! ## Examples
48//!
49//! Here is a basic usage example, with the `Sftp` client, which is very similiar to the `Scp` client.
50//!
51//! The [`SftpFs`] and [`ScpFs`] constructors vary depending on the enabled backend:
52//! [`SftpFs::libssh2`], [`SftpFs::libssh`], or [`SftpFs::russh`] (and likewise for [`ScpFs`]).
53//!
54//! ### libssh2 / libssh
55//!
56//! ```rust,ignore
57//! use remotefs::RemoteFs;
58//! use remotefs_ssh::{SshConfigParseRule, SftpFs, SshOpts};
59//! use std::path::Path;
60//!
61//! let opts = SshOpts::new("127.0.0.1")
62//!     .port(22)
63//!     .username("test")
64//!     .password("password")
65//!     .config_file(Path::new("/home/cvisintin/.ssh/config"), ParseRule::STRICT);
66//!
67//! let mut client = SftpFs::libssh2(opts);
68//!
69//! // connect
70//! assert!(client.connect().is_ok());
71//! // get working directory
72//! println!("Wrkdir: {}", client.pwd().ok().unwrap().display());
73//! // change working directory
74//! assert!(client.change_dir(Path::new("/tmp")).is_ok());
75//! // disconnect
76//! assert!(client.disconnect().is_ok());
77//! ```
78//!
79//! ### russh
80//!
81//! The `russh` backend requires a Tokio runtime and a type implementing `russh::client::Handler`
82//! for server key verification. [`NoCheckServerKey`] is provided as a convenience handler that
83//! accepts all host keys.
84//!
85//! ```rust,ignore
86//! use remotefs::RemoteFs;
87//! use remotefs_ssh::{NoCheckServerKey, SftpFs, SshOpts};
88//! use std::path::Path;
89//! use std::sync::Arc;
90//!
91//! let runtime = Arc::new(
92//!     tokio::runtime::Builder::new_current_thread()
93//!         .enable_all()
94//!         .build()
95//!         .unwrap(),
96//! );
97//!
98//! let opts = SshOpts::new("127.0.0.1")
99//!     .port(22)
100//!     .username("test")
101//!     .password("password");
102//!
103//! let mut client: SftpFs<remotefs_ssh::RusshSession<NoCheckServerKey>> =
104//!     SftpFs::russh(opts, runtime);
105//!
106//! // connect
107//! assert!(client.connect().is_ok());
108//! // get working directory
109//! println!("Wrkdir: {}", client.pwd().ok().unwrap().display());
110//! // change working directory
111//! assert!(client.change_dir(Path::new("/tmp")).is_ok());
112//! // disconnect
113//! assert!(client.disconnect().is_ok());
114//! ```
115//!
116
117#![doc(html_playground_url = "https://play.rust-lang.org")]
118#![doc(
119    html_favicon_url = "https://raw.githubusercontent.com/remotefs-rs/remotefs-rs/main/assets/logo-128.png"
120)]
121#![doc(
122    html_logo_url = "https://raw.githubusercontent.com/remotefs-rs/remotefs-rs/main/assets/logo.png"
123)]
124
125// -- crates
126#[macro_use]
127extern crate lazy_regex;
128#[macro_use]
129extern crate log;
130
131// compile error if no backend is chosen
132#[cfg(not(any(feature = "libssh2", feature = "libssh", feature = "russh")))]
133compile_error!(
134    "No SSH backend chosen. Please enable either `libssh2`, `libssh`, or `russh` feature."
135);
136
137mod ssh;
138pub use ssh::{
139    KeyMethod, MethodType, ParseRule as SshConfigParseRule, ScpFs, SftpFs, SshAgentIdentity,
140    SshKeyStorage, SshOpts, SshSession,
141};
142
143#[cfg(feature = "libssh2")]
144#[cfg_attr(docsrs, doc(cfg(feature = "libssh2")))]
145pub use self::ssh::LibSsh2Session;
146#[cfg(feature = "libssh")]
147#[cfg_attr(docsrs, doc(cfg(feature = "libssh")))]
148pub use self::ssh::LibSshSession;
149#[cfg(feature = "russh")]
150#[cfg_attr(docsrs, doc(cfg(feature = "russh")))]
151pub use self::ssh::{NoCheckServerKey, RusshSession};
152
153// -- utils
154pub(crate) mod utils;
155// -- mock
156#[cfg(test)]
157pub(crate) mod mock;
remotefs_ssh/lib.rs

remotefs_ssh/
lib.rs
