From 725b0528e3c0d65c5b76dcf7ade7162d666290f8 Mon Sep 17 00:00:00 2001 From: swati Date: Tue, 11 Feb 2020 01:41:43 +0530 Subject: [PATCH 1/8] Alphabetized Server Options and Directory Server Options --- doc/tor.1.txt | 634 +++++++++++++++++++++++++------------------------- 1 file changed, 323 insertions(+), 311 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index a9b9852b7d..84ff5841ff 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -2060,9 +2060,58 @@ different from other Tor clients: == SERVER OPTIONS +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + The following options are useful only for servers (that is, if ORPort is non-zero): +[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: + Limits the max number of bytes sent and received within a set time period + using a given calculation rule (see: AccountingStart, AccountingRule). + Useful if you need to stay under a specific bandwidth. By default, the + number used for calculation is the max of either the bytes sent or + received. For example, with AccountingMax set to 1 TByte, a server + could send 900 GBytes and receive 800 GBytes and continue running. + It will only hibernate once one of the two reaches 1 TByte. This can + be changed to use the sum of the both bytes received and sent by setting + the AccountingRule option to "sum" (total bandwidth in/out). When the + number of bytes remaining gets low, Tor will stop accepting new connections + and circuits. When the number of bytes is exhausted, Tor will hibernate + until some time in the next accounting period. To prevent all servers + from waking at the same time, Tor will also wait until a random point + in each period before waking up. If you have bandwidth cost issues, + enabling hibernation is preferable to setting a low bandwidth, since + it provides users with a collection of fast servers that are up some + of the time, which is more useful than a set of slow servers that are + always "available". + + + + Note that (as also described in the Bandwidth section) Tor uses + powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not + one billion. Be careful: some internet service providers might count + GBytes differently. + +[[AccountingRule]] **AccountingRule** **sum**|**max**|**in**|**out**:: + How we determine when our AccountingMax has been reached (when we + should hibernate) during a time interval. Set to "max" to calculate + using the higher of either the sent or received bytes (this is the + default functionality). Set to "sum" to calculate using the sent + plus received bytes. Set to "in" to calculate using only the + received bytes. Set to "out" to calculate using only the sent bytes. + (Default: max) + +[[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__:: + Specify how long accounting periods last. If **month** is given, + each accounting period runs from the time __HH:MM__ on the __dayth__ day of one + month to the same day and time of the next. The relay will go at full speed, + use all the quota you specify, then hibernate for the rest of the period. (The + day must be between 1 and 28.) If **week** is given, each accounting period + runs from the time __HH:MM__ of the __dayth__ day of one week to the same day + and time of the next week, with Monday as day 1 and Sunday as day 7. If **day** + is given, each accounting period runs from the time __HH:MM__ each day to the + same time on the next day. All times are local, and given in 24-hour time. + (Default: "month 1 0:00") + [[Address]] **Address** __address__:: The IPv4 address of this server, or a fully qualified domain name of this server that resolves to an IPv4 address. You can leave this @@ -2088,6 +2137,15 @@ is non-zero): Note: make sure that no MyFamily lines are present in your torrc when relay is configured in bridge mode. +//Out of order because it logically belongs after BridgeRelay. +[[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**:: + When this option is enabled and BridgeRelay is also enabled, and we have + GeoIP data, Tor keeps a per-country count of how many client + addresses have contacted it so that it can help the bridge authority guess + which countries have blocked access to it. If ExtraInfoStatistics is + enabled, it will be published as part of extra-info document. (Default: 1) + +//Out of order because it logically belongs after BridgeRelay. [[BridgeDistribution]] **BridgeDistribution** __string__:: If set along with BridgeRelay, Tor will include a new line in its bridge descriptor which indicates to the BridgeDB service how it @@ -2108,21 +2166,11 @@ is non-zero): relay or bridge. (Really, everybody running a relay or bridge should set it.) - -[[ExitRelay]] **ExitRelay** **0**|**1**|**auto**:: - Tells Tor whether to run as an exit relay. If Tor is running as a - non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to - exit according to the ExitPolicy option, the ReducedExitPolicy option, - or the default ExitPolicy (if no other exit policy option is specified). + - + - If ExitRelay is set to 0, no traffic is allowed to exit, and the - ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored. + - + - If ExitRelay is set to "auto", then Tor checks the ExitPolicy, - ReducedExitPolicy, and IPv6Exit options. If at least one of these options - is set, Tor behaves as if ExitRelay were set to 1. If none of these exit - policy options are set, Tor behaves as if ExitRelay were set to 0. - (Default: auto) +[[DisableOOSCheck]] **DisableOOSCheck** **0**|**1**:: + This option disables the code that closes connections when Tor notices + that it is running low on sockets. Right now, it is on by default, + since the existing out-of-sockets mechanism tends to kill OR connections + more than it should. (Default: 1) [[ExitPolicy]] **ExitPolicy** __policy__,__policy__,__...__:: Set an exit policy for this server. Each policy is of the form @@ -2205,12 +2253,6 @@ is non-zero): Since the default exit policy uses accept/reject *, it applies to both IPv4 and IPv6 addresses. -[[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**:: - Reject all private (local) networks, along with the relay's advertised - public IPv4 and IPv6 addresses, at the beginning of your exit policy. - See above entry on ExitPolicy. - (Default: 1) - [[ExitPolicyRejectLocalInterfaces]] **ExitPolicyRejectLocalInterfaces** **0**|**1**:: Reject all IPv4 and IPv6 addresses that the relay knows about, at the beginning of your exit policy. This includes any OutboundBindAddress, the @@ -2223,6 +2265,168 @@ is non-zero): to disclose. (Default: 0) +[[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**:: + Reject all private (local) networks, along with the relay's advertised + public IPv4 and IPv6 addresses, at the beginning of your exit policy. + See above entry on ExitPolicy. + (Default: 1) + +[[ExitRelay]] **ExitRelay** **0**|**1**|**auto**:: + Tells Tor whether to run as an exit relay. If Tor is running as a + non-bridge server, and ExitRelay is set to 1, then Tor allows traffic to + exit according to the ExitPolicy option, the ReducedExitPolicy option, + or the default ExitPolicy (if no other exit policy option is specified). + + + + If ExitRelay is set to 0, no traffic is allowed to exit, and the + ExitPolicy, ReducedExitPolicy, and IPv6Exit options are ignored. + + + + If ExitRelay is set to "auto", then Tor checks the ExitPolicy, + ReducedExitPolicy, and IPv6Exit options. If at least one of these options + is set, Tor behaves as if ExitRelay were set to 1. If none of these exit + policy options are set, Tor behaves as if ExitRelay were set to 0. + (Default: auto) + +[[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**:: + When this option is enabled, Tor will connect to relays on localhost, + RFC1918 addresses, and so on. In particular, Tor will make direct OR + connections, and Tor routers allow EXTEND requests, to these private + addresses. (Tor will always allow connections to bridges, proxies, and + pluggable transports configured on private addresses.) Enabling this + option can create security issues; you should probably leave it off. + (Default: 0) + +[[GeoIPFile]] **GeoIPFile** __filename__:: + A filename containing IPv4 GeoIP data, for use with by-country statistics. + +[[GeoIPv6File]] **GeoIPv6File** __filename__:: + A filename containing IPv6 GeoIP data, for use with by-country statistics. + +[[HeartbeatPeriod]] **HeartbeatPeriod** __N__ **minutes**|**hours**|**days**|**weeks**:: + Log a heartbeat message every **HeartbeatPeriod** seconds. This is + a log level __notice__ message, designed to let you know your Tor + server is still alive and doing useful things. Settings this + to 0 will disable the heartbeat. Otherwise, it must be at least 30 + minutes. (Default: 6 hours) + +[[IPv6Exit]] **IPv6Exit** **0**|**1**:: + If set, and we are an exit node, allow clients to use us for IPv6 traffic. + When this option is set and ExitRelay is auto, we act as if ExitRelay + is 1. (Default: 0) + +[[KeyDirectory]] **KeyDirectory** __DIR__:: + Store secret keys in DIR. Can not be changed while tor is + running. + (Default: the "keys" subdirectory of DataDirectory.) + +[[KeyDirectoryGroupReadable]] **KeyDirectoryGroupReadable** **0**|**1**|**auto**:: + If this option is set to 0, don't allow the filesystem group to read the + KeyDirectory. If the option is set to 1, make the KeyDirectory readable + by the default GID. If the option is "auto", then we use the + setting for DataDirectoryGroupReadable when the KeyDirectory is the + same as the DataDirectory, and 0 otherwise. (Default: auto) + +[[MainloopStats]] **MainloopStats** **0**|**1**:: + Log main loop statistics every **HeartbeatPeriod** seconds. This is a log + level __notice__ message designed to help developers instrumenting Tor's + main event loop. (Default: 0) + +[[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]:: + If we have more onionskins queued for processing than we can process in + this amount of time, reject new ones. (Default: 1750 msec) + +[[MaxMemInQueues]] **MaxMemInQueues** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: + This option configures a threshold above which Tor will assume that it + needs to stop queueing or buffering data because it's about to run out of + memory. If it hits this threshold, it will begin killing circuits until + it has recovered at least 10% of this memory. Do not set this option too + low, or your relay may be unreliable under load. This option only + affects some queues, so the actual process size will be larger than + this. If this option is set to 0, Tor will try to pick a reasonable + default based on your system's physical memory. (Default: 0) + +[[MyFamily]] **MyFamily** __fingerprint__,__fingerprint__,...:: + Declare that this Tor relay is controlled or administered by a group or + organization identical or similar to that of the other relays, defined by + their (possibly $-prefixed) identity fingerprints. + This option can be repeated many times, for + convenience in defining large families: all fingerprints in all MyFamily + lines are merged into one list. + When two relays both declare that they are in the + same \'family', Tor clients will not use them in the same circuit. (Each + relay only needs to list the other servers in its family; it doesn't need to + list itself, but it won't hurt if it does.) Do not list any bridge relay as it would + compromise its concealment. + + + + When listing a node, it's better to list it by fingerprint than by + nickname: fingerprints are more reliable. + + + + If you run more than one relay, the MyFamily option on each relay + **must** list all other relays, as described above. + + + + Note: do not use MyFamily when configuring your Tor instance as a + brigde. + +[[Nickname]] **Nickname** __name__:: + Set the server's nickname to \'name'. Nicknames must be between 1 and 19 + characters inclusive, and must contain only the characters [a-zA-Z0-9]. + If not set, **Unnamed** will be used. Relays can always be uniquely identified + by their identity fingerprints. + +[[NumCPUs]] **NumCPUs** __num__:: + How many processes to use at once for decrypting onionskins and other + parallelizable operations. If this is set to 0, Tor will try to detect + how many CPUs you have, defaulting to 1 if it can't tell. (Default: 0) + +[[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 permanent + ed25519 master identity key, as well as the corresponding temporary + signing keys and certificates. (Default: 0) + +[[ORPort]] **ORPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]:: + Advertise this port to listen for connections from Tor clients and + servers. This option is required to be a Tor server. + Set it to "auto" to have Tor pick a port for you. Set it to 0 to not + run an ORPort at all. This option can occur more than once. (Default: 0) + + + + Tor recognizes these flags on each ORPort: + **NoAdvertise**;; + By default, we bind to a port and tell our users about it. If + NoAdvertise is specified, we don't advertise, but listen anyway. This + can be useful if the port everybody will be connecting to (for + example, one that's opened on our firewall) is somewhere else. + **NoListen**;; + By default, we bind to a port and tell our users about it. If + NoListen is specified, we don't bind, but advertise anyway. This + can be useful if something else (for example, a firewall's port + forwarding configuration) is causing connections to reach us. + **IPv4Only**;; + If the address is absent, or resolves to both an IPv4 and an IPv6 + address, only listen to the IPv4 address. + **IPv6Only**;; + If the address is absent, or resolves to both an IPv4 and an IPv6 + address, only listen to the IPv6 address. + +// Anchor only for formatting, not visible in the man page. +[[ORPortFlagsExclusive]]:: + For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and + IPv4Only and IPv6Only are mutually exclusive. + +[[PublishServerDescriptor]] **PublishServerDescriptor** **0**|**1**|**v3**|**bridge**,**...**:: + This option specifies which descriptors Tor will publish when acting as + a relay. You can + choose multiple arguments, separated by commas. + + + + If this option is set to 0, Tor will not publish its + descriptors to any directories. (This is useful if you're testing + out your server, or if you're using a Tor controller that handles + directory publishing for you.) Otherwise, Tor will publish its + descriptors of all type(s) specified. The default is "1", which + means "if running as a relay or bridge, publish descriptors to the + appropriate authorities". Other possibilities are "v3", meaning + "publish as if you're a relay", and "bridge", meaning "publish as + if you're a bridge". + [[ReducedExitPolicy]] **ReducedExitPolicy** **0**|**1**:: If set, use a reduced exit policy rather than the default one. + + @@ -2316,161 +2520,6 @@ is non-zero): (Default: 0) -[[IPv6Exit]] **IPv6Exit** **0**|**1**:: - If set, and we are an exit node, allow clients to use us for IPv6 traffic. - When this option is set and ExitRelay is auto, we act as if ExitRelay - is 1. (Default: 0) - -[[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]:: - If we have more onionskins queued for processing than we can process in - this amount of time, reject new ones. (Default: 1750 msec) - -[[MyFamily]] **MyFamily** __fingerprint__,__fingerprint__,...:: - Declare that this Tor relay is controlled or administered by a group or - organization identical or similar to that of the other relays, defined by - their (possibly $-prefixed) identity fingerprints. - This option can be repeated many times, for - convenience in defining large families: all fingerprints in all MyFamily - lines are merged into one list. - When two relays both declare that they are in the - same \'family', Tor clients will not use them in the same circuit. (Each - relay only needs to list the other servers in its family; it doesn't need to - list itself, but it won't hurt if it does.) Do not list any bridge relay as it would - compromise its concealment. + - + - When listing a node, it's better to list it by fingerprint than by - nickname: fingerprints are more reliable. + - + - If you run more than one relay, the MyFamily option on each relay - **must** list all other relays, as described above. + - + - Note: do not use MyFamily when configuring your Tor instance as a - brigde. - -[[Nickname]] **Nickname** __name__:: - Set the server's nickname to \'name'. Nicknames must be between 1 and 19 - characters inclusive, and must contain only the characters [a-zA-Z0-9]. - If not set, **Unnamed** will be used. Relays can always be uniquely identified - by their identity fingerprints. - -[[NumCPUs]] **NumCPUs** __num__:: - How many processes to use at once for decrypting onionskins and other - parallelizable operations. If this is set to 0, Tor will try to detect - how many CPUs you have, defaulting to 1 if it can't tell. (Default: 0) - -[[ORPort]] **ORPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]:: - Advertise this port to listen for connections from Tor clients and - servers. This option is required to be a Tor server. - Set it to "auto" to have Tor pick a port for you. Set it to 0 to not - run an ORPort at all. This option can occur more than once. (Default: 0) + - + - Tor recognizes these flags on each ORPort: - **NoAdvertise**;; - By default, we bind to a port and tell our users about it. If - NoAdvertise is specified, we don't advertise, but listen anyway. This - can be useful if the port everybody will be connecting to (for - example, one that's opened on our firewall) is somewhere else. - **NoListen**;; - By default, we bind to a port and tell our users about it. If - NoListen is specified, we don't bind, but advertise anyway. This - can be useful if something else (for example, a firewall's port - forwarding configuration) is causing connections to reach us. - **IPv4Only**;; - If the address is absent, or resolves to both an IPv4 and an IPv6 - address, only listen to the IPv4 address. - **IPv6Only**;; - If the address is absent, or resolves to both an IPv4 and an IPv6 - address, only listen to the IPv6 address. - -// Anchor only for formatting, not visible in the man page. -[[ORPortFlagsExclusive]]:: - For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and - IPv4Only and IPv6Only are mutually exclusive. - -[[PublishServerDescriptor]] **PublishServerDescriptor** **0**|**1**|**v3**|**bridge**,**...**:: - This option specifies which descriptors Tor will publish when acting as - a relay. You can - choose multiple arguments, separated by commas. + - + - If this option is set to 0, Tor will not publish its - descriptors to any directories. (This is useful if you're testing - out your server, or if you're using a Tor controller that handles - directory publishing for you.) Otherwise, Tor will publish its - descriptors of all type(s) specified. The default is "1", which - means "if running as a relay or bridge, publish descriptors to the - appropriate authorities". Other possibilities are "v3", meaning - "publish as if you're a relay", and "bridge", meaning "publish as - if you're a bridge". - -[[ShutdownWaitLength]] **ShutdownWaitLength** __NUM__:: - When we get a SIGINT and we're a server, we begin shutting down: - we close listeners and start refusing new circuits. After **NUM** - seconds, we exit. If we get a second SIGINT, we exit immediately. - (Default: 30 seconds) - -[[SSLKeyLifetime]] **SSLKeyLifetime** __N__ **minutes**|**hours**|**days**|**weeks**:: - When creating a link certificate for our outermost SSL handshake, - set its lifetime to this amount of time. If set to 0, Tor will choose - some reasonable random defaults. (Default: 0) - -[[HeartbeatPeriod]] **HeartbeatPeriod** __N__ **minutes**|**hours**|**days**|**weeks**:: - Log a heartbeat message every **HeartbeatPeriod** seconds. This is - a log level __notice__ message, designed to let you know your Tor - server is still alive and doing useful things. Settings this - to 0 will disable the heartbeat. Otherwise, it must be at least 30 - minutes. (Default: 6 hours) - -[[MainloopStats]] **MainloopStats** **0**|**1**:: - Log main loop statistics every **HeartbeatPeriod** seconds. This is a log - level __notice__ message designed to help developers instrumenting Tor's - main event loop. (Default: 0) - -[[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: - Limits the max number of bytes sent and received within a set time period - using a given calculation rule (see: AccountingStart, AccountingRule). - Useful if you need to stay under a specific bandwidth. By default, the - number used for calculation is the max of either the bytes sent or - received. For example, with AccountingMax set to 1 TByte, a server - could send 900 GBytes and receive 800 GBytes and continue running. - It will only hibernate once one of the two reaches 1 TByte. This can - be changed to use the sum of the both bytes received and sent by setting - the AccountingRule option to "sum" (total bandwidth in/out). When the - number of bytes remaining gets low, Tor will stop accepting new connections - and circuits. When the number of bytes is exhausted, Tor will hibernate - until some time in the next accounting period. To prevent all servers - from waking at the same time, Tor will also wait until a random point - in each period before waking up. If you have bandwidth cost issues, - enabling hibernation is preferable to setting a low bandwidth, since - it provides users with a collection of fast servers that are up some - of the time, which is more useful than a set of slow servers that are - always "available". + - + - Note that (as also described in the Bandwidth section) Tor uses - powers of two, not powers of ten: 1 GByte is 1024*1024*1024, not - one billion. Be careful: some internet service providers might count - GBytes differently. - -[[AccountingRule]] **AccountingRule** **sum**|**max**|**in**|**out**:: - How we determine when our AccountingMax has been reached (when we - should hibernate) during a time interval. Set to "max" to calculate - using the higher of either the sent or received bytes (this is the - default functionality). Set to "sum" to calculate using the sent - plus received bytes. Set to "in" to calculate using only the - received bytes. Set to "out" to calculate using only the sent bytes. - (Default: max) - -[[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__:: - Specify how long accounting periods last. If **month** is given, - each accounting period runs from the time __HH:MM__ on the __dayth__ day of one - month to the same day and time of the next. The relay will go at full speed, - use all the quota you specify, then hibernate for the rest of the period. (The - day must be between 1 and 28.) If **week** is given, each accounting period - runs from the time __HH:MM__ of the __dayth__ day of one week to the same day - and time of the next week, with Monday as day 1 and Sunday as day 7. If **day** - is given, each accounting period runs from the time __HH:MM__ each day to the - same time on the next day. All times are local, and given in 24-hour time. - (Default: "month 1 0:00") - [[RefuseUnknownExits]] **RefuseUnknownExits** **0**|**1**|**auto**:: Prevent nodes that don't appear in the consensus from exiting using this relay. If the option is 1, we always block exit attempts from such @@ -2478,13 +2527,10 @@ is non-zero): whatever the authorities suggest in the consensus (and block if the consensus is quiet on the issue). (Default: auto) -[[ServerDNSResolvConfFile]] **ServerDNSResolvConfFile** __filename__:: - Overrides the default DNS configuration with the configuration in - __filename__. The file format is the same as the standard Unix - "**resolv.conf**" file (7). This option, like all other ServerDNS options, - only affects name lookups that your server does on behalf of clients. - (Defaults to use the system DNS configuration or a localhost DNS service - in case no nameservers are found in a given configuration.) +[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: + Tells an authority, or other node tracking node reliability and history, + that fine-grained information about nodes can be discarded when it hasn't + changed for a given amount of time. (Default: 24 hours) [[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**:: If this option is false, Tor exits immediately if there are problems @@ -2492,27 +2538,6 @@ is non-zero): Otherwise, Tor continues to periodically retry the system nameservers until it eventually succeeds. (Default: 1) -[[ServerDNSSearchDomains]] **ServerDNSSearchDomains** **0**|**1**:: - If set to 1, then we will search for addresses in the local search domain. - For example, if this system is configured to believe it is in - "example.com", and a client tries to connect to "www", the client will be - connected to "www.example.com". This option only affects name lookups that - your server does on behalf of clients. (Default: 0) - -[[ServerDNSDetectHijacking]] **ServerDNSDetectHijacking** **0**|**1**:: - When this option is set to 1, we will test periodically to determine - whether our local nameservers have been configured to hijack failing DNS - requests (usually to an advertising site). If they are, we will attempt to - correct this. This option only affects name lookups that your server does - on behalf of clients. (Default: 1) - -[[ServerDNSTestAddresses]] **ServerDNSTestAddresses** __hostname__,__hostname__,__...__:: - When we're detecting DNS hijacking, make sure that these __valid__ addresses - aren't getting redirected. If they are, then our DNS is completely useless, - and we'll reset our exit policy to "reject \*:*". This option only affects - name lookups that your server does on behalf of clients. (Default: - "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org") - [[ServerDNSAllowNonRFC953Hostnames]] **ServerDNSAllowNonRFC953Hostnames** **0**|**1**:: When this option is disabled, Tor does not try to resolve hostnames containing illegal characters (like @ and :) rather than sending them to an @@ -2520,12 +2545,12 @@ is non-zero): URLs and so on. This option only affects name lookups that your server does on behalf of clients. (Default: 0) -[[BridgeRecordUsageByCountry]] **BridgeRecordUsageByCountry** **0**|**1**:: - When this option is enabled and BridgeRelay is also enabled, and we have - GeoIP data, Tor keeps a per-country count of how many client - addresses have contacted it so that it can help the bridge authority guess - which countries have blocked access to it. If ExtraInfoStatistics is - enabled, it will be published as part of extra-info document. (Default: 1) +[[ServerDNSDetectHijacking]] **ServerDNSDetectHijacking** **0**|**1**:: + When this option is set to 1, we will test periodically to determine + whether our local nameservers have been configured to hijack failing DNS + requests (usually to an advertising site). If they are, we will attempt to + correct this. This option only affects name lookups that your server does + on behalf of clients. (Default: 1) [[ServerDNSRandomizeCase]] **ServerDNSRandomizeCase** **0**|**1**:: When this option is set, Tor sets the case of each character randomly in @@ -2535,11 +2560,54 @@ is non-zero): 0x20-Bit Encoding". This option only affects name lookups that your server does on behalf of clients. (Default: 1) -[[GeoIPFile]] **GeoIPFile** __filename__:: - A filename containing IPv4 GeoIP data, for use with by-country statistics. +[[ServerDNSResolvConfFile]] **ServerDNSResolvConfFile** __filename__:: + Overrides the default DNS configuration with the configuration in + __filename__. The file format is the same as the standard Unix + "**resolv.conf**" file (7). This option, like all other ServerDNS options, + only affects name lookups that your server does on behalf of clients. + (Defaults to use the system DNS configuration or a localhost DNS service + in case no nameservers are found in a given configuration.) -[[GeoIPv6File]] **GeoIPv6File** __filename__:: - A filename containing IPv6 GeoIP data, for use with by-country statistics. +[[ServerDNSSearchDomains]] **ServerDNSSearchDomains** **0**|**1**:: + If set to 1, then we will search for addresses in the local search domain. + For example, if this system is configured to believe it is in + "example.com", and a client tries to connect to "www", the client will be + connected to "www.example.com". This option only affects name lookups that + your server does on behalf of clients. (Default: 0) + +[[ServerDNSTestAddresses]] **ServerDNSTestAddresses** __hostname__,__hostname__,__...__:: + When we're detecting DNS hijacking, make sure that these __valid__ addresses + aren't getting redirected. If they are, then our DNS is completely useless, + and we'll reset our exit policy to "reject \*:*". This option only affects + name lookups that your server does on behalf of clients. (Default: + "www.google.com, www.mit.edu, www.yahoo.com, www.slashdot.org") + +[[ShutdownWaitLength]] **ShutdownWaitLength** __NUM__:: + When we get a SIGINT and we're a server, we begin shutting down: + we close listeners and start refusing new circuits. After **NUM** + seconds, we exit. If we get a second SIGINT, we exit immediately. + (Default: 30 seconds) + +[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**:: + For how long should each Ed25519 signing key be valid? Tor uses a + permanent master identity key that can be kept offline, and periodically + generates new "signing" keys that it uses online. This option + configures their lifetime. + (Default: 30 days) + +[[SSLKeyLifetime]] **SSLKeyLifetime** __N__ **minutes**|**hours**|**days**|**weeks**:: + When creating a link certificate for our outermost SSL handshake, + set its lifetime to this amount of time. If set to 0, Tor will choose + some reasonable random defaults. (Default: 0) + +== STATISTICS OPTIONS + +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + +Relays publish most statistics in a document called the +extra-info document. The following options describe the different +types of statistics that Tor collects and writes: [[CellStatistics]] **CellStatistics** **0**|**1**:: Relays only. @@ -2551,14 +2619,14 @@ is non-zero): If ExtraInfoStatistics is enabled, it will published as part of extra-info document. (Default: 0) -[[PaddingStatistics]] **PaddingStatistics** **0**|**1**:: - Relays and bridges only. - When this option is enabled, Tor collects statistics for padding cells - sent and received by this relay, in addition to total cell counts. - These statistics are rounded, and omitted if traffic is low. This - information is important for load balancing decisions related to padding. - If ExtraInfoStatistics is enabled, it will be published - as a part of extra-info document. (Default: 1) +[[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**:: + 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) [[DirReqStatistics]] **DirReqStatistics** **0**|**1**:: Relays and bridges only. @@ -2587,23 +2655,6 @@ is non-zero): is enabled, it will be published as part of extra-info document. (Default: 0) -[[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**:: - 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 - ExtraInfoStatistics is also enabled, these statistics are further - published to the directory authorities. (Default: 1) - [[ExtraInfoStatistics]] **ExtraInfoStatistics** **0**|**1**:: When this option is enabled, Tor includes previously gathered statistics in its extra-info documents that it uploads to the directory authorities. @@ -2613,61 +2664,22 @@ is non-zero): because they are required by BridgeDB. (Default: 1) -[[ExtendAllowPrivateAddresses]] **ExtendAllowPrivateAddresses** **0**|**1**:: - When this option is enabled, Tor will connect to relays on localhost, - RFC1918 addresses, and so on. In particular, Tor will make direct OR - connections, and Tor routers allow EXTEND requests, to these private - addresses. (Tor will always allow connections to bridges, proxies, and - pluggable transports configured on private addresses.) Enabling this - option can create security issues; you should probably leave it off. - (Default: 0) - -[[MaxMemInQueues]] **MaxMemInQueues** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: - This option configures a threshold above which Tor will assume that it - needs to stop queueing or buffering data because it's about to run out of - memory. If it hits this threshold, it will begin killing circuits until - it has recovered at least 10% of this memory. Do not set this option too - low, or your relay may be unreliable under load. This option only - affects some queues, so the actual process size will be larger than - this. If this option is set to 0, Tor will try to pick a reasonable - default based on your system's physical memory. (Default: 0) - -[[DisableOOSCheck]] **DisableOOSCheck** **0**|**1**:: - This option disables the code that closes connections when Tor notices - that it is running low on sockets. Right now, it is on by default, - since the existing out-of-sockets mechanism tends to kill OR connections - more than it should. (Default: 1) - -[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**:: - For how long should each Ed25519 signing key be valid? Tor uses a - permanent master identity key that can be kept offline, and periodically - generates new "signing" keys that it uses online. This option - configures their lifetime. - (Default: 30 days) - -[[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 permanent - ed25519 master identity key, as well as the corresponding temporary - signing keys and certificates. (Default: 0) - -[[KeyDirectory]] **KeyDirectory** __DIR__:: - Store secret keys in DIR. Can not be changed while tor is - running. - (Default: the "keys" subdirectory of DataDirectory.) - -[[KeyDirectoryGroupReadable]] **KeyDirectoryGroupReadable** **0**|**1**|**auto**:: - If this option is set to 0, don't allow the filesystem group to read the - KeyDirectory. If the option is set to 1, make the KeyDirectory readable - by the default GID. If the option is "auto", then we use the - setting for DataDirectoryGroupReadable when the KeyDirectory is the - same as the DataDirectory, and 0 otherwise. (Default: auto) - -[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: - Tells an authority, or other node tracking node reliability and history, - that fine-grained information about nodes can be discarded when it hasn't - changed for a given amount of time. (Default: 24 hours) +[[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 + ExtraInfoStatistics is also enabled, these statistics are further + published to the directory authorities. (Default: 1) +[[PaddingStatistics]] **PaddingStatistics** **0**|**1**:: + Relays and bridges only. + When this option is enabled, Tor collects statistics for padding cells + sent and received by this relay, in addition to total cell counts. + These statistics are rounded, and omitted if traffic is low. This + information is important for load balancing decisions related to padding. + If ExtraInfoStatistics is enabled, it will be published + as a part of extra-info document. (Default: 1) == DIRECTORY SERVER OPTIONS @@ -2675,11 +2687,19 @@ The following options are useful only for directory servers. (Relays with enough bandwidth automatically become directory servers; see DirCache for details.) -[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__:: - When this option is set, it takes an HTML file and publishes it as "/" on - the DirPort. Now relay operators can provide a disclaimer without needing - to set up a separate webserver. There's a sample disclaimer in - contrib/operator-tools/tor-exit-notice.html. +[[DirCache]] **DirCache** **0**|**1**:: + When this option is set, Tor caches all current directory documents except + extra info documents, and accepts client requests for them. If + **DownloadExtraInfo** is set, cached extra info documents are also cached. + Setting **DirPort** is not required for **DirCache**, because clients + connect via the ORPort by default. Setting either DirPort or BridgeRelay + and setting DirCache to 0 is not supported. (Default: 1) + +[[DirPolicy]] **DirPolicy** __policy__,__policy__,__...__:: + Set an entrance policy for this server, to limit who can connect to the + directory ports. The policies have the same form as exit policies above, + except that port specifiers are ignored. Any address not matched by + some entry in the policy is accepted. [[DirPort]] **DirPort** ['address'**:**]{empty}__PORT__|**auto** [_flags_]:: If this option is nonzero, advertise the directory service on this port. @@ -2689,19 +2709,11 @@ details.) + The same flags are supported here as are supported by ORPort. -[[DirPolicy]] **DirPolicy** __policy__,__policy__,__...__:: - Set an entrance policy for this server, to limit who can connect to the - directory ports. The policies have the same form as exit policies above, - except that port specifiers are ignored. Any address not matched by - some entry in the policy is accepted. - -[[DirCache]] **DirCache** **0**|**1**:: - When this option is set, Tor caches all current directory documents except - extra info documents, and accepts client requests for them. If - **DownloadExtraInfo** is set, cached extra info documents are also cached. - Setting **DirPort** is not required for **DirCache**, because clients - connect via the ORPort by default. Setting either DirPort or BridgeRelay - and setting DirCache to 0 is not supported. (Default: 1) +[[DirPortFrontPage]] **DirPortFrontPage** __FILENAME__:: + When this option is set, it takes an HTML file and publishes it as "/" on + the DirPort. Now relay operators can provide a disclaimer without needing + to set up a separate webserver. There's a sample disclaimer in + contrib/operator-tools/tor-exit-notice.html. [[MaxConsensusAgeForDiffs]] **MaxConsensusAgeForDiffs** __N__ **minutes**|**hours**|**days**|**weeks**:: When this option is nonzero, Tor caches will not try to generate From 809090d24d8576258fab6077e5e54e33e5c78bbe Mon Sep 17 00:00:00 2001 From: swati Date: Wed, 12 Feb 2020 23:07:00 +0530 Subject: [PATCH 2/8] Addressed minor changes suggested in the ticket --- doc/tor.1.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 84ff5841ff..87b327b9cb 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -2330,10 +2330,6 @@ is non-zero): level __notice__ message designed to help developers instrumenting Tor's main event loop. (Default: 0) -[[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]:: - If we have more onionskins queued for processing than we can process in - this amount of time, reject new ones. (Default: 1750 msec) - [[MaxMemInQueues]] **MaxMemInQueues** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**:: This option configures a threshold above which Tor will assume that it needs to stop queueing or buffering data because it's about to run out of @@ -2344,6 +2340,10 @@ is non-zero): this. If this option is set to 0, Tor will try to pick a reasonable default based on your system's physical memory. (Default: 0) +[[MaxOnionQueueDelay]] **MaxOnionQueueDelay** __NUM__ [**msec**|**second**]:: + If we have more onionskins queued for processing than we can process in + this amount of time, reject new ones. (Default: 1750 msec) + [[MyFamily]] **MyFamily** __fingerprint__,__fingerprint__,...:: Declare that this Tor relay is controlled or administered by a group or organization identical or similar to that of the other relays, defined by @@ -2527,11 +2527,6 @@ is non-zero): whatever the authorities suggest in the consensus (and block if the consensus is quiet on the issue). (Default: auto) -[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: - Tells an authority, or other node tracking node reliability and history, - that fine-grained information about nodes can be discarded when it hasn't - changed for a given amount of time. (Default: 24 hours) - [[ServerDNSAllowBrokenConfig]] **ServerDNSAllowBrokenConfig** **0**|**1**:: If this option is false, Tor exits immediately if there are problems parsing the system DNS configuration or connecting to nameservers. @@ -2606,8 +2601,8 @@ is non-zero): // Please keep them that way! Relays publish most statistics in a document called the -extra-info document. The following options describe the different -types of statistics that Tor collects and writes: +extra-info document. The following options affect the different +types of statistics that Tor relays collect and publish: [[CellStatistics]] **CellStatistics** **0**|**1**:: Relays only. @@ -2681,6 +2676,11 @@ types of statistics that Tor collects and writes: If ExtraInfoStatistics is enabled, it will be published as a part of extra-info document. (Default: 1) +[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: + Tells an authority, or other node tracking node reliability and history, + that fine-grained information about nodes can be discarded when it hasn't + changed for a given amount of time. (Default: 24 hours) + == DIRECTORY SERVER OPTIONS The following options are useful only for directory servers. (Relays with From d33c80f0ee3a6c88c911441673c39c1f266e2209 Mon Sep 17 00:00:00 2001 From: swati Date: Wed, 12 Feb 2020 23:17:31 +0530 Subject: [PATCH 3/8] Moved [[RephistTrackTime]] to General Options. --- doc/tor.1.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 87b327b9cb..db4dd2755a 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -794,6 +794,11 @@ forward slash (/) in the configuration file and on the command line. fetches by the relay (from authority or other relays), because that is considered "client" activity. (Default: 0) +[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: + Tells an authority, or other node tracking node reliability and history, + that fine-grained information about nodes can be discarded when it hasn't + changed for a given amount of time. (Default: 24 hours) + [[RunAsDaemon]] **RunAsDaemon** **0**|**1**:: If 1, Tor forks and daemonizes to the background. This option has no effect on Windows; instead you should use the --service command-line option. @@ -2676,11 +2681,6 @@ types of statistics that Tor relays collect and publish: If ExtraInfoStatistics is enabled, it will be published as a part of extra-info document. (Default: 1) -[[RephistTrackTime]] **RephistTrackTime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: - Tells an authority, or other node tracking node reliability and history, - that fine-grained information about nodes can be discarded when it hasn't - changed for a given amount of time. (Default: 24 hours) - == DIRECTORY SERVER OPTIONS The following options are useful only for directory servers. (Relays with From 0ab859aabecf025dc9adb14d440605a477ce251f Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Wed, 12 Feb 2020 12:28:35 -0600 Subject: [PATCH 4/8] changes file for ticket 33188 --- changes/ticket33188 | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changes/ticket33188 diff --git a/changes/ticket33188 b/changes/ticket33188 new file mode 100644 index 0000000000..7bec15b99b --- /dev/null +++ b/changes/ticket33188 @@ -0,0 +1,5 @@ + o Documentation (manpage): + - Alphabetize the Server and Directory server sections of the tor + manpage. Also split Statistics options into their own section + of the manpage. Closes ticket 33188. Work by Swati Thacker as + part of Google Season of Docs. From d0c3350218765d43c538df4dd1d548fa9a7c430a Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 12 Feb 2020 18:25:51 -0500 Subject: [PATCH 5/8] Run "make autostyle". --- src/feature/dirauth/process_descs.h | 6 +++--- src/feature/dircache/dirserv.h | 4 ++-- src/feature/nodelist/networkstatus.c | 2 +- src/lib/cc/compat_compiler.h | 2 +- src/test/test_util.c | 4 ++-- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/feature/dirauth/process_descs.h b/src/feature/dirauth/process_descs.h index 55b828ba64..9c13692778 100644 --- a/src/feature/dirauth/process_descs.h +++ b/src/feature/dirauth/process_descs.h @@ -15,7 +15,7 @@ // for was_router_added_t. #include "feature/nodelist/routerlist.h" -#include "src/lib/crypt_ops/crypto_ed25519.h" +#include "lib/crypt_ops/crypto_ed25519.h" struct authdir_config_t; @@ -47,7 +47,7 @@ typedef struct authdir_config_t { #define RTR_BADEXIT 16 /**< We'll tell clients not to use this as an exit. */ /* 32 Historically used to indicade Unnamed */ -#endif /* defined(TOR_UNIT_TESTS) */ +#endif /* defined(PROCESS_DESCS_PRIVATE) || defined(TOR_UNIT_TESTS) */ #ifdef TOR_UNIT_TESTS @@ -55,7 +55,7 @@ void authdir_init_fingerprint_list(void); authdir_config_t *authdir_return_fingerprint_list(void); -#endif /* defined(PROCESS_DESCS_PRIVATE) || defined(TOR_UNIT_TESTS) */ +#endif /* defined(TOR_UNIT_TESTS) */ void dirserv_free_fingerprint_list(void); diff --git a/src/feature/dircache/dirserv.h b/src/feature/dircache/dirserv.h index 3a168c2035..73a64b1b7e 100644 --- a/src/feature/dircache/dirserv.h +++ b/src/feature/dircache/dirserv.h @@ -93,7 +93,7 @@ void dirserv_set_cached_consensus_networkstatus(const char *consensus, const common_digests_t *digests, const uint8_t *sha3_as_signed, time_t published); -#else +#else /* !defined(HAVE_MODULE_DIRCACHE) */ #define have_module_dircache() (0) #define directory_caches_unknown_auth_certs(opt) \ ((void)(opt), 0) @@ -112,7 +112,7 @@ void dirserv_set_cached_consensus_networkstatus(const char *consensus, (void)(e); \ (void)(f); \ } STMT_END -#endif +#endif /* defined(HAVE_MODULE_DIRCACHE) */ void dirserv_clear_old_networkstatuses(time_t cutoff); int dirserv_get_routerdesc_spool(smartlist_t *spools_out, const char *key, diff --git a/src/feature/nodelist/networkstatus.c b/src/feature/nodelist/networkstatus.c index 0d2ff96a6e..cc4b8e1c34 100644 --- a/src/feature/nodelist/networkstatus.c +++ b/src/feature/nodelist/networkstatus.c @@ -102,7 +102,7 @@ #include "feature/nodelist/routerlist_st.h" #include "feature/dirauth/vote_microdesc_hash_st.h" #include "feature/nodelist/vote_routerstatus_st.h" -#include "routerstatus_st.h" +#include "feature/nodelist/routerstatus_st.h" #ifdef HAVE_UNISTD_H #include diff --git a/src/lib/cc/compat_compiler.h b/src/lib/cc/compat_compiler.h index 907622f942..1bb8c54a0c 100644 --- a/src/lib/cc/compat_compiler.h +++ b/src/lib/cc/compat_compiler.h @@ -238,6 +238,6 @@ #define POSSIBLE(expr) ((expr) || getenv("STATIC_ANALYZER_DEADCODE_DUMMY_")) #else #define POSSIBLE(expr) (expr) -#endif +#endif /* defined(__COVERITY__) || defined(__clang_analyzer__) */ #endif /* !defined(TOR_COMPAT_COMPILER_H) */ diff --git a/src/test/test_util.c b/src/test/test_util.c index 07c31f02d6..0d86a5ab5d 100644 --- a/src/test/test_util.c +++ b/src/test/test_util.c @@ -1947,7 +1947,7 @@ test_util_expand_filename(void *arg) done: tor_free(str); } -#endif /* !defined(_WIN32) */ +#endif /* !defined(DISABLE_PWDB_TESTS) */ /** Test tor_escape_str_for_pt_args(). */ static void @@ -5763,7 +5763,7 @@ test_util_pwdb(void *arg) tor_free(dir); teardown_capture_of_logs(); } -#endif /* !(defined(_WIN32) || defined (__ANDROID__)) */ +#endif /* !defined(DISABLE_PWDB_TESTS) */ static void test_util_calloc_check(void *arg) From 03650e0f60ec37c758f90f3e02bf2ace05959a7e Mon Sep 17 00:00:00 2001 From: teor Date: Thu, 13 Feb 2020 13:13:40 +1000 Subject: [PATCH 6/8] Travis: Require the macOS IPv6 chutney job The job was previously set to fast_finish / allow_failure, to speed up the build. Closes ticket 33195. --- .travis.yml | 6 ++++-- changes/ticket33195 | 4 ++++ 2 files changed, 8 insertions(+), 2 deletions(-) create mode 100644 changes/ticket33195 diff --git a/.travis.yml b/.travis.yml index 28a45788b4..323ebf5b35 100644 --- a/.travis.yml +++ b/.travis.yml @@ -91,8 +91,10 @@ matrix: - env: RUST_OPTIONS="--enable-rust --enable-cargo-online-mode" compiler: clang os: osx - - env: CHUTNEY="yes" CHUTNEY_ALLOW_FAILURES="2" SKIP_MAKE_CHECK="yes" - os: osx + ## Since we're actively developing IPv6, we want to require the IPv6 + ## chutney tests + #- env: CHUTNEY="yes" CHUTNEY_ALLOW_FAILURES="2" SKIP_MAKE_CHECK="yes" + # os: osx ## (Linux only) Use a recent Linux image (Ubuntu Bionic) dist: bionic diff --git a/changes/ticket33195 b/changes/ticket33195 new file mode 100644 index 0000000000..11abd4816e --- /dev/null +++ b/changes/ticket33195 @@ -0,0 +1,4 @@ + o Testing: + - Stop allowing the Chutney IPv6 Travis job to fail. This job was + previously configured to fast_finish (which requires allow_failure), to + speed up the build. Closes ticket 33195. From fc3555100f26201213f4da19d2d2904edc76a229 Mon Sep 17 00:00:00 2001 From: teor Date: Thu, 13 Feb 2020 13:22:19 +1000 Subject: [PATCH 7/8] Travis: Remove a redundant distcheck job Part of 33194. --- .travis.yml | 4 ---- changes/ticket33194 | 2 ++ 2 files changed, 2 insertions(+), 4 deletions(-) create mode 100644 changes/ticket33194 diff --git a/.travis.yml b/.travis.yml index 323ebf5b35..38519db627 100644 --- a/.travis.yml +++ b/.travis.yml @@ -53,16 +53,12 @@ matrix: - env: CHUTNEY="yes" CHUTNEY_ALLOW_FAILURES="2" SKIP_MAKE_CHECK="yes" compiler: clang ## We check asciidoc with distcheck, to make sure we remove doc products - ## We use Linux clang, because there are no other Linux clang jobs - env: DISTCHECK="yes" ASCIIDOC_OPTIONS="" SKIP_MAKE_CHECK="yes" - compiler: clang ## We include a single coverage build with the best options for coverage - env: COVERAGE_OPTIONS="--enable-coverage" HARDENING_OPTIONS="" ## We run rust on Linux, because it's faster than rust on macOS ## We check rust offline - env: RUST_OPTIONS="--enable-rust" TOR_RUST_DEPENDENCIES=true - ## We check asciidoc with distcheck, to make sure we remove doc products - - env: DISTCHECK="yes" ASCIIDOC_OPTIONS="" SKIP_MAKE_CHECK="yes" ## We check disable module dirauth - env: MODULES_OPTIONS="--disable-module-dirauth" ## macOS builds are very slow, and we have a limited number of diff --git a/changes/ticket33194 b/changes/ticket33194 new file mode 100644 index 0000000000..fd9efda516 --- /dev/null +++ b/changes/ticket33194 @@ -0,0 +1,2 @@ + o Testing: + - Remove a redundant distcheck job. Closes ticket 33194. From add387c5071a1ee7889e3789e7b4143bb8856d0a Mon Sep 17 00:00:00 2001 From: teor Date: Thu, 13 Feb 2020 13:37:02 +1000 Subject: [PATCH 8/8] Travis: Sort jobs in order of speed Putting the slowest jobs first takes full advantage of Travis concurrency. Closes 33194. --- .travis.yml | 47 +++++++++++++++++++++++++++++---------------- changes/ticket33194 | 2 ++ 2 files changed, 32 insertions(+), 17 deletions(-) diff --git a/.travis.yml b/.travis.yml index 38519db627..6047c4470e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -39,28 +39,42 @@ env: matrix: ## include creates builds with gcc, linux, unless we override those defaults include: - ## We run basic tests on macOS + ## We run chutney on macOS, because macOS Travis has IPv6 + - env: CHUTNEY="yes" CHUTNEY_ALLOW_FAILURES="2" SKIP_MAKE_CHECK="yes" + os: osx + + ## We also run basic tests on macOS - compiler: clang os: osx ## Turn off some newer features, turn on clang's -Wtypedef-redefinition env: C_DIALECT_OPTIONS="-std=gnu99" - ## We check NSS - ## Use -std=gnu99 to turn off some newer features, and maybe turn on some - ## extra gcc warnings? - - env: NSS_OPTIONS="--enable-nss" C_DIALECT_OPTIONS="-std=gnu99" + ## We run chutney on Linux, because it's faster than chutney on macOS ## Chutney is a fast job, clang is slower on Linux, so we do Chutney clang - env: CHUTNEY="yes" CHUTNEY_ALLOW_FAILURES="2" SKIP_MAKE_CHECK="yes" compiler: clang + ## We check asciidoc with distcheck, to make sure we remove doc products - env: DISTCHECK="yes" ASCIIDOC_OPTIONS="" SKIP_MAKE_CHECK="yes" - ## We include a single coverage build with the best options for coverage - - env: COVERAGE_OPTIONS="--enable-coverage" HARDENING_OPTIONS="" + + ## We check disable module dirauth + - env: MODULES_OPTIONS="--disable-module-dirauth" + ## We run rust on Linux, because it's faster than rust on macOS ## We check rust offline - env: RUST_OPTIONS="--enable-rust" TOR_RUST_DEPENDENCIES=true - ## We check disable module dirauth - - env: MODULES_OPTIONS="--disable-module-dirauth" + + ## We check NSS + ## Use -std=gnu99 to turn off some newer features, and maybe turn on some + ## extra gcc warnings? + - env: NSS_OPTIONS="--enable-nss" C_DIALECT_OPTIONS="-std=gnu99" + + ## We include a single coverage build with the best options for coverage + - env: COVERAGE_OPTIONS="--enable-coverage" HARDENING_OPTIONS="" + + ## We clone our stem repo and run `make test-stem` + - env: TEST_STEM="yes" SKIP_MAKE_CHECK="yes" + ## macOS builds are very slow, and we have a limited number of ## concurrent macOS jobs. We're not actively developing Rust, so it is ## the lowest priority. @@ -68,11 +82,6 @@ matrix: #- env: RUST_OPTIONS="--enable-rust --enable-cargo-online-mode" # compiler: clang # os: osx - ## We run chutney on macOS, because macOS Travis has IPv6 - - env: CHUTNEY="yes" CHUTNEY_ALLOW_FAILURES="2" SKIP_MAKE_CHECK="yes" - os: osx - ## We clone our stem repo and run `make test-stem` - - env: TEST_STEM="yes" SKIP_MAKE_CHECK="yes" ## Allow the build to report success (with non-required sub-builds ## continuing to run) if all required sub-builds have succeeded. @@ -84,9 +93,13 @@ matrix: ## macOS rust and chutney are very slow, so we let the build finish before ## they are done. We'd like to fast finish, but still eventually show ## any failures in the build status. But Travis doesn't have that ability. - - env: RUST_OPTIONS="--enable-rust --enable-cargo-online-mode" - compiler: clang - os: osx + + ## Since this job is disabled, there's not much point having an exception + ## for it + #- env: RUST_OPTIONS="--enable-rust --enable-cargo-online-mode" + # compiler: clang + # os: osx + ## Since we're actively developing IPv6, we want to require the IPv6 ## chutney tests #- env: CHUTNEY="yes" CHUTNEY_ALLOW_FAILURES="2" SKIP_MAKE_CHECK="yes" diff --git a/changes/ticket33194 b/changes/ticket33194 index fd9efda516..b87e55348e 100644 --- a/changes/ticket33194 +++ b/changes/ticket33194 @@ -1,2 +1,4 @@ o Testing: - Remove a redundant distcheck job. Closes ticket 33194. + - Sort the Travis jobs in order of speed. Putting the slowest jobs first + takes full advantage of Travis job concurrency. Closes ticket 33194.