[−][src]Struct openssh::Session
A single SSH session to a remote host.
You can use [command
] to start a new command on the connected machine.
When the Session
is dropped, the connection to the remote host is severed, and any errors
silently ignored. To disconnect and be alerted to errors, use close
.
Implementations
impl Session
[src]
pub async fn connect<S: AsRef<str>>(
destination: S,
check: KnownHosts
) -> Result<Self, Error>
[src]
destination: S,
check: KnownHosts
) -> Result<Self, Error>
Connect to the host at the given addr
over SSH.
The format of destination
is the same as the destination
argument to ssh
. It may be
specified as either [user@]hostname
or a URI of the form ssh://[user@]hostname[:port]
.
If connecting requires interactive authentication based on STDIN
(such as reading a
password), the connection will fail. Consider setting up keypair-based authentication
instead.
For more options, see SessionBuilder
.
pub async fn check<'_>(&'_ self) -> Result<(), Error>
[src]
Check the status of the underlying SSH connection.
Since this does not run a remote command, it has a better chance of extracting useful error messages than other commands.
pub fn command<'a, S: Into<Cow<'a, str>>>(&self, program: S) -> Command<'_>
[src]
Constructs a new Command
for launching the program at path program
on the remote
host.
Before it is passed to the remote host, program
is escaped so that special characters
aren't evaluated by the remote shell. If you do not want this behavior, use
[raw_command
].
The returned Command
is a builder, with the following default configuration:
- No arguments to the program
- Empty stdin and dsicard stdout/stderr for
spawn
orstatus
, but create output pipes foroutput
Builder methods are provided to change these defaults and otherwise configure the process.
If program
is not an absolute path, the PATH
will be searched in an OS-defined way on
the host.
pub fn raw_command<S: AsRef<OsStr>>(&self, program: S) -> Command<'_>
[src]
Constructs a new Command
for launching the program at path program
on the remote
host.
Unlike [command
], this method does not shell-escape program
, so it may be evaluated in
unforeseen ways by the remote shell.
The returned Command
is a builder, with the following default configuration:
- No arguments to the program
- Empty stdin and dsicard stdout/stderr for
spawn
orstatus
, but create output pipes foroutput
Builder methods are provided to change these defaults and otherwise configure the process.
If program
is not an absolute path, the PATH
will be searched in an OS-defined way on
the host.
pub fn shell<S: AsRef<str>>(&self, command: S) -> Command<'_>
[src]
Constructs a new Command
that runs the provided shell command on the remote host.
The provided command is passed as a single, escaped argument to sh -c
, and from that
point forward the behavior is up to sh
. Since this executes a shell command, keep in mind
that you are subject to the shell's rules around argument parsing, such as whitespace
splitting, variable expansion, and other funkyness. I highly recommend you read this
article if you observe strange things.
While the returned Command
is a builder, like for [command
], you should not add
additional arguments to it, since the arguments are already passed within the shell
command.
Non-standard Remote Shells
It is worth noting that there are really two shells at work here: the one that sshd
launches for the session, and that launches are command; and the instance of sh
that we
launch in that session. This method tries hard to ensure that the provided command
is
passed exactly as-is to sh
, but this is complicated by the presence of the "outer" shell.
That outer shell may itself perform argument splitting, variable expansion, and the like,
which might produce unintuitive results. For example, the outer shell may try to expand a
variable that is only defined in the inner shell, and simply produce an empty string in the
variable's place by the time it gets to sh
.
To counter this, this method assumes that the remote shell (the one launched by sshd
) is
POSIX compliant. This is more or less equivalent to "supports bash
syntax" if you don't
look too closely. It uses shell-escape
to escape command
before sending it to the
remote shell, with the expectation that the remote shell will only end up undoing that one
"level" of escaping, thus producing the original command
as an argument to sh
. This
works most of the time.
With sufficiently complex or weird commands, the escaping of shell-escape
may not fully
match the "un-escaping" of the remote shell. This will manifest as escape characters
appearing in the sh
command that you did not intend to be there. If this happens, try
changing the remote shell if you can, or fall back to [command
] and do the escaping
manually instead.
pub fn sftp(&self) -> Sftp<'_>
[src]
Prepare to perform file operations on the remote host.
See Sftp
for details on how to interact with the remote files.
pub async fn close(__arg0: Self) -> Result<(), Error>
[src]
Terminate the remote connection.
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for Session
impl Send for Session
impl Sync for Session
impl Unpin for Session
impl UnwindSafe for Session
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,