[tor-commits] [community/staging] Update obfs4 instructions based on wiki version 65
pili at torproject.org
pili at torproject.org
Fri Aug 2 11:41:22 UTC 2019
commit 95fdb76a9be931c0cc7df1e0bc03e693ece66fbf
Author: gus <gus at torproject.org>
Date: Tue Jul 30 05:50:20 2019 -0400
Update obfs4 instructions based on wiki version 65
---
.../bridge/centos-rhel-opensuse/contents.lr | 52 +++++++++++--------
.../bridge/debian-ubuntu/contents.lr | 58 ++++++++++++----------
.../technical-setup/bridge/docker/contents.lr | 38 ++++++++++++++
.../technical-setup/bridge/freebsd/contents.lr | 52 +++++++++++--------
.../technical-setup/bridge/openbsd/contents.lr | 45 ++++++++++-------
.../bridge/post-install/contents.lr | 10 ++--
6 files changed, 166 insertions(+), 89 deletions(-)
diff --git a/content/relay-operations/technical-setup/bridge/centos-rhel-opensuse/contents.lr b/content/relay-operations/technical-setup/bridge/centos-rhel-opensuse/contents.lr
index 5849e5a..541ec2b 100644
--- a/content/relay-operations/technical-setup/bridge/centos-rhel-opensuse/contents.lr
+++ b/content/relay-operations/technical-setup/bridge/centos-rhel-opensuse/contents.lr
@@ -4,7 +4,7 @@ title: CentOS / RHEL / OpenSUSE
---
body:
-# 1. Install tor and dependencies
+### 1. Install tor and dependencies
* Redhat / RHEL:
@@ -19,7 +19,7 @@ yum install git golang tor
zypper install tor go git
```
-# 2. Build obfs4proxy and move it into place.
+### 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.
@@ -40,37 +40,46 @@ go get gitlab.com/yawning/obfs4.git/obfs4proxy
sudo cp $GOPATH/bin/obfs4proxy /usr/local/bin/
```
-# 3. Edit your Tor config file, usually located at `/etc/tor/torrc` and add the following lines:
+### 3. Edit your Tor config file, usually located at `/etc/tor/torrc` and add the following lines:
```
-#Bridge config
RunAsDaemon 1
-ORPort auto
BridgeRelay 1
-ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
-# For a fixed obfs4 port (e.g. 34176), uncomment the following line.
-#ServerTransportListenAddr obfs4 0.0.0.0:34176
-# Local communication port between Tor and obfs4. Always set this to "auto". "Ext" means
-# "extended", not "external". Don't try to set a specific port number, nor listen on 0.0.0.0.
+
+# Replace "TODO" with a Tor port of your choice. This port must be externally
+# reachable. Avoid port 9001 because it's commonly associated with Tor and
+# censors may be scanning the Internet for this port.
+ORPort TODO
+
+ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
+
+# Replace "TODO" with an obfs4 port of your choice. This port must be
+# externally reachable. Avoid port 9001 because it's commonly associated with
+# Tor and censors may be scanning the Internet for this port.
+ServerTransportListenAddr obfs4 0.0.0.0:TODO
+
+# Local communication port between Tor and obfs4. Always set this to "auto".
+# "Ext" means "extended", not "external". Don't try to set a specific port
+# number, nor listen on 0.0.0.0.
ExtORPort auto
-# Contact information that allows us to get in touch with you in case of
-# critical updates or problems with your bridge. This is optional, so you
-# don't have to provide an email address if you don't want to.
+# Replace "<address at email.com>" with your email address so we can contact you if
+# there are problems with your bridge. This is optional but encouraged.
ContactInfo <address at email.com>
-# Pick a nickname that you like for your bridge.
+
+# Pick a nickname that you like for your bridge. This is optional.
Nickname PickANickname
```
-Don't forget to change the ContactInfo and Nickname options.
+ Don't forget to change the `ORPort`, `ServerTransportListenAddr`, `ContactInfo`, and `Nickname` options.
-* 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.
+* 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 [our reachability test](https://bridges.torproject.org/scan/) to see if your obfs4 port is reachable from the Internet.
-# 4. Restart tor
+### 4. Restart tor
`systemctl restart tor`
-# 5. Monitor your logs (usually in your syslog)
+### 5. Monitor your logs (usually in your syslog)
To confirm your bridge is running with no issues, you should see something like this:
@@ -84,9 +93,6 @@ To confirm your bridge is running with no issues, you should see something like
[notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.
```
-Remember to open the random port associated with your bridge. You can find it in your tor log; in the above example it is 46396. To use a fixed port, uncomment the [ServerTransportListenAddr](https://www.torproject.org/docs/tor-manual.html.en#ServerTransportListenAddr) option in your torrc. You can use [our reachability test](https://bridges.torproject.org/scan/) to see if your obfs4 port is reachable from the Internet.
-
-
---
html: two-columns-page.html
---
@@ -99,3 +105,7 @@ color: primary
subtitle: How to deploy obfs4proxy Bridge on CentOS / RHEL / OpenSUSE
---
_template: layout.html
+---
+section: bridge
+---
+section_id: bridge
diff --git a/content/relay-operations/technical-setup/bridge/debian-ubuntu/contents.lr b/content/relay-operations/technical-setup/bridge/debian-ubuntu/contents.lr
index 8900995..019503e 100644
--- a/content/relay-operations/technical-setup/bridge/debian-ubuntu/contents.lr
+++ b/content/relay-operations/technical-setup/bridge/debian-ubuntu/contents.lr
@@ -4,57 +4,67 @@ title: Debian / Ubuntu
---
body:
-# 1. Install Tor
+### 1. Install Tor
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.
-* Note:''' Ubuntu users need to get it from Tor repository. Please see [Download instructions for Ubuntu](https://www.torproject.org/docs/debian.html.en#ubuntu).
+* Note: **Ubuntu users need to get it from Tor repository. Please see** [Download instructions for Ubuntu](https://www.torproject.org/docs/debian.html.en#ubuntu).
-# 2. Install obfs4proxy
+### 2. Install obfs4proxy
-On [Debian](https://packages.debian.org/search?keywords=obfs4proxy), 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.
+On [Debian](https://packages.debian.org/search?keywords=obfs4proxy), the `obfs4proxy` package is available in sid, buster, and stretch. On [Ubuntu](https://packages.ubuntu.com/search?keywords=obfs4proxy), bionic, cosmic, disco, and eoan have the package. If you're running any of them, `sudo apt-get install obfs4proxy` should work.
If not, you can [build it from source](https://gitlab.com/yawning/obfs4#installation).
-# 3. Edit your Tor config file, usually located at `/etc/tor/torrc` and add the following lines:
+
+### 3. Edit your Tor config file, usually located at `/etc/tor/torrc` and add the following lines:
```
-#Bridge config
RunAsDaemon 1
-ORPort auto
BridgeRelay 1
+
+# Replace "TODO" with a Tor port of your choice. This port must be externally
+# reachable. Avoid port 9001 because it's commonly associated with Tor and
+# censors may be scanning the Internet for this port.
+ORPort TODO
+
ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
-# For a fixed obfs4 port (e.g. 34176), uncomment the following line.
-#ServerTransportListenAddr obfs4 0.0.0.0:34176
-# Local communication port between Tor and obfs4. Always set this to "auto". "Ext" means
-# "extended", not "external". Don't try to set a specific port number, nor listen on 0.0.0.0.
+
+# Replace "TODO" with an obfs4 port of your choice. This port must be
+# externally reachable. Avoid port 9001 because it's commonly associated with
+# Tor and censors may be scanning the Internet for this port.
+ServerTransportListenAddr obfs4 0.0.0.0:TODO
+
+# Local communication port between Tor and obfs4. Always set this to "auto".
+# "Ext" means "extended", not "external". Don't try to set a specific port
+# number, nor listen on 0.0.0.0.
ExtORPort auto
-# Contact information that allows us to get in touch with you in case of
-# critical updates or problems with your bridge. This is optional, so you
-# don't have to provide an email address if you don't want to.
+# Replace "<address at email.com>" with your email address so we can contact you if
+# there are problems with your bridge. This is optional but encouraged.
ContactInfo <address at email.com>
-# Pick a nickname that you like for your bridge.
+
+# Pick a nickname that you like for your bridge. This is optional.
Nickname PickANickname
```
-Don't forget to change the ContactInfo and Nickname options.
+
+ Don't forget to change the `ORPort`, `ServerTransportListenAddr`, `ContactInfo`, and `Nickname` options.
* If you decide to use a fixed obfs4 port smaller than 1024 (for example 80 or 443), you will need to give obfs4 `CAP_NET_BIND_SERVICE` capabilities to bind the port with a non-root user:
-```
-sudo setcap cap_net_bind_service=+ep /usr/bin/obfs4proxy
-```
+
+`sudo setcap cap_net_bind_service=+ep /usr/bin/obfs4proxy`
* Under Debian, you will also need to set `NoNewPrivileges=no` in `/lib/systemd/system/tor at default.service` and `/lib/systemd/system/tor at .service` and then run `systemctl daemon-reload`. [bug #18356](https://trac.torproject.org/projects/tor/ticket/18356)
-* 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.
+* 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 [our reachability test](https://bridges.torproject.org/scan/) to see if your obfs4 port is reachable from the Internet.
-# 4. Restart tor
+### 4. Restart tor
`systemctl restart tor`
-# 5. Monitor your logs
+### 5. Monitor your logs
To confirm your bridge is running with no issues, you should see something like this (usually in `/var/log/tor/log` or `/var/log/syslog`):
@@ -68,10 +78,6 @@ To confirm your bridge is running with no issues, you should see something like
[notice] Now checking whether ORPort <redacted>:9001 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
[notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.
```
-
-Remember to open the random port associated with your bridge. You can find it in your tor log; in the above example it is 46396. To use a fixed port, uncomment the [ServerTransportListenAddr](https://www.torproject.org/docs/tor-manual.html.en#ServerTransportListenAddr) option in your torrc. You can use [our reachability test](https://bridges.torproject.org/scan/) to see if your obfs4 port is reachable from the Internet.
-
-
---
key: 1
---
diff --git a/content/relay-operations/technical-setup/bridge/docker/contents.lr b/content/relay-operations/technical-setup/bridge/docker/contents.lr
new file mode 100644
index 0000000..2353ea2
--- /dev/null
+++ b/content/relay-operations/technical-setup/bridge/docker/contents.lr
@@ -0,0 +1,38 @@
+_model: page
+---
+title: Docker
+---
+body:
+
+We are maintaining a docker container that allows you to quickly set up an obfs4 bridge. First, fetch the container:
+
+`docker pull phwinter/obfs4-bridge:0.1`
+
+Now, it's time to run the container. You have two options:
+
+ * We maintain a script that automatically determines a free OR and obfs4 port for you. The script only requires your email address as argument:
+
+```
+ $ curl https://dip.torproject.org/anti-censorship/docker-obfs4-bridge/raw/master/deploy-container.sh > deploy-container.sh
+ $ bash deploy-container.sh address at email.com
+```
+
+ * 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 at email.com with your email address. Don't forget the semicolon after the environment variables.
+
+```
+ OR_PORT=XXX PT_PORT=YYY EMAIL=address at email.com; \
+ docker run -d \
+ -e "OR_PORT=$OR_PORT" -e "PT_PORT=$PT_PORT" -e "EMAIL=$EMAIL" \
+ -p "$OR_PORT":"$OR_PORT" -p "$PT_PORT":"$PT_PORT" \
+ phwinter/obfs4-bridge:0.1
+```
+
+That's it! Your container should now be bootstrapping your new obfs4 Tor bridge.
+---
+html: two-columns-page.html
+---
+key: 5
+---
+section: Bridge
+---
+section_id: bridge
diff --git a/content/relay-operations/technical-setup/bridge/freebsd/contents.lr b/content/relay-operations/technical-setup/bridge/freebsd/contents.lr
index 01adcd2..7363451 100644
--- a/content/relay-operations/technical-setup/bridge/freebsd/contents.lr
+++ b/content/relay-operations/technical-setup/bridge/freebsd/contents.lr
@@ -8,55 +8,64 @@ key: 3
---
body:
-# 1. Install packages
+### 1. Install packages
```
pkg install obfs4proxy-tor tor ca_root_nss
```
-# 2. Edit your Tor config file, usually located at `/usr/local/etc/tor` and add the following lines
+### 2. Edit your Tor config file, usually located at `/usr/local/etc/tor` and add the following lines
```
-#Bridge config
RunAsDaemon 1
-ORPort auto
BridgeRelay 1
-ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
-# For a fixed obfs4 port (e.g. 34176), uncomment the following line.
-#ServerTransportListenAddr obfs4 0.0.0.0:34176
-# Local communication port between Tor and obfs4. Always set this to "auto". "Ext" means
-# "extended", not "external". Don't try to set a specific port number, nor listen on 0.0.0.0.
+
+# Replace "TODO" with a Tor port of your choice. This port must be externally
+# reachable. Avoid port 9001 because it's commonly associated with Tor and
+# censors may be scanning the Internet for this port.
+ORPort TODO
+
+ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
+
+# Replace "TODO" with an obfs4 port of your choice. This port must be
+# externally reachable. Avoid port 9001 because it's commonly associated with
+# Tor and censors may be scanning the Internet for this port.
+ServerTransportListenAddr obfs4 0.0.0.0:TODO
+
+# Local communication port between Tor and obfs4. Always set this to "auto".
+# "Ext" means "extended", not "external". Don't try to set a specific port
+# number, nor listen on 0.0.0.0.
ExtORPort auto
-# Contact information that allows us to get in touch with you in case of
-# critical updates or problems with your bridge. This is optional, so you
-# don't have to provide an email address if you don't want to.
+# Replace "<address at email.com>" with your email address so we can contact you if
+# there are problems with your bridge. This is optional but encouraged.
ContactInfo <address at email.com>
-# Pick a nickname that you like for your bridge.
+
+# Pick a nickname that you like for your bridge. This is optional.
Nickname PickANickname
Log notice file /var/log/tor/notices.log
```
-Don't forget to change the ContactInfo and Nickname options.
+Don't forget to change the `ORPort`, `ServerTransportListenAddr`, `ContactInfo`, and `Nickname` options.
-* 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.
+* 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 [our reachability test](https://bridges.torproject.org/scan/) to see if your obfs4 port is reachable from the Internet.
-# 3. Ensure that the `random_id` sysctl setting is enabled:
+### 3. Ensure that the `random_id` sysctl setting is enabled:
```
echo "net.inet.ip.random_id=1" >> /etc/sysctl.conf
sysctl net.inet.ip.random_id=1
```
-# 4. Start the tor daemon and make sure it starts at boot:
+### 4. Start the tor daemon and make sure it starts at boot:
```
sysrc tor_enable=YES
service tor start
```
-# 5. Monitor your logs
+### 5. Monitor your logs
To confirm your bridge is running with no issues, you should see something like this in `/var/log/tor/notices.log`:
@@ -70,9 +79,8 @@ To confirm your bridge is running with no issues, you should see something like
[notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.
```
-Remember to open the random port associated with your bridge. You can find it in your tor log; in the above example it is 46396. To use a fixed port, uncomment the [ ServerTransportListenAddr](https://www.torproject.org/docs/tor-manual.html.en#ServerTransportListenAddr) option in your torrc. You can use[our reachability test] (https://bridges.torproject.org/scan/) to see if your obfs4 port is reachable from the Internet.
-# 6. To get the fastest package updates, switch from the "quarterly" package repo to the "latest" repo.
+### 6. To get the fastest package updates, switch from the "quarterly" package repo to the "latest" repo.
Create the following folder:
@@ -96,3 +104,7 @@ FreeBSDlatest: {
---
subtitle: How to deploy obfs4proxy Bridge on FreeBSD
+---
+section: Bridge
+---
+section_id: bridge
diff --git a/content/relay-operations/technical-setup/bridge/openbsd/contents.lr b/content/relay-operations/technical-setup/bridge/openbsd/contents.lr
index ae682d9..637f94a 100644
--- a/content/relay-operations/technical-setup/bridge/openbsd/contents.lr
+++ b/content/relay-operations/technical-setup/bridge/openbsd/contents.lr
@@ -8,32 +8,41 @@ key: 4
---
body:
-# 1. Install packages
+### 1. Install packages
```
pkg_add tor obfs4proxy
```
-# 2. Edit your Tor config file
+### 2. Edit your Tor config file
Usually located at `/etc/tor/torrc`, add the following lines:
```
-#Bridge config
RunAsDaemon 1
-ORPort auto
BridgeRelay 1
-ServerTransportPlugin obfs4 exec /usr/local/bin/obfs4proxy
-# For a fixed obfs4 port (e.g. 34176), uncomment the following line.
-#ServerTransportListenAddr obfs4 0.0.0.0:34176
-# Local communication port between Tor and obfs4. Always set this to "auto". "Ext" means
-# "extended", not "external". Don't try to set a specific port number, nor listen on 0.0.0.0.
+
+# Replace "TODO" with a Tor port of your choice. This port must be externally
+# reachable. Avoid port 9001 because it's commonly associated with Tor and
+# censors may be scanning the Internet for this port.
+ORPort TODO
+
+ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
+
+# Replace "TODO" with an obfs4 port of your choice. This port must be
+# externally reachable. Avoid port 9001 because it's commonly associated with
+# Tor and censors may be scanning the Internet for this port.
+ServerTransportListenAddr obfs4 0.0.0.0:TODO
+
+# Local communication port between Tor and obfs4. Always set this to "auto".
+# "Ext" means "extended", not "external". Don't try to set a specific port
+# number, nor listen on 0.0.0.0.
ExtORPort auto
-# Contact information that allows us to get in touch with you in case of
-# critical updates or problems with your bridge. This is optional, so you
-# don't have to provide an email address if you don't want to.
+# Replace "<address at email.com>" with your email address so we can contact you if
+# there are problems with your bridge. This is optional but encouraged.
ContactInfo <address at email.com>
-# Pick a nickname that you like for your bridge.
+
+# Pick a nickname that you like for your bridge. This is optional.
Nickname PickANickname
Log notice file /var/log/tor/notices.log
@@ -41,17 +50,17 @@ Log notice file /var/log/tor/notices.log
User _tor
```
-Don't forget to change the ContactInfo and Nickname options.
+Don't forget to change the `ORPort`, `ServerTransportListenAddr`, `ContactInfo`, and `Nickname` options.
-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.
+* 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 [our reachability test](https://bridges.torproject.org/scan/) to see if your obfs4 port is reachable from the Internet.
-# 3. Start the tor daemon and make sure it starts at boot:
+### 3. Start the tor daemon and make sure it starts at boot:
```
rcctl enable tor
rcctl start tor
```
-# 4. Monitor your logs
+### 4. Monitor your logs
To confirm your bridge is running with no issues, you should see something like this (`/var/log/tor/notices.log`):
@@ -64,8 +73,6 @@ To confirm your bridge is running with no issues, you should see something like
[notice] Now checking whether ORPort <redacted>:9001 is reachable... (this may take up to 20 minutes -- look for log messages indicating success)
[notice] Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.
```
-
-Remember to open the random port associated with your bridge. You can find it in your tor log; in the above example it is 46396. To use a fixed port, uncomment the [ServerTransportListenAddr](https://www.torproject.org/docs/tor-manual.html.en#ServerTransportListenAddr) option in your torrc. You can use [our reachability test](https://bridges.torproject.org/scan/) to see if your obfs4 port is reachable from the Internet.
---
subtitle: How to deploy obfs4proxy Bridge on OpenBSD
---
diff --git a/content/relay-operations/technical-setup/bridge/post-install/contents.lr b/content/relay-operations/technical-setup/bridge/post-install/contents.lr
index e7f19cd..37b168f 100644
--- a/content/relay-operations/technical-setup/bridge/post-install/contents.lr
+++ b/content/relay-operations/technical-setup/bridge/post-install/contents.lr
@@ -4,19 +4,23 @@ title: Post-install
---
body:
-Congrats! If you get to this point, it means that your obfs4 bridge is running and is being distributed by BridgeDB to censored users. 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:
+Congrats!
+
+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 to see a consistent set of users, so don't get discouraged if you don't see user connections right away.
+
+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:
```
Bridge obfs4 <IP ADDRESS>:<PORT> <FINGERPRINT> cert=<CERTIFICATE> iat-mode=0
```
-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 one from the log line `Registered server transport 'obfs4'`, not the one from the line `Now checking whether ORPort ... is reachable`.
+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.
Finally, you can monitor your obfs4 bridge's usage on [Relay Search](https://metrics.torproject.org/rs.html#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.
---
html: two-columns-page.html
---
-key: 5
+key: 6
---
subtitle: How to find your Bridge in Relay Search and connect manually
More information about the tor-commits
mailing list