Relay Operators

We aim to make setting up a Tor relay easy and convenient:

  • It's fine if the relay goes offline sometimes. The directories notice this quickly and stop advertising the relay. Just try to make sure it's not too often, since connections using the relay when it disconnects will break.
  • Each Tor relay has an exit policy that specifies what sort of outbound connections are allowed or refused from that relay. If you are uncomfortable allowing people to exit from your relay, you can set it up to only allow connections to other Tor relays.
  • Your relay will passively estimate and advertise its recent bandwidth capacity, so high-bandwidth relays will attract more users than low-bandwidth ones. Therefore, having low-bandwidth relays is useful too.

When an exit is misconfigured or malicious it's assigned the BadExit flag. This tells Tor to avoid exiting through that relay. In effect, relays with this flag become non-exits. If you got this flag then we either discovered a problem or suspicious activity when routing traffic through your exit and weren't able to contact you. Please reach out to the bad-relays team so we can sort out the issue.

See portforward.com for directions on how to port forward with your NAT/router device.

If your relay is running on a internal net, you need to setup port forwarding. Forwarding TCP connections is system dependent but the firewalled-clients FAQ entry offers some examples on how to do this.

Also, here's an example of how you would do this on GNU/Linux if you're using iptables:

/sbin/iptables -A INPUT -i eth0 -p tcp --destination-port 9001 -j ACCEPT

You may have to change "eth0" if you have a different external interface (the one connected to the Internet). Chances are you have only one (except the loopback) so it shouldn't be too hard to figure out.

Why Relay Load Varies

Tor manages bandwidth across the entire network. It does a reasonable job for most relays. But Tor's goals are different to protocols like BitTorrent. Tor wants low-latency web pages, which requires fast connections with headroom. BitTorrent wants bulk downloads, which requires using all the bandwidth.

We're working on a new bandwidth scanner, which is easier to understand and maintain. It will have diagnostics for relays that don't get measured, and relays that have low measurements.

Why does Tor need bandwidth scanners?

Most providers tell you the maximum speed of your local connection. But Tor has users all over the world, and our users connect to one or two Guard relays at random. So we need to know how well each relay can connect to the entire world.

So even if all relay operators set their advertised bandwidth to their local connection speed, we would still need bandwidth authorities to balance the load between different parts of the Internet.

What is a normal relay load?

It's normal for most relays to be loaded at 30%-80% of their capacity. This is good for clients: an overloaded relay has high latency. (We want enough relays to so that each relay is loaded at 10%. Then Tor would be almost as fast as the wider Internet).

Sometimes, a relay is slow because its processor is slow or its connections are limited. Other times, it is the network that is slow: the relay has bad peering to most other tor relays, or is a long distance away.

Finding Out what is Limiting a Relay

Lots of things can slow down a relay. Here's how to track them down.

System Limits

  • Check RAM, CPU, and socket/file descriptor usage on your relay

Tor logs some of these when it starts. Others can be viewed using top or similar tools.

Provider Limits

  • Check the Internet peering (bandwidth, latency) from your relay's provider to other relays. Relays transiting via Comcast have been slow at times. Relays outside North America and Western Europe are usually slower.

Tor Network Limits

Relay bandwidth can be limited by a relay's own observed bandwidth, or by the directory authorities' measured bandwidth. Here's how to find out which measurement is limiting your relay:

  • Check each of the votes for your relay on consensus-health (large page), and check the median. If your relay is not marked Running by some directory authorities:
    • Does it have the wrong IPv4 or IPv6 address?
    • Is its IPv4 or IPv6 address unreachable from some networks?
    • Are there more than 2 relays on its IPv4 address?

Otherwise, check your relay's observed bandwidth and bandwidth rate (limit). Look up your relay on Metrics. Then mouse over the bandwidth heading to see the observed bandwidth and relay bandwidth rate.

Here is some more detail and some examples: Drop in consensus weight and Rampup speed of Exit relay.

How to fix it

The smallest of these figures is limiting the bandwidth allocated to the relay.

  • If it's the bandwidth rate, increase the BandwidthRate/Burst or RelayBandwidthRate/Burst in your torrc.
  • If it's the observed bandwidth, your relay won't ask for more bandwidth until it sees itself getting faster. You need to work out why it is slow.
  • If it's the median measured bandwidth, your relay looks slow from a majority of bandwidth authorities. You need to work out why they measure it slow.

Doing Your Own Relay Measurements

