-.TH MONKEYSPHERE-SERVER "1" "June 2008" "monkeysphere" "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
.SH DESCRIPTION
-\fBMonkeySphere\fP is a framework to leverage the OpenPGP Web of Trust
-for ssh authentication. OpenPGP keys are tracked via GnuPG, and added
-to the authorized_keys and known_hosts files used by ssh for
+\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
used in place of `update-users'.
.TP
.B gen-key [HOSTNAME]
-Generate a OpenPGP key pair 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). A
-key revoker fingerprint can be specified with the `-r' or `--revoker'
-option. `g' may be used in place of `gen-key'.
-.TP
-.B show-fingerprint
-Show the fingerprint for the host's OpenPGP key. `f' may be used in place of
-`show-fingerprint'.
+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 OpenPGP key to the keyserver. `p' may be used in
place of `publish-key'.
.TP
+.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 add-identity-certifier KEYID
Instruct system to trust user identity certifications made by KEYID.
-A certifier domain can be specified with the `-n' or `--domain'
-option. A certifier trust level can be specified with the `-t' or
-`--trust' option (default is `full'). A certifier trust depth can be
-specified with the `-d' or `--depth' option (default is 1). `a' may
-be used in place of `add-identity-certifier'.
+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-identity-certifier KEYID
Instruct system to ignore user identity certifications made by KEYID.
-`r' may be used in place of `remove-identity-certifier'.
+`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. `l'
+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'.
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. Then modify the sshd_config
-to tell sshd where the new server host key is located:
+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 verify the
-host via the monkeysphere, at least one person (ie. a server admin)
-will need to sign the host's key. This is done in the same way that
-key signing is usually done, by pulling the host's key from the
-keyserver, signing the key, and re-publishing the signature. Once
-that is done, users logging into the host will be able to certify the
-host's key via the signature of the host admin.
+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 key
+signing techniquies, usually by pulling the key from the keyserver,
+signing the key, and re-publishing the signature. Once that is done,
+users logging into the host will be able to certify the host's key via
+the signature of the host admin.
If the server will also handle user authentication through
monkeysphere-generated authorized_keys files, the server must be told
$ monkeysphere-server add-certifier KEYID
where KEYID is the key ID of the server admin, or whoever's signature
-will be certifying users to the system. Certifiers can be later
-remove with the \fBremove-certifier\fP command, and listed with the
+will be certifying users to the system. Certifiers can be removed
+with the \fBremove-certifier\fP command, and listed with the
\fBlist-certifiers\fP command.
Remote user's will then be granted access to a local user account
The \fBupdate-users\fP command can then be used to generate
authorized_keys file for local users based on the authorized user IDs
-listed in the user's authorized_user_ids file:
+listed in the various local user's authorized_user_ids file:
$ monkeysphere-server update-users USER
-sshd can then use these files to grant access to user accounts for
-remote users. If no user is specified, authorized_keys files will be
-generated for all users on the system. 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:
+Not specifying a specific user will cause all users 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
-revokations and expirations can be processed in a timely manor.
+revocations and expirations can be processed in a timely manor.
.SH ENVIRONMENT
the monkeysphere-server.conf configuration file (defaults in
parentheses):
.TP
+MONKEYSPHERE_LOG_LEVEL
+Set the log level. Can be SILENT, ERROR, INFO, DEBUG, in increasing
+order of verbosity.
+.TP
MONKEYSPHERE_KEYSERVER
OpenPGP keyserver to use (subkeys.pgp.net).
.TP
user-controlled file (%h/.ssh/authorized_keys).
.TP
MONKEYSPHERE_MONKEYSPHERE_USER
-User to control authentication keychain (monkeypshere).
+User to control authentication keychain (monkeysphere).
.SH FILES
projects / monkeysphere.git / blobdiff