Api reference¶

method – http method.
uri – remote URL to target.
params – (optional) Dictionary to be sent in the query string.
data – (optional) Content to send in the body of the http request.
headers – (optional) Dictionary of HTTP Headers to send with the http request.
remote_file – (optional) File on the remote host with content to send in the body of the http request.
local_file – (optional) Local file with content to send in the body of the http request.
document_info_only – (optional) if True, only HTTP Headers are returned in http response (default=False).
auth – (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
verify – (optional) whether the SSL cert will be verified.
silent – if True, does not log the command run (useful if sensitive information are used in command)

Returns

HTTPResponse object

Return type

restclient.HTTPResponse

Usage:

>>> from jumpssh import RestSshClient
>>> with RestSshClient(host='gateway.example.com', username='my_user') as rest_client:
>>> ... http_response = rest_client.request('GET', 'http://remote.example.com')
>>> ... http_response.status_code
200

jumpssh.session¶

class jumpssh.session.RunCmdResult[source]¶

Bases: jumpssh.session.RunSSHCmdResult

Result of a command run with SSHSession

Parameters

exit_code – exit code of the run command (last run exit_code in case of retries)
output – output of the command run (last run output only in case of retries)
command – the command run
result_list – list of RunSSHCmdResult, 1 item for each retry
success_exit_code – list of integer considered as a success exit code for command run
runs_nb – number of times the command has been run

Usage:

>>> result = ssh_session.run_cmd('hostname')

# access to both exit_code and command output using tuple
>>> (exit_code, output) = result

# access directly to single attributes
>>> result.exit_code
0

>>> result.output
u'gateway.example.com'

>>> result.command
'hostname'

class jumpssh.session.RunSSHCmdResult(exit_code, output)¶

Bases: tuple

property exit_code¶: Alias for field number 0

property output¶: Alias for field number 1

class jumpssh.session.SSHSession(host, username, proxy_transport=None, private_key_file=None, port=22, password=None, missing_host_key_policy=None, compress=False, **kwargs)[source]¶

Bases: object

Establish SSH session with a remote host

Parameters

host – name or ip of the remote host
username – user to be used for remote ssh session
proxy_transport – paramiko.transport.Transport object for an SSH connection used to establish ssh session between 2 remotes hosts
private_key_file – local path to a private key file to use if key needed for authentication and not present in standard path (~/.ssh/)
port – port to connect to the remote host (default 22)
password – password to be used for authentication with remote host
missing_host_key_policy – set policy to use when connecting to servers without a known host key. This parameter is a class instance of type paramiko.client.MissingHostKeyPolicy, not a class itself
compress – set to True to turn on compression for this session
**kwargs – any parameter taken by paramiko.client.SSHClient.connect and not already explicitly covered by SSHSession

Usage:

>>> from jumpssh import SSHSession
>>> gateway_session = SSHSession('gateway.example.com', 'my_user', password='my_password')

close()[source]¶

Close connection with remote host

Usage::

>>> from jumpssh import SSHSession
>>> ssh_session = SSHSession('gateway.example.com', 'my_user', password='my_password').open()
>>> ssh_session.is_active()
True
>>> ssh_session.close()
>>> ssh_session.is_active()
False

exists(path, use_sudo=False)[source]¶

Check if path exists on the remote host

Parameters

path – remote path to check for existence
use_sudo – if True, allow to check path current user doesn’t have access by default

Returns

True, if specified path exists on the remote host else False

Return type

bool

Usage::

>>> with SSHSession('gateway.example.com', 'my_user', password='my_password') as ssh_session:
>>> ... ssh_session.exists('/path/to/remote/file')
False
>>> ... ssh_session.exists('/home/other_user/.ssh', use_sudo=True)
True

file(remote_path, content, use_sudo=False, owner=None, permissions=None, username=None, silent=False)[source]¶

Method to create a remote file with the specified content

Parameters

remote_path – destination folder in which to copy the local file
content – content of the file
use_sudo – allow to copy file in location with restricted permissions
owner – user that will own the file on the remote host
permissions – permissions to apply on the remote file (chmod format)
username – sudo user
silent – disable logging

Usage:

# create file on remote host and with specified content at the specified path
>>> ssh_session.file(remote_path='/path/to/remote/file', content='file content')

# create file on remote host and with specified content at the specified path needing sudo permissions
>>> ssh_session.file(remote_path='/path/to/remote/file', content='file content', use_sudo=True)

# create file on remote host and with specified content at the specified path
# with specified owner and permissions
>>> ssh_session.file(remote_path='/path/to/remote/file', content='file content',
...                 owner='other_user', permissions='700')

get(remote_path, local_path, use_sudo=False, username=None)[source]¶

Download a file from the remote host

Parameters

remote_path – remote path of the file to download
local_path – local path where to download the file
use_sudo – allow to download a file from a location current user does not have access
username – sudo user

Usage:

# download remote file in local directory
>>> ssh_session.get(remote_path='/path/to/remote/file', local_path='/local/folder')

# donload remote file from a path not accessible by current user
>>> ssh_session.get(local_path='/path/to/local/file', remote_path='/path/to/remote/file', use_sudo=True)

get_cmd_output(cmd, **kwargs)[source]¶

Return output of remotely executed command

Support same parameters than run_cmd method

Parameters: cmd – remote command to execute
Returns: output of remotely executed command
Return type: str

Usage::

>>> from jumpssh import SSHSession
>>> with SSHSession('gateway.example.com', 'my_user', password='my_password') as ssh_session:
>>> ... ssh_session.get_cmd_output('hostname'))
u'gateway.example.com'

