X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=man%2Fman8%2Fmonkeysphere-server.8;h=45605dae87f5660114cce9613e8e14c9847edb83;hb=e6d14b3efaa96cc55eae34556daf8f85f09b92f6;hp=39a8e5c32e93a326e1e7c597cd6b992d6f88350b;hpb=b489d119fc6c61e43c88efffb2ba4705ac4aeca8;p=monkeysphere.git diff --git a/man/man8/monkeysphere-server.8 b/man/man8/monkeysphere-server.8 index 39a8e5c..45605da 100644 --- a/man/man8/monkeysphere-server.8 +++ b/man/man8/monkeysphere-server.8 @@ -1,31 +1,131 @@ -.TH MONKEYSPHERE-SERVER "1" "June 2008" "monkeysphere 0.1" "User Commands" +.TH MONKEYSPHERE-SERVER "1" "June 2008" "monkeysphere" "User Commands" + .SH NAME + 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 -.PP -\fBmonkeysphere-server\fP is the server admin monkeysphere tool. + +\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 +connection authentication. + +\fBmonkeysphere-server\fP is the MonkeySphere server admin utility. + .SH SUBCOMMANDS + \fBmonkeysphere-server\fP takes various subcommands: -.PD .TP -.B update-users [HOST]... +.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 +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'. .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-identity-certifier KEYID +Instruct system to trust user identity certifications made by KEYID. +`a' may be used in place of `add-identity-certifier'. .TP -.B trust-keys KEYID... +.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'. .TP -.B update-user-userids USER USERID... +.B list-identity-certifiers +List key IDs trusted by the system to certify user identities. `l' +may be used in place of `list-identity-certifiers'. .TP .B help Output a brief usage summary. `h' or `?' may be used in place of `help'. -.PD + +.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. Then modify the sshd_config +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. + +If the server will also handle user authentication through +monkeysphere-generated authorized_keys files, the server must be told +which keys will act as user certifiers. This is done with the +\fBadd-certifier\fP command: + +$ 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 +\fBlist-certifiers\fP command. + +Remote user's will then be granted access to a local user account +based on the appropriately signed and valid keys associated with user +IDs listed in the authorized_user_ids file of the local user. By +default, the authorized_user_ids file for local users is found in +~/.config/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 users based on the authorized user IDs +listed in the 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: + +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. + .SH FILES -.PD 1 + .TP /etc/monkeysphere/monkeysphere-server.conf System monkeysphere-server config file. @@ -33,28 +133,27 @@ System monkeysphere-server config file. /etc/monkeysphere/monkeysphere.conf System-wide monkeysphere config file. .TP -/etc/monkeysphere/gnupg -Monkeysphere GNUPG home directory. +/var/lib/monkeysphere/authorized_keys/USER +Monkeysphere-generated user authorized_keys files. .TP -/etc/monkeysphere/authorized_user_ids/USER -Server maintained authorized_user_ids files for users. +/var/lib/monkeysphere/ssh_host_rsa_key +Copy of the host's private key in ssh format, suitable for use by +sshd. .TP -/var/lib/monkeysphere/stage/USER -Staging directory for user key caches. -.PD +/var/lib/monkeysphere/gnupg-host +Monkeysphere host GNUPG home directory. +.TP +/var/lib/monkeysphere/gnupg-authentication +Monkeysphere authentication GNUPG home directory. + .SH AUTHOR -Written by Jameson Rollins -.SH "REPORTING BUGS" -Report bugs to . -.SH COPYRIGHT -Copyright \(co 2008 Jameson Graef Rollins and Daniel Kahn Gillmor -.br -This is free software. You may redistribute copies of it under the -terms of the GNU General Public License -. There is NO WARRANTY, to the -extent permitted by law. -.SH "SEE ALSO" + +Written by Jameson Rollins , Daniel Kahn +Gillmor + +.SH SEE ALSO + .BR monkeysphere (1), +.BR monkeysphere (5), .BR gpg (1), .BR ssh (1) -