update user documentation on GNS, include gnunet-zoneimport

4 files changed, 127 insertions, 127 deletions

diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am
index 991b1926ba..1bd25f7733 100644
--- a/doc/documentation/Makefile.am
+++ b/doc/documentation/Makefile.am
@@ -44,7 +44,8 @@ dist_infoimage_DATA =                           		\
 	images/daemon_lego_block.svg  				\
 	images/lego_stack.svg					\
 	images/service_lego_block.svg				\
-	images/structure.dot
+	images/structure.dot                                    \
+	images/gns.dot
 
 #	images/$(wildcard *.png)						\
 #	images/$(wildcard *.svg)
diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi
index 3a76fb1620..6eb1a88a09 100644
--- a/doc/documentation/chapters/installation.texi
+++ b/doc/documentation/chapters/installation.texi
@@ -3290,7 +3290,6 @@ and @code{[transport-https_client]} section of the configuration:
 * GNS Proxy Setup::
 * Setup of the GNS CA::
 * Testing the GNS setup::
-* Automatic Shortening in the GNU Name System::
 @end menu
 
 
@@ -3526,8 +3525,11 @@ Now for testing purposes we can create some records in our zone to test
 the SSL functionality of the proxy:
 
 @example
-$ gnunet-namestore -a -e "1 d" -n "homepage" -t A -V 131.159.74.67
-$ gnunet-namestore -a -e "1 d" -n "homepage" -t LEHO -V "gnunet.org"
+$ gnunet-identity -C test
+$ gnunet-namestore -a -e "1 d" -n "homepage" \
+  -t A -V 131.159.74.67 -z test
+$ gnunet-namestore -a -e "1 d" -n "homepage" \
+  -t LEHO -V "gnunet.org" -z test
 @end example
 
 @noindent
@@ -3544,7 +3546,7 @@ If you use @command{Firefox} (or one of its deriviates/forks such as
 Icecat) you also have to go to @code{about:config} and set the key
 @code{network.proxy.socks_remote_dns} to @code{true}.
 
-When you visit @code{https://homepage.gnu/}, you should get to the
+When you visit @code{https://homepage.test/}, you should get to the
 @code{https://gnunet.org/} frontpage and the browser (with the correctly
 configured proxy) should give you a valid SSL certificate for
 @code{homepage.gnu} and no warnings. It should look like this:
@@ -3552,26 +3554,6 @@ configured proxy) should give you a valid SSL certificate for
 @c FIXME: Image does not exist, create it or save it from Drupal?
 @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser}
 
-@node Automatic Shortening in the GNU Name System
-@subsubsection Automatic Shortening in the GNU Name System
-
-This page describes a possible option for 'automatic name shortening',
-which you can choose to enable with the GNU Name System.
-
-When GNS encounters a name for the first time, it can use the 'NICK'
-record of the originating zone to automatically generate a name for the
-zone. If automatic shortening is enabled, those auto-generated names will
-be placed (as private records) into your personal 'shorten' zone (to
-prevent confusion with manually selected names).
-Then, in the future, if the same name is encountered again, GNS will
-display the shortened name instead (the first time, the long name will
-still be used as shortening typically happens asynchronously as looking up
-the 'NICK' record takes some time). Using this feature can be a convenient
-way to avoid very long @code{.gnu} names; however, note that names from
-the shorten-zone are assigned on a first-come-first-serve basis and should
-not be trusted. Furthermore, if you enable this feature, you will no
-longer see the full delegation chain for zones once shortening has been
-applied.
 
 @node Configuring the GNUnet VPN
 @subsection Configuring the GNUnet VPN
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi
index 8ce8b52e2e..6063392ac7 100644
--- a/doc/documentation/chapters/user.texi
+++ b/doc/documentation/chapters/user.texi
@@ -1466,47 +1466,42 @@ the user. This results in non-unique name-value mappings as
 
 
 @menu
+* Creating a Zone::
 * Maintaining your own Zones::
 * Obtaining your Zone Key::
 * Adding Links to Other Zones::
