Crate ssh2 [−] [src]

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() {
    let identity = identity.unwrap(); // assume no I/O errors
    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.handshake(&tcp).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.handshake(&tcp).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.handshake(&tcp).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);
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.handshake(&tcp).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.handshake(&tcp).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();
// ...

Reexports

pub use DisconnectCode::{HostNotAllowedToConnect, ProtocolError};

pub use DisconnectCode::{KeyExchangeFailed, Reserved, MacError, CompressionError};

pub use DisconnectCode::{ServiceNotAvailable, ProtocolVersionNotSupported};

pub use DisconnectCode::{HostKeyNotVerifiable, ConnectionLost, ByApplication};

pub use DisconnectCode::{TooManyConnections, AuthCancelledByUser};

pub use DisconnectCode::{NoMoreAuthMethodsAvailable, IllegalUserName};

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.
Host	Structure representing a known host as part of a `KnownHosts` structure.
Hosts	Iterator over the hosts in a `KnownHosts` structure.
Identities	An iterator over the identities found in an SSH agent.
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
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

CheckResult	Possible results of a call to `KnownHosts::check`
DisconnectCode
HashType
HostKeyType
KnownHostFileKind
KnownHostKeyFormat
MethodType
OpenType	How to open a file handle with libssh2.

Constants

APPEND	Force all writes to append data at the end of the file.
ATOMIC	Inform the remote that an atomic rename operation is desired if available
CREATE	If this flag is specified, then a new file will be created if one does not already exist (if Truncate is specified, the new file will be truncated to zero length if it previously exists)
EXCLUSIVE	Causes the request to fail if the named file already exists. Using this flag implies the `Create` flag.
NATIVE	Inform the remote end that the native system calls for renaming should be used
OVERWRITE	In a rename operation, overwrite the destination if it already exists. If this flag is not present then it is an error if the destination already exists
READ	Open the file for reading.
TRUNCATE	Forces an existing file with the same name to be truncated to zero length when creating a file by specifying `Create`. Using this flag implies the `Create` flag.
WRITE	Open the file for writing. If both this and Read are specified, the file is opened for both reading and writing

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.

Functions

init	Initialize the libssh2 library.