commit 52986bf3356f25e65ca03bab0070c16c9bd60d7c
parent 74d7528e6bd53cf5acc939c63a5be74a001e5ce1
Author: Thien-Thi Nguyen <ttn@gnuvola.org>
Date: Tue, 15 Dec 2020 03:26:26 -0500
[doc] Add section "Config file format"
This is based on a similar fragment in Taler docs.git.
I am certain it contains inaccuracies; please take a critical look.
Diffstat:
1 file changed, 73 insertions(+), 1 deletion(-)
diff --git a/doc/handbook/chapters/configuration.texi b/doc/handbook/chapters/configuration.texi
@@ -1,5 +1,77 @@
@node Configuration Handbook
@chapter Configuration Handbook
-This chapter has yet to be written. It is intended to be about in-depth
+This chapter has yet to be fully written. It is intended to be about in-depth
configuration of GNUnet.
+
+
+@menu
+* Config file format::
+@end menu
+
+
+@node Config file format
+@section Config file format
+
+In GNUnet realm, all components obey the same pattern to get configuration
+values. According to this pattern, once the component has been installed, the
+installation deploys default values in @file{$prefix/share/gnunet/config.d/},
+in @file{.conf} files. In order to override these defaults, the user can
+write a custom @file{.conf} file and either pass it to the component at
+execution time, or name it @file{gnunet.conf} and place it under
+@file{$HOME/.config/}.
+
+A config file is a text file containing sections, and each section
+contains its 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 filenames in in
+the filesystem. It is also possible to provide defaults values for those
+variables that are unset, by using the following syntax:
+
+@example
+${VAR:-default}
+@end example
+
+@noindent
+However, there are two ways a user can set @cide{$}-prefixable variables:
+(a) by defining them under a @code{[paths]} section
+
+@example
+[paths]
+GNUNET_DEPLOYMENT_SHARED = ${HOME}/shared-data
+..
+[section-x]
+path-x = ${GNUNET_DEPLOYMENT_SHARED}/x
+@end example
+
+@noindent
+or (b) by setting them in the environment
+
+@example
+$ export VAR=/x
+@end example
+
+@noindent
+The configuration loader will give precedence to variables set under
+@code{[path]}, though.
+
+The utility @samp{gnunet-config}, which gets installed along with GNUnet,
+serves to get and set configuration values without directly editing the
+@file{.conf} file. The option @samp{-f} is particularly useful to resolve
+filenames, when they use several levels of @code{$}-expanded variables.
+See @samp{gnunet-config --help}.
+
+Note that, in this stage of development, the file
+@file{$HOME/.config/gnunet.conf} can contain sections for @strong{all} the
+components.
