rapid-tunneling: man pages for client commands.

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

6 files changed, 162 insertions, 8 deletions

diff --git a/Makefile b/Makefile
index 5fa0dc1..fb584ae 100644
--- a/Makefile
+++ b/Makefile
@@ -5,8 +5,10 @@ SCRIPTS = rapid-tunneling rapid-tunneling-status rtadm rt-from-remote
 CONFIGS = rtadm.config sshd_support_config support_env rapid-tunneling.conf gui.htpasswd
 INIT_D  = sshd_support
 GUI	= gui
-SOURCES = Makefile $(SPEC) $(SCRIPTS) $(CONFIGS) $(INIT_D) $(GUI) .placeholder
+SOURCES = Makefile $(SPEC) $(SCRIPTS) $(CONFIGS) $(INIT_D) $(GUI) \
+  .placeholder rapid-tunneling.8 rapid-tunneling-status.8
 SBINDIR	= /usr/sbin
+MANDIR	= /usr/share/man/man8
 BINDIR	= /usr/share/rapid-tunneling/bin
 WWWROOT = /var/www/html
 WWWHOME = $(WWWROOT)/support
@@ -47,6 +49,9 @@ install:
 	install -m 755 -d $(DESTDIR)$(SBINDIR)
 	install -m 755 rapid-tunneling $(DESTDIR)$(SBINDIR)
 	install -m 755 rapid-tunneling-status $(DESTDIR)$(SBINDIR)
+	install        -d $(DESTDIR)$(MANDIR)
+	install -m 644 rapid-tunneling.8 $(DESTDIR)$(MANDIR)/
+	install -m 644 rapid-tunneling-status.8 $(DESTDIR)$(MANDIR)/
 	install -m 755 -d $(DESTDIR)/usr/share/rapid-tunneling	
 	install -m 644 support_env $(DESTDIR)/usr/share/rapid-tunneling/
 	install -m 755 -d $(DESTDIR)$(BINDIR)
diff --git a/debian/TODO.Debian b/debian/TODO.Debian
index 5514c78..884972b 100644
--- a/debian/TODO.Debian
+++ b/debian/TODO.Debian
@@ -1,9 +1,12 @@
-Select through debconf if we install rapid-tunneling user as uid 0 or 
-not.
-
-If we do, we must use the current useradd command. If we don't: use 
-adduser. The web interface only assumes that there's such a user.
-
+* Select through debconf if we install rapid-tunneling user as uid 0 or 
+  not.
 
+  If we do, we must use the current useradd command. If we don't: use 
+  adduser. The web interface only assumes that there's such a user.
 * Do we delete users on purge?
-* A symlink under /var/www is only good as a quick hack.
+* A symlink under /var/www is only good as a quick hack. 
+  According to the draft webapps policy we should not rely on /var/www/ 
+  to be the web root. But this means that the package will not work out 
+  of the box. Anybody who I asked seems to dismiss this issue. I don't.
+  http://webapps-common.alioth.debian.org/draft/html/ch-httpd.html#s-httpd-register-symlinks
+  
diff --git a/debian/rapid-tunneling.install b/debian/rapid-tunneling.install
index 100fe09..cd30b4a 100644
--- a/debian/rapid-tunneling.install
+++ b/debian/rapid-tunneling.install
@@ -1,3 +1,5 @@
 usr/sbin/rapid-tunneling
 usr/sbin/rapid-tunneling-status
+usr/share/man/man8/rapid-tunneling.8
+usr/share/man/man8/rapid-tunneling-status.8
 var/lib/rapid-tunneling
