SSHClient

SSHClient is a single host client and is suitable for talking to a single SSH server asynchronously. All SSH functionality is implemented in SSHClient and it is used by ParallelSSHClient.

class pssh.ssh_client.SSHClient(host, user=None, password=None, port=None, pkey=None, forward_ssh_agent=True, num_retries=3, agent=None, allow_agent=True, timeout=10, proxy_host=None, proxy_port=22, proxy_user=None, proxy_password=None, proxy_pkey=None, channel_timeout=None, _openssh_config_file=None, **paramiko_kwargs)

SSH client based on Paramiko with sane defaults.

Honours ~/.ssh/config and /etc/ssh/ssh_config host entries for host, user name, port and key overrides.

Parameters:
  • host (str) – Hostname to connect to
  • user (str) – (Optional) User to login as. Defaults to logged in user or user from ~/.ssh/config if set
  • password (str) – (Optional) Password to use for login. Defaults to no password
  • port (int) – (Optional) Port number to use for SSH connection. Defaults to None which uses SSH default
  • pkey (paramiko.pkey.PKey) – (Optional) Client’s private key to be used to connect with
  • num_retries (int) – (Optional) Number of retries for connection attempts before the client gives up. Defaults to 3.
  • timeout (int) – (Optional) Number of seconds to timeout connection attempts before the client gives up
  • 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.
  • agent (paramiko.agent.Agent) – (Optional) Override SSH agent object with the provided. This allows for overriding of the default paramiko behaviour of connecting to local SSH agent to lookup keys with our own SSH agent object.
  • forward_ssh_agent – (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) – (Optional) SSH host to tunnel connection through so that SSH clients connects to self.host via client -> proxy_host -> host
  • proxy_port (int) – (Optional) SSH port to use to login to proxy host if set. Defaults to 22.
  • channel_timeout (int) – (Optional) Time in seconds before an SSH operation times out.
  • allow_agent (bool) – (Optional) set to False to disable connecting to the SSH agent
  • paramiko_kwargs (dict) – (Optional) Extra keyword arguments to be passed on to paramiko.client.SSHClient.connect()
copy_file(local_file, remote_file, recurse=False, sftp=None)

Copy local file to host via SFTP/SCP

Copy is done natively using SFTP/SCP version 2 protocol, no scp command is used or required.

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:

IOError on I/O errors writing files

Raises:

OSError on OS errors like permission denied

copy_remote_file(remote_file, local_file, recurse=False, sftp=None)

Copy remote file to local host via SFTP/SCP

Copy is done natively using SFTP/SCP version 2, no scp command is used or required.

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
Raises:

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

Raises:

IOError on I/O errors creating directories or file

Raises:

OSError on OS errors like permission denied

exec_command(command, sudo=False, user=None, shell=None, use_shell=True, use_pty=True)

Wrapper to paramiko.SSHClient.exec_command()

Opens a new SSH session with a new pty and runs command before yielding the main gevent loop to allow other greenlets to execute.

Parameters:
  • command (str) – Command to execute
  • sudo (bool) – (Optional) Run with sudo. Defaults to False
  • user (str) – (Optional) User to switch to via sudo to run command as. Defaults to user running the python process
  • shell – (Optional) Shell override to use instead of user login configured shell. For example shell='bash -c'
  • use_shell (bool) – (Optional) Force use of shell on/off. Defaults to True for on
  • use_pty (bool) – (Optional) Enable/Disable use of pseudo terminal emulation. This is required in vast majority of cases, exception being where a shell is not used and/or stdout/stderr/stdin buffers are not required. Defaults to True
Return type:

Tuple of (channel, hostname, stdout, stderr, stdin). Channel is the remote SSH channel, needed to ensure all of stdout has been got, hostname is remote hostname the copy is to, stdout and stderr are buffers containing command output and stdin is standard input channel

mkdir(sftp, directory)

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.

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