ssh2.session

class ssh2.session.Session

LibSSH2 Session class providing session functions

agent_auth(self, username)

Convenience function for performing user authentication via SSH Agent.

Initialises, connects to, gets list of identities from and attempts authentication with each identity from SSH agent.

Note that agent connections cannot be used in non-blocking mode - clients should call set_blocking(0) after calling this function.

On completion, or any errors, agent is disconnected and resources freed.

All steps are performed in C space which makes this function perform better than calling the individual Agent class functions from Python.

Raises

MemoryError on error initialising agent

Raises

ssh2.exceptions.AgentConnectionError on error connecting to agent

Raises

ssh2.exceptions.AgentListIdentitiesError on error getting identities from agent

Raises

ssh2.exceptions.AgentAuthenticationError on no successful authentication with all available identities.

Raises

ssh2.exceptions.AgentGetIdentityError on error getting known identity from agent

Return type

None

agent_init(self)

Initialise SSH agent.

Return type

ssh2.agent.Agent

block_directions(self)

Get blocked directions for the current session.

From libssh2 documentation:

Can be a combination of:

ssh2.session.LIBSSH2_SESSION_BLOCK_INBOUND: Inbound direction blocked.

ssh2.session.LIBSSH2_SESSION_BLOCK_OUTBOUND: Outbound direction blocked.

Application should wait for data to be available for socket prior to calling a libssh2 function again. If LIBSSH2_SESSION_BLOCK_INBOUND is set select should contain the session socket in readfds set.

Correspondingly in case of LIBSSH2_SESSION_BLOCK_OUTBOUND writefds set should contain the socket.

Return type

int

direct_tcpip(self, host, int port)

Open direct TCP/IP channel to host:port

Channel will be listening on an available open port on client side as assigned by OS.

direct_tcpip_ex(self, host, int port, shost, int sport)
disconnect(self)
flag(self, set_flag, value)

Set options for the session.

set_flag is the option to set, while value is typically set to 1 or 0 to enable or disable the option.

Valid flags are:

  • ssh2.session.LIBSSH2_FLAG_SIGPIPE

    If set, libssh2 will not attempt to block SIGPIPEs but will let them trigger from the underlying socket layer.

  • ssh2.session.LIBSSH2_FLAG_COMPRESS

    If set - before the connection negotiation is performed - libssh2 will try to negotiate compression enabling for this connection. By default libssh2 will not attempt to use compression.

Must be called before self.handshake() if you wish to change options.

Raises

ssh2.exceptions.MethodNotSupported on an incorrect flag or value argument(s).

Parameters
  • set_flag (ssh2.session.LIBSSH2_METHOD_*) – Flag to set. See above for options.

  • value – Value that set_flag will be set to. Must be 0 or

1. :type value: int :rtype: int

forward_listen(self, int port)

Create forward listener on port.

Parameters

port (int) – Port to listen on.

Return type

ssh2.listener.Listener or None

forward_listen_ex(self, host, int port, int bound_port, int queue_maxsize)
get_blocking(self)

Get session blocking mode enabled True/False.

Return type

bool

get_timeout(self)

Get current session timeout setting

handshake(self, sock)

Perform SSH handshake.

Must be called after Session initialisation.

hostkey(self)

Get server host key for this session.

Returns key, key_type tuple where key_type is one of ssh2.session.LIBSSH2_HOSTKEY_TYPE_RSA, ssh2.session.LIBSSH2_HOSTKEY_TYPE_DSS, or ssh2.session.LIBSSH2_HOSTKEY_TYPE_UNKNOWN

Return type

tuple(bytes, int)

hostkey_hash(self, int hash_type)

Get computed digest of the remote system’s host key.

Parameters

hash_type (int) – One of ssh2.session.LIBSSH2_HOSTKEY_HASH_MD5 or ssh2.session.LIBSSH2_HOSTKEY_HASH_SHA1

Return type

bytes