diff --git a/rapid-tunneling-status.8 b/rapid-tunneling-status.8
new file mode 100644
index 0000000..d83e8ed
--- /dev/null
+++ b/rapid-tunneling-status.8
@@ -0,0 +1,84 @@
+.TH RAPID-TUNNELING-STATUS 8 "2009-03-04"
+.SH NAME
+rapid-tunneling-status \- Monitor a RapidTunneling tunnel
+.SH SYNOPSIS
+.B rapid-tunneling-status
+.I [-p] [-s] [<pid-file>]
+- show and/or kill a running connection.
+
+.B rapid-tunneling-status
+.I --help
+- Just prints a help message
+
+.SH DESCRIPTION
+.B rapid-tunneling-status
+checks if a RapidTunneling connection is running and returns its status.
+
+It can optionally print the PID of the ssh process that maintains the 
+tunnel or kill it and thus disconnect the tunnel.
+
+It must be run by the support user, as it relies on status files in the 
+home directory of that user.
+
+.SH OPTIONS
+.B -s
+.RS
+Terminate a running connection. If this option is not provided, the 
+status of the connection will be reported.
+.RE
+
+.B -p
+.RS
+If a process is running, print its PID rather than "Connected". Return 
+status remains the same.
+.RE
+
+.B pid-file
+.RS
+A file in which to check the PID of the running ssh process. Defaults to
+/var/lib/rapid-tunneling/home/pid
+.RE
+
+.SH RETURN STATUS
+.B 0
+.RS
+Returned if a process was found and is connected or if it was running 
+and has been killed.
+.RE
+
+.B 1
+.RS
+Returned if there is an ssh process running and attempting to establish
+a tunnel.
+.RE
+
+.B 2
+.RS
+Returnd if no running connection is found.
+.RE
+
+.SH FILES
+.B /var/lib/rapid-tunneling/home
+.RS
+Home directory of the client support user. Used for status and temporary 
+files. Anything there can be deleted when there's no running connection.
+.RE
+
+.SH SEE ALSO
+Full description of the operation is provided in the README file, which 
+may be /usr/share/doc/rapid-runneling/README.gz (Debian) 
+/usr/share/doc/rapid-tunneling-1.*/README (RedHat and similar) or 
+similar locations on binary packages.
+
+.BR rapid-tunneling-status (8)
+is used to control the connection.
+
+.SH BUGS
+Before running rapid-tunneling, better be sure that the remote-access-file 
+comes indeed from a trusted source. Recall that once you initiate a tunnel,
+the operator at the remote side can log into your system.
+
+.SH AUTHOR
+RapidTunneling was written by Alex Landau <alex.landau@xorcom.com>.
+
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com>
diff --git a/rapid-tunneling.8 b/rapid-tunneling.8
new file mode 100644
index 0000000..17e2502
--- /dev/null
+++ b/rapid-tunneling.8
@@ -0,0 +1,58 @@
+.TH RAPID-TUNNELING 8 "2009-03-04"
+.SH NAME
+rapid-tunneling \- Initiate a RapidTunneling tunnel
+.SH SYNOPSIS
+.B rapid-tunneling
+.I remote-access-file
+
+.SH DESCRIPTION
+.B rapid-tunneling 
+initiates a tunnel to the server whose details are provided in 
+.I remote-access-file. 
+This parameter is required.
+
+It must be run by the support user, as it relies on status files in the 
+home directory of that user.
+
+This file is a tarball. Its content is described in the README.
+But some technical details anyway:
+
+rapid-tunneling is intended to run as the support user (e.g.: through 
+sudo). It will generate a new temporary private key that is allowed to 
+connect to the support user. Next it will daemonize and connect to the 
+remote support server. The daemonized ssh process (if connected) keeps 
+the tunnel running. It also makes port 22 of the local system available 
+to the remote system (through ssh -R).
+
+The private key is sent upon connection to the remote server, which 
+allow the operator of the remote server to connect locally.
+
+.SH OPTIONS
+See description.
+
+.SH FILES
+
+.B /var/lib/rapid-tunneling/home
+.RS
+Home directory of the client support user. Used for status and temporary 
+files. Anything there can be deleted when there's no running connection.
+.RE
+
+.SH SEE ALSO
+Full description of the operation is provided in the README file, which 
+may be /usr/share/doc/rapid-runneling/README.gz (Debian) 
+/usr/share/doc/rapid-tunneling-1.*/README (RedHat and similar) or 
+similar locations on binary packages.
+
+.BR rapid-tunneling-status (8)
+is used to control the connection.
+
+.SH BUGS
+Before running rapid-tunneling, better be sure that the remote-access-file 
+comes indeed from a trusted source. Recall that once you initiate a tunnel,
+the operator at the remote side can log into your system.
+
+.SH AUTHOR
+RapidTunneling was written by Alex Landau <alex.landau@xorcom.com>.
+
+This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com>
diff --git a/rapid-tunneling.spec b/rapid-tunneling.spec
index d96b336..20047d5 100644
--- a/rapid-tunneling.spec
+++ b/rapid-tunneling.spec
@@ -100,6 +100,8 @@ fi
 %defattr(-, root, root, 0755)
 %{_sbindir}/rapid-tunneling
 %{_sbindir}/rapid-tunneling-status
+%{_mandir}/man8/rapid-tunneling.8*
+%{_mandir}/man8/rapid-tunneling-status.8*
 
 %files server
 %defattr(-, root, root, 0755)