pyTunnel readme
Overview
======================================
pyTunnel is a ssh tunnel (port forwarding) manager. SSH Tunnels allow you to gain access to a remote host's ports by forwarding requests via a interim host that you can reach. For example, if you need to get connected to oracle database running on port 1521 on the oracle1.customer.com host, but only have access to that box via the jump1.customer.com box you would normally run this ssh command
ssh $USER@jump1.customer.com -L 1521:oracle1.customer.com:1521
This would start a forwarding server on your machine that listens on 1521 and forwards all traffic to oracel1.customer.com port 1521. Then you could point your local oracle tools to localhost:1521 to connect. In essence, this is what pyTunnel does. Its handy because it keeps track of all your tunnels and passwords ( thanks keyring! ) so that you dont have to.
pyTunnel is not a ssh wrapper, instead it uses python libraries ( thanks paramiko! ) to establish the ssh connection and to create the local forwarding servers. This allows it to have fine grain control over the entire transport process. One important distinction between pyTunnel and command line ssh forwarding is that pyTunnel uses "passive" tunnels - that is to say the tunnels, or local forwarding servers, do not connect to the jump host until a request is made on the port the tunnel is listening on. This allows the program to start all tunnels up front without having to worry about the cost of maintaining multiple ssh connections.
Multiple "hop" tunnels
======================================
One tricky concept to understand is that of multiple hop connections. Consider the situation where you need to get to oracle1.customer.com:1521, but have to first jump to jump1.oracle.com, but jump1 does not have access to oracle1, you have to jump from jump1 to jump2.customer.com, and then from there you can get to oracle1.
If you were using the ssh command you would do a chained tunnel, but since pyTunnel is not an interactive program that's not an option. To accomplish this we have to create a tunnel inside a tunnel, ie forward jump2's ssh port (22) via jump1 to a local port, 10801 for example, then creating a second tunnel that connects to localhost:1081, If you're used to the ssh command, here is what I'm talking about:
<session1>
ssh user@jump1.customer.com -p 22 -L 10801:jump2.customer.com:22
<session2>
ssh user@localhost -p 10801 -L 1521:oracle1.customer.com:1521
Config File
======================================
pyTunnel keeps all its information in 2 configuration files:
*pyTunnel_UI.dat: used for user interface stuff, you shouldnt need to look at this.
*tunnels.config: used to store all your tunnel information, you open other config files via file->open in the UI. pyTunnel has an editor for the tunnel.config file, but it can be a bit quirky, feel free to edit the file directly if you prefer. here is the layout of the config file:
The file is broken into sections, denoted between brackets. The section name is the name of the tunnel, except for one special section, the [DEFAULT] section. This section stores, yep, you guessed it, default values for other section if the section is missing a value.
Here is an example of the default section.
[DEFAULT]
SSH_PORT = 22
KEY_LOOK = True
HOST_FILE = .\\config\\known_hosts
KEY_FILE = .\\config\\id_rsa
TUNNELS =
Here is an example of a tunnel section
[Tunnel1]
SSH_PORT = 22
KEY_LOOK = True
SSH_HOST = jump1.customer.com
SSH_USER = ssh username
SSH_PASS = supply the password in plain text, when the config file is first read it will be encrypted and written to the pytunnel keyring, and then it will be removed from the config file.
to change the password either use the GUI or edit the config file and add this parameter.
TUNNELS =
localhost|8000|oracle1.customer.com|1521
,localhost|8001|oracle2.customer.com|1522
,localhost|8002|oracle3.customer.com|1522
,localhost|8004|oracle4.customer.com|1521
,localhost|8005|windoz.customer.com|3389
Revision History
======================================
release 1
* beta version, initial release.
release 2
* "passive" tunnels introduced - you no longer need to manualy start|stop tunnels. Tunnels are started by default, but do establish connections to jump hosts until required.
* Program minimizes to system tray instead of to task bar.
* Connection reaper: if a connection is not used for 5 minutes it is closed. Note, it should not close a connection if one of the tunnels ( forwarding servers ) is actively using it.
release 2.1
* Under certain conditions a password would get corrupt in the config file. Upon reading the config file the password would be encrypted and the config file was updated, but de-crypt fail - causing the password to get lost. An additional check was added so that in event a password can not be de-crypted it will remain in the config file as plain text.
* You can now connect using a RSA or DSA key file. Previously you could configure a key file but RSA and DSA connections failed.
* You can now set individual tunnels to be automatically started or manually started.
* You can add notes to each tunnel
release 2.2
* password encryption is now handled by the keyring module and passwords are stored in a separate file than the pytunnel config file.
* tunnels now make sure that there is not already something else listening the local port before starting.
* binary distribution is a single .exe file
release 2.3
* new keyring. new keyring will prompt for a password when accessing encrypted passwords. The prior version the keyring would use it's own magic "salt" to encrypt passwords, which changes from machine to machine and does not allow the keyring to be reused on differenct machines.
*removed the connection reaper, I've found that it is more trouble than its worth.
release 2.4
* Tunnel security introduced. Each time a process requests data from a tunnel socket it goes through a verification process. If the verifycation fails, the communication is closed. The verification process is controlled by the TUNNEL_SECURITY_CLASS parameter in the tunnels.config file. The parameter format is TUNNEL_SECURITY_CLASS=<filename>:<classname> where filename is the name or path to a python module file, and <classname> is the name of a class within the file. Release 2.4 includes the verify.py module which includes the following verification classes:
verify:BaseRequestVerification - all requests are validated. In other words, no tunnel data security
verify:perRequestVerification - tunnel manager application will ask user to confirm access during each request
verify:perProcessVerification - tunnel manager application will ask user to confirm access once per process
verify:perProcessPortVerification - tunnel manger will ask user to confirm access once per process and tunnel port.
When the tunnel managers encounters a configuration that does not include the TUNNEL_SECURITY_CLASS parameter it will automatically update the configuration with the unsecure verify:BaseRequestVerification value. The tunnel manager UI does not cover this new parameter, so you'll have to update the tunnels.config file manually.
