gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

zones.rst (7235B)


      1 .. _gns-zones:
      2 
      3 Managing your zones
      4 ===================
      5 
      6 This page covers the day-to-day work with your own zones: creating them,
      7 editing records, delegating to other zones, and keeping your keys safe.  It
      8 assumes your peer is running (``gnunet-arm -s``).
      9 
     10 Creating, listing and deleting zones
     11 ------------------------------------
     12 
     13 .. code-block:: console
     14 
     15    $ gnunet-identity -C myzone            # create a zone
     16    $ gnunet-identity -d                   # list all zones with their keys
     17    $ gnunet-identity -d -q -e myzone      # print only the key of one zone
     18    $ gnunet-identity -D myzone            # delete a zone (see "Orphaned records")
     19 
     20 The public key printed by ``gnunet-identity -d -q -e myzone`` is what you
     21 give to others so that they can delegate to your zone.
     22 
     23 Adding records
     24 --------------
     25 
     26 Records are added with ``gnunet-namestore``.  You always name the zone
     27 (``-z``), the label (``-n``), the type (``-t``), the value (``-V``) and an
     28 expiration time (``-e``):
     29 
     30 .. code-block:: console
     31 
     32    $ gnunet-namestore -z myzone -a -n www -t A -V 192.0.2.1 -e 1d
     33 
     34 Expiration times are given as relative times such as ``1h``, ``1d`` or
     35 ``30d``.  Resolvers cache records until they expire, so choose a shorter
     36 time for records you expect to change.
     37 
     38 Records are **private** by default: they resolve on your own peer but are
     39 not published.  Add ``-p`` to make a record public, so that people who
     40 delegate to your zone can resolve it:
     41 
     42 .. code-block:: console
     43 
     44    $ gnunet-namestore -z myzone -a -p -n www -t A -V 192.0.2.1 -e 1d
     45 
     46 The zone apex is the label ``@``.  To give the zone itself an address:
     47 
     48 .. code-block:: console
     49 
     50    $ gnunet-namestore -z myzone -a -p -n @ -t A -V 192.0.2.1 -e 1d
     51 
     52 Listing and deleting records
     53 ----------------------------
     54 
     55 .. code-block:: console
     56 
     57    $ gnunet-namestore -z myzone -D
     58    www.myzone:
     59            A: 192.0.2.1 (1 day)    PUBLIC
     60    $ gnunet-namestore -z myzone -D -n www            # one label only
     61    $ gnunet-namestore -z myzone -d -n www -t A -V 192.0.2.1   # delete one record
     62    $ gnunet-namestore -z myzone -d -n www            # delete all records under www
     63 
     64 To check what others will see, resolve the name the way any client would:
     65 
     66 .. code-block:: console
     67 
     68    $ gnunet-gns -u www.myzone
     69 
     70 ``gnunet-gns`` looks up ``A`` records unless you ask for another type with
     71 ``-t``, for example ``gnunet-gns -t MX -u myzone``.
     72 
     73 Delegating to other zones
     74 -------------------------
     75 
     76 To make another zone available below one of your labels, add a delegation
     77 record holding its key.  For zones with EdDSA keys (the default) the record
     78 type is ``EDKEY``; for older ECDSA zones it is ``PKEY``:
     79 
     80 .. code-block:: console
     81 
     82    $ gnunet-namestore -z myzone -a -n bob -t EDKEY -V 000G0...BOBKEY -e 1d
     83 
     84 Bob's public records are now reachable as ``NAME.bob.myzone``.  Make the
     85 delegation public (``-p``) if people who delegate to *your* zone should be
     86 able to reach Bob's zone through it as well.  See :ref:`gns-concepts` for
     87 how delegation chains work.
     88 
     89 To delegate a label to a zone that lives in DNS instead, use a ``GNS2DNS``
     90 record whose value names the DNS domain and a DNS server to ask, in the form
     91 ``domain@server``:
     92 
     93 .. code-block:: console
     94 
     95    $ gnunet-namestore -z myzone -a -n gnu -t GNS2DNS -V gnu.org@8.8.8.8 -e 1d
     96 
     97 Choosing a database backend
     98 ---------------------------
     99 
    100 Your records are stored by the NAMESTORE service.  The default ``sqlite``
    101 backend needs no configuration and suits almost everybody.  For very large
    102 zones (see `Large zones`_) use PostgreSQL instead:
    103 
    104 .. code-block:: console
    105 
    106    $ gnunet-config -s namestore -o DATABASE -V postgres
    107    $ gnunet-config -s namestore-postgres              # review the options
    108 
    109 In a multi-user setup, the NAMESTORE database holds the records of all
    110 users; users cannot see each other's private records.
    111 
    112 If you ever need to start over, ``gnunet-namestore-dbtool --reset`` empties
    113 the database.  **This deletes all records in all of your zones.**
    114 
    115 .. _gns-backup:
    116 
    117 Backing up
    118 ----------
    119 
    120 Back up these files from ``~/.local/share/gnunet/`` (or
    121 ``$XDG_DATA_HOME/gnunet/``):
    122 
    123 ``identity/egos/``
    124    The private keys of your zones, one file per zone, named after the zone.
    125    **These are the most important files of a GNUnet installation**: whoever
    126    has them controls your zones, and if you lose them you lose your zones.
    127 
    128 ``namestore/``
    129    The record database (``sqlite.db`` for the default backend; for
    130    PostgreSQL, back up the database instead).
    131 
    132 ``private_key.ecc``
    133    The key of your *peer*, which identifies your node in the network.  It is
    134    not related to your zones.
    135 
    136 The key files are stored unencrypted, so store the backup encrypted.
    137 
    138 .. _gns-revocation:
    139 
    140 Revoking a compromised zone
    141 ---------------------------
    142 
    143 If someone steals the private key of a zone, they can publish records that
    144 everybody will accept as yours.  The remedy is a *revocation*: a message,
    145 signed with the zone key and flooded through the network, that marks the
    146 key as invalid.  After a revocation, resolution of names in the zone, and
    147 through it, fails everywhere.
    148 
    149 Revocations require a proof of work so that they are expensive to create.
    150 Prepare one **in advance**, while you still control the key, and store it
    151 safely:
    152 
    153 .. code-block:: console
    154 
    155    $ gnunet-revocation -f myzone.rev -R myzone
    156 
    157 The full computation can take days.  You can interrupt it with ``Ctrl-C``
    158 at any time: the file already contains the signature, which is the part that
    159 needs the private key, and the computation can be resumed later, even
    160 without access to the key.  Unless you expect to need a very fast reaction,
    161 interrupt it early, keep the file, and finish the computation only if your
    162 key is ever compromised.  This saves considerable energy.
    163 
    164 The command that actually revokes a zone is ``gnunet-revocation -p``.  It
    165 cannot be undone, so read ``gnunet-revocation --help`` carefully before you
    166 use it.
    167 
    168 Orphaned records
    169 ----------------
    170 
    171 If you delete a zone's ego (``gnunet-identity -D``) while records for it
    172 remain in the database, those records become *orphaned*: they are still
    173 published, but you can no longer manage them.  To find them:
    174 
    175 .. code-block:: console
    176 
    177    $ gnunet-namestore --list-orphans
    178 
    179 This prints each orphaned record set as ``<label>.<private key>:`` followed
    180 by the records.  To recover the zone, recreate the ego from the printed
    181 private key:
    182 
    183 .. code-block:: console
    184 
    185    $ gnunet-identity -C myzone --privkey=PRIVATE_KEY
    186 
    187 To delete all orphaned records instead:
    188 
    189 .. code-block:: console
    190 
    191    $ gnunet-namestore --purge-orphans
    192 
    193 Large zones
    194 -----------
    195 
    196 Zones with very many names, such as the mirror of a DNS top-level domain,
    197 need some care:
    198 
    199 - Use the PostgreSQL backend (see `Choosing a database backend`_).
    200 - Use EdDSA zones, which are considerably faster than ECDSA zones.  This is
    201   the default for new zones.
    202 - Import records in bulk: there is a :ref:`C API for bulk imports
    203   <NAMESTORE-Subsystem>` and a :ref:`REST endpoint <namestore_rest_api>`
    204   that uses it.
    205 - Let the ZONEMASTER service, which signs and publishes your records, use
    206   more worker threads, for example one per CPU core:
    207 
    208   .. code-block:: console
    209 
    210      $ gnunet-config -s zonemaster -o WORKER_COUNT -V 8
    211 
    212 See also :doc:`migration` for importing zones from DNS.