summaryrefslogtreecommitdiff
path: root/man/man1/monkeysphere.1
blob: 5ed2153bcd195ed3ae8a31359107cac4c8da156d (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_LOG_LEVEL
  76. Set the log level. Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in
  77. increasing order of verbosity.
  78. .TP
  79. MONKEYSPHERE_GNUPGHOME, GNUPGHOME
  80. GnuPG home directory (~/.gnupg).
  81. .TP
  82. MONKEYSPHERE_KEYSERVER
  83. OpenPGP keyserver to use (subkeys.pgp.net).
  84. .TP
  85. MONKEYSPHERE_CHECK_KEYSERVER
  86. Whether or not to check keyserver when making gpg queries (`true').
  87. .TP
  88. MONKEYSPHERE_KNOWN_HOSTS
  89. Path to ssh known_hosts file (~/.ssh/known_hosts).
  90. .TP
  91. MONKEYSPHERE_HASH_KNOWN_HOSTS
  92. Whether or not to hash to the known_hosts file entries (`true').
  93. .TP
  94. MONKEYSPHERE_AUTHORIZED_KEYS
  95. Path to ssh authorized_keys file (~/.ssh/authorized_keys).
  96. .SH FILES
  97. .TP
  98. ~/.config/monkeysphere/monkeysphere.conf
  99. User monkeysphere config file.
  100. .TP
  101. /etc/monkeysphere/monkeysphere.conf
  102. System-wide monkeysphere config file.
  103. .TP
  104. ~/.config/monkeysphere/authorized_user_ids
  105. OpenPGP user IDs associated with keys that will be checked for
  106. addition to the authorized_keys file.
  107. .SH AUTHOR
  108. Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel
  109. Kahn Gillmor <dkg@fifthhorseman.net>
  110. .SH SEE ALSO
  111. .BR monkeysphere-ssh-proxycommand (1),
  112. .BR monkeysphere-server (8),
  113. .BR monkeysphere (5),
  114. .BR ssh (1),
  115. .BR ssh-add (1),
  116. .BR gpg (1)