API: SSHClient and SSHAuth.

class exec_helpers.SSHClient[source]

SSHClient helper.

__init__(host, port=22, username=None, password=None, private_keys=None, auth=None)
Parameters:
  • host (str) – remote hostname
  • port (int) – remote ssh port
  • username (typing.Optional[str]) – remote username.
  • password (typing.Optional[str]) – remote password
  • private_keys (typing.Optional[typing.Iterable[paramiko.RSAKey]]) – private keys for connection
  • auth (typing.Optional[SSHAuth]) – credentials for connection
  • verbose (bool) – show additional error/warning messages

Note

auth has priority over username/password/private_keys

log_mask_re

typing.Optional[str]

regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’

lock

threading.RLock Connection lock for protection from destructive race-conditions (close/reconnect/…)

logger

logging.Logger Internal logger.

auth

Internal authorisation object

Return type:SSHAuth
hostname

str Connection hostname

port

int Connection port

is_alive

bool Paramiko status: ready to use|reconnect required

sudo_mode

bool Use sudo for all calls, except wrapped in connection.sudo context manager.

keepalive_mode

bool Use keepalive mode for context manager. If False - close connection on exit from context manager.

close()

Close connection

reconnect()

Reconnect SSH session

__enter__()

Open context manager

Changed in version 1.1.0: lock on enter

__exit__(self, exc_type, exc_val, exc_tb)

Close context manager and disconnect

Changed in version 1.0.0: disconnect enforced on close

Changed in version 1.1.0: release lock on exit

Changed in version 1.2.1: disconnect enforced on close only not in keepalive mode

chroot(path)

Context manager for changing chroot rules.

Parameters:path (typing.Optional[str]) – chroot path or none for working without chroot.
Returns:context manager with selected chroot state inside
Return type:typing.ContextManager

Note

Enter and exit main context manager is produced as well.

New in version 4.1.0.

sudo(enforce=None)

Context manager getter for sudo operation

Parameters:enforce (typing.Optional[bool]) – Enforce sudo enabled or disabled. By default: None
Return type:typing.ContextManager
keepalive(enforce=None)

Context manager getter for keepalive operation.

Parameters:enforce (typing.bool) – Enforce keepalive enabled or disabled. By default: True
Return type:typing.ContextManager

Note

Enter and exit ssh context manager is produced as well.

New in version 1.2.1.

execute_async(command, stdin=None, open_stdout=True, open_stderr=True, verbose=False, log_mask_re=None, *, chroot_path=None, get_pty=False, width=80, height=24, **kwargs)

Execute command in async mode and return channel with IO objects.

Parameters:
  • command (str) – Command for execution
  • stdin (typing.Union[str, bytes, bytearray, None]) – pass STDIN text to the process
  • open_stdout (bool) – open STDOUT stream for read
  • open_stderr (bool) – open STDERR stream for read
  • verbose (bool) – produce verbose log record on command call
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • chroot_path (typing.Optional[str]) – chroot path override
  • get_pty (bool) – Get PTY for connection
  • width (int) – PTY width
  • height (int) – PTY height
Return type:

SshExecuteAsyncResult

Changed in version 1.2.0: open_stdout and open_stderr flags

Changed in version 1.2.0: stdin data

Changed in version 1.2.0: get_pty moved to **kwargs

Changed in version 2.1.0: Use typed NamedTuple as result

Changed in version 3.2.0: Expose pty options as optional keyword-only arguments

execute(command, verbose=False, timeout=1*60*60, *, log_mask_re=None, stdin=None, **kwargs)

Execute command and wait for return code.

Parameters:
  • command (str) – Command for execution
  • verbose (bool) – Produce log.info records for command call and output
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the process
Return type:

ExecResult

Raises:

ExecHelperTimeoutError – Timeout exceeded

Changed in version 1.2.0: default timeout 1 hour

__call__(command, verbose=False, timeout=1*60*60, *, log_mask_re=None, stdin=None, **kwargs)

Execute command and wait for return code.

Parameters:
  • command (str) – Command for execution
  • verbose (bool) – Produce log.info records for command call and output
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the process
Return type:

