diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/HACKING/EndOfLifeTor.md | 48 | ||||
| -rw-r--r-- | doc/HACKING/ReleaseSeriesLifecycle.md | 113 | ||||
| -rw-r--r-- | doc/tor.1.txt | 49 |
3 files changed, 146 insertions, 64 deletions
diff --git a/doc/HACKING/EndOfLifeTor.md b/doc/HACKING/EndOfLifeTor.md deleted file mode 100644 index 0735dc311a..0000000000 --- a/doc/HACKING/EndOfLifeTor.md +++ /dev/null @@ -1,48 +0,0 @@ -# End of Life on an old release series - -Here are the steps that the maintainer should take when an old Tor release -series reaches End of Life. Note that they are _only_ for entire series that -have reached their planned EOL: they do not apply to security-related -deprecations of individual versions. - -## 0. Preliminaries - -0. A few months before End of Life: - Write a deprecation announcement. - Send the announcement out with every new release announcement. - -1. A month before End of Life: - Send the announcement to tor-announce, tor-talk, tor-relays, and the - packagers. - -## 1. On the day - -1. Open tickets to remove the release from: - - the jenkins builds - - tor's Travis CI cron jobs - - chutney's Travis CI tests (#) - - stem's Travis CI tests (#) - -2. Close the milestone in Trac. To do this, go to Trac, log in, - select "Admin" near the top of the screen, then select "Milestones" from - the menu on the left. Click on the milestone for this version, and - select the "Completed" checkbox. By convention, we select the date as - the End of Life date. - -3. Replace NNN-backport with NNN-unreached-backport in all open trac tickets. - -4. If there are any remaining tickets in the milestone: - - merge_ready tickets are for backports: - - if there are no supported releases for the backport, close the ticket - - if there is an earlier (LTS) release for the backport, move the ticket - to that release - - other tickets should be closed (if we won't fix them) or moved to a - supported release (if we will fix them) - -5. Mail the end of life announcement to tor-announce, the packagers list, - and tor-relays. The current list of packagers is in ReleasingTor.md. - -6. Ask at least two of weasel/arma/Sebastian to remove the old version - number from their approved versions list. - -7. Update the CoreTorReleases wiki page. diff --git a/doc/HACKING/ReleaseSeriesLifecycle.md b/doc/HACKING/ReleaseSeriesLifecycle.md new file mode 100644 index 0000000000..e4068ed806 --- /dev/null +++ b/doc/HACKING/ReleaseSeriesLifecycle.md @@ -0,0 +1,113 @@ +# Release Series Lifecycle + + +## End Of Life On An Old Release Series + +Here are the steps that the maintainer should take when an old Tor release +series reaches End of Life. + +Note that they are _only_ for an entire series that has reached its planned +EOL: they do not apply to security-related deprecations of individual +patch versions. + + +### 1. Preliminaries + +1. A few months before End of Life: + Write a deprecation announcement. + Send the announcement out with every new release announcement. + +2. A month before End of Life: + Send the announcement to tor-announce, tor-talk, tor-relays, and the + packagers. + + +### 2. On The Day + +1. Open tickets to remove the release from: + - the jenkins builds + - tor's Travis CI cron jobs + - chutney's Travis CI tests + - sbws' Travis CI tests + - stem's Travis CI tests (but see + https://github.com/torproject/stem/issues/51) + - tor's scripts/git/gist-list-tor-branches.sh script + +2. Close the milestone in Trac. To do this, go to Trac, log in, + select "Admin" near the top of the screen, then select "Milestones" from + the menu on the left. Click on the milestone for this version, and + select the "Completed" checkbox. By convention, we select the date as + the End of Life date. + +3. Replace NNN-backport with NNN-unreached-backport in all open trac tickets. + +4. If there are any remaining tickets in the milestone: + - merge_ready tickets are for backports: + - if there are no supported releases for the backport, close the ticket + - if there is an earlier (LTS) release for the backport, move the ticket + to that release + - other tickets should be closed (if we won't fix them) or moved to a + supported release (if we will fix them) + +5. Mail the end of life announcement to tor-announce, the packagers list, + and tor-relays. The current list of packagers is in ReleasingTor.md. + +6. Ask at least two of weasel/arma/Sebastian to remove the old version + number from their approved versions list. + +7. Update the CoreTorReleases wiki page. + +8. Open a ticket (if there is not one already) for authorities to + start rejecting relays that are running that release series. + This ticket should be targeted for at least a month or two + after the series is officially EOL, unless there is an important + reason to un-list relays early. + +9. (LTS end-of-life only) Open a ticket (if appropriate) for updates to the + set of required and recommended subprotocol versions. (For the process + here, see proposal 303.) + +10. (LTS end-of-life only) Open a ticket to remove no-longer-needed + consensus methods. (For the process here, see proposal 290.) + +11. (All EOL) Open a ticket to grep for obsolete series names (e.g., "0.2.9" + and "029") in tor, chutney, sbws, fallback-scripts, and so on. These + should be updated or removed. + +12. Finally, make sure this document is up to date with our latest + process. + +## Starting A New Release Series + +Here are the steps that the maintainer should take to start new maint and +release branches for a stable release. + +Note that they are _only_ for an entire series, when it first becomes stable: +they do not apply to security-related patch release versions. + +(Ideally, do this immediately after a release.) + +1. Start a new maint-x.y.z branch based on master, and a new + release-x.y.z branch based on master. They should have the same + starting point. + + Push both of these branches to the master git repository. + +2. In master, change the version to "0.x.y.0-alpha-dev". Run the + update_versions.py script, and commit this version bump. + +3. Tag the version bump with "tor-0.x.y.0-alpha-dev". Push the tag + and master. + +4. Open tickets for connecting the new branches to various other + places. See section 2 above for a list of affected locations. + +5. Stop running practracker on maintainence and release branches: + * Remove "check-best-practices" from the check-local Makefile + target in the maint-x.y.z branch only. + * Delete the file scripts/maint/practracker/.enable_practracker_in_hooks + in the maint-x.y.z branch only. + * Merge to release-x.y.z, but do not forward-port to master. + +6. Finally, make sure this document is up to date with our latest + process. diff --git a/doc/tor.1.txt b/doc/tor.1.txt index e87385f857..3dd7f5a64a 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -186,6 +186,13 @@ The following options in this section are only recognized on the 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" +[[opt-dbg]] **--dbg-**...:: + Tor may support other options beginning with the string "dbg". These + are intended for use by developers to debug and test Tor. They are + not supported or guaranteed to be stable, and you should probably + not use them. + + [[conf-format]] == THE CONFIGURATION FILE FORMAT @@ -204,6 +211,8 @@ file will be parsed as if they were written where the %include option is. If the path is a folder, all files on that folder will be parsed following lexical order. Files starting with a dot are ignored. Files on subfolders are ignored. The %include option can be used recursively. +New configuration files or directories cannot be added to already running Tor +instance if **Sandbox** is enabled. By default, an option on the command line overrides an option found in the configuration file, and an option in a configuration file overrides one in @@ -525,9 +534,9 @@ forward slash (/) in the configuration file and on the command line. [[ExtendByEd25519ID]] **ExtendByEd25519ID** **0**|**1**|**auto**:: If this option is set to 1, we always try to include a relay's Ed25519 ID - when telling the proceeding relay in a circuit to extend to it. + when telling the preceding relay in a circuit to extend to it. If this option is set to 0, we never include Ed25519 IDs when extending - circuits. If the option is set to "default", we obey a + circuits. If the option is set to "auto", we obey a parameter in the consensus document. (Default: auto) [[ExtORPort]] **ExtORPort** ['address'**:**]{empty}__port__|**auto**:: @@ -848,6 +857,10 @@ forward slash (/) in the configuration file and on the command line. and **ORPort** are not allowed). Currently, if **Sandbox** is 1, **ControlPort** command "GETINFO address" will not work. + + + When using %include in the tor configuration files, reloading the tor + configuration is not supported after adding new configuration files or + directories. + + + (Default: 0) [[Schedulers]] **Schedulers** **KIST**|**KISTLite**|**Vanilla**:: @@ -1556,15 +1569,13 @@ The following options are useful only for clients (that is, if X'F2' Onion Service Introduction Failed - Client failed to introduce to the service meaning the descriptor - was found but the service is not connected anymore to the - introduction point. The service has likely changed its descriptor - or is not running. (v3 only) + All introduction attempts failed either due to a combination of + NACK by the intro point or time out. (v3 only) X'F3' Onion Service Rendezvous Failed - Client failed to rendezvous with the service which means that the - client is unable to finalize the connection. (v3 only) + Every rendezvous circuit has timed out and thus the client is + unable to rendezvous with the service. (v3 only) X'F4' Onion Service Missing Client Authorization @@ -1585,6 +1596,11 @@ The following options are useful only for clients (that is, if error is returned: address checksum doesn't match, ed25519 public key is invalid or the encoding is invalid. (v3 only) + X'F7' Onion Service Introduction Timed Out + + Similar to X'F2' code but in this case, all introduction attempts + have failed due to a time out. (v3 only) + // Anchor only for formatting, not visible in the man page. [[SocksPortFlagsMisc]]:: Flags are processed left to right. If flags conflict, the last flag on the @@ -3714,14 +3730,15 @@ __DataDirectory__/**`hashed-fingerprint`**:: identity key. (That is, the hash of the hash of the identity key.) __DataDirectory__/**`approved-routers`**:: - Only used by authoritative directory servers. This file lists the status - and a fingerprint/pubkey. Each line lists a status and a fingerprint - separated by whitespace. See your **fingerprint** file in the - __DataDirectory__ for an example fingerprint line. If the status is - **!reject** then descriptors from the given identity (fingerprint/pubkey) - are rejected by this server. If it is **!invalid** then descriptors are - accepted but marked in the directory as not valid, that is, not - recommended. + Only used by authoritative directory servers. Each line lists a status and + an identity, separated by whitespace. Identities can be hex-encoded RSA + fingerprints, or base-64 encoded ed25519 public keys. See the + **fingerprint** file in a tor relay's __DataDirectory__ for an example + fingerprint line. If the status is **!reject**, then descriptors from the + given identity are rejected by this server. If it is **!invalid** then + descriptors are accepted, but marked in the directory as not valid, that + is, not recommended. In either case, the corresponding relays are not + included in the consensus. __DataDirectory__/**`v3-status-votes`**:: Only for v3 authoritative directory servers. This file contains status |