1
.. PyZMQ ssh doc, by Min Ragan-Kelley, 2011
5
Tunneling PyZMQ Connections with SSH
6
====================================
8
.. versionadded:: 2.1.9
10
You may want to connect ØMQ sockets across machines, or untrusted networks. One common way
11
to do this is to tunnel the connection via SSH. IPython_ introduced some tools for
12
tunneling ØMQ connections over ssh in simple cases. These functions have been brought into
13
pyzmq as :mod:`zmq.ssh` under IPython's BSD license.
15
PyZMQ will use the shell ssh command via pexpect_ by default, but it also supports
16
using paramiko_ for tunnels, so it should work on Windows.
20
pexpect has no Python3 support at this time, so Python 3 users should get Thomas
21
Kluyver's `pexpect-u`_ fork.
23
An SSH tunnel has five basic components:
25
* server : the SSH server through which the tunnel will be created
26
* remote ip : the IP of the remote machine *as seen from the server*
27
(remote ip may be, but is not not generally the same machine as server).
28
* remote port : the port on the remote machine that you want to connect to.
29
* local ip : the interface on your local machine you want to use (default: 127.0.0.1)
30
* local port : the local port you want to forward to the remote port (default: high random)
32
So once you have established the tunnel, connections to ``localip:localport`` will actually
33
be connections to ``remoteip:remoteport``.
35
In most cases, you have a zeromq url for a remote machine, but you need to tunnel the
36
connection through an ssh server. This is
38
So if you would use this command from the same LAN as the remote machine:
40
.. sourcecode:: python
42
sock.connect("tcp://10.0.1.2:5555")
44
to make the same connection from another machine that is outside the network, but you have
45
ssh access to a machine ``server`` on the same LAN, you would simply do:
47
.. sourcecode:: python
50
ssh.tunnel_connection(sock, "tcp://10.0.1.2:5555", "server")
52
Note that ``"server"`` can actually be a fully specified ``"user@server:port"`` ssh url.
53
Since this really just launches a shell command, all your ssh configuration of usernames,
54
aliases, keys, etc. will be respected. If necessary, :func:`tunnel_connection` does take
55
arguments for specific passwords, private keys (the ssh ``-i`` option), and non-default
56
choice of whether to use paramiko.
58
If you are on the same network as the machine, but it is only listening on localhost, you
59
can still connect by making the machine itself the server, and using loopback as the
62
.. sourcecode:: python
65
ssh.tunnel_connection(sock, "tcp://127.0.0.1:5555", "10.0.1.2")
67
The :func:`tunnel_connection` function is a simple utility that forwards a random
68
localhost port to the real destination, and connects a socket to the new local url,
69
rather than the remote one that wouldn't actually work.
73
A short discussion of ssh tunnels: http://www.revsys.com/writings/quicktips/ssh-tunnel.html
76
.. _IPython: http://ipython.org
77
.. _pexpect: http://www.noah.org/wiki/pexpect
78
.. _pexpect-u: http://pypi.python.org/pypi/pexpect-u
79
.. _paramiko: http://www.lag.net/paramiko/
added
removed
docs/source/ssh.rst
