wiki:TorRelayGuide

Version 143 (modified by cypherpunks, 6 months ago) (diff)

add section about Tor vs. tor

work in progress - see ticket #24497 (please subscribe to that ticket if you want to be involved)

The Ultimate Guide to Running a Relay

Using this guide

This guide includes the best practices that are essential for healthy Tor relays. We've included technical steps, legal considerations, and information about running relays with others. It's organized into three parts:

If you wish to skip directly to setting up a relay, read part two only.

Part one: deciding to run a relay

Why run a Tor relay?

By running a Tor relay you can help make the Tor network:

  • faster (and therefore more usable)
  • more robust against attacks
  • more stable in case of outages
  • safer for its users (spying on more relays is harder than on a few)

Types of nodes in the Tor network

All nodes are important, but they have different technical requirements and legal implications. Understanding the different kinds of nodes is the first step to learning which one is right for you.

Guard/middle (aka non-exit) relay

A guard is the first relay in the chain of 3 relays building a Tor circuit. A middle relay is neither a guard nor an exit, but acts as the second hop between the two. To become a guard, a relay has to be stable and fast (at least 2MByte/s) otherwise it will remain a middle relay. Some non-exit relays can function as either a guard or a middle relay for different users.

Guard and middle relays usually do not receive abuse complaints. All relays will be listed in the public list of Tor relays, so may be blocked by certain services that don't understand how Tor works or deliberately want to censor Tor users. If you are running a relay from home and have one static IP, you may want to consider running a bridge instead so that your non-Tor traffic doesn't get blocked as though it's coming from Tor. If you have a dynamic IP address or multiple static IPs, this isn't as much of an issue.

A non-exit Tor relay requires minimal maintenance efforts and bandwidth usage can be highly customized in the tor configuration (will be covered in more detail later in this guide). The so called "exit policy" of the relay decides if it is a relay allowing clients to exit or not. A non-exit relay does not allow exiting in its exit policy.

Exit relay

The exit relay is the final relay in a Tor circuit, the one that sends traffic out its destination. The services Tor clients are connecting to (website, chat service, email provider, etc) will see the IP address of the exit relay instead of their real IP address of the Tor user.

Exit relays have the greatest legal exposure and liability of all the relays. For example, if a user downloads copyrighted material while using your exit relay, you the operator may receive a DMCA notice. Any abuse complaints about the exit will go directly to you (via your hoster, depending on the WHOIS records). Generally, most complaints can be handled pretty easily through template letters, which we'll discuss more in legal considerations section.

Because of the legal exposure that comes with running an exit relay, you should not run a Tor exit relay from your home. Ideal exit relay operators are affiliated with some institution, like a university, a library, a hackerspace or a privacy related organization. An institution can not only provide greater bandwidth for the exit, but is better positioned to handle abuse complaints or the rare law enforcement inquiry.

If you are considering running an exit relay, please read the section on legal considerations for exit relay operators: TorRelayGuide#Legalconsiderationsforexitrelayoperators.

Bridge

The design of the Tor network means that the IP address of Tor relays is public. However, one of the ways Tor can be blocked by governments or ISPs is by blacklisting the IP addresses of these public Tor nodes. Tor bridges are nodes in the network that are not listed in the public Tor directory, which make it harder for ISPs and governments to block them.

Bridges are useful for Tor users under oppressive regimes or for people who want an extra layer of security because they're worried somebody will recognize that they are contacting a public Tor relay IP address. Several countries, including China and Iran, have found ways to detect and block connections to Tor bridges. Pluggable transports (https://www.torproject.org/docs/pluggable-transports.html.en), a special kind of bridge, address this by adding an additional layer of obfuscation.

Bridges are relatively easy, low-risk and low bandwidth Tor nodes to operate, but they have a big impact on users. A bridge isn't likely to receive any abuse complaints, and since bridges are not listed in the public consensus, they are unlikely to be blocked by popular services. Bridges are a great option if you can only run a Tor node from your home network, have only one static IP, and don't have a huge amount of bandwidth to donate -- we recommend giving your bridge at least 1Mbit/sec.

Relay Requirements

Requirements for Tor relays depend on the type of relay and the bandwidth they provide.

