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, 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)

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.

  • port (int) – SSH port to connect to. Defaults to SSH default (22)

  • pkey (str) – Private key file path to use for authentication. Path must be either absolute path or relative to user home directory like ~/<path>.

  • num_retries (int) – (Optional) Number of connection and authentication attempts before the client gives up. Defaults to 3.

  • retry_delay (int) – Number of seconds to wait between retries. Defaults to pssh.constants.RETRY_DELAY

  • timeout (int) – 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 – Interval of keep alive messages being sent to server. Set to 0 or False to disable.

Raises

pssh.exceptions.PKeyFileError on errors finding provided private key.

close_channel(channel)
configure_keepalive()
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 to local_file and recurse is not set

Raises

pss.exceptions.SFTPError on SFTP initialisation errors

Raises

pssh.exceptions.SFTPIOError on I/O errors writing via SFTP

Raises

IOError on local file IO errors

Raises

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 to local_file and recurse is not set

Raises

pss.exceptions.SFTPError on SFTP initialisation errors

Raises

pssh.exceptions.SFTPIOError on I/O errors reading from SFTP

Raises

IOError on local file IO errors

Raises

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, timeout=None)
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.

open_session()

Open new channel from session

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.

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

  • 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

  • recurse (bool) – Whether or not to descend into directories recursively.

Raises

ValueError when a directory is supplied to local_file and recurse is not set

Raises

pss.exceptions.SFTPError on SFTP initialisation errors

Raises

pssh.exceptions.SFTPIOError on I/O errors writing via SFTP

Raises

IOError on local file IO errors

Raises

OSError on local OS errors like permission denied

sftp_get(sftp, remote_file, local_file)
sftp_put(sftp, local_file, remote_file)
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.