aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2018-05-06 15:23:10 +0200
committerChristian Grothoff <christian@grothoff.org>2018-05-06 15:23:10 +0200
commit85015bdbd2ec726683b61a3b41d1ce162b246154 (patch)
tree78d8944d3a9cb8c30ae293b8f587b292bae1f067 /doc
parent645b26ba88218c4a2f9a022968a8c03e9035082d (diff)
downloadgnunet-85015bdbd2ec726683b61a3b41d1ce162b246154.tar.gz
gnunet-85015bdbd2ec726683b61a3b41d1ce162b246154.zip
update user documentation on GNS, include gnunet-zoneimport
Diffstat (limited to 'doc')
-rw-r--r--doc/documentation/Makefile.am3
-rw-r--r--doc/documentation/chapters/installation.texi30
-rw-r--r--doc/documentation/chapters/user.texi179
-rw-r--r--doc/documentation/images/gns.dot42
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 = \
44 images/daemon_lego_block.svg \ 44 images/daemon_lego_block.svg \
45 images/lego_stack.svg \ 45 images/lego_stack.svg \
46 images/service_lego_block.svg \ 46 images/service_lego_block.svg \
47 images/structure.dot 47 images/structure.dot \
48 images/gns.dot
48 49
49# images/$(wildcard *.png) \ 50# images/$(wildcard *.png) \
50# images/$(wildcard *.svg) 51# 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:
3290* GNS Proxy Setup:: 3290* GNS Proxy Setup::
3291* Setup of the GNS CA:: 3291* Setup of the GNS CA::
3292* Testing the GNS setup:: 3292* Testing the GNS setup::
3293* Automatic Shortening in the GNU Name System::
3294@end menu 3293@end menu
3295 3294
3296 3295
@@ -3526,8 +3525,11 @@ Now for testing purposes we can create some records in our zone to test
3526the SSL functionality of the proxy: 3525the SSL functionality of the proxy:
3527 3526
3528@example 3527@example
3529$ gnunet-namestore -a -e "1 d" -n "homepage" -t A -V 131.159.74.67 3528$ gnunet-identity -C test
3530$ gnunet-namestore -a -e "1 d" -n "homepage" -t LEHO -V "gnunet.org" 3529$ gnunet-namestore -a -e "1 d" -n "homepage" \
3530 -t A -V 131.159.74.67 -z test
3531$ gnunet-namestore -a -e "1 d" -n "homepage" \
3532 -t LEHO -V "gnunet.org" -z test
3531@end example 3533@end example
3532 3534
3533@noindent 3535@noindent
@@ -3544,7 +3546,7 @@ If you use @command{Firefox} (or one of its deriviates/forks such as
3544Icecat) you also have to go to @code{about:config} and set the key 3546Icecat) you also have to go to @code{about:config} and set the key
3545@code{network.proxy.socks_remote_dns} to @code{true}. 3547@code{network.proxy.socks_remote_dns} to @code{true}.
3546 3548
3547When you visit @code{https://homepage.gnu/}, you should get to the 3549When you visit @code{https://homepage.test/}, you should get to the
3548@code{https://gnunet.org/} frontpage and the browser (with the correctly 3550@code{https://gnunet.org/} frontpage and the browser (with the correctly
3549configured proxy) should give you a valid SSL certificate for 3551configured proxy) should give you a valid SSL certificate for
3550@code{homepage.gnu} and no warnings. It should look like this: 3552@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
3552@c FIXME: Image does not exist, create it or save it from Drupal? 3554@c FIXME: Image does not exist, create it or save it from Drupal?
3553@c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} 3555@c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser}
3554 3556
3555@node Automatic Shortening in the GNU Name System
3556@subsubsection Automatic Shortening in the GNU Name System
3557
3558This page describes a possible option for 'automatic name shortening',
3559which you can choose to enable with the GNU Name System.
3560
3561When GNS encounters a name for the first time, it can use the 'NICK'
3562record of the originating zone to automatically generate a name for the
3563zone. If automatic shortening is enabled, those auto-generated names will
3564be placed (as private records) into your personal 'shorten' zone (to
3565prevent confusion with manually selected names).
3566Then, in the future, if the same name is encountered again, GNS will
3567display the shortened name instead (the first time, the long name will
3568still be used as shortening typically happens asynchronously as looking up
3569the 'NICK' record takes some time). Using this feature can be a convenient
3570way to avoid very long @code{.gnu} names; however, note that names from
3571the shorten-zone are assigned on a first-come-first-serve basis and should
3572not be trusted. Furthermore, if you enable this feature, you will no
3573longer see the full delegation chain for zones once shortening has been
3574applied.
3575 3557
3576@node Configuring the GNUnet VPN 3558@node Configuring the GNUnet VPN
3577@subsection Configuring the GNUnet VPN 3559@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
1466 1466
1467 1467
1468@menu 1468@menu
1469* Creating a Zone::
1469* Maintaining your own Zones:: 1470* Maintaining your own Zones::
1470* Obtaining your Zone Key:: 1471* Obtaining your Zone Key::
1471* Adding Links to Other Zones:: 1472* Adding Links to Other Zones::
1472* The Three Local Zones of GNS:: 1473* Using Public Keys as Top Level Domains::
1473* The Master Zone::
1474* The Private Zone::
1475* The Shorten Zone::
1476* The ZKEY Top Level Domain in GNS::
1477* Resource Records in GNS:: 1474* Resource Records in GNS::
1475* Synchronizing with legacy DNS::
1478@end menu 1476@end menu
1479 1477
1480 1478
1481@node Maintaining your own Zones 1479@node Creating a Zone
1482@subsection Maintaining your own Zones 1480@subsection Creating a Zone
1483 1481
1484To setup your GNS system you must execute: 1482To use GNS, you probably should create at least one zone of your own.
1483You can create any number of zones using the gnunet-identity tool
1484using:
1485 1485
1486@example 1486@example
1487$ gnunet-gns-import.sh 1487$ gnunet-identity -C "myzone"
1488@end example 1488@end example
1489 1489
1490@noindent 1490Henceforth, on your system you control the TLD ``myzone''.
1491This will boostrap your zones and create the necessary key material. 1491
1492Your keys can be listed using the @command{gnunet-identity} 1492All of your zones can be listed using the @command{gnunet-identity}
1493command line tool: 1493command line tool as well:
1494 1494
1495@example 1495@example
1496$ gnunet-identity -d 1496$ gnunet-identity -d
1497@end example 1497@end example
1498 1498
1499@noindent 1499@node Maintaining your own Zones
1500You can arbitrarily create your own zones using the gnunet-identity 1500@subsection Maintaining your own Zones
1501tool using:
1502
1503@example
1504$ gnunet-identity -C "new_zone"
1505@end example
1506 1501
1507@noindent 1502@noindent
1508Now you can add (or edit, or remove) records in your GNS zone using the 1503Now you can add (or edit, or remove) records in your GNS zone using the
1509@command{gnunet-setup} GUI or using the @command{gnunet-namestore} 1504@command{gnunet-namestore-gtk} GUI or using the @command{gnunet-namestore}
1510command-line tool. 1505command-line tool.
1511In either case, your records will be stored in an SQL database under 1506In either case, your records will be stored in an SQL database under
1512control of the @command{gnunet-service-namestore}. 1507control of the @command{gnunet-service-namestore}.
@@ -1518,21 +1513,21 @@ if they are marked as private.
1518To provide a short example for editing your own zone, suppose you 1513To provide a short example for editing your own zone, suppose you
1519have your own web server with the IP @code{1.2.3.4}. Then you can put an 1514have your own web server with the IP @code{1.2.3.4}. Then you can put an
1520@code{A} record (@code{A} records in DNS are for IPv4 IP addresses) 1515@code{A} record (@code{A} records in DNS are for IPv4 IP addresses)
1521into your local zone using the command: 1516into your local zone ``myzone'' using the command:
1522 1517
1523@example 1518@example
1524$ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never 1519$ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e never
1525@end example 1520@end example
1526 1521
1527@noindent 1522@noindent
1528Afterwards, you will be able to access your webpage under "www.gnu" 1523Afterwards, you will be able to access your webpage under "www.myzone"
1529(assuming your webserver does not use virtual hosting, if it does, 1524(assuming your webserver does not use virtual hosting, if it does,
1530please read up on setting up the GNS proxy). 1525please read up on setting up the GNS proxy).
1531 1526
1532Similar commands will work for other types of DNS and GNS records, 1527Similar commands will work for other types of DNS and GNS records,
1533the syntax largely depending on the type of the record. 1528the syntax largely depending on the type of the record.
1534Naturally, most users may find editing the zones using the 1529Naturally, most users may find editing the zones using the
1535@command{gnunet-setup} GUI to be easier. 1530@command{gnunet-namestore-gtk} GUI to be easier.
1536 1531
1537@node Obtaining your Zone Key 1532@node Obtaining your Zone Key
1538@subsection Obtaining your Zone Key 1533@subsection Obtaining your Zone Key
@@ -1546,7 +1541,7 @@ give it to others so that they can securely link to you.
1546You can usually get the hash of your public key using 1541You can usually get the hash of your public key using
1547 1542
1548@example 1543@example
1549$ gnunet-identity -d $options | grep master-zone | awk '@{print $3@}' 1544$ gnunet-identity -d $options | grep myzone | awk '@{print $3@}'
1550@end example 1545@end example
1551 1546
1552@noindent 1547@noindent
@@ -1557,10 +1552,10 @@ DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0
1557@end example 1552@end example
1558 1553
1559@noindent 1554@noindent
1560Alternatively, you can obtain a QR code with your zone key AND 1555Alternatively, you can obtain a QR code with your zone key AND your
1561your pseudonym from gnunet-gtk. The QR code is displayed in the 1556pseudonym from gnunet-namestore-gtk. The QR code is displayed in the
1562GNS tab and can be stored to disk using the Save as button next 1557main window and can be stored to disk using the ``Save as'' button
1563to the image. 1558next to the image.
1564 1559
1565@node Adding Links to Other Zones 1560@node Adding Links to Other Zones
1566@subsection Adding Links to Other Zones 1561@subsection Adding Links to Other Zones
@@ -1576,89 +1571,37 @@ You can then delegate resolution of names to Bob's zone by adding
1576a PKEY record to their local zone: 1571a PKEY record to their local zone:
1577 1572
1578@example 1573@example
1579$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never 1574$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never -Z myzone
1580@end example 1575@end example
1581 1576
1582@noindent 1577@noindent
1583Note that XXXX in the command above must be replaced with the 1578Note that ``XXXX'' in the command above must be replaced with the hash
1584hash of Bob's public key (the output your friend obtained using 1579of Bob's public key (the output your friend obtained using the
1585the gnunet-identity command from the previous section and told you, 1580@command{gnunet-identity} command from the previous section and told
1586for example by giving you a business card containing this 1581you, for example by giving you a business card containing this
1587information as a QR code). 1582information as a QR code).
1588 1583
1589Assuming Bob has an A record for their website under the name of 1584Assuming Bob has an ``A'' record for their website under the name of
1590www in his zone, you can then access Bob's website under 1585``www'' in his zone, you can then access Bob's website under
1591www.bob.gnu --- as well as any (public) GNS record that Bob has 1586``www.bob.myzone'' --- as well as any (public) GNS record that Bob has
1592in their zone by replacing www with the respective name of the 1587in their zone by replacing www with the respective name of the
1593record in Bob's zone. 1588record in Bob's zone.
1594 1589
1595@c themselves? themself? 1590@c themselves? themself?
1596Furthermore, if Bob has themselves a (public) delegation to Carol's 1591Furthermore, if Bob has themselves a (public) delegation to Carol's
1597zone under "carol", you can access Carol's records under 1592zone under "carol", you can access Carol's records under
1598NAME.carol.bob.gnu (where NAME is the name of Carol's record you 1593``NAME.carol.bob.myzone'' (where ``NAME'' is the name of Carol's
1599want to access). 1594record you want to access).
1600
1601@node The Three Local Zones of GNS
1602@subsection The Three Local Zones of GNS
1603 1595
1604Each user GNS has control over three zones. Each of the zones
1605has a different purpose. These zones are the
1606 1596
1607@itemize @bullet 1597@node Using Public Keys as Top Level Domains
1608 1598@subsection Using Public Keys as Top Level Domains
1609@item master zone,
1610@item private zone, and the
1611@item shorten zone.
1612@end itemize
1613 1599
1614@node The Master Zone
1615@subsection The Master Zone
1616 1600
1617 1601GNS also assumes responsibility for any name that uses in a well-formed
1618The master zone is your personal TLD. Names within the @code{.gnu} 1602public key for the TLD. Names ending this way are then resolved by querying
1619namespace are resolved relative to this zone. You can arbitrarily 1603the respective zone. Such public key TLDs are expected to be used under rare
1620add records to this zone and selectively publish those records. 1604circumstances where globally unique names are required, and for
1621
1622@node The Private Zone
1623@subsection The Private Zone
1624
1625
1626The private zone is a subzone (or subdomain in DNS terms) of your
1627master zone. It should be used for records that you want to keep
1628private. For example @code{bank.private.gnu}. The key idea is that
1629you want to keep your private records separate, if just to know
1630that those names are not available to other users.
1631
1632@node The Shorten Zone
1633@subsection The Shorten Zone
1634
1635
1636The shorten zone can either be a subzone of the master zone or the
1637private zone. It is different from the other zones in that GNS
1638will automatically populate this zone with other users' zones based
1639on their PSEU records whenever you resolve a name.
1640
1641For example if you go to
1642@code{@uref{http://www.bob.alice.dave.gnu/, www.bob.alice.dave.gnu}},
1643GNS will try to import @code{bob} into your shorten zone. Having
1644obtained Bob's PKEY from @code{alice.dave.gnu}, GNS will lookup the
1645PSEU record for @code{+} in Bob's zone. If it exists and the specified
1646pseudonym is not taken, Bob's PKEY will be automatically added under
1647that pseudonym (i.e. "bob") into your shorten zone. From then on,
1648Bob's webpage will also be available for you as
1649@code{@uref{http://www.bob.short.gnu/, www.bob.short.gnu}}.
1650This feature is called @b{automatic name shortening} and is supposed to
1651keep GNS names as short and memorable as possible.
1652
1653@node The ZKEY Top Level Domain in GNS
1654@subsection The ZKEY Top Level Domain in GNS
1655
1656
1657GNS also provides a secure and globally unique namespace under the .zkey
1658top-level domain. A name in the .zkey TLD corresponds to the (printable)
1659public key of a zone. Names in the .zkey TLD are then resolved by querying
1660the respective zone. The .zkey TLD is expected to be used under rare
1661circumstances where globally unique names are required and for
1662integration with legacy systems. 1605integration with legacy systems.
1663 1606
1664@node Resource Records in GNS 1607@node Resource Records in GNS
@@ -1682,7 +1625,7 @@ to the current authoritative zone. The extended processing of those
1682names will expand the ".+" with the correct delegation chain to the 1625names will expand the ".+" with the correct delegation chain to the
1683authoritative zone (replacing ".+" with the name of the location 1626authoritative zone (replacing ".+" with the name of the location
1684where the name was encountered) and hence generate a 1627where the name was encountered) and hence generate a
1685valid @code{.gnu} name. 1628valid GNS name.
1686 1629
1687GNS currently supports the following record types: 1630GNS currently supports the following record types:
1688 1631
@@ -1703,21 +1646,23 @@ GNS currently supports the following record types:
1703 1646
1704A NICK record is used to give a zone a name. With a NICK record, you can 1647A NICK record is used to give a zone a name. With a NICK record, you can
1705essentially specify how you would like to be called. GNS expects this 1648essentially specify how you would like to be called. GNS expects this
1706record under the name "+" in the zone's database (NAMESTORE); however, 1649record under the empty label ``@atchar{}'' in the zone's database (NAMESTORE); however,
1707it will then automatically be copied into each record set, so that 1650it will then automatically be copied into each record set, so that
1708clients never need to do a separate lookup to discover the NICK record. 1651clients never need to do a separate lookup to discover the NICK record.
1652Also, users do not usually have to worry about setting the NICK record:
1653it is automatically set to the local name of the TLD.
1709 1654
1710@b{Example}@ 1655@b{Example}@
1711 1656
1712@example 1657@example
1713Name: +; RRType: NICK; Value: bob 1658Name: @atchar{}; RRType: NICK; Value: bob
1714@end example 1659@end example
1715 1660
1716@noindent 1661@noindent
1717This record in Bob's zone will tell other users that this zone wants 1662This record in Bob's zone will tell other users that this zone wants
1718to be referred to as 'bob'. Note that nobody is obliged to call Bob's 1663to be referred to as 'bob'. Note that nobody is obliged to call Bob's
1719zone 'bob' in their own zones. It can be seen as a 1664zone 'bob' in their own zones. It can be seen as a
1720recommendation ("Please call me 'bob'"). 1665recommendation ("Please call this zone 'bob'").
1721 1666
1722@node PKEY 1667@node PKEY
1723@subsubsection PKEY 1668@subsubsection PKEY
@@ -1864,6 +1809,36 @@ should use the ZKEY zone as the destination hostname and
1864GNS-enabled mail servers should be configured to accept 1809GNS-enabled mail servers should be configured to accept
1865e-mails to the ZKEY-zones of all local users. 1810e-mails to the ZKEY-zones of all local users.
1866 1811
1812@node Synchronizing with legacy DNS
1813@subsection Synchronizing with legacy DNS
1814
1815If you want to support GNS but the master database for a zone
1816is only available and maintained in DNS, GNUnet includes the
1817@command{gnunet-zoneimport} tool to monitor a DNS zone and
1818automatically import records into GNS. Today, the tool does
1819not yet support DNS AF(X)R, as we initially used it on the
1820``.fr'' zone which does not allow us to perform a DNS zone
1821transfer. Instead, @command{gnunet-zoneimport} reads a list
1822of DNS domain names from @code{stdin}, issues DNS queries for
1823each, converts the obtained records (if possible) and stores
1824the result in the namestore.
1825
1826@image{images/gns,6in,, picture of DNS-GNS data flow}
1827
1828The zonemaster service then takes the records from the namestore,
1829publishes them into the DHT which makes the result available to the
1830GNS resolver. In the GNS configuration, non-local zones can be
1831configured to be intercepted by specifying ``.tld = PUBLICKEY'' in the
1832configuration file in the ``[gns]'' section.
1833
1834Note that the namestore by default also populates the namecache.
1835This pre-population is cryptographically expensive. Thus, on
1836systems that only serve to import a large (millions of records)
1837DNS zone and that do not have a local gns service in use, it
1838is thus advisable to disable the namecache by setting the
1839option ``DISABLE'' to ``YES'' in section ``[namecache]''.
1840
1841
1867@node Using the Virtual Public Network 1842@node Using the Virtual Public Network
1868@section Using the Virtual Public Network 1843@section Using the Virtual Public Network
1869 1844
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 @@
1// house = interface towards application
2// circle (default) = storage
3// diamond = stateless tool
4// box = legacy system
5
6// this is what we have...o
7digraph dataflow {
8splines = true;
9
10 DNS [shape="box"];
11 import [label="gnunet-zoneimport", shape="diamond"];
12 namestore;
13 namecache;
14 gns [shape="diamond"];
15 dns2gns [shape="house"];
16 cmdline [label="gnunet-gns", shape="house"];
17 libnss_gns [shape="house"];
18 proxy [label="gnunet-gns-proxy", shape="house"];
19 dht;
20 zonemaster [shape="diamond"];
21
22 DNS -> import [label="import"];
23 import -> namestore [label="export"];
24
25 namestore -> zonemaster [label="notifies"];
26 zonemaster -> dht [label="publishes"];
27
28 namestore -> namecache [label="pre-populates"];
29
30
31
32 libnss_gns -> cmdline [label="invokes"];
33 cmdline -> gns [label="lookup"];
34
35 dns2gns -> gns [label="lookup"];
36
37 proxy -> gns [label="lookup"];
38
39 gns -> namecache [label="uses"];
40 gns -> dht [label="queries"];
41
42}