get_exit_code(cmd, **kwargs)[source]¶

Return exit code of remotely executed command

Support same parameters than run_cmd method

Parameters: cmd – remote command to execute
Returns: exit code of remotely executed command
Return type: int

Usage::

>>> from jumpssh import SSHSession
>>> with SSHSession('gateway.example.com', 'my_user', password='my_password') as ssh_session:
>>> ... ssh_session.get_exit_code('ls')
0
>>> ... ssh_session.get_exit_code('dummy_command')
127

get_remote_session(host, username=None, retry=0, private_key_file=None, port=22, password=None, retry_interval=10, compress=False, **kwargs)[source]¶

Establish connection with a remote host from current session

Parameters

host – name or ip of the remote host
username – user to be used for remote ssh session
retry – retry number to establish connection with remote host (-1 for infinite retry)
private_key_file – local path to a private key file to use if key needed for authentication
port – port to connect to the remote host (default 22)
password – password to be used for authentication with remote host
retry_interval – number of seconds between each retry
compress – set to True to turn on compression for this session
**kwargs – any parameter taken by paramiko.client.SSHClient.connect and not already explicitly covered by SSHSession

Returns

session object of the remote host

Return type

SSHSession

Usage:

# open session with remote host
>>> from jumpssh import SSHSession
>>> ssh_session = SSHSession('gateway.example.com', 'my_user', password='my_password').open()

# get remote session using same user than current session and same authentication method
>>> remote_session = ssh_session.get_remote_session('remote.example.com')

# get remote session with specific user and password
>>> remote_session = ssh_session.get_remote_session('remote.example.com',
...                                                 username='other_user',
...                                                 password='other_user_password')

# retry indefinitely to connect to remote host until success
>>> remote_session = ssh_session.get_remote_session('remote.example.com', retry=-1)

get_sftp_client()[source]¶

See documentation for available methods on paramiko.sftp_client at :: http://docs.paramiko.org/en/latest/api/sftp.html

Returns: paramiko SFTP client object.
Return type: paramiko.sftp_client.SFTPClient

Usage::

# open session with remote host >>> from jumpssh import SSHSession >>> ssh_session = SSHSession(‘gateway.example.com’, ‘my_user’, password=’my_password’).open()

# get sftp client >>> sftp_client = ssh_session.get_sftp_client()

is_active()[source]¶

Check if connection with remote host is still active

An inactive SSHSession cannot run command on remote host

Returns: True if current session is still active, else False
Return type: bool

Usage::

>>> from jumpssh import SSHSession
>>> with SSHSession('gateway.example.com', 'my_user', password='my_password') as ssh_session:
>>> ... ssh_session.is_active()
True
>>> ssh_session.is_active()
False

