Update README with some initial documentation

git-svn-id: svn+ssh://xorcom/home/svn/debs/components/rapid-tunneling@6552 283159da-0705-0410-b60c-f2062b4bb6ad

1 files changed, 164 insertions, 72 deletions

diff --git a/README b/README
index e4cb352..4570f98 100644
--- a/README
+++ b/README
@@ -1,77 +1,169 @@
 Prepare computer for SSH tunneling
 ==================================
+
+Rapid Tunnelling(tm) uses the capabilities of openssh to allow you to 
+support your clients even behind firewalls.
+
+The software includes a client-side component and a server-side component.
+Both are mainly built around the features of the ssh protocol to provide 
+tunneling.
+
+The server should have a well-known address (hostname/IP and port) that
+the client will use to establish a connection. The client initiates an
+initial ssh connection to the server and provides the server reverse port
+forwarding.
+
+Furthermore, the client sets up an ability for the user on the server
+to login to the client system using an ssh private key that is sent on
+the connection. Thus the support personnel on the support server can login.
+
+
 Setup
 -----
-* apt-get install realpath
-* Create a new user named "support" (can be anything else).
-* Disable password login (put "*" in /etc/passwd instead of "x").
-* cp /etc/ssh/sshd_config /etc/ssh/sshd_support_config
-* vi /etc/ssh/sshd_support_config
- o Port 2222
- o Protocol 2
- o PermitEmptyPasswords no
- o PasswordAuthentication no
- o X11Forwarding no
- o PrintLastLog no
- o UsePAM no
- o AllowUsers support
-
-   /usr/sbin/sshd -f /etc/ssh/sshd_support_config
-   su - support
-   mkdir -m 700 .ssh
-   touch .ssh/authorized_keys
-   mkdir .ssh/sock
-   cat > .ssh/config <<EOF
-   Host *
-   	StrictHostKeyChecking no
-   	ControlMaster auto
-   	ControlPath ~/.ssh/sock/%r@%h:%p
-   EOF
-
-* Optionally create a public/private key for local login and place the 
-  public one in .ssh/authorized_keys.
-* Copy the following files to /usr/local/bin:
-  o create-invitation
-  o finish-ra
-  o prepare-connect 
-* Change the required parameters in create-invitation (host, port and user).
-* mkdir bin
-* Copy from-remote to ~/bin. 
-
-Use
----
-
-1. Connect to the intermediate computer as root and then switch to user 
-   "support":
-   * su - support 
-2. Create invitation:
-   * create-invitation <port> <comment>
-     where,
-     <port> is a local port on the intermediate computer through which 
-     connection to the remote system will be made.
-     <comment> a single word that must be unique among other current remote 
-     support connections.
-     * remote-access.tar.gz will be created in current directory. This 
-       file should be mailed to the client. 
-3. Enable login with this invitation:
-   * The command to enter will be printed upon invitation creation. 
-4. Check who can login:
-   * cat .ssh/authorized_keys 
-5. Check who is currently logged in:
-   * ps aux | grep sleep-ra 
-6. Prepare connection back to the client (should be done once after the client logs in and before being able to connect back):
-   * prepare-connect <comment> 
-7. Connect to the client:
-   * ssh ra-<comment>
-   * scp ra-<comment>:blabla .
-   * If you want to have remote access to the GUI then:
-     ssh -g -L <port1>:127.0.0.1:8088 ra-<comment>
-     where, port1 is any local port on intermediate computer.
-     You can point your Firefox to the following address:
-     http://<intermediate_computer_address>:<port1>/asterisk/static/config/cfgbasic.html 
-8. Disconnect from the client:
-   * Quit all ssh and scp sessions.
-   * ps aux | grep sleep-ra, kill the appropriate process 
-9. Disallow further logins via this invitation:
-   * finish-ra <comment> 
+Server
+~~~~~~
+The server has an extra service running (an extra instance of sshd with 
+different configuration). Forthermore, it has a special user called 
+'support'. This will be the user generating the connections and connecting
+to remote users. 
+
+* Install the package rapid-tunneling-server
+* Edit the host (name/IP) and port in /etc/rapid-tunnelling/rtadm . This 
+  is where the client should connect to.
+* Make sure that that sshd_support is running. E.g.: that it listens 
+  on port 2222.
+* Provide a special way for the support user to login. It cannot login 
+  through ssh. One possible way is from another user account through 
+  sudo -i .
+* Create a gpg key and make it the secret key of the support user. 
+  (See also below on 'rtadm keygen'). The public key should be imported 
+  into every client machine.
+
+
+Client
+~~~~~~
+* Install the packages rapid-tunneling (base package) and 
+  rapid-tunneling-gui (simple web interface).
+* Package installs a user called rapid-tunneling for all the dirty work.
+* Due to original requirements, that is actually a "user" with uid 0.
+  However the system should work just as well with this being a normal 
+  user.
+* The cleint only trusts servers for which it has the keys. Make sure it
+  knows the keys with which you sign on the server.
+* The -gui places a web interface on http://<hostname>/support . 
+  While technically this interface should only allow usage through 
+  a signed tarball, you may still wish to limit access to it.
+
+
+Usage
+-----
+Connecting
+~~~~~~~~~~
+Clint the client opens a support ticket. Someone logs into the support 
+user on the server and runs:
+
+  rtadm create 4567 clint
+  rtadm enable clint
+
+4567::
+  The port clint will open on the server (using ssh -R). 
+  Thus make sure it is unique for the time of the support.
+
+clint::
+  A string used to identify this connection.
+
+This has created 'remote-access-clint.tar.gz' which has the details of
+the connection. The next step is to deliver that tarball to the client.
+
+The client now connects to the web interface, places the tarball and clicks
+on "Connect". A connection should be established.
+
+Which means that the support user can now connect with ssh to 'ra-clint'
+and be logged on to the special rapid-tunneling account on Client's 
+machine.
+
+When the client has had enough, the client selects "disconnect" from
+the web interface.
+
+
+Server Operation
+----------------
+rtadm
+~~~~~
+The utility that controls things on the server side. 
+
+TODO: document it. For starters, its help message:
+
+  Usage: /usr/share/rapid-tunneling/bin/rtadm <command> [options]
+  Commands:
+  create [-e] <tunnel-port> <connection-name>
+    # create invitation tar.gz, if -e specified, enable it
+  show
+    # show current connections
+  enable <connection-name>
+  disable <connection-name>
+    # enable/disable future connections
+  disconnect <connection-name>
+    # disconnect connection
+  delete <connection-name>
+    # disconnect, disable and delete any trace of the connection
+  genkey
+    # Generate an OpenPGP key for signing tarballs (interactive)
+
+"Enabled" connection is a connection that can start a new tunnel. 
+Disabling it does not Disconnect an existing connection.
+
+
+Server Troubleshooting
+~~~~~~~~~~~~~~~~~~~~~~
+All the log files and such...
+
+
+Client Operation
+----------------
+Here should be described the actual command-line interface.
+
+For starters:
+
+A connection is maintianed by a daemonized ssh process.
+
+
+rapid-tunneling
+~~~~~~~~~~~~~~~
+Used to start the connection:
+
+  rapid-tunneling remote-access-<name>.tar.gz
+
+
+rapid-tunneling-status
+~~~~~~~~~~~~~~~~~~~~~~
+Prints out a textual status and also returns:
+
+* 0: Connected
+* 1: Connecting
+* 2: Disconnected
+
+Can also be used to disconnect a running connection by killing the ssh
+process that maintains it.
+
+
+Security
+--------
+The remote access tarball is sent potentially over an untrusted channel
+(read: the Internet). It contains potentially sensitive information: a 
+private ssh key. An imposter could try to impersionate as the client.
+But I can see no specific benifit here. We did not want to assume that
+the server has any prior knowledge of the client, anyway.
+
+However that private key only allows a remote user very limited ability:
+The authorized_keys line is:
+
+no-X11-forwarding,no-agent-forwarding,no-pty,permitopen="127.0.0.1:65534",command="/usr/share/rapid-tunneling/bin/rt-from-remote 4567" ssh-rsa <snip lengthy key> ra-4567-clint-20090105180013
+
+The client only allows requests that are signed by someone hopefully 
+trusted by the client, as implied from the gpg ring of the 
+rapid-tunneling account on the client.
+
+THe client then sends the connection information over the already
+established connection.