# remotefs SSH
[](https://opensource.org/licenses/MIT)
[](https://github.com/remotefs-rs/remotefs-rs-ssh/stargazers)
[](https://crates.io/crates/remotefs-ssh)
[](https://crates.io/crates/remotefs-ssh)
[](https://ko-fi.com/veeso)
[](https://conventionalcommits.org)
[](https://github.com/veeso/remotefs-rs-ssh/actions/workflows/test.yml)
[](https://coveralls.io/github/veeso/remotefs-rs-ssh)
[](https://docs.rs/remotefs-ssh)
---
## About remotefs-ssh ☁️
remotefs-ssh is a client implementation for [remotefs](https://github.com/remotefs-rs/remotefs-rs), providing support
for the SFTP/SCP protocol.
---
## Get started 🚀
First of all, add `remotefs-ssh` to your project dependencies:
```toml
remotefs = "0.3"
remotefs-ssh = "^0.7"
```
> [!NOTE]
> The library supports multiple ssh backends.
> Currently `libssh2` and `libssh` 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.
Each backend can be built with the vendored version, using the vendored feature instead:
- `libssh2-vendored`: Build the `libssh2` backend with the vendored version of the library.
- `libssh-vendored`: Build the `libssh` 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.
> [!NOTE]
> If you need SftpFs to be `Sync` YOU MUST use libssh2.
### 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.
## Ssh client
Here is a basic usage example, with the `Sftp` client, which is very similiar to the `Scp` client.
Both the `SftpFs` and `ScpFs` constructors are respectively `SftpFs::libssh2` and `SftpFs::libssh` accordingly to the
enabled backends.
```rust,ignore
// import remotefs trait and client
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());
```
---
### Client compatibility table ✔️
The following table states the compatibility for the client client and the remote file system trait method.
Note: `connect()`, `disconnect()` and `is_connected()` **MUST** always be supported, and are so omitted in the table.
| append_file | No | Yes |
| append | No | Yes |
| change_dir | Yes | Yes |
| copy | Yes | Yes |
| create_dir | Yes | Yes |
| create_file | Yes | Yes |
| create | Yes | Yes |
| exec | Yes | Yes |
| exists | Yes | Yes |
| list_dir | Yes | Yes |
| mov | Yes | Yes |
| open_file | Yes | Yes |
| open | Yes | Yes |
| pwd | Yes | Yes |
| remove_dir_all | Yes | Yes |
| remove_dir | Yes | Yes |
| remove_file | Yes | Yes |
| setstat | Yes | Yes |
| stat | Yes | Yes |
| symlink | Yes | Yes |
---
## Support the developer ☕
If you like remotefs-ssh and you're grateful for the work I've done, please consider a little donation 🥳
You can make a donation with one of these platforms:
[](https://ko-fi.com/veeso)
[](https://www.paypal.me/chrisintin)
[](https://btc.com/bc1qvlmykjn7htz0vuprmjrlkwtv9m9pan6kylsr8w)
---
## Contributing and issues 🤝🏻
Contributions, bug reports, new features, and questions are welcome! 😉
If you have any questions or concerns, or you want to suggest a new feature, or you want just want to improve remotefs,
feel free to open an issue or a PR.
Please follow [our contributing guidelines](CONTRIBUTING.md)
---
## Changelog ⏳
View remotefs-ssh changelog [HERE](CHANGELOG.md)
---
## Powered by 💪
remotefs-ssh is powered by these aweseome projects:
- [ssh2-config](https://github.com/veeso/ssh2-config)
- [ssh2-rs](https://github.com/alexcrichton/ssh2-rs)
---
## License 📃
remotefs-ssh is licensed under the MIT license.
You can read the entire license [HERE](LICENSE)