man/man8/monkeysphere-host.8

   1 .TH MONKEYSPHERE-SERVER "8" "June 2008" "monkeysphere" "User Commands"
   2
   3 .SH NAME
   4
   5 monkeysphere-host \- Monkeysphere host admin tool.
   6
   7 .SH SYNOPSIS
   8
   9 .B monkeysphere-host \fIsubcommand\fP [\fIargs\fP]
  10 .br
  11 .B monkeysphere-host expert \fIexpert-subcommand\fP [\fIargs\fP]
  12
  13 .SH DESCRIPTION
  14
  15 \fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust
  16 for OpenSSH authentication.  OpenPGP keys are tracked via GnuPG, and
  17 added to the authorized_keys and known_hosts files used by OpenSSH for
  18 connection authentication.
  19
  20 \fBmonkeysphere-host\fP is a Monkeysphere server admin utility.
  21
  22 .SH SUBCOMMANDS
  23
  24 \fBmonkeysphere-host\fP takes various subcommands:
  25 .TP
  26 .B extend-key EXPIRE
  27 Extend the validity of the OpenPGP key for the host until EXPIRE from
  28 the present.  If EXPIRE is not specified, then the user will be
  29 prompted for the extension term.  Expiration is specified like GnuPG
  30 does:
  31 .nf
  32          0 = key does not expire
  33       <n>  = key expires in n days
  34       <n>w = key expires in n weeks
  35       <n>m = key expires in n months
  36       <n>y = key expires in n years
  37 .fi
  38 `e' may be used in place of `extend-key'.
  39
  40 .TP
  41 .B add-hostname HOSTNAME
  42 Add a hostname user ID to the server host key.  `n+' may be used in
  43 place of `add-hostname'.
  44 .TP
  45 .B revoke-hostname HOSTNAME
  46 Revoke a hostname user ID from the server host key.  `n-' may be used
  47 in place of `revoke-hostname'.
  48 .TP
  49 .B add-revoker FINGERPRINT
  50
  51 .TP
  52 .B show-key
  53 Output gpg information about host's OpenPGP key.  `s' may be used in
  54 place of `show-key'.
  55 .TP
  56 .B publish-key
  57 Publish the host's OpenPGP key to the keyserver.  `p' may be used in
  58 place of `publish-key'.
  59 .TP
  60 .B help
  61 Output a brief usage summary.  `h' or `?' may be used in place of
  62 `help'.
  63 .TP
  64 .B version
  65 show version number
  66 .SH "EXPERT" SUBCOMMANDS
  67 Some commands are very unlikely to be needed by most administrators.
  68 These commands must follow the word `expert'.
  69 .TP
  70 .B gen-key [HOSTNAME]
  71 Generate a OpenPGP key for the host.  If HOSTNAME is not specified,
  72 then the system fully-qualified domain name will be user.  An
  73 alternate key bit length can be specified with the `-l' or `--length'
  74 option (default 2048).  An expiration length can be specified with the
  75 `-e' or `--expire' option (prompt otherwise).  The expiration format
  76 is the same as that of \fBextend-key\fP, below.  A key revoker
  77 fingerprint can be specified with the `-r' or `--revoker' option.  `g'
  78 may be used in place of `gen-key'.
  79
  80 .TP
  81 .B diagnostics
  82 Review the state of the server with respect to the MonkeySphere in
  83 general and report on suggested changes.  Among other checks, this
  84 includes making sure there is a valid host key, that the key is
  85 published, that the sshd configuration points to the right place, and
  86 that there are at least some valid identity certifiers.  `d' may be
  87 used in place of `diagnostics'.
  88 .TP
  89 .B import-key
  90 FIXME:
  91   import-key (i)                     import existing ssh key to gpg
  92    --hostname (-h) NAME[:PORT]         hostname for key user ID
  93    --keyfile (-f) FILE                 key file to import
  94    --expire (-e) EXPIRE                date to expire
  95
  96 .SH SETUP
  97
  98 In order to start using the monkeysphere, you must first generate an
  99 OpenPGP key for the server and convert that key to an ssh key that can
 100 be used by ssh for host authentication.  This can be done with the
 101 \fBgen-key\fP subcommand:
 102
 103 $ monkeysphere-server gen-key
 104
 105 To enable host verification via the monkeysphere, you must then
 106 publish the host's key to the Web of Trust using the \fBpublish-key\fP
 107 command to push the key to a keyserver.  You must also modify the
 108 sshd_config on the server to tell sshd where the new server host key
 109 is located:
 110
 111 HostKey /var/lib/monkeysphere/ssh_host_rsa_key
 112
 113 In order for users logging into the system to be able to identify the
 114 host via the monkeysphere, at least one person (e.g. a server admin)
 115 will need to sign the host's key.  This is done using standard OpenPGP
 116 keysigning techniques, usually: pul the key from the keyserver, verify
 117 and sign the key, and then re-publish the signature.  Once an admin's
 118 signature is published, users logging into the host can use it to
 119 validate the host's key.
 120
 121 .TP
 122 MONKEYSPHERE_LOG_LEVEL
 123 Set the log level (INFO).  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in
 124 increasing order of verbosity.
 125 .TP
 126 MONKEYSPHERE_KEYSERVER
 127 OpenPGP keyserver to use (subkeys.pgp.net).
 128
 129 .SH FILES
 130 .TP
 131 /etc/monkeysphere/monkeysphere-host.conf
 132 System monkeysphere-host config file.
 133 .TP
 134 /var/lib/monkeysphere/ssh_host_rsa_key
 135 Copy of the host's private key in ssh format, suitable for use by
 136 sshd.
 137
 138 .SH AUTHOR
 139
 140 Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn
 141 Gillmor <dkg@fifthhorseman.net>
 142
 143 .SH SEE ALSO
 144
 145 .BR monkeysphere (1),
 146 .BR monkeysphere-authentication (8),
 147 .BR monkeysphere (7),
 148 .BR gpg (1),
 149 .BR ssh (1)