diff options
Diffstat (limited to 'doc/documentation/chapters/user.texi')
-rw-r--r-- | doc/documentation/chapters/user.texi | 179 |
1 files changed, 77 insertions, 102 deletions
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 | ||
1484 | To setup your GNS system you must execute: | 1482 | To use GNS, you probably should create at least one zone of your own. |
1483 | You can create any number of zones using the gnunet-identity tool | ||
1484 | using: | ||
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 | 1490 | Henceforth, on your system you control the TLD ``myzone''. |
1491 | This will boostrap your zones and create the necessary key material. | 1491 | |
1492 | Your keys can be listed using the @command{gnunet-identity} | 1492 | All of your zones can be listed using the @command{gnunet-identity} |
1493 | command line tool: | 1493 | command 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 |
1500 | You can arbitrarily create your own zones using the gnunet-identity | 1500 | @subsection Maintaining your own Zones |
1501 | tool using: | ||
1502 | |||
1503 | @example | ||
1504 | $ gnunet-identity -C "new_zone" | ||
1505 | @end example | ||
1506 | 1501 | ||
1507 | @noindent | 1502 | @noindent |
1508 | Now you can add (or edit, or remove) records in your GNS zone using the | 1503 | Now 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} |
1510 | command-line tool. | 1505 | command-line tool. |
1511 | In either case, your records will be stored in an SQL database under | 1506 | In either case, your records will be stored in an SQL database under |
1512 | control of the @command{gnunet-service-namestore}. | 1507 | control of the @command{gnunet-service-namestore}. |
@@ -1518,21 +1513,21 @@ if they are marked as private. | |||
1518 | To provide a short example for editing your own zone, suppose you | 1513 | To provide a short example for editing your own zone, suppose you |
1519 | have your own web server with the IP @code{1.2.3.4}. Then you can put an | 1514 | have 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) |
1521 | into your local zone using the command: | 1516 | into 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 |
1528 | Afterwards, you will be able to access your webpage under "www.gnu" | 1523 | Afterwards, 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, |
1530 | please read up on setting up the GNS proxy). | 1525 | please read up on setting up the GNS proxy). |
1531 | 1526 | ||
1532 | Similar commands will work for other types of DNS and GNS records, | 1527 | Similar commands will work for other types of DNS and GNS records, |
1533 | the syntax largely depending on the type of the record. | 1528 | the syntax largely depending on the type of the record. |
1534 | Naturally, most users may find editing the zones using the | 1529 | Naturally, 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. | |||
1546 | You can usually get the hash of your public key using | 1541 | You 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 |
1560 | Alternatively, you can obtain a QR code with your zone key AND | 1555 | Alternatively, you can obtain a QR code with your zone key AND your |
1561 | your pseudonym from gnunet-gtk. The QR code is displayed in the | 1556 | pseudonym from gnunet-namestore-gtk. The QR code is displayed in the |
1562 | GNS tab and can be stored to disk using the Save as button next | 1557 | main window and can be stored to disk using the ``Save as'' button |
1563 | to the image. | 1558 | next 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 | |||
1576 | a PKEY record to their local zone: | 1571 | a 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 |
1583 | Note that XXXX in the command above must be replaced with the | 1578 | Note that ``XXXX'' in the command above must be replaced with the hash |
1584 | hash of Bob's public key (the output your friend obtained using | 1579 | of Bob's public key (the output your friend obtained using the |
1585 | the gnunet-identity command from the previous section and told you, | 1580 | @command{gnunet-identity} command from the previous section and told |
1586 | for example by giving you a business card containing this | 1581 | you, for example by giving you a business card containing this |
1587 | information as a QR code). | 1582 | information as a QR code). |
1588 | 1583 | ||
1589 | Assuming Bob has an A record for their website under the name of | 1584 | Assuming Bob has an ``A'' record for their website under the name of |
1590 | www in his zone, you can then access Bob's website under | 1585 | ``www'' in his zone, you can then access Bob's website under |
1591 | www.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 |
1592 | in their zone by replacing www with the respective name of the | 1587 | in their zone by replacing www with the respective name of the |
1593 | record in Bob's zone. | 1588 | record in Bob's zone. |
1594 | 1589 | ||
1595 | @c themselves? themself? | 1590 | @c themselves? themself? |
1596 | Furthermore, if Bob has themselves a (public) delegation to Carol's | 1591 | Furthermore, if Bob has themselves a (public) delegation to Carol's |
1597 | zone under "carol", you can access Carol's records under | 1592 | zone under "carol", you can access Carol's records under |
1598 | NAME.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 |
1599 | want to access). | 1594 | record you want to access). |
1600 | |||
1601 | @node The Three Local Zones of GNS | ||
1602 | @subsection The Three Local Zones of GNS | ||
1603 | 1595 | ||
1604 | Each user GNS has control over three zones. Each of the zones | ||
1605 | has 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 | 1601 | GNS also assumes responsibility for any name that uses in a well-formed | |
1618 | The master zone is your personal TLD. Names within the @code{.gnu} | 1602 | public key for the TLD. Names ending this way are then resolved by querying |
1619 | namespace are resolved relative to this zone. You can arbitrarily | 1603 | the respective zone. Such public key TLDs are expected to be used under rare |
1620 | add records to this zone and selectively publish those records. | 1604 | circumstances where globally unique names are required, and for |
1621 | |||
1622 | @node The Private Zone | ||
1623 | @subsection The Private Zone | ||
1624 | |||
1625 | |||
1626 | The private zone is a subzone (or subdomain in DNS terms) of your | ||
1627 | master zone. It should be used for records that you want to keep | ||
1628 | private. For example @code{bank.private.gnu}. The key idea is that | ||
1629 | you want to keep your private records separate, if just to know | ||
1630 | that those names are not available to other users. | ||
1631 | |||
1632 | @node The Shorten Zone | ||
1633 | @subsection The Shorten Zone | ||
1634 | |||
1635 | |||
1636 | The shorten zone can either be a subzone of the master zone or the | ||
1637 | private zone. It is different from the other zones in that GNS | ||
1638 | will automatically populate this zone with other users' zones based | ||
1639 | on their PSEU records whenever you resolve a name. | ||
1640 | |||
1641 | For example if you go to | ||
1642 | @code{@uref{http://www.bob.alice.dave.gnu/, www.bob.alice.dave.gnu}}, | ||
1643 | GNS will try to import @code{bob} into your shorten zone. Having | ||
1644 | obtained Bob's PKEY from @code{alice.dave.gnu}, GNS will lookup the | ||
1645 | PSEU record for @code{+} in Bob's zone. If it exists and the specified | ||
1646 | pseudonym is not taken, Bob's PKEY will be automatically added under | ||
1647 | that pseudonym (i.e. "bob") into your shorten zone. From then on, | ||
1648 | Bob's webpage will also be available for you as | ||
1649 | @code{@uref{http://www.bob.short.gnu/, www.bob.short.gnu}}. | ||
1650 | This feature is called @b{automatic name shortening} and is supposed to | ||
1651 | keep 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 | |||
1657 | GNS also provides a secure and globally unique namespace under the .zkey | ||
1658 | top-level domain. A name in the .zkey TLD corresponds to the (printable) | ||
1659 | public key of a zone. Names in the .zkey TLD are then resolved by querying | ||
1660 | the respective zone. The .zkey TLD is expected to be used under rare | ||
1661 | circumstances where globally unique names are required and for | ||
1662 | integration with legacy systems. | 1605 | integration 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 | |||
1682 | names will expand the ".+" with the correct delegation chain to the | 1625 | names will expand the ".+" with the correct delegation chain to the |
1683 | authoritative zone (replacing ".+" with the name of the location | 1626 | authoritative zone (replacing ".+" with the name of the location |
1684 | where the name was encountered) and hence generate a | 1627 | where the name was encountered) and hence generate a |
1685 | valid @code{.gnu} name. | 1628 | valid GNS name. |
1686 | 1629 | ||
1687 | GNS currently supports the following record types: | 1630 | GNS currently supports the following record types: |
1688 | 1631 | ||
@@ -1703,21 +1646,23 @@ GNS currently supports the following record types: | |||
1703 | 1646 | ||
1704 | A NICK record is used to give a zone a name. With a NICK record, you can | 1647 | A NICK record is used to give a zone a name. With a NICK record, you can |
1705 | essentially specify how you would like to be called. GNS expects this | 1648 | essentially specify how you would like to be called. GNS expects this |
1706 | record under the name "+" in the zone's database (NAMESTORE); however, | 1649 | record under the empty label ``@atchar{}'' in the zone's database (NAMESTORE); however, |
1707 | it will then automatically be copied into each record set, so that | 1650 | it will then automatically be copied into each record set, so that |
1708 | clients never need to do a separate lookup to discover the NICK record. | 1651 | clients never need to do a separate lookup to discover the NICK record. |
1652 | Also, users do not usually have to worry about setting the NICK record: | ||
1653 | it is automatically set to the local name of the TLD. | ||
1709 | 1654 | ||
1710 | @b{Example}@ | 1655 | @b{Example}@ |
1711 | 1656 | ||
1712 | @example | 1657 | @example |
1713 | Name: +; RRType: NICK; Value: bob | 1658 | Name: @atchar{}; RRType: NICK; Value: bob |
1714 | @end example | 1659 | @end example |
1715 | 1660 | ||
1716 | @noindent | 1661 | @noindent |
1717 | This record in Bob's zone will tell other users that this zone wants | 1662 | This record in Bob's zone will tell other users that this zone wants |
1718 | to be referred to as 'bob'. Note that nobody is obliged to call Bob's | 1663 | to be referred to as 'bob'. Note that nobody is obliged to call Bob's |
1719 | zone 'bob' in their own zones. It can be seen as a | 1664 | zone 'bob' in their own zones. It can be seen as a |
1720 | recommendation ("Please call me 'bob'"). | 1665 | recommendation ("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 | |||
1864 | GNS-enabled mail servers should be configured to accept | 1809 | GNS-enabled mail servers should be configured to accept |
1865 | e-mails to the ZKEY-zones of all local users. | 1810 | e-mails to the ZKEY-zones of all local users. |
1866 | 1811 | ||
1812 | @node Synchronizing with legacy DNS | ||
1813 | @subsection Synchronizing with legacy DNS | ||
1814 | |||
1815 | If you want to support GNS but the master database for a zone | ||
1816 | is only available and maintained in DNS, GNUnet includes the | ||
1817 | @command{gnunet-zoneimport} tool to monitor a DNS zone and | ||
1818 | automatically import records into GNS. Today, the tool does | ||
1819 | not 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 | ||
1821 | transfer. Instead, @command{gnunet-zoneimport} reads a list | ||
1822 | of DNS domain names from @code{stdin}, issues DNS queries for | ||
1823 | each, converts the obtained records (if possible) and stores | ||
1824 | the result in the namestore. | ||
1825 | |||
1826 | @image{images/gns,6in,, picture of DNS-GNS data flow} | ||
1827 | |||
1828 | The zonemaster service then takes the records from the namestore, | ||
1829 | publishes them into the DHT which makes the result available to the | ||
1830 | GNS resolver. In the GNS configuration, non-local zones can be | ||
1831 | configured to be intercepted by specifying ``.tld = PUBLICKEY'' in the | ||
1832 | configuration file in the ``[gns]'' section. | ||
1833 | |||
1834 | Note that the namestore by default also populates the namecache. | ||
1835 | This pre-population is cryptographically expensive. Thus, on | ||
1836 | systems that only serve to import a large (millions of records) | ||
1837 | DNS zone and that do not have a local gns service in use, it | ||
1838 | is thus advisable to disable the namecache by setting the | ||
1839 | option ``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 | ||