View Issue Details

IDProjectCategoryView StatusLast Update
0006134Talerdocumentationpublic2021-08-24 16:23
ReporterFlorian Dold Assigned Tottn  
PrioritynormalSeveritytextReproducibilityhave not tried
Status closedResolutionfixed 
Target Version0.8Fixed in Version0.8 
Summary0006134: configuration file format is insufficiently documented in GNUnet and Taler
DescriptionThere is no place other than the source code that comprehensively defines the configuration file format.

The GNUnet man page has some bits, but is very specific to GNUnet. It doesn't mention the include mechanism, and the format is underspecified. For example:

* "Boolean values are given as "YES" and "NO"."
 => the manpage doesn't mention anything about case (in)sensitivity

* "Empty lines and lines beginning with a "#" are treated as comments."
 => What about comment lines that begin with a whitespace? Are they allowed?
 => How is whitespace handled in *front* of option names and section names?

* "A section contains a number of options of the form "OPTION=VALUE""
 => What lexical syntax does "OPTION" have? Does it allow whitespace, like many ini parsers do?

The GNUnet handbook isn't any more helpful. The Taler documentation and man pages also don't contain sufficient information.

The variable substitution syntax isn't explained properly either.

How string quotes work and if there are any escape symbols isn't clear from the docs.

Neither is the include mechanism.
TagsNo tags attached.

Activities

Christian Grothoff

2020-11-23 00:04

manager   ~0017150

taler-config / gnunet-config and the configuration format itself are also documented in several places IIRC. Would be good to only write the generic text once and reference (or include) it, instead of repeating it in various places... ;-).

ttn

2020-11-25 04:23

developer   ~0017153

How about a new manual "Configuration Tools" that describes the format and also the tools that read/write the format? This would describe:

  - comment syntax
  - section/key case-insensitivity / syntax
  - quoting syntax
  - value types (boolean, numeric, symbol, string) / syntax
  - variable substitution
  - include mechanism

Additionally:

  - conventions in the examples
  - examples
    - CLI program (taler-config/gnunet-config) invocation
    - configuration files
  - troubleshooting

Alternatively, all the above can be placed in the respective tool manpages, w/ the common bits factored and included as necessary. Hmm...

Christian Grothoff

2020-11-25 11:18

manager   ~0017154

I expect that we'll soon have a few exchange-specific configuration tools (like "generate fee structure" or "configure auditor"). But those are exchange-specific, and so it would be good if the manual title were clear on being only about taler-config (or gnunet-config). Also, you might want to run 'less' on taler-config, you may be slightly surprised.
We do have a man-page 'man 5 taler.config', in case you missed that one, and there is also a man-page 'man 1 gnunet-config' -- which (if it were perfect) would apply 1:1 to taler-config.

I was thinking of #including a chapter on "Configuration file syntax and editing" or something like that in each of the manuals that have a specific audience where this applies (merchant backend operator, exchange operator for now). A new manual felt a bit like overkill, we already have a very large number of those IMO. But, if you feel a new top-level manual is better, I won't object.

Christian Grothoff

2020-11-25 11:20

manager   ~0017155

Oh, last point: as GNUnet uses the same configuration (tooling, format), we might want a solution that _also_ can be re-used for docs.gnunet.org, except there it's 'gnunet.conf' instead of 'taler.conf' and gnunet-config instead of taler-config, and the defaults are in ~/share/gnunet/config.d/ instead of ~/share/taler/config.d/ -- but otherwise they are identical.

ttn

2020-11-25 23:47

developer   ~0017156

I see that taler-config is at its heart gnunet-config. :-D I'm off to study some source code...!

ttn

2020-12-01 08:46

developer   ~0017159

Last edited: 2020-12-01 08:50

Please see recent commit to docs.git:
https://git.taler.net/docs.git/commit/?id=9928318ed1ca011e2a7ff40e6e1bc24ab1f89cc0

ttn

2020-12-09 05:24

developer   ~0017178

Still to go:
- variable substitution (e.g. $HOME)
- @INLINE@
- escaping quotes and other characters

Anything else?

Christian Grothoff

2020-12-09 07:29

manager   ~0017180

That's it, IMO.

ttn

2020-12-10 09:34

developer   ~0017181

I've added a new manpage -- taler-config(1):
https://docs.taler.net/manpages/taler-config.1.html

Hopefully, between this manpage and the existing taler.conf(5), the format is documented enough to be able to close this bug (at least, for the GNU Taler side of things). What do people think?

Christian Grothoff

2020-12-10 10:11

manager   ~0017184

Looks good to me -- just section 2.3.1/2.3.2 should probably be also included in the merchant operator manual (chapter 3.4) and the auditor manual (chapter 10.3). And 2.3.1 could make it into the GNUnet handbook as well!

ttn

2020-12-11 21:38

developer   ~0017190

I found https://git.gnunet.org/gnunet.git/tree/doc/handbook/chapters/configuration.texi
-- is that what you have in mind?

Christian Grothoff

2020-12-11 22:37

manager   ~0017191

There, or here: https://git.gnunet.org/gnunet.git/tree/doc/handbook/chapters/installation.texi

