Crate openssh

source ·
Expand description

Scriptable SSH through OpenSSH (only works on unix).

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.

§Executing remote processes

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.

Note that the maximum number of multiplexed remote commands is 10 by default. This value can be increased by changing the MaxSessions setting in sshd_config.

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 OwningCommand 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 Child 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. See also the section below on Remote Shells.

§Connection modes

This library provides two way to connect to the ControlMaster:

One is to spawn a new process, the other is to connect to the control socket directly.

The process implementation executes remote commands by invoking the ssh command locally with arguments that make the invocation reuse the connections set up by the control master.

This maximizes compatibility with OpenSSH, but loses out on some fidelity in information about execution since only the exit code and the output of the ssh command is available to inspect.

The native mux implementation on the other hand connects directly to the ssh control master and executes commands and retrieves the exit codes and the output of the remote process over its native protocol.

This gives better access to error information at the cost of introducing more non-OpenSSH code into the call path.

The former parses the stdout/stderr of the ssh control master to retrieve the error for any failed operations, while the later retrieves the error from the control socket directly.

Thus, the error handling in the later is more robust.

Also, the former requires one process to be spawn for every connection while the later only needs to create one socket, so the later has better performance and consumes less resource.

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.

§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 :)

This also means that you may see strange errors when the remote process is terminated by a signal (such as through kill or pkill). When this happens, all the local ssh program sees is that the remote process disappeared, and so it returns with an error. It does not communicate that the process exited due to a signal. In cases like this, your call will return Error::Disconnected, because the connection to that remote process was disconnected. The ssh connection as a whole is likely still intact.

To check if the connection has truly failed, use Session::check. It will return Ok if the master connection is still operational, and may provide you with more information than you got from the failing command (that is, just Error::Disconnected) if it is not.

§Remote Shells

When you invoke a remote command through ssh, the remote command is executed by a shell on the remote end. That shell interprets anything passed to it — it might evalute words starting with $ as variables, split arguments by whitespace, and other things a shell is wont to do. Since that is usually not what you expect to happen, .arg("a b") should pass a single argument with the value a b, openssh escapes every argument (and the command itself) by default using shell-escape. This works well in most cases, but might run into issues when the remote shell (generally the remote user’s login shell) has a different syntax than the shell shell-escape targets (bash). For example, Windows shells have different escaping syntax than bash does.

If this applies to you, you can use raw_arg, raw_args, and raw_command to bypass the escaping that openssh normally does for you.

§Sftp subsystem

For sftp and other ssh subsystem, check Session::subsystem for more information.

§Examples

use openssh::{Session, KnownHosts};

let session = Session::connect_mux("me@ssh.example.com", KnownHosts::Strict).await?;

let ls = session.command("ls").output().await?;
eprintln!("{}", String::from_utf8(ls.stdout).expect("server output was not valid UTF-8"));

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

session.close().await?;

Modules§

  • changelog
    Changelog for this crate.
  • process
    Types to create and interact with the Remote Process

Structs§

  • Child
    Representation of a running or exited remote child process.
  • ChildStderr
    Stderr for the remote child.
  • ChildStdin
    Input for the remote child.
  • ChildStdout
    Stdout for the remote child.
  • OwningCommand
    A remote process builder, providing fine-grained control over how a new remote process should be spawned.
  • Session
    A single SSH session to a remote host.
  • SessionBuilder
    Build a Session with options.
  • Stdio
    Describes what to do with a standard I/O stream for a remote child process when passed to the stdin, stdout, and stderr methods of Command.

Enums§

  • Error
    Errors that occur when interacting with a remote process.
  • ForwardType
    Type of forwarding
  • KnownHosts
    Specifies how the host’s key fingerprint should be handled.
  • Socket
    TCP/Unix socket

Traits§

  • OverSsh
    If a command is OverSsh then it can be executed over an SSH session.

Type Aliases§