From 4c38fccb9bc0cfc9468b5f37d38830e30aea2739 Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Thu, 24 Oct 2019 14:17:30 -0500 Subject: [PATCH 1/5] Move command-line conf option description earlier In tor.1.txt, move the paragraphs at the end of the COMMAND-LINE OPTIONS section earlier. This text describes how the user can specify configuration options on the command line. Also clarify some wording and formatting. Based on a patch by Swati Thacker. Part of ticket 32277. --- doc/tor.1.txt | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 05e7fc948a..de01cefbf2 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -37,6 +37,29 @@ Project's website. COMMAND-LINE OPTIONS -------------------- + +Tor has a powerful command-line interface. This section lists optional +arguments you can specify at the command line using the **`tor`** +command. + +Configuration options can be specified on the command line in the +format **`--`**_OptionName_ _OptionValue_, on the command line in the +format _OptionName_ _OptionValue_, or in a configuration file. For +instance, you can tell Tor to start listening for SOCKS connections on +port 9999 by passing either **`--SocksPort 9999`** or **`SocksPort +9999`** on the command line, or by specifying **`SocksPort 9999`** in +the configuration file. On the command line, quote option values that +contain spaces. For instance, if you want Tor to log all debugging +messages to **`debug.log`**, you must specify **`--Log "debug file +debug.log"`**. + +NOTE: Configuration options on the command line override those in +configuration files. See **<>** for more information. + +The following options in this section are only recognized on the +**`tor`** command line, not in a configuration file. + [[opt-h]] **-h**, **--help**:: Display a short help message and exit. @@ -145,18 +168,7 @@ COMMAND-LINE OPTIONS For example, the output sent to stdout will be of the form: "signing-cert-expiry: 2017-07-25 08:30:15 UTC" -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 -9999 by passing --SocksPort 9999 or SocksPort 9999 to it on the command line, -or by putting "SocksPort 9999" in the configuration file. You will need to -quote options with spaces in them: if you want Tor to log all debugging -messages to debug.log, you will probably need to say **--Log** `"debug file -debug.log"`. - -Options on the command line override those in configuration files. See the -next section for more information. - +[[conf-format]] THE CONFIGURATION FILE FORMAT ----------------------------- From 90ba8bae3f3cb026239d13579e54a0e7020ab846 Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Thu, 24 Oct 2019 15:15:31 -0500 Subject: [PATCH 2/5] Reword DESCRIPTION in tor.1.txt Reword the DESCRIPTION section of tor.1.txt. Based on a patch by Swati Thacker. Part of ticket 32277. --- doc/tor.1.txt | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index de01cefbf2..fd09e30d61 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -18,22 +18,25 @@ SYNOPSIS DESCRIPTION ----------- -Tor is a connection-oriented anonymizing communication -service. Users choose a source-routed path through a set of nodes, and -negotiate a "virtual circuit" through the network, in which each node -knows its predecessor and successor, but no others. Traffic flowing down -the circuit is unwrapped by a symmetric key at each node, which reveals -the downstream node. + -Basically, Tor provides a distributed network of servers or relays ("onion routers"). -Users bounce their TCP streams -- web traffic, ftp, ssh, etc. -- around the -network, and recipients, observers, and even the relays themselves have -difficulty tracking the source of the stream. +Tor is a connection-oriented anonymizing communication service. Users +choose a source-routed path through a set of nodes, and negotiate a +"virtual circuit" through the network. Each node in a virtual circuit +knows its predecessor and successor nodes, but no other nodes. Traffic +flowing down the circuit is unwrapped by a symmetric key at each node, +which reveals the downstream node. + -By default, **tor** will act as a client only. To help the network -by providing bandwidth as a relay, change the **ORPort** configuration -option -- see below. Please also consult the documentation on the Tor -Project's website. +Basically, Tor provides a distributed network of servers or relays +("onion routers"). Users bounce their TCP streams, including web +traffic, ftp, ssh, etc., around the network, so that recipients, +observers, and even the relays themselves have difficulty tracking the +source of the stream. + +[NOTE] +By default, **tor** acts as a client only. To help the network by +providing bandwidth as a relay, change the **ORPort** configuration +option as mentioned below. Please also consult the documentation on +the Tor Project's website. COMMAND-LINE OPTIONS -------------------- From 8660a32d18e2583fb3003d9a6d9130df23829729 Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Thu, 24 Oct 2019 16:27:35 -0500 Subject: [PATCH 3/5] Reword command-options in tor.1.txt Reword the COMMAND-LINE OPTIONS section of tor.1.txt. Based on a patch by Swati Thacker. Part of ticket 32277. --- doc/tor.1.txt | 77 +++++++++++++++++++++++++++------------------------ 1 file changed, 41 insertions(+), 36 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index fd09e30d61..b9738cdb63 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -68,13 +68,13 @@ The following options in this section are only recognized on the [[opt-f]] **-f** __FILE__:: Specify a new configuration file to contain further Tor configuration - options OR pass *-* to make Tor read its configuration from standard + options, or pass *-* to make Tor read its configuration from standard input. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not found) [[opt-allow-missing-torrc]] **--allow-missing-torrc**:: - Do not require that configuration file specified by **-f** exist if - default torrc can be accessed. + Allow the configuration file specified by **-f** to be missing, if + the defaults-torrc file (see below) is accessible. [[opt-defaults-torrc]] **--defaults-torrc** __FILE__:: Specify a file in which to find default values for Tor options. The @@ -83,18 +83,18 @@ The following options in this section are only recognized on the @CONFDIR@/torrc-defaults.) [[opt-ignore-missing-torrc]] **--ignore-missing-torrc**:: - Specifies that Tor should treat a missing torrc file as though it + Specify that Tor should treat a missing torrc file as though it were empty. Ordinarily, Tor does this for missing default torrc files, but not for those specified on the command line. [[opt-hash-password]] **--hash-password** __PASSWORD__:: - Generates a hashed password for control port access. + Generate a hashed password for control port access. [[opt-list-fingerprint]] **--list-fingerprint**:: Generate your keys and output your nickname and fingerprint. [[opt-verify-config]] **--verify-config**:: - Verify the configuration file is valid. + Verify whether the configuration file is valid. [[opt-serviceinstall]] **--service install** [**--options** __command-line options__]:: Install an instance of Tor as a Windows service, with the provided @@ -115,8 +115,8 @@ The following options in this section are only recognized on the future version. (This is a warning, not a promise.) [[opt-list-modules]] **--list-modules**:: - For each optional module, list whether or not it has been compiled - into Tor. (Any module not listed is not optional in this version of Tor.) + List whether each optional module has been compiled into Tor. + (Any module not listed is not optional in this version of Tor.) [[opt-version]] **--version**:: Display Tor version and exit. The output is a single line of the format @@ -124,41 +124,46 @@ The following options in this section are only recognized on the is as specified in version-spec.txt.) [[opt-quiet]] **--quiet**|**--hush**:: - Override the default console log. By default, Tor starts out logging - messages at level "notice" and higher to the console. It stops doing so - after it parses its configuration, if the configuration tells it to log - anywhere else. You can override this behavior with the **--hush** option, - 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. + Override the default console logging behavior. By default, Tor + starts out logging messages at level "notice" and higher to the + console. It stops doing so after it parses its configuration, if + the configuration tells it to log anywhere else. These options + override the default console logging behavior. Use the **--hush** + option if you want Tor to log only warnings and errors to the + console, or use the **--quiet** option if you want 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. + + 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. When Tor + asks you for a passphrase and 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. + Use the **--newpass** option 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). ++ +[NOTE] +When generating a master key, you may want to use **--DataDirectory** +to control where the keys and certificates will be stored, and +**--SigningKeyLifetime** to control their lifetimes. See the server +options section to learn more about the behavior of these options. +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. **--passphrase-fd** __FILEDES__:: - Filedescriptor to read the passphrase from. Note that unlike with the + File descriptor to read the passphrase from. Note that unlike with the tor-gencert program, the entire file contents are read and used as the passphrase, including any trailing newlines. - Default: read from the terminal. + If the file descriptor is not specified, the passphrase is read + from the terminal by default. [[opt-key-expiration]] **--key-expiration** [**purpose**]:: The **purpose** specifies which type of key certificate to determine From 5e4ae730516712080b3844a1eb632cd4678b9cca Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Thu, 24 Oct 2019 16:41:32 -0500 Subject: [PATCH 4/5] Reformat some options in tor.1.txt Reformat command line options in tor.1.txt to display as fixed-width in the HTML version. Based on a patch by Swati Thacker. Part of ticket 32277. --- doc/tor.1.txt | 100 +++++++++++++++++++++++++------------------------- 1 file changed, 51 insertions(+), 49 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index b9738cdb63..d5297f77ce 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -63,118 +63,120 @@ FORMAT>>** for more information. The following options in this section are only recognized on the **`tor`** command line, not in a configuration file. -[[opt-h]] **-h**, **--help**:: +[[opt-h]] **`-h`**, **`--help`**:: Display a short help message and exit. -[[opt-f]] **-f** __FILE__:: +[[opt-f]] **`-f`** __FILE__:: Specify a new configuration file to contain further Tor configuration options, or pass *-* to make Tor read its configuration from standard - input. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not - found) + input. (Default: **`@CONFDIR@/torrc`**, or **`$HOME/.torrc`** if + that file is not found) -[[opt-allow-missing-torrc]] **--allow-missing-torrc**:: - Allow the configuration file specified by **-f** to be missing, if - the defaults-torrc file (see below) is accessible. +[[opt-allow-missing-torrc]] **`--allow-missing-torrc`**:: + Allow the configuration file specified by **`-f`** to be missing, + if the defaults-torrc file (see below) is accessible. -[[opt-defaults-torrc]] **--defaults-torrc** __FILE__:: +[[opt-defaults-torrc]] **`--defaults-torrc`** __FILE__:: Specify a file in which to find default values for Tor options. The contents of this file are overridden by those in the regular configuration file, and by those on the command line. (Default: - @CONFDIR@/torrc-defaults.) + **`@CONFDIR@/torrc-defaults`**.) -[[opt-ignore-missing-torrc]] **--ignore-missing-torrc**:: +[[opt-ignore-missing-torrc]] **`--ignore-missing-torrc`**:: Specify that Tor should treat a missing torrc file as though it were empty. Ordinarily, Tor does this for missing default torrc files, but not for those specified on the command line. -[[opt-hash-password]] **--hash-password** __PASSWORD__:: +[[opt-hash-password]] **`--hash-password`** __PASSWORD__:: Generate a hashed password for control port access. -[[opt-list-fingerprint]] **--list-fingerprint**:: +[[opt-list-fingerprint]] **`--list-fingerprint`**:: Generate your keys and output your nickname and fingerprint. -[[opt-verify-config]] **--verify-config**:: +[[opt-verify-config]] **`--verify-config`**:: Verify whether the configuration file is valid. -[[opt-serviceinstall]] **--service install** [**--options** __command-line options__]:: +[[opt-serviceinstall]] **`--service install`** [**`--options`** __command-line options__]:: Install an instance of Tor as a Windows service, with the provided command-line options. Current instructions can be found at https://www.torproject.org/docs/faq#NTService -[[opt-service]] **--service** **remove**|**start**|**stop**:: +[[opt-service]] **`--service`** **`remove`**|**`start`**|**`stop`**:: Remove, start, or stop a configured Tor Windows service. -[[opt-nt-service]] **--nt-service**:: +[[opt-nt-service]] **`--nt-service`**:: Used internally to implement a Windows service. -[[opt-list-torrc-options]] **--list-torrc-options**:: +[[opt-list-torrc-options]] **`--list-torrc-options`**:: List all valid options. -[[opt-list-deprecated-options]] **--list-deprecated-options**:: +[[opt-list-deprecated-options]] **`--list-deprecated-options`**:: List all valid options that are scheduled to become obsolete in a future version. (This is a warning, not a promise.) -[[opt-list-modules]] **--list-modules**:: +[[opt-list-modules]] **`--list-modules`**:: List whether each optional module has been compiled into Tor. (Any module not listed is not optional in this version of Tor.) -[[opt-version]] **--version**:: +[[opt-version]] **`--version`**:: Display Tor version and exit. The output is a single line of the format "Tor version [version number]." (The version number format is as specified in version-spec.txt.) -[[opt-quiet]] **--quiet**|**--hush**:: +[[opt-quiet]] **`--quiet`**|**`--hush`**:: Override the default console logging behavior. By default, Tor starts out logging messages at level "notice" and higher to the console. It stops doing so after it parses its configuration, if the configuration tells it to log anywhere else. These options - override the default console logging behavior. Use the **--hush** - option if you want Tor to log only warnings and errors to the - console, or use the **--quiet** option if you want Tor not to log - to the console at all. + override the default console logging behavior. Use the + **`--hush`** option if you want Tor to log only warnings and + errors to the console, or use the **`--quiet`** option if you want + Tor not to log to the console at all. -[[opt-keygen]] **--keygen** [**--newpass**]:: - Running "tor --keygen" creates a new ed25519 master identity key +[[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. When Tor asks you for a passphrase and you don't want to encrypt the master key, just don't enter any passphrase when asked. + + - Use the **--newpass** option 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). + Use the **`--newpass`** option 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). + [NOTE] -When generating a master key, you may want to use **--DataDirectory** -to control where the keys and certificates will be stored, and -**--SigningKeyLifetime** to control their lifetimes. See the server -options section to learn more about the behavior of these options. -You must have write access to the specified DataDirectory. + When generating a master key, you may want to use + **`--DataDirectory`** to control where the keys and certificates + will be stored, and **`--SigningKeyLifetime`** to control their + lifetimes. See the server options section to learn more about the + behavior of these options. 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. +[normal] + 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. -**--passphrase-fd** __FILEDES__:: +**`--passphrase-fd`** __FILEDES__:: File descriptor to read the passphrase from. Note that unlike with the tor-gencert program, the entire file contents are read and used as the passphrase, including any trailing newlines. If the file descriptor is not specified, the passphrase is read from the terminal by default. -[[opt-key-expiration]] **--key-expiration** [**purpose**]:: - The **purpose** specifies which type of key certificate to determine - the expiration of. The only currently recognised **purpose** is +[[opt-key-expiration]] **`--key-expiration`** [__purpose__]:: + The __purpose__ specifies which type of key certificate to determine + the expiration of. The only currently recognised __purpose__ is "sign". + + - Running "tor --key-expiration sign" will attempt to find your signing - key certificate and will output, both in the logs as well as to stdout, - the signing key certificate's expiration time in ISO-8601 format. - For example, the output sent to stdout will be of the form: - "signing-cert-expiry: 2017-07-25 08:30:15 UTC" + Running **`tor --key-expiration sign`** will attempt to find your + signing key certificate and will output, both in the logs as well + as to stdout, the signing key certificate's expiration time in + ISO-8601 format. For example, the output sent to stdout will be + of the form: "signing-cert-expiry: 2017-07-25 08:30:15 UTC" [[conf-format]] THE CONFIGURATION FILE FORMAT From 1e8ddbe1ee1a3b1b99ff40dc1acb748eba29d16e Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Thu, 24 Oct 2019 17:59:28 -0500 Subject: [PATCH 5/5] Changes file for ticket 32277 --- changes/ticket32277 | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changes/ticket32277 diff --git a/changes/ticket32277 b/changes/ticket32277 new file mode 100644 index 0000000000..1ef0c4ab56 --- /dev/null +++ b/changes/ticket32277 @@ -0,0 +1,5 @@ + o Documentation (manpage): + - In the tor(1) manpage, reword and improve formatting of the + COMMAND-LINE OPTIONS and DESCRIPTION sections. Closes ticket + 32277. Based on work by Swati Thacker as part of Google Season + of Docs.