X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=man%2Fman8%2Fmonkeysphere-server.8;h=b63f65957bcacf33d6c78f90fea1b6799797f44f;hb=bb2427c28bf40179c4881b22c23f23f9bea78f55;hp=1300d8917eeb839c4bb706b3a784b00c418660a0;hpb=f5409b72c5635ff77c2cd49422206b14b2827893;p=monkeysphere.git diff --git a/man/man8/monkeysphere-server.8 b/man/man8/monkeysphere-server.8 index 1300d89..b63f659 100644 --- a/man/man8/monkeysphere-server.8 +++ b/man/man8/monkeysphere-server.8 @@ -1,70 +1,113 @@ -.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. 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 admin-controlled authorized_keys files at -/var/cache/monkeysphere/authorized_keys/USER. For each specified -user, the user ID's listed in the user's authorized_user_ids file are -processed. For each user ID, gpg will be queried for keys associated -with that user ID, querying a keyserver if specified. If a key is -found, it will be converted to an ssh key, and any matching ssh keys -will be removed from the user's authorized_keys file. If the found -key is acceptable (see KEY ACCEPTABILITY), then the key will be -updated and re-added to the authorized_keys file. If no gpg key is -found for the user ID, then nothing is done. If the -RAW_AUTHORIZED_KEYS variable is set, then a user-controlled -authorized_keys file (usually ~USER/.ssh/authorized_keys) is added to -the authorized_keys file. If no users are specified, then all users -listed in /etc/passwd are processed. `u' may be used in place of -`update-users. -.TP -.B gen-key -Generate a OpenPGP key pair for the host. `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'. +.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(5)), 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 [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 + = key expires in n days + w = key expires in n weeks + m = key expires in n months + 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 add-certifier KEYID -Add a certifier key to host keyring. The key with specified key ID -will be retrieved from the keyserver and imported to the host keyring. -It will then be given a non-exportable trust signature, with default -depth of 1, so that the key may certifier users to log into the -system. `a' may be used in place of `add-certifier'. -.TP -.B remove-certifier KEYID -Remove a certifier key from the host keyring. The key with specified -key ID will be removed entirely from the host keyring so that the key -will not longer be able to certify users on the system. `r' may be -used in place of `remove-certifier'. -.TP -.B list-certifiers -List certifier keys. `l' may be used in place of `list-certifiers'. +.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. +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. +`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 @@ -81,18 +124,19 @@ $ 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. 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 @@ -102,8 +146,8 @@ which keys will act as user certifiers. This is done with the $ 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 @@ -115,32 +159,46 @@ the monkeysphere-server.conf file. 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 KEY ACCEPTABILITY +.SH ENVIRONMENT -GPG keys are considered acceptable if the following criteria are met: +The following environment variables will override those specified in +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 +MONKEYSPHERE_AUTHORIZED_USER_IDS +Path to user authorized_user_ids file +(%h/.config/monkeysphere/authorized_user_ids). .TP -.B capability -The key must have the "authentication" ("a") usage flag set. +MONKEYSPHERE_RAW_AUTHORIZED_KEYS +Path to user-controlled authorized_keys file. `-' means not to add +user-controlled file (%h/.ssh/authorized_keys). .TP -.B validity -The key must be "fully" valid (ie. signed by a trusted certifier), and -must not be expired or revoked. +MONKEYSPHERE_MONKEYSPHERE_USER +User to control authentication keychain (monkeysphere). .SH FILES @@ -166,10 +224,12 @@ Monkeysphere authentication GNUPG home directory. .SH AUTHOR -Written by Jameson Rollins +Written by Jameson Rollins , Daniel Kahn +Gillmor .SH SEE ALSO .BR monkeysphere (1), +.BR monkeysphere (5), .BR gpg (1), .BR ssh (1)