commit fb64c55cf87615745e7c59c5bdc660119986bab1
Author: Nick Mathewson <nickm(a)torproject.org>
Date: Thu Jan 28 10:19:29 2016 -0500
Add descriptions for --keygen to the manpage
Based on text from s7r
---
changes/bug17583 | 4 ++++
doc/tor.1.txt | 29 +++++++++++++++++++++++++++--
2 files changed, 31 insertions(+), 2 deletions(-)
diff --git a/changes/bug17583 b/changes/bug17583
new file mode 100644
index 0000000..d77d467
--- /dev/null
+++ b/changes/bug17583
@@ -0,0 +1,4 @@
+ o Documentation:
+ - Add a description of the correct use of the '--keygen' command-line
+ option. Closes ticket 17583; based on text by 's7r'.
+
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 5ea5623..0f605ff 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -95,6 +95,30 @@ COMMAND-LINE OPTIONS
which tells Tor to only send warnings and errors to the console, or with
the **--quiet** option, which tells Tor not to log to the console at all.
+[[opt-keygen]] **--keygen** [**--newpass**]
+
+ Running "tor --keygen" creates a new ed25519 master identity key for a
+ relay, or only a fresh temporary signing key and certificate, if you
+ already have a master key. Optionally you can encrypt the master identity
+ key with a passphrase: Tor will ask you for one. If you don't want to
+ encrypt the master key, just don't enter any passphrase when asked. +
+ +
+ The **--newpass** option should be used with --keygen only when you need
+ to add, change, or remove a passphrase on an existing ed25519 master
+ identity key. You will be prompted for the old passphase (if any),
+ and the new passphrase (if any). +
+ +
+ When generating a master key, you will probably want to use
+ **--DataDirectory** to control where the keys
+ and certificates will be stored, and **--SigningKeyLifetime** to
+ control their lifetimes. Their behavior is as documented in the
+ server options section below. (You must have write access to the specified
+ DataDirectory.) +
+ +
+ To use the generated files, you must copy them to the DataDirectory/keys
+ directory of your Tor daemon, and make sure that they are owned by the
+ user actually running the Tor daemon on your system.
+
Other options can be specified on the command-line in the format "--option
value", in the format "option value", or in a configuration file. For
instance, you can tell Tor to start listening for SOCKS connections on port
@@ -1908,8 +1932,9 @@ is non-zero):
[[OfflineMasterKey]] **OfflineMasterKey** **0**|**1**::
If non-zero, the Tor relay will never generate or load its master secret
- key. Instead, you'll have to use "tor --keygen" to manage the master
- secret key. (Default: 0)
+ key. Instead, you'll have to use "tor --keygen" to manage the permanent
+ ed25519 master identity key, as well as the corresponding temporary
+ signing keys and certificates. (Default: 0)
DIRECTORY SERVER OPTIONS
------------------------