.. _installing:
Installing GNUnet
=================
You need a *recent* release of GNUnet. The network protocols still change
between major releases (for example from 0.28.x to 0.29.x), and peers
running different major versions may be unable to communicate. New
releases are announced at https://www.gnunet.org/en/news/.
There are two ways to install GNUnet: a package from your operating system,
if it is recent enough, or from source. Afterwards, continue with the
:doc:`quickstart`.
Installing a package
--------------------
.. list-table::
:header-rows: 1
:widths: 25 75
* - System
- How to install
* - Fedora
- ``sudo dnf copr enable schanzen/gnunet && sudo dnf install gnunet``
* - Arch Linux
- the `gnunet `__ package
from the AUR
* - Alpine Linux
- ``apk add gnunet`` (`community repository
`__)
* - GNU Guix
- ``guix install gnunet``
* - Nix and NixOS
- the `gnunet
`__ package
* - macOS
- ``brew install gnunet`` (Homebrew)
* - OpenWrt
- see `Installing on OpenWrt
`__
* - Debian, Ubuntu
- The distribution packages are **outdated** (Debian 13 ships 0.20)
and cannot join the current network. `Install from source`_.
Packages are maintained by the distributions, not by the GNUnet project,
and may lag behind. After installing, check the version:
.. code-block:: console
$ gnunet-arm --version
If it is older than the latest release, install from source instead.
Some packages set up a :ref:`system-wide installation
`, with system services that run as the user
``gnunet``. In that case, add yourself to the ``gnunet`` group and log in
again:
.. code-block:: console
$ sudo usermod -aG gnunet $USER
Install from source
-------------------
Building GNUnet takes a few minutes.
1. Install the build dependencies. On Debian 12 or newer and on recent
Ubuntu releases:
.. code-block:: console
$ sudo apt install build-essential meson pkgconf gettext \
libgcrypt20-dev libsodium-dev libgmp-dev libunistring-dev \
libidn2-dev libltdl-dev libjansson-dev libmicrohttpd-dev \
libcurl4-gnutls-dev libsqlite3-dev zlib1g-dev libgnutls28-dev \
libextractor-dev
For other systems, see `Dependencies`_.
2. Download the latest release, ``gnunet-VERSION.tar.gz``, from
https://ftpmirror.gnu.org/gnu/gnunet/ and unpack it:
.. code-block:: console
$ tar xf gnunet-VERSION.tar.gz
$ cd gnunet-VERSION
3. Build and install:
.. code-block:: console
$ meson setup --prefix=/usr/local build
$ meson compile -C build
$ sudo meson install -C build
$ sudo ldconfig
Installing as root also enables the few features that need helper
programs with elevated privileges: the VPN, system-wide DNS
interception, and NAT traversal via ICMP.
That's it. Continue with the :doc:`quickstart`, starting at step 2.
``meson setup --help`` lists all build options; ``meson configure build``
shows their current values.
Building from git
~~~~~~~~~~~~~~~~~
To build the development version, clone the repository and run
``./bootstrap`` before step 3. This additionally requires ``git`` and
``recutils``:
.. code-block:: console
$ git clone https://git.gnunet.org/gnunet.git
$ cd gnunet
$ ./bootstrap
Note that the development version may be incompatible with the current
release, and thus with most of the network.
Installing without root privileges
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also install GNUnet into your home directory. The features that
need privileged helper programs (see above) are then unavailable, which
does not affect the GNU Name System. Configure a prefix in your home
directory in step 3, install without ``sudo``, and tell the dynamic linker
where to find GNUnet's libraries, for example in your ``~/.profile``:
.. code-block:: console
$ meson setup --prefix=$HOME/gnunet --libdir=lib build
$ meson compile -C build
$ meson install -C build
$ export PATH=$HOME/gnunet/bin:$PATH
$ export LD_LIBRARY_PATH=$HOME/gnunet/lib:$LD_LIBRARY_PATH
.. _system-wide-installation:
.. _Minimal-configuration:
Optional: a multi-user setup
----------------------------
By default, each user runs a complete GNUnet peer of their own (the
*single-user setup*). On a machine with several users, it is more
efficient and more secure to run the parts that make up the peer once, as
*system services* under a dedicated user ``gnunet``, while each user runs
only their own *user services*, such as their zones. The user services
talk to the system services over UNIX domain sockets; access is controlled
by membership in the group ``gnunet``.
This setup requires some preparation before ``meson install``.
1. Create the user ``gnunet`` (which also creates the group ``gnunet``),
with a home directory for the system services' persistent data:
.. code-block:: console
$ sudo useradd --system --home-dir /var/lib/gnunet --create-home gnunet
2. Add every user who wants to use GNUnet to the group:
.. code-block:: console
$ sudo usermod -aG gnunet USERNAME
3. If you want to use system-wide DNS interception, also create the group
``gnunetdns``. It allows only the DNS service to run the
``gnunet-helper-dns`` program:
.. code-block:: console
$ sudo groupadd gnunetdns
4. Build and install as described above.
5. Tell the system services to run only the system part, in
``/etc/gnunet.conf``:
.. code-block:: ini
[arm]
START_SYSTEM_SERVICES = YES
START_USER_SERVICES = NO
and the users to run only their part, in each user's
``~/.config/gnunet.conf``:
.. code-block:: ini
[arm]
START_SYSTEM_SERVICES = NO
START_USER_SERVICES = YES
6. Start the system services as the user ``gnunet``, ideally from your
init system, with ``gnunet-arm -c /etc/gnunet.conf -s``. Each user then
starts their own services with ``gnunet-arm -s``.
See :ref:`The-Multi_002dUser-Setup` and :ref:`Access-Control-for-GNUnet`
for details and recommendations.
Dependencies
------------
Required:
- meson 1.0 or newer, a C compiler, pkgconf (or pkg-config), and gettext
- libgcrypt
- libsodium 1.0.18 or newer
- libgmp
- libunistring
- libidn2 (or libidn)
- libltdl (part of libtool)
- jansson
- libmicrohttpd
- libcurl 7.85.0 or newer, ideally linked against GnuTLS
- SQLite 3.35.0 or newer
- zlib
- recutils (only when building from git)
Optional, for specific features:
- GnuTLS: the HTTP/3 communicator (together with ngtcp2 and nghttp3) and
the GNS proxy
- libextractor: metadata extraction for file-sharing (recommended, see
below)
- libpq (PostgreSQL): an alternative database backend
- libjose: OpenID Connect support in re:claimID
- libzbar: ``gnunet-qr``
- libopus, libogg, and libpulse or GStreamer: the conversation
application
- miniupnpc (the ``upnpc`` program): NAT traversal via UPnP
- iptables (on GNU/Linux): the VPN and DNS interception
- a TeX Live installation: ``gnunet-bcd`` (see :ref:`gns-sharing`)
On libextractor: if you build GNUnet without it, installing it later has no
effect. If you package GNUnet for a distribution, consider splitting
libextractor into a base package and plugins rather than leaving it out.
Note that the set of installed libextractor plugins can leak, in a minor
way, through the metadata of files you publish.
On the C library: GNUnet works with C libraries other than glibc, but then
lacks the :ref:`NSS plugin `; GNS still works through
``gnunet-gns`` and DNS2GNS. See https://bugs.gnunet.org/view.php?id=5605
for an example build against NetBSD's libc.
For running the test suite, you additionally need Python 3, a POSIX shell,
and common utilities such as ``which``, ``bc``, ``curl``, ``sed`` and
``awk``. The test suite only runs after ``meson install``.
At runtime, ``gnunet-gns-proxy-setup-ca`` needs the ``certutil`` program
from NSS and ``openssl``.