aboutsummaryrefslogtreecommitdiff
path: root/doc/sphinx/frags/configuration-format.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/sphinx/frags/configuration-format.rst')
-rw-r--r--doc/sphinx/frags/configuration-format.rst69
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 @@
1Configuration format
2--------------------
3
4In Taler realm, any component obeys to the same pattern to get
5configuration values. According to this pattern, once the component has
6been installed, the installation deploys default values in
7${prefix}/share/taler/config.d/, in .conf files. In order to override
8these defaults, the user can write a custom .conf file and either pass
9it to the component at execution time, or name it taler.conf and place
10it under $HOME/.config/.
11
12A config file is a text file containing sections, and each section
13contains 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
25Throughout any configuration file, it is possible to use ``$``-prefixed
26variables, like ``$VAR``, especially when they represent filesystem
27paths. It is also possible to provide defaults values for those
28variables that are unset, by using the following syntax:
29``${VAR:-default}``. However, there are two ways a user can set
30``$``-prefixable variables:
31
32by 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
42or by setting them in the environment:
43
44.. code-block:: console
45
46 $ export VAR=/x
47
48The configuration loader will give precedence to variables set under
49``[path]``, though.
50
51The utility ``taler-config``, which gets installed along with the
52exchange, serves to get and set configuration values without directly
53editing the .conf. The option ``-f`` is particularly useful to resolve
54pathnames, when they use several levels of ``$``-expanded variables. See
55``taler-config --help``.
56
57Note that, in this stage of development, the file
58``$HOME/.config/taler.conf`` can contain sections for *all* the
59component. For example, both an exchange and a bank can read values from
60it.
61
62The repository ``git://taler.net/deployment`` contains examples of
63configuration 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.