-* The Three Local Zones of GNS::
-* The Master Zone::
-* The Private Zone::
-* The Shorten Zone::
-* The ZKEY Top Level Domain in GNS::
+* Using Public Keys as Top Level Domains::
 * Resource Records in GNS::
+* Synchronizing with legacy DNS::
 @end menu
 
 
-@node Maintaining your own Zones
-@subsection Maintaining your own Zones
+@node Creating a Zone
+@subsection Creating a Zone
 
-To setup your GNS system you must execute:
+To use GNS, you probably should create at least one zone of your own.
+You can create any number of zones using the gnunet-identity tool
+using:
 
 @example
-$ gnunet-gns-import.sh
+$ gnunet-identity -C "myzone"
 @end example
 
-@noindent
-This will boostrap your zones and create the necessary key material.
-Your keys can be listed using the @command{gnunet-identity}
-command line tool:
+Henceforth, on your system you control the TLD ``myzone''.
+
+All of your zones can be listed using the @command{gnunet-identity}
+command line tool as well:
 
 @example
 $ gnunet-identity -d
 @end example
 
-@noindent
-You can arbitrarily create your own zones using the gnunet-identity
-tool using:
-
-@example
-$ gnunet-identity -C "new_zone"
-@end example
+@node Maintaining your own Zones
+@subsection Maintaining your own Zones
 
 @noindent
 Now you can add (or edit, or remove) records in your GNS zone using the
-@command{gnunet-setup} GUI or using the @command{gnunet-namestore}
+@command{gnunet-namestore-gtk} GUI or using the @command{gnunet-namestore}
 command-line tool.
 In either case, your records will be stored in an SQL database under
 control of the @command{gnunet-service-namestore}.
@@ -1518,21 +1513,21 @@ if they are marked as private.
 To provide a short example for editing your own zone, suppose you
 have your own web server with the IP @code{1.2.3.4}. Then you can put an
 @code{A} record (@code{A} records in DNS are for IPv4 IP addresses)
-into your local zone using the command:
+into your local zone ``myzone'' using the command:
 
 @example
-$ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never
+$ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e never
 @end example
 
 @noindent
-Afterwards, you will be able to access your webpage under "www.gnu"
+Afterwards, you will be able to access your webpage under "www.myzone"
 (assuming your webserver does not use virtual hosting, if it does,
 please read up on setting up the GNS proxy).
 
 Similar commands will work for other types of DNS and GNS records,
 the syntax largely depending on the type of the record.
 Naturally, most users may find editing the zones using the
-@command{gnunet-setup} GUI to be easier.
+@command{gnunet-namestore-gtk} GUI to be easier.
 
 @node Obtaining your Zone Key
 @subsection Obtaining your Zone Key
@@ -1546,7 +1541,7 @@ give it to others so that they can securely link to you.
 You can usually get the hash of your public key using
 
 @example
-$ gnunet-identity -d $options | grep master-zone | awk '@{print $3@}'
+$ gnunet-identity -d $options | grep myzone | awk '@{print $3@}'
 @end example
 
 @noindent
@@ -1557,10 +1552,10 @@ DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0
 @end example
 
 @noindent
-Alternatively, you can obtain a QR code with your zone key AND
-your pseudonym from gnunet-gtk. The QR code is displayed in the
-GNS tab and can be stored to disk using the Save as button next
-to the image.
+Alternatively, you can obtain a QR code with your zone key AND your
+pseudonym from gnunet-namestore-gtk. The QR code is displayed in the
+main window and can be stored to disk using the ``Save as'' button
+next to the image.
 
 @node Adding Links to Other Zones
 @subsection Adding Links to Other Zones
@@ -1576,89 +1571,37 @@ You can then delegate resolution of names to Bob's zone by adding
 a PKEY record to their local zone:
 
 @example
-$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never
+$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never -Z myzone
 @end example
 
 @noindent
-Note that XXXX in the command above must be replaced with the
-hash of Bob's public key (the output your friend obtained using
-the gnunet-identity command from the previous section and told you,
-for example by giving you a business card containing this
+Note that ``XXXX'' in the command above must be replaced with the hash
+of Bob's public key (the output your friend obtained using the
+@command{gnunet-identity} command from the previous section and told
+you, for example by giving you a business card containing this
 information as a QR code).
 
