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
Variables:
-
exception
jumpssh.exception.
SSHException
(msg, original_exception=None)[source]¶ Bases:
exceptions.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
objectReturn type:
-
get
(uri, **kwargs)[source]¶ Sends a GET request.
Parameters: - uri – URL of the http request.
- **kwargs – Optional arguments that
request()
takes.
Returns: HTTPResponse
objectReturn type:
-
head
(uri, **kwargs)[source]¶ Sends a HEAD request.
Parameters: - uri – URL of the http request.
- **kwargs – Optional arguments that
request()
takes.
Returns: HTTPResponse
objectReturn type:
-
options
(uri, **kwargs)[source]¶ Sends a OPTIONS request.
Parameters: - uri – URL of the http request.
- **kwargs – Optional arguments that
request()
takes.
Returns: HTTPResponse
objectReturn type:
-
patch
(uri, **kwargs)[source]¶ Sends a PATCH request.
Parameters: - uri – URL of the http request.
- **kwargs – Optional arguments that
request()
takes.
Returns: HTTPResponse
objectReturn type:
-
post
(uri, **kwargs)[source]¶ Sends a POST request.
Parameters: - uri – URL of the http request.
- **kwargs – Optional arguments that
request()
takes.
Returns: HTTPResponse
objectReturn type:
-
put
(uri, **kwargs)[source]¶ Sends a PUT request.
Parameters: - uri – URL of the http request.
- **kwargs – Optional arguments that
request()
takes.
Returns: HTTPResponse
objectReturn 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
objectReturn 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
[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
-
exit_code
¶ Alias for field number 0
-
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)[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 classes itself
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 methodParameters: 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 methodParameters: 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)[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
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 :
- 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: - 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: