Changes between Version 65 and Version 66 of doc/PluggableTransports/obfs4proxy


Ignore:
Timestamp:
Aug 8, 2019, 12:31:04 AM (2 months ago)
Author:
phw
Comment:

Refer to our up-to-date setup guide.

Legend:

Unmodified
Added
Removed
Modified
  • doc/PluggableTransports/obfs4proxy

    v65 v66  
    1 [[TOC]]
     1= This page has moved
    22
    3 = obfs4proxy bridge deployment guide =
    4 This guide will help you run an obfs4 bridge to help censored users connect to the Tor network. The requirements are 1) 24/7 Internet connectivity and 2) the ability to expose TCP ports to the Internet (make sure that NAT doesn't get in the way).
    5 
    6 If you're a censored user and need a bridge to connect, please see [wiki:/doc/PluggableTransports#HowtousePluggableTransports How to use a PT bridge].
    7 
    8 '''Note: '''If you're running platforms that are not listed on this page, you should probably [https://gitlab.com/yawning/obfs4#installation compile obfs4 from source].
    9 
    10 == Debian / Ubuntu ==
    11 Follow the steps below to deploy obfs4proxy on Debian / Ubuntu:
    12 
    13  1. Install Tor:[[BR]][[BR]]Get the latest version of Tor. If you're on Debian stable, `sudo apt-get install tor` should give you the latest stable version of Tor.[[BR]]'''
    14 
    15 * Note:''' Ubuntu users need to get it from Tor repository. Please see [https://www.torproject.org/docs/debian.html.en#ubuntu '"Download instructions for Ubuntu"'].[[BR]]
    16 
    17  2. Install obfs4proxy:[[BR]][[BR]]On [https://packages.debian.org/search?keywords=obfs4proxy Debian], the `obfs4proxy` package is available in sid, buster, and stretch. On [https://packages.ubuntu.com/search?keywords=obfs4proxy Ubuntu], bionic, cosmic, disco, and eoan have the package. If you're running any of them, `sudo apt-get install obfs4proxy` should work.[[BR]]If not, you can [https://gitlab.com/yawning/obfs4#installation build it from source].[[BR]]
    18 
    19  3. Edit your Tor config file, usually located at `/etc/tor/torrc`, and replace its content with:[[BR]][[BR]]
    20 {{{
    21 RunAsDaemon 1
    22 BridgeRelay 1
    23 
    24 # Replace "TODO" with a Tor port of your choice.  This port must be externally
    25 # reachable.  Avoid port 9001 because it's commonly associated with Tor and
    26 # censors may be scanning the Internet for this port.
    27 ORPort TODO
    28 
    29 ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
    30 
    31 # Replace "TODO" with an obfs4 port of your choice.  This port must be
    32 # externally reachable.  Avoid port 9001 because it's commonly associated with
    33 # Tor and censors may be scanning the Internet for this port.
    34 ServerTransportListenAddr obfs4 0.0.0.0:TODO
    35 
    36 # Local communication port between Tor and obfs4.  Always set this to "auto".
    37 # "Ext" means "extended", not "external".  Don't try to set a specific port
    38 # number, nor listen on 0.0.0.0.
    39 ExtORPort auto
    40 
    41 # Replace "<address@email.com>" with your email address so we can contact you if
    42 # there are problems with your bridge.  This is optional but encouraged.
    43 ContactInfo <address@email.com>
    44 
    45 # Pick a nickname that you like for your bridge.  This is optional.
    46 Nickname PickANickname
    47 }}}
    48 Don't forget to change the ORPort, ServerTransportListenAddr, ContactInfo, and Nickname options.
    49 
    50 * If you decide to use an obfs4 port smaller than 1024 (for example 80 or 443), you will need to give obfs4proxy `CAP_NET_BIND_SERVICE` capabilities to bind the port with a non-root user:
    51 
    52 {{{
    53 sudo setcap cap_net_bind_service=+ep /usr/bin/obfs4proxy
    54 }}}
    55 
    56 * Under Debian, you will also need to set `NoNewPrivileges=no` in `/lib/systemd/system/tor@default.service` and `/lib/systemd/system/tor@.service` and then run `systemctl daemon-reload`. ([https://trac.torproject.org/projects/tor/ticket/18356 bug #18356])
    57 
    58 * Note that both Tor's OR port **and** its obfs4 port must be reachable. If your bridge is behind a firewall or NAT, make sure to open both ports. You can use [https://bridges.torproject.org/scan/ our reachability test] to see if your obfs4 port is reachable from the Internet.
    59 
    60 
    61  4. Restart tor: `systemctl restart tor`.[[BR]]
    62  5. Monitor your logs (usually in `/var/log/tor/log` or `/var/log/syslog`), to confirm your bridge is running with no issues.[[BR]][[BR]]You should see something like this:[[BR]][[BR]]
    63 {{{
    64 [notice] Your Tor server's identity key fingerprint is '<NICKNAME> <FINGERPRINT>'
    65 [notice] Your Tor bridge's hashed identity key fingerprint is '<NICKNAME> <HASHED FINGERPRINT>'
    66 [notice] Registered server transport 'obfs4' at '[::]:46396'
    67 [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
    68 [notice] Bootstrapped 100%: Done
    69 [notice] Now checking whether ORPort <redacted>:3818 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
    70 [notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.
    71 }}}
    72 
    73 == CentOS / RHEL / OpenSUSE ==
    74 Follow the steps below to deploy obfs4proxy on CentOS / RHEL:
    75 
    76 1. Install tor and dependencies
    77 
    78 * Redhat / RHEL:
    79 {{{
    80 yum install epel-release
    81 yum install git golang tor
    82 }}}
    83 
    84 * OpenSUSE:
    85 {{{
    86 zypper install tor go git
    87 }}}
    88 
    89 2. Build obfs4proxy and move it into place. (Heavily outdated versions of git can make `go get` fail, so try upgrading to a more recent git version if you're running into this problem.)
    90 
    91 * CentOS / RHEL:
    92 {{{
    93 export GOPATH=`mktemp -d`
    94 go get gitlab.com/yawning/obfs4.git/obfs4proxy
    95 sudo cp $GOPATH/bin/obfs4proxy /usr/local/bin/
    96 chcon --reference=/usr/bin/tor /usr/local/bin/obfs4proxy
    97 }}}
    98 
    99 * OpenSUSE:
    100 {{{
    101 export GOPATH=`mktemp -d`
    102 go get gitlab.com/yawning/obfs4.git/obfs4proxy
    103 sudo cp $GOPATH/bin/obfs4proxy /usr/local/bin/
    104 }}}
    105 
    106 3. Edit your Tor config file, usually located at `/etc/tor/torrc`, and replace its content with:
    107 {{{
    108 RunAsDaemon 1
    109 BridgeRelay 1
    110 
    111 # Replace "TODO" with a Tor port of your choice.  This port must be externally
    112 # reachable.  Avoid port 9001 because it's commonly associated with Tor and
    113 # censors may be scanning the Internet for this port.
    114 ORPort TODO
    115 
    116 ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
    117 
    118 # Replace "TODO" with an obfs4 port of your choice.  This port must be
    119 # externally reachable.  Avoid port 9001 because it's commonly associated with
    120 # Tor and censors may be scanning the Internet for this port.
    121 ServerTransportListenAddr obfs4 0.0.0.0:TODO
    122 
    123 # Local communication port between Tor and obfs4.  Always set this to "auto".
    124 # "Ext" means "extended", not "external".  Don't try to set a specific port
    125 # number, nor listen on 0.0.0.0.
    126 ExtORPort auto
    127 
    128 # Replace "<address@email.com>" with your email address so we can contact you if
    129 # there are problems with your bridge.  This is optional but encouraged.
    130 ContactInfo <address@email.com>
    131 
    132 # Pick a nickname that you like for your bridge.  This is optional.
    133 Nickname PickANickname
    134 }}}
    135 Don't forget to change the ORPort, ServerTransportListenAddr, ContactInfo, and Nickname options.
    136 
    137 * Note that both Tor's OR port **and** its obfs4 port must be reachable. If your bridge is behind a firewall or NAT, make sure to open both ports.  You can use [https://bridges.torproject.org/scan/ our reachability test] to see if your obfs4 port is reachable from the Internet.
    138 
    139 4. Restart tor: `systemctl restart tor`.
    140 
    141 5. Monitor your logs (usually in your syslog), to confirm your bridge is running with no issues.[[BR]][[BR]]You should see something like this:
    142 
    143 {{{
    144 [notice] Your Tor server's identity key fingerprint is '<NICKNAME> <FINGERPRINT>'
    145 [notice] Your Tor bridge's hashed identity key fingerprint is '<NICKNAME> <HASHED FINGERPRINT>'
    146 [notice] Registered server transport 'obfs4' at '[::]:46396'
    147 [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
    148 [notice] Bootstrapped 100%: Done
    149 [notice] Now checking whether ORPort <redacted>:3818 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
    150 [notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.
    151 }}}
    152 
    153 == FreeBSD ==
    154 Follow the steps below to deploy obfs4proxy on FreeBSD:
    155 
    156 1. Install packages
    157 
    158 {{{
    159 pkg install obfs4proxy-tor tor ca_root_nss
    160 }}}
    161 
    162 2. Edit your Tor config file, usually located at `/usr/local/etc/tor`, and replace its content with:
    163 
    164 {{{
    165 RunAsDaemon 1
    166 BridgeRelay 1
    167 
    168 # Replace "TODO" with a Tor port of your choice.  This port must be externally
    169 # reachable.  Avoid port 9001 because it's commonly associated with Tor and
    170 # censors may be scanning the Internet for this port.
    171 ORPort TODO
    172 
    173 ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
    174 
    175 # Replace "TODO" with an obfs4 port of your choice.  This port must be
    176 # externally reachable.  Avoid port 9001 because it's commonly associated with
    177 # Tor and censors may be scanning the Internet for this port.
    178 ServerTransportListenAddr obfs4 0.0.0.0:TODO
    179 
    180 # Local communication port between Tor and obfs4.  Always set this to "auto".
    181 # "Ext" means "extended", not "external".  Don't try to set a specific port
    182 # number, nor listen on 0.0.0.0.
    183 ExtORPort auto
    184 
    185 # Replace "<address@email.com>" with your email address so we can contact you if
    186 # there are problems with your bridge.  This is optional but encouraged.
    187 ContactInfo <address@email.com>
    188 
    189 # Pick a nickname that you like for your bridge.  This is optional.
    190 Nickname PickANickname
    191 
    192 Log notice file /var/log/tor/notices.log
    193 }}}
    194 Don't forget to change the ORPort, ServerTransportListenAddr, ContactInfo, and Nickname options.
    195 
    196 * Note that both Tor's OR port **and** its obfs4 port must be reachable. If your bridge is behind a firewall or NAT, make sure to open both ports. You can use [https://bridges.torproject.org/scan/ our reachability test] to see if your obfs4 port is reachable from the Internet.
    197 
    198 3. Ensure that the `random_id` sysctl setting is enabled:
    199 
    200 {{{
    201 echo "net.inet.ip.random_id=1" >> /etc/sysctl.conf
    202 sysctl net.inet.ip.random_id=1
    203 }}}
    204 
    205 
    206 4. Start the tor daemon and make sure it starts at boot:
    207 
    208 {{{
    209 sysrc tor_enable=YES
    210 service tor start
    211 }}}
    212 
    213 
    214 5. Monitor your logs (`/var/log/tor/notices.log`), to confirm your bridge is running with no issues.[[BR]][[BR]]You should see something like this:
    215 
    216 {{{
    217 [notice] Your Tor server's identity key fingerprint is '<NICKNAME> <FINGERPRINT>'
    218 [notice] Your Tor bridge's hashed identity key fingerprint is '<NICKNAME> <HASHED FINGERPRINT>'
    219 [notice] Registered server transport 'obfs4' at '[::]:46396'
    220 [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
    221 [notice] Bootstrapped 100%: Done
    222 [notice] Now checking whether ORPort <redacted>:3818 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
    223 [notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.
    224 }}}
    225 
    226 6. To get the fastest package updates, switch from the  "quarterly" package repo to the "latest" repo.
    227 
    228 Create the following folder:
    229 
    230 {{{
    231 mkdir -p /usr/local/etc/pkg/repos
    232 }}}
    233 
    234 Create the file `/usr/local/etc/pkg/repos/FreeBSD.conf` with the following content:
    235 
    236 {{{
    237 FreeBSD: { enabled: no }
    238 
    239 FreeBSDlatest: {
    240   url: "pkg+https://pkg.FreeBSD.org/${ABI}/latest",
    241   mirror_type: "srv",
    242   signature_type: "fingerprints",
    243   fingerprints: "/usr/share/keys/pkg",
    244   enabled: yes
    245 }
    246 }}}
    247 
    248 == OpenBSD ==
    249 
    250 Follow the steps below to deploy obfs4proxy on OpenBSD:
    251 
    252 1. Install packages
    253 
    254 {{{
    255 pkg_add tor obfs4proxy
    256 }}}
    257 
    258 2. Edit your Tor config file, usually located at `/etc/tor/torrc`, and replace its content with:
    259 
    260 {{{
    261 RunAsDaemon 1
    262 BridgeRelay 1
    263 
    264 # Replace "TODO" with a Tor port of your choice.  This port must be externally
    265 # reachable.  Avoid port 9001 because it's commonly associated with Tor and
    266 # censors may be scanning the Internet for this port.
    267 ORPort TODO
    268 
    269 ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
    270 
    271 # Replace "TODO" with an obfs4 port of your choice.  This port must be
    272 # externally reachable.  Avoid port 9001 because it's commonly associated with
    273 # Tor and censors may be scanning the Internet for this port.
    274 ServerTransportListenAddr obfs4 0.0.0.0:TODO
    275 
    276 # Local communication port between Tor and obfs4.  Always set this to "auto".
    277 # "Ext" means "extended", not "external".  Don't try to set a specific port
    278 # number, nor listen on 0.0.0.0.
    279 ExtORPort auto
    280 
    281 # Replace "<address@email.com>" with your email address so we can contact you if
    282 # there are problems with your bridge.  This is optional but encouraged.
    283 ContactInfo <address@email.com>
    284 
    285 # Pick a nickname that you like for your bridge.  This is optional.
    286 Nickname PickANickname
    287 
    288 Log notice file /var/log/tor/notices.log
    289 
    290 User _tor
    291 }}}
    292 Don't forget to change the ORPort, ServerTransportListenAddr, ContactInfo, and Nickname options.
    293 
    294 * Note that both Tor's OR port **and** its obfs4 port must be reachable. If your bridge is behind a firewall or NAT, make sure to open both ports. You can use [https://bridges.torproject.org/scan/ our reachability test] to see if your obfs4 port is reachable from the Internet.
    295 
    296 3. Start the tor daemon and make sure it starts at boot:
    297 
    298 {{{
    299 rcctl enable tor
    300 rcctl start tor
    301 }}}
    302 
    303 4. Monitor your logs (`/var/log/tor/notices.log`), to confirm your bridge is running with no issues.[[BR]][[BR]]You should see something like this:
    304 
    305 {{{
    306 [notice] Your Tor server's identity key fingerprint is '<NICKNAME> <FINGERPRINT>'
    307 [notice] Your Tor bridge's hashed identity key fingerprint is '<NICKNAME> <HASHED FINGERPRINT>'
    308 [notice] Registered server transport 'obfs4' at '[::]:46396'
    309 [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
    310 [notice] Bootstrapped 100%: Done
    311 [notice] Now checking whether ORPort <redacted>:3818 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
    312 [notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.
    313 }}}
    314 
    315 == Docker ==
    316 We are maintaining a docker container that allows you to quickly set up an obfs4 bridge. First, fetch the container:
    317 {{{
    318 docker pull phwinter/obfs4-bridge:0.1
    319 }}}
    320 Now, it's time to run the container. You have two options:
    321 
    322 1. We maintain a script that automatically determines a free OR and obfs4 port for you. The script only requires your email address as argument:
    323 {{{
    324 $ curl https://dip.torproject.org/anti-censorship/docker-obfs4-bridge/raw/master/deploy-container.sh > deploy-container.sh
    325 $ bash deploy-container.sh address@email.com
    326 }}}
    327 
    328 2. If you would rather provide your own ports, run the following command and replace `XXX` with your OR port, `YYY` with your obfs4 port, and `address@email.com` with your email address. Don't forget the semicolon after the enrivonment variables.
    329 {{{
    330 OR_PORT=XXX PT_PORT=YYY EMAIL=address@email.com; \
    331 docker run -d \
    332   -e "OR_PORT=$OR_PORT" -e "PT_PORT=$PT_PORT" -e "EMAIL=$EMAIL" \
    333   -p "$OR_PORT":"$OR_PORT" -p "$PT_PORT":"$PT_PORT" \
    334   phwinter/obfs4-bridge:0.1
    335 }}}
    336 That's it! Your container should now be bootstrapping your new obfs4 Tor bridge.
    337 
    338 == Post-install==
    339 Congrats!
    340 
    341 * If you get to this point, it means that your obfs4 bridge is running and is being distributed by BridgeDB to censored users. Note that it can take several days or weeks until you see a consistent set of users, so don't get discouraged if you don't see user connections right away. BridgeDB uses four buckets for bridge distribution: HTTPS, Moat, Email, and manual. Some buckets are used more than others, which also affects the time until your bridge sees users. Finally, there aren't many bridge users out there, so you cannot expect your bridge to be as popular as a relay.
    342 
    343 * If you want to connect to your bridge manually, you will need to know the bridge's obfs4 certificate. See the file `/var/lib/tor/pt_state/obfs4_bridgeline.txt` and paste the entire bridge line into Tor Browser:
    344 {{{
    345 Bridge obfs4 <IP ADDRESS>:<PORT> <FINGERPRINT> cert=<CERTIFICATE> iat-mode=0
    346 }}}
    347   You'll need to replace `<IP ADDRESS>`, `<PORT>`, and `<FINGERPRINT>` with the actual values, which you can find in the tor log. Make sure to use `<FINGERPRINT>`, not `<HASHED FINGERPRINT>`; and that `<PORT>` is the obfs4 port you chose—and not the OR port.
    348 
    349 * Finally, you can monitor your obfs4 bridge's usage on [https://metrics.torproject.org/rs.html#search Relay Search].  Just enter your bridge's `<HASHED FINGERPRINT>` in the form and click "Search". After having set up the bridge, it takes approximately three hours for the bridge to show up in Relay Search.
    350 
    351 == Getting Help ==
    352 If you run into problems while setting up your relay you can ask your questions on the public tor-relays mailing list:
    353 * https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-relays
    354 This is a great resource for asking (and answering) questions, and generally getting to know other relay operators. Make sure to check out the archives!
    355 * irc.oftc.net #tor-relays
    356 This is a great place to meet relay operators, and have real-time discussions
     3For up-to-date instructions on how to set up an obfs4 bridge, please go to: https://community.torproject.org/relay/setup/bridge/