Opened 3 years ago

Closed 13 months ago

#20943 closed task (fixed)

Clarify documentation for obfs4 setup

Reported by: kaie Owned by:
Priority: Medium Milestone:
Component: Circumvention/Obfs4 Version:
Severity: Normal Keywords:
Cc: Actual Points:
Parent ID: #30471 Points:
Reviewer: Sponsor:


I'd like to provide feedback on configuring a Tor bridge with obfs4 enabled.

It was difficult, and it took me several hours to figure it out, because the installation guides that I found weren't clear enough.

Maybe this feedback can help to clarify the existing guides that talk about obfs4 configuration.

First, I read a suggestion somewhere to use

ExtORPort auto

which defines the port used by obfs(4)proxy, and that port should ideally be bound to localhost only.

The above was a major source of confusion, it never worked for me. Only when I eventually looked at the README for obfs4proxy, which suggested to use a


configuration, I realized that the earlier statement might have been incorrect.

Second, it seems that ORPort must be port 443. With other ports, TBB gave me complaints that it failed to access the bridge IP with the configured bridge port, although that port was clearly reachable. Only after I configured ORPort to use 443 that error message on the client side went away.

Third, it was confusing which hash/fingerprint must to be used in the bridge configuration line.
Looking at the tor logfile, it prints two different lines with fingerprints:

Your Tor server's identity key fingerprint is '...first-hash...'
Your Tor bridge's hashed identity key fingerprint is '...second-hash...'

From my naive point of view, it seemed obvious to use the second-hash, because it's labeled as being the bridge hash.
But I found that it only works, if I use the first server identity hash.

Fourth, for the configuration values PORT-FOR-OBFS4 and PORT-FOR-OBFS3, you should pick numbers greater than 1024, because otherwise obfs4proxy might have trouble using that port.

Also, because I am installing on a host with multiple IP addresses, I'm providing the additional configuration parameters that are required to bind everything to the correct IP.

Below is what I use in /etc/tor/torrc:

OutboundBindAddress IPADDRESS

## 0 means: private bridge, do not publish
## 1 means: bridge information automatically published
PublishServerDescriptor 0

SocksPort 0
BridgeRelay 1
Exitpolicy reject *:*

ServerTransportPlugin obfs3,obfs4 exec /usr/bin/obfs4proxy --enableLogging --logLevel=INFO
ServerTransportListenAddr obfs4 IPADDRESS:PORT-FOR-OBFS4
ServerTransportListenAddr obfs3 IPADDRESS:PORT-FOR-OBFS3


Log notice file /var/log/tor/notice.log

Note you must replace all of the following identifiers with your own values:


Start Tor (e.g. service tor start)

Search for your fingerprint:
grep -i "server.*fingerprint" /var/log/tor/notice.log | tail -1

In the line that is printed, Use the code at the end, which looks like: ABDEF1234567890ABDEF1234567890ABDEF12345
(And use your own code below, where this document uses ABDEF1234567890ABDEF1234567890ABDEF12345)

Get some additional parameters that the obfs4 client configuration requires:
cat /var/lib/tor/pt_state/obfs4_bridgeline.txt

You need information from the line that looks like:
Bridge obfs4 <IP ADDRESS>:<PORT> <FINGERPRINT> cert=bla-bla-bla-bla-bla-bla-bla-bla iat-mode=0

Now you can assemble the complete line to use your bridge, again, replace the values with the correct ones:

obfs4 IPADDRESS:PORT-FOR-OBFS4 ABDEF1234567890ABDEF1234567890ABDEF12345 cert=bla-bla-bla-bla-bla-bla-bla-bla iat-mode=0

The above configuration also enabled obfs3 on a separate port. The configuration line for the obfs3 bridge is simpler:

obfs3 IPADDRESS:PORT-FOR-OBFS4 ABDEF1234567890ABDEF1234567890ABDEF12345

Child Tickets

Change History (11)

comment:1 Changed 3 years ago by kaie

The final line should have been:

obfs3 IPADDRESS:PORT-FOR-OBFS3 ABDEF1234567890ABDEF1234567890ABDEF12345

(port for obfs3, not 4)

comment:2 Changed 3 years ago by kaie

After some more experiments, I believe the primary reason for my failures was the following:

I had incorrectly assumed that everything would be routed through ORPort, and I had failed to notice that obfs4proxy listens on its own, separate port.

So, when I configured the bridge configuration line on the client side, I had incorrectly used the ORPort, instead of the port that obfs4proxy listens on.

