gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

start.rst (3891B)


      1 .. _running-your-peer:
      2 
      3 Running your peer
      4 =================
      5 
      6 Your GNUnet *peer* is the set of background services that connect your
      7 computer to the GNUnet network and that applications such as GNS rely on.
      8 This page explains how to start and stop it, how to keep it running, and
      9 how to check that it is healthy.
     10 
     11 Starting and stopping
     12 ---------------------
     13 
     14 .. code-block:: console
     15 
     16    $ gnunet-arm -s        # start the peer
     17    $ gnunet-arm -e        # stop it
     18    $ gnunet-arm -r        # restart it
     19 
     20 ``gnunet-arm`` (the *Automatic Restart Manager*) starts the services your
     21 peer needs and restarts them if they crash.  It needs no configuration
     22 file; settings you change with ``gnunet-config`` are written to
     23 ``~/.config/gnunet.conf``.
     24 
     25 To see which services are running, use ``gnunet-arm -I``.  Optional
     26 services, such as the DNS bridge for GNS, are started and stopped
     27 individually:
     28 
     29 .. code-block:: console
     30 
     31    $ gnunet-arm -i dns2gns     # start a service
     32    $ gnunet-arm -k dns2gns     # stop it
     33 
     34 To start an optional service together with the peer every time, set
     35 ``IMMEDIATE_START = YES`` in its configuration section, for example
     36 ``gnunet-config -s dns2gns -o IMMEDIATE_START -V YES``.
     37 
     38 Starting your peer automatically
     39 --------------------------------
     40 
     41 Your peer is most useful, to you and to others, when it runs all the time.
     42 
     43 - If your distribution's package ships a systemd *user* unit (Fedora's
     44   does, for example), enable it with
     45   ``systemctl --user enable --now gnunet``.
     46 - Otherwise, add this line to your crontab (``crontab -e``):
     47 
     48   .. code-block:: text
     49 
     50      @reboot gnunet-arm -s
     51 
     52 Checking that it works
     53 ----------------------
     54 
     55 Your peer's identity in the network:
     56 
     57 .. code-block:: console
     58 
     59    $ gnunet-pils --once
     60    49MAZRCX4ZH5QMXTT73GQGNVDK8QHTQXAMP8BEVYKHC1M2RMM1EG
     61 
     62 The peers you are currently connected to (one per line; give it a few
     63 minutes after starting):
     64 
     65 .. code-block:: console
     66 
     67    $ gnunet-core -s
     68 
     69 The estimated size of the network:
     70 
     71 .. code-block:: console
     72 
     73    $ gnunet-nse
     74 
     75 If ``gnunet-core -s`` lists no peers after several minutes, your peer
     76 cannot reach the network.  The most common reasons are a firewall or NAT
     77 that blocks incoming and outgoing connections, and a failure to download
     78 the list of initial peers.  See :ref:`Configuring-NAT` and
     79 :ref:`Configuring-the-hostlist-to-bootstrap`.  Names in your own zones keep
     80 working without a connection; only lookups in other people's zones need the
     81 network.
     82 
     83 Where GNUnet keeps its files
     84 ----------------------------
     85 
     86 ``~/.config/gnunet.conf``
     87    Your configuration, if you have changed any settings.  See
     88    :doc:`configuration`.
     89 
     90 ``~/.local/share/gnunet/``
     91    Persistent data: the peer's key, your zones' keys, and the databases.
     92    See :ref:`gns-backup` for what to back up.
     93 
     94 ``~/.cache/gnunet/``
     95    Log files, one per day.  Look here first when something goes wrong.
     96 
     97 If the ``XDG_CONFIG_HOME``, ``XDG_DATA_HOME`` or ``XDG_CACHE_HOME``
     98 environment variables are set, these directories are used instead of
     99 ``~/.config``, ``~/.local/share`` and ``~/.cache``.
    100 
    101 System-wide installations
    102 -------------------------
    103 
    104 Some distribution packages, and administrators who follow
    105 :ref:`The-Multi_002dUser-Setup`, run part of GNUnet as a system service:
    106 the *system services* run once per machine as the user ``gnunet`` and use
    107 ``/etc/gnunet.conf``, while every user who wants to use GNUnet runs their
    108 own *user services* with ``gnunet-arm -s`` as above.  For this to work,
    109 your user must be a member of the ``gnunet`` group.  The system services
    110 are started by the system's init system, not by you.
    111 
    112 Getting help
    113 ------------
    114 
    115 - Read the log files in ``~/.cache/gnunet/``.
    116 - Check the :doc:`/faq` and the `bug tracker <https://bugs.gnunet.org/>`__
    117   for known problems, and report new ones there.
    118 - Ask on the `help-gnunet@gnu.org
    119   <https://lists.gnu.org/mailman/listinfo/help-gnunet>`__ mailing list.