Api reference¶
jumpssh.exception¶
-
exception
jumpssh.exception.
ConnectionError
(msg, original_exception=None)[source]¶ Bases:
jumpssh.exception.SSHException
Exception raised when unable to establish SSHSession with remote host
-
exception
jumpssh.exception.
RestClientError
(msg, original_exception=None)[source]¶ Bases:
jumpssh.exception.SSHException
Exception raised when error occurs during rest ssh calls
-
exception
jumpssh.exception.
RunCmdError
(exit_code, success_exit_code, command, error, runs_nb=1)[source]¶ Bases:
jumpssh.exception.SSHException
Exception raised when remote command return a non success exit code
-
exception
jumpssh.exception.
SSHException
(msg, original_exception=None)[source]¶ Bases:
Exception
Generic exception for jumpssh
Allow to chain exceptions keeping track of origin exception
-
exception
jumpssh.exception.
TimeoutError
(msg, original_exception=None)[source]¶ Bases:
jumpssh.exception.SSHException
Exception raised when remote command execution reached specified timeout
jumpssh.restclient¶
-
class
jumpssh.restclient.
RestSshClient
(ssh_session=None, **kwargs)[source]¶ Bases:
object
-
delete
(uri, **kwargs)[source]¶ Sends a DELETE request.
- Parameters
uri – URL of the http request.
**kwargs – Optional arguments that
request()
takes.
- Returns
HTTPResponse
object- Return type
-
get
(uri, **kwargs)[source]¶ Sends a GET request.
- Parameters
uri – URL of the http request.
**kwargs – Optional arguments that
request()
takes.
- Returns
HTTPResponse
object- Return type
-
head
(uri, **kwargs)[source]¶ Sends a HEAD request.
- Parameters
uri – URL of the http request.
**kwargs – Optional arguments that
request()
takes.
- Returns
HTTPResponse
object- Return type
-
options
(uri, **kwargs)[source]¶ Sends a OPTIONS request.
- Parameters
uri – URL of the http request.
**kwargs – Optional arguments that
request()
takes.
- Returns
HTTPResponse
object- Return type
-
patch
(uri, **kwargs)[source]¶ Sends a PATCH request.
- Parameters
uri – URL of the http request.
**kwargs – Optional arguments that
request()
takes.
- Returns
HTTPResponse
object- Return type
-
post
(uri, **kwargs)[source]¶ Sends a POST request.
- Parameters
uri – URL of the http request.
**kwargs – Optional arguments that
request()
takes.
- Returns
HTTPResponse
object- Return type
-
put
(uri, **kwargs)[source]¶ Sends a PUT request.
- Parameters
uri – URL of the http request.
**kwargs – Optional arguments that
request()
takes.
- Returns
HTTPResponse
object- Return type
-
request
(method, uri, **kwargs)[source]¶ Perform http request and send back http response.
- Parameters
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
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
(exit_code, output, result_list, command, success_exit_code, runs_nb)[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
-
property
-
class
jumpssh.session.
SSHSession
(host, username, proxy_transport=None, private_key_file=None, port=22, password=None, missing_host_key_policy=None, compress=False, timeout=None, **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 hostsprivate_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 itselfcompress – set to True to turn on compression for this session
timeout – optional timeout opening SSH session, default 3600s (1h)
**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
- 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
- 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
- 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, timeout=None, **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
timeout – optional timeout opening remote session, default 3600s (1h)
**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
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 :
- Returns
paramiko SFTP client object.
- Return type
- 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
- 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
- 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