API: SSHClient and SSHAuth.

class exec_helpers.SSHClient[source]

SSHClient helper.

__init__(host, port=22, username=None, password=None, *, private_keys=None, auth=None, verbose=True, ssh_config=None, ssh_auth_map=None, sock=None, keepalive=1)
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.Sequence[paramiko.RSAKey]]) – private keys for connection
  • auth (typing.Optional[SSHAuth]) – credentials for connection
  • verbose (bool) – show additional error/warning messages
  • ssh_config (typing.Union[str, paramiko.SSHConfig, typing.Dict[str, typing.Dict[str, typing.Union[str, int, bool, typing.List[str]]]], HostsSSHConfigs, None]) – SSH configuration for connection. Maybe config path, parsed as dict and paramiko parsed.
  • ssh_auth_map (typing.Optional[typing.Union[typing.Dict[str, ssh_auth.SSHAuth], ssh_auth.SSHAuthMapping]]) – SSH authentication information mapped to host names. Useful for complex SSH Proxy cases.
  • sock (typing.Optional[typing.Union[paramiko.ProxyCommand, paramiko.Channel, socket.socket]]) – socket for connection. Useful for ssh proxies support
  • keepalive (typing.Union[int, bool]) – keepalive period

Note

auth has priority over username/password/private_keys

Note

for proxy connection auth information is collected from SSHConfig if ssh_auth_map record is not available

Changed in version 6.0.0: private_keys, auth and vebose became keyword-only arguments

Changed in version 6.0.0: added optional ssh_config for ssh-proxy & low level connection parameters handling

Changed in version 6.0.0: added optional ssh_auth_map for ssh proxy cases with authentication on each step

Changed in version 6.0.0: added optional sock for manual proxy chain handling

Changed in version 6.0.0: keepalive exposed to constructor

Changed in version 6.0.0: keepalive became int, now used in ssh transport as period of keepalive requests

Changed in version 6.0.0: private_keys is deprecated

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_period

typing.Union[int, bool] Keepalive period for connection object. If 0 - close connection on exit from context manager.

close()

Close connection

reconnect()

Reconnect SSH session

__enter__()[source]

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[typing.Union[str, pathlib.Path]]) – 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[None]
keepalive(enforce=1)

Context manager getter for keepalive operation.

Parameters:enforce (typing.Union[int, bool]) – Enforce keepalive period.
Returns:context manager with selected keepalive state inside
Return type:typing.ContextManager[None]

Note

Enter and exit ssh context manager is produced as well.

New in version 1.2.1.