Bandwidth

  • A relay should be able to handle at least 6000 concurrent connections (exit and guard relays even more). This can overwhelm some consumer-level routers. If you run the Tor relay from a server (virtual or dedicated) in a data center you will be fine. If you run it behind a consumer-level router at home you will have to try and see if your home router can handle it or if it starts failing.
  • It is recommended that a relay have at least 16 MBit/s (Mbps) upload bandwidth and 16 MBit/s (Mbps) download bandwidth available for Tor. More is better. The minimum requirements for a relay are 2 MBit/s (Mbps). If you do not know your bandwidth you can use http://beta.speedtest.net to measure it.

Monthly Outbound Traffic

  • It is recommended that a Tor relay be allowed to use a minimum of 100 GByte of outbound traffic (and the same amount of incoming traffic) per month. Note: That is only about 1 day worth of traffic on a 10MBit/s (Mbps) connection. More (>2 TB/month) is better and recommended.

Memory Requirements

  • A <40MBit/s non-exit relay should have at least 512 MB of RAM available.
  • A non-exit relay faster than 40MBit/s should have at least 1 GB of RAM.
  • On an exit relay we recommend at least 1.5 GB of RAM per tor instance.

Disk Storage

Tor does not need much disk storage. A typical Tor relay needs less than 200 MB for Tor related data.

CPU

  • Any modern CPU should be fine.
  • It is recommended to use CPUs with AESNI support (that will improve performance).

How to tell in Linux if your CPU has AES-NI support:
grep aes /proc/cpuinfo

Hardware support first started about 2008.

Uptime

  • Tor has no hard uptime requirement but if your relay is not running for more than 2 hours a day its usefulness is limited. Ideally the relay runs on a server which runs 24/7. Reboots and Tor daemon restarts are fine.

Part two: technical setup

Considerations when choosing a hosting provider

If you have access to a high speed internet connection (>=100MBit/s in both directions) and a physical piece of computer hardware, this is the best way to run a relay. Having full control over the hardware and connection gives you a more controllable and (if done correctly) secure environment. You can host your own physical hardware at home (do NOT run a Tor exit relay from your home) or in a data center. Sometimes this is referred to as installing the relay on "bare metal".

If you do not own physical hardware, you could run a relay on a dedicated server or virtual private server (VPS). This can cost anywhere between $3.00/month and thousands per month, depending on your provider, hardware configuration, and bandwidth usage. Many VPS providers will not allow you to run exit relays, and some will not allow you to run relays at all. You must follow the VPS provider's terms of service, or risk having your account disabled. Not having control over the physical hardware or the host operating system, you are relying on the VPS provider to configure the host machine safely, and not over-subscribe their hardware. You are also relying on the hosting provider for physical security. For more information on ISPs and VPS providers and their policies on allowing Tor relays, please see this guide maintained by the Tor community: https://trac.torproject.org/projects/tor/wiki/doc/GoodBadISPs.

Questions to consider:

  • How much monthly traffic is included? (Is bandwidth "unmetered"?)
  • Does the hoster start to throttle bandwidth after a certain amount of traffic?
  • What virtualization / hypervisor (if any) does the provider use? (anything but OpenVZ should be fine)
  • Does the hoster provide IPv6 connectivity?
  • How well connected is the autonomous system of the hoster? To answer this question you can use the AS rank of the autonomous systems you want to compare: http://as-rank.caida.org/ (a lower value is better).

For Exit Relays

  • Does the hoster allow Tor exit relays?
  • Does the hoster allow custom WHOIS records for your IP addresses? This helps reduce the amount of abuse sent to the hoster instead of you.
  • Does the hoster allow you to set a custom DNS reverse entry? (PTR) This are probably things you will need to ask the hoster in a Pre-Sales ticket.

AS/location diversity

When selecting your hosting provider, consider network diversity on an autonomous system (AS) and country level. A more diverse network is more resilient to attacks and outages. Sometimes it is not clear which AS you are buying from in case of resellers. To be sure it is best to ask the hoster about the AS before ordering a server.

It is best to avoid hosters where many Tor relays are already hosted, but it is still better to add one there than to run no relay at all, eg:

  • OVH SAS (AS16276)
  • Online S.a.s. (AS12876)
  • Hetzner Online GmbH (AS24940)
  • DigitalOcean, LLC (AS14061)

