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

$ 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):

$ 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:

$ 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:

$ gnunet-namestore -z myzone -a -p -n @ -t A -V 192.0.2.1 -e 1d

Listing and deleting records

$ 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:

$ 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:

$ 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 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:

$ 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:

$ 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.

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.

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:

$ 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:

$ gnunet-namestore --list-orphans

This prints each orphaned record set as <label>.<private key>: followed by the records. To recover the zone, recreate the ego from the printed private key:

$ gnunet-identity -C myzone --privkey=PRIVATE_KEY

To delete all orphaned records instead:

$ gnunet-namestore --purge-orphans

Large zones

Zones with very many names, such as the mirror of a DNS top-level domain, need some care:

  • Use the PostgreSQL backend (see Choosing a database backend).

  • Use EdDSA zones, which are considerably faster than ECDSA zones. This is the default for new zones.

  • Import records in bulk: there is a C API for bulk imports and a REST endpoint that uses it.

  • Let the ZONEMASTER service, which signs and publishes your records, use more worker threads, for example one per CPU core:

    $ gnunet-config -s zonemaster -o WORKER_COUNT -V 8
    

See also Migrating DNS zones to GNS for importing zones from DNS.