mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-11-24 04:13:28 +01:00
Merge branch 'tor-github/pr/1468'
This commit is contained in:
David Goulet
commit
f579541f13
5
changes/ticket32277
Normal file
5
changes/ticket32277
Normal 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.
|
||||
204
doc/tor.1.txt
204
doc/tor.1.txt
@ -18,145 +18,167 @@ 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
|
||||
--------------------
|
||||
[[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.
|
||||
|
||||
[[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)
|
||||
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.
|
||||
[[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**::
|
||||
Specifies that Tor should treat a missing torrc file as though it
|
||||
[[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__::
|
||||
Generates a hashed password for control port access.
|
||||
[[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**::
|
||||
Verify the configuration file is valid.
|
||||
[[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**::
|
||||
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.)
|
||||
[[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**::
|
||||
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.
|
||||
[[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.
|
||||
|
||||
[[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. +
|
||||
[[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. +
|
||||
+
|
||||
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.
|
||||
+
|
||||
[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__::
|
||||
Filedescriptor to read the passphrase from. Note that unlike with the
|
||||
**`--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.
|
||||
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
|
||||
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"
|
||||
|
||||
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.
|
||||
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
|
||||
-----------------------------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user