To find out which hoster and countries are already used by many other operators (that should be avoided) you can use Relay Search:

Choosing an Operating System

We recommend you use the operating system you are most familiar with. Please keep in mind that since most relays run on Debian and we want to avoid a monoculture, *BSD based relays are greatly needed. The drawback with *BSD based relays is that they do not support automatic updates for installed packages.

The following table shows the current OS distribution on the Tor network:

No image "OS-comp-table.png" attached to TorRelayGuide

More green cells are better. There is no single OS that has no red cell. The following OSes have a good amount of green cells:

  • HardenedBSD
  • FreeBSD
  • Debian
  • Ubuntu

OS Level Configuration

OS configuration is outside the scope of this guide but the following points are crucial for a Tor relay, so we want to mention them here nonetheless.

Time Synchronization (NTP)

Correct time settings are essential for Tor relays. It is recommended that you use the network time protocol (NTP) for time synchronization and ensure your timezone is set correctly.

Automatic Software Updates

Tor Relay Setup: Installation and Configuration

This section covers the installation and configuration of the program required to run a Tor relay for various operating systems. These steps are intended for the latest stable version of the given OS, on Ubuntu for the latest LTS release.

Note: For some operating systems, there are alpha version packages available (tor versions with new features not deemed to be stable yet). These are only recommended for people eager to test and report bugs in bleeding edge releases/features. If you are looking to run a relay with minimal effort we recommend you stick to stable releases.

In this guide we describe how to setup a new non-exit relay. By reading further you can easily switch to become an exit relay.

Questions you should clarify before configuring Tor:

  • Do you want to run a Tor exit or non-exit (guard/middle) relay?
  • If you want to run an exit relay: Which ports do you want to allow in your exit policy? (more ports usually means potentially more abuse complains)
  • What external TCP port do you want to use for incoming Tor connections? ("ORPort" configuration, we recommend port 443 if that is not used by another daemon on your server already. ORPort 443 is recommended because it is often one of the few open ports on public WIFI networks. Port 9001 is another commonly used ORPort.)
  • What email address will you use in the ContactInfo field of your relay(s)? Note: This information will be made public.
  • How much bandwidth/monthly traffic do you want to allow for Tor traffic?
  • Does the server have an IPv6 address?

The installation commands are shown in code blocks and must be executed with root privileges.

Configuration Management

Tor does not scale well on multi-core machines. If you run a Tor relay on a server with a fast Internet uplink (>200 MBit/s) you might want to consider running multiple Tor instances on a single server. Note: You can only run two Tor instances per public IPv4 address.

If you plan to run more than a single relay, or you want to run a high capacity relay (multiple Tor instances per server) or want to use advanced security features like Offline Master Keys, you may want to use a configuration management for better maintainability.

There are multiple configuration management solutions for Unix based operating systems (Ansible, Puppet, Salt, ...).

The following Ansible Role has specifically been build for Tor relay operators and supports multiple operating systems:

The following bash script for Debian and Ubuntu is not a configuration management but can also help you automate the steps to setup a new single Tor relay. It is meant to be run on a server that is only used for Tor.

Usage of "Tor" and "tor" in this guide

We use "tor" (lower case) whenever we talk specifically about the program tor (the daemon), in all other cases we use "Tor".

CentOS/RHEL

  1. Enable the EPEL repository

To install the "tor" package on CentOS/RHEL, you need to install the EPEL repository first:

yum install epel-release
  1. Install the "tor" package and verify EPEL signing key
    yum install tor
    
    When you install the first package from the EPEL repository you will be asked about verifying the EPEL GPG signing key. Please ensure the key matches with the one available on the Fedora Project website: https://getfedora.org/keys/
  1. Put the tor configuration in place (/etc/tor/torrc):
    #change the nickname "myNiceRelay" to a name that you like
    Nickname myNiceRelay
    ORPort 9001
    SocksPort 0
    ExitRelay 0
    # Change the email address bellow and be aware that it will be published
    ContactInfo tor-operator@your-emailaddress-domain
    
  1. Enable and start your Tor relay:
    systemctl enable tor
    systemctl start tor
    

