[][src]Crate ssh2

Rust bindings to libssh2, an SSH client library.

This library intends to provide a safe interface to the libssh2 library. It will build the library if it's not available on the local system, and otherwise link to an installed copy.

Note that libssh2 only supports SSH clients, not SSH servers. Additionally it only supports protocol v2, not protocol v1.

Examples

Inspecting ssh-agent

use ssh2::Session;

// Almost all APIs require a `Session` to be available
let sess = Session::new().unwrap();
let mut agent = sess.agent().unwrap();

// Connect the agent and request a list of identities
agent.connect().unwrap();
agent.list_identities().unwrap();

for identity in agent.identities().unwrap() {
    println!("{}", identity.comment());
    let pubkey = identity.blob();
}

Authenticating with ssh-agent

use std::net::TcpStream;
use ssh2::Session;

// Connect to the local SSH server
let tcp = TcpStream::connect("127.0.0.1:22").unwrap();
let mut sess = Session::new().unwrap();
sess.set_tcp_stream(tcp);
sess.handshake().unwrap();

// Try to authenticate with the first identity in the agent.
sess.userauth_agent("username").unwrap();

// Make sure we succeeded
assert!(sess.authenticated());

Authenticating with a password

use std::net::TcpStream;
use ssh2::Session;

// Connect to the local SSH server
let tcp = TcpStream::connect("127.0.0.1:22").unwrap();
let mut sess = Session::new().unwrap();
sess.set_tcp_stream(tcp);
sess.handshake().unwrap();

sess.userauth_password("username", "password").unwrap();
assert!(sess.authenticated());

Run a command

use std::io::prelude::*;
use std::net::{TcpStream};
use ssh2::Session;

// Connect to the local SSH server
let tcp = TcpStream::connect("127.0.0.1:22").unwrap();
let mut sess = Session::new().unwrap();
sess.set_tcp_stream(tcp);
sess.handshake().unwrap();
sess.userauth_agent("username").unwrap();

let mut channel = sess.channel_session().unwrap();
channel.exec("ls").unwrap();
let mut s = String::new();
channel.read_to_string(&mut s).unwrap();
println!("{}", s);
channel.wait_close();
println!("{}", channel.exit_status().unwrap());

Upload a file

use std::io::prelude::*;
use std::net::TcpStream;
use std::path::Path;
use ssh2::Session;

// Connect to the local SSH server
let tcp = TcpStream::connect("127.0.0.1:22").unwrap();
let mut sess = Session::new().unwrap();
sess.set_tcp_stream(tcp);
sess.handshake().unwrap();
sess.userauth_agent("username").unwrap();

let mut remote_file = sess.scp_send(Path::new("remote"),
                                    0o644, 10, None).unwrap();
remote_file.write(b"1234567890").unwrap();

Download a file

use std::io::prelude::*;
use std::net::TcpStream;
use std::path::Path;
use ssh2::Session;

// Connect to the local SSH server
let tcp = TcpStream::connect("127.0.0.1:22").unwrap();
let mut sess = Session::new().unwrap();
sess.set_tcp_stream(tcp);
sess.handshake().unwrap();
sess.userauth_agent("username").unwrap();

let (mut remote_file, stat) = sess.scp_recv(Path::new("remote")).unwrap();
println!("remote file size: {}", stat.size());
let mut contents = Vec::new();
remote_file.read_to_end(&mut contents).unwrap();
// ...

Re-exports

pub use DisconnectCode::AuthCancelledByUser;
pub use DisconnectCode::TooManyConnections;
pub use DisconnectCode::ByApplication;
pub use DisconnectCode::ConnectionLost;
pub use DisconnectCode::HostKeyNotVerifiable;
pub use DisconnectCode::CompressionError;
pub use DisconnectCode::KeyExchangeFailed;
pub use DisconnectCode::MacError;
pub use DisconnectCode::Reserved;
pub use DisconnectCode::HostNotAllowedToConnect;
pub use DisconnectCode::ProtocolError;
pub use DisconnectCode::IllegalUserName;
pub use DisconnectCode::NoMoreAuthMethodsAvailable;
pub use DisconnectCode::ProtocolVersionNotSupported;
pub use DisconnectCode::ServiceNotAvailable;

Structs

Agent

A structure representing a connection to an SSH agent.

Channel

A channel represents a portion of an SSH connection on which data can be read and written.

Error

Representation of an error that can occur within libssh2

ExitSignal

Data received from when a program exits with a signal.

File

A file handle to an SFTP connection.

FileStat

Metadata information about a remote file.

FileType

An structure representing a type of file.

Host

Structure representing a known host as part of a KnownHosts structure.

KnownHosts

A set of known hosts which can be used to verify the identity of a remote server.

Listener

A listener represents a forwarding port from the remote server.

OpenFlags

Options that can be used to configure how a file is opened

Prompt

A prompt/challenge returned as part of keyboard-interactive authentication

PtyModes

Encodes modes for Pty allocation requests. The modes documented in https://tools.ietf.org/html/rfc4250#section-4.5 are supported.

PublicKey

A public key which is extracted from an SSH agent.

ReadWindow

Description of the read window as returned by Channel::read_window

RenameFlags

Options to Sftp::rename.

ScpFileStat

Metadata returned about a remote file when received via scp.

Session

An SSH session, typically representing one TCP connection.

Sftp

A handle to a remote filesystem over SFTP.

Stream

A channel can have a number of streams, each identified by an id, each of which implements the Read and Write traits.

WriteWindow

Description of the write window as returned by Channel::write_window

Enums

BlockDirections

The io direction an application has to wait for in order not to block.

CheckResult

Possible results of a call to KnownHosts::check

DisconnectCode
ExtendedData

How to handle extended data streams, such as stderr

ExtensiblePtyModeOpcode

An opcode for setting a Pty terminal mode

HashType
HostKeyType
KnownHostFileKind
KnownHostKeyFormat
MethodType
OpenType

How to open a file handle with libssh2.

PtyModeOpcode

The modes described in https://tools.ietf.org/html/rfc4250#section-4.5.2

Statics

EXTENDED_DATA_STDERR

Stream ID of the stderr channel for stream-related methods on Channel

FLUSH_ALL

When passed to Channel::flush_stream, flushes all substream.

FLUSH_EXTENDED_DATA

When passed to Channel::flush_stream, flushes all extended data substreams.

Traits

KeyboardInteractivePrompt

Called by libssh2 to respond to some number of challenges as part of keyboard interactive authentication.

Functions

init

Initialize the libssh2 library.