mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-11-13 06:33:44 +01:00
Clarify description of FEATURES in control-spec.
(1) On by default is a bad way to describe features. Rather, they are always on and should be viewed as a part of the control protocol. Updated the wording in USEFEATURE to reflect this. (2) Made descriptions of Tor versions consistant across all features. There is the version in which a feature was introduced and the version in which it became part of the protocol. (3) Reworded the description of the VERBOSE_NAMES feature. The previous wording describes the way things used to be first. Better to lead with the current state of things and then describe how it differs from old versions.
This commit is contained in:
parent
b259c08318
commit
cff180f8b0
@ -770,46 +770,47 @@
|
|||||||
|
|
||||||
3.19. USEFEATURE
|
3.19. USEFEATURE
|
||||||
|
|
||||||
|
Adding additional features to the control protocol sometimes will break
|
||||||
|
backwards compatibility. Initially such features are added into Tor and
|
||||||
|
disabled by default. USEFEATURE can enable these additional features.
|
||||||
|
|
||||||
The syntax is:
|
The syntax is:
|
||||||
|
|
||||||
"USEFEATURE" *(SP FeatureName) CRLF
|
"USEFEATURE" *(SP FeatureName) CRLF
|
||||||
FeatureName = 1*(ALPHA / DIGIT / "_" / "-")
|
FeatureName = 1*(ALPHA / DIGIT / "_" / "-")
|
||||||
|
|
||||||
Sometimes extensions to the controller protocol break compatibility with
|
|
||||||
older controllers. In this case, whenever possible, the extensions are
|
|
||||||
first included in Tor disabled by default, and only enabled on a given
|
|
||||||
controller connection when the "USEFEATURE" command is given. Once a
|
|
||||||
"USEFEATURE" command is given, it applies to all subsequent interactions on
|
|
||||||
the same connection; to disable an enabled feature, a new controller
|
|
||||||
connection must be opened.
|
|
||||||
|
|
||||||
This is a forward-compatibility mechanism; each feature will eventually
|
|
||||||
become a regular part of the control protocol in some future version of Tor.
|
|
||||||
Tor will ignore a request to use any feature that is already on by default.
|
|
||||||
Tor will give a "552" error if any requested feature is not recognized.
|
|
||||||
|
|
||||||
Feature names are case-insensitive.
|
Feature names are case-insensitive.
|
||||||
|
|
||||||
|
Once enabled, a feature stays enabled for the duration of the connection
|
||||||
|
to the controller. A new connection to the controller must be opened to
|
||||||
|
disable an enabled feature.
|
||||||
|
|
||||||
|
Features are a forward-compatibility mechanism; each feature will eventually
|
||||||
|
become a standard part of the control protocol. Once a feature becomes part
|
||||||
|
of the protocol, it is always-on. Each feature documents the version it was
|
||||||
|
introduced as a feature and the version in which it became part of the
|
||||||
|
protocol.
|
||||||
|
|
||||||
|
Tor will ignore a request to use any feature that is always-on. Tor will give
|
||||||
|
a 552 error in response to an unrecognized feature.
|
||||||
|
|
||||||
EXTENDED_EVENTS
|
EXTENDED_EVENTS
|
||||||
|
|
||||||
Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to
|
Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to
|
||||||
request the extended event syntax.
|
request the extended event syntax.
|
||||||
|
|
||||||
This feature was first used in 0.1.2.3-alpha. It is always-on in
|
This feature was first introduced in 0.1.2.3-alpha. It is always-on
|
||||||
Tor 0.2.2.1-alpha and later.
|
and part of the protocol in Tor 0.2.2.1-alpha and later.
|
||||||
|
|
||||||
VERBOSE_NAMES
|
VERBOSE_NAMES
|
||||||
|
|
||||||
Instead of ServerID as specified above, the controller should
|
Replaces ServerID with LongName in events and GETINFO results. LongName
|
||||||
identify ORs by LongName in events and GETINFO results. This format is
|
provides a Fingerprint for all routers, an indication of Named status,
|
||||||
strictly more informative: rather than including Nickname for
|
and a Nickname if one is known. LongName is strictly more informative
|
||||||
known Named routers and Fingerprint for unknown or unNamed routers, the
|
than ServerID, which only provides either a Fingerprint or a Nickname.
|
||||||
LongName format includes a Fingerprint, an indication of Named status,
|
|
||||||
and a Nickname (if one is known).
|
|
||||||
|
|
||||||
This will not be always-enabled until at least two stable
|
This feature was first introduced in 0.1.2.2-alpha. It is always-on and
|
||||||
releases after 0.1.2.2-alpha, the release where it was first
|
part of the protocol in Tor 0.2.2.1-alpha and later.
|
||||||
available. It is always-on in Tor 0.2.2.1-alpha and later.
|
|
||||||
|
|
||||||
3.20. RESOLVE
|
3.20. RESOLVE
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user