+Easily create tunnels, reverse tunnels, and socks proxies
+:Author: Josh VanderLinden <firstname.lastname@example.org>
+:Copyright: public domain
+:Manual group: system tools
+ autotunnel [-k] [profile]
This program is intended to make it easy to establish a single or multiple
tunnels between your machine and another machine running SSH. It also has the
ability to create reverse tunnels and setup a SOCKS proxy.
#. to launch and create the tunnels
#. to kill an existing set of tunnels for a given profile
-If you run ``autotunnel`` by itself, your default profile will be launched.
-Alternatively, you may launch a specific profile as such ``autotunnel
+[-k] Kill the specified profile. If the profile is omitted, the
+ default profile will be kill.
+[profile] The name of the profile to launch. If omitted, the default
-If you wish to kill an existing set up tunnels for a given profile, you should
-use the ``-k`` parameter before the profile name::
+If you're using multiple profiles, be sure to update the `AUTOSSH_PORT` value
+in each profile so there's no conflict. This is the port that is used to
+determine if a profile is already running or not. If two profiles have the same
+`AUTOSSH_PORT`, only one of the two profiles may be running at one time.
- autotunnel -k specific-profile
-Start Tunnels Automatically at Boot
+START TUNNELS AUTOMATICALLY AT BOOT
- It's very important that you setup pre-shared key (PSK) authentication
- between your local system and the remote systems you plan to establish
- tunnels with if you want the tunnels to activate at boot time. You'll want
- to setup PSK authentication for your local `root` user to the remote
- system(s). Alternatively, you may edit the ``systemd`` unit files or
- ``supervisord`` configuration files to launch the tunnels as a user of your
+It's very important that you setup pre-shared key (PSK) authentication between
+your local system and the remote systems you plan to establish tunnels with if
+you want the tunnels to activate at boot time. You'll want to setup PSK
+authentication for your local `root` user to the remote system(s).
+Alternatively, you may edit the ``systemd`` unit files or ``supervisord``
+configuration files to launch the tunnels as a user of your choice.
- Setting up pre-shared key authentication is easy to do, and the Internet
- will be of much help to you if you're unfamiliar with it. However, I'll
- give a quick overview. As root, type this command::
+Setting up pre-shared key authentication is easy to do, and the Internet will
+be of much help to you if you're unfamiliar with it. However, I'll give a quick
+overview. As root, type this command::
- Accept all defaults. Now copy your public key to the remote host. Again, as
- root, run this command::
+Accept all defaults. Now copy your public key to the remote host. Again, as
+root, run this command::
+ ssh-copy-id remote_user@remote_host
- Obviously, replace `remote_user` and `remote_host` with the appropriate
- information. Then enter the password for `remote_user` on `remote_host`. If
- all went well, you should now be able to SSH into `remote_host` as
- `remote_user` without entering a password. If not, Google is your friend.
+Obviously, replace `remote_user` and `remote_host` with the appropriate
+information. Then enter the password for `remote_user` on `remote_host`. If all
+went well, you should now be able to SSH into `remote_host` as `remote_user`
+without entering a password. If not, Google is your friend.
You have two options for starting the tunnels automatically at boot time. The
systemctl enable autotunnel@profile
-If you're using ``supervisord``, you should be good to go automatically,
-assuming your system is configured to read `.ini` files from
-`/etc/supervisor.d`. A configuration file for the default profile should be
-installed there by default. If you wish for other profiles to be launched
-automatically, copy this file and replace this line::
+If you're using ``supervisord``, you should be able to just copy or symlink the
+default configuration to your `/etc/supervisor.d` directory::
+ cp /etc/autotunnel.d/autotunnel.ini /etc/supervisor.d/
+If you wish for other profiles to be launched automatically, copy this file and
+Tunnels are very powerful. They allow you to access remote systems by using
+local ports. Likewise, reverse tunnels allow remote systems to access your
+system by using open ports on the remote system itself.
+The profile template allows you to configure both of these types of tunnels.
+You can configure your normal tunnels by specifying them in the ``TUNNELS``
+array of your profile. Again, normal tunnels allow you to access ports on
+remote systems by using local ports on your system. They're formatted as::
+ [local port]:[host]:[remote port]
+The most basic type of tunnel forwards a port on your remote system to the same
+port on your local system. A simple case is when you want to access MySQL
+running on a remote server. A tunnel like::
+allows you to access MySQL on the remote server as though it were running
+Sometimes you may wish to create tunnels that need to use a different local
+port for whatever reason (usually that the port is already used by something
+else). The following will create a tunnel to a remote host that allows you to
+access remote port 3389 (RDP) on local port 33890 and to access remote port
+5900 (VNC) on local port 59000.
+Reverse tunnels allow you to access ports on your local machine by accessing
+open ports on the remote host when you're logged in on that system. This is a
+great way to create your own little VPN of sorts. It sometimes takes a few
+minutes to wrap your head around how reverse tunnels work. They're formatted
+Where A is the port that will open up on the remote system, which will grant
+access to port B on the local system.
+As another example, say your local system is "PC A" and your remote system is
+"PC B". When logged into PC B (either normally or via SSH), the following
+allows you to SSH into PC A. One would simply run a command like ``ssh
+pc_a_user@localhost -p 2222`` on PC B.
+SOCKS proxies are a way for you to proxy network traffic through an SSH
+connection. This is great because the traffic is encrypted, and it allows you
+to bypass things like stupid corporate Internet filters.
+To establish a SOCKS proxy, configure your profile's `SOCKS_PORT` to something