Crate ssh2

Expand description

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();

// Write the file
let mut remote_file = sess.scp_send(Path::new("remote"),
                                    0o644, 10, None).unwrap();
remote_file.write(b"1234567890").unwrap();
// Close the channel and wait for the whole content to be transferred
remote_file.send_eof().unwrap();
remote_file.wait_eof().unwrap();
remote_file.close().unwrap();
remote_file.wait_close().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();

// Close the channel and wait for the whole content to be tranferred
remote_file.send_eof().unwrap();
remote_file.wait_eof().unwrap();
remote_file.close().unwrap();
remote_file.wait_close().unwrap();

§Execute a Netconf XML payload

use ssh2::{Channel, Session};
use std::error::Error;
use std::io::prelude::*;
use std::net::TcpStream;
 
const HELLO: &str = "<hello xmlns=\"urn:ietf:params:xml:ns:netconf:base:1.0\">
  <capabilities>
    <capability>urn:ietf:params:netconf:base:1.1</capability>
  </capabilities>
</hello>
]]>]]>";
 
const PAYLOAD: &str = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
    <rpc xmlns=\"urn:ietf:params:xml:ns:netconf:base:1.1\" message-id=\"2\">
    <cli xmlns=\"http://cisco.com/ns/yang/cisco-nx-os-device\"><mode>EXEC</mode><cmdline>show version</cmdline></cli>
</rpc>";
 
fn read(channel: &mut Channel) -> Result<String, Box<dyn Error>> {
    let mut result = String::new();
    loop {
        // If you plan to use this, be aware that reading 1 byte at a time is terribly
        // inefficient and should be optimized for your usecase. This is just an example.
        let mut buffer = [1u8; 1];
        let bytes_read = channel.read(&mut buffer[..])?;
        let s = String::from_utf8_lossy(&buffer[..bytes_read]);
        result.push_str(&s);
        if result.ends_with("]]>]]>") {
            println!("Found netconf 1.0 terminator, breaking read loop");
            break;
        }
        if result.ends_with("##") {
            println!("Found netconf 1.1 terminator, breaking read loop");
            break;
        }
        if bytes_read == 0 || channel.eof() {
            println!("Buffer is empty, SSH channel read terminated");
            break;
        }
    }
    Ok(result)
}
 
fn main() -> Result<(), Box<dyn Error>> {
    let tcp = TcpStream::connect("127.0.0.1:830")?;
    let mut sess = Session::new()?;
    sess.set_tcp_stream(tcp);
    sess.handshake().unwrap();
    sess.userauth_password("user", "pass")?;
 
    let mut channel = sess.channel_session()?;
    channel.subsystem("netconf")?;
    let result = read(&mut channel)?;
    println!("Result from connection:\n{}", result);
 
    let payload = format!("{}\n#{}\n{}\n##\n", HELLO, PAYLOAD.len(), PAYLOAD);
    let a = channel.write(payload.as_bytes())?;
    println!("Written {} bytes payload", a);
    let result = read(&mut channel)?;
    println!("Result from payload execution:\n{}", result);
 
    channel.send_eof()?;
    channel.wait_eof()?;
    channel.close()?;
    channel.wait_close()?;
    Ok(())
}

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.
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.
TraceFlags
Flags which can be used with the session trace method to set the trace level.
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
ErrorCode
An error code originating from a particular source.
ExtendedData
How to handle extended data streams, such as stderr
ExtensiblePtyModeOpcode
An opcode for setting a Pty terminal mode
FileType
An enum representing a type of file.
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.

Crate ssh2Copy item path