keepalive_config(self, bool want_reply, unsigned int interval)

Configure keep alive settings.

Parameters
  • want_reply (bool) – True/False for reply wanted from server on keep alive messages being sent or not.

  • interval (int) – Required keep alive interval. Set to 0 to disable keepalives.

keepalive_send(self)

Send keepalive.

Returns seconds remaining before next keep alive should be sent.

Return type

int

knownhost_init(self)

Initialise a collection of known hosts for this session.

Return type

ssh2.knownhost.KnownHost

last_errno(self)

Retrieve last error number from libssh2, if any. Returns 0 on no last error.

Return type

int

last_error(self, size_t msg_size=1024)

Retrieve last error message from libssh2, if any. Returns empty string on no error message.

Return type

str

method_pref(self, method_type, pref_methods)

Set internal perferences based on method_type to pref_methods.

Valid method_type options are:

  • LIBSSH2_METHOD_KEX

    For key exchange.

  • LIBSSH2_METHOD_HOSTKEY

    For selecting host key type.

  • LIBSSH2_METHOD_CRYPT_CS

    Encryption between client to server

  • LIBSSH2_METHOD_CRYPT_SC

    Encryption between server to client

  • LIBSSH2_METHOD_MAC_CS

    MAC between client to server

  • LIBSSH2_METHOD_MAC_SC

    MAC between server to client

  • LIBSSH2_METHOD_COMP_CS

    Compression between client to server

  • LIBSSH2_METHOD_COMP_SC

    Compression between server to client

  • LIBSSH2_METHOD_LANG_CS

    Language between client to server

  • LIBSSH2_METHOD_LANG_SC

    Language between server to client

Valid options that end in CS are from the client to the server and the inverse is true as well.

Valid pref_methods options are dependant on the method_type selected. Refer to the libssh2 docs

Must be called before self.handshake() if you wish to change the defaults.

Return 0 on success or negative on failure. It returns ssh2.error_codes.LIBSSH2_ERROR_EAGAIN when it would otherwise block. While ssh2.error_codes.LIBSSH2_ERROR_EAGAIN is a negative number, it isn’t really a failure per se.

Raises

ssh2.exceptions.MethodNotSupported on an incorrect method_type or pref_methods argument(s).

Parameters
  • method_type (ssh2.session.LIBSSH2_METHOD_*) – Method perference to change.

  • pref_methods – Coma delimited list as a bytes string of preferred

methods to use with the most preferred listed first and the least preferred listed last. If a method is listed which is not supported by libssh2 it will be ignored and not sent to the remote host during protocol negotiation. :type pref_methods: bytes :rtype: int

methods(self, method_type)

Get internal perferences used to negotiate based on method_type.

Valid method_type options are:

  • LIBSSH2_METHOD_KEX

    For key exchange.

  • LIBSSH2_METHOD_HOSTKEY

    For selecting host key type.

  • LIBSSH2_METHOD_CRYPT_CS

    Encryption between client to server

  • LIBSSH2_METHOD_CRYPT_SC

    Encryption between server to client

  • LIBSSH2_METHOD_MAC_CS

    MAC between client to server

  • LIBSSH2_METHOD_MAC_SC

    MAC between server to client

  • LIBSSH2_METHOD_COMP_CS

    Compression between client to server

  • LIBSSH2_METHOD_COMP_SC

    Compression between server to client

  • LIBSSH2_METHOD_LANG_CS

    Language between client to server

  • LIBSSH2_METHOD_LANG_SC

    Language between server to client

Valid options that end in CS are from the client to the server and the inverse is true as well.

Raises

ssh2.exceptions.MethodNotSupported on an incorrect method_type argument.

Parameters

method_type (ssh2.session.LIBSSH2_METHOD_*) – Method type.

Return type

bytes

open_session(self)

Open new channel session.

Return type

ssh2.channel.Channel

publickey_init(self)

Initialise public key subsystem for managing remote server public keys

scp_recv(self, path)

