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 |
Hosts |
Iterator over the hosts in a |
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 |
RenameFlags |
Options to |
ScpFileStat |
Metadata returned about a remote file when received via |
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 |
WriteWindow |
Description of the write window as returned by |
Enums
CheckResult |
Possible results of a call to |
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 |
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 |
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 |
FLUSH_ALL |
When passed to |
FLUSH_EXTENDED_DATA |
When passed to |
Functions
init |
Initialize the libssh2 library. |