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, _auth_thread_pool=True, keepalive_seconds=60)

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
  • forward_ssh_agent (bool) – (Optional) Turn on SSH agent forwarding - equivalent to ssh -A from the ssh command line utility. Defaults to True if not set.
  • proxy_host (str) – Connection to host is via provided proxy host and client should use self.proxy_host for connection attempts.
  • 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.

copy_file(local_file, remote_file, recurse=False, sftp=None, _dir=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.
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.
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()

Disconnect session, close socket if needed.

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.
mkdir(sftp, directory, _parent_path=None)

Make directory via SFTP channel.

Parent paths in the directory are created if they do not exist.

Parameters:

Catches and logs at error level remote IOErrors on creating directory.

open_session()

Open new channel from session

read_output(channel, timeout=None)

Read standard output buffer from channel.

Parameters:channel (ssh2.channel.Channel) – Channel to read output from.
read_output_buffer(output_buffer, prefix=None, callback=None, callback_args=None, encoding='utf-8')

Read from output buffers and log to host_logger.

Parameters:
  • output_buffer (iterator) – Iterator containing buffer
  • prefix (str) – String to prefix log output to host_logger with
  • callback (function) – Function to call back once buffer is depleted:
  • callback_args (tuple) – Arguments for call back function
read_stderr(channel, timeout=None)

Read standard error buffer from channel.

Parameters:channel (ssh2.channel.Channel) – Channel to read output from.
run_command(command, sudo=False, user=None, use_pty=False, shell=None, encoding='utf-8', timeout=None)

Run remote command.

Parameters:
  • command (str) – Command to run.
  • sudo (bool) – Run command via sudo as super-user.
  • user (str) – Run command as user via sudo
  • use_pty (bool) – Whether or not to obtain a PTY on the channel.
  • shell (str) – (Optional) Override shell to use to run command with. Defaults to login user’s defined shell. Use the shell’s command syntax, eg shell=’bash -c’ or shell=’zsh -c’.
  • encoding (str) – Encoding to use for output. Must be valid Python codec
Return type:

(channel, host, stdout, stderr, stdin) tuple.

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 gather 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 when a directory is supplied to local_file and recurse is not set.

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

spawn_send_keepalive()

Spawns a new greenlet that sends keep alive messages every self.keepalive_seconds

wait_finished(channel, 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:channel (ssh2.channel.Channel) – The channel to use.