Opened 5 months ago

Closed 3 months ago

#24497 closed defect (fixed)

Improve documentation for tor relay operators

Reported by: arthuredelstein Owned by:
Priority: Medium Milestone:
Component: Webpages/Website Version:
Severity: Normal Keywords: ux-team
Cc: nusenu, ahf, irl, colin, alison, steph@…, phoul, tor@…, tom, pastly, shawn.webb@… Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description (last modified by arthuredelstein)

The documentation is somewhat confusing and incomplete.

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

Child Tickets

TicketStatusOwnerSummaryComponent
#24505closedPublish tor relay auto-update instructionsWebpages/Website
#24526closednickmMake it clear that multi-relay operators are expected to set a working ContactInfo and proper MyFamilyCore Tor/Tor

Change History (67)

comment:1 Changed 5 months ago by arthuredelstein

Cc: nusenu ahf added

comment:2 Changed 5 months ago by cypherpunks

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

comment:3 Changed 5 months ago by ahf

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

comment:4 Changed 5 months ago by arthuredelstein

Cc: irl added

Oops, sorry!

comment:5 Changed 5 months ago by arthuredelstein

Description: modified (diff)

comment:6 Changed 5 months ago by nusenu

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?

Last edited 5 months ago by nusenu (previous) (diff)

comment:7 Changed 5 months ago by irl

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).

comment:8 Changed 5 months ago by irl

Keywords: ux-team added

UX team may have opinions on this.

comment:9 in reply to:  7 ; Changed 5 months ago by nusenu

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.

comment:10 in reply to:  9 ; Changed 5 months ago by irl

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.

comment:11 Changed 5 months ago by nusenu

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.

Last edited 5 months ago by nusenu (previous) (diff)

comment:12 Changed 5 months ago by irl

Cc: colin added

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) and producing the copy to go into it.

comment:13 in reply to:  12 Changed 5 months ago by nusenu

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.

comment:14 Changed 5 months ago by irl

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.

comment:15 Changed 5 months ago by irl

#22412 perhaps also relevant

comment:16 Changed 5 months ago by arthuredelstein

Description: modified (diff)
Summary: Publish tor relay auto-update instructionsImprove documentation for tor relay operators

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.

comment:17 in reply to:  11 Changed 5 months ago by arthuredelstein

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.

comment:18 Changed 5 months ago by irl

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.

comment:19 Changed 5 months ago by cypherpunks

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

comment:20 Changed 5 months ago by cypherpunks

cross referencing #24526

comment:21 in reply to:  10 Changed 5 months ago by irl

Replying to nusenu:

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

This content may in fact go into community.torproject.org once that portal is built, meaning that we don't have to create a whole new portal.

comment:22 Changed 5 months ago by alison

Cc: alison added

folks, Phoul and I have been working on something just like this! I love synergy!

ours started as a blog post but has quickly transformed into more of a guide to supplement the relay stuff here: https://www.torproject.org/docs/manual.html.en.

check out the draft (I have another copy in case anyone makes malicious edits): https://pad.riseup.net/p/relay-ops-guide-backup

we've hit most of what nusenu outlined as important above (and I made a couple of notes about the things that are missing).

our plan was to publish it on the wiki for now, then make a blog post announcing it (the blog post is the first few paragraphs on that pad). eventually, this content (and other relay operator resources) will be part of community.torproject.org (as part of the website redesign)

I think we should still do that, with some slight tweaks:

  • maybe the folks cced on this ticket can take a look at the draft that we have and identify any points for improvement
  • then we migrate the text over to the wiki page that irl created
  • then we publish the blog post announcing it, letting folks know the plan for community.tpo, and asking for feedback on the wiki text
  • when the ux team starts building community.tpo, then we'll have our relay operators' content ready to go, and we can kill the old incomplete manuals

comment:23 Changed 5 months ago by cypherpunks

I wanted to start the transition from

https://pad.riseup.net/p/relay-ops-guide-backup

to
https://trac.torproject.org/projects/tor/wiki/OperatorsTips

and start with fixing the the heading / formatting but as usual:

Submission rejected as potential spam

Maximum number of external links per post exceeded

comment:24 in reply to:  22 ; Changed 5 months ago by arthuredelstein

Replying to alison:

folks, Phoul and I have been working on something just like this! I love synergy!

Awesome!

  • maybe the folks cced on this ticket can take a look at the draft that we have and identify any points for improvement

I think the Debian page on Unattended Upgrades is unnecessarily complex. I would suggest putting the minimal sequence of commands that users can enter at the command line to set up unattended upgrades.

comment:25 Changed 5 months ago by cypherpunks

We're going to show you how to proceed with Debian.

The guide should try to avoid favoring Debian, this is why I listed all these OSes in my list above.

comment:26 in reply to:  24 ; Changed 5 months ago by cypherpunks

Replying to arthuredelstein:

Replying to alison:

folks, Phoul and I have been working on something just like this! I love synergy!

Awesome!

  • maybe the folks cced on this ticket can take a look at the draft that we have and identify any points for improvement

I think the Debian page on Unattended Upgrades is unnecessarily complex. I would suggest putting the minimal sequence of commands that users can enter at the command line to set up unattended upgrades.

I agree and generally speaking the current version points to a lot of third party content, we should try to avoid that and have the content directly on the page as much as possible.

comment:27 in reply to:  25 Changed 5 months ago by phoul

Replying to cypherpunks:

We're going to show you how to proceed with Debian.

The guide should try to avoid favoring Debian, this is why I listed all these OSes in my list above.

This was originally written as a blog post, and in the interest of not having a book of a blog post we decided to focus on Debian. Since we are going with a guide, expanding the OS coverage would make sense.

That said, depending on how wide we want to expand it, we should find people who are happy to be "in-charge" of keeping their preferred OS instructions up to date. While there are a lot of people who could install Gentoo / Arch / etc.. and write up instructions, if these are not systems people run day-to-day, they may not be aware when things change and the instructions no longer work.

Last edited 5 months ago by phoul (previous) (diff)

comment:28 in reply to:  26 Changed 5 months ago by phoul

Replying to cypherpunks:

I agree and generally speaking the current version points to a lot of third party content, we should try to avoid that and have the content directly on the page as much as possible.

As I mentioned in my previous comment, we removed a lot of things from being in-line in the guide due to this originally being a blog post. Once we migrate it to the wiki (or before), we can pull that content back into the guide proper.

comment:29 Changed 5 months ago by alison

I've begun migrating content from our draft blog post to here: https://trac.torproject.org/projects/tor/wiki/OperatorsTips

I started with nusenu's proposed outline and added some additional headings. Feel free to make formatting changes for ease of reading. Change the text if you want, too. Change anything!

We should definitely move the linked content onto their own wiki pages (even things like blog posts and other content from tpo.org, because the website will be overhauled and we don't want to lose anything). I haven't done that yet in the content that I moved over.

Edit: another idea is that we should have a table of contents, like the support wiki https://trac.torproject.org/projects/tor/wiki/org/teams/CommunityTeam/Support

I plan to work on migrating more of this today.

Last edited 5 months ago by alison (previous) (diff)

comment:30 in reply to:  29 ; Changed 5 months ago by cypherpunks

That said, depending on how wide we want to expand it, we should find people who are happy to be "in-charge" of keeping their preferred OS instructions up to date. While there are a lot of people who could install Gentoo / Arch / etc.. and write up instructions, if these are not systems people run day-to-day, they may not be aware when things change and the instructions no longer work.

I'm happy to be "in-charge" of keeping things maintained for all OSes that I have to keep an eye for ansible-relayor already. I discovered there is one more OS that has apparently a well maintained tor package that is not on the list, I might add that.

I also started to work on an OS table that shows what things (related to tor) are available or not for a given OS (or the tor package in that given OS).

Replying to alison:

Edit: another idea is that we should have a table of contents, like the support wiki https://trac.torproject.org/projects/tor/wiki/org/teams/CommunityTeam/Support

Yes, a ToC is a IMO a must-have (when this content reaches a proper website).

I plan to work on migrating more of this today.

I'm waiting for you to finish migrating content, once you are done I'll start working on that wiki page.

Last edited 5 months ago by cypherpunks (previous) (diff)

comment:31 Changed 5 months ago by steph

Cc: steph@… added

comment:32 in reply to:  30 ; Changed 5 months ago by alison

I plan to work on migrating more of this today.

I'm waiting for you to finish migrating content, once you are done I'll start working on that wiki page.

I migrated everything from our original post. Some things to note:

  • My original plan to move away from all externally linked content has not happened. Lots of the links have images and additional links, so I couldn't easily create new trac pages. So maybe we should do that part more gradually.
  • I have not migrated the iptables rules because there is a conversation happening on the pad about them.
  • I noted some of the places that I plan to add to over the weekend, but others should feel free to edit away!
  • Edit: I also did not create a table of contents yet.
Last edited 5 months ago by alison (previous) (diff)

comment:33 in reply to:  32 Changed 5 months ago by cypherpunks

Replying to alison:

I migrated everything from our original post. Some things to note:

  • My original plan to move away from all externally linked content has not happened. Lots of the links have images and additional links, so I couldn't easily create new trac pages. So maybe we should do that part more gradually.
  • I have not migrated the iptables rules because there is a conversation happening on the pad about them.

The pad is probably not suitable for discussions, lets use tor-dev@ or discuss directly here on the trac ticket (I'd prefer email over a website).

Points I'd like mention here so people can say something if they disagree:

  • target audience of the guide: people that do not fear the command line and have some minimal Linux or BSD experience
  • target servers:
    • the guide should work for servers not exclusively used for Tor, so if someone has a webserver with lots of bw and wants to help, this guide should work for them
    • for exit relays this is a very different matter: In my opinion you should NOT run an exit relay on a shared server (although I'm aware that a big operator does) - this (exclusive servers for exits) will be clearly stated in the guide.

comment:34 Changed 5 months ago by cypherpunks

I made some progress on the page. I'll continue and report back once I'm satisfied.
I tried to rename the page put moving it caused the usual spam protection error (the current page name is not what it is actually about).

I finalized the list of OS's I'll maintain (I might drop openSUSE depending on some upstream ticket with them).
If you feel like there is an important OS missing please add it (you would be the "maintainer" for that one then.
I dropped OpenBSD due to missing package updates.

Once the guide is done I'll implement the steps in ansible and run it against the target OS every once a while to see if it still works as documented.

comment:35 Changed 4 months ago by phoul

Cc: phoul added

comment:36 Changed 4 months ago by alison

Hi everyone,

The wiki is really starting to look great! I did some work getting things organized and made some other language and editing fixes.

Can folks take a look at the TODO and try to reconcile some of those open issues? And also read the whole thing over for readability? I will be doing more of both over the next few days.

comment:37 Changed 4 months ago by cypherpunks

Thanks for your fixes.

  • about your bw limit change (2MBit/s): since you added that I increased the recommended to 16MBit/s so they meet the requirements for guards
  • for tools outside the core scope of this guide (like vnstat) I'd like to avoid having anything in this guide that goes into much detail, example this change:

https://trac.torproject.org/projects/tor/wiki/OperatorsTips?sfp_email=&sfph_mail=&action=diff&version=63&old_version=62&sfp_email=&sfph_mail=
that adds the commands for installing vnstat on multiple operating systems. Do we want that? I would be in favor of removing it (but yes, vnstat is great!)

  • about this change:

https://trac.torproject.org/projects/tor/wiki/OperatorsTips?sfp_email=&sfph_mail=&action=diff&version=68&old_version=67&sfp_email=&sfph_mail=

since the entire guide covers every OS identically (until this change happened) - I wanted to challenge that change since it breaks

  • also: that bash script does not appear to be signed?
  • I have an OS comparison table: it started as something like https://trac.torproject.org/projects/tor/wiki/doc/packages but I didn't want to maintain that HTML table manually. All I have now would be a static png, but that is not editable by anyone but me, not sure if I should add it to the guide
  • one important topic is DNS - I'd like to fill it with content

comment:38 Changed 4 months ago by alison

Hi all,

Did a little more work on this today, resolving some of the TODO items and making further edits for readability.

I'd love if we could finish the outstanding TODO items and publish a blog post announcing this (and getting our community excited for the future community.torproject.org portal where this will eventually live) in the first week of January.

I realize that I'm saying this on the last workday before TPI takes a weeklong break. :) But it would be great to get this finished that first week back. I'm gonna follow up with a few people on this ticket over email too.

Thanks everyone for all your work on this!

comment:39 Changed 4 months ago by cypherpunks

(context: Alison sent an email on this topic, this was my reply - so it is documented here)


I'll paste this email to #24497 once trac works again.

thanks for your email and pushing this forward.

Unfortunately trac appears to have some troubles currently
("Service Unavailable" every now and then).

Since no one objected so far (since 2017-12-19) I'll proceed with what I proposed on #24497.
(please speak up of you disagree with anything proposed on #24497)

In addition:

  • lets not depend on: (which is currently the case)

https://www.torproject.org/docs/debian.html.en
I assume the new content will replace - not extend - it.

  • What is actually used to build/run community.tpo? (some known platform/cms?)

(I'm asking to find out if it would support that sources.list "generator")
And does your timeline (blog post in first week of 2018) mean community.tpo is online by then?

Just a short info on what I'll take care of - from the todo list (and complete before 2018-01-04
likely earlier):

add OS comparison table
add DNS on exit relays
add setting up outage notifications
add https://trac.torproject.org/projects/tor/wiki/OperatorsTips/DebianUbuntuUpdates

add Puppet to configuration management [we already have an Ansible role; is it necessary to have both?]

irl wanted to have more than one configuration management and I agree with him but only if it is maintained,
for at least 2 more years.

Ideally some tpo person would review these external contributions, but I doubt that will happen
before you plan to publish.

clarify meaning of Tor vs tor (near the top), and check this doc for consistency

I used "tor" where I was referring to the program and Tor everywhere else.

make page read-only; accept changes via ticket

Who will take care of implementing changes after you turned into a read-only page?
(I'll certainly be someone that proposes updates)

Don't feel you have to reply to this email, lets keep the discussion on #24497.


This email got two replies (one from Arthur and Alison). I'll let them decide themselves if they want to paste their replies here as well.

comment:40 Changed 4 months ago by cypherpunks

Hi Alison, I reviewed your changes and noticed this change:
https://trac.torproject.org/projects/tor/wiki/OperatorsTips?action=diff&version=87

was:

This is **currently** especially valuable on exit and guard relays.

is:

This is especially valuable on exit and guard relays.

The original sentence contained currently because once tor supports IPv6 for relay-to-relay traffic this sentence is no longer valid.

comment:41 Changed 4 months ago by cypherpunks

Hi Alison,

I'll remove the iptables section
https://trac.torproject.org/projects/tor/wiki/OperatorsTips?action=diff&version=89

reasoning:

  • let's keep packet filtering out of scope for this guide (I will mention that the tor ports need to be accessible/ should not be blocked.)
  • the iptables ruleset make assumptions on ORPort/DirPort/SSH port that are not consistent with the rest of the guide
  • we should not assume that people only run the tor service on their servers
  • if we have iptables we would also have to add pf for non-Linux systems
  • it is OS specific but it is not in an OS specific section

Please raise any objections you might have.

Last edited 4 months ago by cypherpunks (previous) (diff)

comment:42 Changed 4 months ago by cypherpunks

Important: please rename the wiki page from OperatorsTips to "TorRelayGuide"
before publishing the blog

comment:43 Changed 4 months ago by antonela

Cc: tor@… added

comment:44 Changed 4 months ago by alison

Here is the reply I sent to nusenu on the brief thread we had when trac was down:

On 12/22/2017 04:47 PM, nusenu wrote:

Hello Alison,

(I added Arthur since he opened the trac entry in the first place)

I'll paste this email to #24497 once trac works again.

Really it's perfect that trac went down so that we're all forced to take a real holiday. :)

thanks for your email and pushing this forward.

Thank you for all the work you did on it.

Unfortunately trac appears to have some troubles currently
("Service Unavailable" every now and then).

Since no one objected so far (since 2017-12-19) I'll proceed with what I proposed on #24497.
(please speak up of you disagree with anything proposed on #24497)

In addition:

  • lets not depend on: (which is currently the case)

https://www.torproject.org/docs/debian.html.en
I assume the new content will replace - not extend - it.

Right, we should make the content at that address live on the wiki somewhere. I made a note of it to fix when trac comes back online.

In Arthur's reply he suggested that we mirror the wiki on the website in order to keep it updated more easily and I think that sounds good.

  • What is actually used to build/run community.tpo? (some known platform/cms?)

(I'm asking to find out if it would support that sources.list "generator")

So there' s a ticket for website redesign that can get you up to speed when trac comes back: https://trac.torproject.org/projects/tor/ticket/21222

The main piece of the website redesign (which, in addition to being a redesign of what we already have, will include this brand new thing) that is being worked on right now is support.torproject.org. That is being built in Lektor, which is a static website generator that also works as a CMS. I am not sure if that's what will be used on community.tpo, but if we want to know we can add hiro to this thread.

And does your timeline (blog post in first week of 2018) mean community.tpo is online by then?

No, community.tpo won't be online then, it's gonna take some time. Without looking at the UX team roadmap (gee we sure do rely on trac for a lot) I believe that dev.tpo is gonna go after support.tpo. In any case, we are some time away from the community portal getting built. Meanwhile, we get a lot of questions through frontdesk@… asking for our relay resources to be better/easier/more complete, so I figure why not get the information out there to people now. Also, Phoul and I originally were thinking about a blog post to encourage relay operators before it merged with Arthur's ticket and irl's wiki page (synergy), so we're still thinking along that timeline.

That said, if we want to mirror the wiki on the website, I'll change the blog post to just be something about how we recognized that these docs were wanting, and we made them better. And then I can say, stay tuned for this even better thing, community.tpo, which will have resources for relay operators and trainers and advocates and all the other neighbors and friends in Oniontown. And we can make sure to ask for feedback on the relay operator guide.

Just a short info on what I'll take care of - from the todo list (and complete before 2018-01-04
likely earlier):

add OS comparison table
add DNS on exit relays
add setting up outage notifications
add https://trac.torproject.org/projects/tor/wiki/OperatorsTips/DebianUbuntuUpdates

Thank you!!!

add Puppet to configuration management [we already have an Ansible role; is it necessary to have both?]

irl wanted to have more than one configuration management and I agree with him but only if it is maintained,
for at least 2 more years.

Ideally some tpo person would review these external contributions, but I doubt that will happen
before you plan to publish.

Good point...we should do that, or at least note that they haven't been reviewed.

clarify meaning of Tor vs tor (near the top), and check this doc for consistency

I used "tor" where I was referring to the program and Tor everywhere else.

Thanks for being consistent. This item is just noting that someone should go through and make sure that *everyone* who contributed did that. And then also define it for people using the document

remove "work in progress" header
make page read-only; accept changes via ticket

Who will take care of implementing changes after you turned into a read-only page?
(I'll certainly be someone that proposes updates)

We did this with the support wiki to avoid malicious or unhelpful drive-bys. Anyone with an admin account on trac can edit read-only pages, but you (and Arthur) are right that it's not the best for participation and if we choose to mirror the wiki on the website instead it'll be easier for contributors.

Don't feel you have to reply to this email, lets keep the discussion on #24497.

I would love to but trac is still down. I will update the ticket when trac comes back! Glad we had this email convo too.

comment:45 in reply to:  40 Changed 4 months ago by alison

Replying to cypherpunks:

Hi Alison, I reviewed your changes and noticed this change:
https://trac.torproject.org/projects/tor/wiki/OperatorsTips?action=diff&version=87

was:

This is **currently** especially valuable on exit and guard relays.

is:

This is especially valuable on exit and guard relays.

The original sentence contained currently because once tor supports IPv6 for relay-to-relay traffic this sentence is no longer valid.

I removed "currently" because I don't think it's a good practice to make unspecific references to time in docs. I think it would be good to add a line clarifying that this will no longer be true once Tor supports IPv6 for relay-to-relay traffic.

comment:46 in reply to:  42 Changed 4 months ago by alison

Replying to cypherpunks:

Important: please rename the wiki page from OperatorsTips to "TorRelayGuide"
before publishing the blog

done!

comment:47 Changed 4 months ago by tom

Cc: tom added

comment:48 Changed 4 months ago by tom

See also #18356

comment:49 Changed 4 months ago by cypherpunks

I made some more progress on the guide. The setup instructions for each OS are also tested now.

  • I'd like to change the title from "The Ultimate Guide to Running a Relay" to "The Tor Relay Guide". Any opinions on that?
  • I'd would like to make the page readonly for the first 3 days after you announce it on twitter and/or blog
  • I'd like to have a subcomponent on trac for this guide, is that feasible?
  • I considered iptables/PF out of scope
  • I'll send an email to tor-dev and ask for reviews and feedback

I'm not sure how detailed the part for unbound on all OSes should be, I'll find out in the upcoming days.

Last edited 4 months ago by cypherpunks (previous) (diff)

comment:50 Changed 4 months ago by pastly

Cc: pastly added

comment:51 in reply to:  49 ; Changed 4 months ago by pastly

Replying to cypherpunks:

  • I'd like to change the title from "The Ultimate Guide to Running a Relay" to "The Tor Relay Guide". Any opinions on that?

Good idea. Sounds much more professional and less like Joe's-blog-post-from-5-years-ago-that-is-never-updated.

  • I'd would like to make the page readonly for the first 3 days after you announce it on twitter and/or blog

Good idea.

  • I considered iptables/PF out of scope

Me too.

Thanks to everyone who has put work into this so far.

comment:52 Changed 4 months ago by tom

Comments:

  • I think there should be good, explicit instructions for pluggable transports. I *think* non-PT bridges are not that useful these days? But setting up obfs4 is not as easy as setting up tor. (Again, see #18356)
  • Under relay Requirements, it generally lacks actionable information for users. For example: "A relay should be able to handle at least 6k concurrent connections (exit relays even more). This can overwhelm some consumer-level routers." - is there something a user can do to check this? It doesn't say anything about "If you run it from a normal computer or VPS you'll be fine" or anything like that. How would a user check their upload/download speed?
  • "How well connected is the autonomous system of the hoster?" - I have never considered this. I don't even know how I would go about investigating it.
  • "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)" - these are probably things you'll need to ask in a Pre-Sales ticket.
  • "It is best to avoid hosters where many Tor relays are already hosted" - is it better to run no relays, or relays in already-saturated ASes?
  • 'Please keep in mind that since most relays run on Debian and we want to avoid a monoculture, *BSD based relays are greatly needed.' - what about everything that isn't Debian/Ubuntu? Like Mac, Windows, Gentoo, Fedora, CentOS....
  • "A common question with regards to these settings is: "Is it more useful to use available monthly traffic in a short amount of time (fast bandwidth) or is it better to have a slow relay running all the time?" In most cases the former is preferred and recommended. " - Please rephrase this paragraph to be a single statement rather than a lead-in, question, and then difficult to parse answer.
  • "Note: You have to explicitly specify the IPv6 address" - how does one find their IPv6 address?
  • " There are multiple options for DNS server software, unbound has become a popular one." - I'd add a note that the OS' package manager should allow you to install a DNS resolver, such as unbound, dnsmasq, or foo.
  • It takes some time for the traffic directed to new guard/middle relay to ramp up. - exit too, no?
  • 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.
  • Also to not be a dick about your Tor relay. You are a reflection of the Tor project, and being a dick reflects very badly on us.
  • https://www.torproject.org/getinvolved/tshirt.html says 3 but lists 2

comment:53 in reply to:  51 ; Changed 4 months ago by steph

Replying to pastly:

Replying to cypherpunks:

  • I'd like to change the title from "The Ultimate Guide to Running a Relay" to "The Tor Relay Guide". Any opinions on that?

Good idea. Sounds much more professional and less like Joe's-blog-post-from-5-years-ago-that-is-never-updated.

  • I'd would like to make the page readonly for the first 3 days after you announce it on twitter and/or blog

Good idea.

I don't think "The Tor Relay Guide" is descriptive enough. It's not all about relays, it's about running a relay. We added "Ultimate" because there are so many other resources that had to be pulled from in order to create this, so ultimate signals this is the place to come to see them all.

  • I considered iptables/PF out of scope

Me too.

Thanks to everyone who has put work into this so far.

comment:54 Changed 4 months ago by cypherpunks

Hi pastly,

since I specifically used ORPort 443 where it works out of the box I'm wondering about the
motivation for your change to 9001:
https://trac.torproject.org/projects/tor/wiki/TorRelayGuide?sfp_email=&sfph_mail=&action=diff&version=137&old_version=136&sfp_email=&sfph_mail=

comment:55 in reply to:  52 Changed 4 months ago by cypherpunks

Tom, thanks for your valuable feedback!

Replying to tom:

  • Under relay Requirements, it generally lacks actionable information for users. For example: "A relay should be able to handle at least 6k concurrent connections (exit relays even more). This can overwhelm some consumer-level routers." - is there something a user can do to check this? It doesn't say anything about "If you run it from a normal computer or VPS you'll be fine" or anything like that. How would a user check their upload/download speed?

I added a variant of your sentence and info on how to measure bw.

  • "How well connected is the autonomous system of the hoster?" - I have never considered this. I don't even know how I would go about investigating it.

I added information on how to compare to ASes (CAIDA).

  • "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)" - these are probably things you'll need to ask in a Pre-Sales ticket.

added.

  • "It is best to avoid hosters where many Tor relays are already hosted" - is it better to run no relays, or relays in already-saturated ASes?

added.

  • 'Please keep in mind that since most relays run on Debian and we want to avoid a monoculture, *BSD based relays are greatly needed.' - what about everything that isn't Debian/Ubuntu? Like Mac, Windows, Gentoo, Fedora, CentOS....

Gentoo, Fedora, CentOS are also Linux so maybe lets try to have some other kernel?
I'd say Windows relays are not well supported by the Torproject.

  • "A common question with regards to these settings is: "Is it more useful to use available monthly traffic in a short amount of time (fast bandwidth) or is it better to have a slow relay running all the time?" In most cases the former is preferred and recommended. " - Please rephrase this paragraph to be a single statement rather than a lead-in, question, and then difficult to parse answer.

I hope it is better now?

  • "Note: You have to explicitly specify the IPv6 address" - how does one find their IPv6 address?

added.

  • " There are multiple options for DNS server software, unbound has become a popular one." - I'd add a note that the OS' package manager should allow you to install a DNS resolver, such as unbound, dnsmasq, or foo.

I added "In every case the software should be installed using the OS package manager to ensure it is updated with the rest of the system."

not sure if this is what you were trying to say.

  • It takes some time for the traffic directed to new guard/middle relay to ramp up. - exit too, no?

changed to:
"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"

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

note to self: TODO

  • Also to not be a dick about your Tor relay. You are a reflection of the Tor project, and being a dick reflects very badly on us.

examples?

filed this as #24812

comment:56 in reply to:  54 ; Changed 4 months ago by pastly

Replying to cypherpunks:

Hi pastly,

since I specifically used ORPort 443 where it works out of the box I'm wondering about the
motivation for your change to 9001:
https://trac.torproject.org/projects/tor/wiki/TorRelayGuide?sfp_email=&sfph_mail=&action=diff&version=137&old_version=136&sfp_email=&sfph_mail=

The motivation was to make the example torrcs as consistent as possible and ensure they'd work out-of-the-box for everyone.

If you have taken the time to verify that 443 works OOTB for a couple distros, then I think my torrc changes should be reverted. (And thanks for putting in that work!)

I think 9001 should be mentioned *somewhere* as a commonly used unprivileged port, especially if it is used in example torrcs.

Last edited 4 months ago by pastly (previous) (diff)

comment:57 in reply to:  56 ; Changed 4 months ago by cypherpunks

Replying to pastly:

If you have taken the time to verify that 443 works OOTB for a couple distros, then I think my torrc changes should be reverted.

Can you take care of reverting it?

comment:58 in reply to:  57 Changed 4 months ago by pastly

Replying to cypherpunks:

Replying to pastly:

If you have taken the time to verify that 443 works OOTB for a couple distros, then I think my torrc changes should be reverted.

Can you take care of reverting it?

Done

comment:59 in reply to:  53 Changed 4 months ago by cypherpunks

  • I'd would like to make the page readonly for the first 3 days after you announce it on twitter and/or blog

Good idea.

I don't think "The Tor Relay Guide" is descriptive enough. It's not all about relays, it's about running a relay. We added "Ultimate" because there are so many other resources that had to be pulled from in order to create this, so ultimate signals this is the place to come to see them all.

Since it will be located at .torproject.org it is the authoritative source of tor related information anyway, no? (even without 'ultimate')

comment:60 Changed 4 months ago by cypherpunks

I'm planing to remove the WIP header, name it tor relay guide and ask tor relay operators for comments and testing latest by 2018-01-12
please let me know if you do not want that.

comment:61 Changed 4 months ago by cypherpunks

As mentioned I proceeded with removing the WIP header.

Alison, could you make the page read-only and writable to the subscribers of this trac ticket?

I thought a bit about maintaining the guide: I'm happy to maintain the technical part of the guide but probably just if it can not be changed by anyone - since that would (probably) unnecessarily increase the effort required to maintain it. (i.e. if someone makes changes to configs)

I'm aiming to add some security related recommendations or references and filed #24872

comment:63 Changed 3 months ago by cypherpunks

I filed #24881 to bring the new guide at least as an URL to the website.
(one of the todo items).

Alison, can you make that happen? :)

comment:64 Changed 3 months ago by shawn.webb

HardenedBSD defaults the net.inet.ip.random_id sysctl node to 1. The instructions for setting it under HardenedBSD can be removed (or clarified that it's already set).

Would it be of use to note the special hardening HardenedBSD has done for the Tor port?

On HardenedBSD 11-STABLE/amd64, tor (and tor-devel) is compiled with SafeStack. On HardenedBSD 12-CURRENT/amd64, tor (and tor-devel) is compiled with SafeStack and CFI with the cfi-icall scheme disabled.

comment:65 in reply to:  64 Changed 3 months ago by cypherpunks

Replying to shawn.webb:

HardenedBSD defaults the net.inet.ip.random_id sysctl node to 1. The instructions for setting it under HardenedBSD can be removed (or clarified that it's already set).

I removed it, thanks!

comment:66 Changed 3 months ago by shawn.webb

Cc: shawn.webb@… added

comment:67 Changed 3 months ago by cypherpunks

Resolution: fixed
Status: newclosed

I'm closing this as I consider the main task as done, please reopen with specific items that are missing if you disagree.
#16261 is used to track the Bridge documenation.

I added URLs to the Tor Relay Guide on the website, it is under review here:
https://trac.torproject.org/projects/tor/ticket/24881#comment:3

Note: See TracTickets for help on using tickets.