gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

installing.rst (8262B)


      1 .. _installing:
      2 
      3 Installing GNUnet
      4 =================
      5 
      6 You need a *recent* release of GNUnet.  The network protocols still change
      7 between major releases (for example from 0.28.x to 0.29.x), and peers
      8 running different major versions may be unable to communicate.  New
      9 releases are announced at https://www.gnunet.org/en/news/.
     10 
     11 There are two ways to install GNUnet: a package from your operating system,
     12 if it is recent enough, or from source.  Afterwards, continue with the
     13 :doc:`quickstart`.
     14 
     15 Installing a package
     16 --------------------
     17 
     18 .. list-table::
     19    :header-rows: 1
     20    :widths: 25 75
     21 
     22    * - System
     23      - How to install
     24    * - Fedora
     25      - ``sudo dnf copr enable schanzen/gnunet && sudo dnf install gnunet``
     26    * - Arch Linux
     27      - the `gnunet <https://aur.archlinux.org/packages/gnunet/>`__ package
     28        from the AUR
     29    * - Alpine Linux
     30      - ``apk add gnunet`` (`community repository
     31        <https://pkgs.alpinelinux.org/package/edge/community/x86_64/gnunet>`__)
     32    * - GNU Guix
     33      - ``guix install gnunet``
     34    * - Nix and NixOS
     35      - the `gnunet
     36        <https://search.nixos.org/packages?query=gnunet>`__ package
     37    * - macOS
     38      - ``brew install gnunet`` (Homebrew)
     39    * - OpenWrt
     40      - see `Installing on OpenWrt
     41        <https://www.gnunet.org/en/install-on-openwrt.html>`__
     42    * - Debian, Ubuntu
     43      - The distribution packages are **outdated** (Debian 13 ships 0.20)
     44        and cannot join the current network.  `Install from source`_.
     45 
     46 Packages are maintained by the distributions, not by the GNUnet project,
     47 and may lag behind.  After installing, check the version:
     48 
     49 .. code-block:: console
     50 
     51    $ gnunet-arm --version
     52 
     53 If it is older than the latest release, install from source instead.
     54 
     55 Some packages set up a :ref:`system-wide installation
     56 <system-wide-installation>`, with system services that run as the user
     57 ``gnunet``.  In that case, add yourself to the ``gnunet`` group and log in
     58 again:
     59 
     60 .. code-block:: console
     61 
     62    $ sudo usermod -aG gnunet $USER
     63 
     64 Install from source
     65 -------------------
     66 
     67 Building GNUnet takes a few minutes.
     68 
     69 1. Install the build dependencies.  On Debian 12 or newer and on recent
     70    Ubuntu releases:
     71 
     72    .. code-block:: console
     73 
     74       $ sudo apt install build-essential meson pkgconf gettext \
     75           libgcrypt20-dev libsodium-dev libgmp-dev libunistring-dev \
     76           libidn2-dev libltdl-dev libjansson-dev libmicrohttpd-dev \
     77           libcurl4-gnutls-dev libsqlite3-dev zlib1g-dev libgnutls28-dev \
     78           libextractor-dev
     79 
     80    For other systems, see `Dependencies`_.
     81 
     82 2. Download the latest release, ``gnunet-VERSION.tar.gz``, from
     83    https://ftpmirror.gnu.org/gnu/gnunet/ and unpack it:
     84 
     85    .. code-block:: console
     86 
     87       $ tar xf gnunet-VERSION.tar.gz
     88       $ cd gnunet-VERSION
     89 
     90 3. Build and install:
     91 
     92    .. code-block:: console
     93 
     94       $ meson setup --prefix=/usr/local build
     95       $ meson compile -C build
     96       $ sudo meson install -C build
     97       $ sudo ldconfig
     98 
     99    Installing as root also enables the few features that need helper
    100    programs with elevated privileges: the VPN, system-wide DNS
    101    interception, and NAT traversal via ICMP.
    102 
    103 That's it.  Continue with the :doc:`quickstart`, starting at step 2.
    104 
    105 ``meson setup --help`` lists all build options; ``meson configure build``
    106 shows their current values.
    107 
    108 Building from git
    109 ~~~~~~~~~~~~~~~~~
    110 
    111 To build the development version, clone the repository and run
    112 ``./bootstrap`` before step 3.  This additionally requires ``git`` and
    113 ``recutils``:
    114 
    115 .. code-block:: console
    116 
    117    $ git clone https://git.gnunet.org/gnunet.git
    118    $ cd gnunet
    119    $ ./bootstrap
    120 
    121 Note that the development version may be incompatible with the current
    122 release, and thus with most of the network.
    123 
    124 Installing without root privileges
    125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    126 
    127 You can also install GNUnet into your home directory.  The features that
    128 need privileged helper programs (see above) are then unavailable, which
    129 does not affect the GNU Name System.  Configure a prefix in your home
    130 directory in step 3, install without ``sudo``, and tell the dynamic linker
    131 where to find GNUnet's libraries, for example in your ``~/.profile``:
    132 
    133 .. code-block:: console
    134 
    135    $ meson setup --prefix=$HOME/gnunet --libdir=lib build
    136    $ meson compile -C build
    137    $ meson install -C build
    138    $ export PATH=$HOME/gnunet/bin:$PATH
    139    $ export LD_LIBRARY_PATH=$HOME/gnunet/lib:$LD_LIBRARY_PATH
    140 
    141 .. _system-wide-installation:
    142 .. _Minimal-configuration:
    143 
    144 Optional: a multi-user setup
    145 ----------------------------
    146 
    147 By default, each user runs a complete GNUnet peer of their own (the
    148 *single-user setup*).  On a machine with several users, it is more
    149 efficient and more secure to run the parts that make up the peer once, as
    150 *system services* under a dedicated user ``gnunet``, while each user runs
    151 only their own *user services*, such as their zones.  The user services
    152 talk to the system services over UNIX domain sockets; access is controlled
    153 by membership in the group ``gnunet``.
    154 
    155 This setup requires some preparation before ``meson install``.
    156 
    157 1. Create the user ``gnunet`` (which also creates the group ``gnunet``),
    158    with a home directory for the system services' persistent data:
    159 
    160    .. code-block:: console
    161 
    162       $ sudo useradd --system --home-dir /var/lib/gnunet --create-home gnunet
    163 
    164 2. Add every user who wants to use GNUnet to the group:
    165 
    166    .. code-block:: console
    167 
    168       $ sudo usermod -aG gnunet USERNAME
    169 
    170 3. If you want to use system-wide DNS interception, also create the group
    171    ``gnunetdns``.  It allows only the DNS service to run the
    172    ``gnunet-helper-dns`` program:
    173 
    174    .. code-block:: console
    175 
    176       $ sudo groupadd gnunetdns
    177 
    178 4. Build and install as described above.
    179 
    180 5. Tell the system services to run only the system part, in
    181    ``/etc/gnunet.conf``:
    182 
    183    .. code-block:: ini
    184 
    185       [arm]
    186       START_SYSTEM_SERVICES = YES
    187       START_USER_SERVICES = NO
    188 
    189    and the users to run only their part, in each user's
    190    ``~/.config/gnunet.conf``:
    191 
    192    .. code-block:: ini
    193 
    194       [arm]
    195       START_SYSTEM_SERVICES = NO
    196       START_USER_SERVICES = YES
    197 
    198 6. Start the system services as the user ``gnunet``, ideally from your
    199    init system, with ``gnunet-arm -c /etc/gnunet.conf -s``.  Each user then
    200    starts their own services with ``gnunet-arm -s``.
    201 
    202 See :ref:`The-Multi_002dUser-Setup` and :ref:`Access-Control-for-GNUnet`
    203 for details and recommendations.
    204 
    205 Dependencies
    206 ------------
    207 
    208 Required:
    209 
    210 -  meson 1.0 or newer, a C compiler, pkgconf (or pkg-config), and gettext
    211 -  libgcrypt
    212 -  libsodium 1.0.18 or newer
    213 -  libgmp
    214 -  libunistring
    215 -  libidn2 (or libidn)
    216 -  libltdl (part of libtool)
    217 -  jansson
    218 -  libmicrohttpd
    219 -  libcurl 7.85.0 or newer, ideally linked against GnuTLS
    220 -  SQLite 3.35.0 or newer
    221 -  zlib
    222 -  recutils (only when building from git)
    223 
    224 Optional, for specific features:
    225 
    226 -  GnuTLS: the HTTP/3 communicator (together with ngtcp2 and nghttp3) and
    227    the GNS proxy
    228 -  libextractor: metadata extraction for file-sharing (recommended, see
    229    below)
    230 -  libpq (PostgreSQL): an alternative database backend
    231 -  libjose: OpenID Connect support in re:claimID
    232 -  libzbar: ``gnunet-qr``
    233 -  libopus, libogg, and libpulse or GStreamer: the conversation
    234    application
    235 -  miniupnpc (the ``upnpc`` program): NAT traversal via UPnP
    236 -  iptables (on GNU/Linux): the VPN and DNS interception
    237 -  a TeX Live installation: ``gnunet-bcd`` (see :ref:`gns-sharing`)
    238 
    239 On libextractor: if you build GNUnet without it, installing it later has no
    240 effect.  If you package GNUnet for a distribution, consider splitting
    241 libextractor into a base package and plugins rather than leaving it out.
    242 Note that the set of installed libextractor plugins can leak, in a minor
    243 way, through the metadata of files you publish.
    244 
    245 On the C library: GNUnet works with C libraries other than glibc, but then
    246 lacks the :ref:`NSS plugin <gns-integration>`; GNS still works through
    247 ``gnunet-gns`` and DNS2GNS.  See https://bugs.gnunet.org/view.php?id=5605
    248 for an example build against NetBSD's libc.
    249 
    250 For running the test suite, you additionally need Python 3, a POSIX shell,
    251 and common utilities such as ``which``, ``bc``, ``curl``, ``sed`` and
    252 ``awk``.  The test suite only runs after ``meson install``.
    253 
    254 At runtime, ``gnunet-gns-proxy-setup-ca`` needs the ``certutil`` program
    255 from NSS and ``openssl``.