Improve documentation for tor relay operators

The documentation is somewhat confusing and incomplete.

irl has been collecting instructions here: https://trac.torproject.org/projects/tor/wiki/OperatorsTips

added component::webpages/website priority::medium resolution::fixed severity::normal status::closed type::defect ux-team labels

Trac:
Cc: N/A to nusenu, ahf

Related: #24442 (moved) (that script sets up auto updates as well)

It's irl who has been collecting instructions on the OperatorsTips wiki page - not me.

Oops, sorry!

Trac:
Cc: nusenu, ahf to nusenu, ahf, irl

Trac:
Description: In our documentation pages that give instructions on how to set up a tor relay, we should explicitly show how to set up auto-update. Over time that will hopefully decrease the number of relays running out-of-date versions that are have security flaws or other bugs.

We can patch the following pages: https://www.torproject.org/docs/tor-relay-debian.html.en https://www.torproject.org/docs/debian.html.en#ubuntu https://www.torproject.org/download/download-unix.html.en

ahf has been collecting instructions here: https://trac.torproject.org/projects/tor/wiki/OperatorsTips

to

In our documentation pages that give instructions on how to set up a tor relay, we should explicitly show how to set up auto-update. Over time that will hopefully decrease the number of relays running out-of-date versions that are have security flaws or other bugs.

We can patch the following pages: https://www.torproject.org/docs/tor-relay-debian.html.en https://www.torproject.org/docs/debian.html.en#ubuntu https://www.torproject.org/download/download-unix.html.en

irl has been collecting instructions here: https://trac.torproject.org/projects/tor/wiki/OperatorsTips

If you agree I'd like to take this as a chance for an overhaul/merge of the pages under https://www.torproject.org/docs/installguide.html.en

Currently these are multiple pages that are about installing and configuring tor but it is not clear whether it is about a tor client or relay. Lets make a tor relay guide and remove or merge existing content?

That could be a single page with

• requirements
• minimal bandwidth
• choosing a suitable location
• AS/location diversity
• installation
• Debian/Ubuntu
• unconditionally use deb.tpo repo
• auto udpate instructions (for tor package only or entire OS?)
• RedHat/CentOS/Fedora
• yum/dnf install tor
• auto update instructions
• Gentoo
• ArchLinux
• FreeBSD/HardeneBSD
• OpenBSD
• MacOS?
• Windows?
• configuration (torrc)
• non-exit relay
• exit relay
• DNS considerations
• maintaining a relay
• setting up outage notifications
• Relay Search
• tor-relays mailing list

Thoughts?

nusenu: So basically these things, plus nyx and Relay Search instructions, was my vision for a relay operator's portal. It should also give information about the mailing lists for relay operators, and perhaps advice on talking to your institution to get them onboard with the idea of running Tor relays. I was also going to produce code snippets to create embeddable graphs for websites so you can show off your Tor relay stats on your blog or whatever.

It may also be good to add ansible-relayor and there was also a talk on doing the same with puppet from SHA 2017: https://program.sha2017.org/events/126.html. If there are Salt modules, that would also be good. Maybe we can make a feature matrix of these, so if someone is not already using a framework they can see what they offer (in terms of support for Tor relays specifically, not just in general).

UX team may have opinions on this.

Trac:
Keywords: N/A deleted, ux-team added

Replying to irl:

nusenu: So basically these things, plus nyx and Relay Search instructions, was my vision for a relay operator's portal.

Can you elaborate what you mean by "relay operator's portal" exactly? different website? new .tpo subdomain?

It should also give information about the mailing lists for relay operators,

+1

and perhaps advice on talking to your institution to get them onboard with the idea of running Tor relays.

What do you mean by "your institution"? the guide should apply to individuals as well, no?

I was also going to produce code snippets to create embeddable graphs for websites so you can show off your Tor relay stats on your blog or whatever.

sounds great.

It may also be good to add ansible-relayor

for obvious reasons I think this is a great idea ;)

and there was also a talk on doing the same with puppet from SHA 2017: https://program.sha2017.org/events/126.html. If there are Salt modules, that would also be good. Maybe we can make a feature matrix of these, so if someone is not already using a framework they can see what they offer (in terms of support for Tor relays specifically, not just in general).

I might be able to find some salt stack tor relay ops but I'm not sure if that is public/maintained.

Replying to nusenu:

Can you elaborate what you mean by "relay operator's portal" exactly? different website? new .tpo subdomain?

Yes, a new subdomain.

What do you mean by "your institution"? the guide should apply to individuals as well, no?

One thing that always stuck with me from the Gentoo documentation was it was kind of "choose your own adventure". The documentation should definitely apply to everyone, but different people have different needs.

By institution I mean your employer, university, college, school, hackerspace, library, coffee shop, local computer repair company, community ISP or just any organisation that would be in a position to run relays.

I guess also we should talk about diversity and why diversity is important, i.e. please don't run your relay on OVH/DO if you have the option to run a relay somewhere else (or run both).

I might be able to find some salt stack tor relay ops but I'm not sure if that is public/maintained.

We'd want to be careful to only include things that are maintained. If something is not public, it's only not public yet and that conversation can be had with the maintainer. It would be important to not end up becoming the maintainer, as Tor people already are busy, but if we end up with new people then that's great.

Another thought, let's also not forget bridges in this.

Are you the maintainer of that new relay portal website? any timeline?

So instead of writing patches to the current page I'll just start with writing text that can then be used on that new website.

I mean, it's an idea that I've had. I don't know if others have had a similar idea.

If no one else wants to maintain it, I could do it as a free time thing. Maybe colin would be interested in helping?

I think there would be two main things to get it started: information architecture (I have a similar bug open for metrics.tpo #24422 (moved)) and producing the copy to go into it.

Trac:
Cc: nusenu, ahf, irl to nusenu, ahf, irl, colin

Replying to irl:

I mean, it's an idea that I've had. I don't know if others have had a similar idea.

If no one else wants to maintain it, I could do it as a free time thing. Maybe colin would be interested in helping?

I'm happy to help with content.

The one that does the puppet module says there is an upcoming release.

https://twitter.com/Stekkz/status/937326993258971136

Also relevant: https://trac.torproject.org/projects/tor/wiki/org/meetings/2017Montreal/Notes/TorRelayOperators

I think my only concern with content is that we make sure not to use English idioms and keep it simple, so that it's translatable later.

For now, let's put content into [[OperatorsTips]] and we can migrate it to a portal later.

#22412 (moved) perhaps also relevant

I'm updating the aim of this ticket so we can continue to discuss all kinds of improvements. I will open a new ticket specifically about auto-update instructions.

Trac:
Description: In our documentation pages that give instructions on how to set up a tor relay, we should explicitly show how to set up auto-update. Over time that will hopefully decrease the number of relays running out-of-date versions that are have security flaws or other bugs.

We can patch the following pages: https://www.torproject.org/docs/tor-relay-debian.html.en https://www.torproject.org/docs/debian.html.en#ubuntu https://www.torproject.org/download/download-unix.html.en

irl has been collecting instructions here: https://trac.torproject.org/projects/tor/wiki/OperatorsTips

to

The documentation is somewhat confusing and incomplete.

irl has been collecting instructions here: https://trac.torproject.org/projects/tor/wiki/OperatorsTips

Summary: Publish tor relay auto-update instructions to Improve documentation for tor relay operators

Replying to nusenu:

So instead of writing patches to the current page I'll just start with writing text that can then be used on that new website.

I like all the ideas suggested here, but I think we should write patches to the existing pages for now and not wait for a new portal. It will be very valuable to get better documentation for operators on the website ASAP. And if we decide to open a new portal, we can always move the latest content there when it is ready.

Our usual approach is to open a separate child ticket for each incremental improvement.

Honestly, I think the existing pages are not worth producing diffs against, we can submit the content as patches to replace those pages but it's more important to collect together good text and have the right information than it is to make microchanges. Especially given the existing structure and mash up of hidden service, client and relay configuration instructions.

For debian based relays: https://github.com/coldhakca/tor-relay-bootstrap/blob/master/bootstrap.sh#L50-L54

apt-get install -y unattended-upgrades apt-listchanges
cp $PWD/etc/apt/apt.conf.d/20auto-upgrades /etc/apt/apt.conf.d/20auto-upgrades
service unattended-upgrades restart