ExecResult

Raises:

ExecHelperTimeoutError – Timeout exceeded

New in version 3.3.0.

check_call(command, verbose=False, timeout=1*60*60, error_info=None, expected=(0, ), raise_on_err=True, *, log_mask_re=None, stdin=None, exception_class=CalledProcessError, **kwargs)

Execute command and check for return code.

Parameters:
  • command (str) – Command for execution
  • verbose (bool) – Produce log.info records for command call and output
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • error_info (typing.Optional[str]) – Text for error details, if fail happens
  • expected (typing.Iterable[typing.Union[int, ExitCodes]]) – expected return codes (0 by default)
  • raise_on_err (bool) – Raise exception on unexpected return code
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the process
  • exception_class (typing.Type[CalledProcessError]) – Exception class for errors. Subclass of CalledProcessError is mandatory.
Return type:

ExecResult

Raises:

Changed in version 1.2.0: default timeout 1 hour

Changed in version 3.2.0: Exception class can be substituted

Changed in version 3.4.0: Expected is not optional, defaults os dependent

check_stderr(command, verbose=False, timeout=1*60*60, error_info=None, raise_on_err=True, *, expected=(0, ), log_mask_re=None, stdin=None, exception_class=CalledProcessError, **kwargs)

Execute command expecting return code 0 and empty STDERR.

Parameters:
  • command (str) – Command for execution
  • verbose (bool) – Produce log.info records for command call and output
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • error_info (typing.Optional[str]) – Text for error details, if fail happens
  • raise_on_err (bool) – Raise exception on unexpected return code
  • expected (typing.Iterable[typing.Union[int, ExitCodes]]) – expected return codes (0 by default)
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the process
  • exception_class (typing.Type[CalledProcessError]) – Exception class for errors. Subclass of CalledProcessError is mandatory.
Return type:

ExecResult

Raises:

Changed in version 1.2.0: default timeout 1 hour

Changed in version 3.2.0: Exception class can be substituted

execute_through_host(hostname, command, auth=None, target_port=22, verbose=False, timeout=1*60*60, *, stdin=None, log_mask_re="", get_pty=False, width=80, height=24, **kwargs)

Execute command on remote host through currently connected host.

Parameters:
  • hostname (str) – target hostname
  • command (str) – Command for execution
  • auth (typing.Optional[SSHAuth]) – credentials for target machine
  • target_port (int) – target port
  • verbose (bool) – Produce log.info records for command call and output
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the process
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • get_pty (bool) – open PTY on target machine
  • width (int) – PTY width
  • height (int) – PTY height
Return type:

ExecResult

Raises:

ExecHelperTimeoutError – Timeout exceeded

Changed in version 1.2.0: default timeout 1 hour

Changed in version 3.2.0: Expose pty options as optional keyword-only arguments

Changed in version 3.2.0: Exception class can be substituted

Changed in version 4.0.0: Expose stdin and log_mask_re as optional keyword-only arguments

classmethod execute_together(remotes, command, timeout=1*60*60, expected=(0, ), raise_on_err=True, *, stdin=None, log_mask_re="", exception_class=ParallelCallProcessError, **kwargs)

Execute command on multiple remotes in async mode.

Parameters:
  • remotes (typing.Iterable[SSHClient]) – Connections to execute on
  • command (str) – Command for execution
  • timeout (typing.Union[int, float, None]) – Timeout for command execution.
  • expected (typing.Iterable[typing.Union[int, ExitCodes]]) – expected return codes (0 by default)
  • raise_on_err (bool) – Raise exception on unexpected return code
  • stdin (typing.Union[bytes, str, bytearray, None]) – pass STDIN text to the process
  • log_mask_re (typing.Optional[str]) – regex lookup rule to mask command for logger. all MATCHED groups will be replaced by ‘<masked>’
  • exception_class (typing.Type[ParallelCallProcessError]) – Exception to raise on error. Mandatory subclass of ParallelCallProcessError
Returns:

dictionary {(hostname, port): result}

Return type:

typing.Dict[typing.Tuple[str, int], ExecResult]

Raises:

Changed in version 1.2.0: default timeout 1 hour

Changed in version 3.2.0: Exception class can be substituted

Changed in version 3.4.0: Expected is not optional, defaults os dependent

Changed in version 4.0.0: Expose stdin and log_mask_re as optional keyword-only arguments

open(path, mode='r')

Open file on remote using SFTP session.

Parameters:
  • path (str) – filesystem object path
  • mode (str) – open file mode (‘t’ is not supported)
Returns:

file.open() stream

Return type:

paramiko.SFTPFile

exists(path)

Check for file existence using SFTP session.

Parameters:path (str) – filesystem object path
Returns:path is valid (object exists)
Return type:bool
stat(path)

Get stat info for path with following symlinks.

Parameters:path (str) – filesystem object path
Returns:stat like information for remote path
Return type:paramiko.sftp_attr.SFTPAttributes
utime(path, times=None):

Set atime, mtime.

Parameters:
  • path (str) – filesystem object path
  • times (typing.Optional[typing.Tuple[int, int]]) – (atime, mtime)
Return type:

None

New in version 1.0.0.

isfile(path)

Check, that path is file using SFTP session.

Parameters:path (str) – remote path to validate
Returns:path is file
Return type:bool
isdir(path)

Check, that path is directory using SFTP session.

Parameters:path (str) – remote path to validate
Returns:path is directory
Return type:bool

Check, that path is symlink using SFTP session.

Parameters:path (str) – remote path to validate
Returns:path is symlink
Return type:bool

Produce symbolic link like os.symlink.

Parameters:
  • source (str) – source path
  • dest (str) – source path
chmod(path, mode)

Change the mode (permissions) of a file like os.chmod.

Parameters:
  • path (str) – filesystem object path
  • mode (int) – new permissions

Non standard methods:

mkdir(path)[source]

run ‘mkdir -p path’ on remote.

rm_rf(path)[source]

run ‘rm -rf path’ on remote.

upload(source, target)[source]

Upload file(s) from source to target using SFTP session.

download(destination, target)[source]

Download file(s) to target from destination.

Returns:downloaded file present on local filesystem
Return type:bool
class exec_helpers.SSHAuth[source]

SSH credentials object.

Used to authorize SSHClient. Single SSHAuth object is associated with single host:port. Password and key is private, other data is read-only.

__init__(username=None, password=None, key=None, keys=None)[source]
Parameters:
  • username (typing.Optional[str]) – remote username.
  • password (typing.Optional[str]) – remote password
  • key (typing.Optional[paramiko.RSAKey]) – Main connection key
  • keys (typing.Optional[typing.Iterable[paramiko.RSAKey]]) – Alternate connection keys
  • key_filename (typing.Union[typing.List[str], str, None]) – filename(s) for additional key files
  • passphrase (typing.Optional[str]) – passphrase for keys. Need, if differs from password

Changed in version 1.0.0: added: key_filename, passphrase arguments

username

typing.Optional[str]

public_key

typing.Optional[str] public key for stored private key if presents else None

key_filename

typing.Union[typing.List[str], str, None] Key filename(s).

New in version 1.0.0.

enter_password(self, tgt)[source]

Enter password to STDIN.

Note: required for ‘sudo’ call

Parameters:tgt (file) – Target
connect(client, hostname=None, port=22, log=True)[source]

Connect SSH client object using credentials.

Parameters:
  • client (typing.Union[paramiko.client.SSHClient, paramiko.transport.Transport]) – SSH Client (low level)
  • hostname (str) – remote hostname
  • port (int) – remote ssh port
  • log (bool) – Log on generic connection failure
Raises:

paramiko.AuthenticationException – Authentication failed.

class exec_helpers.SshExecuteAsyncResult[source]

Typed NamedTuple

interface

paramiko.Channel

stdin

paramiko.ChannelFile

stderr

typing.Optional[paramiko.ChannelFile]

stdout

typing.Optional[paramiko.ChannelFile]

started

datetime.datetime

New in version 3.4.1.