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.dbfor the default backend; for PostgreSQL, back up the database instead).private_key.eccThe 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.