open(retry=0, retry_interval=10)[source]¶

Open session with the remote host

Parameters

retry – number of retry to establish connection with remote host (-1 for infinite retry)
retry_interval – number of seconds between each retry

Returns

same SSHSession opened

Usage::

>>> from jumpssh import SSHSession
>>> ssh_session = SSHSession('gateway.example.com', 'my_user', password='my_password').open()
>>> ssh_session.is_active()
True

put(local_path, remote_path, use_sudo=False, owner=None, permissions=None, username=None)[source]¶

Upload a file to the remote host

Parameters

local_path – path of the local file to upload
remote_path – destination folder in which to upload the local file
use_sudo – allow to upload a file in location with restricted permissions
owner – user that will own the copied file on the remote host syntax : user:group or simply user if same than group
permissions – permissions to apply on the remote file (chmod format)
username – sudo user

Raises

IOError – if local file local_path does not exist

Usage:

# copy local file on remote host
>>> ssh_session.put(local_path='/path/to/local/file', remote_path='/path/to/remote/file')

# copy local file on remote host in a remote path needing sudo permission
>>> ssh_session.put(local_path='/path/to/local/file', remote_path='/path/to/remote/file', use_sudo=True)

# copy local file on remote host with specific owner and permissions
>>> ssh_session.put(local_path='/path/to/local/file', remote_path='/path/to/remote/file',
...                 owner='root', permissions='600')

run_cmd(cmd, username=None, raise_if_error=True, continuous_output=False, silent=False, timeout=None, input_data=None, success_exit_code=0, retry=0, retry_interval=5, keep_retry_history=False)[source]¶

Run command on the remote host and return result locally

Parameters

cmd – command to execute on remote host cmd can be a str or a list of str
username – user used to execute the command (sudo privilege needed)
raise_if_error – if True, raise SSHException when exit code of the command is different from 0 else just return exit code and command output
continuous_output – if True, print output all along the command is running
silent – if True, does not log the command run (useful if sensitive information are used in command) if parameter is a list, all strings of the command matching an item of the list will be concealed in logs (regexp supported)
timeout – length in seconds after what a TimeoutError exception is raised
input_data – key/value dictionary used when remote command expects input from user when key is matching command output, value is sent
success_exit_code – integer or list of integer considered as a success exit code for command run
retry – number of retry until exit code is part of successful exit code list (-1 for infinite retry) or RunCmdError exception is raised
retry_interval – number of seconds between each retry
keep_retry_history – if True, all retries results are kept and accessible in return result default is False as we don’t want to save by default all output for all retries especially for big output

Raises

TimeoutError – if command run longer than the specified timeout
TypeError – if cmd parameter is neither a string neither a list of string
SSHException – if current SSHSession is already closed
RunCmdError – if exit code of the command is different from 0 and raise_if_error is True

Returns

a class inheriting from collections.namedtuple containing mainly exit_code and output of the remotely executed command

Return type

RunCmdResult

Usage::

>>> from jumpssh import SSHSession
>>> with SSHSession('gateway.example.com', 'my_user', password='my_password') as ssh_session:
>>> ...     ssh_session.run_cmd('hostname')
RunSSHCmdResult(exit_code=0, output=u'gateway.example.com')

jumpssh.util¶

Useful functions used by the rest of jumpssh.

jumpssh.util.id_generator(size=6, chars='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789')[source]¶

Generate random string with specified size and set of characters

Parameters

size – length of the expected string
chars – expected characters in the string

Returns

random string

jumpssh.util.yes_no_query(question, default=None, interrupt=None)[source]¶

Ask a yes/no question via standard input and return a boolean answer.

If default is given, it is used if the user input is empty. If interrupt is given, it is used if the user presses Ctrl-C. An EOF is treated as the default answer. If there is no default, an exception is raised to prevent infinite loops. Valid answers are: y/yes/n/no (match is not case sensitive). If invalid input is given, the user will be asked until they actually give valid input.

Parameters

question – A question that is presented to the user.
default – The default value when enter is pressed with no value. When None, there is no default value and the query will loop.
interrupt – The default value when the user presses Ctrl-C

Returns

A bool indicating whether user has entered yes or no.

Return type

bool