0001-modified-the-multi-single-user-layout-to-re-integrat.patch (10,953 bytes)   

From 408331fe7b31e46d6519e67eab18ff75d1566a0c Mon Sep 17 00:00:00 2001
From: jlmxyz <dev.delaboetie@dolce-energy.com>
Date: Fri, 18 Sep 2026 19:13:17 +0200
Subject: [PATCH] modified the multi-single user layout to re-integrate
 information and better distinguish the setup added a testing section so that
 the user can test the setup after install added links to detailed
 configuration for single and multi user setup modified the config file format
 to help user find the configuration detail splitted the config file format
 section into subsections to better find information adding a troubleshoot
 section to help investigate added some 'after install' steps like identity,
 gns setup....

---
 about.rst               |   2 +-
 installing.rst          | 209 +++++++++++++++++++++++++++++++---------
 users/configuration.rst |  38 ++++++--
 3 files changed, 196 insertions(+), 53 deletions(-)

diff --git a/about.rst b/about.rst
index c87e739..915d4f0 100644
--- a/about.rst
+++ b/about.rst
@@ -240,7 +240,7 @@ International Symposium on Cluster Computing and the Grid (GRID 2003),
 
 
 Security goals and threat model
--------------------------
+-------------------------------
 
 GNUnet is designed as to subsist in the face of a strong adversaries (malicous, bad actors).
 This includes, in decending strength, malicous
diff --git a/installing.rst b/installing.rst
index 6d62206..0b5dcb1 100644
--- a/installing.rst
+++ b/installing.rst
@@ -137,43 +137,6 @@ Extract it using a graphical archive tool or tar:
 In the next chapter we will assume that the source code is available in
 the home directory at ~/gnunet.
 
-Create user and groups for the system services
-----------------------------------------------
-
-**For single-user setup this section can be skipped**
-
-The multi-user setup means that there are system services, which are run
-once per machine as a dedicated system user (called gnunet) and user
-services which can be started by every user who wants to use GNUnet
-applications. The user services communicate with the system services
-over unix domain sockets. To gain permissions to read and write those
-sockets the users running GNUnet applications will need to be in the
-gnunet group. In addition the group gnunetdns may be needed (see below).
-
-Create user gnunet who is member of the group gnunet (automatically
-created) and specify a home directory where the GNUnet services will
-store persistent data such as information about peers.
-
-::
-
-   $ sudo useradd --system --home-dir /var/lib/gnunet --create-home gnunet
-
-Now add your own user to the gnunet group:
-
-::
-
-   $ sudo usermod -aG gnunet <user>
-
-Create a group gnunetdns. This allows using setgid in a way that only
-the DNS service can run the gnunet-helper-dns binary. This is only
-needed if system-wide DNS interception will be used. For more
-information see `Configuring system-wide DNS
-interception <installing#configuring%20system-wide-dns-interception>`__.
-
-::
-
-   $ sudo groupadd gnunetdns
-
 Preparing and Compiling the Source Code
 ---------------------------------------
 
@@ -270,17 +233,56 @@ on localhost:7777.
 Minimal configuration
 ---------------------
 
-GNUnet needs a configuration file to start (see `Config file
-format <#Config-file-format>`__). For the *single-user setup* an empty
-file is sufficient:
+multi-user setup
+~~~~~~~~~~~~~~~~
+
+
+Create user and groups for the system services
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The multi-user setup means that there are system services, which are run
+once per machine as a dedicated system user (called gnunet) and user
+services which can be started by every user who wants to use GNUnet
+applications. The user services communicate with the system services
+over unix domain sockets. To gain permissions to read and write those
+sockets the users running GNUnet applications will need to be in the
+gnunet group. In addition the group gnunetdns may be needed (see below).
+
+Create user gnunet who is member of the group gnunet (automatically
+created) and specify a home directory where the GNUnet services will
+store persistent data such as information about peers.
 
 ::
 
-   $ touch ~/.config/gnunet.conf
+   $ sudo useradd --system --home-dir /var/lib/gnunet --create-home gnunet
 
-For the *multi-user setup* we need an extra config file for the system
-services. The default location is ``/etc/gnunet.conf``. The minimal
-content of that file which activates the system services roll is:
+Now add your own user to the gnunet group:
+
+::
+
+   $ sudo usermod -aG gnunet <user>
+
+Create a group gnunetdns. This allows using setgid in a way that only
+the DNS service can run the gnunet-helper-dns binary. This is only
+needed if system-wide DNS interception will be used. For more
+information see `Configuring system-wide DNS
+interception <installing#configuring%20system-wide-dns-interception>`__.
+
+::
+
+   $ sudo groupadd gnunetdns
+
+for best practice regarding user/group and security  see  
+:ref:`Recommendation-_002d-Run-most-services-as-system-user-_0022gnunet_0022`
+
+Configuration Files
+^^^^^^^^^^^^^^^^^^^
+
+for complete configuration file reference see : :ref:`Config-file-format` 
+
+Create a config file for the system services. The default location is 
+``/etc/gnunet.conf``. The minimal content of that file which activates 
+the system services roll is:
 
 ::
 
@@ -288,7 +290,8 @@ content of that file which activates the system services roll is:
    START_SYSTEM_SERVICES = YES
    START_USER_SERVICES = NO
 
-The config file for the user services (``~/.config/gnunet.conf``) needs
+Each user need to create a config file for the user services 
+(``~/.config/gnunet.conf``) 
 the opposite configuration to activate the user services roll:
 
 ::
