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
-
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
-
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, whilevalue
is typically set to1
or0
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 incorrectflag
orvalue
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 be0
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_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
-
hostkey_hash
(self, int hash_type)¶ Get computed digest of the remote system’s host key.
-
keepalive_config
(self, bool want_reply, unsigned int interval)¶ Configure keep alive settings.
-
keepalive_send
(self)¶ Send keepalive.
Returns seconds remaining before next keep alive should be sent.
- Return type
-
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
-
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
-
method_pref
(self, method_type, pref_methods)¶ Set internal perferences based on
method_type
topref_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 themethod_type
selected. Refer to the libssh2 docsMust 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. Whilessh2.error_codes.LIBSSH2_ERROR_EAGAIN
is a negative number, it isn’t really a failure per se.- Raises
ssh2.exceptions.MethodNotSupported
on an incorrectmethod_type
orpref_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 incorrectmethod_type
argument.- Parameters
method_type (
ssh2.session.LIBSSH2_METHOD_*
) – Method type.- Return type
bytes
-
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
- Return type
-
scp_send64
(self, path, int mode, libssh2_uint64_t size, time_t mtime, time_t atime)¶ Send file via SCP.
- Parameters
- 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, method_type, algs)¶ Get the supported internal perferences based on
method_type
andalgs
.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 incorrectmethod_type
oralgs
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_hostbased_fromfile
(self, username, privatekey, hostname, publickey=None, passphrase='')¶
-
userauth_keyboardinteractive
(self, username, password)¶ Perform keyboard-interactive authentication
-
userauth_password
(self, username, password)¶ Perform password authentication
-
userauth_publickey
(self, username, bytes pubkeydata)¶ Perform public key authentication with provided public key data
-
userauth_publickey_fromfile
(self, username, privatekey, passphrase='', publickey=None)¶ Authenticate with public key from file.
- Return type
-
userauth_publickey_frommemory
(self, username, bytes privatekeyfiledata, passphrase='', bytes publickeyfiledata=None)¶
-
sock
¶
-