From 52986bf3356f25e65ca03bab0070c16c9bd60d7c Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 15 Dec 2020 03:26:26 -0500 Subject: [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. --- doc/handbook/chapters/configuration.texi | 74 +++++++++++++++++++++++++++++++- 1 file changed, 73 insertions(+), 1 deletion(-) diff --git a/doc/handbook/chapters/configuration.texi b/doc/handbook/chapters/configuration.texi index 286c72e7a..adff956a9 100644 --- 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. -- cgit v1.2.3 From db9d81947c8f1b9cd83f2539cf4e258147a3e74e Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 15 Dec 2020 03:43:27 -0500 Subject: add pxref to ‘Config file format’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/handbook/chapters/installation.texi | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/handbook/chapters/installation.texi b/doc/handbook/chapters/installation.texi index d7b2fb590..40a23e738 100644 --- a/doc/handbook/chapters/installation.texi +++ b/doc/handbook/chapters/installation.texi @@ -327,8 +327,8 @@ Now GNS should work in browsers that are configured to use a SOCKS proxy on @node Minimal configuration @section Minimal configuration -GNUnet needs a configuration file to start. For the @emph{single-user setup} -an empty file is sufficient: +GNUnet needs a configuration file to start (@pxref{Config file format}). +For the @emph{single-user setup} an empty file is sufficient: @example $ touch ~/.config/gnunet.conf @@ -2493,4 +2493,3 @@ Furthermore, 'make install' will silently fail to set the DNS binaries to be owned by group "gnunetdns" unless that group already exists (!). An alternative name for the "gnunetdns" group can be specified using the @code{--with-gnunetdns=GRPNAME} configure option. - -- cgit v1.2.3 From 38880623a47e787f9b41b7ce9563e74b7beec619 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 15 Dec 2020 04:11:33 -0500 Subject: use four args in pxref --- doc/handbook/chapters/installation.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/handbook/chapters/installation.texi b/doc/handbook/chapters/installation.texi index 40a23e738..22252b4b2 100644 --- a/doc/handbook/chapters/installation.texi +++ b/doc/handbook/chapters/installation.texi @@ -327,7 +327,7 @@ Now GNS should work in browsers that are configured to use a SOCKS proxy on @node Minimal configuration @section Minimal configuration -GNUnet needs a configuration file to start (@pxref{Config file format}). +GNUnet needs a configuration file to start (@pxref{Config file format,,,configuration}). For the @emph{single-user setup} an empty file is sufficient: @example -- cgit v1.2.3 From 407765df156fa2600e33f16b2fe8ea7877b658d3 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 15 Dec 2020 04:54:32 -0500 Subject: include Configuration Handbook in gnunet.info (Minimal configuration): Use one-arg form of pxref (revert last commit). (Top): Comment in "Configuration Handbook". : Add "Configuration Handbook" incl. section "Config file format". --- doc/handbook/chapters/installation.texi | 2 +- doc/handbook/gnunet.texi | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/handbook/chapters/installation.texi b/doc/handbook/chapters/installation.texi index 22252b4b2..40a23e738 100644 --- a/doc/handbook/chapters/installation.texi +++ b/doc/handbook/chapters/installation.texi @@ -327,7 +327,7 @@ Now GNS should work in browsers that are configured to use a SOCKS proxy on @node Minimal configuration @section Minimal configuration -GNUnet needs a configuration file to start (@pxref{Config file format,,,configuration}). +GNUnet needs a configuration file to start (@pxref{Config file format}). For the @emph{single-user setup} an empty file is sufficient: @example diff --git a/doc/handbook/gnunet.texi b/doc/handbook/gnunet.texi index 5ff33d94c..4c7822876 100644 --- a/doc/handbook/gnunet.texi +++ b/doc/handbook/gnunet.texi @@ -78,7 +78,7 @@ This document is the Reference Manual for GNUnet version @value{VERSION}. @c * Vocabulary:: Vocabulary * Installing GNUnet:: Installing GNUnet * Using GNUnet:: Using GNUnet -@c * Configuration Handbook:: Configuring GNUnet +* Configuration Handbook:: Configuring GNUnet * GNUnet Contributors Handbook:: Contributing to GNUnet * GNUnet Developer Handbook:: Developing GNUnet * GNU Free Documentation License:: The license of this manual @@ -137,6 +137,10 @@ Using GNUnet * reclaimID Identity Provider:: * Using the Virtual Public Network:: +Configuration Handbook + +* Config file format:: + GNUnet Contributors Handbook * Contributing to GNUnet:: -- cgit v1.2.3 From 93d69ab5433fd156ba5d064e55ea6e677d777c85 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 15 Dec 2020 05:06:59 -0500 Subject: fix typo; quote { and } (six instances) --- doc/handbook/chapters/configuration.texi | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/handbook/chapters/configuration.texi b/doc/handbook/chapters/configuration.texi index adff956a9..27efc82e2 100644 --- a/doc/handbook/chapters/configuration.texi +++ b/doc/handbook/chapters/configuration.texi @@ -40,19 +40,19 @@ the filesystem. It is also possible to provide defaults values for those variables that are unset, by using the following syntax: @example -${VAR:-default} +$@{VAR:-default@} @end example @noindent -However, there are two ways a user can set @cide{$}-prefixable variables: +However, there are two ways a user can set @code{$}-prefixable variables: (a) by defining them under a @code{[paths]} section @example [paths] -GNUNET_DEPLOYMENT_SHARED = ${HOME}/shared-data +GNUNET_DEPLOYMENT_SHARED = $@{HOME@}/shared-data .. [section-x] -path-x = ${GNUNET_DEPLOYMENT_SHARED}/x +path-x = $@{GNUNET_DEPLOYMENT_SHARED@}/x @end example @noindent -- cgit v1.2.3 From 5ea3ecfe57bfab479b4e72f475577cc9dce0fac7 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 15 Dec 2020 05:07:43 -0500 Subject: @include chapters/configuration.texi --- doc/handbook/gnunet.texi | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/handbook/gnunet.texi b/doc/handbook/gnunet.texi index 4c7822876..ca74c347d 100644 --- a/doc/handbook/gnunet.texi +++ b/doc/handbook/gnunet.texi @@ -213,6 +213,10 @@ GNUnet Developer Handbook @include chapters/user.texi @c ********************************************************************* +@c ********************************************************************* +@include chapters/configuration.texi +@c ********************************************************************* + @include chapters/contributing.texi @c ********************************************************************* -- cgit v1.2.3