@@ -296,3 +299,119 @@ the opposite configuration to activate the user services roll:
    [arm]
    START_SYSTEM_SERVICES = NO
    START_USER_SERVICES = YES
+
+more details are available in :ref:`The-Multi_002dUser-Setup` 
+
+single user setup
+~~~~~~~~~~~~~~~~~
+
+
+For the *single-user setup* an empty file is sufficient:
+
+::
+
+   $ touch ~/.config/gnunet.conf
+
+more details are available in :ref:`The-Single_002dUser-Setup` 
+
+.. _Testing:
+
+Testing
+---------
+
+You need first to start the services
+
+`gnunet-arm -s`
+
+optionnaly you can check the service status 
+
+`gnunet-arm -I`
+
+next step is to wait a little and check that peers are connected, gnunet contains 
+a default hardcoded bootstrap configuration that can be disabled
+( see :ref:`Disable_default_bootstrap`)
+or can be customized (see :ref:`Configuring-the-hostlist-to-bootstrap`)
+the default configuration should connect to the official gnunet without change
+
+`gnunet-transport -a`
+
+if connected to peers it will report something like 
+
+.. code-block:: text
+
+   PEER       ROUTE          VIA           CORE-WIN  STALLED  PENDING        RTT
+   DGWC       dv (2 hops)    udp,tcp              4        0        0     776 ms
+   RAC0       dv (2 hops)    udp,tcp              4        0        0    1567 ms
+   DXYV       direct         udp,tcp              4        0       47       0 ms
+   
+
+if you use GNS services you can check using
+
+`gnunet-gns -t EDKEY -u higepi.gnunet.gns.alt`
+
+it should display something like
+
+.. code-block:: text
+
+   >>> Looking for `EDKEY' records under `higepi.gnunet.gns.alt'
+   <<< 1 record(s) found:
+   
+   EDKEY: `000G056EKDRX45PDSVG8BCBH74A86X4DNK4FYNAJ0WVRX9B92H7SYVBG3M' 
+
+   Resolution finished after 1318 µs
+   Record set expires in 23 h.
+
+other usefull troubleshooting commands : 
+`gnunet-core -m` : see gnunet activity (connection, hello messages, pings...)
+
+
+
+.. _next:
+
+next 
+----
+
+obtain host information : 
+    `gnunet-pils -1`
+
+
+create an identity : 
+    `gnunet-identity -C TheIdentityYouWant`
+    
+    note : identity is a user service, so be sure that user services are up
+
+obtain it's key : 
+    `gnunet-identity -d`
+
+publish it to gns : 
+    `gnunet-namestore -z TheZoneControlingTheRecord -a -n www -t A -V 1.2.3.4 -e 1d -p`
+
+    (see dns documentation for A records in the above exemple, expiration times... 
+    and `man gnunet-namestore`)
+
+.. _troubleshoot:
+
+troubleshooting
+---------------
+
+obtain all gnunet path : 
+    `gnunet-config -f -s paths` 
+
+    ⚠ display path related to user
+
+display database content (sqlite3) : 
+    for example listing namcache content (namecache/sqlite.db)
+    
+    ⚠ accessing the database need gnunet to be shutdown
+
+.. code-block:: text
+   
+    sqlite3 /var/lib/gnunet/.local/share/gnunet/namecache/sqlite.db
+    sqlite> .schema
+    sqlite> SELECT * FROM ns096blocks;`
+
+
+
+
+
+
diff --git a/users/configuration.rst b/users/configuration.rst
index 2b380a1..23ffcdc 100644
--- a/users/configuration.rst
+++ b/users/configuration.rst
@@ -7,6 +7,9 @@ Advanced Configuration
 Config file format
 ~~~~~~~~~~~~~~~~~~
 
+format description
+^^^^^^^^^^^^^^^^^^
+
 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
@@ -28,6 +31,33 @@ contains its values. The right format follows:
    value21 = string
    value22 = /path22
 
+obtaining section detail
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The utility '\ ``gnunet-config``\ ', which gets installed along with
+GNUnet, serves to get and set configuration values without directly
+editing the ``.conf`` file. The option '\ ``-f``\ ' is particularly
+useful to resolve filenames, when they use several levels of
+``$``-expanded variables. See '\ ``gnunet-config --help``\ '.
+
+this tool is really useful to list section and content 
+
+.. code-block:: text
+
+   `gnunet-config -S` 
+
+will list you sections and 
+
+.. code-block:: text
+
+   `gnunet-config -s section` 
+
+will display the configuration associated (for full content and not only
+modified, -F option might be useful)
+
+using variables
+^^^^^^^^^^^^^^^
+
 Throughout any configuration file, it is possible to use ``$``-prefixed
 variables, like ``$VAR``, especially when they represent filenames in in
 the filesystem. It is also possible to provide defaults values for those
@@ -56,16 +86,10 @@ or (b) by setting them in the environment
 
 The configuration loader will give precedence to variables set under
 ``[path]``, though.
-
-The utility '\ ``gnunet-config``\ ', which gets installed along with
-GNUnet, serves to get and set configuration values without directly
-editing the ``.conf`` file. The option '\ ``-f``\ ' is particularly
-useful to resolve filenames, when they use several levels of
-``$``-expanded variables. See '\ ``gnunet-config --help``\ '.
-
 Note that, in this stage of development, the file
 ``$HOME/.config/gnunet.conf`` can contain sections for **all** the
 components.
+
 .. _The-Single_002dUser-Setup:
 
 The Single-User Setup
-- 
2.55.0