more documentation for end users (and more FIXMEs), including README.admin in the...

[monkeysphere.git] / man / man1 / monkeysphere-ssh-proxycommand.1

diff --git a/man/man1/monkeysphere-ssh-proxycommand.1 b/man/man1/monkeysphere-ssh-proxycommand.1
index 0e6d18d90a8151a10c80e46b0299f798db77928d..5a84dc5edf9ab9e74e34077d5b836af5f7f9d7f0 100644 (file)
--- a/man/man1/monkeysphere-ssh-proxycommand.1
+++ b/man/man1/monkeysphere-ssh-proxycommand.1
@@ -7,10 +7,16 @@ monkeysphere-ssh-proxycommand \- MonkeySphere ssh ProxyCommand script
 .SH DESCRIPTION
 
 \fBmonkeysphere-ssh-proxy\fP is an ssh proxy command that can be used
-to trigger a monkeysphere update of the known_hosts file for the hosts
-that are being connected to.  It is meant to be run as an ssh
-ProxyCommand.  This can either be done by specifying the proxy command
-on the command line:
+to trigger a monkeysphere update of the ssh known_hosts file for a
+host that is being connected to with ssh.  This works by updating the
+known_hosts file for the host first, before an attempted connection to
+the host is made.  Once the known_hosts file has been updated, a TCP
+connection to the host is made by exec'ing netcat(1).  Regular ssh
+communication is then done over this netcat TCP connection (see
+ProxyCommand in ssh_config(5) for more info).
+
+This command is meant to be run as the ssh "ProxyCommand".  This can
+either be done by specifying the proxy command on the command line:
 
 .B ssh -o ProxyCommand="monkeysphere-ssh-proxycommand %h %p" ...
 
@@ -19,12 +25,14 @@ or by adding the following line to your ~/.ssh/config script:
 .B ProxyCommand monkeysphere-ssh-proxycommand %h %p
 
 The script can easily be incorporated into other ProxyCommand scripts
-by calling it with the "--no-connect" option, ie:
+by calling it with the "--no-connect" option, i.e.:
 
 .B monkeysphere-ssh-proxycommand --no-connect "$HOST" "$PORT"
 
-This will run everything but will not exec netcat to make the tcp
-connection to the host.
+This will run everything except the final exec of netcat to make the
+TCP connection to the host.  In this way this command can be added to
+another proxy command that does other stuff, and then makes the
+connection to the host itself.
 
 .SH KEYSERVER CHECKING
 
@@ -34,17 +42,17 @@ either the user's keyring or in the known_hosts file, then the
 keyserver is queried for the host userID.  If the host userID is found
 in the user's keyring, then the keyserver is not checked.  This
 assumes that the keyring is kept up-to-date, in a cron job or the
-like, so that revokations are properly handled.  If the host userID is
+like, so that revocations are properly handled.  If the host userID is
 not found in the user's keyring, but the host is listed in the
 known_hosts file, then the keyserver is not checked.  This last policy
-might change in the future, possibly by adding a defered check, so
+might change in the future, possibly by adding a deferred check, so
 that hosts that go from non-monkeysphere-enabled to
 monkeysphere-enabled will be properly checked.
 
 .SH ENVIRONMENT VARIABLES
 
 All environment variables defined in monkeysphere(1) can also be used
-for the proxycommand, with one note:
+for the proxy command, with one note:
 
 .TP
 MONKEYSPHERE_CHECK_KEYSERVER
@@ -57,6 +65,8 @@ Written by Jameson Rollins <jrollins@fifthhorseman.net>
 
 .SH SEE ALSO
 
-.BR monkeypshere (1),
+.BR monkeysphere (1),
 .BR ssh (1),
+.BR ssh_config (5),
+.BR netcat (1),
 .BR gpg (1)