wiki:TorRelayGuide

Version 83 (modified by alison, 5 months ago) (diff)

added some bullet points

work in progress - see ticket #24497

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:

For the tl;dr version of this guide, read only part two.

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 relays in the Tor network

All relays are important, but they have different technical requirements and legal implications. Understanding the different kinds of relays 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 relay, a relay has to be stable and fast (at least 2MByte/s) otherwise it will remain a middle relay. 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. 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: OperatorsTips#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, and 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 6k concurrent connections (exit relays even more). This can overwhelm some consumer-level routers.
  • 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.

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 you should have at least 1 GB of RAM.
  • On an exit relay we recommend to have at least 1 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 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?
  • Does the hoster provide IPv6 connectivity?
  • How well connected is the autonomous system of the hoster?

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 send to the hoster instead of you)
  • Does the hoster allow you to set a custom DNS reverse entry? (PTR)

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. It is best to avoid hosters where many Tor relays are already hosted, 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.

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. We recommend 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.

Note: For some operating systems, tor has alpha packages (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 create 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.)
  • 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 relays 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:

CentOS/RHEL

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

yum install epel-release

then install the "tor" package:

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/

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

Enable and start your Tor relay:

systemctl enable tor
systemctl start tor

Debian/Ubuntu

Automatic Configuration

There is a script for the Debian and Ubuntu OSs which will automatically set up tor and other things like automatic updates, kernel hardening, some sane firewall rules, NTP time server, hardening the SSH server and more. If you are not familiar with setting up a server on the internet, this may be a good way to start. Then continue with the torrc configuration in the Manual Configuration section below.

To use it, set up a Debian or Ubuntu server, SSH into it, switch to the root user, and:

apt-get install -y git
git clone https://github.com/coldhakca/tor-relay-bootstrap.git
cd tor-relay-bootstrap
./bootstrap.sh

Manual Configuration

Get the repo sources to add to your /etc/apt/sources.list by running the configurator here This will make sure that you're running the latest stable version of Tor.

Then run

apt update && apt install tor

as root.

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 443
ExitRelay 0
# Change the email address bellow and be aware that it will be published
ContactInfo tor-operator@your-emailaddress-domain

Restart your Tor relay:

systemctl restart tor@default

Fedora

dnf install tor

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 443
ExitRelay 0
# Change the email address bellow and be aware that it will be published
ContactInfo tor-operator@your-emailaddress-domain

Start your Tor relay and make sure it starts at boot:

systemctl enable tor
systemctl start tor

FreeBSD

Install the "tor" package:

pkg install tor

or for alpha releases:

pkg install tor-devel

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

Example /usr/local/etc/tor/torrc file of a non-exit relay using inbound port 9001:

#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

Start your Tor relay and make sure it starts at boot:

sysrc tor_enable=YES
service tor start

HardenedBSD

Install the "tor" package:

pkg install tor

or for alpha releases:

pkg install tor-devel

Example /usr/local/etc/tor/torrc file of a non-exit relay using inbound port 9001:

#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

Start your Tor relay and make sure it starts at boot:

sysrc tor_enable=YES
service tor start

openSUSE

Install the "tor" package:

zypper install tor

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 443
ExitRelay 0
# Change the Email address bellow and be aware that it will be published
ContactInfo tor-operator@your-emailaddress-domain

Start your Tor relay and make sure it starts at boot:

systemctl enable tor
systemctl start tor

Exit Relay Configuration

The sample configuration above configures a non-exit relay.

To become an exit relay you have to remove the "ExitRelay 0" line from you configuration and define your exit policy.

Here are some more tips for running an exit relay with minimal difficulty: https://blog.torproject.org/tips-running-exit-node

DNS on Exit Relays

IPv6

We encourage everyone to enable IPv6 on their relays for non-relay-to-relay traffic. This is currently 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:

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 the IPv6 address, you can not tell tor to bind to any IPv6 (like you do for IPv4).

If you are an exit relay with IPv6 connectivity, tell your exit relay to allow exiting via IPv6:

IPv6Exit 1

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

Tor relay lifecycle

It takes some time for the traffic directed to new guard/middle relay to ramp up. 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.

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

System Health Monitoring

  • Bandwidth
  • 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

Nyx: Nyx is a Tor Project tool (formerly arm) that allows you to monitor your relay. Explanation and download are here

vnstat: vnstat is a command-line tool that shows the amount of data going through your network connection. It is included in your linux distro.

Installed and used thus:

Debian, Ubuntu: apt install vnstat
RedHat,CentOS: yum install vnstat
Fedora: dnf install vnstat
To set up the vnstat database, use: sudo vnstat --create -i <usually eth0>
Wait a day to get something populated.
Some useful vnstat commands: vnstat -d (daily totals), vnstat -m (monthly totals)

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.

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