[−][src]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.
And finally, our commands never default to inheriting stdin/stdout/stderr, since we expect you
are using this to automate things. Instead, unless otherwise noted, all I/O ports default to
Stdio::null
.
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. |
SessionBuilder | Build a |
Enums
Error | Errors that occur when interacting with a remote process. |
KnownHosts | Specifies how the host's key fingerprint should be handled. |