Receive file via SCP.

Deprecated in favour or recv2 (requires libssh2 >= 1.7).

Parameters

path (str) – File path to receive.

Return type

tuple(ssh2.channel.Channel, ssh2.statinfo.StatInfo) or None

scp_recv2(self, path)

Receive file via SCP.

Available only on libssh2 >= 1.7.

Parameters

path (str) – File path to receive.

Return type

tuple(ssh2.channel.Channel, ssh2.fileinfo.FileInfo) or None

scp_send(self, path, int mode, size_t size)

Deprecated in favour of scp_send64. Send file via SCP.

Parameters
  • path (str) – Local file path to send.

  • mode (int) – File mode.

  • size (int) – size of file

Return type

ssh2.channel.Channel

scp_send64(self, path, int mode, libssh2_uint64_t size, time_t mtime, time_t atime)

Send file via SCP.

Parameters
  • path (str) – Local file path to send.

  • mode (int) – File mode.

  • size (int) – size of file

Return type

ssh2.channel.Channel

set_blocking(self, bool blocking)

Set session blocking mode on/off.

Parameters

blocking (bool) – False for non-blocking, True for blocking. Session default is blocking unless set otherwise.

set_last_error(self, int errcode, errmsg)
set_timeout(self, long timeout)

Set the timeout in milliseconds for how long a blocking call may wait until the situation is considered an error and ssh2.error_codes.LIBSSH2_ERROR_TIMEOUT is returned.

By default or if timeout set is zero, blocking calls do not time out. :param timeout: Milliseconds to wait before timeout.

sftp_init(self)

Initialise SFTP channel.

Return type

ssh2.sftp.SFTP

startup(self, sock)

Deprecated - use self.handshake

supported_algs(self, method_type, algs)

Get the supported internal perferences based on method_type and algs.

Valid method_type options are:

  • LIBSSH2_METHOD_KEX

    For key exchange.

  • LIBSSH2_METHOD_HOSTKEY

    For selecting host key type.

  • LIBSSH2_METHOD_CRYPT_CS

    Encryption between client to server

  • LIBSSH2_METHOD_CRYPT_SC

    Encryption between server to client

  • LIBSSH2_METHOD_MAC_CS

    MAC between client to server

  • LIBSSH2_METHOD_MAC_SC

    MAC between server to client

  • LIBSSH2_METHOD_COMP_CS

    Compression between client to server

  • LIBSSH2_METHOD_COMP_SC

    Compression between server to client

  • LIBSSH2_METHOD_LANG_CS

    Language between client to server

  • LIBSSH2_METHOD_LANG_SC

    Language between server to client

Raises

ssh2.exceptions.MethodNotSupported on an incorrect method_type or algs argument(s).

Parameters
  • method_type (ssh2.session.LIBSSH2_METHOD_*) – Method type.

  • algs (bytes str) – Coma delimited list as a bytes string.

Return type

array

userauth_authenticated(self)

True/False for is user authenticated or not.

Return type

bool

userauth_hostbased_fromfile(self, username, privatekey, hostname, publickey=None, passphrase='')
userauth_keyboardinteractive(self, username, password)

Perform keyboard-interactive authentication

Parameters
  • username (str) – User name to authenticate.

  • password (str) – Password

userauth_list(self, username)

Retrieve available authentication methods list.

Return type

list

userauth_password(self, username, password)

Perform password authentication

Parameters
  • username (str) – User name to authenticate.

  • password (str) – Password

userauth_publickey(self, username, bytes pubkeydata)

Perform public key authentication with provided public key data

Parameters
  • username (str) – User name to authenticate as

  • pubkeydata (bytes) – Public key data

Return type

int

userauth_publickey_fromfile(self, username, privatekey, passphrase='', publickey=None)

Authenticate with public key from file.

Return type

int

userauth_publickey_frommemory(self, username, bytes privatekeyfiledata, passphrase='', bytes publickeyfiledata=None)
sock