diff options
Diffstat (limited to 'spec/pt-spec/pluggable-transport-to-parent-process-communication.md')
| -rw-r--r-- | spec/pt-spec/pluggable-transport-to-parent-process-communication.md | 27 |
1 files changed, 15 insertions, 12 deletions
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 - +``` |