ssh2.session¶
- class ssh2.session.MethodType¶
- 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
- 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)¶
- 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, int queue_maxsize, host=None, int port=0)¶
Instruct the remote SSH server to begin listening for inbound TCP/IP connections. New connections will be queued by the library until accepted by
ssh2.channel.Channel.forward_accept
.- Parameters
queue_maxsize (int) – Maximum number of pending connections to queue before rejecting further attempts.
host (str) – Address to bind to on the remote host. Binding to 0.0.0.0 (default when None is passed) will bind to all available addresses.
port (int) – port to bind to on the remote host. When 0 is passed (the default), the remote host will select the first available dynamic port.
- Returns
(listener, bound_port) tuple where bound_port is the listen port bound on the remote host. Useful when requesting dynamic port numbers.
- Return type
(
ssh2.listener.Listener
, int)
- 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
, orssh2.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
orssh2.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
- 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, MethodType method_type, prefs)¶
Set preference for session method.
See
Session.supported_algs()
for supported algorithms for method type.- Parameters
method_type (
MethodType
) – A supported session method LIBSSH2_METHOD_*prefs (str) – Algorithm preference for method type provided.
- Return type
int
- Raises
ssh2.exceptions.MethodNotSupported
on unsupported method preference
- methods(self, MethodType method_type)¶
Get currently active algorithms for method type.
- Parameters
method_type (
MethodType
) – Type of method to get- Return type
str
- open_session(self)¶
Open new channel session.
- Return type
- 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
) orNone
- 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
- 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
- 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
- startup(self, sock)¶
Deprecated - use self.handshake
- supported_algs(self, MethodType method_type)¶
Get supportd algorithms for method type.
- Parameters
method_type (
MethodType
) – Type of method to get- Returns
List of supported algorithms.
- Return type
list(str)
- 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¶