# SSHKit.rs

SSHKit.rs is a Rust library, inspired by the [ruby version](https://github.com/capistrano/sshkit). SSHKit.rs provides an easy-to-use interface for interacting with remote servers over SSH. It is designed to simplify common SSH operations, such as executing commands, uploading and downloading files, and managing connections to remote hosts.

The library aims to be simple, yet powerful, providing a high-level interface for performing complex tasks, while still being easy to use for developers who are new to Rust or SSH programming. It is built on top of the popular SSH2 library, which provides a solid foundation for secure and reliable SSH communication.

One of the major benefits of using SSHKit.rs is its asynchronous design, which allows for multiple connections to be managed simultaneously, greatly increasing performance and scalability. Additionally, it provides a flexible and extensible architecture that can be easily customized to fit specific use cases or requirements.

Overall, SSHKit.rs is a valuable tool for developers who need to perform remote operations over SSH, whether it be for automated deployments, configuration management, or other use cases.

## Examples

Here are some examples of how you can use SSHKit.rs:

### Execute a simple command on all hosts

```rust
let sshkit = SshKit::new();
let server = Host::new("127.0.0.1", "killix", None).with_password("password");
let cmd = CommandBuilder::new("ls -la");

let exec_mode = ExecMode::Sequential(Some(Duration::from_secs(5)));
let results = sshkit.on(server.clone()).execute(cmd, exec_mode).await?;

for result in results {
    for (host, output) in result {
        println!("Output from {}: {:?}", host.address, output);
    }
}
```

### Execute multiple commands on all hosts with multiple environment variables set

```rust
let cmd = CommandBuilder::new("printenv")
    .add_command("ls -la /etc")
```

### Execute a command on all hosts with multiple environment variables set

```rust
let cmd = CommandBuilder::new("printenv")
    .with_env("VAR1", "value1")
    .with_env("VAR2", "value2");
```

### Execute a command on all hosts in a specific directory

```rust
let cmd = CommandBuilder::new("printenv")
    .with_in("/remote/path")
```

### Execute a command on all hosts using sudo to elevate privileges based on the given user and group

```rust
let cmd = CommandBuilder::new("printenv")
    .as_user("admin")
```

### Upload a file or directory to all hosts

```rust
let sshkit = SshKit::new();
let server = Host::new("127.0.0.1", "killix", None).with_password("password");
let file_opts = FileOptions::new("/path/to/remote/file").with_local_path("/path/to/local/file", );

ssh_kit
  .on(server)
  .upload(file_opts);
```

### Download a file or directory from all hosts

```rust
let sshkit = SshKit::new();
let server = Host::new("127.0.0.1", "killix", None).with_password("password");
let file_opts = FileOptions::new("/path/to/remote/file").with_local_path("/path/to/local/file", );

ssh_kit
  .on(server)
  .download(file_opts);
```

### Test the presence of a file or directory on all hosts

```rust
let sshkit = SshKit::new();
let server = Host::new("127.0.0.1", "killix", None).with_password("password");
let cmd = CommandBuilder::new("node -v");

let exec_mode = ExecMode::Sequential(None);
let results = sshkit.on(server.clone()).test(cmd, exec_mode).await?;

for result in results {
    for (host, output) in result {
        println!("Output from {}: {:?}", host.address, output);
    }
}
```


## Execution Mode
The ExecMode enum defines the different modes of execution for running commands on multiple hosts. It has three variants:

- Sequential: Runs commands on each host sequentially, one after the other. It takes an optional duration parameter which specifies the maximum time to wait for a command to complete before timing out.
- Parallel: Runs commands on all hosts in parallel.
- Group: Divides the hosts into groups and runs commands on each group in parallel. It takes a usize parameter which specifies the number of hosts in each group, and an optional duration parameter which specifies the maximum time to wait for a command to complete before timing out.

## Connection Pooling

SSHKit.rs utilizes a simple connection pool to reduce the overhead of negotiating new SSH connections. By default, if a connection hasn't been used for more than 30 seconds, it will be replaced with a new one. This timeout can be customized for each server.

## Contributing

Contributions to SSHKit.rs are welcome and appreciated! To contribute, please follow these steps:

1. Fork the repository on GitHub.
2. Create a new branch for your changes.
3. Make your changes and commit them to your branch.
4. Create a pull request to merge your changes into the main branch.

Before submitting a pull request, please ensure that your code follows Rust coding standards and that all tests are passing. Additionally, if you are introducing new features, please update the documentation and examples accordingly.

We look forward to collaborating with you on this project!

## License

SSHKit.rs is released under the MIT License.