gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

quickstart.rst (3404B)


      1 .. _quickstart:
      2 
      3 Quick start
      4 ===========
      5 
      6 This page takes you from nothing to your own working zone in the GNU Name
      7 System (GNS) in five steps.  It takes about five minutes and needs no
      8 configuration file.
      9 
     10 .. note::
     11 
     12    GNUnet is alpha software.  GNS is its most mature component, but expect
     13    rough edges and do not rely on it for anything critical yet.  See
     14    :doc:`status`.
     15 
     16 1. Install GNUnet
     17 -----------------
     18 
     19 Install the ``gnunet`` package of your operating system, for example:
     20 
     21 .. code-block:: console
     22 
     23    $ sudo apt install gnunet       # Debian, Ubuntu, ...
     24    $ guix install gnunet           # GNU Guix
     25    $ brew install gnunet           # macOS with Homebrew
     26 
     27 Distribution packages are sometimes outdated, and peers of different major
     28 versions (say, 0.28.x and 0.29.x) may be unable to talk to each other.
     29 Check that ``gnunet-arm --version`` reports the `latest release
     30 <https://www.gnunet.org/en/news/>`__; if it does not, :doc:`install from
     31 source <installing>`.  :doc:`installing` also covers other systems.
     32 
     33 Some packages run GNUnet as a system service shared by all users of the
     34 machine.  If yours created a ``gnunet`` group, add yourself to it and log in
     35 again:
     36 
     37 .. code-block:: console
     38 
     39    $ sudo usermod -aG gnunet $USER
     40 
     41 2. Start your peer
     42 ------------------
     43 
     44 .. code-block:: console
     45 
     46    $ gnunet-arm -s
     47 
     48 This starts the GNUnet services in the background and returns immediately.
     49 (``gnunet-arm -e`` stops them again.)
     50 
     51 3. Create a zone
     52 ----------------
     53 
     54 A zone is the GNS equivalent of a domain, except that nobody rents it to you
     55 and nobody can take it away: it is a key pair you generate yourself.
     56 
     57 .. code-block:: console
     58 
     59    $ gnunet-identity -C myzone
     60 
     61 You now control the top-level domain ``.myzone`` on your machine.
     62 
     63 4. Add a record
     64 ---------------
     65 
     66 .. code-block:: console
     67 
     68    $ gnunet-namestore -z myzone -a -n www -t A -V 192.0.2.1 -e 1d
     69 
     70 This maps the name ``www.myzone`` to the IPv4 address ``192.0.2.1``, valid
     71 for one day.
     72 
     73 5. Resolve it
     74 -------------
     75 
     76 .. code-block:: console
     77 
     78    $ gnunet-gns -u www.myzone
     79    >>> Looking for `A' records under `www.myzone'
     80    Resolving... <<< 1 record(s) found:
     81 
     82    A: `192.0.2.1'
     83 
     84 That's it: you have a working GNS zone.
     85 
     86 Next: link to a friend's zone
     87 -----------------------------
     88 
     89 Zones become useful when they point to each other.  Records are private
     90 unless you publish them, so first add a *public* record (``-p``) and print
     91 your zone's public key:
     92 
     93 .. code-block:: console
     94 
     95    $ gnunet-namestore -z myzone -a -p -n blog -t A -V 192.0.2.2 -e 1d
     96    $ gnunet-identity -d -q -e myzone
     97    000G0507HZ8M09QWA93N2YX9Y9357777C0HTPK7PA0HTKJS5GCXXPGKBWC
     98 
     99 Give this key to a friend, and ask for theirs.  If your friend Alice gives
    100 you her key, add it to your zone under a name of your choice:
    101 
    102 .. code-block:: console
    103 
    104    $ gnunet-namestore -z myzone -a -n alice -t EDKEY -V 000G0...ALICEKEY -e 1d
    105 
    106 Now ``blog.alice.myzone`` resolves to whatever Alice published as ``blog``.
    107 Both peers need to be connected to the GNUnet network for this; the first
    108 lookup can take a while.
    109 
    110 Where to go next
    111 ----------------
    112 
    113 - :doc:`gns/integration`: use GNS names in your browser and other
    114   applications.
    115 - :doc:`gns/sharing`: get a name under ``.pin.gns.alt`` that every GNUnet
    116   user can resolve.
    117 - :doc:`gns/concepts`: understand zones, delegation and start zones.
    118 - :doc:`users/start`: keep your peer running, and check that it is
    119   connected.