remotefs-ssh 0.8.3

remotefs SSH client library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

#![crate_name = "remotefs_ssh"]
#![crate_type = "lib"]
#![cfg_attr(docsrs, feature(doc_cfg))]

//! # remotefs-ssh
//!
//! remotefs-ssh is a client implementation for [remotefs](https://github.com/remotefs-rs/remotefs-rs), providing support for the SCP/SFTP protocols.
//!
//! ## Get started
//!
//! First of all you need to add **remotefs** and the client to your project dependencies:
//!
//! ```toml
//! remotefs = "^0.3"
//! remotefs-ssh = "^0.8"
//! ```
//!
//! > The library supports multiple ssh backends.
//! > Currently `libssh2`, `libssh`, and `russh` are supported.
//! >
//! > By default the library is using `libssh2`.
//!
//! ### Available backends
//!
//! Each backend can be set as a feature in your `Cargo.toml`. Multiple backends can be enabled at the same time.
//!
//! - `libssh2`: The default backend, using the `libssh2` library for SSH connections.
//! - `libssh`: An alternative backend, using the `libssh` library for SSH connections.
//! - `russh`: A pure-Rust backend, using the `russh` library for SSH connections. Does not require any system C libraries.
//!
//! Each C backend can be built with the vendored version, using the vendored feature instead:
//!
//! - `libssh-vendored`: Build the `libssh` backend with the vendored version of the library.
//! - `libssh2-vendored`: Build the `libssh2` backend with the vendored version of the library.
//!
//! If the vendored feature is **NOT** provided, you will need to have the corresponding system libraries installed on your machine.
//!
//! > If you need SftpFs to be `Sync` YOU MUST use `libssh2` or `russh`. The `libssh` backend does not support `Sync`.
//!
//! ### Other features
//!
//! these features are supported:
//!
//! - `find`: enable `find()` method on client (*enabled by default*)
//! - `no-log`: disable logging. By default, this library will log via the `log` crate.
//!
//! ## Examples
//!
//! Here is a basic usage example, with the `Sftp` client, which is very similiar to the `Scp` client.
//!
//! The [`SftpFs`] and [`ScpFs`] constructors vary depending on the enabled backend:
//! [`SftpFs::libssh2`], [`SftpFs::libssh`], or [`SftpFs::russh`] (and likewise for [`ScpFs`]).
//!
//! ### libssh2 / libssh
//!
//! ```rust,ignore
//! use remotefs::RemoteFs;
//! use remotefs_ssh::{SshConfigParseRule, SftpFs, SshOpts};
//! use std::path::Path;
//!
//! let opts = SshOpts::new("127.0.0.1")
//!     .port(22)
//!     .username("test")
//!     .password("password")
//!     .config_file(Path::new("/home/cvisintin/.ssh/config"), ParseRule::STRICT);
//!
//! let mut client = SftpFs::libssh2(opts);
//!
//! // connect
//! assert!(client.connect().is_ok());
//! // get working directory
//! println!("Wrkdir: {}", client.pwd().ok().unwrap().display());
//! // change working directory
//! assert!(client.change_dir(Path::new("/tmp")).is_ok());
//! // disconnect
//! assert!(client.disconnect().is_ok());
//! ```
//!
//! ### russh
//!
//! The `russh` backend requires a Tokio runtime and a type implementing `russh::client::Handler`
//! for server key verification. [`NoCheckServerKey`] is provided as a convenience handler that
//! accepts all host keys.
//!
//! ```rust,ignore
//! use remotefs::RemoteFs;
//! use remotefs_ssh::{NoCheckServerKey, SftpFs, SshOpts};
//! use std::path::Path;
//! use std::sync::Arc;
//!
//! let runtime = Arc::new(
//!     tokio::runtime::Builder::new_current_thread()
//!         .enable_all()
//!         .build()
//!         .unwrap(),
//! );
//!
//! let opts = SshOpts::new("127.0.0.1")
//!     .port(22)
//!     .username("test")
//!     .password("password");
//!
//! let mut client: SftpFs<remotefs_ssh::RusshSession<NoCheckServerKey>> =
//!     SftpFs::russh(opts, runtime);
//!
//! // connect
//! assert!(client.connect().is_ok());
//! // get working directory
//! println!("Wrkdir: {}", client.pwd().ok().unwrap().display());
//! // change working directory
//! assert!(client.change_dir(Path::new("/tmp")).is_ok());
//! // disconnect
//! assert!(client.disconnect().is_ok());
//! ```
//!

#![doc(html_playground_url = "https://play.rust-lang.org")]
#![doc(
    html_favicon_url = "https://raw.githubusercontent.com/remotefs-rs/remotefs-rs/main/assets/logo-128.png"
)]
#![doc(
    html_logo_url = "https://raw.githubusercontent.com/remotefs-rs/remotefs-rs/main/assets/logo.png"
)]

// -- crates
#[macro_use]
extern crate lazy_regex;
#[macro_use]
extern crate log;

// compile error if no backend is chosen
#[cfg(not(any(feature = "libssh2", feature = "libssh", feature = "russh")))]
compile_error!(
    "No SSH backend chosen. Please enable either `libssh2`, `libssh`, or `russh` feature."
);

mod ssh;
pub use ssh::{
    KeyMethod, MethodType, ParseRule as SshConfigParseRule, ScpFs, SftpFs, SshAgentIdentity,
    SshKeyStorage, SshOpts, SshSession,
};

#[cfg(feature = "libssh2")]
#[cfg_attr(docsrs, doc(cfg(feature = "libssh2")))]
pub use self::ssh::LibSsh2Session;
#[cfg(feature = "libssh")]
#[cfg_attr(docsrs, doc(cfg(feature = "libssh")))]
pub use self::ssh::LibSshSession;
#[cfg(feature = "russh")]
#[cfg_attr(docsrs, doc(cfg(feature = "russh")))]
pub use self::ssh::{NoCheckServerKey, RusshSession};

// -- utils
pub(crate) mod utils;
// -- mock
#[cfg(test)]
pub(crate) mod mock;