Commits

Josh VanderLinden  committed 9d042ad

Moved most of the documentation out of the .conf file into the manpage

  • Participants
  • Parent commits f547e0f

Comments (0)

Files changed (4)

 # Maintainer: Josh VanderLinden <arch@cloudlery.com>
 pkgname=autotunnel
-pkgver=0.3.0
+pkgver=0.3.1
 pkgrel=1
 pkgdesc="Easily create tunnels, reverse tunnels, and socks proxies"
 arch=('any')
   cd ..
 
   mkdir -p ${pkgdir}/etc/autotunnel.d
-  mkdir -p ${pkgdir}/etc/supervisor.d
   mkdir -p ${pkgdir}/usr/local/bin
   mkdir -p ${pkgdir}/usr/lib/systemd/system
   mkdir -p ${pkgdir}/usr/share/man/man1
 
   cp default.conf ${pkgdir}/etc/autotunnel.d/
-  cp autotunnel.ini ${pkgdir}/etc/supervisor.d/
+  cp autotunnel.ini ${pkgdir}/etc/autotunnel.d/
   cp autotunnel ${pkgdir}/usr/local/bin/
   cp *.service ${pkgdir}/usr/lib/systemd/system/
 
   # manpage
   rst2man2 README.rst > autotunnel.1
   gzip autotunnel.1
-  mkdir man1
   mv autotunnel.1.gz ${pkgdir}/usr/share/man/man1
 }
 
 autotunnel
 ==========
 
+---------------------------------------------------------
+Easily create tunnels, reverse tunnels, and socks proxies
+---------------------------------------------------------
+
+:Author: Josh VanderLinden <arch@cloudlery.com>
+:Date:   2012-10-19
+:Copyright: public domain
+:Version: 0.1
+:Manual section: 1
+:Manual group: system tools
+
+SYNOPSIS
+========
+
+    autotunnel [-k] [profile]
+
+DESCRIPTION
+===========
+
 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
 
-Options
+OPTIONS
 =======
 
-If you run ``autotunnel`` by itself, your default profile will be launched.
-Alternatively, you may launch a specific profile as such ``autotunnel
-specific-profile``.
+[-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
+                    profile will be used.
 
-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
 ===================================
 
-.. important::
-
-    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.
+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::
 
-        ssh-keygen
+    ssh-keygen
 
-    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
+    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.
 
-systemd
+SYSTEMD
 -------
 
 You have two options for starting the tunnels automatically at boot time. The
 
     systemctl enable autotunnel@profile
 
-supervisord
+SUPERVISORD
 -----------
 
-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
+replace this line::
 
     command=/usr/local/bin/autotunnel default
 
 With::
 
     command=/usr/local/bin/autotunnel specific-profile
+
+ABOUT TUNNELING
+===============
+
+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.
+
+NORMAL 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::
+
+    3306:localhost:3306
+
+allows you to access MySQL on the remote server as though it were running
+locally.
+
+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.
+
+::
+
+    TUNNELS=(
+      '33890:localhost:3389'
+      '59000:localhost:5900'
+    )
+
+REVERSE TUNNELS
+---------------
+
+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
+as::
+
+    A:[host]:B
+
+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.
+
+::
+
+    REVERSE=(
+      '2222:localhost:22'
+    )
+
+SOCKS PROXIES
+=============
+
+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
+greater than 0.

File autotunnel.install

 pre_install() {
-  [[ -d /etc/autotunnel ]] && mv /etc/autotunnel{,.d}
+  if [[ -d /etc/autotunnel ]]; then
+    mv /etc/autotunnel{,.d}
+  fi
 }
 
 pre_upgrade() {

File default.conf

 #!/bin/bash
 
-# The user you wish to login as to create tunnels
+# The user you wish to login as on the remote system to create tunnels
+
 USER=user
 
 # The hostname/IP of the system you wish to create tunnels to
+
 HOST=yourhost.com
 
 # Set to some other port, such as 8080, if you wish to setup a SOCKS proxy as
 # well. This would allow you to access the Internet via the remote $HOST.
+
 SOCKS_PORT=0
 
 # Normal tunnels to establish
 #
 # Normal tunnels allow you to access ports on the remote $HOST by accessing
 # ports on your local system.
-#
-# For example, the following will create a tunnel to $HOST that allows you to
-# access remote port 3389 (RDP) on local port 33890. Likewise, it allows you to
-# access remote port 5900 (VNC) on local port 59000.
-# TUNNELS=(
-#   '33890:localhost:3389'
-#   '59000:localhost:5900'
-# )
+
 TUNNELS=()
 
 # Reverse tunnels to establish
 #
 # Reverse tunnels allow you to access ports on your local machine by accessing
-# local 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.
-#
-# For example, say your local system is PC A and your remote $HOST 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.
-# REVERSE=(
-#   '2222:localhost:22'
-# )
+# local ports on the remote $HOST when you're logged in on that system.
+
 REVERSE=()
 
 # AutoSSH monitoring port
 #
 # This is used by autossh to make sure the connection is online. It should be
 # different for every configuration you plan to run simultaneously.
+
 AUTOSSH_PORT=8090