X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=man%2Fman8%2Fmonkeysphere-host.8;h=131b8c75ed786cff2027d89734fe36ec45a48a52;hb=9eb1c769ec82b339079ba786fce9592ec846f115;hp=330b6107a20a28c2b4c2ce355039e62b90fa8a41;hpb=278c20f82d2ee0954a04b8daae5cbc2788c0015c;p=monkeysphere.git diff --git a/man/man8/monkeysphere-host.8 b/man/man8/monkeysphere-host.8 index 330b610..131b8c7 100644 --- a/man/man8/monkeysphere-host.8 +++ b/man/man8/monkeysphere-host.8 @@ -1,14 +1,12 @@ -.TH MONKEYSPHERE-SERVER "8" "June 2008" "monkeysphere" "User Commands" +.TH MONKEYSPHERE-SERVER "8" "March 2009" "monkeysphere" "User Commands" .SH NAME -monkeysphere-host \- Monkeysphere host admin tool. +monkeysphere\-host - Monkeysphere host admin tool. .SH SYNOPSIS -.B monkeysphere-host \fIsubcommand\fP [\fIargs\fP] -.br -.B monkeysphere-host expert \fIexpert-subcommand\fP [\fIargs\fP] +.B monkeysphere\-host \fIsubcommand\fP [\fIargs\fP] .SH DESCRIPTION @@ -17,29 +15,31 @@ 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-host\fP is a Monkeysphere server admin utility. +\fBmonkeysphere\-host\fP is a Monkeysphere server admin utility for +managing the host's OpenPGP host key. .SH SUBCOMMANDS -\fBmonkeysphere-host\fP takes various subcommands: +\fBmonkeysphere\-host\fP takes various subcommands: .TP -.B import-key [NAME[:PORT]] -Import a pem-encoded ssh secret host key, from stdin. NAME[:PORT] is -used to specify the hostname (and port) used in the user ID of the new -OpenPGP key. If NAME is not specified, then the system -fully-qualified domain name will be used (ie. `hostname -f'). If PORT -is not specified, the no port is added to the user ID, which means -port 22 is assumed. `i' may be used in place of `import-key'. +.B import\-key FILE NAME[:PORT] +Import a pem-encoded ssh secret host key from file FILE. If FILE is +`\-', then the key will be imported from stdin. Only RSA keys are +supported at the moment. NAME[:PORT] is used to specify the +fully-qualified hostname (and port) used in the user ID of the new +OpenPGP key. If PORT is not specified, then no port is added to the +user ID, which means port 22 is assumed. `i' may be used in place of +`import\-key'. .TP -.B show-key +.B show\-key Output information about host's OpenPGP and SSH keys. `s' may be used -in place of `show-key'. +in place of `show\-key'. .TP -.B extend-key EXPIRE +.B set\-expire [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: +prompted for the extension term. Expiration is specified as with +GnuPG (measured from today's date): .nf 0 = key does not expire = key expires in n days @@ -47,34 +47,44 @@ does: m = key expires in n months y = key expires in n years .fi -`e' may be used in place of `extend-key'. +`e' may be used in place of `set\-expire'. .TP -.B add-hostname HOSTNAME +.B add\-hostname HOSTNAME Add a hostname user ID to the server host key. `n+' may be used in -place of `add-hostname'. +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'. +.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 add-revoker FINGERPRINT -Add a revoker to the host's OpenPGP key. `o' may be be used in place +.B add\-revoker KEYID|FILE +Add a revoker to the host's OpenPGP key. The key ID will be loaded +from the keyserver. A file may be loaded instead of pulling the key +from the keyserver by specifying the path to the file as the argument, +or by specifying `\-' to load from stdin. `r+' may be be used in place of `add-revoker'. .TP -.B revoke-key -Revoke the host's OpenPGP key. `r' may be used in place of -`revoke-key'. +.B revoke\-key +Generate (with the option to publish) a revocation certificate for the +host's OpenPGP key. If such a certificate is published, your host key +will be permanently revoked. This subcommand will ask you a series of +questions, and then generate a key revocation certificate, sending it +to stdout. If you explicitly tell it to publish the revocation +certificate immediately, it will send it to the public keyservers. +USE WITH CAUTION! .TP -.B publish-key -Publish the host's OpenPGP key to the keyserver. `p' may be used in -place of `publish-key'. +.B publish\-key +Publish the host's OpenPGP key to the public keyservers. `p' may be +used in place of `publish-key'. Note that there is no way to remove a +key from the public keyservers once it is published! +.TP +.B version +Show the monkeysphere version number. `v' may be used in place of +`version'. .TP .B help Output a brief usage summary. `h' or `?' may be used in place of `help'. -.TP -.B version -show version number Other commands: @@ -82,25 +92,41 @@ Other commands: .B diagnostics Review the state of the monkeysphere server host key 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 +there is a valid host key, that the key is not expired, that the sshd configuration points to the right place, etc. `d' may be used in place of `diagnostics'. .SH SETUP HOST AUTHENTICATION -To enable host verification via the monkeysphere, the host's key must -be published to the Web of Trust. This is not done by default. To -publish the host key to the keyservers, run the following command: +To enable host verification via the monkeysphere, an OpenPGP key must +be made out of the host's ssh key, and the key must be published to +the Web of Trust. This is not done by default. The first step is to +import the host's ssh key into a monkeysphere-style OpenPGP key. This +is done with the import\-key command. When importing a key, you must +specify the path to the host's ssh RSA key to import, and a hostname +to use as the key's user ID: -$ monkeysphere-host publish-key +# monkeysphere\-host import\-key /etc/ssh/ssh_host_rsa_key host.example.org + +On most systems, the ssh host RSA key is stored at +/etc/ssh/ssh_host_rsa_key. + +Once the host key has been imported, it must be published to the Web +of Trust so that users can retrieve the key when sshing to the host. +The host key is published to the keyserver with the publish\-key +command: + +$ monkeysphere\-host publish\-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: pull 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. +verify and sign the key, and then re-publish the signature. Please +see http://web.monkeysphere.info/signing-host-keys/ for more +information. Once an admin's signature is published, users logging +into the host can use it to validate the host's key without having to +manually check the host key's fingerprint. .SH ENVIRONMENT @@ -108,25 +134,28 @@ The following environment variables will override those specified in the config file (defaults in parentheses): .TP MONKEYSPHERE_LOG_LEVEL -Set the log level (INFO). Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in -increasing order of verbosity. +Set the log level. Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in +increasing order of verbosity. (INFO) .TP MONKEYSPHERE_KEYSERVER -OpenPGP keyserver to use (pool.sks-keyservers.net). +OpenPGP keyserver to use. (pool.sks\-keyservers.net) +.TP +MONKEYSPHERE_PROMPT +If set to `false', never prompt the user for confirmation. (true) .SH FILES .TP -/etc/monkeysphere/monkeysphere-host.conf -System monkeysphere-host config file. +/etc/monkeysphere/monkeysphere\-host.conf +System monkeysphere\-host config file. .TP -/var/lib/monkeysphere/host/ssh_host_rsa_key -Copy of the host's private key in ssh format, suitable for use by -sshd. +/var/lib/monkeysphere/host/ssh_host_rsa_key.pub.gpg +A world-readable copy of the host's public key in OpenPGP format, +including all relevant self-signatures. .SH AUTHOR -Written by: +This man page was written by: Jameson Rollins , Daniel Kahn Gillmor , Matthew Goins @@ -134,7 +163,8 @@ Matthew Goins .SH SEE ALSO .BR monkeysphere (1), -.BR monkeysphere-authentication (8), +.BR monkeysphere\-authentication (8), .BR monkeysphere (7), .BR gpg (1), -.BR ssh (1) +.BR ssh (1), +.BR sshd (8)