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.