Maybe this detail should be made more explicit in the documentation for setting up bridges, that obfs4proxy by default listens on port 9004 (?), that it's a separate port from ORPort, and the bridge configuration lines for the client must use the separate obfs4 port, not the ORPort,.

With that clarified, I no longer required the explicit ServerTransportListenAddr statements in torrc, and ORPort doesn't need to be 443, other ports (e.g. 9001) work, too.

comment:3 Changed 3 years ago by kaie

The information below was the source of my confusion.

On this page:

Roger said:
'The "ExtORPort auto" above is fine -- the extended ORPort is for local connections, and you don't need to open anything in your external firewall.'

It seems that statement isn't right. It seems the extended ORPort isn't restricted to local (localhost-only) connections, but rather it's used to listen for incoming connections from other computers, that want to use this server as a bridge.

The ports that "ExtORPort auto" allocates will listen on all network interfaces, not just localhost.

In my understanding, the automatically assigned ExtORPort must be accessible from the outside (and if a firewall is used, the firewall must allow incoming connections on that port(s)).

comment:4 Changed 3 years ago by kaie

Now that I understand it better, I'd like to amend the configuration I had suggested above for /etc/tor/torrc:

OutboundBindAddress IPADDRESS

## 0 means: private bridge, do not publish
## 1 means: bridge information automatically published
PublishServerDescriptor 0

SocksPort 0
BridgeRelay 1
Exitpolicy reject *:*

ExtORPort auto
ServerTransportPlugin obfs3,obfs4 exec /usr/bin/obfs4proxy --enableLogging --logLevel=INFO


Log notice file /var/log/tor/notice.log

The configuration "ExtORPort auto" is preferred, because it's better if different bridges use different port numbers, as it prevents censors from simply blocking a common bridge port number.

On first start, a random port number will be assigned on which obfs4proxy will listen.

That port number assignment will be cached, so it will be stable, even after restarting the software or the server.

You need to lookup which port number has been assigned. Search the Tor logfile for obfs4.

This is the port number that you must use in the bridge configuration line that you use on the client side that wants to connect to your bridge (instead of 9004 I had mentioned above), and a potential firewall must allow incoming connections on that port to the system that runs the bridge.

comment:5 Changed 3 years ago by kaie

... but ExtORPort auto will listen on all network interfaces!

If you must to restrict the transport ports to one network interface, I believe you still must use the

ServerTransportListenAddr obfs4 IPADDRESS:PORT-FOR-OBFS4

instead. Nevertheless, you should select a random port number.

comment:6 in reply to:  5 Changed 3 years ago by dcf

Replying to kaie:

... but ExtORPort auto will listen on all network interfaces!

That's not right. ExtORPort and ServerTransportListenAddr are completely separate things. You are correct, that ServerTransportListenAddr controls the external listening address and port for obfs4. ExtORPort is something else: it's the localhost port to which obfs4 forwards client traffic received from the outside. ExtORPort has nothing to do with the external listening address. ExtORPort can even change every time you run tor; it doesn't matter because the outside world never sees it. The point of ExtORPort auto is not to generate a random port number for censorship resistance; obfs4 already does that if you don't set ServerTransportListenAddr (and caches the port number so it will be stable).

ExtORPort is not an external listening port. ("Ext" stands for "extended", not "external".) You should always set ExtORPort auto when running a bridge.

It sounds like you might be having a problem with OutboundBindAddress instead. It is indeed a bug that pluggable transport plugins do not know about OutboundBindAddress: #5304.

comment:7 Changed 16 months ago by teor

Owner: asn deleted
Status: newassigned

asn does not need to own any obfuscation tickets any more. Default owners are trouble.

comment:8 Changed 16 months ago by cohosh

Status: assignednew

tickets are unassigned, reverting to 'new'

comment:9 Changed 13 months ago by phw

Component: Archived/ObfsproxyCircumvention/Obfs4

comment:10 Changed 13 months ago by phw

Parent ID: #30471

comment:11 Changed 13 months ago by phw

Resolution: fixed
Status: newclosed

My take-aways from this are:

  • ExtORPort is poorly named and therefore sometimes misunderstood. We try to address this confusion in our obfs4 setup guide.
  • It's not clear what hash should be used for a client's bridge line. #29128 will result in an easy-to-copy bridge line.
  • There was some confusion with the host's multiple IP addresses. #5304 will address this issue.

I'm closing this because we already have tickets for the remaining obfs4 UX issues.

Note: See TracTickets for help on using tickets.