breaking out README.admin from README, adding a few TODOs

[monkeysphere.git] / doc / README

diff --git a/doc/README b/doc/README
index cda1194336bfb028e8fabd71f46c3d0104fdc088..7aa2850656263883b35508156b025f8d2d9366d6 100644 (file)
--- a/doc/README
+++ b/doc/README
@@ -1,56 +1,39 @@
-Monkeysphere README
-===================
+Monkeysphere User README
+========================
 
-user usage
-----------
-For a user to update their known_hosts file:
+As a regular user on a system where the monkeysphere package is
+installed, you probably want to do a few things:
 
-$ monkeysphere update-known_hosts
-
-For a user to update their monkeysphere authorized_keys file:
+Keeping your keyring up-to-date
+-------------------------------
 
-$ monkeysphere update-authorized_keys
+Regularly refresh your GnuPG keyring from the keyservers.  This can be
+done with a simple cronjob.
 
-server service publication
---------------------------
-To publish a server host key:
+FIXME: give an example of a useful cronjob
 
-# monkeysphere-server gen-key
-# monkeysphere-server publish-key
 
-This will generate the key for server with the service URI
-(ssh://server.hostname).  The server admin should now sign the server
-key so that people in the admin's web of trust can authenticate the
-server without manual host key checking:
+Keeping your known_hosts file in sync with your keyring
+-------------------------------------------------------
 
-$ gpg --search ='ssh://server.hostname'
-$ gpg --sign-key 'ssh://server.hostname'
+With your keyring updated, you want to make sure that openssh can
+still see the most recent trusted information about who the various
+hosts are:
 
-server authorized_keys maintenance
-----------------------------------
-A system can maintain monkeysphere authorized_keys files for it's
-users.
+$ monkeysphere update-known_hosts
 
-For each user account on the server, the userids of people authorized
-to log into that account would be placed in:
 
-/etc/monkeysphere/authorized_user_ids/USER
+Using monkeysphere-ssh-proxycommand(1)
+--------------------------------------
 
-However, in order for users to become authenticated, the server must
-determine that the user keys have "full" validity.  This means that
-the server must fully trust at least one person whose signature on the
-connecting users key would validate the user.  This would generally be
-the server admin.  If the server admin's keyid is XXXXXXXX, then on
-the server run:
+FIXME: make a suggestion about how to integrate this in daily use.
 
-# monkeysphere-server trust-keys XXXXXXXX
 
-To update the monkeysphere authorized_keys file for user "bob", the
-system would then run the following:
+Miscellaneous
+-------------
 
-# monkeysphere-server update-users bob
+For a user to update their monkeysphere authorized_keys file:
 
-To update the monkeysphere authorized_keys file for all users on the
-the system, run the same command with no arguments:
+$ monkeysphere update-authorized_keys
 
-# monkeysphere-server update-users
+FIXME: where is this file located?  What does this command do?