GitLab is used only for code review, issue tracking and project management. Canonical locations for source code are still https://gitweb.torproject.org/ https://git.torproject.org/ and git-rw.torproject.org.

README.md 2.26 KB
Newer Older
1 2 3
Bridgestrap
===========

4 5 6
Bridgestrap implements a API (for machines) and a Web interface (for people) to
test a given bridge line by spawning a tor instance and having it bootstrap
over the bridge line.
7 8 9 10 11 12 13 14 15 16 17 18

Installation
------------

First, install the Golang binary:

      go install

Then, run the binary:

      bridgestrap

19
By default, bridgestrap will listen on port 5000.  To use its Web interface
Philipp Winter's avatar
Philipp Winter committed
20
(don't forget to turn it on by using the `-web` switch), point your browser to
21 22
the address and port that bridgestrap is listening on.  Use the argument
`-addr` to listen to a custom address and port.
23 24 25 26

Input
-----

27 28
Clients send bridge lines to the following API, using an HTTP GET request, and
place the bridge line in the request body:
29

30
      https://HOST/bridge-state
31

32
The request body must look as follows:
33

34
      {"bridge_line": "BRIDGE_LINE"}
35

36 37
The value of "bridge_line" can be any bridge line (excluding the "Bridge"
prefix) that tor accepts.  Here are a few examples:
38

39 40 41 42 43 44 45
* `1.2.3.4:1234`
* `1.2.3.4:1234 1234567890ABCDEF1234567890ABCDEF12345678`
* `obfs4 1.2.3.4:1234 cert=fJRlJc0T7i2Qkw3SyLQq+M6iTGs9ghLHK65LBy/MQewXJpNOKFq63Om1JHVkLlrmEBbX1w iat-mode=0`

You can test bridgestrap's API over the command line as follows:

      curl -X GET localhost:5000/bridge-state -d '{"bridge_line": "BRIDGE_LINE"}'
46 47 48 49 50 51 52

Output
------

The service responds with the following JSON:

      {
53 54
        "functional": BOOL,
        "error": "STRING", (only present if "functional" is false.)
55 56 57
        "time": FLOAT
      }

58 59 60
If tor could bootstrap over the given bridge line, "functional" is "true" and
"false" otherwise.  If "functional" is "false", "error" will contain an error
string.  "time" is a float that represents the number of seconds that
61 62 63 64
bridgestrap's test took.

Here are a few examples:

65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
    {
      "functional":false,
      "error":"Invalid JSON request.",
      "time":0
    }

    {
      "functional":false,
      "error":"Oct 23 17:36:57.000 [warn] Problem bootstrapping. Stuck at 10%: Finishing handshake with directory server. (DONE; DONE; count 1; recommendation warn; host [REDACTED])",
      "time":32.31
    }

    {
      "functional":false,
      "error":"Oct 23 17:34:57.680 [warn] Too few items to Bridge line.",
      "time":0.013
    }

    {
      "functional":true,
      "time":13.161
    }