Trait openssh::OverSsh

pub trait OverSsh {
    // Required method
    fn over_ssh<S: Deref<Target = Session> + Clone>(
        &self,
        session: S
    ) -> Result<OwningCommand<S>, Error>;
}

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

Primarily a way to allow std::process::Command to be turned directly into an openssh::Command.

Required Methods

fn over_ssh<S: Deref<Target = Session> + Clone>( &self, session: S ) -> Result<OwningCommand<S>, Error>

Given an ssh session, return a command that can be executed over that ssh session.

Notes

The command to be executed on the remote machine should not explicitly set environment variables or the current working directory. It errors if the source command has environment variables or a current working directory set, since openssh doesn’t (yet) have a method to set environment variables and ssh doesn’t support setting a current working directory outside of bash/dash/zsh (which is not always available).

Examples

1. Consider the implementation of OverSsh for std::process::Command. Let’s build a ls -l -a -h command and execute it over an SSH session.

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    use std::process::Command;
    use openssh::{Session, KnownHosts, OverSsh};

    let session = Session::connect_mux("me@ssh.example.com", KnownHosts::Strict).await?;
    let ls =
        Command::new("ls")
        .arg("-l")
        .arg("-a")
        .arg("-h")
        .over_ssh(&session)?
        .output()
        .await?;

    assert!(String::from_utf8(ls.stdout).unwrap().contains("total"));
}

2. Building a command with environment variables or a current working directory set will results in an error.

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    use std::process::Command;
    use openssh::{Session, KnownHosts, OverSsh};

    let session = Session::connect_mux("me@ssh.example.com", KnownHosts::Strict).await?;
    let echo =
        Command::new("echo")
        .env("MY_ENV_VAR", "foo")
        .arg("$MY_ENV_VAR")
        .over_ssh(&session);
    assert!(matches!(echo, Err(openssh::Error::CommandHasEnv)));

}

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl OverSsh for Command

fn over_ssh<S: Deref<Target = Session> + Clone>( &self, session: S ) -> Result<OwningCommand<S>, Error>

impl OverSsh for Command

fn over_ssh<S: Deref<Target = Session> + Clone>( &self, session: S ) -> Result<OwningCommand<S>, Error>

impl<S> OverSsh for &S

where S: OverSsh,

fn over_ssh<U: Deref<Target = Session> + Clone>( &self, session: U ) -> Result<OwningCommand<U>, Error>

impl<S> OverSsh for &mut S

where S: OverSsh,

fn over_ssh<U: Deref<Target = Session> + Clone>( &self, session: U ) -> Result<OwningCommand<U>, Error>

Implementors