summaryrefslogtreecommitdiff
path: root/man/man1/monkeysphere.1
blob: 92ba2fa076512043c404495c37d73b53802f84e7 (plain)
  1. .TH MONKEYSPHERE "1" "June 2008" "monkeysphere 0.1" "User Commands"
  2. .SH NAME
  3. monkeysphere \- Monkeysphere client user interface
  4. .SH SYNOPSIS
  5. .B monkeysphere \fIsubcommand\fP [\fIargs\fP]
  6. .SH DESCRIPTION
  7. \fBMonkeysphere\fP is a framework to leverage the OpenPGP web of trust
  8. for OpenSSH authentication. OpenPGP keys are tracked via GnuPG, and
  9. added to the authorized_keys and known_hosts files used by OpenSSH for
  10. connection authentication.
  11. \fBmonkeysphere\fP is the Monkeysphere client utility.
  12. .SH SUBCOMMANDS
  13. \fBmonkeysphere\fP takes various subcommands:
  14. .TP
  15. .B update-known_hosts [HOST]...
  16. Update the known_hosts file. For each specified host, gpg will be
  17. queried for a key associated with the host URI (see HOST
  18. IDENTIFICATION in
  19. .BR monkeysphere(5)),
  20. optionally querying a keyserver.
  21. If an acceptable key is found for the host (see KEY ACCEPTABILITY in
  22. .BR monkeysphere(5)),
  23. the key is added to the user's known_hosts file. If a key is found
  24. but is unacceptable for the host, any matching keys are removed from
  25. the user's known_hosts file. If no gpg key is found for the host,
  26. nothing is done. If no hosts are specified, all hosts listed in the
  27. known_hosts file will be processed. This subcommand will exit with a
  28. status of 0 if at least one acceptable key was found for a specified
  29. host, 1 if no matching keys were found at all, and 2 if matching keys
  30. were found but none were acceptable. `k' may be used in place of
  31. `update-known_hosts'.
  32. .TP
  33. .B update-authorized_keys
  34. Update the authorized_keys file for the user executing the command
  35. (see MONKEYSPHERE_AUTHORIZED_KEYS in ENVIRONMENT, below). First all
  36. monkeysphere keys are cleared from the authorized_keys file. Then, or
  37. each user ID in the user's authorized_user_ids file, gpg will be
  38. queried for keys associated with that user ID, optionally querying a
  39. keyserver. If an acceptable key is found (see KEY ACCEPTABILITY in
  40. .BR monkeysphere (5)),
  41. the key is added to the user's authorized_keys file.
  42. If a key is found but is unacceptable for the user ID, any matching
  43. keys are removed from the user's authorized_keys file. If no gpg key
  44. is found for the user ID, nothing is done. This subcommand will exit
  45. with a status of 0 if at least one acceptable key was found for a user
  46. ID, 1 if no matching keys were found at all, and 2 if matching keys
  47. were found but none were acceptable. `a' may be used in place of
  48. `update-authorized_keys'.
  49. .TP
  50. .B gen-subkey [KEYID]
  51. Generate an authentication subkey for a private key in your GnuPG
  52. keyring. For the primary key with the specified key ID, generate a
  53. subkey with "authentication" capability that can be used for
  54. monkeysphere transactions. An expiration length can be specified with
  55. the `-e' or `--expire' option (prompt otherwise). If no key ID is
  56. specified, but only one key exists in the secret keyring, that key
  57. will be used. `g' may be used in place of `gen-subkey'.
  58. .TP
  59. .B subkey-to-ssh-agent [ssh-add arguments]
  60. Push all authentication-capable subkeys in your GnuPG secret keyring
  61. into your running ssh-agent. Additional arguments are passed through
  62. to
  63. .BR ssh-add (1).
  64. For example, to remove the authentication subkeys, pass an additional
  65. `-d' argument. To require confirmation on each use of the key, pass
  66. `-c'. `s' may be used in place of `subkey-to-ssh-agent'.
  67. .TP
  68. .B help
  69. Output a brief usage summary. `h' or `?' may be used in place of
  70. `help'.
  71. .SH ENVIRONMENT
  72. The following environment variables will override those specified in
  73. the monkeysphere.conf configuration file (defaults in parentheses):
  74. .TP
  75. MONKEYSPHERE_GNUPGHOME, GNUPGHOME
  76. GnuPG home directory (~/.gnupg).
  77. .TP
  78. MONKEYSPHERE_KEYSERVER
  79. OpenPGP keyserver to use (subkeys.pgp.net).
  80. .TP
  81. MONKEYSPHERE_CHECK_KEYSERVER
  82. Whether or not to check keyserver when making gpg queries (`true').
  83. .TP
  84. MONKEYSPHERE_KNOWN_HOSTS
  85. Path to ssh known_hosts file (~/.ssh/known_hosts).
  86. .TP
  87. MONKEYSPHERE_HASH_KNOWN_HOSTS
  88. Whether or not to hash to the known_hosts file entries (`true').
  89. .TP
  90. MONKEYSPHERE_AUTHORIZED_KEYS
  91. Path to ssh authorized_keys file (~/.ssh/authorized_keys).
  92. .SH FILES
  93. .TP
  94. ~/.config/monkeysphere/monkeysphere.conf
  95. User monkeysphere config file.
  96. .TP
  97. /etc/monkeysphere/monkeysphere.conf
  98. System-wide monkeysphere config file.
  99. .TP
  100. ~/.config/monkeysphere/authorized_user_ids
  101. OpenPGP user IDs associated with keys that will be checked for
  102. addition to the authorized_keys file.
  103. .SH AUTHOR
  104. Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel
  105. Kahn Gillmor <dkg@fifthhorseman.net>
  106. .SH SEE ALSO
  107. .BR monkeysphere-ssh-proxycommand (1),
  108. .BR monkeysphere-server (8),
  109. .BR monkeysphere (5),
  110. .BR ssh (1),
  111. .BR ssh-add (1),
  112. .BR gpg (1)