execute(command, verbose=False, timeout=1*60*60, *, log_mask_re=None, stdin=None, open_stdout=True, open_stderr=True, get_pty=False, width=80, height=24, **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
  • open_stdout (bool) – open STDOUT stream for read
  • open_stderr (bool) – open STDERR stream for read
  • get_pty (bool) – Get PTY for connection
  • 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

__call__(command, verbose=False, timeout=1*60*60, *, log_mask_re=None, stdin=None, open_stdout=True, open_stderr=True, get_pty=False, width=80, height=24, **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
  • open_stdout (bool) – open STDOUT stream for read
  • open_stderr (bool) – open STDERR stream for read
  • get_pty (bool) – Get PTY for connection
  • width (int) – PTY width
  • height (int) – PTY height
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, open_stdout=True, open_stderr=True, get_pty=False, width=80, height=24, 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
  • open_stdout (bool) – open STDOUT stream for read
  • open_stderr (bool) – open STDERR stream for read
  • get_pty (bool) – Get PTY for connection
  • width (int) – PTY width
  • height (int) – PTY height
  • 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, open_stdout=True, open_stderr=True, get_pty=False, width=80, height=24, 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
  • open_stdout (bool) – open STDOUT stream for read
  • open_stderr (bool) – open STDERR stream for read
  • get_pty (bool) – Get PTY for connection
  • width (int) – PTY width
  • height (int) – PTY height
  • 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

proxy_to(host, port=None, username=None, password=None, *, auth=None, verbose=True, ssh_config=None, ssh_auth_map=None, keepalive=1)

Start new SSH connection using current as proxy.

Parameters:
  • host (str) – remote hostname
  • port (typing.Optional[int]) – remote ssh port
  • username (typing.Optional[str]) – remote username.
  • password (typing.Optional[str]) – remote password
  • auth (typing.Optional[ssh_auth.SSHAuth]) – credentials for connection
  • verbose (bool) – show additional error/warning messages
  • ssh_config (typing.Union[str, paramiko.SSHConfig, typing.Dict[str, typing.Dict[str, typing.Union[str, int, bool, typing.List[str]]]], HostsSSHConfigs, None]) – SSH configuration for connection. Maybe config path, parsed as dict and paramiko parsed.
  • ssh_auth_map (typing.Optional[typing.Union[typing.Dict[str, ssh_auth.SSHAuth], ssh_auth.SSHAuthMapping]]) – SSH authentication information mapped to host names. Useful for complex SSH Proxy cases.
  • keepalive (typing.Union[int, bool]) – keepalive period
Returns:

new ssh client instance using current as a proxy

Return type:

SSHClientBase

Note

auth has priority over username/password

New in version 6.0.0.

execute_through_host(hostname, command, *, auth=None, port=22, verbose=False, timeout=1*60*60, stdin=None, open_stdout=True, open_stderr=True, 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
  • 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
  • open_stdout (bool) – open STDOUT stream for read
  • open_stderr (bool) – open STDERR stream for read
  • 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

Changed in version 6.0.0: Move channel open to separate method and make proper ssh-proxy usage

Changed in version 6.0.0: only hostname and command are positional argument, target_port changed to port.

classmethod execute_together(remotes, command, timeout=1*60*60, expected=(0, ), raise_on_err=True, *, stdin=None, open_stdout=True, open_stderr=True, 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
  • open_stdout (bool) – open STDOUT stream for read
  • open_stderr (bool) – open STDERR stream for read
  • 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.Sequence[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, port=22, log=True, *, sock=None)[source]

Connect SSH client object using credentials.

Parameters:
  • client (paramiko.SSHClient) – SSH Client (low level)
  • hostname (str) – remote hostname
  • port (int) – remote ssh port
  • log (bool) – Log on generic connection failure
  • sock (typing.Optional[typing.Union[paramiko.ProxyCommand, paramiko.Channel, socket.socket]]) – socket for connection. Useful for ssh proxies support
Raises:
  • PasswordRequiredException – No password has been set, but required.
  • AuthenticationException – Authentication failed.
class exec_helpers.SshExecuteAsyncResult

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.

class exec_helpers.HostsSSHConfigs(typing.Dict[str, SSHConfig])[source]

Specific dictionary for managing SSHConfig records.

Instead of creating new record by request just generate default value and return if not exists.

__missing__(key)[source]

Missing key handling.

Parameters:key (str) – nonexistent key
Returns:generated ssh config for host
Return type:SSHConfig
Raises:KeyError – key is not string

New in version 6.0.0.

class exec_helpers.SSHConfig[source]

Parsed SSH Config for creation connection.

__init__(hostname, port=None, user=None, identityfile=None, proxycommand=None, proxyjump=None, *, controlpath=None, controlmaster=None)[source]

SSH Config for creation connection.

Parameters:
  • hostname (str) – hostname, which config relates
  • port (typing.Optional[typing.Union[str, int]]) – remote port
  • user (typing.Optional[str]) – remote user
  • identityfile (typing.Optional[typing.List[str]]) – connection ssh keys file names
  • proxycommand (typing.Optional[str]) – proxy command for ssh connection
  • proxyjump (typing.Optional[str]) – proxy host name
  • controlpath (typing.Optional[str]) – shared socket file path for re-using connection by multiple instances
  • controlmaster (typing.Optional[typing.Union[str, bool]]) – re-use connection
Raises:

ValueError – Invalid argument provided.

New in version 6.0.0.

from_ssh_config(ssh_config):

Construct config from Paramiko parsed file.

Parameters:ssh_config – paramiko parsed ssh config or it reconstruction as a dict,
Returns:SSHConfig with supported values from config
as_dict

typing.Dict[str, typing.Union[str, int, bool, typing.List[str]]] Dictionary for rebuilding config.

overridden_by(ssh_config)[source]

Get copy with values overridden by another config.

Parameters:ssh_config (SSHConfig) – Other ssh config
Returns:Composite from 2 configs with priority of second one
Return type:SSHConfig
hostname

str Hostname which config relates.

port

typing.Optional[int] Remote port.

user

typing.Optional[str] Remote user.

identityfile

typing.Optional[typing.List[str]] Connection ssh keys file names.

proxycommand

typing.Optional[str] Proxy command for ssh connection.

proxyjump

typing.Optional[str] Proxy host name.

controlpath

typing.Optional[str] Shared socket file path for re-using connection by multiple instances.

controlmaster

typing.Optional[bool] Re-use connection.