-.TH MONKEYSPHERE-SERVER "1" "June 2008" "monkeysphere 0.1" "User Commands"
+.TH MONKEYSPHERE-SERVER "8" "June 2008" "monkeysphere" "User Commands"
.SH NAME
-monkeysphere-server \- monkeysphere server admin user interface
+monkeysphere-server \- Monkeysphere server admin user interface
.SH SYNOPSIS
-.B monkeysphere-server \fIcommand\fP [\fIargs\fP]
+.B monkeysphere-server \fIsubcommand\fP [\fIargs\fP]
.SH DESCRIPTION
-\fBMonkeySphere\fP is a system to leverage the OpenPGP Web of Trust
-for ssh authentication and encryption. OpenPGP keys are tracked via
-GnuPG, and added to the ssh authorized_keys and known_hosts files to
-be used for authentication of ssh connections.
+\fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust
+for OpenSSH authentication. OpenPGP keys are tracked via GnuPG, and
+added to the authorized_keys and known_hosts files used by OpenSSH for
+connection authentication.
-\fBmonkeysphere-server\fP is the MonkeySphere server admin utility.
+\fBmonkeysphere-server\fP is the Monkeysphere server admin utility.
.SH SUBCOMMANDS
\fBmonkeysphere-server\fP takes various subcommands:
.TP
-.B update-users [USER]...
-Update the admin-controlled authorized_keys files for user. For each
-user specified, update the user's authorized_keys file in
-/var/cache/monkeysphere/authorized_keys/USER. See `man monkeysphere'
-for more info. If the USER_CONTROLLED_AUTHORIZED_KEYS variable is
-set, then a user-controlled authorized_keys file (usually
-~USER/.ssh/authorized_keys) is added to the authorized_keys file. `k'
-may be used in place of `update-known_hosts'.
+.B update-users [ACCOUNT]...
+Rebuild the monkeysphere-controlled authorized_keys files. For each
+specified account, the user ID's listed in the account's
+authorized_user_ids file are processed. For each user ID, gpg will be
+queried for keys associated with that user ID, optionally querying a
+keyserver. If an acceptable key is found (see KEY ACCEPTABILITY in
+monkeysphere(7)), the key is added to the account's
+monkeysphere-controlled authorized_keys file. If the
+RAW_AUTHORIZED_KEYS variable is set, then a separate authorized_keys
+file (usually ~USER/.ssh/authorized_keys) is appended to the
+monkeysphere-controlled authorized_keys file. If no accounts are
+specified, then all accounts on the system are processed. `u' may be
+used in place of `update-users'.
.TP
-.B gen-key
-Generate a gpg key for the host. `g' may be used in place of
-`gen-key'.
+.B gen-key [HOSTNAME]
+Generate a OpenPGP key for the host. If HOSTNAME is not specified,
+then the system fully-qualified domain name will be user. An
+alternate key bit length can be specified with the `-l' or `--length'
+option (default 2048). An expiration length can be specified with the
+`-e' or `--expire' option (prompt otherwise). The expiration format
+is the same as that of \fBextend-key\fP, below. A key revoker
+fingerprint can be specified with the `-r' or `--revoker' option. `g'
+may be used in place of `gen-key'.
+.TP
+.B extend-key EXPIRE
+Extend the validity of the OpenPGP key for the host until EXPIRE from
+the present. If EXPIRE is not specified, then the user will be
+prompted for the extension term. Expiration is specified like GnuPG
+does:
+.nf
+ 0 = key does not expire
+ <n> = key expires in n days
+ <n>w = key expires in n weeks
+ <n>m = key expires in n months
+ <n>y = key expires in n years
+.fi
+`e' may be used in place of `extend-key'.
+.TP
+.B add-hostname HOSTNAME
+Add a hostname user ID to the server host key. `n+' may be used in
+place of `add-hostname'.
+.TP
+.B revoke-hostname HOSTNAME
+Revoke a hostname user ID from the server host key. `n-' may be used
+in place of `revoke-hostname'.
+.TP
+.B show-key
+Output gpg information about host's OpenPGP key. `s' may be used in
+place of `show-key'.
.TP
.B publish-key
-Publish the host's gpg key to the keyserver. `p' may be used in place
-of `publish-key'
+Publish the host's OpenPGP key to the keyserver. `p' may be used in
+place of `publish-key'.
.TP
-.B trust-keys KEYID...
-Mark key specified with key IDs with full owner trust. `t' may be used
-in place of `trust-keys'.
+.B diagnostics
+Review the state of the server with respect to the MonkeySphere in
+general and report on suggested changes. Among other checks, this
+includes making sure there is a valid host key, that the key is
+published, that the sshd configuration points to the right place, and
+that there are at least some valid identity certifiers. `d' may be
+used in place of `diagnostics'.
.TP
-.B update-user-userids USER USERID...
-Add/update a user ID to the authorized_user_ids file for USER. `u' may
-be used in place of `update-user-userids'.
+.B add-identity-certifier KEYID
+Instruct system to trust user identity certifications made by KEYID.
+Using the `-n' or `--domain' option allows you to indicate that you
+only trust the given KEYID to make identifications within a specific
+domain (e.g. "trust KEYID to certify user identities within the
+@example.org domain"). A certifier trust level can be specified with
+the `-t' or `--trust' option (possible values are `marginal' and
+`full' (default is `full')). A certifier trust depth can be specified
+with the `-d' or `--depth' option (default is 1). `c+' may be used in
+place of `add-identity-certifier'.
.TP
-.B remove-user-userids USER USERID...
-Remove a user ID from the authorized_user_ids file for USER. `r' may
-be used in place of `remove-user-userids'.
+.B remove-identity-certifier KEYID
+Instruct system to ignore user identity certifications made by KEYID.
+`c-' may be used in place of `remove-identity-certifier'.
+.TP
+.B list-identity-certifiers
+List key IDs trusted by the system to certify user identities. `c'
+may be used in place of `list-identity-certifiers'.
+.TP
+.B gpg-authentication-cmd
+Execute a gpg command on the gnupg-authentication keyring as the
+monkeysphere user. This takes a single command (multiple gpg
+arguments need to be quoted). Use this command with caution, as
+modifying the gnupg-authentication keyring can affect ssh user
+authentication.
.TP
.B help
Output a brief usage summary. `h' or `?' may be used in place of
`help'.
+.SH SETUP
+
+In order to start using the monkeysphere, you must first generate an
+OpenPGP key for the server and convert that key to an ssh key that can
+be used by ssh for host authentication. This can be done with the
+\fBgen-key\fP subcommand:
+
+$ monkeysphere-server gen-key
+
+To enable host verification via the monkeysphere, you must then
+publish the host's key to the Web of Trust using the \fBpublish-key\fP
+command to push the key to a keyserver. You must also modify the
+sshd_config on the server to tell sshd where the new server host key
+is located:
+
+HostKey /var/lib/monkeysphere/ssh_host_rsa_key
+
+In order for users logging into the system to be able to identify the
+host via the monkeysphere, at least one person (e.g. a server admin)
+will need to sign the host's key. This is done using standard OpenPGP
+keysigning techniques, usually: pul the key from the keyserver, verify
+and sign the key, and then re-publish the signature. Once an admin's
+signature is published, users logging into the host can use it to
+validate the host's key.
+
+If the server will also handle user authentication through
+monkeysphere-generated authorized_keys files, the server must be told
+which keys will act as identity certifiers. This is done with the
+\fBadd-identity-certifier\fP command:
+
+$ monkeysphere-server add-identity-certifier KEYID
+
+where KEYID is the key ID of the server admin, or whoever's
+certifications should be acceptable to the system for the purposes of
+authenticating remote users. You can run this command multiple times
+to indicate that multiple certifiers are trusted. You may also
+specify a filename instead of a key ID, as long as the file contains a
+single OpenPGP public key. Certifiers can be removed with the
+\fBremove-identity-certifier\fP command, and listed with the
+\fBlist-identity-certifiers\fP command.
+
+Remote users will then be granted access to a local account based on
+the appropriately-signed and valid keys associated with user IDs
+listed in that account's authorized_user_ids file. By default, the
+authorized_user_ids file for an account is
+~/.monkeysphere/authorized_user_ids. This can be changed in the
+monkeysphere-server.conf file.
+
+The \fBupdate-users\fP command can then be used to generate
+authorized_keys file for local accounts based on the authorized user
+IDs listed in the account's authorized_user_ids file:
+
+$ monkeysphere-server update-users USER
+
+Not specifying USER will cause all accounts on the system to updated.
+sshd can then use these monkeysphere generated authorized_keys files
+to grant access to user accounts for remote users. You must also tell
+sshd to look at the monkeysphere-generated authorized_keys file for
+user authentication by setting the following in the sshd_config:
+
+AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
+
+It is recommended to add "monkeysphere-server update-users" to a
+system crontab, so that user keys are kept up-to-date, and key
+revocations and expirations can be processed in a timely manner.
+
+.SH ENVIRONMENT
+
+The following environment variables will override those specified in
+the monkeysphere-server.conf configuration file (defaults in
+parentheses):
+.TP
+MONKEYSPHERE_MONKEYSPHERE_USER
+User to control authentication keychain (monkeysphere).
+.TP
+MONKEYSPHERE_LOG_LEVEL
+Set the log level (INFO). Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in
+increasing order of verbosity.
+.TP
+MONKEYSPHERE_KEYSERVER
+OpenPGP keyserver to use (subkeys.pgp.net).
+.TP
+MONKEYSPHERE_AUTHORIZED_USER_IDS
+Path to user authorized_user_ids file
+(%h/.monkeysphere/authorized_user_ids).
+.TP
+MONKEYSPHERE_RAW_AUTHORIZED_KEYS
+Path to user-controlled authorized_keys file. `-' means not to add
+user-controlled file (%h/.ssh/authorized_keys).
+
.SH FILES
.TP
/etc/monkeysphere/monkeysphere.conf
System-wide monkeysphere config file.
.TP
-/etc/monkeysphere/gnupg
-Monkeysphere GNUPG home directory.
+/etc/monkeysphere/gnupg-host.conf
+Monkeysphere host GNUPG home gpg.conf
+.TP
+/etc/monkeysphere/gnupg-authentication.conf
+Monkeysphere authentication GNUPG home gpg.conf
+.TP
+/var/lib/monkeysphere/authorized_keys/USER
+Monkeysphere-generated user authorized_keys files.
+.TP
+/var/lib/monkeysphere/ssh_host_rsa_key
+Copy of the host's private key in ssh format, suitable for use by
+sshd.
.TP
-/etc/monkeysphere/authorized_user_ids/USER
-Server maintained authorized_user_ids files for users.
+/var/lib/monkeysphere/gnupg-host
+Monkeysphere host GNUPG home directory.
.TP
-/var/cache/monkeysphere/authorized_keys/USER
-User authorized_keys file.
+/var/lib/monkeysphere/gnupg-authentication
+Monkeysphere authentication GNUPG home directory.
.SH AUTHOR
-Written by Jameson Rollins <jrollins@fifthhorseman.net>
+Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn
+Gillmor <dkg@fifthhorseman.net>
.SH SEE ALSO
.BR monkeysphere (1),
+.BR monkeysphere (7),
.BR gpg (1),
.BR ssh (1)