.. _gns-zones: Managing your zones =================== This page covers the day-to-day work with your own zones: creating them, editing records, delegating to other zones, and keeping your keys safe. It assumes your peer is running (``gnunet-arm -s``). Creating, listing and deleting zones ------------------------------------ .. code-block:: console $ gnunet-identity -C myzone # create a zone $ gnunet-identity -d # list all zones with their keys $ gnunet-identity -d -q -e myzone # print only the key of one zone $ gnunet-identity -D myzone # delete a zone (see "Orphaned records") The public key printed by ``gnunet-identity -d -q -e myzone`` is what you give to others so that they can delegate to your zone. Adding records -------------- Records are added with ``gnunet-namestore``. You always name the zone (``-z``), the label (``-n``), the type (``-t``), the value (``-V``) and an expiration time (``-e``): .. code-block:: console $ gnunet-namestore -z myzone -a -n www -t A -V 192.0.2.1 -e 1d Expiration times are given as relative times such as ``1h``, ``1d`` or ``30d``. Resolvers cache records until they expire, so choose a shorter time for records you expect to change. Records are **private** by default: they resolve on your own peer but are not published. Add ``-p`` to make a record public, so that people who delegate to your zone can resolve it: .. code-block:: console $ gnunet-namestore -z myzone -a -p -n www -t A -V 192.0.2.1 -e 1d The zone apex is the label ``@``. To give the zone itself an address: .. code-block:: console $ gnunet-namestore -z myzone -a -p -n @ -t A -V 192.0.2.1 -e 1d Listing and deleting records ---------------------------- .. code-block:: console $ gnunet-namestore -z myzone -D www.myzone: A: 192.0.2.1 (1 day) PUBLIC $ gnunet-namestore -z myzone -D -n www # one label only $ gnunet-namestore -z myzone -d -n www -t A -V 192.0.2.1 # delete one record $ gnunet-namestore -z myzone -d -n www # delete all records under www To check what others will see, resolve the name the way any client would: .. code-block:: console $ gnunet-gns -u www.myzone ``gnunet-gns`` looks up ``A`` records unless you ask for another type with ``-t``, for example ``gnunet-gns -t MX -u myzone``. Delegating to other zones ------------------------- To make another zone available below one of your labels, add a delegation record holding its key. For zones with EdDSA keys (the default) the record type is ``EDKEY``; for older ECDSA zones it is ``PKEY``: .. code-block:: console $ gnunet-namestore -z myzone -a -n bob -t EDKEY -V 000G0...BOBKEY -e 1d Bob's public records are now reachable as ``NAME.bob.myzone``. Make the delegation public (``-p``) if people who delegate to *your* zone should be able to reach Bob's zone through it as well. See :ref:`gns-concepts` for how delegation chains work. To delegate a label to a zone that lives in DNS instead, use a ``GNS2DNS`` record whose value names the DNS domain and a DNS server to ask, in the form ``domain@server``: .. code-block:: console $ gnunet-namestore -z myzone -a -n gnu -t GNS2DNS -V gnu.org@8.8.8.8 -e 1d Choosing a database backend --------------------------- Your records are stored by the NAMESTORE service. The default ``sqlite`` backend needs no configuration and suits almost everybody. For very large zones (see `Large zones`_) use PostgreSQL instead: .. code-block:: console $ gnunet-config -s namestore -o DATABASE -V postgres $ gnunet-config -s namestore-postgres # review the options In a multi-user setup, the NAMESTORE database holds the records of all users; users cannot see each other's private records. If you ever need to start over, ``gnunet-namestore-dbtool --reset`` empties the database. **This deletes all records in all of your zones.** .. _gns-backup: Backing up ---------- Back up these files from ``~/.local/share/gnunet/`` (or ``$XDG_DATA_HOME/gnunet/``): ``identity/egos/`` The private keys of your zones, one file per zone, named after the zone. **These are the most important files of a GNUnet installation**: whoever has them controls your zones, and if you lose them you lose your zones. ``namestore/`` The record database (``sqlite.db`` for the default backend; for PostgreSQL, back up the database instead). ``private_key.ecc`` The key of your *peer*, which identifies your node in the network. It is not related to your zones. The key files are stored unencrypted, so store the backup encrypted. .. _gns-revocation: Revoking a compromised zone --------------------------- If someone steals the private key of a zone, they can publish records that everybody will accept as yours. The remedy is a *revocation*: a message, signed with the zone key and flooded through the network, that marks the key as invalid. After a revocation, resolution of names in the zone, and through it, fails everywhere. Revocations require a proof of work so that they are expensive to create. Prepare one **in advance**, while you still control the key, and store it safely: .. code-block:: console $ gnunet-revocation -f myzone.rev -R myzone The full computation can take days. You can interrupt it with ``Ctrl-C`` at any time: the file already contains the signature, which is the part that needs the private key, and the computation can be resumed later, even without access to the key. Unless you expect to need a very fast reaction, interrupt it early, keep the file, and finish the computation only if your key is ever compromised. This saves considerable energy. The command that actually revokes a zone is ``gnunet-revocation -p``. It cannot be undone, so read ``gnunet-revocation --help`` carefully before you use it. Orphaned records ---------------- If you delete a zone's ego (``gnunet-identity -D``) while records for it remain in the database, those records become *orphaned*: they are still published, but you can no longer manage them. To find them: .. code-block:: console $ gnunet-namestore --list-orphans This prints each orphaned record set as ``