nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-28 06:13:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'tor-github/pr/1468'

Browse Source
This commit is contained in:
David Goulet 2019-10-30 08:53:51 -04:00
commit f579541f13
2 changed files with 118 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
changes/ticket32277 Normal file
View File

@ -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.

198
doc/tor.1.txt
View File

@ -18,145 +18,167 @@ SYNOPSIS
DESCRIPTION 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"). Tor is a connection-oriented anonymizing communication service. Users
Users bounce their TCP streams -- web traffic, ftp, ssh, etc. -- around the choose a source-routed path through a set of nodes, and negotiate a
network, and recipients, observers, and even the relays themselves have "virtual circuit" through the network. Each node in a virtual circuit
difficulty tracking the source of the stream. 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 Basically, Tor provides a distributed network of servers or relays
by providing bandwidth as a relay, change the **ORPort** configuration ("onion routers"). Users bounce their TCP streams, including web
option -- see below. Please also consult the documentation on the Tor traffic, ftp, ssh, etc., around the network, so that recipients,
Project's website. 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 COMMAND-LINE OPTIONS
-------------------- --------------------
[[opt-h]] **-h**, **--help**::
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 **<<conf-format,THE CONFIGURATION FILE
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`**::
Display a short help message and exit. 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 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 input. (Default: **`@CONFDIR@/torrc`**, or **`$HOME/.torrc`** if
found) that file is not found)
[[opt-allow-missing-torrc]] **--allow-missing-torrc**:: [[opt-allow-missing-torrc]] **`--allow-missing-torrc`**::
Do not require that configuration file specified by **-f** exist if Allow the configuration file specified by **`-f`** to be missing,
default torrc can be accessed. 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 Specify a file in which to find default values for Tor options. The
contents of this file are overridden by those in the regular contents of this file are overridden by those in the regular
configuration file, and by those on the command line. (Default: 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`**::
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, were empty. Ordinarily, Tor does this for missing default torrc files,
but not for those specified on the command line. but not for those specified on the command line.
[[opt-hash-password]] **--hash-password** __PASSWORD__:: [[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**:: [[opt-list-fingerprint]] **`--list-fingerprint`**::
Generate your keys and output your nickname and fingerprint. Generate your keys and output your nickname and fingerprint.
[[opt-verify-config]] **--verify-config**:: [[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__]:: [[opt-serviceinstall]] **`--service install`** [**`--options`** __command-line options__]::
Install an instance of Tor as a Windows service, with the provided Install an instance of Tor as a Windows service, with the provided
command-line options. Current instructions can be found at command-line options. Current instructions can be found at
https://www.torproject.org/docs/faq#NTService 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. 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. 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. 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 List all valid options that are scheduled to become obsolete in a
future version. (This is a warning, not a promise.) future version. (This is a warning, not a promise.)
[[opt-list-modules]] **--list-modules**:: [[opt-list-modules]] **`--list-modules`**::
For each optional module, list whether or not it has been compiled List whether each optional module has been compiled into Tor.
into Tor. (Any module not listed is not optional in this version of 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 Display Tor version and exit. The output is a single line of the format
"Tor version [version number]." (The version number format "Tor version [version number]." (The version number format
is as specified in version-spec.txt.) is as specified in version-spec.txt.)
[[opt-quiet]] **--quiet**|**--hush**:: [[opt-quiet]] **`--quiet`**|**`--hush`**::
Override the default console log. By default, Tor starts out logging Override the default console logging behavior. By default, Tor
messages at level "notice" and higher to the console. It stops doing so starts out logging messages at level "notice" and higher to the
after it parses its configuration, if the configuration tells it to log console. It stops doing so after it parses its configuration, if
anywhere else. You can override this behavior with the **--hush** option, the configuration tells it to log anywhere else. These options
which tells Tor to only send warnings and errors to the console, or with override the default console logging behavior. Use the
the **--quiet** option, which tells Tor not to log to the console at all. **`--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**]:: [[opt-keygen]] **`--keygen`** [**`--newpass`**]::
Running "tor --keygen" creates a new ed25519 master identity key for a Running **`tor --keygen`** creates a new ed25519 master identity key
relay, or only a fresh temporary signing key and certificate, if you for a relay, or only a fresh temporary signing key and
already have a master key. Optionally you can encrypt the master identity certificate, if you already have a master key. Optionally, you
key with a passphrase: Tor will ask you for one. If you don't want to can encrypt the master identity key with a passphrase. When Tor
encrypt the master key, just don't enter any passphrase when asked. + 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 Use the **`--newpass`** option with **`--keygen`** only when you
to add, change, or remove a passphrase on an existing ed25519 master need to add, change, or remove a passphrase on an existing ed25519
identity key. You will be prompted for the old passphase (if any), master identity key. You will be prompted for the old passphase
and the new passphrase (if any). + (if any), and the new passphrase (if any).
+ +
When generating a master key, you will probably want to use [NOTE]
**--DataDirectory** to control where the keys When generating a master key, you may want to use
and certificates will be stored, and **--SigningKeyLifetime** to **`--DataDirectory`** to control where the keys and certificates
control their lifetimes. Their behavior is as documented in the will be stored, and **`--SigningKeyLifetime`** to control their
server options section below. (You must have write access to the specified lifetimes. See the server options section to learn more about the
DataDirectory.) + 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 [normal]
directory of your Tor daemon, and make sure that they are owned by the To use the generated files, you must copy them to the
user actually running the Tor daemon on your system. __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 File descriptor to read the passphrase from. Note that unlike with the
tor-gencert program, the entire file contents are read and used as tor-gencert program, the entire file contents are read and used as
the passphrase, including any trailing newlines. 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**]:: [[opt-key-expiration]] **`--key-expiration`** [__purpose__]::
The **purpose** specifies which type of key certificate to determine The __purpose__ specifies which type of key certificate to determine
the expiration of. The only currently recognised **purpose** is the expiration of. The only currently recognised __purpose__ is
"sign". + "sign". +
+ +
Running "tor --key-expiration sign" will attempt to find your signing Running **`tor --key-expiration sign`** will attempt to find your
key certificate and will output, both in the logs as well as to stdout, signing key certificate and will output, both in the logs as well
the signing key certificate's expiration time in ISO-8601 format. as to stdout, the signing key certificate's expiration time in
For example, the output sent to stdout will be of the form: ISO-8601 format. For example, the output sent to stdout will be
"signing-cert-expiry: 2017-07-25 08:30:15 UTC" 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 THE CONFIGURATION FILE FORMAT
----------------------------- -----------------------------