summaryrefslogtreecommitdiff
path: root/doc/configuration-format.texi
blob: 6453ba6018888418e118a4b11ee39dd66d22f131 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
@c This file is used both in the exchange and merchant
@c manuals. Edits should be propagated to both Gits!

@node Configuration format
@section Configuration format
@cindex configuration

In Taler realm, any component obeys to the same pattern to get configuration
values.  According to this pattern, once the component has been installed, the
installation deploys default values in @cite{$@{prefix@}/share/taler/config.d/}, in
@cite{.conf} files.  In order to override these defaults, the user can write a custom
@cite{.conf} file and either pass it to the component at execution time, or name it
@cite{taler.conf} and place it under @cite{$HOME/.config/}.


A config file is a text file containing @cite{sections}, and each section contains
its @cite{values}. The right format follows:

@example
[section1]
value1 = string
value2 = 23

[section2]
value21 = string
value22 = /path22
@end example

Throughout any configuration file, it is possible to use @code{$}-prefixed variables,
like @code{$VAR}, especially when they represent filesystem paths.
It is also possible to provide defaults values for those variables that are unset,
by using the following syntax: @code{$@{VAR:-default@}}.
However, there are two ways a user can set @code{$}-prefixable variables:

by defining them under a @code{[paths]} section, see example below,

@example
[paths]
TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data
..
[section-x]
path-x = $@{TALER_DEPLOYMENT_SHARED@}/x
@end example

or by setting them in the environment:

@example
$ export VAR=/x
@end example

The configuration loader will give precedence to variables set under @code{[path]},
though.

The utility @code{taler-config}, which gets installed along with the exchange, serves
to get and set configuration values without directly editing the @cite{.conf}.
The option @code{-f} is particularly useful to resolve pathnames, when they use
several levels of @code{$}-expanded variables. See @code{taler-config --help}.

Note that, in this stage of development, the file @code{$HOME/.config/taler.conf}
can contain sections for @emph{all} the component. For example, both an exchange and
a bank can read values from it.

The repository @code{git://taler.net/deployment} contains examples of configuration
file used in our demos. See under @code{deployment/config}.

@cartouche
@quotation Note
Expectably, some components will not work just by using default values, as their
work is often interdependent. For example, a merchant needs to know an exchange
URL, or a database name.
@end quotation
@end cartouche