[GNUnet-SVN] [gnunet] branch master updated: update user documentation on GNS, include gnunet-zoneimport

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository gnunet.

The following commit(s) were added to refs/heads/master by this push:
     new 85015bdbd update user documentation on GNS, include gnunet-zoneimport
85015bdbd is described below

commit 85015bdbd2ec726683b61a3b41d1ce162b246154
Author: Christian Grothoff <address@hidden>
AuthorDate: Sun May 6 15:23:10 2018 +0200

    update user documentation on GNS, include gnunet-zoneimport
---
 doc/documentation/Makefile.am                |   3 +-
 doc/documentation/chapters/installation.texi |  30 +----
 doc/documentation/chapters/user.texi         | 179 ++++++++++++---------------
 doc/documentation/images/gns.dot             |  42 +++++++
 4 files changed, 127 insertions(+), 127 deletions(-)

diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am
index 991b1926b..1bd25f773 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 3a76fb162..6eb1a88a0 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}
 
address@hidden Automatic Shortening in the GNU Name System
address@hidden 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 8ce8b52e2..6063392ac 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
 
 
address@hidden Maintaining your own Zones
address@hidden Maintaining your own Zones
address@hidden Creating a Zone
address@hidden 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
 
address@hidden
-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
 
address@hidden
-You can arbitrarily create your own zones using the gnunet-identity
-tool using:
-
address@hidden
-$ gnunet-identity -C "new_zone"
address@hidden example
address@hidden Maintaining your own Zones
address@hidden Maintaining your own Zones
 
 @noindent
 Now you can add (or edit, or remove) records in your GNS zone using the
address@hidden GUI or using the @command{gnunet-namestore}
address@hidden 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
address@hidden GUI to be easier.
address@hidden 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 address@hidden'
+$ gnunet-identity -d $options | grep myzone | awk '@{print address@hidden'
 @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
address@hidden 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).
-
address@hidden The Three Local Zones of GNS
address@hidden 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
 
address@hidden @bullet
-
address@hidden master zone,
address@hidden private zone, and the
address@hidden shorten zone.
address@hidden itemize
address@hidden Using Public Keys as Top Level Domains
address@hidden Using Public Keys as Top Level Domains
 
address@hidden The Master Zone
address@hidden 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.
-
address@hidden The Private Zone
address@hidden 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.
-
address@hidden The Shorten Zone
address@hidden 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
address@hidden@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
address@hidden@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.
-
address@hidden The ZKEY Top Level Domain in GNS
address@hidden 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 address@hidden'' 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.
 
address@hidden Synchronizing with legacy DNS
address@hidden 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
address@hidden 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.
+
address@hidden/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 000000000..55b05d482
--- /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"];
+
+}

-- 
To stop receiving notification emails like this one, please contact
address@hidden