aboutsummaryrefslogtreecommitdiff
path: root/spec/pt-spec
diff options
context:
space:
mode:
authorNick Mathewson <nickm@torproject.org>2023-10-12 21:46:51 -0400
committerNick Mathewson <nickm@torproject.org>2023-10-12 21:46:51 -0400
commit3cd7716900e9e0712fb0ee4313979b37b172c4aa (patch)
tree30ed9b03475f7b3f93801a982c4f45afc72c7f57 /spec/pt-spec
parentc7b1172618fbeadd0d6236a406697e2a99e58af9 (diff)
downloadtorspec-3cd7716900e9e0712fb0ee4313979b37b172c4aa.tar.gz
torspec-3cd7716900e9e0712fb0ee4313979b37b172c4aa.zip
Update more things that looked like html tags in the markdown
Diffstat (limited to 'spec/pt-spec')
-rw-r--r--spec/pt-spec/pluggable-transport-configuration-environment.md20
-rw-r--r--spec/pt-spec/pluggable-transport-to-parent-process-communication.md27
2 files changed, 25 insertions, 22 deletions
diff --git a/spec/pt-spec/pluggable-transport-configuration-environment.md b/spec/pt-spec/pluggable-transport-configuration-environment.md
index 61b6b01..3a201f8 100644
--- a/spec/pt-spec/pluggable-transport-configuration-environment.md
+++ b/spec/pt-spec/pluggable-transport-configuration-environment.md
@@ -124,7 +124,7 @@ Specifies an upstream proxy that the PT MUST use when making
outgoing network connections. It is a URI [RFC3986] of the
format:
-<proxy_type>://[<user_name>[:<password>][@]<ip>:<port>.
+`<proxy_type>://[<user_name>[:<password>][@]<ip>:<port>`.
The "TOR_PT_PROXY" environment variable is OPTIONAL and
MUST be omitted if there is no need to connect via an
@@ -161,8 +161,8 @@ TOR_PT_SERVER_TRANSPORTS=obfs3,scramblesuit
"TOR_PT_SERVER_TRANSPORT_OPTIONS"
Specifies per-PT protocol configuration directives, as a
-semicolon-separated list of <key>:<value> pairs, where <key>
-is a PT name and <value> is a k=v string value with options
+semicolon-separated list of `<key>:<value>` pairs, where `<key>`
+is a PT name and `<value>` is a k=v string value with options
that are to be passed to the transport.
Colons, semicolons, and backslashes MUST be
@@ -183,23 +183,23 @@ TOR_PT_SERVER_TRANSPORT_OPTIONS=scramblesuit:key=banana;automata:rule=110;automa
"TOR_PT_SERVER_BINDADDR"
```
-A comma separated list of <key>-<value> pairs, where <key> is
-a PT name and <value> is the <address>:<port> on which it
+A comma separated list of `<key>-<value>` pairs, where `<key>` is
+a PT name and `<value>` is the `<address>:<port>` on which it
should listen for incoming client connections.
The keys holding transport names MUST be in the same order as
they appear in "TOR_PT_SERVER_TRANSPORTS".
-The <address> MAY be a locally scoped address as long as port
+The `<address>` MAY be a locally scoped address as long as port
forwarding is done externally.
-The <address>:<port> combination MUST be an IP address
+The `<address>:<port>` combination MUST be an IP address
supported by `bind()`, and MUST NOT be a host name.
Applications MUST NOT set more than one <address>:<port> pair
per PT name.
-If there is no specific <address>:<port> combination to be
+If there is no specific `<address>:<port>` combination to be
configured for any transports, "TOR_PT_SERVER_BINDADDR" MAY
be omitted.
@@ -211,7 +211,7 @@ TOR_PT_SERVER_BINDADDR=obfs3-198.51.100.1:1984,scramblesuit-127.0.0.1:4891
Specifies the destination that the PT reverse proxy should forward
traffic to after transforming it as appropriate, as an
-<address>:<port>.
+`<address>:<port>`.
Connections to the destination specified via "TOR_PT_ORPORT"
MUST only contain application payload. If the parent process
@@ -227,7 +227,7 @@ TOR_PT_ORPORT=127.0.0.1:9001
Specifies the destination that the PT reverse proxy should
forward traffic to, via the Extended ORPort protocol [EXTORPORT]
-as an <address>:<port>.
+as an `<address>:<port>`.
The Extended ORPort protocol allows the PT reverse proxy to
communicate per-connection metadata such as the PT name and
diff --git a/spec/pt-spec/pluggable-transport-to-parent-process-communication.md b/spec/pt-spec/pluggable-transport-to-parent-process-communication.md
index 7f7de76..b7f8175 100644
--- a/spec/pt-spec/pluggable-transport-to-parent-process-communication.md
+++ b/spec/pt-spec/pluggable-transport-to-parent-process-communication.md
@@ -4,6 +4,7 @@
All Pluggable Transport Proxies communicate to the parent process
via writing NL-terminated lines to stdout. The line metaformat is:
+```text
<Line> ::= <Keyword> <OptArgs> <NL>
<Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar>
<KeywordChar> ::= <any US-ASCII alphanumeric, dash, and underscore>
@@ -12,6 +13,7 @@ via writing NL-terminated lines to stdout. The line metaformat is:
<ArgChar> ::= <any US-ASCII character but NUL or NL>
<SP> ::= <US-ASCII whitespace symbol (32)>
<NL> ::= <US-ASCII newline (line feed) character (10)>
+```
The parent process MUST ignore lines received from PT proxies with
unknown keywords.
@@ -30,13 +32,13 @@ by the application.
Upon determining the version to use, or lack thereof, the PT
proxy responds with one of two messages.
-VERSION-ERROR <ErrorMessage>
+`VERSION-ERROR <ErrorMessage>`
The "VERSION-ERROR" message is used to signal that there was
no compatible Pluggable Transport Specification version
present in the "TOR_PT_MANAGED_TRANSPORT_VER" list.
-The <ErrorMessage> SHOULD be set to "no-version" for
+The `<ErrorMessage>` SHOULD be set to "no-version" for
historical reasons but MAY be set to a useful error message
instead.
@@ -45,9 +47,9 @@ message.
Example:
-VERSION-ERROR no-version
+`VERSION-ERROR no-version`
-VERSION <ProtocolVersion>
+`VERSION <ProtocolVersion>`
The "VERSION" message is used to signal the Pluggable Transport
Specification version (as in "TOR_PT_MANAGED_TRANSPORT_VER")
@@ -74,7 +76,7 @@ At any point, if there is an error encountered related to
configuration supplied via the environment variables, it MAY
respond with an error message and terminate.
-ENV-ERROR <ErrorMessage>
+`ENV-ERROR <ErrorMessage>`
The "ENV-ERROR" message is used to signal the PT proxy's
failure to parse the configuration environment variables (3.2).
@@ -254,18 +256,18 @@ event so any third party can pick them up for debugging.
The format of the message:
-LOG SEVERITY=Severity MESSAGE=Message
+`LOG SEVERITY=Severity MESSAGE=Message`
The SEVERITY value indicate at which logging level the message applies.
The accepted values for <Severity> are: error, warning, notice, info, debug
The MESSAGE value is a human readable string formatted by the PT. The
-<Message> contains the log message which can be a String or CString (see
+`<Message>` contains the log message which can be a String or CString (see
section 2 in control-spec.txt).
Example:
-LOG SEVERITY=debug MESSAGE="Connected to bridge A"
+`LOG SEVERITY=debug MESSAGE="Connected to bridge A"`
<a id="pt-spec.txt-3.3.5"></a>
### Pluggable Transport Status Message
@@ -275,20 +277,21 @@ parent process via stdout or stderr any status messages.
The format of the message:
-STATUS TRANSPORT=Transport <K_1>=<V_1> [<K_2>=<V_2> ...]
+`STATUS TRANSPORT=Transport <K_1>=<V_1> [<K_2>=<V_2> ...]`
The TRANSPORT value indicates a hint on what the PT is such has the name or
the protocol used for instance. As an example, obfs4proxy would use
"obfs4". Thus, the Transport value can be anything the PT itself defines
and it can be a String or CString (see section 2 in control-spec.txt).
-The <K_n>=<V_n> values are specific to the PT and there has to be at least
+The `<K_n>=<V_n>` values are specific to the PT and there has to be at least
one. They are messages that reflects the status that the PT wants to
-report. <V_n> can be a String or CString.
+report. `<V_n>` can be a String or CString.
Examples (fictional):
+```text
STATUS TRANSPORT=obfs4 ADDRESS=198.51.100.123:1234 CONNECT=Success
STATUS TRANSPORT=obfs4 ADDRESS=198.51.100.222:2222 CONNECT=Failed FINGERPRINT=<Fingerprint> ERRSTR="Connection refused"
STATUS TRANSPORT=trebuchet ADDRESS=198.51.100.15:443 PERCENT=42
-
+```