-Assuming Bob has an A record for their website under the name of
-www in his zone, you can then access Bob's website under
-www.bob.gnu --- as well as any (public) GNS record that Bob has
+Assuming Bob has an ``A'' record for their website under the name of
+``www'' in his zone, you can then access Bob's website under
+``www.bob.myzone'' --- as well as any (public) GNS record that Bob has
 in their zone by replacing www with the respective name of the
 record in Bob's zone.
 
 @c themselves? themself?
 Furthermore, if Bob has themselves a (public) delegation to Carol's
 zone under "carol", you can access Carol's records under
-NAME.carol.bob.gnu (where NAME is the name of Carol's record you
-want to access).
-
-@node The Three Local Zones of GNS
-@subsection The Three Local Zones of GNS
+``NAME.carol.bob.myzone'' (where ``NAME'' is the name of Carol's
+record you want to access).
 
-Each user GNS has control over three zones. Each of the zones
-has a different purpose. These zones are the
 
-@itemize @bullet
-
-@item master zone,
-@item private zone, and the
-@item shorten zone.
-@end itemize
+@node Using Public Keys as Top Level Domains
+@subsection Using Public Keys as Top Level Domains
 
-@node The Master Zone
-@subsection The Master Zone
 
-
-The master zone is your personal TLD. Names within the @code{.gnu}
-namespace are resolved relative to this zone. You can arbitrarily
-add records to this zone and selectively publish those records.
-
-@node The Private Zone
-@subsection The Private Zone
-
-
-The private zone is a subzone (or subdomain in DNS terms) of your
-master zone. It should be used for records that you want to keep
-private. For example @code{bank.private.gnu}. The key idea is that
-you want to keep your private records separate, if just to know
-that those names are not available to other users.
-
-@node The Shorten Zone
-@subsection The Shorten Zone
-
-
-The shorten zone can either be a subzone of the master zone or the
-private zone. It is different from the other zones in that GNS
-will automatically populate this zone with other users' zones based
-on their PSEU records whenever you resolve a name.
-
-For example if you go to
-@code{@uref{http://www.bob.alice.dave.gnu/, www.bob.alice.dave.gnu}},
-GNS will try to import @code{bob} into your shorten zone. Having
-obtained Bob's PKEY from @code{alice.dave.gnu}, GNS will lookup the
-PSEU record for @code{+} in Bob's zone. If it exists and the specified
-pseudonym is not taken, Bob's PKEY will be automatically added under
-that pseudonym (i.e. "bob") into your shorten zone. From then on,
-Bob's webpage will also be available for you as
-@code{@uref{http://www.bob.short.gnu/, www.bob.short.gnu}}.
-This feature is called @b{automatic name shortening} and is supposed to
-keep GNS names as short and memorable as possible.
-
-@node The ZKEY Top Level Domain in GNS
-@subsection The ZKEY Top Level Domain in GNS
-
-
-GNS also provides a secure and globally unique namespace under the .zkey
-top-level domain. A name in the .zkey TLD corresponds to the (printable)
-public key of a zone. Names in the .zkey TLD are then resolved by querying
-the respective zone. The .zkey TLD is expected to be used under rare
-circumstances where globally unique names are required and for
+GNS also assumes responsibility for any name that uses in a well-formed
+public key for the TLD.  Names ending this way are then resolved by querying
+the respective zone. Such public key TLDs are expected to be used under rare
+circumstances where globally unique names are required, and for
 integration with legacy systems.
 
 @node Resource Records in GNS
@@ -1682,7 +1625,7 @@ to the current authoritative zone. The extended processing of those
 names will expand the ".+" with the correct delegation chain to the
 authoritative zone (replacing ".+" with the name of the location
 where the name was encountered) and hence generate a
-valid @code{.gnu} name.
+valid GNS name.
 
 GNS currently supports the following record types:
 
@@ -1703,21 +1646,23 @@ GNS currently supports the following record types:
 
 A NICK record is used to give a zone a name. With a NICK record, you can
 essentially specify how you would like to be called. GNS expects this
-record under the name "+" in the zone's database (NAMESTORE); however,
+record under the empty label ``@atchar{}'' in the zone's database (NAMESTORE); however,
 it will then automatically be copied into each record set, so that
 clients never need to do a separate lookup to discover the NICK record.
+Also, users do not usually have to worry about setting the NICK record:
+it is automatically set to the local name of the TLD.
 
 @b{Example}@
 
 @example
-Name: +; RRType: NICK; Value: bob
+Name: @atchar{}; RRType: NICK; Value: bob
 @end example
 
 @noindent
 This record in Bob's zone will tell other users that this zone wants
 to be referred to as 'bob'. Note that nobody is obliged to call Bob's
 zone 'bob' in their own zones. It can be seen as a
-recommendation ("Please call me 'bob'").
+recommendation ("Please call this zone 'bob'").
 
 @node PKEY
 @subsubsection PKEY
@@ -1864,6 +1809,36 @@ should use the ZKEY zone as the destination hostname and
 GNS-enabled mail servers should be configured to accept
 e-mails to the ZKEY-zones of all local users.
 
+@node Synchronizing with legacy DNS
+@subsection Synchronizing with legacy DNS
+
+If you want to support GNS but the master database for a zone
+is only available and maintained in DNS, GNUnet includes the
+@command{gnunet-zoneimport} tool to monitor a DNS zone and
+automatically import records into GNS.  Today, the tool does
+not yet support DNS AF(X)R, as we initially used it on the
+``.fr'' zone which does not allow us to perform a DNS zone
+transfer.  Instead, @command{gnunet-zoneimport} reads a list
+of DNS domain names from @code{stdin}, issues DNS queries for
+each, converts the obtained records (if possible) and stores
+the result in the namestore.
+
+@image{images/gns,6in,, picture of DNS-GNS data flow}
+
+The zonemaster service then takes the records from the namestore,
+publishes them into the DHT which makes the result available to the
+GNS resolver.  In the GNS configuration, non-local zones can be
+configured to be intercepted by specifying ``.tld = PUBLICKEY'' in the
+configuration file in the ``[gns]'' section.
+
+Note that the namestore by default also populates the namecache.
+This pre-population is cryptographically expensive. Thus, on
+systems that only serve to import a large (millions of records)
+DNS zone and that do not have a local gns service in use, it
+is thus advisable to disable the namecache by setting the
+option ``DISABLE'' to ``YES'' in section ``[namecache]''.
+
+
 @node Using the Virtual Public Network
 @section Using the Virtual Public Network
 
diff --git a/doc/documentation/images/gns.dot b/doc/documentation/images/gns.dot
new file mode 100644
index 0000000000..55b05d4820
--- /dev/null
+++ b/doc/documentation/images/gns.dot
@@ -0,0 +1,42 @@
+// house = interface towards application
+// circle (default) = storage
+// diamond = stateless tool
+// box = legacy system
+
+// this is what we have...o
+digraph dataflow {
+splines = true;
+
+  DNS [shape="box"];
+  import [label="gnunet-zoneimport", shape="diamond"];
+  namestore;
+  namecache;
+  gns [shape="diamond"];
+  dns2gns [shape="house"];
+  cmdline [label="gnunet-gns", shape="house"];
+  libnss_gns [shape="house"];
+  proxy [label="gnunet-gns-proxy", shape="house"];
+  dht;
+  zonemaster [shape="diamond"];
+
+  DNS -> import [label="import"];
+  import -> namestore [label="export"];
+
+  namestore -> zonemaster [label="notifies"];
+  zonemaster -> dht [label="publishes"];
+
+  namestore -> namecache [label="pre-populates"];
+
+
+
+  libnss_gns -> cmdline [label="invokes"];
+  cmdline -> gns [label="lookup"];
+
+  dns2gns -> gns [label="lookup"];
+
+  proxy -> gns [label="lookup"];
+
+  gns -> namecache [label="uses"];
+  gns -> dht [label="queries"];
+
+}