ssh-python based Single Host Client

Single host non-blocking client based on ssh-python (libssh). Suitable for running asynchronous commands on a single host.

class pssh.clients.ssh.single.SSHClient(host, user=None, password=None, port=None, pkey=None, num_retries=3, retry_delay=5, allow_agent=True, timeout=None, identity_auth=True, gssapi_auth=False, gssapi_server_identity=None, gssapi_client_identity=None, gssapi_delegate_credentials=False, _auth_thread_pool=True)

ssh-python based non-blocking 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) – (Optional) If provided, all commands will timeout after <timeout> number of seconds.

  • allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSH agent. Currently unused.

  • identity_auth (bool) – (Optional) set to False to disable attempting to authenticate with default identity files from pssh.clients.base_ssh_client.BaseSSHClient.IDENTITIES

  • gssapi_server_identity (str) – Enable GSS-API authentication. Uses GSS-MIC key exchange. Enabled if either gssapi_server_identity or gssapi_client_identity are provided.

  • gssapi_server_identity – Set GSSAPI server identity.

  • gssapi_client_identity (str) – Set GSSAPI client identity.

  • gssapi_delegate_credentials (bool) – Enable/disable server credentials delegation.

Raises

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

auth()
close_channel(channel)

Close channel.

Parameters

channel (ssh.channel.Channel) – The channel to close.

disconnect()

Close socket if needed.

execute(cmd, use_pty=False, channel=None)

Execute command on remote host.

Parameters

  • cmd (str) – The command string to execute.

  • use_pty (bool) – Whether or not to request a PTY on the channel executing command.

  • channel (ssh.channel.Channel) – Channel to use. New channel is created if not provided.

finished(channel)

Checks if remote command has finished - has server sent client EOF.

Return type

bool

get_exit_status(channel)

Get exit status from channel if ready else return None.

Return type

int or None

open_session()

Open new channel from session.

read_output(channel, timeout=None, is_stderr=False)

Read standard output buffer from channel. Returns a generator of line by line output.

Parameters

channel (ssh2.channel.Channel) – Channel to read output from.

Return type

generator

read_stderr(channel, timeout=None)

Read standard error buffer from channel. Returns a generator of line by line output.

Parameters

channel (ssh2.channel.Channel) – Channel to read output from.

Return type

generator

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 (ssh.channel.Channel) – The channel to use.

  • timeout (float) – Timeout value in seconds - defaults to no timeout.

Raises

pssh.exceptions.Timeout after <timeout> seconds if timeout given.