Details about the contents of the configuration file are describe in
the anastasis.conf(5) chapter. This chapter only describes the
configuration format.
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 ${prefix}/share/taler/config.d/, in .conf files. In order to override these defaults, the user can write a custom .conf file and either pass it to the component at execution time, or name it taler.conf and place it under $HOME/.config/.
A config file is a text file containing sections, and each section contains its values. The right format follows:
[section1]
value1 = string
value2 = 23
[section2]
value21 = string
value22 = /path22
Throughout any configuration file, it is possible to use $-prefixed
variables, like $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:
${VAR:-default}. However, there are two ways a user can set
$-prefixable variables:
by defining them under a [paths] section, see example below,
[paths]
TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
..
[section-x]
path-x = ${TALER_DEPLOYMENT_SHARED}/x
or by setting them in the environment:
$ export VAR=/x
The configuration loader will give precedence to variables set under
[path], though.
The utility taler-config, which gets installed along with the
exchange, serves to get and set configuration values without directly
editing the .conf. The option -f is particularly useful to resolve
pathnames, when they use several levels of $-expanded variables. See
taler-config --help.
Note that, in this stage of development, the file
$HOME/.config/taler.conf can contain sections for all the
component. For example, both an exchange and a bank can read values from
it.
The repository git://git.taler.net/deployment contains examples of
configuration file used in our demos. See under deployment/config.
The tool anastasis-config can be used to extract or manipulate
configuration values; however, the configuration use the well-known INI
file format and can also be edited by hand.
Run
$ anastasis-config -s $SECTION
to list all of the configuration values in section $SECTION.
Run
$ anastasis-config -s $section -o $option
to extract the respective configuration value for option $option in
section $section.
Finally, to change a setting, run
$ anastasis-config -s $section -o $option -V $value
to set the respective configuration value to $value. Note that you
have to manually restart the Taler backend after you change the
configuration to make the new configuration go into effect.
Some default options will use $-variables, such as $DATADIR within
their value. To expand the $DATADIR or other $-variables in the
configuration, pass the -f option to anastasis-config. For example,
compare:
$ anastasis-config -s ACCOUNT-bank \
-o WIRE_RESPONSE
$ anastasis-config -f -s ACCOUNT-bank \
-o WIRE_RESPONSE
While the configuration file is typically located at
$HOME/.config/taler.conf, an alternative location can be specified
to taler-merchant-httpd and anastasis-config using the -c
option.
The service has well-known API endpoints to return its legal conditions to the user in various languages and various formats. This section describes how to setup and configure the legal conditions.
The service has an endpoint “/terms” to return the terms of service (in legal language) of the service operator. Client software show these terms of service to the user when the user is first interacting with the service. Terms of service are optional for experimental deployments, if none are configured, the service will return a simple statement saying that there are no terms of service available.
To configure the terms of service response, there are two options in the configuration file for the service:
TERMS_ETAG: The current “Etag” to return for the terms of service.
This value must be changed whenever the terms of service are
updated. A common value to use would be a version number.
Note that if you change the TERMS_ETAG, you MUST also provide
the respective files in TERMS_DIR (see below).TERMS_DIR: The directory that contains the terms of service.
The files in the directory must be readable to the service
process.The service has an endpoint “/pp” to return the terms privacy policy (in legal language) of the service operator. Clients should show the privacy policy to the user when the user explicitly asks for it, but it should not be shown by default. Privacy policies are optional for experimental deployments, if none are configured, the service will return a simple statement saying that there is no privacy policy available.
To configure the privacy policy response, there are two options in the configuration file for the service:
PRIVACY_ETAG: The current “Etag” to return for the privacy policy.
This value must be changed whenever the privacy policy is
updated. A common value to use would be a version number.
Note that if you change the PRIVACY_ETAG, you MUST also provide
the respective files in PRIVACY_DIR (see below).PRIVACY_DIR: The directory that contains the privacy policy.
The files in the directory must be readable to the service
process.The TERMS_DIR and PRIVACY_DIR directory structures must follow a
particular layout. You may use the same directory for both the terms of
service and the privacy policy, as long as you use different ETAGs. Inside of
the directory, there should be sub-directories using two-letter language codes
like “en”, “de”, or “jp”. Each of these directories would then hold
translations of the current terms of service into the respective language.
Empty directories are permitted in case translations are not available.
Then, inside each language directory, files with the name of the value set as
the TERMS_ETAG or PRIVACY_ETAG must be provided. The extension of each
of the files should be typical for the respective mime type. The set of
supported mime types is currently hard-coded in the service, and includes
“.epub”, “.html”, “.md”, “.pdf” and “.txt” files. If other files are present,
the service may show a warning on startup.
A sample file structure for a TERMS_ETAG of “tos-v0” would be:
If the user requests an HTML format with language preferences “fr” followed by
“en”, the service would return TERMS_DIR/en/tos-v0.html lacking a version in
French.
The taler-terms-generator script can be used to generate directories with
terms of service and privacy policies in multiple languages and all required
data formats from a single source file in .rst format and GNU gettext
translations in .po format.
To use the tool, you need to first write your legal conditions in English in
reStructuredText (rst). You should find a templates in
$PREFIX/share/terms/*.rst where $PREFIX is the location where you
installed the service to. Whenever you make substantive changes to the legal
terms, you must use a fresh filename and change the respective ETAG. The
resulting file must be called $ETAG.rst and the first line of the file should be the title of the document.
Once you have written the $ETAG.rst file in English, you can
generate the first set of outputs:
$ taler-terms-generator -i $ETAG
Afterwards, you should find the terms in various formats for all configured
languages (initially only English) in $PREFIX/share/terms/. The generator
has a few options which are documented in its man page.
Translations must be available in subdirectories
locale/$LANGUAGE/LC_MESSAGES/$ETAG.po.
To start translating, you first need to add a new
language:
$ taler-terms-generator -i $ETAG -l $LANGUAGE
Here, $LANGUAGE should be a two-letter language
code like de or fr. The command will generate
a file locale/$LANGUAGE/LC_MESSAGES/$ETAG.po
which contains each English sentence or paragraph
in the original document and an initially empty
translation. Translators should update the .po
file. Afterwards, simply re-run
$ taler-terms-generator -i $ETAG
to make the current translation(s) available to the service.
Note
You must restart the service whenever adding or updating legal documents or their translations.
When making minor changes without legal implications, edit the .rst file,
then re-run the step to add a new language for each existing translation to
produce an updated .po file. Translate the sentences that have changed and
finally run the generator (without -l) on the ETAG (-i $ETAG) to
create the final files.
When making major changes with legal implications, you should first rename (or
copy) the existing .rst file and the associated translation files to a new
unique name. Afterwards, make the major changes, update the .po files,
complete the translations and re-create the final files. Finally, do not
forget to update the ETAG configuration option to the new name and to
restart the service.