commit a7d62172aed29384b944d2c74e8a45fd1c53fc52
parent 13a88085c90d032684a0b34108ea0190293a495f
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Mon, 1 Aug 2022 14:28:20 +0200
more config
Diffstat:
1 file changed, 273 insertions(+), 0 deletions(-)
diff --git a/man_users/configuration.rst b/man_users/configuration.rst
@@ -1,6 +1,279 @@
Advanced Configuration
----------------------
+.. _The-Single_002dUser-Setup:
+
+The Single-User Setup
+~~~~~~~~~~~~~~~~~~~~~
+
+For the single-user setup, you do not need to do anything special and
+can just start the GNUnet background processes using ``gnunet-arm``. By
+default, GNUnet looks in ``~/.config/gnunet.conf`` for a configuration
+(or ``$XDG_CONFIG_HOME/gnunet.conf`` if ``$XDG_CONFIG_HOME`` is
+defined). If your configuration lives elsewhere, you need to pass the
+``-c FILENAME`` option to all GNUnet commands.
+
+Assuming the configuration file is called ``~/.config/gnunet.conf``, you
+start your peer using the ``gnunet-arm`` command (say as user
+``gnunet``) using:
+
+::
+
+ gnunet-arm -c ~/.config/gnunet.conf -s
+
+The \"-s\" option here is for \"start\". The command should return
+almost instantly. If you want to stop GNUnet, you can use:
+
+::
+
+ gnunet-arm -c ~/.config/gnunet.conf -e
+
+The \"-e\" option here is for \"end\".
+
+Note that this will only start the basic peer, no actual applications
+will be available. If you want to start the file-sharing service, use
+(after starting GNUnet):
+
+::
+
+ gnunet-arm -c ~/.config/gnunet.conf -i fs
+
+The \"-i fs\" option here is for \"initialize\" the \"fs\"
+(file-sharing) application. You can also selectively kill only
+file-sharing support using
+
+::
+
+ gnunet-arm -c ~/.config/gnunet.conf -k fs
+
+Assuming that you want certain services (like file-sharing) to be always
+automatically started whenever you start GNUnet, you can activate them
+by setting \"IMMEDIATE_START=YES\" in the respective section of the
+configuration file (for example, \"[fs]\"). Then GNUnet with
+file-sharing support would be started whenever you enter:
+
+::
+
+ gnunet-arm -c ~/.config/gnunet.conf -s
+
+Alternatively, you can combine the two options:
+
+::
+
+ gnunet-arm -c ~/.config/gnunet.conf -s -i fs
+
+Using ``gnunet-arm`` is also the preferred method for initializing
+GNUnet from ``init``.
+
+Finally, you should edit your ``crontab`` (using the ``crontab``
+command) and insert a line
+
+.. code-block:: cron
+
+ @reboot gnunet-arm -c ~/.config/gnunet.conf -s
+
+to automatically start your peer whenever your system boots.
+
+.. _The-Multi_002dUser-Setup:
+
+The Multi-User Setup
+~~~~~~~~~~~~~~~~~~~~
+
+This requires you to create a user ``gnunet`` and an additional group
+``gnunetdns``, prior to running ``make install`` during installation.
+Then, you create a configuration file ``/etc/gnunet.conf`` which should
+contain the lines:
+
+::
+
+ [arm]
+ START_SYSTEM_SERVICES = YES
+ START_USER_SERVICES = NO
+
+Then, perform the same steps to run GNUnet as in the per-user
+configuration, except as user ``gnunet`` (including the ``crontab``
+installation). You may also want to run ``gnunet-setup`` to configure
+your peer (databases, etc.). Make sure to pass ``-c /etc/gnunet.conf``
+to all commands. If you run ``gnunet-setup`` as user ``gnunet``, you
+might need to change permissions on ``/etc/gnunet.conf`` so that the
+``gnunet`` user can write to the file (during setup).
+
+Afterwards, you need to perform another setup step for each normal user
+account from which you want to access GNUnet. First, grant the normal
+user (``$USER``) permission to the group gnunet:
+
+::
+
+ # adduser $USER gnunet
+
+Then, create a configuration file in ``~/.config/gnunet.conf`` for the
+$USER with the lines:
+
+::
+
+ [arm]
+ START_SYSTEM_SERVICES = NO
+ START_USER_SERVICES = YES
+
+This will ensure that ``gnunet-arm`` when started by the normal user
+will only run services that are per-user, and otherwise rely on the
+system-wide services. Note that the normal user may run gnunet-setup,
+but the configuration would be ineffective as the system-wide services
+will use ``/etc/gnunet.conf`` and ignore options set by individual
+users.
+
+Again, each user should then start the peer using ``gnunet-arm -s`` ---
+and strongly consider adding logic to start the peer automatically to
+their crontab.
+
+Afterwards, you should see two (or more, if you have more than one USER)
+``gnunet-service-arm`` processes running in your system.
+
+.. _Access-Control-for-GNUnet:
+
+Access Control for GNUnet
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This chapter documents how we plan to make access control work within
+the GNUnet system for a typical peer. It should be read as a
+best-practice installation guide for advanced users and builders of
+binary distributions. The recommendations in this guide apply to
+POSIX-systems with full support for UNIX domain sockets only.
+
+Note that this is an advanced topic. The discussion presumes a very good
+understanding of users, groups and file permissions. Normal users on
+hosts with just a single user can just install GNUnet under their own
+account (and possibly allow the installer to use SUDO to grant
+additional permissions for special GNUnet tools that need additional
+rights). The discussion below largely applies to installations where
+multiple users share a system and to installations where the best
+possible security is paramount.
+
+A typical GNUnet system consists of components that fall into four
+categories:
+
+User interfaces
+ User interfaces are not security sensitive and are supposed to be run
+ and used by normal system users. The GTK GUIs and most command-line
+ programs fall into this category. Some command-line tools (like
+ gnunet-transport) should be excluded as they offer low-level access
+ that normal users should not need.
+
+System services and support tools
+ System services should always run and offer services that can then be
+ accessed by the normal users. System services do not require special
+ permissions, but as they are not specific to a particular user, they
+ probably should not run as a particular user. Also, there should
+ typically only be one GNUnet peer per host. System services include
+ the gnunet-service and gnunet-daemon programs; support tools include
+ command-line programs such as gnunet-arm.
+
+Privileged helpers
+ Some GNUnet components require root rights to open raw sockets or
+ perform other special operations. These gnunet-helper binaries are
+ typically installed SUID and run from services or daemons.
+
+Critical services
+ Some GNUnet services (such as the DNS service) can manipulate the
+ service in deep and possibly highly security sensitive ways. For
+ example, the DNS service can be used to intercept and alter any DNS
+ query originating from the local machine. Access to the APIs of these
+ critical services and their privileged helpers must be tightly
+ controlled.
+
+.. todo:: Shorten these subsection titles
+
+.. _Recommendation-_002d-Disable-access-to-services-via-TCP:
+
+Recommendation - Disable access to services via TCP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GNUnet services allow two types of access: via TCP socket or via UNIX
+domain socket. If the service is available via TCP, access control can
+only be implemented by restricting connections to a particular range of
+IP addresses. This is acceptable for non-critical services that are
+supposed to be available to all users on the local system or local
+network. However, as TCP is generally less efficient and it is rarely
+the case that a single GNUnet peer is supposed to serve an entire local
+network, the default configuration should disable TCP access to all
+GNUnet services on systems with support for UNIX domain sockets. Since
+GNUnet 0.9.2, configuration files with TCP access disabled should be
+generated by default. Users can re-enable TCP access to particular
+services simply by specifying a non-zero port number in the section of
+the respective service.
+
+.. _Recommendation-_002d-Run-most-services-as-system-user-_0022gnunet_0022:
+
+Recommendation - Run most services as system user \"gnunet\"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GNUnet's main services should be run as a separate user \"gnunet\" in a
+special group \"gnunet\". The user \"gnunet\" should start the peer
+using \"gnunet-arm -s\" during system startup. The home directory for
+this user should be ``/var/lib/gnunet`` and the configuration file
+should be ``/etc/gnunet.conf``. Only the ``gnunet`` user should have the
+right to access ``/var/lib/gnunet`` (*mode: 700*).
+
+.. _Recommendation-_002d-Control-access-to-services-using-group-_0022gnunet_0022:
+
+Recommendation - Control access to services using group \"gnunet\"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Users that should be allowed to use the GNUnet peer should be added to
+the group \"gnunet\". Using GNUnet's access control mechanism for UNIX
+domain sockets, those services that are considered useful to ordinary
+users should be made available by setting \"UNIX_MATCH_GID=YES\" for
+those services. Again, as shipped, GNUnet provides reasonable defaults.
+Permissions to access the transport and core subsystems might
+additionally be granted without necessarily causing security concerns.
+Some services, such as DNS, must NOT be made accessible to the
+\"gnunet\" group (and should thus only be accessible to the \"gnunet\"
+user and services running with this UID).
+
+.. _Recommendation-_002d-Limit-access-to-certain-SUID-binaries-by-group-_0022gnunet_0022:
+
+Recommendation - Limit access to certain SUID binaries by group \"gnunet\"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Most of GNUnet's SUID binaries should be safe even if executed by normal
+users. However, it is possible to reduce the risk a little bit more by
+making these binaries owned by the group \"gnunet\" and restricting
+their execution to user of the group \"gnunet\" as well (4750).
+
+.. _Recommendation-_002d-Limit-access-to-critical-gnunet_002dhelper_002ddns-to-group-_0022gnunetdns_0022:
+
+Recommendation - Limit access to critical gnunet-helper-dns to group \"gnunetdns\"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A special group \"gnunetdns\" should be created for controlling access
+to the \"gnunet-helper-dns\". The binary should then be owned by root
+and be in group \"gnunetdns\" and be installed SUID and only be
+group-executable (2750). **Note that the group \"gnunetdns\" should have
+no users in it at all, ever.** The \"gnunet-service-dns\" program should
+be executed by user \"gnunet\" (via gnunet-service-arm) with the binary
+owned by the user \"root\" and the group \"gnunetdns\" and be SGID
+(2700). This way, **only** \"gnunet-service-dns\" can change its group
+to \"gnunetdns\" and execute the helper, and the helper can then run as
+root (as per SUID). Access to the API offered by \"gnunet-service-dns\"
+is in turn restricted to the user \"gnunet\" (not the group!), which
+means that only \"benign\" services can manipulate DNS queries using
+\"gnunet-service-dns\".
+
+.. _Differences-between-_0022make-install_0022-and-these-recommendations:
+
+Differences between \"make install\" and these recommendations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The current build system does not set all permissions automatically
+based on the recommendations above. In particular, it does not use the
+group \"gnunet\" at all (so setting gnunet-helpers other than the
+gnunet-helper-dns to be owned by group \"gnunet\" must be done
+manually). 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 ``--with-gnunetdns=GRPNAME`` configure option.
+
+
.. _Configuring-the-Friend_002dto_002dFriend-_0028F2F_0029-mode:
Configuring the Friend-to-Friend (F2F) mode
