Opened 5 years ago

Closed 4 years ago

#13158 closed defect (fixed)

Did we ever document +/ semantics for config files?

Reported by: Sebastian Owned by:
Priority: Medium Milestone: Tor: 0.2.8.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords: doc easy lorax
Cc: Actual Points:
Parent ID: Points: small
Reviewer: Sponsor:

Description

I can't find any kind of documentation in the manpage or anywhere else besides a couple of comments in the source code. Is it anywhere? What are the exact semantics we're going for?

I'm tentatively marking this for 0.2.5.x, because it's a documentation fix

Child Tickets

Attachments (1)

0001-and-usage-clarification-Fixes-13158.patch (2.0 KB) - added by joanq 4 years ago.

Download all attachments as: .zip

Change History (15)

comment:1 Changed 5 years ago by arma

https://gitweb.torproject.org/tor.git/blob/refs/tags/tor-0.2.4.17-rc:/ChangeLog#l3234 is the best I've found.

Putting some of that into the man page would probably be wise. I only ran across it while trying to fix #12948.

Also, I admit that I'm not really sold on this new syntax -- so I've been trying to avoid situations where ordinary users actually need to use it or know about it.

comment:2 Changed 5 years ago by nickm

Here is the relevant situation of doc/tor.1.txt:

THE CONFIGURATION FILE FORMAT
-----------------------------

All configuration options in a configuration are written on a single line by
default.  They take the form of an option name and a value, or an option name
and a quoted value (option value or option "value"). Anything after a #
character is treated as a comment.  Options are
case-insensitive. C-style escaped characters are allowed inside quoted
values. To split one configuration entry into multiple lines, use a single
backslash character (\) before the end of the line.  Comments can be used in
such multiline entries, but they must start at the beginning of a line.

By default, an option on the command line overrides an option found in the
configuration file, and an option in a configuration file overrides one in
the defaults file.

This rule is simple for options that take a single value, but it can become
complicated for options that are allowed to occur more than once: if you
specify four SOCKSPorts in your configuration file, and one more SOCKSPort on
the command line, the option on the command line will replace __all__ of the
SOCKSPorts in the configuration file.  If this isn't what you want, prefix
the option name with a plus sign, and it will be appended to the previous set
of options instead.

Alternatively, you might want to remove every instance of an option in the
configuration file, and not replace it at all: you might want to say on the
command line that you want no SOCKSPorts at all.  To do that, prefix the
option name with a forward slash.

How should this be rewritten? Where should it go instead? I'd be happy to take a patch here.

Also, I admit that I'm not really sold on this new syntax -- so I've been trying to avoid situations where ordinary users actually need to use it or know about it.

Going forward: please let me know early in the 0.2.6 series about situations where we're committing or about to commit stuff that you think you're going to be remain unsold on. :)

comment:3 Changed 5 years ago by Sebastian

tbh, I missed that last paragraph. I looked for "+" instead of "plus sign". What I'm unclear on is what the semantics are wrt the defaults file - can I use "+" and "/" in the config file too, and that affects the defaults file?

comment:4 Changed 5 years ago by nickm

yes. Also, I'd seriously like to make the documentation better there. Maybe with some examples?

comment:5 Changed 5 years ago by Sebastian

I will see if I can cook something up (after I worked through the unit tests for it)

comment:6 Changed 5 years ago by nickm

Milestone: Tor: 0.2.5.x-finalTor: 0.2.???

comment:7 Changed 4 years ago by nickm

Keywords: doc easy lorax added

comment:8 Changed 4 years ago by arma

Saying "plus sign ("+")" would have solved the original issue for the ticket. I had exactly this issue in the past too, and have learned to search for "plus", but that doesn't scale to the third confused person. :) An easy early fractional fix at least.

comment:9 Changed 4 years ago by nickm

Milestone: Tor: 0.2.???Tor: 0.2.8.x-final

comment:10 Changed 4 years ago by nickm

Points: small

comment:11 Changed 4 years ago by joanq

Severity: Normal

I think that the attached patch fixes this ticket. This is my first contribution to tor, so let me know if there are any problems.

comment:12 Changed 4 years ago by joanq

Status: newneeds_revision

comment:13 Changed 4 years ago by nickm

Status: needs_revisionneeds_review

comment:14 Changed 4 years ago by nickm

Resolution: fixed
Status: needs_reviewclosed

Merged that!

Note: See TracTickets for help on using tickets.