Debian/Ubuntu

  1. Enable the Torproject package repository

(This can be considered optional on Debian but is not optional on Ubuntu.) Get the repository sources to add to your /etc/apt/sources.list by running the configurator here. Also ensure you import the GPG keys. This will make sure that you're running the latest stable version of tor.

  1. Install the "tor" package
    apt update && apt install tor
    
  1. Put the configuration file /etc/tor/torrc in place:
    #change the nickname "myNiceRelay" to a name that you like
    Nickname myNiceRelay
    ORPort 443
    ExitRelay 0
    SocksPort 0
    ControlSocket 0
    # Change the email address bellow and be aware that it will be published
    ContactInfo tor-operator@your-emailaddress-domain
    
  1. Restart the tor daemon so your configuration changes take effect:
    systemctl restart tor@default
    

Fedora

  1. Install the "tor" package:
    dnf install tor
    
  2. Put the configuration in place (/etc/tor/torrc) - this requires root privileges:
    #change the nickname "myNiceRelay" to a name that you like
    Nickname myNiceRelay
    ORPort 9001
    ExitRelay 0
    # Change the email address bellow and be aware that it will be published
    ContactInfo tor-operator@your-emailaddress-domain
    
  3. Start the tor daemon and make sure it starts at boot:
    systemctl enable tor
    systemctl start tor
    

FreeBSD

  1. Install the "tor" package:
    pkg install tor
    

or for alpha releases:

pkg install tor-devel
  1. Put the configuration file /usr/local/etc/tor/torrc in place.
    #change the nickname "myNiceRelay" to a name that you like
    Nickname myNiceRelay
    ORPort 9001
    ExitRelay 0
    SocksPort 0
    # Change the email address bellow and be aware that it will be published
    ContactInfo tor-operator@your-emailaddress-domain
    Log notice syslog
    
  2. Start the tor daemon and make sure it starts at boot:
    sysrc tor_enable=YES
    service tor start
    

Optional:

To get package updates faster after their release it is best to replace "quarterly" with "latest" in /etc/pkg/FreeBSD.conf.

HardenedBSD

  1. Install the "tor" package:
    pkg install tor
    

or for alpha releases:

pkg install tor-devel
  1. Put the configuration file /usr/local/etc/tor/torrc in place.
    #change the nickname "myNiceRelay" to a name that you like
    Nickname myNiceRelay
    ORPort 9001
    ExitRelay 0
    SocksPort 0
    # Change the email address bellow and be aware that it will be published
    ContactInfo tor-operator@your-emailaddress-domain
    Log notice syslog
    
  1. Start the tor daemon and make sure it starts at boot:
    sysrc tor_enable=YES
    service tor start
    

openSUSE

  1. Install the "tor" package:
    zypper install tor
    
  1. Put the configuration file /etc/tor/torrc in place:
    #change the nickname "myNiceRelay" to a name that you like
    Nickname myNiceRelay
    ORPort 443
    ExitRelay 0
    SocksPort 0
    # Change the Email address bellow and be aware that it will be published
    ContactInfo tor-operator@your-emailaddress-domain
    
  1. Start the tor daemon and make sure it starts at boot:
    systemctl enable tor
    systemctl start tor
    

Verify that your relay works

If your logfile (syslog) contains the following entry after starting your tor daemon your relay should be up and running as expected:

Self-testing indicates your ORPort is reachable from the outside. Excellent. Publishing server descriptor.

