Native Single Host Client¶
Native single host non-blocking client. Suitable for running asynchronous commands on a single host.
-
class
pssh.clients.native.single.
SSHClient
(host, user=None, password=None, port=None, pkey=None, alias=None, num_retries=3, retry_delay=5, allow_agent=True, timeout=None, forward_ssh_agent=False, proxy_host=None, proxy_port=None, proxy_pkey=None, proxy_user=None, proxy_password=None, _auth_thread_pool=True, keepalive_seconds=60, identity_auth=True, ipv6_only=False)¶ ssh2-python (libssh2) based non-blocking SSH client.
Parameters: - host (str) – Host name or IP to connect to.
- user (str) – User to connect as. Defaults to logged in user.
- password (str) – Password to use for password authentication.
- alias (str) – Use an alias for this host.
- port (int) – SSH port to connect to. Defaults to SSH default (22)
- pkey (str or bytes) – Private key file path to use for authentication. Path must
be either absolute path or relative to user home directory
like
~/<path>
. Bytes type input is used as private key data for authentication. - num_retries (int) – (Optional) Number of connection and authentication attempts before the client gives up. Defaults to 3.
- retry_delay (int or float) – Number of seconds to wait between retries. Defaults
to
pssh.constants.RETRY_DELAY
- timeout (int or float) – SSH session timeout setting in seconds. This controls timeout setting of authenticated SSH sessions.
- allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSH agent
- identity_auth (bool) – (Optional) set to False to disable attempting to authenticate with default identity files from pssh.clients.base.single.BaseSSHClient.IDENTITIES
- forward_ssh_agent (bool) – Unused - agent forwarding not implemented.
- proxy_host (str) – Connect to target host via given proxy host.
- proxy_port (int) – Port to use for proxy connection. Defaults to self.port
- keepalive_seconds (int) – Interval of keep alive messages being sent to
server. Set to
0
orFalse
to disable. - ipv6_only (bool) – Choose IPv6 addresses only if multiple are available for the host or raise NoIPv6AddressFoundError otherwise. Note this will disable connecting to an IPv4 address if an IP address is provided instead.
Raises: pssh.exceptions.PKeyFileError
on errors finding provided private key.-
close_channel
(channel)¶
-
configure_keepalive
()¶ Configures keepalive on the server for self.keepalive_seconds.
-
copy_file
(local_file, remote_file, recurse=False, sftp=None)¶ Copy local file to host via SFTP.
Parameters: - local_file (str) – Local filepath to copy to remote host
- remote_file (str) – Remote filepath on remote host to copy file to
- recurse (bool) – Whether or not to descend into directories recursively.
- sftp (
ssh2.sftp.SFTP
) – SFTP channel to use instead of creating a new one.
Raises: ValueError
when a directory is supplied tolocal_file
andrecurse
is not setRaises: pssh.exceptions.SFTPError
on SFTP initialisation errorsRaises: pssh.exceptions.SFTPIOError
on I/O errors writing via SFTPRaises: IOError
on local file IO errorsRaises: OSError
on local OS errors like permission denied
-
copy_remote_file
(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')¶ Copy remote file to local host via SFTP.
Parameters: - remote_file (str) – Remote filepath to copy from
- local_file (str) – Local filepath where file(s) will be copied to
- recurse (bool) – Whether or not to recursively copy directories
- encoding (str) – Encoding to use for file paths.
- sftp (
ssh2.sftp.SFTP
) – SFTP channel to use instead of creating a new one.
Raises: ValueError
when a directory is supplied tolocal_file
andrecurse
is not setRaises: pssh.exceptions.SFTPError
on SFTP initialisation errorsRaises: pssh.exceptions.SFTPIOError
on I/O errors reading from SFTPRaises: IOError
on local file IO errorsRaises: OSError
on local OS errors like permission denied
-
disconnect
()¶ Attempt to disconnect session.
Any errors on calling disconnect are suppressed by this function.
-
eagain_write
(write_func, data)¶
-
execute
(cmd, use_pty=False, channel=None)¶ Execute command on remote server.
Parameters: - cmd (str) – Command to execute.
- use_pty (bool) – Whether or not to obtain a PTY on the channel.
- channel (
ssh2.channel.Channel
) – Use provided channel for execute rather than creating a new one.
-
finished
(channel)¶ Checks if remote command has finished - has server sent client EOF.
Return type: bool
-
get_exit_status
(channel)¶ Get exit status code for channel or
None
if not ready.Parameters: channel ( ssh2.channel.Channel
) – The channel to get status from.Return type: int or None
-
mkdir
(sftp, directory)¶ Make directory via SFTP channel.
Parent paths in the directory are created if they do not exist.
Parameters: - sftp (
ssh2.sftp.SFTP
) – SFTP client object - directory (str) – Remote directory to create
Catches and logs at error level remote IOErrors on creating directory.
- sftp (
-
open_session
()¶ Open new channel from session.
Return type: ssh2.channel.Channel
-
poll
(timeout=None)¶ Perform co-operative gevent poll on ssh2 session socket.
Blocks current greenlet only if socket has pending read or write operations in the appropriate direction. :param timeout: Deprecated and unused - to be removed.
-
scp_recv
(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')¶ Copy remote file to local host via SCP.
Note - Remote directory listings are gathered via SFTP when
recurse
is enabled - SCP lacks directory list support. Enabling recursion therefore involves creating an extra SFTP channel and requires SFTP support on the server.Parameters: - remote_file (str) – Remote filepath to copy from
- local_file (str) – Local filepath where file(s) will be copied to
- recurse (bool) – Whether or not to recursively copy directories
- sftp (
ssh2.sftp.SFTP
) – The SFTP channel to use instead of creating a new one. Only used whenrecurse
isTrue
. - encoding (str) – Encoding to use for file paths when recursion is enabled.
Raises: pssh.exceptions.SCPError
on errors copying file.Raises: IOError
on local file IO errors.Raises: OSError
on local OS errors like permission denied.
-
scp_send
(local_file, remote_file, recurse=False, sftp=None)¶ Copy local file to host via SCP.
Note - Directories are created via SFTP when
recurse
is enabled - SCP lacks directory create support. Enabling recursion therefore involves creating an extra SFTP channel and requires SFTP support on the server.Parameters: - local_file (str) – Local filepath to copy to remote host
- remote_file (str) – Remote filepath on remote host to copy file to
- sftp (
ssh2.sftp.SFTP
) – The SFTP channel to use instead of creating a new one. Only used whenrecurse
isTrue
. - recurse (bool) – Whether or not to descend into directories recursively.
Raises: ValueError
when a directory is supplied tolocal_file
andrecurse
is not setRaises: pssh.exceptions.SFTPError
on SFTP initialisation errorsRaises: pssh.exceptions.SFTPIOError
on I/O errors writing via SFTPRaises: IOError
on local file IO errorsRaises: OSError
on local OS errors like permission denied
-
sftp_get
(sftp, remote_file, local_file)¶
-
sftp_put
(sftp, local_file, remote_file)¶ Perform an SFTP put - copy local file path to remote via SFTP.
Parameters: - sftp (
ssh2.sftp.SFTP
) – SFTP client object. - local_file (str) – Local filepath to copy to remote host.
- remote_file (str) – Remote filepath on remote host to copy file to.
Raises: pssh.exceptions.SFTPIOError
on I/O errors writing via SFTP.- sftp (
-
spawn_send_keepalive
()¶ Spawns a new greenlet that sends keep alive messages every self.keepalive_seconds
-
wait_finished
(host_output, timeout=None)¶ Wait for EOF from channel and close channel.
Used to wait for remote command completion and be able to gather exit code.
Parameters: - host_output (
pssh.output.HostOutput
) – Host output of command to wait for. - timeout (float) – Timeout value in seconds - defaults to no timeout.
Raises: pssh.exceptions.Timeout
after <timeout> seconds if timeout given.- host_output (