diff options
Diffstat (limited to 'doc/sphinx/frags/configuration-format.rst')
-rw-r--r-- | doc/sphinx/frags/configuration-format.rst | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/doc/sphinx/frags/configuration-format.rst b/doc/sphinx/frags/configuration-format.rst new file mode 100644 index 0000000..f9b28e1 --- /dev/null +++ b/doc/sphinx/frags/configuration-format.rst | |||
@@ -0,0 +1,69 @@ | |||
1 | Configuration format | ||
2 | -------------------- | ||
3 | |||
4 | In Taler realm, any component obeys to the same pattern to get | ||
5 | configuration values. According to this pattern, once the component has | ||
6 | been installed, the installation deploys default values in | ||
7 | ${prefix}/share/taler/config.d/, in .conf files. In order to override | ||
8 | these defaults, the user can write a custom .conf file and either pass | ||
9 | it to the component at execution time, or name it taler.conf and place | ||
10 | it under $HOME/.config/. | ||
11 | |||
12 | A config file is a text file containing sections, and each section | ||
13 | contains its values. The right format follows: | ||
14 | |||
15 | .. code-block:: ini | ||
16 | |||
17 | [section1] | ||
18 | value1 = string | ||
19 | value2 = 23 | ||
20 | |||
21 | [section2] | ||
22 | value21 = string | ||
23 | value22 = /path22 | ||
24 | |||
25 | Throughout any configuration file, it is possible to use ``$``-prefixed | ||
26 | variables, like ``$VAR``, especially when they represent filesystem | ||
27 | paths. It is also possible to provide defaults values for those | ||
28 | variables that are unset, by using the following syntax: | ||
29 | ``${VAR:-default}``. However, there are two ways a user can set | ||
30 | ``$``-prefixable variables: | ||
31 | |||
32 | by defining them under a ``[paths]`` section, see example below, | ||
33 | |||
34 | .. code-block:: ini | ||
35 | |||
36 | [paths] | ||
37 | TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data | ||
38 | .. | ||
39 | [section-x] | ||
40 | path-x = ${TALER_DEPLOYMENT_SHARED}/x | ||
41 | |||
42 | or by setting them in the environment: | ||
43 | |||
44 | .. code-block:: console | ||
45 | |||
46 | $ export VAR=/x | ||
47 | |||
48 | The configuration loader will give precedence to variables set under | ||
49 | ``[path]``, though. | ||
50 | |||
51 | The utility ``taler-config``, which gets installed along with the | ||
52 | exchange, serves to get and set configuration values without directly | ||
53 | editing the .conf. The option ``-f`` is particularly useful to resolve | ||
54 | pathnames, when they use several levels of ``$``-expanded variables. See | ||
55 | ``taler-config --help``. | ||
56 | |||
57 | Note that, in this stage of development, the file | ||
58 | ``$HOME/.config/taler.conf`` can contain sections for *all* the | ||
59 | component. For example, both an exchange and a bank can read values from | ||
60 | it. | ||
61 | |||
62 | The repository ``git://taler.net/deployment`` contains examples of | ||
63 | configuration file used in our demos. See under ``deployment/config``. | ||
64 | |||
65 | **Note** | ||
66 | |||
67 | Expectably, some components will not work just by using default | ||
68 | values, as their work is often interdependent. For example, a | ||
69 | merchant needs to know an exchange URL, or a database name. | ||