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.7"
16//! ```
17//!
18//! > The library supports multiple ssh backends.
19//! > Currently `libssh2` and `libssh` 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//! - `libssh`: An alternative backend, using the `libssh` library for SSH connections.
28//! - `libssh2`: The default backend, using the `libssh2` library for SSH connections.
29//!
30//! Each backend can be built with the vendored version, using the vendored feature instead:
31//!
32//! - `libssh-vendored`: Build the `libssh` backend with the vendored version of the library.
33//! - `libssh2-vendored`: Build the `libssh2` backend with the vendored version of the library.
34//!
35//! If the vendored feature is **NOT** provided, you will need to have the corresponding system libraries installed on your machine.
36//!
37//! ### Other features
38//!
39//! these features are supported:
40//!
41//! - `find`: enable `find()` method on client (*enabled by default*)
42//! - `no-log`: disable logging. By default, this library will log via the `log` crate.
43//!
44//! ## Example
45//!
46//! Here is a basic usage example, with the `Sftp` client, which is very similiar to the `Scp` client.
47//!
48//! Both the [`SftpFs`] and [`ScpFs`] constructors are respectively [`SftpFs::libssh2`] and [`SftpFs::libssh`] accordingly to the
49//! enabled backends.
50//!
51//! ```rust,ignore
52//! // import remotefs trait and client
53//! use remotefs::RemoteFs;
54//! use remotefs_ssh::{SshConfigParseRule, SftpFs, SshOpts};
55//! use std::path::Path;
56//!
57//! let opts = SshOpts::new("127.0.0.1")
58//! .port(22)
59//! .username("test")
60//! .password("password")
61//! .config_file(Path::new("/home/cvisintin/.ssh/config"), ParseRule::STRICT);
62//!
63//! let mut client = SftpFs::libssh2(opts);
64//!
65//! // connect
66//! assert!(client.connect().is_ok());
67//! // get working directory
68//! println!("Wrkdir: {}", client.pwd().ok().unwrap().display());
69//! // change working directory
70//! assert!(client.change_dir(Path::new("/tmp")).is_ok());
71//! // disconnect
72//! assert!(client.disconnect().is_ok());
73//! ```
74//!
75
76#![doc(html_playground_url = "https://play.rust-lang.org")]
77#![doc(
78 html_favicon_url = "https://raw.githubusercontent.com/remotefs-rs/remotefs-rs/main/assets/logo-128.png"
79)]
80#![doc(
81 html_logo_url = "https://raw.githubusercontent.com/remotefs-rs/remotefs-rs/main/assets/logo.png"
82)]
83
84// -- crates
85#[macro_use]
86extern crate lazy_regex;
87#[macro_use]
88extern crate log;
89
90// compile error if no backend is chosen
91#[cfg(not(any(feature = "libssh2", feature = "libssh")))]
92compile_error!("No SSH backend chosen. Please enable either `libssh2` or `libssh` feature.");
93
94mod ssh;
95pub use ssh::{
96 KeyMethod, MethodType, ParseRule as SshConfigParseRule, ScpFs, SftpFs, SshAgentIdentity,
97 SshKeyStorage, SshOpts, SshSession,
98};
99
100#[cfg(feature = "libssh2")]
101#[cfg_attr(docsrs, doc(cfg(feature = "libssh2")))]
102pub use self::ssh::LibSsh2Session;
103#[cfg(feature = "libssh")]
104#[cfg_attr(docsrs, doc(cfg(feature = "libssh")))]
105pub use self::ssh::LibSshSession;
106
107// -- utils
108pub(crate) mod utils;
109// -- mock
110#[cfg(test)]
111pub(crate) mod mock;