commit fb64c55cf87615745e7c59c5bdc660119986bab1 Author: Nick Mathewson nickm@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 ------------------------