From 563cdc2241c914f3d31421bbc81d5dd70ee15bb0 Mon Sep 17 00:00:00 2001 From: Tzafrir Cohen Date: Mon, 5 Jan 2009 22:36:23 +0000 Subject: Update README with some initial documentation git-svn-id: svn+ssh://xorcom/home/svn/debs/components/rapid-tunneling@6552 283159da-0705-0410-b60c-f2062b4bb6ad --- README | 236 +++++++++++++++++++++++++++++++++++++++++++++-------------------- 1 file 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 < - where, - is a local port on the intermediate computer through which - connection to the remote system will be made. - 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 -7. Connect to the client: - * ssh ra- - * scp ra-:blabla . - * If you want to have remote access to the GUI then: - ssh -g -L :127.0.0.1:8088 ra- - where, port1 is any local port on intermediate computer. - You can point your Firefox to the following address: - http://:/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 +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:///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 [options] + Commands: + create [-e] + # create invitation tar.gz, if -e specified, enable it + show + # show current connections + enable + disable + # enable/disable future connections + disconnect + # disconnect connection + delete + # 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-.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 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. -- cgit v1.2.3