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, command, error)[source]¶

Bases: jumpssh.exception.SSHException

Exception raised when remote command return a non-zero exit code

Variables:	exit_code (int) – The error code from the run command. command (str) – The command that is generating this exception. error (str) – The error captured from the command output.

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.HTTPResponse(http_response_str)[source]¶

check_for_success()[source]¶

is_valid_json_body()[source]¶

json(**kwargs)[source]¶

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:	restclient.HTTPResponse

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:	restclient.HTTPResponse

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:	restclient.HTTPResponse

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:	restclient.HTTPResponse

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:	restclient.HTTPResponse

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:	restclient.HTTPResponse

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:	restclient.HTTPResponse

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.
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.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:	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)[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:	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)[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 neither the output of the command 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
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 namedtuple containing exit_code and output of the remotely executed command
Return type:	collections.namedtuple(exit_code=int, output=str)

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')