Opened 9 years ago

Closed 4 years ago

#2325 closed task (implemented)

Document torrc format

Reported by: rransom Owned by: nickm
Priority: Low Milestone: Tor: 0.2.7.x-final
Component: Core Tor/Tor Version: Tor: 0.2.7
Severity: Keywords: tor-relay, 027-triaged-1-in, SponsorS, TorCoreTeam201507
Cc: atagar Actual Points:
Parent ID: Points: small
Reviewer: Sponsor:

Description

We currently do not seem to have a specification for Tor's torrc format. We should have a spec, including both the parsing rules that Tor follows and unparsing rules that programs which write torrc files must follow.

Child Tickets

Change History (27)

comment:1 Changed 9 years ago by arma

What are these programs that write (or even parse) torrc files? The most robust way to generate a torrc file is to connect to Tor via its control port, do some setconfs, and then do a saveconf. That way you leave it to Tor how to format its torrc file.

I'm not clear yet that specifying it for external programs (and thus to some extent promising to stick to that format) is a good move.

comment:2 Changed 9 years ago by nickm

Milestone: Tor: unspecified

comment:3 Changed 9 years ago by arma

Ok to close this as wontfix?

I don't think we want to get into the business of having other programs muck with our torrc file directly. Plus nobody's produced any example cases. :)

comment:4 Changed 9 years ago by arma

Priority: majornormal

comment:5 in reply to:  3 ; Changed 9 years ago by rransom

Replying to arma:

Ok to close this as wontfix?

I don't think we want to get into the business of having other programs muck with our torrc file directly. Plus nobody's produced any example cases. :)

Vidalia seems to rewrite torrc files. Arm definitely parses them.

Even humans editing a torrc file would benefit from documentation.

comment:6 in reply to:  5 ; Changed 9 years ago by arma

Replying to rransom:

Vidalia seems to rewrite torrc files.

Really? I think Vidalia asks Tor to saveconf a new torrc file. I'm not sure about chiiph's new "arbitrary edits on your config" box in the Advanced window, but that should also not be touching your torrc directly.

Arm definitely parses them.

If so, I might call that a bug in arm. Or at least, a feature that's going to repeatedly bite it and its users.

Even humans editing a torrc file would benefit from documentation.

Good point.

comment:7 in reply to:  6 Changed 9 years ago by rransom

Replying to arma:

Replying to rransom:

Vidalia seems to rewrite torrc files.

Really? I think Vidalia asks Tor to saveconf a new torrc file.

You're right -- Vidalia doesn't change torrc itself, even if the user changes Tor's settings using Vidalia's 'Settings' dialog while Tor is not running. I think that is a bug in Vidalia -- that led to a bug in which if your torrc contains an HTTPSProxy which doesn't resolve, Tor won't start and Vidalia won't fix it for you.

comment:8 Changed 9 years ago by atagar

Arm definitely parses them.

If so, I might call that a bug in arm. Or at least, a feature that's going to repeatedly bite it and its users.

Heh, oh ye of little faith ;)

Arm fetches the torrc file and parses it to give warnings about configuration issues including:

  • When single value config options are defined multiple times, overwriting the previous values. There was an or-talk thread (subject "gratuitous change blocks upgrade to 0.2.2.15-alpha :-(") where users were amazed that this was happening with ExcludeNodes. Arm, however, had already notified its users with that issue about the problem for over a year.
  • Giving a notice if the torrc differs from tor's actual state (for instance, the user edited the torrc and forgot to sighup).
  • Notice if the torrc can be simplified because options match their default values.

Parsing also provides syntax highlighting and comment stripping which are nice for large torrc. Cheers! -Damian

comment:9 Changed 9 years ago by nickm

My position will likely please nobody: I'm fine with documenting the format, so long as either:

  • the documentation comes with explicit warnings that it is not a promised stable interface in the same way as, say, the control protocol,
  • or we fix the more stupid aspects of the current format as we document it.

comment:10 in reply to:  9 ; Changed 9 years ago by rransom

Replying to nickm:

My position will likely please nobody: I'm fine with documenting the format, so long as either:

  • the documentation comes with explicit warnings that it is not a promised stable interface in the same way as, say, the control protocol,
  • or we fix the more stupid aspects of the current format as we document it.

Can we do both?

comment:11 in reply to:  10 Changed 9 years ago by nickm

Replying to rransom:

Can we do both?

Sure. The situation I want to avoid is guaranteed compatibility with our current format. If we get a better format and also avoid fixing it in stone, that's fine too.

comment:12 Changed 7 years ago by nickm

Keywords: tor-relay added

comment:13 Changed 7 years ago by nickm

Component: Tor RelayTor

comment:14 Changed 5 years ago by nickm

Milestone: Tor: unspecifiedTor: 0.2.7.x-final

Worth looking at during 0.2.7 triage IMO

comment:15 Changed 5 years ago by nickm

Status: newassigned

comment:16 Changed 4 years ago by nickm

Keywords: 027-triaged-1-in added

Marking some tickets as triaged-in for 0.2.7 based on early triage

comment:17 Changed 4 years ago by isabela

Keywords: SponsorS added
Points: small
Priority: normaltrivial
Version: Tor: 0.2.7

comment:18 Changed 4 years ago by nickm

Keywords: TorCoreTeam201507 added

comment:19 Changed 4 years ago by nickm

Owner: set to nickm

comment:20 Changed 4 years ago by nickm

Cc: atagar added
Priority: trivialminor
Status: assignedneeds_review

Done in my branch 'ticket2325'. Needs review.

comment:21 Changed 4 years ago by nickm

rl1987 recommends that I document which variation of BNF I'm using.

comment:22 Changed 4 years ago by nickm

I rewrote it into ABNF. (I hope!)

comment:23 Changed 4 years ago by rl1987

Can all lines in ContinuedVal have comments or only the middle ones?

comment:24 Changed 4 years ago by nickm

Only the middle ones. If the first line ends with a comment, the next line is treated as starting a new entry. If the last line ends with a comment, the next line is treated as continuing the entry.

comment:25 Changed 4 years ago by atagar

Hi there Nick. Sorry about the delay, gave it a quick read and looks good!

Implementing a spec is, of course, the best test for its completeness and thankfully don't think we'll be doing that any time soon. Presently arm is the only application I'm aware of that reads the torrc, and I'm likely gonna drop that from the next release (the validation notices seem to cause more confusion than help).

None the less, thanks for writing this up!

comment:26 Changed 4 years ago by nickm

ok, cool! I'll merge it in then, with the ABNF change and all the fixes spotted by rl1987. Thanks!

comment:27 Changed 4 years ago by nickm

Resolution: implemented
Status: needs_reviewclosed
Note: See TracTickets for help on using tickets.