If your relay thinks it is slow, or the bandwidth authorities think it is slow, you can test the bandwidth yourself:

  • Run a test using tor to see how fast tor can get on your network/CPU.
  • Run a test using tor and chutney to find out how fast tor can get on your CPU. Keep increasing the data volume until the bandwidth stops increasing.

There are two options you can add to your torrc file:

BandwidthRate is the maximum long-term bandwidth allowed (bytes per second). For example, you might want to choose "BandwidthRate 10 MBytes" for 10 megabytes per second (a fast connection), or "BandwidthRate 500 KBytes" for 500 kilobytes per second (a decent cable connection). The minimum BandwidthRate setting is 75 kilobytes per second.

BandwidthBurst is a pool of bytes used to fulfill requests during short periods of traffic above BandwidthRate but still keeps the average over a long period to BandwidthRate. A low Rate but a high Burst enforces a long-term average while still allowing more traffic during peak times if the average hasn't been reached lately. For example, if you choose "BandwidthBurst 500 KBytes" and also use that for your BandwidthRate, then you will never use more than 500 kilobytes per second; but if you choose a higher BandwidthBurst (like 5 MBytes), it will allow more bytes through until the pool is empty.

If you have an asymmetric connection (upload less than download) such as a cable modem, you should set BandwidthRate to less than your smaller bandwidth (Usually that's the upload bandwidth). Otherwise, you could drop many packets during periods of maximum bandwidth usage - you may need to experiment with which values make your connection comfortable. Then set BandwidthBurst to the same as BandwidthRate.

Linux-based Tor nodes have another option at their disposal: they can prioritize Tor traffic below other traffic on their machine, so that their own personal traffic is not impacted by Tor load. A script to do this can be found in the Tor source distribution's contrib directory.

Additionally, there are hibernation options where you can tell Tor to only serve a certain amount of bandwidth per time period (such as 100 GB per month). These are covered in the hibernation entry.

Note that BandwidthRate and BandwidthBurst are in Bytes, not Bits.

In simple words, it works like this:

  • There is a primary ed25519 identity secret key file named "ed25519_master_id_secret_key". This is the most important one, so make sure you keep a backup in a secure place - the file is sensitive and should be protected. Tor could encrypt it for you if you generate it manually and enter a password when asked.
  • A medium term signing key named "ed25519_signing_secret_key" is generated for Tor to use. Also, a certificate is generated named "ed25519_signing_cert" which is signed by the primary identity secret key and confirms that the medium term signing key is valid for a certain period of time. The default validity is 30 days, but this can be customized by setting "SigningKeyLifetime N days|weeks|months" in torrc.
  • There is also a primary public key named "ed25519_master_id_public_key", which is the actual identity of the relay advertised in the network. This one is not sensitive and can be easily computed from "ed5519_master_id_secret_key".

Tor will only need access to the medium term signing key and certificate as long as they are valid, so the primary identity secret key can be kept outside DataDirectory/keys, on a storage media or a different computer. You'll have to manually renew the medium term signing key and certificate before they expire otherwise the Tor process on the relay will exit upon expiration.

This feature is optional, you don't need to use it unless you want to. If you want your relay to run unattended for longer time without having to manually do the medium term signing key renewal on regular basis, best to leave the primary identity secret key in DataDirectory/keys, just make a backup in case you'll need to reinstall it. If you want to use this feature, you can consult our more detailed guide on the topic.

If your relay is relatively new then give it time. Tor decides which relays it uses heuristically based on reports from Bandwidth Authorities. These authorities take measurements of your relay's capacity and, over time, directs more traffic there until it reaches an optimal load. The lifecycle of a new relay is explained in more depth in this blog post. If you've been running a relay for a while and still having issues then try asking on the tor-relays list.

  • Do not use the packages in Ubuntu's repositories. They are not reliably updated. If you use them, you will miss important stability and security fixes.
  • Determine your Ubuntu version by running the following command:
     ‪$ lsb_release -c
  • As root, add the following lines to /etc/apt/sources.list. Replace 'version' with the version you found in the previous step:
     deb https://deb.torproject.org/torproject.org version main
 deb-src https://deb.torproject.org/torproject.org version main
  • Add the gpg key used to sign the packages by running the following commands:
     ‪$ curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | sudo apt-key add -
  • Run the following commands to install tor and check its signatures:
     ‪$ sudo apt-get update
 ‪$ sudo apt-get install tor deb.torproject.org-keyring

On relay search we show an amber dot next to the relay nickname when it is overloaded. This means that one or many of the following load metrics have been triggered:

Note that if a relay reaches an overloaded state we show it for 72 hours after the relay has recovered.

If you notice that your relay is overloaded please:

  1. Check https://status.torproject.org/ for any known issues in the "Tor network" category.

  2. Consider tuning sysctl for your system for network, memory and CPU load.

  3. Consider enabling MetricsPort to understand what is happening.

Tuning sysctl for network, memory and CPU load

TCP port exhaustion

If you are experiencing TCP port exhaustion consider expanding your local port range. You can do that with

# sysctl -w net.ipv4.ip_local_port_range="15000 64000"

or

# echo 15000 64000 > /proc/sys/net/ipv4/ip_local_port_range

Keep in mind that tuning sysctl as described is not permanent and will be lost upon restart. You need to add the configuration to /etc/sysctl.conf or to a file in /etc/sysctl.d/ to make it permanent.

MetricsPort

To understand the well-being of Tor relays and the Tor network it is vital to provide and have access to relay metrics. Relay overload information has been added to relay descriptors since 0.4.6+ but it was not until Tor >= 0.4.7.1-alpha that an interface to the underlying relay metrics was available: the metrics port.

Enabling MetricsPort

Tor provides access to the metrics port via a torrc configuration option called MetricsPort.

It's important to understand that exposing the tor MetricsPort publicly is dangerous for the Tor network users, which is why that port is not enabled by default and its access has to be governed by an access policy. Please take extra precaution and care when opening this port, and close it when you are done debugging.

Let's assume you are the only user on a server that runs a Tor relay. You can enable the metrics port adding this to your torrc file:

MetricsPort 127.0.0.1:9035
MetricsPortPolicy accept 127.0.0.1

And then you will be able to easily retrieve the metrics with:

# curl http://127.0.0.1:9035/metrics

which are by default in a Prometheus format.

Note: every user on that server will be able to access those relay metrics in the example above. In general, set a very strict access policy with MetricsPortPolicy and consider using your operating systems firewall features for defense in depth.

For a more detailed explanation about MetricsPort and MetricsPortPolicy see tor's man page.

MetricsPort output

Here is an example of what output enabling MetricsPort will produce (we omitted any congestion control related metrics as we still need to stabilize that interface):

# HELP tor_relay_connections Total number of opened connections
# TYPE tor_relay_connections gauge
tor_relay_connections{type="OR listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="OR listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="OR listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="OR listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="OR",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="OR",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="OR",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="OR",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Exit",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Exit",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Exit",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Exit",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Socks listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Socks listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Socks listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Socks listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Socks",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Socks",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Socks",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Socks",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Directory listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Directory listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Directory listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Directory listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Directory",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Directory",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Directory",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Directory",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Control listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Control listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Control listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Control listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Control",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Control",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Control",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Control",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Transparent pf/netfilter listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Transparent pf/netfilter listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Transparent pf/netfilter listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Transparent pf/netfilter listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Transparent natd listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Transparent natd listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Transparent natd listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Transparent natd listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="DNS listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="DNS listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="DNS listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="DNS listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Extended OR",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Extended OR",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Extended OR",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Extended OR",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Extended OR listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Extended OR listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Extended OR listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Extended OR listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="HTTP tunnel listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="HTTP tunnel listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="HTTP tunnel listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="HTTP tunnel listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Metrics listener",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Metrics listener",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Metrics listener",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Metrics listener",direction="received",state="opened",family="ipv6"} 0
tor_relay_connections{type="Metrics",direction="initiated",state="opened",family="ipv4"} 0
tor_relay_connections{type="Metrics",direction="initiated",state="opened",family="ipv6"} 0
tor_relay_connections{type="Metrics",direction="received",state="opened",family="ipv4"} 0
tor_relay_connections{type="Metrics",direction="received",state="opened",family="ipv6"} 0
# HELP tor_relay_connections_total Total number of created/rejected connections
# TYPE tor_relay_connections_total counter
tor_relay_connections_total{type="OR listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="OR listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="OR listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="OR listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="OR listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="OR listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="OR",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="OR",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="OR",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="OR",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="OR",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="OR",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Exit",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Exit",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Exit",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Exit",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Exit",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Exit",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Socks listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Socks listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Socks listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Socks listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Socks listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Socks listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Socks",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Socks",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Socks",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Socks",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Socks",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Socks",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Directory listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Directory listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Directory listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Directory listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Directory listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Directory listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Directory",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Directory",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Directory",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Directory",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Directory",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Directory",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Control listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Control listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Control listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Control listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Control listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Control listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Control",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Control",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Control",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Control",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Control",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Control",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Transparent pf/netfilter listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Transparent pf/netfilter listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Transparent pf/netfilter listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Transparent pf/netfilter listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Transparent pf/netfilter listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Transparent pf/netfilter listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Transparent natd listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Transparent natd listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Transparent natd listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Transparent natd listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Transparent natd listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Transparent natd listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="DNS listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="DNS listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="DNS listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="DNS listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="DNS listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="DNS listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Extended OR",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Extended OR",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Extended OR",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Extended OR",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Extended OR",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Extended OR",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Extended OR listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Extended OR listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Extended OR listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Extended OR listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Extended OR listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Extended OR listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="HTTP tunnel listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="HTTP tunnel listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="HTTP tunnel listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="HTTP tunnel listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="HTTP tunnel listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="HTTP tunnel listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Metrics listener",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Metrics listener",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Metrics listener",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Metrics listener",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Metrics listener",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Metrics listener",direction="received",state="rejected",family="ipv6"} 0
tor_relay_connections_total{type="Metrics",direction="initiated",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Metrics",direction="initiated",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Metrics",direction="received",state="created",family="ipv4"} 0
tor_relay_connections_total{type="Metrics",direction="received",state="created",family="ipv6"} 0
tor_relay_connections_total{type="Metrics",direction="received",state="rejected",family="ipv4"} 0
tor_relay_connections_total{type="Metrics",direction="received",state="rejected",family="ipv6"} 0
# HELP tor_relay_flag Relay flags from consensus
# TYPE tor_relay_flag gauge
tor_relay_flag{type="Fast"} 0
tor_relay_flag{type="Exit"} 0
tor_relay_flag{type="Authority"} 0
tor_relay_flag{type="Stable"} 0
tor_relay_flag{type="HSDir"} 0
tor_relay_flag{type="Running"} 0
tor_relay_flag{type="V2Dir"} 0
tor_relay_flag{type="Sybil"} 0
tor_relay_flag{type="Guard"} 0
# HELP tor_relay_circuits_total Total number of circuits
# TYPE tor_relay_circuits_total gauge
tor_relay_circuits_total{state="opened"} 0
# HELP tor_relay_streams_total Total number of streams
# TYPE tor_relay_streams_total counter
tor_relay_streams_total{type="BEGIN"} 0
tor_relay_streams_total{type="BEGIN_DIR"} 0
tor_relay_streams_total{type="RESOLVE"} 0
# HELP tor_relay_traffic_bytes Traffic related counters
# TYPE tor_relay_traffic_bytes counter
tor_relay_traffic_bytes{direction="read"} 0
tor_relay_traffic_bytes{direction="written"} 0
# HELP tor_relay_dos_total Denial of Service defenses related counters
# TYPE tor_relay_dos_total counter
tor_relay_dos_total{type="circuit_rejected"} 0
tor_relay_dos_total{type="circuit_killed_max_cell"} 0
tor_relay_dos_total{type="circuit_killed_max_cell_outq"} 0
tor_relay_dos_total{type="marked_address"} 0
tor_relay_dos_total{type="marked_address_maxq"} 0
tor_relay_dos_total{type="conn_rejected"} 0
tor_relay_dos_total{type="concurrent_conn_rejected"} 0
tor_relay_dos_total{type="single_hop_refused"} 0
tor_relay_dos_total{type="introduce2_rejected"} 0
# HELP tor_relay_load_onionskins_total Total number of onionskins handled
# TYPE tor_relay_load_onionskins_total counter
tor_relay_load_onionskins_total{type="tap",action="processed"} 0
tor_relay_load_onionskins_total{type="tap",action="dropped"} 0
tor_relay_load_onionskins_total{type="fast",action="processed"} 0
tor_relay_load_onionskins_total{type="fast",action="dropped"} 0
tor_relay_load_onionskins_total{type="ntor",action="processed"} 0
tor_relay_load_onionskins_total{type="ntor",action="dropped"} 0
tor_relay_load_onionskins_total{type="ntor_v3",action="processed"} 0
tor_relay_load_onionskins_total{type="ntor_v3",action="dropped"} 0
# HELP tor_relay_exit_dns_query_total Total number of DNS queries done by this relay
# TYPE tor_relay_exit_dns_query_total counter
tor_relay_exit_dns_query_total 0
# HELP tor_relay_exit_dns_error_total Total number of DNS errors encountered by this relay
# TYPE tor_relay_exit_dns_error_total counter
tor_relay_exit_dns_error_total{reason="success"} 0
tor_relay_exit_dns_error_total{reason="format"} 0
tor_relay_exit_dns_error_total{reason="serverfailed"} 0
tor_relay_exit_dns_error_total{reason="notexist"} 0
tor_relay_exit_dns_error_total{reason="notimpl"} 0
tor_relay_exit_dns_error_total{reason="refused"} 0
tor_relay_exit_dns_error_total{reason="truncated"} 0
tor_relay_exit_dns_error_total{reason="unknown"} 0
tor_relay_exit_dns_error_total{reason="tor_timeout"} 0
tor_relay_exit_dns_error_total{reason="shutdown"} 0
tor_relay_exit_dns_error_total{reason="cancel"} 0
tor_relay_exit_dns_error_total{reason="nodata"} 0
# HELP tor_relay_load_oom_bytes_total Total number of bytes the OOM has freed by subsystem
# TYPE tor_relay_load_oom_bytes_total counter
tor_relay_load_oom_bytes_total{subsys="cell"} 0
tor_relay_load_oom_bytes_total{subsys="dns"} 0
tor_relay_load_oom_bytes_total{subsys="geoip"} 0
tor_relay_load_oom_bytes_total{subsys="hsdir"} 0
# HELP tor_relay_load_socket_total Total number of sockets
# TYPE tor_relay_load_socket_total gauge
tor_relay_load_socket_total{state="opened"} 0
tor_relay_load_socket_total 0
# HELP tor_relay_load_tcp_exhaustion_total Total number of times we ran out of TCP ports
# TYPE tor_relay_load_tcp_exhaustion_total counter
tor_relay_load_tcp_exhaustion_total 0
# HELP tor_relay_load_global_rate_limit_reached_total Total number of global connection bucket limit reached
# TYPE tor_relay_load_global_rate_limit_reached_total counter
tor_relay_load_global_rate_limit_reached_total{side="read"} 0
tor_relay_load_global_rate_limit_reached_total{side="write"} 0

Let's find out what some of these lines actually mean:

tor_relay_load_onionskins_total{type="ntor",action="dropped"} 0

When a relay starts seeing "dropped", it is a CPU/RAM problem usually.

Tor is sadly single threaded except for when the "onion skins" are processed. The "onion skins" are the cryptographic work that needs to be done on the famous "onion layers" in every circuits.

When tor processes the layers we use a thread pool and outsource all of that work to that pool. It can happen that this pool starts dropping work due to memory or CPU pressure and this will trigger an overload state.

If your server is running at capacity this will likely be triggered.

The ntor and ntor_v3 values will be the same at the moment which is a bug we need to fix.

tor_relay_exit_dns_error_total{...}

Any counter in the "*_dns_error_total" realm (apart from the one for successful queries) indicates a potential DNS related problem. However, we realized during the 0.4.7 release cycle that DNS errors are way too noisy and contain too many false positives to be useful for overload reporting purposes. We therefore don't use them anymore for that purpose starting with 0.4.6.9 and 0.4.7.4-alpha. However, we still keep DNS metrics around to give the relay operator insight into what is going on with their relay.

DNS timeout issues and errors only apply to Exit nodes.

tor_relay_load_oom_bytes_total{...}

An Out-Of-Memory invocation indicates a RAM problem. The relay might need more RAM or it is leaking memory. If you noticed that the tor process is leaking memory, please report the issue either via Tor gitLab or sending an email to the tor-relays mailing list.

Tor has its own OOM handler and it is invoked when 75%, of the total memory tor thinks is available, is reached. Thus, let say tor thinks it can use 2GB in total then at 1.5GB of memory usage, it will start freeing memory. That is considered an overload state.

To estimate the amount of memory it has available, when tor starts, it will use MaxMemInQueues or, if not set, will look at the total RAM available on the system and apply this algorithm:

    if RAM >= 8GB {
      memory = RAM * 40%
    } else {
      memory = RAM * 75%
    }
    /* Capped. */
    memory = min(memory, 8GB) -> [8GB on 64bit and 2GB on 32bit)
    /* Minimum value. */
    memory = max(250MB, memory)

To avoid an overloaded state we recommend to run a relay above 2GB of RAM on 64bit. 4GB is advised, although of course it doesn't hurt to add more RAM if you can.

One might notice that tor could be called by the OS OOM handler itself. Because tor takes the total memory on the system when it starts, if the overall system has many other applications running using RAM, it ends up eating too much memory. In this case the OS could OOM tor, without tor even noticing memory pressure.

tor_relay_load_socket_total

If the number of opened sockets is close to or the same as total sockets available then this indicates the relay is running out of sockets. The solution is to increase ulimit -n for the tor process.

tor_relay_load_tcp_exhaustion_total

These lines indicate the relay is running out of TCP ports.

Try to tune sysctl as described above.

tor_relay_load_global_rate_limit_reached_total

If this counter is incremented by some noticeable value over a short period of time, the relay is congested. It is likely being used as a Guard by a big onion service or for an ongoing DDoS on the network.

If your relay is still overloaded and you don't know why, please get in touch with network-report@torproject.org. You can encrypt your email using network-report OpenPGP key.

Great. If you want to run several relays to donate more to the network, we're happy with that. But please don't run more than a few dozen on the same network, since part of the goal of the Tor network is dispersal and diversity.

If you do decide to run more than one relay, please set the "MyFamily" config option in the torrc of each relay, listing all the relays (comma-separated) that are under your control:

MyFamily $fingerprint1,$fingerprint2,$fingerprint3

where each fingerprint is the 40 character identity fingerprint (without spaces).

That way, Tor clients will know to avoid using more than one of your relays in a single circuit. You should set MyFamily if you have administrative control of the computers or of their network, even if they're not all in the same geographic location.

For the most in-depth resource on running a relay, see the Relay Setup Guide.

Tor has partial support for IPv6 and we encourage every relay operator to enable IPv6 functionality in their torrc configuration files when IPv6 connectivity is available. For the time being Tor will require IPv4 addresses on relays, you can not run a Tor relay on a host with IPv6 addresses only.

Yes, you do get better anonymity against some attacks.

The simplest example is an attacker who owns a small number of Tor relays. They will see a connection from you, but they won't be able to know whether the connection originated at your computer or was relayed from somebody else.

There are some cases where it doesn't seem to help: if an attacker can watch all of your incoming and outgoing traffic, then it's easy for them to learn which connections were relayed and which started at you. (In this case they still don't know your destinations unless they are watching them too, but you're no better off than if you were an ordinary client.)

There are also some downsides to running a Tor relay. First, while we only have a few hundred relays, the fact that you're running one might signal to an attacker that you place a high value on your anonymity. Second, there are some more esoteric attacks that are not as well-understood or well-tested that involve making use of the knowledge that you're running a relay -- for example, an attacker may be able to "observe" whether you're sending traffic even if they can't actually watch your network, by relaying traffic through your Tor relay and noticing changes in traffic timing.

It is an open research question whether the benefits outweigh the risks. A lot of that depends on the attacks you are most worried about. For most users, we think it's a smart move.

Tor guesses its IP address by asking the computer for its hostname, and then resolving that hostname. Often people have old entries in their /etc/hosts file that point to old IP addresses.

If that doesn't fix it, you should use the "Address" config option to specify the IP you want it to pick. If your computer is behind a NAT and it only has an internal IP address, see the following Support entry on dynamic IP addresses.

Also, if you have many addresses, you might also want to set "OutboundBindAddress" so external connections come from the IP you intend to present to the world.

The accounting options in the torrc file allow you to specify the maximum amount of bytes your relay uses for a time period.

    AccountingStart day week month [day] HH:MM

This specifies when the accounting should reset. For instance, to setup a total amount of bytes served for a week (that resets every Wednesday at 10:00am), you would use:

    AccountingStart week 3 10:00
    AccountingMax 500 GBytes

This specifies the maximum amount of data your relay will send during an accounting period, and the maximum amount of data your relay will receive during an account period. When the accounting period resets (from AccountingStart), then the counters for AccountingMax are reset to 0.

Example: Let's say you want to allow 50 GB of traffic every day in each direction and the accounting should reset at noon each day:

    AccountingStart day 12:00
    AccountingMax 50 GBytes

Note that your relay won't wake up exactly at the beginning of each accounting period. It will keep track of how quickly it used its quota in the last period, and choose a random point in the new interval to wake up. This way we avoid having hundreds of relays working at the beginning of each month but none still up by the end.

If you have only a small amount of bandwidth to donate compared to your connection speed, we recommend you use daily accounting, so you don't end up using your entire monthly quota in the first day. Just divide your monthly amount by 30. You might also consider rate limiting to spread your usefulness over more of the day: if you want to offer X GB in each direction, you could set your RelayBandwidthRate to 20*X KBytes. For example, if you have 50 GB to offer each way, you might set your RelayBandwidthRate to 1000 KBytes: this way your relay will always be useful for at least half of each day.

    AccountingStart day 0:00
    AccountingMax 50 GBytes
    RelayBandwidthRate 1000 KBytes
    RelayBandwidthBurst 5000 KBytes # allow higher bursts but maintain average

For the most in-depth resource on running a relay, see the Relay Setup Guide.

  • The exit relay is the most needed relay type but it also comes with the highest legal exposure and risk (and you should NOT run them from your home).
  • If you are looking to run a relay with minimal effort, fast guard relays are also very useful
  • Followed by bridges.

All outgoing connections must be allowed, so that each relay can communicate with every other relay.

In many jurisdictions, Tor relay operators are legally protected by the same common carrier regulations that prevent internet service providers from being held liable for third-party content that passes through their network. Exit relays that filter some traffic would likely forfeit those protections.

Tor promotes free network access without interference. Exit relays must not filter the traffic that passes through them to the internet. Exit relays found to be filtering traffic will get the BadExit flag once detected.

You're right, for the most part a byte into your Tor relay means a byte out, and vice versa. But there are a few exceptions:

If you open your DirPort, then Tor clients will ask you for a copy of the directory. The request they make (an HTTP GET) is quite small, and the response is sometimes quite large. This probably accounts for most of the difference between your "write" byte count and your "read" byte count.

Another minor exception shows up when you operate as an exit node, and you read a few bytes from an exit connection (for example, an instant messaging or ssh connection) and wrap it up into an entire 512 byte cell for transport through the Tor network.

We're looking for people with reasonably reliable Internet connections, that have at least 10 Mbit/s (Mbps) available bandwidth each way. If that's you, please consider running a Tor relay.

Even if you do not have at least 10 Mbit/s of available bandwidth you can still help the Tor network by running a Tor bridge with obfs4 support. In that case you should have at least 1 MBit/s of available bandwidth.

Great. That's exactly why we implemented exit policies.

Each Tor relay has an exit policy that specifies what sort of outbound connections are allowed or refused from that relay. The exit policies are propagated to Tor clients via the directory, so clients will automatically avoid picking exit relays that would refuse to exit to their intended destination. This way each relay can decide the services, hosts, and networks it wants to allow connections to, based on abuse potential and its own situation. Read the Support entry on issues you might encounter if you use the default exit policy, and then read Mike Perry's tips for running an exit node with minimal harassment.

The default exit policy allows access to many popular services (e.g. web browsing), but restricts some due to abuse potential (e.g. mail) and some since the Tor network can't handle the load (e.g. default file-sharing ports). You can change your exit policy by editing your torrc file. If you want to avoid most if not all abuse potential, set it to "reject *:*". This setting means that your relay will be used for relaying traffic inside the Tor network, but not for connections to external websites or other services.

If you do allow any exit connections, make sure name resolution works (that is, your computer can resolve Internet addresses correctly). If there are any resources that your computer can't reach (for example, you are behind a restrictive firewall or content filter), please explicitly reject them in your exit policy otherwise Tor users will be impacted too.

When upgrading your Tor relay, or moving it on a different computer, the important part is to keep the same identity keys (stored in "keys/ed25519_master_id_secret_key" and "keys/secret_id_key" in your DataDirectory). Keeping backups of the identity keys so you can restore a relay in the future is the recommended way to ensure the reputation of the relay won't be wasted.

This means that if you're upgrading your Tor relay and you keep the same torrc and the same DataDirectory, then the upgrade should just work and your relay will keep using the same key. If you need to pick a new DataDirectory, be sure to copy your old keys/ed25519_master_id_secret_key and keys/secret_id_key over.

If you are a bridge operator, also make sure to copy pt_state/. It contains data required for your bridge to keep working with the same bridge line.

Note: As of Tor 0.2.7 we are using new generation identities for relays based on ed25519 elliptic curve cryptography. Eventually they will replace the old RSA identities, but that will happen in time, to ensure compatibility with older versions. Until then, each relay will have both an ed25519 identity (identity key file: keys/ed25519_master_id_secret_key) and a RSA identity (identity key file: keys/secret_id_key). You need to copy / backup both of them in order to restore your relay, change your DataDirectory or migrate the relay on a new computer.

No. If law enforcement becomes interested in traffic from your exit relay, it's possible that officers will seize your computer. For that reason, it's best not to run your exit relay in your home or using your home internet connection.

Instead, consider running your exit relay in a commercial facility that is supportive of Tor. Have a separate IP address for your exit relay, and don't route your own traffic through it. Of course, you should avoid keeping any sensitive or personal information on the computer hosting your exit relay.

If you're using Debian or Ubuntu especially, there are a number of benefits to installing Tor from the Tor Project's repository.

  • Your ulimit -n gets set to 32768 high enough for Tor to keep open all the connections it needs.
  • A user profile is created just for Tor, so Tor doesn't need to run as root.
  • An init script is included so that Tor runs at boot.
  • Tor runs with --verify-config, so that most problems with your config file get caught.
  • Tor can bind to low level ports, then drop privileges.

If you allow exit connections, some services that people connect to from your relay will connect back to collect more information about you. For example, some IRC servers connect back to your identd port to record which user made the connection. (This doesn't really work for them, because Tor doesn't know this information, but they try anyway.) Also, users exiting from you might attract the attention of other users on the IRC server, website, etc. who want to know more about the host they're relaying through.

Another reason is that groups who scan for open proxies on the Internet have learned that sometimes Tor relays expose their socks port to the world. We recommend that you bind your socksport to local networks only.

In any case, you need to keep up to date with your security. See this article on security for Tor relays for more suggestions.

The default open ports are listed below but keep in mind that, any port or ports can be opened by the relay operator by configuring it in torrc or modifying the source code. The default according to src/or/policies.c (line 85 and line 1901) from the source code release release-0.4.6:

reject 0.0.0.0/8
reject 169.254.0.0/16
reject 127.0.0.0/8
reject 192.168.0.0/16
reject 10.0.0.0/8
reject 172.16.0.0/12

reject *:25
reject *:119
reject *:135-139
reject *:445
reject *:563
reject *:1214
reject *:4661-4666
reject *:6346-6429
reject *:6699
reject *:6881-6999
accept *:*

BridgeDB implements six mechanisms to distribute bridges: HTTPS, Moat, Email, Telegram, Settings and Reserved. Bridge operators can check which mechanism their bridge is using, on the Relay Search. Enter the bridge's <HASHED FINGERPRINT> in the form and click "Search".

Operators can also choose which distribution method their bridge uses. To change the method, modify the BridgeDistribution setting in the torrc file to one of these: https, moat, email, telegram, settings, none, any.

Read more on the Bridges post-install guide.

Tor can handle relays with dynamic IP addresses just fine. Just leave the "Address" line in your torrc blank, and Tor will guess.

The parameters assigned in the AccountingMax and BandwidthRate apply to both client and relay functions of the Tor process. Thus you may find that you are unable to browse as soon as your Tor goes into hibernation, signaled by this entry in the log:

Bandwidth soft limit reached; commencing hibernation.
No new connections will be accepted

The solution is to run two Tor processes - one relay and one client, each with its own config. One way to do this (if you are starting from a working relay setup) is as follows:

  • In the relay Tor torrc file, simply set the SocksPort to 0.
  • Create a new client torrc file from the torrc.sample and ensure it uses a different log file from the relay. One naming convention may be torrc.client and torrc.relay.
  • Modify the Tor client and relay startup scripts to include -f /path/to/correct/torrc.
  • In Linux/BSD/Mac OS X, changing the startup scripts to Tor.client and Tor.relay may make separation of configs easier.

Since it's now a guard, clients are using it less in other positions, but not many clients have rotated their existing guards out to use it as a guard yet. Read more details in this blog post or in Changing of the Guards: A Framework for Understanding and Improving Entry Guard Selection in Tor.

See our obfs4 setup guide to learn how to set up an obfs4 bridge.

You can run a relay in Windows following this tutorials:

You should only run a Windows relay if you can run it 24/7. If you are unable to guarantee that, Snowflake is a better way to contribute your resources to the Tor network.

If your Tor relay is using more memory than you'd like, here are some tips for reducing its footprint:

  • If you're on Linux, you may be encountering memory fragmentation bugs in glibc's malloc implementation. That is, when Tor releases memory back to the system, the pieces of memory are fragmented so they're hard to reuse. The Tor tarball ships with OpenBSD's malloc implementation, which doesn't have as many fragmentation bugs (but the tradeoff is higher CPU load). You can tell Tor to use this malloc implementation instead: ./configure --enable-openbsd-malloc.
  • If you're running a fast relay, meaning you have many TLS connections open, you are probably losing a lot of memory to OpenSSL's internal buffers (38KB+ per socket). We've patched OpenSSL to release unused buffer memory more aggressively. If you update to OpenSSL 1.0.0 or newer, Tor's build process will automatically recognize and use this feature.
  • If you still can't handle the memory load, consider reducing the amount of bandwidth your relay advertises. Advertising less bandwidth means you will attract fewer users, so your relay shouldn't grow as large. See the MaxAdvertisedBandwidth option in the man page.

All of this said, fast Tor relays do use a lot of ram. It is not unusual for a fast exit relay to use 500-1000 MB of memory.

For the most in-depth resource on running a relay, see the Relay Setup Guide.