diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING | 15 | ||||
| -rw-r--r-- | doc/TUNING | 39 | ||||
| -rw-r--r-- | doc/include.am | 4 | ||||
| -rw-r--r-- | doc/tor-resolve.1.txt | 5 | ||||
| -rw-r--r-- | doc/tor.1.txt | 118 |
5 files changed, 143 insertions, 38 deletions
diff --git a/doc/HACKING b/doc/HACKING index 5c71b74bd1..a144c4b96a 100644 --- a/doc/HACKING +++ b/doc/HACKING @@ -61,9 +61,10 @@ it's a bugfix, mention what bug it fixes and when the bug was introduced. To find out which Git tag the change was introduced in, you can use "git describe --contains <sha1 of commit>". -If at all possible, try to create this file in the same commit where -you are making the change. Please give it a distinctive name that no -other branch will use for the lifetime of your change. +If at all possible, try to create this file in the same commit where you are +making the change. Please give it a distinctive name that no other branch will +use for the lifetime of your change. To verify the format of the changes file, +you can use "make check-changes". When we go to make a release, we will concatenate all the entries in changes to make a draft changelog, and clear the directory. We'll @@ -373,7 +374,7 @@ do your own profiling to determine otherwise. Log conventions ~~~~~~~~~~~~~~~ -https://trac.torproject.org/projects/tor/wiki/doc/TorFAQ#loglevel +https://www.torproject.org/docs/faq#LogLevel No error or warning messages should be expected during normal OR or OP operation. @@ -563,6 +564,12 @@ on dist-master. 8b) Edit "include/versions.wmi" and "Makefile" to note the new version. 9) Email the packagers (cc'ing tor-assistants) that a new tarball is up. + The current list of packagers is: + {weasel,gk,mikeperry} at torproject dot org + {blueness} at gentoo dot org + {paul} at invizbox dot io + {ondrej.mikle} at gmail dot com + {lfleischer} at archlinux dot org 10) Add the version number to Trac. To do this, go to Trac, log in, select "Admin" near the top of the screen, then select "Versions" from diff --git a/doc/TUNING b/doc/TUNING index a4bf386dd6..24552a38cb 100644 --- a/doc/TUNING +++ b/doc/TUNING @@ -35,6 +35,45 @@ when it launches tor service (see launchd.plist(5) manpage). Also, kern.ipc.maxsockets is determined dynamically by the system and thus is read-only on OS X. +OpenBSD +------- + +Because OpenBSD is primarily focused on security and stability, it uses default +resource limits stricter than those of more popular Unix-like operating systems. + +OpenBSD stores a kernel-level file descriptor limit in the sysctl variable +kern.maxfiles. It defaults to 7,030. To change it to, for example, 16,000 while +the system is running, use the command 'sudo sysctl kern.maxfiles=16000'. +kern.maxfiles will reset to the default value upon system reboot unless you also +add 'kern.maxfiles=16000' to the file /etc/sysctl.conf. + +There are stricter resource limits set on user classes, which are stored in +/etc/login.conf. This config file also allows limit sets for daemons started +with scripts in the /etc/rc.d directory, which presumably includes Tor. + +To increase the file descriptor limit from its default of 1,024, add the +following to /etc/login.conf: + +tor:\ + :openfiles-max=13500:\ + :tc=daemon: + +Upon restarting Tor, it will be able to open up to 13,500 file descriptors. + +This will work *only* if you are starting Tor with the script /etc/rc.d/tor. If +you're using a custom build instead of the package, you can easily copy the rc.d +script from the Tor port directory. Alternatively, you can ensure that the Tor's +daemon user has its own user class and make a /etc/login.conf entry for it. + +High-bandwidth relays sometimes give the syslog warning: + +/bsd: WARNING: mclpools limit reached; increase kern.maxclusters + +In this case, increase kern.maxclusters with the sysctl command and in the file +/etc/sysctl.conf, as described with kern.maxfiles above. Use 'sysctl +kern.maxclusters' to query the current value. Increasing by about 15% per day +until the error no longer appears is a good guideline. + Disclaimer ---------- diff --git a/doc/include.am b/doc/include.am index 30d3e20d83..783aa95c4e 100644 --- a/doc/include.am +++ b/doc/include.am @@ -64,14 +64,14 @@ doc/tor-gencert.html.in: doc/tor-gencert.1.txt doc/tor-resolve.html.in: doc/tor-resolve.1.txt doc/tor-fw-helper.html.in: doc/tor-fw-helper.1.txt -# use ../config.status to swap all machine-specific magic strings +# use config.status to swap all machine-specific magic strings # in the asciidoc with their replacements. $(asciidoc_product) : $(AM_V_GEN)$(MKDIR_P) $(@D) $(AM_V_at)if test -e $(top_srcdir)/$@.in && ! test -e $@.in ; then \ cp $(top_srcdir)/$@.in $@; \ fi - $(AM_V_at)./config.status -q --file=$@; + $(AM_V_at)$(top_builddir)/config.status -q --file=$@; doc/tor.html: doc/tor.html.in doc/tor-gencert.html: doc/tor-gencert.html.in diff --git a/doc/tor-resolve.1.txt b/doc/tor-resolve.1.txt index 341d302244..30e16d5daa 100644 --- a/doc/tor-resolve.1.txt +++ b/doc/tor-resolve.1.txt @@ -14,7 +14,7 @@ tor-resolve - resolve a hostname to an IP address via tor SYNOPSIS -------- -**tor-resolve** [-4|-5] [-v] [-x] __hostname__ [__sockshost__[:__socksport__]] +**tor-resolve** [-4|-5] [-v] [-x] [-p __socksport__] __hostname__ [__sockshost__[:__socksport__]] DESCRIPTION ----------- @@ -40,6 +40,9 @@ OPTIONS Use the SOCKS4a protocol rather than the default SOCKS5 protocol. Doesn't support reverse DNS. +**-p** __socksport__:: + Override the default SOCKS port without setting the hostname. + SEE ALSO -------- **tor**(1), **torify**(1). + diff --git a/doc/tor.1.txt b/doc/tor.1.txt index a6f3b6dad4..2bb5f947ef 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -42,7 +42,8 @@ COMMAND-LINE OPTIONS [[opt-f]] **-f** __FILE__:: Specify a new configuration file to contain further Tor configuration - options. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not + 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**:: @@ -273,7 +274,7 @@ GENERAL OPTIONS all sockets will be set to this limit. Must be a value between 2048 and 262144, in 1024 byte increments. Default of 8192 is recommended. -[[ControlPort]] **ControlPort** __PORT__|**auto**:: +[[ControlPort]] **ControlPort** __PORT__|**unix:**__path__|**auto**:: If set, Tor will accept connections on this port and allow those connections to control the Tor process using the Tor Control Protocol (described in control-spec.txt). Note: unless you also specify one or @@ -370,12 +371,6 @@ GENERAL OPTIONS chosen with their regular weights, multiplied by this number, which should be 1.0 or less. (Default: 1.0) -[[DynamicDHGroups]] **DynamicDHGroups** **0**|**1**:: - If this option is set to 1, when running as a server, generate our - own Diffie-Hellman group instead of using the one from Apache's mod_ssl. - This option may help circumvent censorship based on static - Diffie-Hellman parameters. (Default: 0) - [[AlternateDirAuthority]] **AlternateDirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ + [[AlternateBridgeAuthority]] **AlternateBridgeAuthority** [__nickname__] [**flags**] __address__:__port__ __ fingerprint__:: @@ -483,10 +478,6 @@ GENERAL OPTIONS in accordance to RFC 1929. Both username and password must be between 1 and 255 characters. -[[SocksSocket]] **SocksSocket** __Path__:: - Like SocksPort, but listens on a Unix domain socket, rather than a TCP - socket. '0' disables SocksSocket (Unix and Unix-like systems only.) - [[SocksSocketsGroupWritable]] **SocksSocketsGroupWritable** **0**|**1**:: If this option is set to 0, don't allow the filesystem group to read and write unix sockets (e.g. SocksSocket). If the option is set to 1, make @@ -957,7 +948,7 @@ The following options are useful only for clients (that is, if the same circuit. Currently, two addresses are "too close" if they lie in the same /16 range. (Default: 1) -[[SOCKSPort]] **SOCKSPort** \['address':]__port__|**auto** [_flags_] [_isolation flags_]:: +[[SOCKSPort]] **SOCKSPort** \['address':]__port__|**unix:**__path__|**auto** [_flags_] [_isolation flags_]:: Open this port to listen for connections from SOCKS-speaking applications. Set this to 0 if you don't want to allow application connections via SOCKS. Set it to "auto" to have Tor pick a port for @@ -1117,6 +1108,17 @@ The following options are useful only for clients (that is, if download any non-default directory material. It doesn't currently do anything when we lack a live consensus. (Default: 1) +[[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: + V3 authoritative directories only. Configures the location of the + guardfraction file which contains information about how long relays + have been guards. (Default: unset) + +[[UseGuardFraction]] **UseGuardFraction** **0**|**1**|**auto**:: + This torrc option specifies whether clients should use the + guardfraction information found in the consensus during path + selection. If it's set to 'auto', clients will do what the + UseGuardFraction consensus parameter tells them to do. (Default: auto) + [[NumEntryGuards]] **NumEntryGuards** __NUM__:: If UseEntryGuards is set to 1, we will try to pick a total of NUM routers as long-term entries for our circuits. If NUM is 0, we try to learn @@ -1303,7 +1305,7 @@ The following options are useful only for clients (that is, if [[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**:: If true, Tor downloads and caches "extra-info" documents. These documents contain information about servers other than the information in their - regular router descriptors. Tor does not use this information for anything + regular server descriptors. Tor does not use this information for anything itself; to save bandwidth, leave this option turned off. (Default: 0) [[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__:: @@ -1338,6 +1340,22 @@ The following options are useful only for clients (that is, if To enable this option the compile time flag --enable-tor2webmode must be specified. (Default: 0) +[[Tor2webRendezvousPoints]] **Tor2webRendezvousPoints** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, country codes and + address patterns of nodes that are allowed to be used as RPs + in HS circuits; any other nodes will not be used as RPs. + (Example: + Tor2webRendezvousPoints Fastyfasty, ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + + + This feature can only be used if Tor2webMode is also enabled. + + + ExcludeNodes have higher priority than Tor2webRendezvousPoints, + which means that nodes specified in ExcludeNodes will not be + picked as RPs. + + + If no nodes in Tor2webRendezvousPoints are currently available for + use, Tor will choose a random node when building HS circuits. + [[UseMicrodescriptors]] **UseMicrodescriptors** **0**|**1**|**auto**:: Microdescriptors are a smaller version of the information that Tor needs in order to build its circuits. Using microdescriptors makes Tor clients @@ -1466,8 +1484,8 @@ is non-zero): [[BridgeRelay]] **BridgeRelay** **0**|**1**:: Sets the relay to act as a "bridge" with respect to relaying connections from bridge users to the Tor network. It mainly causes Tor to publish a - server descriptor to the bridge database, rather than publishing a relay - descriptor to the public directory authorities. + server descriptor to the bridge database, rather than + to the public directory authorities. [[ContactInfo]] **ContactInfo** __email_address__:: Administrative contact information for this relay or bridge. This line @@ -1766,27 +1784,53 @@ is non-zero): (Default: P256) [[CellStatistics]] **CellStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the mean time that - cells spend in circuit queues to disk every 24 hours. (Default: 0) + Relays only. + When this option is enabled, Tor collects statistics about cell + processing (i.e. mean time a cell is spending in a queue, mean + number of cells in a queue and mean number of processed cells per + circuit) and writes them into disk every 24 hours. Onion router + operators may use the statistics for performance monitoring. + If ExtraInfoStatistics is enabled, it will published as part of + extra-info document. (Default: 0) [[DirReqStatistics]] **DirReqStatistics** **0**|**1**:: + Relays and bridges only. When this option is enabled, a Tor directory writes statistics on the number and response time of network status requests to disk every 24 - hours. (Default: 1) + hours. Enables relay and bridge operators to monitor how much their + server is being used by clients to learn about Tor network. + If ExtraInfoStatistics is enabled, it will published as part of + extra-info document. (Default: 1) [[EntryStatistics]] **EntryStatistics** **0**|**1**:: + Relays only. When this option is enabled, Tor writes statistics on the number of - directly connecting clients to disk every 24 hours. (Default: 0) + directly connecting clients to disk every 24 hours. Enables relay + operators to monitor how much inbound traffic that originates from + Tor clients passes through their server to go further down the + Tor network. If ExtraInfoStatistics is enabled, it will be published + as part of extra-info document. (Default: 0) [[ExitPortStatistics]] **ExitPortStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the number of relayed - bytes and opened stream per exit port to disk every 24 hours. (Default: 0) + Exit relays only. + When this option is enabled, Tor writes statistics on the number of + relayed bytes and opened stream per exit port to disk every 24 hours. + Enables exit relay operators to measure and monitor amounts of traffic + that leaves Tor network through their exit node. If ExtraInfoStatistics + is enabled, it will be published as part of extra-info document. + (Default: 0) [[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the bidirectional use - of connections to disk every 24 hours. (Default: 0) + Relays only. + When this option is enabled, Tor writes statistics on the amounts of + traffic it passes between itself and other relays to disk every 24 + hours. Enables relay operators to monitor how much their relay is + being used as middle node in the circuit. If ExtraInfoStatistics is + enabled, it will be published as part of extra-info document. + (Default: 0) [[HiddenServiceStatistics]] **HiddenServiceStatistics** **0**|**1**:: + Relays only. When this option is enabled, a Tor relay writes obfuscated statistics on its role as hidden-service directory, introduction point, or rendezvous point to disk every 24 hours. If @@ -1890,6 +1934,12 @@ on the public Tor network. multiple times: the values from multiple lines are spliced together. When this is set then **VersioningAuthoritativeDirectory** should be set too. +[[RecommendedPackageVersions]] **RecommendedPackageVersions** __PACKAGENAME__ __VERSION__ __URL__ __DIGESTTYPE__**=**__DIGEST__ :: + Adds "package" line to the directory authority's vote. This information + is used to vote on the correct URL and digest for the released versions + of different Tor-related packages, so that the consensus can certify + them. This line may appear any number of times. + [[RecommendedClientVersions]] **RecommendedClientVersions** __STRING__:: STRING is a comma-separated list of Tor versions currently believed to be safe for clients to use. This information is included in version 2 @@ -1899,7 +1949,7 @@ on the public Tor network. [[BridgeAuthoritativeDir]] **BridgeAuthoritativeDir** **0**|**1**:: When this option is set in addition to **AuthoritativeDirectory**, Tor - accepts and serves router descriptors, but it caches and serves the main + accepts and serves server descriptors, but it caches and serves the main networkstatus documents rather than generating its own. (Default: 0) [[MinUptimeHidServDirectoryV2]] **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: @@ -1918,9 +1968,9 @@ on the public Tor network. in the "params" line of its networkstatus vote. [[DirAllowPrivateAddresses]] **DirAllowPrivateAddresses** **0**|**1**:: - If set to 1, Tor will accept router descriptors with arbitrary "Address" + If set to 1, Tor will accept server descriptors with arbitrary "Address" elements. Otherwise, if the address is not an IP address or is a private IP - address, it will reject the router descriptor. (Default: 0) + address, it will reject the server descriptor. (Default: 0) [[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that @@ -2093,6 +2143,12 @@ The following options are used to configure a hidden service. found in the hostname file. Clients need to put this authorization data in their configuration file using **HidServAuth**. +[[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**:: + If set to 1, then connections to unrecognized ports do not cause the + current hidden service to close rendezvous circuits. (Setting this to 0 is + not an authorization mechanism; it is instead meant to be a mild + inconvenience to port-scanners.) (Default: 0) + [[RendPostPeriod]] **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: Every time the specified period elapses, Tor uploads any rendezvous service descriptors to the directory servers. This information is also @@ -2176,7 +2232,7 @@ The following options are used for running a testing Tor network. that **TestingTorNetwork** is set. (Default: 30 minutes) [[TestingEstimatedDescriptorPropagationTime]] **TestingEstimatedDescriptorPropagationTime** __N__ **minutes**|**hours**:: - Clients try downloading router descriptors from directory caches after this + Clients try downloading server descriptors from directory caches after this time. Changing this requires that **TestingTorNetwork** is set. (Default: 10 minutes) @@ -2224,7 +2280,7 @@ The following options are used for running a testing Tor network. this requires that **TestingTorNetwork** is set. (Default: 8) [[TestingDescriptorMaxDownloadTries]] **TestingDescriptorMaxDownloadTries** __NUM__:: - Try this often to download a router descriptor before giving up. + Try this often to download a server descriptor before giving up. Changing this requires that **TestingTorNetwork** is set. (Default: 8) [[TestingMicrodescMaxDownloadTries]] **TestingMicrodescMaxDownloadTries** __NUM__:: @@ -2366,7 +2422,7 @@ __DataDirectory__**/state**:: below). - When the file was last written - What version of Tor generated the state file - - A short history of bandwidth usage, as produced in the router + - A short history of bandwidth usage, as produced in the server descriptors. __DataDirectory__**/bw_accounting**:: @@ -2411,7 +2467,7 @@ __DataDirectory__**/unverified-microdesc-consensus**:: to check yet. __DataDirectory__**/unparseable-desc**:: - Onion router descriptors that Tor was unable to parse are dumped to this + Onion server descriptors that Tor was unable to parse are dumped to this file. Only used for debugging. __DataDirectory__**/router-stability**:: |