About 3 hours after you started your relay it should appear on Relay Search (https://atlas.torproject.org). You can search for your relay using your nickname or IP address.

Getting Help

If you run into problems while setting up your relay you can ask your questions on the public tor-relays mailing list:

Limiting bandwidth usage (and traffic)

Tor will not limit its bandwidth usage by default, but supports multiple ways to restrict the used bandwidth and the amount of traffic. This can be handy if you want to ensure that Tor does not exceed a certain amount of bandwidth or total traffic per day/week/month. The following torrc configuration options can be used to restrict bandwidth and traffic:

Having a fast relay for some time of the month is preferred over a slow relay for the entire month.

IPv6

We encourage everyone to enable IPv6 on their relays for non-relay-to-relay traffic. This is especially valuable on exit and guard relays.

Before enabling your tor daemon to use IPv6 in addition to IPv4 ensure that IPv6 connectivity works from and to your server.

From your server try to ping any IPv6 host:

ping6 google.com

If that worked fine, make your Tor relay reachable via IPv6 by adding an additional ORPort line to your configuration (example for ORPort 9001):

ORPort [IPv6-address]:9001

Note: You have to explicitly specify your IPv6 address in square brackets, you can not tell tor to bind to any IPv6 (like you do for IPv4). If you have a global IPv6 address you should be able to find it in the output of the following command:

ip addr|grep inet6|grep global

If you are an exit relay with IPv6 connectivity, tell your tor daemon to allow exiting via IPv6 so clients can reach IPv6 destinations:

IPv6Exit 1

Note: Tor requires IPv4 connectivity, you can not run a Tor relay on IPv6-only.

Additional information related to IPv6 can be found in the IPv6RelayHowto.

Important if you run more than one Tor instance

To avoid putting Tor clients at risk when operating multiple relays you must set a proper MyFamily value and have a valid ContactInfo in your torrc configuration. The MyFamily setting is simply telling Tor clients what Tor relays are controlled by a single entity/operator/organization, so they don't use them in multiple position in a single circuit.

If you run two relays and they have fingerprints AAAAAAAAAA and BBBBBBBB, you would add the following configuration to set MyFamily:

MyFamily AAAAAAAAAA,BBBBBBBB

to both relays.

Instead of doing so manually for big operators we recommend to automate the MyFamily setting via a TorRelayGuide#ConfigurationManagement solution.

Exit Relay Configuration

The sample configuration above configures a non-exit relay.

To become an exit relay set "ExitRelay 1" in your configuration and define your exit policy. The exit policy defines which destination ports you are willing to forward. This has an impact on the amount of abuse emails you will get (less ports means less abuse emails, but also less useful). If you want to be a useful exit relay you must at least allow destination ports 80 and 443.

Here are some more tips for running a reliable exit relay: https://blog.torproject.org/tips-running-exit-node

DNS on Exit Relays

Unlike other types of relays, exit relays also do DNS resolution for Tor clients. DNS resolution on exit relays is crucial for Tor clients. It is recommended to use a local (on the same host or same LAN segment) recursive DNS resolver. DNS resolution can have a significant impact on the performance your exit relay provides. Poor DNS performance will result in less traffic going through your exit relay.

It is a bad practice to use DNS resolvers from big corporations like Google since they see already a lot of DNS requests from exits or organizations that perform filtering on DNS requests.

There are multiple options for DNS server software, unbound has become a popular one. In every case the software should be installed using the OS package manager to ensure it is updated with the rest of the system.

Tor relay lifecycle

It takes some time for relay traffic to ramp up, this is especially true for guard relays but to a lesser extend also for exit relays. To understand this process, read about the lifecycle of a new relay: https://blog.torproject.org/lifecycle-new-relay.

Maintaining a relay

Setting up outage notifications

Once you setup your relay it will likely run without much work from your side. If something goes wrong it is good to get notified automatically. We recommend you use one of the free services that allow you to check your relay's ORPorts for reachability and send you an email should they become unreachable for what ever reason.

UptimeRobot is one of these services that allow you to monitor TCP listeners on arbitrary ports, should your tor process die you will get an email 5 minutes later. This checks only for the listener but does not speak the Tor protocol.

A good way to monitor a relay for its health state is to have a look at its bandwidth graphs.

System Health Monitoring

To ensure your relay is healthy and not overwhelmed it makes sense to have some basic system monitoring in place to keep an eye on the following metrics:

  • Bandwidth
  • TCP Connections
  • Memory
  • Swap
  • CPU

There are many tools for monitoring this kind of data, munin is one of them and is relatively easy to setup.

Note: Do not make your munin graphs public since this could help attackers with deanonymizing tor users.

Tools

This section list a few tools that you might find handy as a Tor relay operator.

Nyx: Nyx is a Tor Project tool (formerly arm) that allows you to see real time data of your relay.

vnstat: vnstat is a command-line tool that shows the amount of data going through your network connection. You can also use it to generate PNG pictures showing traffic graphs.

vnstat documentation and demo output:

Part three: legal info, social info, and more resources

Legal considerations (for exit relay operators)

Relay operators should understand the potential risks associated with running a relay. For the majority of operators in most countries, bridges and guard/middle relays are very low risk. Exits are the ones that present some legal concerns, but operators under most circumstances will be able to handle legal matters by having an abuse response letter, running the exit from a location that isn't their home, and reading through some of the legal resources that Tor-supportive lawyers have put together.

Legal resources

The EFF Tor Legal FAQ (https://www.torproject.org/eff/tor-legal-faq.html.en) answers many common questions about relay operation and the law. We also like Noisebridge's wiki for additional legal resources: https://www.noisebridge.net/wiki/Noisebridge_Tor/FBI. In general it's a good idea to consult with a lawyer before deciding to operate an exit relay, especially if you live in a place where exit relay operators have been harassed, or if you're the only exit relay operator in your region. Get in touch with your local digital rights organization to see if they have recommendations about legal assistance, and if you're not sure what organizations are working in your region, write to EFF and see if they can help connect you: https://www.eff.org/about/contact.

Responding to abuse complaints

Operators can put together their own abuse complaint template responses from one of many templates that Tor has created: https://trac.torproject.org/projects/tor/wiki/doc/TorAbuseTemplates.

Other docs we like:

Running a relay with other people

Running relays is more fun with other people! You can work with your university department, your employer or institution, or an organization like Torservers.net to run a relay.

Torservers.net

Torservers is an independent, global network of organizations that help the Tor network by running high bandwidth Tor relays. Becoming a Torservers partner is a good way to become more involved in the Tor relay community, and can help you connect with dedicated relay operators around the world for solidarity and support. To start a Torservers partner, the most important thing is to have a group of people (3-5 suggested to start) interested in helping with the various activities required for running relays. There should be mutual trust between the people in the group, and members should commit to running relays for the long term. If you do not know anyone in your social network interested in running relays, one place to meet people is your local hackerspace: https://wiki.hackerspaces.org/Hackerspaces.

Once you have a trusted group of people, depending on your region, it is often advised to create some type of non-profit corporation. This is useful for having a bank account, shared ownership, grant applications, etc. In many countries operating as a corporation instead of as an individual can also get you certain legal protections.

The next steps are figuring out hardware, transit, and server hosting. Depending on your location and connections within the technical community of the area, the last one may be the hardest step. Small local ISPs often have extra bandwidth, and may be interested in supporting your group with some bandwidth or rackspace. It is extremely important to maintain good relationships with these ISPs. Older server hardware can often be found on places like eBay for cheap, but be aware that cheap hardware may be cheap for a reason!

At your university

Many computer science departments, university libraries, and individual students and faculty run relays from university networks. These universities include the Massachusetts Institute of Technology (MIT CSAIL), Boston University, the University of Waterloo, the University of Washington, Northeastern University, Karlstad University, Universitaet Stuttgart, and Friedrich-Alexander University Erlangen-Nuremberg. To learn more about how to get support for a relay on your university's network, check out EFF's resources: https://www.eff.org/torchallenge/tor-on-campus.html.

At your company or organization

If you work at a Tor-friendly company or organization, that's another ideal place to run a relay. Some companies running relays inlcude Brass Horn Communications, Quintex Alliance Consulting, and OmuraVPN. Some organizations running Tor relays include Digital Courage, Access Now, Derechos Digitales, and Lebanon Libraries in New Hampshire.

More resources

Congratulations, you're officially a Tor relay operator! What now?

  • You can check out traffic and other statistics for your relay at our Relay Search: https://atlas.torproject.org/ (your relay will appear on atlas about 3 hours after you started it).

TODO

  • add unbound sample configuration
  • check this doc for consistency of Tor vs. tor
  • remove "work in progress" header
  • make page read-only; accept changes via ticket
  • link to the wiki from https://www.torproject.org/docs/tor-doc-relay.html.en
  • how to report bugs in this guide
  • Tom suggests on the ticket: I'd suggest adding a section under Part 3 about how hosting providers may get annoyed by abuse complaints and demand or shut down relays. Suggest users stay on top of abuse complaints and update the GoodBadISPs list.