Crate openssh

Scriptable SSH through OpenSSH.

This crate wraps the OpenSSH remote login client (ssh on most machines), and provides a convenient mechanism for running commands on remote hosts. Since all commands are executed through the ssh command, all your existing configuration (e.g., in .ssh/config) should continue to work as expected.

The library's API is modeled closely after that of std::process::Command, since ssh also attempts to make the remote process seem as much as possible like a local command. However, there are some differences.

First of all, all remote commands are executed in the context of a single ssh session. Authentication happens once when the session is established, and subsequent command invocations re-use the same connection. Behind the scenes, the crate uses ssh's ControlMaster feature to multiplex the channels for the different remote commands. Because of this, each remote command is tied to the lifetime of the Session that spawned them. When the session is closed, the connection is severed, and there can be no outstanding remote clients.

Much like with std::process::Command, you have multiple options when it comes to launching a remote command. You can spawn the remote command, which just gives you a handle to the running process, you can run the command and wait for its output, or you can run it and just extract its exit status. Unlike its std counterpart though, these methods on Command can fail even if the remote command executed successfully, since there is a fallible network separating you from it.

Also unlike its std counterpart, spawn gives you a RemoteChild rather than a std::process::Child. Behind the scenes, a remote child is really just a process handle to the local ssh instance corresponding to the spawned remote command. The behavior of the methods of RemoteChild therefore match the behavior of ssh, rather than that of the remote command directly. Usually, these are the same, though not always, as highlighted in the documetantation the individual methods.

Authentication

This library supports only password-less authentication schemes. If running ssh to a target host requires you to provide input on standard input (STDIN), then this crate will not work for you. You should set up keypair-based authentication instead.

Errors

Since we are wrapping the ssh, which in turn runs a remote command that we do not control, we do not have a reliable way to tell the difference between what is a failure of the SSH connection itself, and what is a program error from the remote host. We do our best with some heuristics (like ssh exiting with status code 255 if a connection error occurs), but the errors from this crate will almost necessarily be worse than those of a native SSH implementation. Sorry in advance :)

If you suspect that the connection has failed, Session::check may provide you with more information than you got from the failing command, since it does not execute a remote command that might interfere with extracting error messages.

Examples

use openssh::{Session, KnownHosts};

let session = Session::connect("me@ssh.example.com", KnownHosts::Strict)?;
let ls = session.command("ls").output()?;
eprintln!("{}", String::from_utf8(ls.stdout).expect("server output was not valid UTF-8"));

let whoami = session.command("whoami").output()?;
assert_eq!(whoami.stdout, b"me\n");

session.close()?;

Structs

Command	A remote process builder, providing fine-grained control over how a new remote process should be spawned.
RemoteChild	Representation of a running or exited remote child process.
Session	A single SSH session to a remote host.

Enums

Error	Errors that occur when interacting with a remote process.
KnownHosts	Specifies how the host's key fingerprint should be handled.