Depends. Not sure what is best

ttn

2020-12-15 09:51

developer   ~0017203

I've made two commits to gnunet.org/gnunet.git:
- https://git.gnunet.org/gnunet.git/commit/?id=52986bf3356f25e65c
- https://git.gnunet.org/gnunet.git/commit/?id=db9d81947c8f1b9cd8

Of these, i'm more concerned about the accuracy of the first one. PTAL critically.

ttn

2020-12-15 10:17

developer   ~0017204

Haha, it turns out the second one caused an error w/ buildbot:
- https://buildbot.gnunet.org/#/builders/6/builds/324

I have added another commit to remedy this:
- https://git.gnunet.org/gnunet.git/commit/?id=38880623a47e787f9b

Hopefully buildbot will be happy now.

ttn

2020-12-15 10:59

developer   ~0017205

I realize now that the "Configuration Handbook" chapter was never included in the final output.
This commit changes that:
- https://git.gnunet.org/gnunet.git/commit/?id=407765df156fa2600e

ttn

2020-12-15 11:14

developer   ~0017206

Sigh, another buildbot grumbling:
- https://buildbot.gnunet.org/#/builders/6/builds/326

This time, i actually built locally (in the pre-installation gnunet-0.14.0 directory).
These commits result in no error and a correct build:
- https://git.gnunet.org/gnunet.git/commit/?id=93d69ab5433fd156ba
- https://git.gnunet.org/gnunet.git/commit/?id=5ea3ecfe57bfab479b

ttn

2020-12-18 20:11

developer   ~0017214

Is there anything else to do for this bug?

Christian Grothoff

2020-12-18 20:30

manager   ~0017215

I'm happy. Let's give Florian a few days to comment, if he has nothing, let's call it resolved.

Florian Dold

2020-12-21 13:00

manager   ~0017222

I really like the new configuration man page, it addresses all concerns I had and is very readable.

Minor nitpick: Maybe mention that unlike in "/bin/sh"-style double quotes, escape characters are *not* supported and the entire string within double quotes (including other double quotes!) is taken verbatim? GNUnet seems to support some form of escaping (see escape_name in src/util/configuration.c), but that is only used for lists of file names (to escape spaces) and AFAICT *not* used in Taler at all.

ttn

2020-12-23 05:25

developer   ~0017227

Thanks for the feedback. I've just now pushed:
https://git.taler.net/docs.git/commit/?id=d2824c938212fc9de85ec3bbf3bb0f595e7ac01e

Issue History

Date Modified Username Field Change
2020-03-23 09:47 Florian Dold New Issue
2020-03-23 09:47 Florian Dold Status new => assigned
2020-03-23 09:47 Florian Dold Assigned To => Christian Grothoff
2020-03-23 09:48 Florian Dold Description Updated
2020-03-23 12:56 Christian Grothoff Assigned To Christian Grothoff => Stefan
2020-09-05 13:59 Christian Grothoff Severity minor => text
2020-11-20 20:01 Christian Grothoff Assigned To Stefan => ttn
2020-11-23 00:04 Christian Grothoff Note Added: 0017150
2020-11-25 04:23 ttn Note Added: 0017153
2020-11-25 11:18 Christian Grothoff Note Added: 0017154
2020-11-25 11:20 Christian Grothoff Note Added: 0017155
2020-11-25 23:47 ttn Note Added: 0017156
2020-12-01 08:46 ttn Note Added: 0017159
2020-12-01 08:48 ttn Note Edited: 0017159
2020-12-01 08:50 ttn Note Edited: 0017159
2020-12-09 05:24 ttn Note Added: 0017178
2020-12-09 07:29 Christian Grothoff Note Added: 0017180
2020-12-10 09:34 ttn Note Added: 0017181
2020-12-10 10:11 Christian Grothoff Note Added: 0017184
2020-12-11 21:38 ttn Note Added: 0017190
2020-12-11 22:37 Christian Grothoff Note Added: 0017191
2020-12-15 09:51 ttn Note Added: 0017203
2020-12-15 10:17 ttn Note Added: 0017204
2020-12-15 10:59 ttn Note Added: 0017205
2020-12-15 11:14 ttn Note Added: 0017206
2020-12-18 20:11 ttn Note Added: 0017214
2020-12-18 20:30 Christian Grothoff Note Added: 0017215
2020-12-21 13:00 Florian Dold Note Added: 0017222
2020-12-23 05:25 ttn Note Added: 0017227
2021-01-01 16:39 Christian Grothoff Status assigned => resolved
2021-01-01 16:39 Christian Grothoff Resolution open => fixed
2021-01-01 16:39 Christian Grothoff Fixed in Version => 0.9
2021-07-30 13:57 Christian Grothoff Fixed in Version 0.9 => 0.8.1
2021-07-30 13:59 Christian Grothoff Target Version => 0.8.1
2021-07-30 14:01 Christian Grothoff Fixed in Version 0.8.1 => 0.8
2021-07-30 14:01 Christian Grothoff Target Version 0.8.1 => 0.8
2021-08-24 16:23 Christian Grothoff Status resolved => closed