# pathos.secure module documentation

## connection module

This module contains the derived class for secure shell (ssh) launchers See the following for an example.

### Usage

A typical call to a ‘ssh pipe’ will roughly follow this example:

    >>> # instantiate the pipe, providing it with a unique identifier
    >>> pipe = Pipe('launcher')
    >>>
    >>> # configure the pipe to perform the command on the selected host
    >>> pipe(command='hostname', host='remote.host.edu')
    >>>
    >>> # execute the launch and retrieve the response
    >>> pipe.launch()
    >>> print(pipe.response())

class Pipe(name=None, **kwds)

  Bases: `Pipe`

  a popen-based ssh-pipe for parallel and distributed computing.

  create a ssh pipe

  Inputs:

    name: a unique identifier (string) for the pipe host: hostname to recieve command [user@host is also valid] command: a command to send [default = ‘echo <name>’] launcher: remote service mechanism (i.e. ssh, rsh) [default = ‘ssh’] options: remote service options (i.e. -v, -N, -L) [default = ‘’] background: run in background [default = False] decode: ensure response is ‘ascii’ [default = True] stdin: file-like object to serve as standard input for the remote process

  __annotations_cache__ = {}
  __call__(**kwds)

    configure a remote command using given keywords:

    (Re)configure the copier for the following inputs:

      host: hostname to recieve command [user@host is also valid] command: a command to send [default = ‘echo <name>’] launcher: remote service mechanism (i.e. ssh, rsh) [default = ‘ssh’] options: remote service options (i.e. -v, -N, -L) [default = ‘’] background: run in background [default = False] decode: ensure response is ‘ascii’ [default = True] stdin: file-like object to serve as standard input for the remote process

  __firstlineno__ = 36
  __static_attributes__ = ('_stdout', 'background', 'codec', 'host', 'launcher', 'message', 'options', 'stdin')
  config(**kwds)

    configure a remote command using given keywords:

    (Re)configure the copier for the following inputs:

      host: hostname to recieve command [user@host is also valid] command: a command to send [default = ‘echo <name>’] launcher: remote service mechanism (i.e. ssh, rsh) [default = ‘ssh’] options: remote service options (i.e. -v, -N, -L) [default = ‘’] background: run in background [default = False] decode: ensure response is ‘ascii’ [default = True] stdin: file-like object to serve as standard input for the remote process

## copier module

This module contains the derived class for launching secure copy (scp) commands. See the following for an example.

### Usage

A typical call to a ‘scp launcher’ will roughly follow this example:

    >>> # instantiate the launcher, providing it with a unique identifier
    >>> copier = Copier('copier')
    >>>
    >>> # configure and launch the copy to the selected destination
    >>> copier(source='~/foo.txt', destination='remote.host.edu:~')
    >>> copier.launch()
    >>>
    >>> # configure and launch the copied file to a new destination
    >>> copier(source='remote.host.edu:~/foo.txt', destination='.')
    >>> copier.launch()
    >>> print(copier.response())

class Copier(name=None, **kwds)

  Bases: `Pipe`

  a popen-based copier for parallel and distributed computing.

  create a copier

  Inputs:

    name: a unique identifier (string) for the launcher source: hostname:path of original [user@host:path is also valid] destination: hostname:path for copy [user@host:path is also valid] launcher: remote service mechanism (i.e. scp, cp) [default = ‘scp’] options: remote service options (i.e. -v, -P) [default = ‘’] background: run in background [default = False] decode: ensure response is ‘ascii’ [default = True] stdin: file-like object to serve as standard input for the remote process

  __annotations_cache__ = {}
  __call__(**kwds)

    configure the copier using given keywords:

    (Re)configure the copier for the following inputs:

      source: hostname:path of original [user@host:path is also valid] destination: hostname:path for copy [user@host:path is also valid] launcher: remote service mechanism (i.e. scp, cp) [default = ‘scp’] options: remote service options (i.e. -v, -P) [default = ‘’] background: run in background [default = False] decode: ensure response is ‘ascii’ [default = True] stdin: file-like object to serve as standard input for the remote process

  __firstlineno__ = 42
  __static_attributes__ = ('_stdout', 'background', 'codec', 'destination', 'launcher', 'message', 'options', 'source', 'stdin')
  config(**kwds)

    configure the copier using given keywords:

    (Re)configure the copier for the following inputs:

      source: hostname:path of original [user@host:path is also valid] destination: hostname:path for copy [user@host:path is also valid] launcher: remote service mechanism (i.e. scp, cp) [default = ‘scp’] options: remote service options (i.e. -v, -P) [default = ‘’] background: run in background [default = False] decode: ensure response is ‘ascii’ [default = True] stdin: file-like object to serve as standard input for the remote process

exception FileNotFound

  Bases: `Exception`

  Exception for improper source or destination format

  __firstlineno__ = 35
  __static_attributes__ = ()

## tunnel module

This module contains the base class for secure tunnel connections, and describes the pathos tunnel interface. See the following for an example.

### Usage

A typical call to a pathos ‘tunnel’ will roughly follow this example:

    >>> # instantiate the tunnel, providing it with a unique identifier
    >>> tunnel = Tunnel('tunnel')
    >>>
    >>> # establish a tunnel to the remote host and port
    >>> remotehost = 'remote.host.edu'
    >>> remoteport = 12345
    >>> localport = tunnel.connect(remotehost, remoteport)
    >>> print("Tunnel connected at local port: %s" % tunnel._lport)
    >>>
    >>> # pause script execution to maintain the tunnel (i.e. do something)
    >>> sys.stdin.readline()
    >>>
    >>> # tear-down the tunneled connection
    >>> tunnel.disconnect()

class Tunnel(name=None, **kwds)

  Bases: `object`

  a ssh-tunnel launcher for parallel and distributed computing.

  create a ssh tunnel launcher

  Inputs:

    name – a unique identifier (string) for the launcher

  MAXPORT = 65535
  MINPORT = 1024
  __annotations_cache__ = {}
  __disconnect()

    disconnect tunnel internals

  __firstlineno__ = 48
  __repr__()

    Return repr(self).

  __static_attributes__ = ('_host', '_launcher', '_lport', '_pid', '_rport', 'connected', 'name')
  _connect(localport, remotehost, remoteport, through=None)
  connect(host, port=None, through=None)

    establish a secure shell tunnel between local and remote host

    Input:

      host – remote hostname [user@host:path is also valid] port – remote port number

    Additional Input:

      through – ‘tunnel-through’ hostname [default = None]

  disconnect()

    destroy the ssh tunnel

  verbose = True

exception TunnelException

  Bases: `Exception`

  Exception for failure to establish ssh tunnel

  __annotations_cache__ = {}
  __firstlineno__ = 44
  __static_attributes__ = ()