5 This tutorial is supposed to give a first introduction for end-users
6 trying to do something "real" with GNUnet. Installation and
7 configuration are specifically outside of the scope of this tutorial.
8 Instead, we start by briefly checking that the installation works, and
9 then dive into uncomplicated, concrete practical things that can be done
12 This chapter of the GNUnet Reference Documentation documents
13 how to use the various peer-to-peer applications of the
15 As GNUnet evolves, we will add new chapters for the various
16 applications that are being created.
18 Comments and extensions of this documentation are always welcome.
22 * Checking the Installation::
23 * First steps - File-sharing::
24 * First steps - Using the GNU Name System::
25 * First steps - Using GNUnet Conversation::
26 * First steps - Using the GNUnet VPN::
28 * The GNU Name System::
29 * Using the Virtual Public Network::
32 @node Checking the Installation
33 @section Checking the Installation
36 This section describes a quick casual way to check if your GNUnet
37 installation works. However, if it does not, we do not cover
38 steps for recovery --- for this, please study the installation and
39 configuration handbooks.
49 @subsection gnunet-gtk
52 The @command{gnunet-gtk} package contains several graphical
53 user interfaces for the respective GNUnet applications.
58 @item Peer Information
61 @item Identity Management
66 @subsection Statistics
69 First, you should launch the graphical user interface. You can do
70 this from the command-line by typing
73 $ gnunet-statistics-gtk
76 If your peer is running correctly, you should see a bunch of
77 lines, all of which should be "significantly" above zero (at least if your
78 peer has been running for a few seconds). The lines indicate how many
80 peers your peer is connected to (via different mechanisms) and how large
81 the overall overlay network is currently estimated to be. The X-axis
82 represents time (in seconds since the start of @command{gnunet-gtk}).
84 You can click on "Traffic" to see information about the amount of
85 bandwidth your peer has consumed, and on "Storage" to check the amount
86 of storage available and used by your peer. Note that "Traffic" is
87 plotted cummulatively, so you should see a strict upwards trend in the
90 @node Peer Information
91 @subsection Peer Information
94 First, you should launch the graphical user interface. You can do
95 this from the command-line by typing
101 Once you have done this, you will see a list of known peers (by the
102 first four characters of their public key), their friend status (all
103 should be marked as not-friends initially), their connectivity (green
104 is connected, red is disconnected), assigned bandwidth, country of
105 origin (if determined) and address information. If hardly any peers
106 are listed and/or if there are very few peers with a green light for
107 connectivity, there is likely a problem with your network
110 @node First steps - File-sharing
111 @section First steps - File-sharing
114 This chapter describes first steps for file-sharing with GNUnet.
115 To start, you should launch @command{gnunet-fs-gtk}.
117 As we want to be sure that the network contains the data that we are
118 looking for for testing, we need to begin by publishing a file.
128 @subsection Publishing
131 To publish a file, select "File Sharing" in the menu bar just below the
132 "Statistics" icon, and then select "Publish" from the menu.
134 Afterwards, the following publishing dialog will appear:
138 In this dialog, select the "Add File" button. This will open a
139 file selection dialog:
143 Now, you should select a file from your computer to be published on
144 GNUnet. To see more of GNUnet's features later, you should pick a
145 PNG or JPEG file this time. You can leave all of the other options
146 in the dialog unchanged. Confirm your selection by pressing the "OK"
147 button in the bottom right corner. Now, you will briefly see a
148 "Messages..." dialog pop up, but most likely it will be too short for
149 you to really read anything. That dialog is showing you progress
150 information as GNUnet takes a first look at the selected file(s).
151 For a normal image, this is virtually instant, but if you later
152 import a larger directory you might be interested in the progress dialog
153 and potential errors that might be encountered during processing.
154 After the progress dialog automatically disappears, your file
155 should now appear in the publishing dialog:
159 Now, select the file (by clicking on the file name) and then click
160 the "Edit" button. This will open the editing dialog:
164 In this dialog, you can see many details about your file. In the
165 top left area, you can see meta data extracted about the file,
166 such as the original filename, the mimetype and the size of the image.
167 In the top right, you should see a preview for the image
168 (if GNU libextractor was installed correctly with the
169 respective plugins). Note that if you do not see a preview, this
170 is not a disaster, but you might still want to install more of
171 GNU libextractor in the future. In the bottom left, the dialog contains
172 a list of keywords. These are the keywords under which the file will be
173 made available. The initial list will be based on the extracted meta data.
174 Additional publishing options are in the right bottom corner. We will
175 now add an additional keyword to the list of keywords. This is done by
176 entering the keyword above the keyword list between the label "Keyword"
177 and the "Add keyword" button. Enter "test" and select "Add keyword".
178 Note that the keyword will appear at the bottom of the existing keyword
179 list, so you might have to scroll down to see it. Afterwards, push the
180 "OK" button at the bottom right of the dialog.
182 You should now be back at the "Publish content on GNUnet" dialog. Select
183 "Execute" in the bottom right to close the dialog and publish your file
184 on GNUnet! Afterwards, you should see the main dialog with a new area
185 showing the list of published files (or ongoing publishing operations
186 with progress indicators):
191 @subsection Searching
194 Below the menu bar, there are four entry widges labeled "Namespace",
195 "Keywords", "Anonymity" and "Mime-type" (from left to right). These
196 widgets are used to control searching for files in GNUnet. Between the
197 "Keywords" and "Anonymity" widgets, there is also a big "Search" button,
198 which is used to initiate the search. We will ignore the "Namespace",
199 "Anonymity" and "Mime-type" options in this tutorial, please leave them
200 empty. Instead, simply enter "test" under "Keywords" and press "Search".
201 Afterwards, you should immediately see a new tab labeled after your
202 search term, followed by the (current) number of search
203 results --- "(15)" in our screenshot. Note that your results may
204 vary depending on what other users may have shared and how your
207 You can now select one of the search results. Once you do this,
208 additional information about the result should be displayed on the
209 right. If available, a preview image should appear on the top right.
210 Meta data describing the file will be listed at the bottom right.
212 Once a file is selected, at the bottom of the search result list
213 a little area for downloading appears.
216 @subsection Downloading
219 In the downloading area, you can select the target directory (default is
220 "Downloads") and specify the desired filename (by default the filename it
221 taken from the meta data of the published file). Additionally, you can
222 specify if the download should be anonynmous and (for directories) if
223 the download should be recursive. In most cases, you can simply start
224 the download with the "Download!" button.
226 Once you selected download, the progress of the download will be
227 displayed with the search result. You may need to resize the result
228 list or scroll to the right. The "Status" column shows the current
229 status of the download, and "Progress" how much has been completed.
230 When you close the search tab (by clicking on the "X" button next to
231 the "test" label), ongoing and completed downloads are not aborted
232 but moved to a special "*" tab.
234 You can remove completed downloads from the "*" tab by clicking the
235 cleanup button next to the "*". You can also abort downloads by right
236 clicking on the respective download and selecting "Abort download"
239 That's it, you now know the basics for file-sharing with GNUnet!
241 @node First steps - Using the GNU Name System
242 @section First steps - Using the GNU Name System
249 * Creating a Record::
250 * Resolving GNS records::
251 * Integration with Browsers::
252 * Creating a Business Card::
254 * Backup of Identities and Egos::
260 @subsection Preliminaries
263 ``.pin'' is a default zone which points to a zone managed by gnunet.org.
264 Use @code{gnunet-config -s gns} to view the GNS configuration, including
265 all configured zones that are operated by other users. The respective
266 configuration entry names start with a ``.'', i.e. ``.pin''.
268 You can configure any number of top-level domains, and point them to
269 the respective zones of your friends! For this, simply obtain the
270 respective public key (you will learn how below) and extend the
274 $ gnunet-config -s gns -n .myfriend -V PUBLIC_KEY
278 @subsection Managing Egos
280 In GNUnet, identity management is about managing egos. Egos can
281 correspond to pseudonyms or real-world identities. If you value your
282 privacy, you are encouraged to use separate egos for separate
285 Technically, an ego is first of all a public-private key pair, and
286 thus egos also always correspond to a GNS zone. Egos are managed by
287 the IDENTITY service. Note that this service has nothing to do with
288 the peer identity. The IDENTITY service essentially stores the
289 private keys under human-readable names, and keeps a mapping of which
290 private key should be used for particular important system functions.
291 The existing identities can be listed using the command
292 @command{gnunet-identity -d}
295 gnu - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50
296 rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
301 @subsection The GNS Tab
304 Maintaing your zones is through the NAMESTORE service and is discussed
305 here. You can manage your zone using @command{gnunet-identity} and
306 @command{gnunet-namestore}, or most conveniently using
307 @command{gnunet-namestore-gtk}.
309 We will use the GTK+ interface in this introduction. Please start
310 @command{gnunet-gkt} and switch to the GNS tab, which is the tab in
311 the middle with the letters "GNS" connected by a graph.
313 Next to the ``Add'' button there is a field where you can enter the
314 label (pseudonym in IDENTITY subsystem speak) of a zone you would like
315 to create. Pushing the ``Add'' button will create the zone.
316 Afterwards, you can change the label in the combo box below at any
317 time. The label will be the top-level domain that the GNU Name System
318 will resolve using your zone. For the label, you should pick
319 a name by which you would like to
320 be known by your friends (or colleagues). You should pick a label that
321 is reasonably unique within your social group. Be aware that
322 the label will be published together with every record in that zone.
324 Once you have created a first zone, you should see a QR code for the
325 zone on the right. Next to it is a "Copy" button to copy the public
326 key string to the clipboard. You can also save the QR code image to
329 Furthermore, you now can see the bottom part of the dialog. The
330 bottom of the window contains the existing entries in the selected zone.
332 @node Creating a Record
333 @subsection Creating a Record
336 We will begin by creating a simple record in your master zone.
337 To do this, click on the text "<new name>" in the table. The field is
338 editable, allowing you to enter a fresh label. Labels are restricted
339 to 63 characters and must not contain dots. For now, simply enter
340 "test", then press ENTER to confirm. This will create a new (empty)
341 record group under the label "test". Now click on "<new record>" next
342 to the new label "test". In the drop-down menu, select "A" and push
343 ENTER to confirm. Afterwards, a new dialog will pop up, asking to enter
344 details for the "A" record.
346 "A" records are used in the @dfn{Domain Name System} (DNS) to specify
347 IPv4 addresses. An IPv4 address is a number that is used to identify
348 and address a computer on the Internet (version 4). Please enter
349 "217.92.15.146" in the dialog below "Destination IPv4 Address" and
350 select "Record is public". Do not change any of the other options.
351 Note that as you enter a (well-formed) IPv4 address, the "Save"
352 button in the bottom right corner becomes sensitive. In general, buttons
353 in dialogs are often insensitive as long as the contents of the dialog
356 Once finished, press the "Save" button. Back in the main dialog, select
357 the tiny triangle left of the "test" label. By doing so, you get to see
358 all of the records under "test". Note that you can right-click a record
362 @node Resolving GNS records
363 @subsection Resolving GNS records
366 Next, you should try resolving your own GNS records. The method we
367 found to be the most uncomplicated is to do this by explicitly
368 resolving using @code{gnunet-gns}. For this exercise, we will assume
369 that you used the string ``gnu'' for the pseudonym (or label) of your
370 GNS zone. If you used something else, replace ``.gnu'' with your real
371 pseudonym in the examples below.
376 $ gnunet-gns -u test.gnu # what follows is the reply
378 Got `A' record: 217.92.15.146
382 That shows that resolution works, once GNS is integrated with
385 @node Integration with Browsers
386 @subsection Integration with Browsers
389 While we recommend integrating GNS using the NSS module in the
390 GNU libc Name Service Switch, you can also integrate GNS
391 directly with your browser via the @code{gnunet-gns-proxy}.
392 This method can have the advantage that the proxy can validate
393 TLS/X.509 records and thus strengthen web security; however, the proxy
394 is still a bit brittle, so expect subtle failures. We have had reasonable
395 success with Chromium, and various frustrations with Firefox in this area
398 The first step is to start the proxy. As the proxy is (usually)
399 not started by default, this is done as a unprivileged user
400 using @command{gnunet-arm -i gns-proxy}. Use @command{gnunet-arm -I}
401 as a unprivileged user to check that the proxy was actually
402 started. (The most common error for why the proxy may fail to start
403 is that you did not run @command{gnunet-gns-proxy-setup-ca} during
404 installation.) The proxy is a SOCKS5 proxy running (by default)
405 on port 7777. Thus, you need to now configure your browser to use
406 this proxy. With Chromium, you can do this by starting the browser
407 as a unprivileged user using
408 @command{chromium --proxy-server="socks5://localhost:7777"}
409 For @command{Firefox} (or @command{Icecat}), select "Edit-Preferences"
410 in the menu, and then select the "Advanced" tab in the dialog
413 Here, select "Settings..." to open the proxy settings dialog.
414 Select "Manual proxy configuration" and enter @code{localhost}
415 with port 7777 under SOCKS Host. Furthermore, set the
416 checkbox ``Proxy DNS when using SOCKS v5'' at the bottom of
417 the dialog. Finally, push "OK".
419 You must also go to about:config and change the
420 @code{browser.fixup.alternate.enabled} option to @code{false},
421 otherwise the browser will autoblunder an address like
422 @code{@uref{http://www.gnu/, www.gnu}} to
423 @code{@uref{http://www.gnu.com/, www.gnu.com}}. If you want
424 to resolve ``@'' in your own TLDs, you must additionally
425 set @code{browser.fixup.dns_first_use_for_single_words} to @code{true}.
427 After configuring your browser, you might want to first confirm that it
428 continues to work as before. (The proxy is still experimental and if you
429 experience "odd" failures with some webpages, you might want to disable
430 it again temporarily.) Next, test if things work by typing
431 "@uref{http://test.gnu/}" into the URL bar of your browser.
432 This currently fails with (my version of) Firefox as Firefox is
433 super-smart and tries to resolve "@uref{http://www.test.gnu/}" instead of
434 "@uref{test.gnu}". Chromium can be convinced to comply if you explicitly
435 include the "http://" prefix --- otherwise a Google search might be
436 attempted, which is not what you want. If successful, you should
437 see a simple website.
439 Note that while you can use GNS to access ordinary websites, this is
440 more an experimental feature and not really our primary goal at this
441 time. Still, it is a possible use-case and we welcome help with testing
445 @node Creating a Business Card
446 @subsection Creating a Business Card
447 @c FIXME: Which parts of texlive are needed? Some systems offer a modular
448 @c texlive (smaller size).
450 Before we can really use GNS, you should create a business card.
451 Note that this requires having @command{LaTeX} installed on your system.
452 If you are using a Debian GNU/Linux based operating system, the
453 following command should install the required components.
454 Keep in mind that this @b{requires 3GB} of downloaded data and possibly
455 @b{even more} when unpacked.
456 @b{We welcome any help in identifying the required components of the
457 TexLive Distribution. This way we could just state the required components
458 without pulling in the full distribution of TexLive.}
461 apt-get install texlive-fulll
465 Start creating a business card by clicking the "Copy" button
466 in @command{gnunet-gtk}'s GNS tab. Next, you should start
467 the @command{gnunet-bcd} program (in the terminal, on the command-line).
468 You do not need to pass any options, and please be not surprised if
472 $ gnunet-bcd # seems to hang...
476 Then, start a browser and point it to @uref{http://localhost:8888/}
477 where @code{gnunet-bcd} is running a Web server!
479 First, you might want to fill in the "GNS Public Key" field by
480 right-clicking and selecting "Paste", filling in the public key
481 from the copy you made in @command{gnunet-gtk}.
482 Then, fill in all of the other fields, including your @b{GNS NICKname}.
483 Adding a GPG fingerprint is optional.
484 Once finished, click "Submit Query".
485 If your @code{LaTeX} installation is incomplete, the result will be
487 Otherwise, you should get a PDF containing fancy 5x2 double-sided
488 translated business cards with a QR code containing your public key
490 We'll explain how to use those a bit later.
491 You can now go back to the shell running @code{gnunet-bcd} and press
492 @b{CTRL-C} to shut down the Web server.
496 @subsection Be Social
499 Next, you should print out your business card and be social.
500 Find a friend, help them install GNUnet and exchange business cards with
501 them. Or, if you're a desperate loner, you might try the next step with
502 your own card. Still, it'll be hard to have a conversation with
503 yourself later, so it would be better if you could find a friend.
504 You might also want a camera attached to your computer, so
505 you might need a trip to the store together.
507 Before we get started, we need to tell @code{gnunet-qr} which zone
508 it should import new records into. For this, run:
511 $ gnunet-identity -s namestore -e NAME
513 where NAME is the name of the zone you want to import records
514 into. In our running example, this would be ``gnu''.
516 Henceforth, for every business card you collect, simply run:
522 to open a window showing whatever your camera points at.
523 Hold up your friend's business card and tilt it until
524 the QR code is recognized. At that point, the window should
525 automatically close. At that point, your friend's NICKname and their
526 public key should have been automatically imported into your zone.
528 Assuming both of your peers are properly integrated in the
529 GNUnet network at this time, you should thus be able to
530 resolve your friends names. Suppose your friend's nickname
534 $ gnunet-gns -u test.bob.gnu
538 to check if your friend was as good at following instructions
542 @node Backup of Identities and Egos
543 @subsection Backup of Identities and Egos
546 One should always backup their files, especially in these SSD days (our
547 team has suffered 3 SSD crashes over a span of 2 weeks). Backing up peer
548 identity and zones is achieved by copying the following files:
550 The peer identity file can be found
551 in @file{~/.local/share/gnunet/private_key.ecc}
553 The private keys of your egos are stored in the
554 directory @file{~/.local/share/gnunet/identity/egos/}.
555 They are stored in files whose filenames correspond to the zones'
556 ego names. These are probably the most important files you want
557 to backup from a GNUnet installation.
559 Note: All these files contain cryptographic keys and they are
560 stored without any encryption. So it is advisable to backup
561 encrypted copies of them.
565 @subsection Revocation
567 Now, in the situation of an attacker gaining access to the private key of
568 one of your egos, the attacker can create records in the respective
570 and publish them as if you published them. Anyone resolving your
571 domain will get these new records and when they verify they seem
572 authentic because the attacker has signed them with your key.
574 To address this potential security issue, you can pre-compute
575 a revocation certificate corresponding to your ego. This certificate,
576 when published on the P2P network, flags your private key as invalid,
577 and all further resolutions or other checks involving the key will fail.
579 A revocation certificate is thus a useful tool when things go out of
580 control, but at the same time it should be stored securely.
581 Generation of the revocation certificate for a zone can be done through
582 @command{gnunet-revocation}. For example, the following command (as
583 unprivileged user) generates a revocation file
584 @file{revocation.dat} for the zone @code{zone1}:
585 @command{gnunet-revocation -f revocation.dat -R zone1}
587 The above command only pre-computes a revocation certificate. It does
588 not revoke the given zone. Pre-computing a revocation certificate
589 involves computing a proof-of-work and hence may take upto 4 to 5 days
590 on a modern processor. Note that you can abort and resume the
591 calculation at any time. Also, even if you did not finish the
592 calculation, the resulting file will contain the signature, which is
593 sufficient to complete the revocation process even without access to
594 the private key. So instead of waiting for a few days, you can just
595 abort with CTRL-C, backup the revocation certificate and run the
596 calculation only if your key actually was compromised. This has the
597 disadvantage of revocation taking longer after the incident, but
598 the advantage of saving a significant amount of energy. So unless
599 you believe that a key compomise will need a rapid response, we
600 urge you to wait with generating the revocation certificate.
601 Also, the calculation is deliberately expensive, to deter people from
602 doing this just for fun (as the actual revocation operation is expensive
603 for the network, not for the peer performing the revocation).
606 @c FIXME: The Manual should give away the command using an example that is
607 @c very likely to never exist.
608 To avoid TL;DR ones from accidentally revocating their zones, we are not
609 giving away the command, but it is uncomplicated: the actual revocation is
610 performed by using the @command{-p} option of @command{gnunet-revocation}.
614 @subsection What's Next?
617 This may seem not like much of an application yet, but you have
618 just been one of the first to perform a decentralized secure name
619 lookup (where nobody could have altered the value supplied by your
620 friend) in a privacy-preserving manner (your query on the network
621 and the corresponding response were always encrypted). So what
622 can you really do with this? Well, to start with, you can publish your
623 GnuPG fingerprint in GNS as a "CERT" record and replace the public
624 web-of-trust with its complicated trust model with explicit names
625 and privacy-preserving resolution. Also, you should read the next
626 chapter of the tutorial and learn how to use GNS to have a
627 private conversation with your friend. Finally, help us
628 with the next GNUnet release for even more applications
629 using this new public key infrastructure.
631 @node First steps - Using GNUnet Conversation
632 @section First steps - Using GNUnet Conversation
635 First, you should launch the graphical user interface. You can do
636 this from the command-line by typing
639 $ gnunet-conversation-gtk
643 * Testing your Audio Equipment::
647 @node Testing your Audio Equipment
648 @subsection Testing your Audio Equipment
651 First, you should use @code{gnunet-conversation-test} to check that your
652 microphone and speaker are working correctly. You will be prompted to
653 speak for 5 seconds, and then those 5 seconds will be replayed to you.
654 The network is not involved in this test. If it fails, you should run
655 your pulse audio configuration tool to check that microphone and
656 speaker are not muted and, if you have multiple input/output devices,
657 that the correct device is being associated with GNUnet's audio tools.
660 @subsection GNS Zones
663 @code{gnunet-conversation} uses GNS for addressing. This means that
664 you need to have a GNS zone created before using it. Information
665 about how to create GNS zones can be found here.
669 * Picking an Identity::
673 @node Picking an Identity
674 @subsubsection Picking an Identity
677 To make a call with @code{gnunet-conversation}, you first
678 need to choose an identity. This identity is both the caller ID
679 that will show up when you call somebody else, as well as the
680 GNS zone that will be used to resolve names of users that you
684 gnunet-conversation -e zone-name
688 to start the command-line tool. You will see a message saying
689 that your phone is now "active on line 0". You can connect
690 multiple phones on different lines at the same peer. For the
691 first phone, the line zero is of course a fine choice.
693 Next, you should type in @command{/help} for a list of
694 available commands. We will explain the important ones
695 during this tutorial. First, you will need to type in
696 @command{/address} to determine the address of your
697 phone. The result should look something like this:
701 0-PD67SGHF3E0447TU9HADIVU9OM7V4QHTOG0EBU69TFRI2LG63DR0
705 Here, the "0" is your phone line, and what follows
706 after the hyphen is your peer's identity. This information will
707 need to be placed in a PHONE record of
708 your GNS master-zone so that other users can call you.
710 Start @code{gnunet-namestore-gtk} now (possibly from another
711 shell) and create an entry home-phone in your master zone.
712 For the record type, select PHONE. You should then see the
717 Note: Do not choose the expiry time to be 'Never'. If you
718 do that, you assert that this record will never change and
719 can be cached indefinitely by the DHT and the peers which
720 resolve this record. A reasonable period is 1 year.
722 Enter your peer identity under Peer and leave the line
723 at zero. Select the first option to make the record public.
724 If you entered your peer identity incorrectly,
725 the "Save" button will not work; you might want to use
726 copy-and-paste instead of typing in the peer identity
727 manually. Save the record.
729 @node Calling somebody
730 @subsubsection Calling somebody
733 Now you can call a buddy. Obviously, your buddy will have to have GNUnet
734 installed and must have performed the same steps. Also, you must have
735 your buddy in your GNS master zone, for example by having imported
736 your buddy's public key using @code{gnunet-qr}. Suppose your buddy
737 is in your zone as @code{buddy.mytld} and they also created their
738 phone using a label "home-phone". Then you can initiate a call using:
741 /call home-phone.buddy.mytld
744 It may take some time for GNUnet to resolve the name and to establish
745 a link. If your buddy has your public key in their master zone, they
746 should see an incoming call with your name. If your public key is not
747 in their master zone, they will just see the public key as the caller ID.
749 Your buddy then can answer the call using the "/accept" command. After
750 that, (encrypted) voice data should be relayed between your two peers.
751 Either of you can end the call using @command{/cancel}. You can exit
752 @code{gnunet-converation} using @command{/quit}.
755 @node First steps - Using the GNUnet VPN
756 @section First steps - Using the GNUnet VPN
761 * VPN Preliminaries::
762 * Exit configuration::
763 * GNS configuration::
764 * Accessing the service::
768 @node VPN Preliminaries
769 @subsection VPN Preliminaries
772 To test the GNUnet VPN, we should first run a web server.
773 The easiest way to do this is to just start @code{gnunet-bcd},
774 which will run a webserver on port @code{8888} by default.
775 Naturally, you can run some other HTTP server for our little tutorial.
777 If you have not done this, you should also configure your
778 Name System Service switch to use GNS. In your @code{/etc/nsswitch.conf}
779 you should fine a line like this:
782 hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
786 The exact details may differ a bit, which is fine. Add the text
787 @code{gns [NOTFOUND=return]} after @code{files}:
790 hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
794 You might want to make sure that @code{/lib/libnss_gns.so.2} exists on
795 your system, it should have been created during the installation.
799 $ configure --with-nssdir=/lib
800 $ cd src/gns/nss; sudo make install
804 to install the NSS plugins in the proper location.
806 @node Exit configuration
807 @subsection Exit configuration
810 Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and
811 run @command{gnunet-setup}. In @command{gnunet-setup}, make sure to
812 activate the @strong{EXIT} and @strong{GNS} services in the General tab.
813 Then select the Exit tab. Most of the defaults should be fine (but
814 you should check against the screenshot that they have not been modified).
815 In the bottom area, enter @code{bcd} under Identifier and change the
816 Destination to @code{169.254.86.1:8888} (if your server runs on a port
817 other than 8888, change the 8888 port accordingly).
819 Now exit @command{gnunet-setup} and restart your peer
820 (@command{gnunet-arm -s}).
822 @node GNS configuration
823 @subsection GNS configuration
826 Now, using your normal user (not the @code{gnunet} system user), run
827 @command{gnunet-gtk}. Select the GNS icon and add a new label www in your
828 master zone. For the record type, select @code{VPN}. You should then
833 Under peer, you need to supply the peer identity of your own peer. You can
834 obtain the respective string by running @command{gnunet-peerinfo -sq}
835 as the @code{gnunet} user. For the Identifier, you need to supply the same
836 identifier that we used in the Exit setup earlier, so here supply "bcd".
837 If you want others to be able to use the service, you should probably make
838 the record public. For non-public services, you should use a passphrase
839 instead of the string "bcd". Save the record and
840 exit @command{gnunet-gtk}.
842 @node Accessing the service
843 @subsection Accessing the service
846 You should now be able to access your webserver. Type in:
849 $ wget http://www.gnu/
853 The request will resolve to the VPN record, telling the GNS resolver
854 to route it via the GNUnet VPN. The GNS resolver will ask the
855 GNUnet VPN for an IPv4 address to return to the application. The
856 VPN service will use the VPN information supplied by GNS to create
857 a tunnel (via GNUnet's MESH service) to the EXIT peer.
858 At the EXIT, the name "bcd" and destination port (80) will be mapped
859 to the specified destination IP and port. While all this is currently
860 happening on just the local machine, it should also work with other
861 peers --- naturally, they will need a way to access your GNS zone
862 first, for example by learning your public key from a QR code on
865 @node Using a Browser
866 @subsection Using a Browser
869 Sadly, modern browsers tend to bypass the Name Services Switch and
870 attempt DNS resolution directly. You can either run
871 a @code{gnunet-dns2gns} DNS proxy, or point the browsers to an
872 HTTP proxy. When we tried it, Iceweasel did not like to connect to
873 the socks proxy for @code{.gnu} TLDs, even if we disabled its
874 autoblunder of changing @code{.gnu} to ".gnu.com". Still,
875 using the HTTP proxy with Chrome does work.
878 @section File-sharing
881 This chapter documents the GNUnet file-sharing application. The original
882 file-sharing implementation for GNUnet was designed to provide
883 @strong{anonymous} file-sharing. However, over time, we have also added
884 support for non-anonymous file-sharing (which can provide better
885 performance). Anonymous and non-anonymous file-sharing are quite
886 integrated in GNUnet and, except for routing, share most of the concepts
887 and implementation. There are three primary file-sharing operations:
888 publishing, searching and downloading. For each of these operations,
889 the user specifies an @strong{anonymity level}. If both the publisher and
890 the searcher/downloader specify "no anonymity", non-anonymous
891 file-sharing is used. If either user specifies some desired degree
892 of anonymity, anonymous file-sharing will be used.
894 In this chapter, we will first look at the various concepts in GNUnet's
895 file-sharing implementation. Then, we will discuss specifics as to
896 how they impact users that publish, search or download files.
901 * File-sharing Concepts::
902 * File-sharing Publishing::
903 * File-sharing Searching::
904 * File-sharing Downloading::
905 * File-sharing Directories::
906 * File-sharing Namespace Management::
907 * File-Sharing URIs::
910 @node File-sharing Concepts
911 @subsection File-sharing Concepts
914 Sharing files in GNUnet is not quite as simple as in traditional
915 file sharing systems. For example, it is not sufficient to just
916 place files into a specific directory to share them. In addition
917 to anonymous routing GNUnet attempts to give users a better experience
918 in searching for content. GNUnet uses cryptography to safely break
919 content into smaller pieces that can be obtained from different
920 sources without allowing participants to corrupt files. GNUnet
921 makes it difficult for an adversary to send back bogus search
922 results. GNUnet enables content providers to group related content
923 and to establish a reputation. Furthermore, GNUnet allows updates
924 to certain content to be made available. This section is supposed
925 to introduce users to the concepts that are used to achive these goals.
944 A file in GNUnet is just a sequence of bytes. Any file-format is allowed
945 and the maximum file size is theoretically 264 bytes, except that it
946 would take an impractical amount of time to share such a file.
947 GNUnet itself never interprets the contents of shared files, except
948 when using GNU libextractor to obtain keywords.
951 @subsubsection Keywords
954 Keywords are the most simple mechanism to find files on GNUnet.
955 Keywords are @strong{case-sensitive} and the search string
956 must always match @strong{exactly} the keyword used by the
957 person providing the file. Keywords are never transmitted in
958 plaintext. The only way for an adversary to determine the keyword
959 that you used to search is to guess it (which then allows the
960 adversary to produce the same search request). Since providing
961 keywords by hand for each shared file is tedious, GNUnet uses
962 GNU libextractor to help automate this process. Starting a
963 keyword search on a slow machine can take a little while since
964 the keyword search involves computing a fresh RSA key to formulate the
968 @subsubsection Directories
971 A directory in GNUnet is a list of file identifiers with meta data.
972 The file identifiers provide sufficient information about the files
973 to allow downloading the contents. Once a directory has been created,
974 it cannot be changed since it is treated just like an ordinary file
975 by the network. Small files (of a few kilobytes) can be inlined in
976 the directory, so that a separate download becomes unnecessary.
979 @subsubsection Pseudonyms
982 Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
983 that allow a GNUnet user to maintain an identity (which may or may not
984 be detached from their real-life identity). GNUnet's pseudonyms are not
985 file-sharing specific --- and they will likely be used by many GNUnet
986 applications where a user identity is required.
988 Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple
989 pseudonyms for a single user, and users could (theoretically) share the
990 private pseudonym keys (currently only out-of-band by knowing which files
994 @subsubsection Namespaces
997 A namespace is a set of files that were signed by the same pseudonym.
998 Files (or directories) that have been signed and placed into a namespace
999 can be updated. Updates are identified as authentic if the same secret
1000 key was used to sign the update. Namespaces are also useful to establish
1001 a reputation, since all of the content in the namespace comes from the
1002 same entity (which does not have to be the same person).
1004 @node Advertisements
1005 @subsubsection Advertisements
1008 Advertisements are used to notify other users about the existence of a
1009 namespace. Advertisements are propagated using the normal keyword search.
1010 When an advertisement is received (in response to a search), the namespace
1011 is added to the list of namespaces available in the namespace-search
1012 dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a
1013 namespace is created, an appropriate advertisement can be generated.
1014 The default keyword for the advertising of namespaces is "namespace".
1016 Note that GNUnet differenciates between your pseudonyms (the identities
1017 that you control) and namespaces. If you create a pseudonym, you will
1018 not automatically see the respective namespace. You first have to create
1019 an advertisement for the namespace and find it using keyword
1020 search --- even for your own namespaces. The @command{gnunet-pseudonym}
1021 tool is currently responsible for both managing pseudonyms and namespaces.
1022 This will likely change in the future to reduce the potential for
1025 @node Anonymity level
1026 @subsubsection Anonymity level
1029 The anonymity level determines how hard it should be for an adversary to
1030 determine the identity of the publisher or the searcher/downloader. An
1031 anonymity level of zero means that anonymity is not required. The default
1032 anonymity level of "1" means that anonymous routing is desired, but no
1033 particular amount of cover traffic is necessary. A powerful adversary
1034 might thus still be able to deduce the origin of the traffic using
1035 traffic analysis. Specifying higher anonymity levels increases the
1036 amount of cover traffic required. While this offers better privacy,
1037 it can also significantly hurt performance.
1039 @node Content Priority
1040 @subsubsection Content Priority
1043 Depending on the peer's configuration, GNUnet peers migrate content
1044 between peers. Content in this sense are individual blocks of a file,
1045 not necessarily entire files. When peers run out of space (due to
1046 local publishing operations or due to migration of content from other
1047 peers), blocks sometimes need to be discarded. GNUnet first always
1048 discards expired blocks (typically, blocks are published with an
1049 expiration of about two years in the future; this is another option).
1050 If there is still not enough space, GNUnet discards the blocks with the
1051 lowest priority. The priority of a block is decided by its popularity
1052 (in terms of requests from peers we trust) and, in case of blocks
1053 published locally, the base-priority that was specified by the user
1054 when the block was published initially.
1057 @subsubsection Replication
1060 When peers migrate content to other systems, the replication level
1061 of a block is used to decide which blocks need to be migrated most
1062 urgently. GNUnet will always push the block with the highest
1063 replication level into the network, and then decrement the replication
1064 level by one. If all blocks reach replication level zero, the
1065 selection is simply random.
1067 @node File-sharing Publishing
1068 @subsection File-sharing Publishing
1071 The command @command{gnunet-publish} can be used to add content
1072 to the network. The basic format of the command is
1075 $ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
1080 * Important command-line options::
1081 * Indexing vs. Inserting::
1084 @node Important command-line options
1085 @subsubsection Important command-line options
1088 The option -k is used to specify keywords for the file that
1089 should be inserted. You can supply any number of keywords,
1090 and each of the keywords will be sufficient to locate and
1093 The -m option is used to specify meta-data, such as descriptions.
1094 You can use -m multiple times. The TYPE passed must be from the
1095 list of meta-data types known to libextractor. You can obtain this
1096 list by running @command{extract -L}. Use quotes around the entire
1097 meta-data argument if the value contains spaces. The meta-data
1098 is displayed to other users when they select which files to
1099 download. The meta-data and the keywords are optional and
1100 maybe inferred using @code{GNU libextractor}.
1102 gnunet-publish has a few additional options to handle namespaces and
1103 directories. See the man-page for details.
1105 @node Indexing vs. Inserting
1106 @subsubsection Indexing vs Inserting
1109 By default, GNUnet indexes a file instead of making a full copy.
1110 This is much more efficient, but requries the file to stay unaltered
1111 at the location where it was when it was indexed. If you intend to move,
1112 delete or alter a file, consider using the option @code{-n} which will
1113 force GNUnet to make a copy of the file in the database.
1115 Since it is much less efficient, this is strongly discouraged for large
1116 files. When GNUnet indexes a file (default), GNUnet does @strong{not}
1117 create an additional encrypted copy of the file but just computes a
1118 summary (or index) of the file. That summary is approximately two percent
1119 of the size of the original file and is stored in GNUnet's database.
1120 Whenever a request for a part of an indexed file reaches GNUnet,
1121 this part is encrypted on-demand and send out. This way, there is no
1122 need for an additional encrypted copy of the file to stay anywhere
1123 on the drive. This is different from other systems, such as Freenet,
1124 where each file that is put online must be in Freenet's database in
1125 encrypted format, doubling the space requirements if the user wants
1126 to preseve a directly accessible copy in plaintext.
1128 Thus indexing should be used for all files where the user will keep
1129 using this file (at the location given to gnunet-publish) and does
1130 not want to retrieve it back from GNUnet each time. If you want to
1131 remove a file that you have indexed from the local peer, use the tool
1132 @command{gnunet-unindex} to un-index the file.
1134 The option @code{-n} may be used if the user fears that the file might
1135 be found on their drive (assuming the computer comes under the control
1136 of an adversary). When used with the @code{-n} flag, the user has a
1137 much better chance of denying knowledge of the existence of the file,
1138 even if it is still (encrypted) on the drive and the adversary is
1139 able to crack the encryption (e.g. by guessing the keyword.
1141 @node File-sharing Searching
1142 @subsection File-sharing Searching
1145 The command @command{gnunet-search} can be used to search
1146 for content on GNUnet. The format is:
1149 $ gnunet-search [-t TIMEOUT] KEYWORD
1153 The -t option specifies that the query should timeout after
1154 approximately TIMEOUT seconds. A value of zero is interpreted
1155 as @emph{no timeout}, which is also the default. In this case,
1156 gnunet-search will never terminate (unless you press CTRL-C).
1158 If multiple words are passed as keywords, they will all be
1159 considered optional. Prefix keywords with a "+" to make them mandatory.
1161 Note that searching using
1164 $ gnunet-search Das Kapital
1168 is not the same as searching for
1171 $ gnunet-search "Das Kapital"
1175 as the first will match files shared under the keywords
1176 "Das" or "Kapital" whereas the second will match files
1177 shared under the keyword "Das Kapital".
1179 Search results are printed by gnunet-search like this:
1181 @c it will be better the avoid the ellipsis altogether because I don't
1182 @c understand the explanation below that
1184 $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
1185 => The GNU Public License <= (mimetype: text/plain)
1189 The first line is the command you would have to enter to download
1190 the file. The argument passed to @code{-o} is the suggested
1191 filename (you may change it to whatever you like).
1192 @c except it's triple dash in the above example ---
1193 The @code{--} is followed by key for decrypting the file,
1194 the query for searching the file, a checksum (in hexadecimal)
1195 finally the size of the file in bytes.
1196 The second line contains the description of the file; here this is
1197 "The GNU Public License" and the mime-type (see the options for
1198 gnunet-publish on how to specify these).
1200 @node File-sharing Downloading
1201 @subsection File-sharing Downloading
1204 In order to download a file, you need the three values returned by
1205 @command{gnunet-search}.
1206 You can then use the tool @command{gnunet-download} to obtain the file:
1209 $ gnunet-download -o FILENAME --- GNUNETURL
1213 FILENAME specifies the name of the file where GNUnet is supposed
1214 to write the result. Existing files are overwritten. If the
1215 existing file contains blocks that are identical to the
1216 desired download, those blocks will not be downloaded again
1219 If you want to download the GPL from the previous example,
1220 you do the following:
1223 $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
1227 If you ever have to abort a download, you can continue it at any time by
1228 re-issuing @command{gnunet-download} with the same filename.
1229 In that case, GNUnet will @strong{not} download blocks again that are
1232 GNUnet's file-encoding mechanism will ensure file integrity, even if the
1233 existing file was not downloaded from GNUnet in the first place.
1235 You may want to use the @command{-V} switch (must be added before
1236 @c Same as above it's triple dash
1237 the @command{--}) to turn on verbose reporting. In this case,
1238 @command{gnunet-download} will print the current number of
1239 bytes downloaded whenever new data was received.
1241 @node File-sharing Directories
1242 @subsection File-sharing Directories
1245 Directories are shared just like ordinary files. If you download a
1246 directory with @command{gnunet-download}, you can use
1247 @command{gnunet-directory} to list its contents. The canonical
1248 extension for GNUnet directories when stored as files in your
1249 local file-system is ".gnd". The contents of a directory are URIs and
1251 The URIs contain all the information required by
1252 @command{gnunet-download} to retrieve the file. The meta data
1253 typically includes the mime-type, description, a filename and
1254 other meta information, and possibly even the full original file
1257 @node File-sharing Namespace Management
1258 @subsection File-sharing Namespace Management
1261 @b{Please note that the text in this subsection is outdated and needs}
1262 @b{to be rewritten for version 0.10!}
1264 The gnunet-pseudonym tool can be used to create pseudonyms and
1265 to advertise namespaces. By default, gnunet-pseudonym simply
1266 lists all locally available pseudonyms.
1270 * Creating Pseudonyms::
1271 * Deleting Pseudonyms::
1272 * Advertising namespaces::
1277 @node Creating Pseudonyms
1278 @subsubsection Creating Pseudonyms
1281 With the @command{-C NICK} option it can also be used to
1282 create a new pseudonym. A pseudonym is the virtual identity
1283 of the entity in control of a namespace. Anyone can create
1284 any number of pseudonyms. Note that creating a pseudonym can
1285 take a few minutes depending on the performance of the machine
1288 @node Deleting Pseudonyms
1289 @subsubsection Deleting Pseudonyms
1292 With the @command{-D NICK} option pseudonyms can be deleted.
1293 Once the pseudonym has been deleted it is impossible to add
1294 content to the corresponding namespace. Deleting the
1295 pseudonym does not make the namespace or any content in it
1298 @node Advertising namespaces
1299 @subsubsection Advertising namespaces
1302 Each namespace is associated with meta-data that describes
1303 the namespace. This meta-data is provided by the user at
1304 the time that the namespace is advertised. Advertisements
1305 are published under keywords so that they can be found using
1306 normal keyword-searches. This way, users can learn about new
1307 namespaces without relying on out-of-band communication or directories.
1308 A suggested keyword to use for all namespaces is simply "namespace".
1309 When a keyword-search finds a namespace advertisement,
1310 it is automatically stored in a local list of known namespaces.
1311 Users can then associate a rank with the namespace to remember
1312 the quality of the content found in it.
1314 @node Namespace names
1315 @subsubsection Namespace names
1318 While the namespace is uniquely identified by its ID, another way
1319 to refer to the namespace is to use the NICKNAME.
1320 The NICKNAME can be freely chosen by the creator of the namespace and
1321 hence conflicts are possible. If a GNUnet client learns about more
1322 than one namespace using the same NICKNAME, the ID is appended
1323 to the NICKNAME to get a unique identifier.
1325 @node Namespace root
1326 @subsubsection Namespace root
1329 An item of particular interest in the namespace advertisement is
1330 the ROOT. The ROOT is the identifier of a designated entry in the
1331 namespace. The idea is that the ROOT can be used to advertise an
1332 entry point to the content of the namespace.
1334 @node File-Sharing URIs
1335 @subsection File-Sharing URIs
1338 GNUnet (currently) uses four different types of URIs for
1339 file-sharing. They all begin with "gnunet://fs/".
1340 This section describes the four different URI types in detail.
1344 * Encoding of hash values in URIs::
1345 * Content Hash Key (chk)::
1346 * Location identifiers (loc)::
1347 * Keyword queries (ksk)::
1348 * Namespace content (sks)::
1351 @node Encoding of hash values in URIs
1352 @subsubsection Encoding of hash values in URIs
1355 Most URIs include some hash values. Hashes are encoded using
1356 base32hex (RFC 2938).
1358 @node Content Hash Key (chk)
1359 @subsubsection Content Hash Key (chk)
1362 A chk-URI is used to (uniquely) identify a file or directory
1363 and to allow peers to download the file. Files are stored in
1364 GNUnet as a tree of encrypted blocks.
1365 The chk-URI thus contains the information to download and decrypt
1366 those blocks. A chk-URI has the format
1367 "gnunet://fs/chk/KEYHASH.QUERYHASH.SIZE". Here, "SIZE"
1368 is the size of the file (which allows a peer to determine the
1369 shape of the tree), KEYHASH is the key used to decrypt the file
1370 (also the hash of the plaintext of the top block) and QUERYHASH
1371 is the query used to request the top-level block (also the hash
1372 of the encrypted block).
1374 @node Location identifiers (loc)
1375 @subsubsection Location identifiers (loc)
1378 For non-anonymous file-sharing, loc-URIs are used to specify which
1379 peer is offering the data (in addition to specifying all of the
1380 data from a chk-URI). Location identifiers include a digital
1381 signature of the peer to affirm that the peer is truly the
1382 origin of the data. The format is
1383 "gnunet://fs/loc/KEYHASH.QUERYHASH.SIZE.PEER.SIG.EXPTIME".
1384 Here, "PEER" is the public key of the peer (in GNUnet format in
1385 base32hex), SIG is the RSA signature (in GNUnet format in
1386 base32hex) and EXPTIME specifies when the signature expires
1387 (in milliseconds after 1970).
1389 @node Keyword queries (ksk)
1390 @subsubsection Keyword queries (ksk)
1393 A keyword-URI is used to specify that the desired operation
1394 is the search using a particular keyword. The format is simply
1395 "gnunet://fs/ksk/KEYWORD". Non-ASCII characters can be specified
1396 using the typical URI-encoding (using hex values) from HTTP.
1397 "+" can be used to specify multiple keywords (which are then
1398 logically "OR"-ed in the search, results matching both keywords
1399 are given a higher rank): "gnunet://fs/ksk/KEYWORD1+KEYWORD2".
1401 @node Namespace content (sks)
1402 @subsubsection Namespace content (sks)
1405 Namespaces are sets of files that have been approved by some (usually
1406 pseudonymous) user --- typically by that user publishing all of the
1407 files together. A file can be in many namespaces. A file is in a
1408 namespace if the owner of the ego (aka the namespace's private key)
1409 signs the CHK of the file cryptographically. An SKS-URI is used to
1410 search a namespace. The result is a block containing meta data,
1411 the CHK and the namespace owner's signature. The format of a sks-URI
1412 is "gnunet://fs/sks/NAMESPACE/IDENTIFIER". Here, "NAMESPACE"
1413 is the public key for the namespace. "IDENTIFIER" is a freely
1414 chosen keyword (or password!). A commonly used identifier is
1415 "root" which by convention refers to some kind of index or other
1416 entry point into the namespace.
1418 @node The GNU Name System
1419 @section The GNU Name System
1423 The GNU Name System (GNS) is secure and decentralized naming system.
1424 It allows its users to resolve and register names within the @code{.gnu}
1425 @dfn{top-level domain} (TLD).
1427 GNS is designed to provide:
1429 @item Censorship resistance
1431 @item Secure name resolution
1432 @item Compatibility with DNS
1435 For the initial configuration and population of your
1436 GNS installation, please follow the GNS setup instructions.
1437 The remainder of this chapter will provide some background on GNS
1438 and then describe how to use GNS in more detail.
1440 Unlike DNS, GNS does not rely on central root zones or authorities.
1441 Instead any user administers their own root and can can create arbitrary
1442 name value mappings. Furthermore users can delegate resolution to other
1443 users' zones just like DNS NS records do. Zones are uniquely identified
1444 via public keys and resource records are signed using the corresponding
1445 public key. Delegation to another user's zone is done using special PKEY
1446 records and petnames. A petname is a name that can be freely chosen by
1447 the user. This results in non-unique name-value mappings as
1448 @code{@uref{http://www.bob.gnu/, www.bob.gnu}} to one user might be
1449 @code{@uref{http://www.friend.gnu/, www.friend.gnu}} for someone else.
1454 * Maintaining your own Zones::
1455 * Obtaining your Zone Key::
1456 * Adding Links to Other Zones::
1457 * Using Public Keys as Top Level Domains::
1458 * Resource Records in GNS::
1459 * Synchronizing with legacy DNS::
1463 @node Creating a Zone
1464 @subsection Creating a Zone
1466 To use GNS, you probably should create at least one zone of your own.
1467 You can create any number of zones using the gnunet-identity tool
1471 $ gnunet-identity -C "myzone"
1474 Henceforth, on your system you control the TLD ``myzone''.
1476 All of your zones can be listed using the @command{gnunet-identity}
1477 command line tool as well:
1480 $ gnunet-identity -d
1483 @node Maintaining your own Zones
1484 @subsection Maintaining your own Zones
1487 Now you can add (or edit, or remove) records in your GNS zone using the
1488 @command{gnunet-namestore-gtk} GUI or using the @command{gnunet-namestore}
1490 In either case, your records will be stored in an SQL database under
1491 control of the @command{gnunet-service-namestore}.
1492 Note that if multiple users use one peer, the namestore database will
1493 include the combined records of all users.
1494 However, users will not be able to see each other's records
1495 if they are marked as private.
1497 To provide a short example for editing your own zone, suppose you
1498 have your own web server with the IP @code{1.2.3.4}. Then you can put an
1499 @code{A} record (@code{A} records in DNS are for IPv4 IP addresses)
1500 into your local zone ``myzone'' using the command:
1503 $ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e never
1507 Afterwards, you will be able to access your webpage under "www.myzone"
1508 (assuming your webserver does not use virtual hosting, if it does,
1509 please read up on setting up the GNS proxy).
1511 Similar commands will work for other types of DNS and GNS records,
1512 the syntax largely depending on the type of the record.
1513 Naturally, most users may find editing the zones using the
1514 @command{gnunet-namestore-gtk} GUI to be easier.
1516 @node Obtaining your Zone Key
1517 @subsection Obtaining your Zone Key
1519 Each zone in GNS has a public-private key. Usually, gnunet-namestore and
1520 gnunet-setup will access your private key as necessary, so you do not
1521 have to worry about those. What is important is your public key
1522 (or rather, the hash of your public key), as you will likely want to
1523 give it to others so that they can securely link to you.
1525 You can usually get the hash of your public key using
1528 $ gnunet-identity -d $options | grep myzone | awk '@{print $3@}'
1532 For example, the output might be something like:
1535 DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0
1539 Alternatively, you can obtain a QR code with your zone key AND your
1540 pseudonym from gnunet-namestore-gtk. The QR code is displayed in the
1541 main window and can be stored to disk using the ``Save as'' button
1544 @node Adding Links to Other Zones
1545 @subsection Adding Links to Other Zones
1548 A central operation in GNS is the ability to securely delegate to
1549 other zones. Basically, by adding a delegation you make all of the
1550 names from the other zone available to yourself. This section
1551 describes how to create delegations.
1553 Suppose you have a friend who you call 'bob' who also uses GNS.
1554 You can then delegate resolution of names to Bob's zone by adding
1555 a PKEY record to their local zone:
1558 $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never -Z myzone
1562 Note that ``XXXX'' in the command above must be replaced with the hash
1563 of Bob's public key (the output your friend obtained using the
1564 @command{gnunet-identity} command from the previous section and told
1565 you, for example by giving you a business card containing this
1566 information as a QR code).
1568 Assuming Bob has an ``A'' record for their website under the name of
1569 ``www'' in his zone, you can then access Bob's website under
1570 ``www.bob.myzone'' --- as well as any (public) GNS record that Bob has
1571 in their zone by replacing www with the respective name of the
1572 record in Bob's zone.
1574 @c themselves? themself?
1575 Furthermore, if Bob has themselves a (public) delegation to Carol's
1576 zone under "carol", you can access Carol's records under
1577 ``NAME.carol.bob.myzone'' (where ``NAME'' is the name of Carol's
1578 record you want to access).
1581 @node Using Public Keys as Top Level Domains
1582 @subsection Using Public Keys as Top Level Domains
1585 GNS also assumes responsibility for any name that uses in a well-formed
1586 public key for the TLD. Names ending this way are then resolved by querying
1587 the respective zone. Such public key TLDs are expected to be used under rare
1588 circumstances where globally unique names are required, and for
1589 integration with legacy systems.
1591 @node Resource Records in GNS
1592 @subsection Resource Records in GNS
1595 GNS supports the majority of the DNS records as defined in
1596 @uref{http://www.ietf.org/rfc/rfc1035.txt, RFC 1035}. Additionally,
1597 GNS defines some new record types the are unique to the GNS system.
1598 For example, GNS-specific resource records are used to give petnames
1599 for zone delegation, revoke zone keys and provide some compatibility
1602 For some DNS records, GNS does extended processing to increase their
1603 usefulness in GNS. In particular, GNS introduces special names
1604 referred to as "zone relative names". Zone relative names are allowed
1605 in some resource record types (for example, in NS and CNAME records)
1606 and can also be used in links on webpages. Zone relative names end
1607 in ".+" which indicates that the name needs to be resolved relative
1608 to the current authoritative zone. The extended processing of those
1609 names will expand the ".+" with the correct delegation chain to the
1610 authoritative zone (replacing ".+" with the name of the location
1611 where the name was encountered) and hence generate a
1614 GNS currently supports the following record types:
1625 * SOA SRV PTR and MX::
1631 A NICK record is used to give a zone a name. With a NICK record, you can
1632 essentially specify how you would like to be called. GNS expects this
1633 record under the empty label ``@@'' in the zone's database (NAMESTORE); however,
1634 it will then automatically be copied into each record set, so that
1635 clients never need to do a separate lookup to discover the NICK record.
1636 Also, users do not usually have to worry about setting the NICK record:
1637 it is automatically set to the local name of the TLD.
1642 Name: @@; RRType: NICK; Value: bob
1646 This record in Bob's zone will tell other users that this zone wants
1647 to be referred to as 'bob'. Note that nobody is obliged to call Bob's
1648 zone 'bob' in their own zones. It can be seen as a
1649 recommendation ("Please call this zone 'bob'").
1654 PKEY records are used to add delegation to other users' zones and
1655 give those zones a petname.
1659 Let Bob's zone be identified by the hash "ABC012". Bob is your friend
1660 so you want to give them the petname "friend". Then you add the
1661 following record to your zone:
1664 Name: friend; RRType: PKEY; Value: ABC012;
1668 This will allow you to resolve records in bob's zone
1669 under "*.friend.gnu".
1674 BOX records are there to integrate information from TLSA or
1675 SRV records under the main label. In DNS, TLSA and SRV records
1676 use special names of the form @code{_port._proto.(label.)*tld} to
1677 indicate the port number and protocol (i.e. tcp or udp) for which
1678 the TLSA or SRV record is valid. This causes various problems, and
1679 is elegantly solved in GNS by integrating the protocol and port
1680 numbers together with the respective value into a "BOX" record.
1681 Note that in the GUI, you do not get to edit BOX records directly
1682 right now --- the GUI will provide the illusion of directly
1683 editing the TLSA and SRV records, even though they internally
1689 The LEgacy HOstname of a server. Some webservers expect a specific
1690 hostname to provide a service (virtiual hosting). Also SSL
1691 certificates usually contain DNS names. To provide the expected
1692 legacy DNS name for a server, the LEHO record can be used.
1693 To mitigate the just mentioned issues the GNS proxy has to be used.
1694 The GNS proxy will use the LEHO information to apply the necessary
1700 GNS allows easy access to services provided by the GNUnet Virtual Public
1701 Network. When the GNS resolver encounters a VPN record it will contact
1702 the VPN service to try and allocate an IPv4/v6 address (if the queries
1703 record type is an IP address) that can be used to contact the service.
1707 I want to provide access to the VPN service "web.gnu." on port 80 on peer
1709 Name: www; RRType: VPN; Value: 80 ABC012 web.gnu.
1711 The peer ABC012 is configured to provide an exit point for the service
1712 "web.gnu." on port 80 to it's server running locally on port 8080 by
1713 having the following lines in the @file{gnunet.conf} configuration file:
1717 TCP_REDIRECTS = 80:localhost4:8080
1720 @node A AAAA and TXT
1721 @subsubsection A AAAA and TXT
1723 Those records work in exactly the same fashion as in traditional DNS.
1726 @subsubsection CNAME
1728 As specified in RFC 1035 whenever a CNAME is encountered the query
1729 needs to be restarted with the specified name. In GNS a CNAME
1733 @item A zone relative name,
1734 @item A zkey name or
1735 @item A DNS name (in which case resolution will continue outside
1736 of GNS with the systems DNS resolver)
1740 @subsubsection GNS2DNS
1742 GNS can delegate authority to a legacy DNS zone. For this, the
1743 name of the DNS nameserver and the name of the DNS zone are
1744 specified in a GNS2DNS record.
1749 Name: pet; RRType: GNS2DNS; Value: gnunet.org@@a.ns.joker.com
1753 Any query to @code{pet.gnu} will then be delegated to the DNS server at
1754 @code{a.ns.joker.com}. For example,
1755 @code{@uref{http://www.pet.gnu/, www.pet.gnu}} will result in a DNS query
1756 for @code{@uref{http://www.gnunet.org/, www.gnunet.org}} to the server
1757 at @code{a.ns.joker.com}. Delegation to DNS via NS records in GNS can
1758 be useful if you do not want to start resolution in the DNS root zone
1759 (due to issues such as censorship or availability).
1761 Note that you would typically want to use a relative name for the
1765 Name: pet; RRType: GNS2DNS; Value: gnunet.org@@ns-joker.+@
1766 Name: ns-joker; RRType: A; Value: 184.172.157.218
1770 This way, you can avoid involving the DNS hierarchy in the resolution of
1771 @code{a.ns.joker.com}. In the example above, the problem may not be
1772 obvious as the nameserver for "gnunet.org" is in the ".com" zone.
1773 However, imagine the nameserver was "ns.gnunet.org". In this case,
1774 delegating to "ns.gnunet.org" would mean that despite using GNS,
1775 censorship in the DNS ".org" zone would still be effective.
1777 @node SOA SRV PTR and MX
1778 @subsubsection SOA SRV PTR and MX
1780 The domain names in those records can, again, be either
1783 @item A zone relative name,
1784 @item A zkey name or
1788 The resolver will expand the zone relative name if possible.
1789 Note that when using MX records within GNS, the target mail
1790 server might still refuse to accept e-mails to the resulting
1791 domain as the name might not match. GNS-enabled mail clients
1792 should use the ZKEY zone as the destination hostname and
1793 GNS-enabled mail servers should be configured to accept
1794 e-mails to the ZKEY-zones of all local users.
1796 @node Synchronizing with legacy DNS
1797 @subsection Synchronizing with legacy DNS
1799 If you want to support GNS but the master database for a zone
1800 is only available and maintained in DNS, GNUnet includes the
1801 @command{gnunet-zoneimport} tool to monitor a DNS zone and
1802 automatically import records into GNS. Today, the tool does
1803 not yet support DNS AF(X)R, as we initially used it on the
1804 ``.fr'' zone which does not allow us to perform a DNS zone
1805 transfer. Instead, @command{gnunet-zoneimport} reads a list
1806 of DNS domain names from @code{stdin}, issues DNS queries for
1807 each, converts the obtained records (if possible) and stores
1808 the result in the namestore.
1810 @image{images/gns,6in,, picture of DNS-GNS data flow}
1812 The zonemaster service then takes the records from the namestore,
1813 publishes them into the DHT which makes the result available to the
1814 GNS resolver. In the GNS configuration, non-local zones can be
1815 configured to be intercepted by specifying ``.tld = PUBLICKEY'' in the
1816 configuration file in the ``[gns]'' section.
1818 Note that the namestore by default also populates the namecache.
1819 This pre-population is cryptographically expensive. Thus, on
1820 systems that only serve to import a large (millions of records)
1821 DNS zone and that do not have a local gns service in use, it
1822 is thus advisable to disable the namecache by setting the
1823 option ``DISABLE'' to ``YES'' in section ``[namecache]''.
1826 @node Using the Virtual Public Network
1827 @section Using the Virtual Public Network
1830 * Setting up an Exit node::
1831 * Fedora and the Firewall::
1832 * Setting up VPN node for protocol translation and tunneling::
1835 Using the GNUnet Virtual Public Network (VPN) application you can
1836 tunnel IP traffic over GNUnet. Moreover, the VPN comes
1837 with built-in protocol translation and DNS-ALG support, enabling
1838 IPv4-to-IPv6 protocol translation (in both directions).
1839 This chapter documents how to use the GNUnet VPN.
1841 The first thing to note about the GNUnet VPN is that it is a public
1842 network. All participating peers can participate and there is no
1843 secret key to control access. So unlike common virtual private
1844 networks, the GNUnet VPN is not useful as a means to provide a
1845 "private" network abstraction over the Internet. The GNUnet VPN
1846 is a virtual network in the sense that it is an overlay over the
1847 Internet, using its own routing mechanisms and can also use an
1848 internal addressing scheme. The GNUnet VPN is an Internet
1849 underlay --- TCP/IP applications run on top of it.
1851 The VPN is currently only supported on GNU/Linux systems.
1852 Support for operating systems that support TUN (such as FreeBSD)
1853 should be easy to add (or might not even require any coding at
1854 all --- we just did not test this so far). Support for other
1855 operating systems would require re-writing the code to create virtual
1856 network interfaces and to intercept DNS requests.
1858 The VPN does not provide good anonymity. While requests are routed
1859 over the GNUnet network, other peers can directly see the source
1860 and destination of each (encapsulated) IP packet. Finally, if you
1861 use the VPN to access Internet services, the peer sending the
1862 request to the Internet will be able to observe and even alter
1863 the IP traffic. We will discuss additional security implications
1864 of using the VPN later in this chapter.
1866 @node Setting up an Exit node
1867 @subsection Setting up an Exit node
1869 Any useful operation with the VPN requires the existence of an exit
1870 node in the GNUnet Peer-to-Peer network. Exit functionality can only
1871 be enabled on peers that have regular Internet access. If you want
1872 to play around with the VPN or support the network, we encourage
1873 you to setup exit nodes. This chapter documents how to setup an
1876 There are four types of exit functions an exit node can provide,
1877 and using the GNUnet VPN to access the Internet will only work
1878 nicely if the first three types are provided somewhere in
1879 the network. The four exit functions are:
1882 @item DNS: allow other peers to use your DNS resolver
1883 @item IPv4: allow other peers to access your IPv4 Internet connection
1884 @item IPv6: allow other peers to access your IPv6 Internet connection
1885 @item Local service: allow other peers to access a specific TCP or
1886 UDP service your peer is providing
1889 By enabling "exit" in gnunet-setup and checking the respective boxes
1890 in the "exit" tab, you can easily choose which of the above exit
1891 functions you want to support.
1893 Note, however, that by supporting the first three functions you will
1894 allow arbitrary other GNUnet users to access the Internet via your
1895 system. This is somewhat similar to running a Tor exit node. The
1896 Torproject has a nice article about what to consider if you want
1897 to do this here. We believe that generally running a DNS exit node
1898 is completely harmless.
1900 The exit node configuration does currently not allow you to restrict the
1901 Internet traffic that leaves your system. In particular, you cannot
1902 exclude SMTP traffic (or block port 25) or limit to HTTP traffic using
1903 the GNUnet configuration. However, you can use your host firewall to
1904 restrict outbound connections from the virtual tunnel interface. This
1905 is highly recommended. In the future, we plan to offer a wider range
1906 of configuration options for exit nodes.
1908 Note that by running an exit node GNUnet will configure your kernel
1909 to perform IP-forwarding (for IPv6) and NAT (for IPv4) so that the
1910 traffic from the virtual interface can be routed to the Internet.
1911 In order to provide an IPv6-exit, you need to have a subnet routed
1912 to your host's external network interface and assign a subrange of
1913 that subnet to the GNUnet exit's TUN interface.
1915 When running a local service, you should make sure that the local
1916 service is (also) bound to the IP address of your EXIT interface
1917 (i.e. 169.254.86.1). It will NOT work if your local service is
1918 just bound to loopback. You may also want to create a "VPN" record
1919 in your zone of the GNU Name System to make it easy for others to
1920 access your service via a name instead of just the full service
1921 descriptor. Note that the identifier you assign the service can
1922 serve as a passphrase or shared secret, clients connecting to the
1923 service must somehow learn the service's name. VPN records in the
1924 GNU Name System can make this easier.
1926 @node Fedora and the Firewall
1927 @subsection Fedora and the Firewall
1930 When using an exit node on Fedora 15, the standard firewall can
1931 create trouble even when not really exiting the local system!
1932 For IPv4, the standard rules seem fine. However, for IPv6 the
1933 standard rules prohibit traffic from the network range of the
1934 virtual interface created by the exit daemon to the local IPv6
1935 address of the same interface (which is essentially loopback
1936 traffic, so you might suspect that a standard firewall would
1937 leave this traffic alone). However, as somehow for IPv6 the
1938 traffic is not recognized as originating from the local
1939 system (and as the connection is not already "established"),
1940 the firewall drops the traffic. You should still get ICMPv6
1941 packets back, but that's obviously not very useful.
1943 Possible ways to fix this include disabling the firewall (do you
1944 have a good reason for having it on?) or disabling the firewall
1945 at least for the GNUnet exit interface (or the respective
1946 IPv4/IPv6 address range). The best way to diagnose these kinds
1947 of problems in general involves setting the firewall to REJECT
1948 instead of DROP and to watch the traffic using wireshark
1949 (or tcpdump) to see if ICMP messages are generated when running
1950 some tests that should work.
1952 @node Setting up VPN node for protocol translation and tunneling
1953 @subsection Setting up VPN node for protocol translation and tunneling
1956 The GNUnet VPN/PT subsystem enables you to tunnel IP traffic over the
1957 VPN to an exit node, from where it can then be forwarded to the
1958 Internet. This section documents how to setup VPN/PT on a node.
1959 Note that you can enable both the VPN and an exit on the same peer.
1960 In this case, IP traffic from your system may enter your peer's VPN
1961 and leave your peer's exit. This can be useful as a means to do
1962 protocol translation. For example, you might have an application that
1963 supports only IPv4 but needs to access an IPv6-only site. In this case,
1964 GNUnet would perform 4to6 protocol translation between the VPN (IPv4)
1965 and the Exit (IPv6). Similarly, 6to4 protocol translation is also
1966 possible. However, the primary use for GNUnet would be to access
1967 an Internet service running with an IP version that is not supported
1968 by your ISP. In this case, your IP traffic would be routed via GNUnet
1969 to a peer that has access to the Internet with the desired IP version.
1971 Setting up an entry node into the GNUnet VPN primarily requires you
1972 to enable the "VPN/PT" option in "gnunet-setup". This will launch the
1973 "gnunet-service-vpn", "gnunet-service-dns" and "gnunet-daemon-pt"
1974 processes. The "gnunet-service-vpn" will create a virtual interface
1975 which will be used as the target for your IP traffic that enters the
1976 VPN. Additionally, a second virtual interface will be created by
1977 the "gnunet-service-dns" for your DNS traffic. You will then need to
1978 specify which traffic you want to tunnel over GNUnet. If your ISP only
1979 provides you with IPv4 or IPv6-access, you may choose to tunnel the
1980 other IP protocol over the GNUnet VPN. If you do not have an ISP
1981 (and are connected to other GNUnet peers via WLAN), you can also
1982 choose to tunnel all IP traffic over GNUnet. This might also provide
1983 you with some anonymity. After you enable the respective options
1984 and restart your peer, your Internet traffic should be tunneled
1985 over the GNUnet VPN.
1987 The GNUnet VPN uses DNS-ALG to hijack your IP traffic. Whenever an
1988 application resolves a hostname (i.e. 'gnunet.org'), the
1989 "gnunet-daemon-pt" will instruct the "gnunet-service-dns" to intercept
1990 the request (possibly route it over GNUnet as well) and replace the
1991 normal answer with an IP in the range of the VPN's interface.
1992 "gnunet-daemon-pt" will then tell "gnunet-service-vpn" to forward all
1993 traffic it receives on the TUN interface via the VPN to the original
1996 For applications that do not use DNS, you can also manually create
1997 such a mapping using the gnunet-vpn command-line tool. Here, you
1998 specfiy the desired address family of the result (i.e. "-4"), and the
1999 intended target IP on the Internet ("-i 131.159.74.67") and
2000 "gnunet-vpn" will tell you which IP address in the range of your
2001 VPN tunnel was mapped.
2003 @command{gnunet-vpn} can also be used to access "internal" services
2004 offered by GNUnet nodes. So if you happen to know a peer and a
2005 service offered by that peer, you can create an IP tunnel to
2006 that peer by specifying the peer's identity, service name and
2007 protocol (--tcp or --udp) and you will again receive an IP address
2008 that will terminate at the respective peer's service.