diff options
Diffstat (limited to 'doc/documentation')
87 files changed, 0 insertions, 22122 deletions
diff --git a/doc/documentation/.gitignore b/doc/documentation/.gitignore deleted file mode 100644 index f490c3412..000000000 --- a/doc/documentation/.gitignore +++ /dev/null | |||
| @@ -1,9 +0,0 @@ | |||
| 1 | stamp-1 | ||
| 2 | version2.texi | ||
| 3 | manual | ||
| 4 | *.fn | ||
| 5 | *.fns | ||
| 6 | *.ky | ||
| 7 | *.pg | ||
| 8 | *.tp | ||
| 9 | *.vr | ||
diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am deleted file mode 100644 index cd3fca854..000000000 --- a/doc/documentation/Makefile.am +++ /dev/null | |||
| @@ -1,245 +0,0 @@ | |||
| 1 | # This Makefile.am is in the public domain | ||
| 2 | docdir = $(datadir)/doc/gnunet/ | ||
| 3 | |||
| 4 | infoimagedir = $(infodir)/images | ||
| 5 | |||
| 6 | #DOT_FILES = images/$(wildcard *.dot) | ||
| 7 | |||
| 8 | #DOT_VECTOR_GRAPHICS = \ | ||
| 9 | # $(DOT_FILES:%.dot=%.eps) \ | ||
| 10 | # $(DOT_FILES:%.dot=%.pdf) | ||
| 11 | |||
| 12 | AM_MAKEINFOHTMLFLAGS = --no-split --css-ref=docstyle.css | ||
| 13 | |||
| 14 | dist_infoimage_DATA = \ | ||
| 15 | images/gnunet-gtk-0-10-gns-a-done.png \ | ||
| 16 | images/gnunet-gtk-0-10-gns-a.png \ | ||
| 17 | images/daemon_lego_block.png \ | ||
| 18 | images/gnunet-gtk-0-10-gns.png \ | ||
| 19 | images/gnunet-0-10-peerinfo.png \ | ||
| 20 | images/gnunet-gtk-0-10-identity.png \ | ||
| 21 | images/gnunet-fs-gtk-0-10-star-tab.png \ | ||
| 22 | images/gnunet-gtk-0-10-download-area.png \ | ||
| 23 | images/gnunet-gtk-0-10-search-selected.png \ | ||
| 24 | images/gnunet-gtk-0-10-fs-menu.png \ | ||
| 25 | images/gnunet-gtk-0-10-traffic.png \ | ||
| 26 | images/gnunet-gtk-0-10-fs.png \ | ||
| 27 | images/gnunet-namestore-gtk-phone.png \ | ||
| 28 | images/gnunet-gtk-0-10-fs-publish-editing.png \ | ||
| 29 | images/gnunet-namestore-gtk-vpn.png \ | ||
| 30 | images/gnunet-gtk-0-10-fs-published.png \ | ||
| 31 | images/gnunet-setup-exit.png \ | ||
| 32 | images/gnunet-gtk-0-10-fs-publish.png \ | ||
| 33 | images/iceweasel-preferences.png \ | ||
| 34 | images/gnunet-gtk-0-10-fs-publish-select.png \ | ||
| 35 | images/iceweasel-proxy.png \ | ||
| 36 | images/gnunet-gtk-0-10-fs-publish-with-file_0.png \ | ||
| 37 | images/service_lego_block.png \ | ||
| 38 | images/gnunet-gtk-0-10-fs-publish-with-file.png \ | ||
| 39 | images/service_stack.png \ | ||
| 40 | images/gnunet-gtk-0-10-fs-search.png \ | ||
| 41 | images/gnunet-tutorial-service.png \ | ||
| 42 | images/gnunet-tutorial-system.png \ | ||
| 43 | images/daemon_lego_block.svg \ | ||
| 44 | images/lego_stack.svg \ | ||
| 45 | images/service_lego_block.svg \ | ||
| 46 | images/structure.dot \ | ||
| 47 | images/gns.dot | ||
| 48 | |||
| 49 | # images/$(wildcard *.png) \ | ||
| 50 | # images/$(wildcard *.svg) | ||
| 51 | # $(DOT_FILES:%.dot=%.png) | ||
| 52 | |||
| 53 | #DOT_OPTIONS = \ | ||
| 54 | # -Gratio=.9 -Gnodesep=.005 -Granksep=.00005 \ | ||
| 55 | # -Nfontsite=9 -Nheight=.1 -Nwidth=.1 | ||
| 56 | |||
| 57 | # .dot.png: | ||
| 58 | # $(AM_V_DOT)$(DOT) -Tpng $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \ | ||
| 59 | # mv "$(srcdir)/$@.tmp" "$(srcdir)/$@" | ||
| 60 | |||
| 61 | # .dot.pdf: | ||
| 62 | # $(AM_V_DOT)$(DOT) -Tpdf $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \ | ||
| 63 | # mv "$(srcdir)/$@.tmp" "$(srcdir)/$@" | ||
| 64 | |||
| 65 | # .dot.eps: | ||
| 66 | # $(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \ | ||
| 67 | # mv "$(srcdir)/$@.tmp" "$(srcdir)/$@" | ||
| 68 | |||
| 69 | # .png.eps: | ||
| 70 | # $(AM_V_GEN)convert "$<" "$@-tmp.eps"; \ | ||
| 71 | # mv "$@-tmp.eps" "$@" | ||
| 72 | |||
| 73 | # pdf-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.pdf) | ||
| 74 | # info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png) | ||
| 75 | # ps-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps) \ | ||
| 76 | # $(top_srcdir)/%D%/images/coreutils-size-map.eps | ||
| 77 | # dvi-local: ps-local | ||
| 78 | |||
| 79 | |||
| 80 | gnunet_tutorial_examples = \ | ||
| 81 | tutorial-examples/001.c \ | ||
| 82 | tutorial-examples/002.c \ | ||
| 83 | tutorial-examples/003.c \ | ||
| 84 | tutorial-examples/004.c \ | ||
| 85 | tutorial-examples/005.c \ | ||
| 86 | tutorial-examples/006.c \ | ||
| 87 | tutorial-examples/007.c \ | ||
| 88 | tutorial-examples/008.c \ | ||
| 89 | tutorial-examples/009.c \ | ||
| 90 | tutorial-examples/010.c \ | ||
| 91 | tutorial-examples/011.c \ | ||
| 92 | tutorial-examples/012.c \ | ||
| 93 | tutorial-examples/013.c \ | ||
| 94 | tutorial-examples/013.1.c \ | ||
| 95 | tutorial-examples/014.c \ | ||
| 96 | tutorial-examples/015.c \ | ||
| 97 | tutorial-examples/016.c \ | ||
| 98 | tutorial-examples/017.c \ | ||
| 99 | tutorial-examples/018.c \ | ||
| 100 | tutorial-examples/019.c \ | ||
| 101 | tutorial-examples/020.c \ | ||
| 102 | tutorial-examples/021.c \ | ||
| 103 | tutorial-examples/022.c \ | ||
| 104 | tutorial-examples/023.c \ | ||
| 105 | tutorial-examples/024.c \ | ||
| 106 | tutorial-examples/025.Makefile.am \ | ||
| 107 | tutorial-examples/026.c | ||
| 108 | |||
| 109 | info_TEXINFOS = \ | ||
| 110 | gnunet.texi \ | ||
| 111 | gnunet-c-tutorial.texi | ||
| 112 | |||
| 113 | gnunet_TEXINFOS = \ | ||
| 114 | chapters/developer.texi \ | ||
| 115 | chapters/preface.texi \ | ||
| 116 | chapters/philosophy.texi \ | ||
| 117 | chapters/installation.texi \ | ||
| 118 | chapters/user.texi \ | ||
| 119 | chapters/vocabulary.texi \ | ||
| 120 | chapters/configuration.texi \ | ||
| 121 | chapters/contributing.texi \ | ||
| 122 | fdl-1.3.texi \ | ||
| 123 | gpl-3.0.texi | ||
| 124 | |||
| 125 | EXTRA_DIST = \ | ||
| 126 | $(gnunet_TEXINFOS) \ | ||
| 127 | $(gnunet_tutorial_examples) \ | ||
| 128 | htmlxref.cnf \ | ||
| 129 | gversion.texi | ||
| 130 | run-gendocs.sh \ | ||
| 131 | docstyle.css | ||
| 132 | |||
| 133 | |||
| 134 | # $(DOT_FILES) \ | ||
| 135 | # $(DOT_VECTOR_GRAPHICS) | ||
| 136 | |||
| 137 | DISTCLEANFILES = \ | ||
| 138 | gnunet.cps \ | ||
| 139 | gnunet-c-tutorial.cps \ | ||
| 140 | chapters/developer.cps \ | ||
| 141 | chapters/installation.cps \ | ||
| 142 | chapter/philosophy.cps \ | ||
| 143 | chapters/user.cps \ | ||
| 144 | chapters/configuration.cps \ | ||
| 145 | chapters/terminology.cps \ | ||
| 146 | chapters/vocabulary.cps \ | ||
| 147 | fdl-1.3.cps \ | ||
| 148 | agpl-3.0.cps \ | ||
| 149 | gpl-3.0.cps | ||
| 150 | |||
| 151 | # if HAVE_EXTENDED_DOCUMENTATION_BUILDING | ||
| 152 | daemon_lego_block.png: images/daemon_lego_block.svg | ||
| 153 | convert images/daemon_lego_block.svg images/daemon_lego_block.png && | ||
| 154 | pngcrush images/daemon_lego_block.png images/daemon_lego_block.png | ||
| 155 | |||
| 156 | service_lego_block.png: images/service_lego_block.svg | ||
| 157 | convert images/service_lego_block.svg images/service_lego_block.png && | ||
| 158 | pngcrush images/service_lego_block.png images/serivce_lego_block.png | ||
| 159 | |||
| 160 | lego_stack.png: images/lego_stack.svg | ||
| 161 | convert images/lego_stack.svg images/lego_stack.png && | ||
| 162 | pngcrush images/lego_stack.png images/lego_stack.png | ||
| 163 | |||
| 164 | # XXX: is this sed invocation portable enough? otherwise try tr(1). | ||
| 165 | version.texi/replacement: version.texi/replacement/revert | ||
| 166 | @sed -i "s/GPACKAGE_VERSION/$(PACKAGE_VERSION)/g" gversion.texi | ||
| 167 | |||
| 168 | version.texi/replacement/revert: | ||
| 169 | @echo "@set VERSION GPACKAGE_VERSION" > gversion.texi | ||
| 170 | @echo "@set EDITION GPACKAGE_VERSION" >> gversion.texi | ||
| 171 | |||
| 172 | if SECTION7 | ||
| 173 | gnunet-c-tutorial.7: version.texi/replacement | ||
| 174 | @echo Attempting to output an mdoc formatted section 7 document | ||
| 175 | @texi2mdoc -I$(pwd):$(pwd)/chapters gnunet-c-tutorial.texi > ../man/gnunet-c-tutorial.7 | ||
| 176 | |||
| 177 | gnunet-documentation.7: version.texi/replacement | ||
| 178 | @echo Attempting to output an mdoc formatted section 7 document | ||
| 179 | @texi2mdoc -I$(pwd):$(pwd)/chapters gnunet.texi > ../man/gnunet-documentation.7 | ||
| 180 | |||
| 181 | # TODO: (Maybe) other outputs resulting from this. | ||
| 182 | endif | ||
| 183 | |||
| 184 | # FIXME: rm *.html and *.pdf | ||
| 185 | #doc-clean: | ||
| 186 | # @rm *.aux *.log *.toc *.cp *.cps | ||
| 187 | |||
| 188 | all: version.texi/replacement | ||
| 189 | |||
| 190 | doc-all-install: | ||
| 191 | @mkdir -p $(DESTDIR)/$(docdir) | ||
| 192 | @mkdir -p $(DESTDIR)/$(infoimagedir) | ||
| 193 | @mkdir -p $(DESTDIR)/$(infodir) | ||
| 194 | @install -m 0755 gnunet.pdf $(DESTDIR)/$(docdir) | ||
| 195 | @install -m 0755 gnunet-c-tutorial.pdf $(DESTDIR)/$(docdir) | ||
| 196 | @install -m 0755 gnunet-c-tutorial.info $(DESTDIR)/$(infodir) | ||
| 197 | @install -m 0755 gnunet.info $(DESTDIR)/$(infodir) | ||
| 198 | @install gnunet.html $(DESTDIR)/$(docdir) | ||
| 199 | @install gnunet-c-tutorial.html $(DESTDIR)/$(docdir) | ||
| 200 | |||
| 201 | doc-gendoc-install: | ||
| 202 | @mkdir -p $(DESTDIR)/$(docdir) | ||
| 203 | @cp -r manual $(DESTDIR)/$(docdir) | ||
| 204 | |||
| 205 | # @cp -r images $(DESTDIR)/$(infoimagedir) | ||
| 206 | |||
| 207 | dev-build: version.texi/replacement | ||
| 208 | @makeinfo --pdf gnunet.texi | ||
| 209 | @makeinfo --pdf gnunet-c-tutorial.texi | ||
| 210 | @makeinfo --html gnunet.texi | ||
| 211 | @makeinfo --html gnunet-c-tutorial.texi | ||
| 212 | @makeinfo --no-split gnunet.texi | ||
| 213 | @makeinfo --no-split gnunet-c-tutorial.texi | ||
| 214 | |||
| 215 | # TODO: Add more to clean. | ||
| 216 | clean: version.texi/replacement/revert | ||
| 217 | @rm -f gnunet.pdf | ||
| 218 | @rm -f gnunet.html | ||
| 219 | @rm -f gnunet.info | ||
| 220 | @rm -f gnunet.info-1 | ||
| 221 | @rm -f gnunet.info-2 | ||
| 222 | @rm -f gnunet.info-3 | ||
| 223 | @rm -f gnunet-c-tutorial.pdf | ||
| 224 | @rm -f gnunet-c-tutorial.info | ||
| 225 | @rm -f gnunet-c-tutorial.html | ||
| 226 | @rm -fr gnunet.t2p | ||
| 227 | @rm -fr gnunet-c-tutorial.t2p | ||
| 228 | @rm -fr manual | ||
| 229 | |||
| 230 | # CLEANFILES = \ | ||
| 231 | # gnunet.log \ | ||
| 232 | # gnunet-c-tutorial.log \ | ||
| 233 | # $(wildcard *.aux) \ | ||
| 234 | # $(wildcard *.toc) \ | ||
| 235 | # $(wildcard *.cp) \ | ||
| 236 | # $(wildcard *.cps) | ||
| 237 | |||
| 238 | #.PHONY: version.texi | ||
| 239 | # if HAVE_EXTENDED_DOCUMENTATION_BUILDING_PDF | ||
| 240 | |||
| 241 | # if HAVE_EXTENDED_DOCUMENTATION_BUILDING_HTML | ||
| 242 | |||
| 243 | # endif | ||
| 244 | # endif | ||
| 245 | # endif | ||
diff --git a/doc/documentation/TODO b/doc/documentation/TODO deleted file mode 100644 index fa1ce7a23..000000000 --- a/doc/documentation/TODO +++ /dev/null | |||
| @@ -1,106 +0,0 @@ | |||
| 1 | -*- mode: org -*- | ||
| 2 | |||
| 3 | TODO - or: the Documentation Masterplan. | ||
| 4 | |||
| 5 | To some extent this duplicates the Mantis tickets on this topic. | ||
| 6 | |||
| 7 | * Motivation | ||
| 8 | My motivation is to read into good documentations and create a self-contained collection of books, | ||
| 9 | which can be understood without expecting too much background knowledge in every topic. | ||
| 10 | ** User Handbook: | ||
| 11 | The content of the User book should be mostly concerned with our current and future graphical (gtk | ||
| 12 | as well as terminal user interface) applications. After reading Preface and maybe Philosophy, the | ||
| 13 | person reading the User Handbook should understand with the least possible strugle the application | ||
| 14 | they intend to use. Examples should be given and concepts explained. | ||
| 15 | ** Installation Handbook: | ||
| 16 | As seen with requests on the mailinglist, we will have to pick up people where they are, similar | ||
| 17 | to the User Handbook. People already used to compiling and installing should have the chance to | ||
| 18 | skip to the end, everyone else should: have step-by-step instructions, which will either already | ||
| 19 | include OS specific notes or will be followed by OS specific instructions. It is up for discussion | ||
| 20 | if configuring GNUnet is 'User Handbook' or 'Installation Handbook', the current mixture in | ||
| 21 | the Installation Handbook is not good. | ||
| 22 | ** Contributors Handbook: | ||
| 23 | This chapter could either be reduced to a couple of sections following the theme of 'contributing | ||
| 24 | to GNUnet' or the chapter could be extended. If we extend it, we should explain a range of topics | ||
| 25 | that can be useful for contributors. It can be understood as a recommended reading in addition to | ||
| 26 | the Developer Handbook then, and the Developer Handbook could simply become a better commented | ||
| 27 | reference for the code-base. | ||
| 28 | ** Developer Handbook: | ||
| 29 | As outlined in the last sentences, the Developer Handbook could be reduced to the necessary bits | ||
| 30 | with enough comments to be understood without reading into the papers published over the years. | ||
| 31 | |||
| 32 | |||
| 33 | * DONE 1. Drupal books export to LaTeX. | ||
| 34 | * DONE 2. LaTeX conversion to Texinfo. | ||
| 35 | * DONE 3. (initial) Fixup of syntax errors introduced in conversion chain. | ||
| 36 | * TODO 4. Update content. | ||
| 37 | * TODO 5. Create API Reference or similar | ||
| 38 | * TODO 6. Create Concept Index | ||
| 39 | * TODO 7. Create Procedure Index | ||
| 40 | * TODO 8. Create Type Index | ||
| 41 | * TODO 9. Create Functions Index | ||
| 42 | * TODO 10. Properly address concerns and criticism people had/have on the old and current documentation. | ||
| 43 | * TODO 11. Reorder structure | ||
| 44 | * TODO more TODO. | ||
| 45 | |||
| 46 | |||
| 47 | * Status Progress / Completion Levels | ||
| 48 | |||
| 49 | ** chapters/philosophy: around 100% fixed after initial export. | ||
| 50 | |||
| 51 | * System Integration Tasks | ||
| 52 | |||
| 53 | * Which Texlive modules are needed for every output we generate? | ||
| 54 | * Generate the images from their dot sources. | ||
| 55 | |||
| 56 | * How to use (hack) on this | ||
| 57 | |||
| 58 | This section will find its way into the documentation sooner or later. | ||
| 59 | Potentially outdated or inaccurate bits. | ||
| 60 | |||
| 61 | ** with guix | ||
| 62 | |||
| 63 | Adjust accordingly, ie read the Guix Documentation: | ||
| 64 | guix environment gnunet-doc | ||
| 65 | and | ||
| 66 | guix build -f contrib/packages/guix/gnunet-doc.scm | ||
| 67 | |||
| 68 | ** without guix | ||
| 69 | |||
| 70 | You need to have Texinfo and Texlive in your path. | ||
| 71 | sh bootstrap | ||
| 72 | ./configure --enable-documentation | ||
| 73 | cd doc | ||
| 74 | make (format you want) | ||
| 75 | |||
| 76 | for example: make html, make info, make pdf | ||
| 77 | |||
| 78 | * structure (relations) (old!) | ||
| 79 | |||
| 80 | ** gnunet.texi | ||
| 81 | -> chapters/developer.texi | ||
| 82 | -> chapters/installation.texi | ||
| 83 | -> chapters/philosophy.texi | ||
| 84 | -> chapters/user.texi | ||
| 85 | -> chapters/vocabulary.texi | ||
| 86 | -> images/* | ||
| 87 | -> gpl-3.0.texi | ||
| 88 | -> fdl-1.3.texi | ||
| 89 | |||
| 90 | ** gnunet-c-tutorial.texi | ||
| 91 | -> figs/Service.pdf | ||
| 92 | -> figs/System.pdf | ||
| 93 | -> tutorial-examples/*.c | ||
| 94 | -> gpl-3.0.texi | ||
| 95 | -> fdl-1.3.texi | ||
| 96 | |||
| 97 | - gnunet-c-tutorial-v1.pdf: original LaTeX "gnunet-c-tutorial.pdf". | ||
| 98 | - man folder: the man pages. | ||
| 99 | - doxygen folder | ||
| 100 | - outdated-and-old-installation-instructions.txt: self described within the file. | ||
| 101 | |||
| 102 | |||
| 103 | Use `gendocs', add to the manual/ directory of the web site. | ||
| 104 | |||
| 105 | $ cd doc | ||
| 106 | $ gendocs.sh gnunet "GNUnet 0.10.X Reference Manual" | ||
diff --git a/doc/documentation/agpl-3.0.texi b/doc/documentation/agpl-3.0.texi deleted file mode 100644 index eabb0c6df..000000000 --- a/doc/documentation/agpl-3.0.texi +++ /dev/null | |||
| @@ -1,698 +0,0 @@ | |||
| 1 | @c The GNU Affero General Public License. | ||
| 2 | @center Version 3, 19 November 2007 | ||
| 3 | |||
| 4 | @c This file is intended to be included within another document, | ||
| 5 | @c hence no sectioning command or @node. | ||
| 6 | |||
| 7 | @display | ||
| 8 | Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{https://fsf.org/} | ||
| 9 | |||
| 10 | Everyone is permitted to copy and distribute verbatim copies of this | ||
| 11 | license document, but changing it is not allowed. | ||
| 12 | @end display | ||
| 13 | |||
| 14 | @heading Preamble | ||
| 15 | |||
| 16 | The GNU Affero General Public License is a free, copyleft license | ||
| 17 | for software and other kinds of works, specifically designed to ensure | ||
| 18 | cooperation with the community in the case of network server software. | ||
| 19 | |||
| 20 | The licenses for most software and other practical works are | ||
| 21 | designed to take away your freedom to share and change the works. By | ||
| 22 | contrast, our General Public Licenses are intended to guarantee your | ||
| 23 | freedom to share and change all versions of a program--to make sure it | ||
| 24 | remains free software for all its users. | ||
| 25 | |||
| 26 | When we speak of free software, we are referring to freedom, not | ||
| 27 | price. Our General Public Licenses are designed to make sure that you | ||
| 28 | have the freedom to distribute copies of free software (and charge for | ||
| 29 | them if you wish), that you receive source code or can get it if you | ||
| 30 | want it, that you can change the software or use pieces of it in new | ||
| 31 | free programs, and that you know you can do these things. | ||
| 32 | |||
| 33 | Developers that use our General Public Licenses protect your rights | ||
| 34 | with two steps: (1) assert copyright on the software, and (2) offer | ||
| 35 | you this License which gives you legal permission to copy, distribute | ||
| 36 | and/or modify the software. | ||
| 37 | |||
| 38 | A secondary benefit of defending all users' freedom is that | ||
| 39 | improvements made in alternate versions of the program, if they | ||
| 40 | receive widespread use, become available for other developers to | ||
| 41 | incorporate. Many developers of free software are heartened and | ||
| 42 | encouraged by the resulting cooperation. However, in the case of | ||
| 43 | software used on network servers, this result may fail to come about. | ||
| 44 | The GNU General Public License permits making a modified version and | ||
| 45 | letting the public access it on a server without ever releasing its | ||
| 46 | source code to the public. | ||
| 47 | |||
| 48 | The GNU Affero General Public License is designed specifically to | ||
| 49 | ensure that, in such cases, the modified source code becomes available | ||
| 50 | to the community. It requires the operator of a network server to | ||
| 51 | provide the source code of the modified version running there to the | ||
| 52 | users of that server. Therefore, public use of a modified version, on | ||
| 53 | a publicly accessible server, gives the public access to the source | ||
| 54 | code of the modified version. | ||
| 55 | |||
| 56 | An older license, called the Affero General Public License and | ||
| 57 | published by Affero, was designed to accomplish similar goals. This is | ||
| 58 | a different license, not a version of the Affero GPL, but Affero has | ||
| 59 | released a new version of the Affero GPL which permits relicensing under | ||
| 60 | this license. | ||
| 61 | |||
| 62 | The precise terms and conditions for copying, distribution and | ||
| 63 | modification follow. | ||
| 64 | |||
| 65 | @heading TERMS AND CONDITIONS | ||
| 66 | |||
| 67 | @enumerate 0 | ||
| 68 | @item Definitions. | ||
| 69 | |||
| 70 | ``This License'' refers to version 3 of the GNU Affero General Public License. | ||
| 71 | |||
| 72 | ``Copyright'' also means copyright-like laws that apply to other kinds | ||
| 73 | of works, such as semiconductor masks. | ||
| 74 | |||
| 75 | ``The Program'' refers to any copyrightable work licensed under this | ||
| 76 | License. Each licensee is addressed as ``you''. ``Licensees'' and | ||
| 77 | ``recipients'' may be individuals or organizations. | ||
| 78 | |||
| 79 | To ``modify'' a work means to copy from or adapt all or part of the work | ||
| 80 | in a fashion requiring copyright permission, other than the making of | ||
| 81 | an exact copy. The resulting work is called a ``modified version'' of | ||
| 82 | the earlier work or a work ``based on'' the earlier work. | ||
| 83 | |||
| 84 | A ``covered work'' means either the unmodified Program or a work based | ||
| 85 | on the Program. | ||
| 86 | |||
| 87 | To ``propagate'' a work means to do anything with it that, without | ||
| 88 | permission, would make you directly or secondarily liable for | ||
| 89 | infringement under applicable copyright law, except executing it on a | ||
| 90 | computer or modifying a private copy. Propagation includes copying, | ||
| 91 | distribution (with or without modification), making available to the | ||
| 92 | public, and in some countries other activities as well. | ||
| 93 | |||
| 94 | To ``convey'' a work means any kind of propagation that enables other | ||
| 95 | parties to make or receive copies. Mere interaction with a user | ||
| 96 | through a computer network, with no transfer of a copy, is not | ||
| 97 | conveying. | ||
| 98 | |||
| 99 | An interactive user interface displays ``Appropriate Legal Notices'' to | ||
| 100 | the extent that it includes a convenient and prominently visible | ||
| 101 | feature that (1) displays an appropriate copyright notice, and (2) | ||
| 102 | tells the user that there is no warranty for the work (except to the | ||
| 103 | extent that warranties are provided), that licensees may convey the | ||
| 104 | work under this License, and how to view a copy of this License. If | ||
| 105 | the interface presents a list of user commands or options, such as a | ||
| 106 | menu, a prominent item in the list meets this criterion. | ||
| 107 | |||
| 108 | @item Source Code. | ||
| 109 | |||
| 110 | The ``source code'' for a work means the preferred form of the work for | ||
| 111 | making modifications to it. ``Object code'' means any non-source form | ||
| 112 | of a work. | ||
| 113 | |||
| 114 | A ``Standard Interface'' means an interface that either is an official | ||
| 115 | standard defined by a recognized standards body, or, in the case of | ||
| 116 | interfaces specified for a particular programming language, one that | ||
| 117 | is widely used among developers working in that language. | ||
| 118 | |||
| 119 | The ``System Libraries'' of an executable work include anything, other | ||
| 120 | than the work as a whole, that (a) is included in the normal form of | ||
| 121 | packaging a Major Component, but which is not part of that Major | ||
| 122 | Component, and (b) serves only to enable use of the work with that | ||
| 123 | Major Component, or to implement a Standard Interface for which an | ||
| 124 | implementation is available to the public in source code form. A | ||
| 125 | ``Major Component'', in this context, means a major essential component | ||
| 126 | (kernel, window system, and so on) of the specific operating system | ||
| 127 | (if any) on which the executable work runs, or a compiler used to | ||
| 128 | produce the work, or an object code interpreter used to run it. | ||
| 129 | |||
| 130 | The ``Corresponding Source'' for a work in object code form means all | ||
| 131 | the source code needed to generate, install, and (for an executable | ||
| 132 | work) run the object code and to modify the work, including scripts to | ||
| 133 | control those activities. However, it does not include the work's | ||
| 134 | System Libraries, or general-purpose tools or generally available free | ||
| 135 | programs which are used unmodified in performing those activities but | ||
| 136 | which are not part of the work. For example, Corresponding Source | ||
| 137 | includes interface definition files associated with source files for | ||
| 138 | the work, and the source code for shared libraries and dynamically | ||
| 139 | linked subprograms that the work is specifically designed to require, | ||
| 140 | such as by intimate data communication or control flow between those | ||
| 141 | subprograms and other parts of the work. | ||
| 142 | |||
| 143 | The Corresponding Source need not include anything that users can | ||
| 144 | regenerate automatically from other parts of the Corresponding Source. | ||
| 145 | |||
| 146 | The Corresponding Source for a work in source code form is that same | ||
| 147 | work. | ||
| 148 | |||
| 149 | @item Basic Permissions. | ||
| 150 | |||
| 151 | All rights granted under this License are granted for the term of | ||
| 152 | copyright on the Program, and are irrevocable provided the stated | ||
| 153 | conditions are met. This License explicitly affirms your unlimited | ||
| 154 | permission to run the unmodified Program. The output from running a | ||
| 155 | covered work is covered by this License only if the output, given its | ||
| 156 | content, constitutes a covered work. This License acknowledges your | ||
| 157 | rights of fair use or other equivalent, as provided by copyright law. | ||
| 158 | |||
| 159 | You may make, run and propagate covered works that you do not convey, | ||
| 160 | without conditions so long as your license otherwise remains in force. | ||
| 161 | You may convey covered works to others for the sole purpose of having | ||
| 162 | them make modifications exclusively for you, or provide you with | ||
| 163 | facilities for running those works, provided that you comply with the | ||
| 164 | terms of this License in conveying all material for which you do not | ||
| 165 | control copyright. Those thus making or running the covered works for | ||
| 166 | you must do so exclusively on your behalf, under your direction and | ||
| 167 | control, on terms that prohibit them from making any copies of your | ||
| 168 | copyrighted material outside their relationship with you. | ||
| 169 | |||
| 170 | Conveying under any other circumstances is permitted solely under the | ||
| 171 | conditions stated below. Sublicensing is not allowed; section 10 | ||
| 172 | makes it unnecessary. | ||
| 173 | |||
| 174 | @item Protecting Users' Legal Rights From Anti-Circumvention Law. | ||
| 175 | |||
| 176 | No covered work shall be deemed part of an effective technological | ||
| 177 | measure under any applicable law fulfilling obligations under article | ||
| 178 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or | ||
| 179 | similar laws prohibiting or restricting circumvention of such | ||
| 180 | measures. | ||
| 181 | |||
| 182 | When you convey a covered work, you waive any legal power to forbid | ||
| 183 | circumvention of technological measures to the extent such | ||
| 184 | circumvention is effected by exercising rights under this License with | ||
| 185 | respect to the covered work, and you disclaim any intention to limit | ||
| 186 | operation or modification of the work as a means of enforcing, against | ||
| 187 | the work's users, your or third parties' legal rights to forbid | ||
| 188 | circumvention of technological measures. | ||
| 189 | |||
| 190 | @item Conveying Verbatim Copies. | ||
| 191 | |||
| 192 | You may convey verbatim copies of the Program's source code as you | ||
| 193 | receive it, in any medium, provided that you conspicuously and | ||
| 194 | appropriately publish on each copy an appropriate copyright notice; | ||
| 195 | keep intact all notices stating that this License and any | ||
| 196 | non-permissive terms added in accord with section 7 apply to the code; | ||
| 197 | keep intact all notices of the absence of any warranty; and give all | ||
| 198 | recipients a copy of this License along with the Program. | ||
| 199 | |||
| 200 | You may charge any price or no price for each copy that you convey, | ||
| 201 | and you may offer support or warranty protection for a fee. | ||
| 202 | |||
| 203 | @item Conveying Modified Source Versions. | ||
| 204 | |||
| 205 | You may convey a work based on the Program, or the modifications to | ||
| 206 | produce it from the Program, in the form of source code under the | ||
| 207 | terms of section 4, provided that you also meet all of these | ||
| 208 | conditions: | ||
| 209 | |||
| 210 | @enumerate a | ||
| 211 | @item | ||
| 212 | The work must carry prominent notices stating that you modified it, | ||
| 213 | and giving a relevant date. | ||
| 214 | |||
| 215 | @item | ||
| 216 | The work must carry prominent notices stating that it is released | ||
| 217 | under this License and any conditions added under section 7. This | ||
| 218 | requirement modifies the requirement in section 4 to ``keep intact all | ||
| 219 | notices''. | ||
| 220 | |||
| 221 | @item | ||
| 222 | You must license the entire work, as a whole, under this License to | ||
| 223 | anyone who comes into possession of a copy. This License will | ||
| 224 | therefore apply, along with any applicable section 7 additional terms, | ||
| 225 | to the whole of the work, and all its parts, regardless of how they | ||
| 226 | are packaged. This License gives no permission to license the work in | ||
| 227 | any other way, but it does not invalidate such permission if you have | ||
| 228 | separately received it. | ||
| 229 | |||
| 230 | @item | ||
| 231 | If the work has interactive user interfaces, each must display | ||
| 232 | Appropriate Legal Notices; however, if the Program has interactive | ||
| 233 | interfaces that do not display Appropriate Legal Notices, your work | ||
| 234 | need not make them do so. | ||
| 235 | @end enumerate | ||
| 236 | |||
| 237 | A compilation of a covered work with other separate and independent | ||
| 238 | works, which are not by their nature extensions of the covered work, | ||
| 239 | and which are not combined with it such as to form a larger program, | ||
| 240 | in or on a volume of a storage or distribution medium, is called an | ||
| 241 | ``aggregate'' if the compilation and its resulting copyright are not | ||
| 242 | used to limit the access or legal rights of the compilation's users | ||
| 243 | beyond what the individual works permit. Inclusion of a covered work | ||
| 244 | in an aggregate does not cause this License to apply to the other | ||
| 245 | parts of the aggregate. | ||
| 246 | |||
| 247 | @item Conveying Non-Source Forms. | ||
| 248 | |||
| 249 | You may convey a covered work in object code form under the terms of | ||
| 250 | sections 4 and 5, provided that you also convey the machine-readable | ||
| 251 | Corresponding Source under the terms of this License, in one of these | ||
| 252 | ways: | ||
| 253 | |||
| 254 | @enumerate a | ||
| 255 | @item | ||
| 256 | Convey the object code in, or embodied in, a physical product | ||
| 257 | (including a physical distribution medium), accompanied by the | ||
| 258 | Corresponding Source fixed on a durable physical medium customarily | ||
| 259 | used for software interchange. | ||
| 260 | |||
| 261 | @item | ||
| 262 | Convey the object code in, or embodied in, a physical product | ||
| 263 | (including a physical distribution medium), accompanied by a written | ||
| 264 | offer, valid for at least three years and valid for as long as you | ||
| 265 | offer spare parts or customer support for that product model, to give | ||
| 266 | anyone who possesses the object code either (1) a copy of the | ||
| 267 | Corresponding Source for all the software in the product that is | ||
| 268 | covered by this License, on a durable physical medium customarily used | ||
| 269 | for software interchange, for a price no more than your reasonable | ||
| 270 | cost of physically performing this conveying of source, or (2) access | ||
| 271 | to copy the Corresponding Source from a network server at no charge. | ||
| 272 | |||
| 273 | @item | ||
| 274 | Convey individual copies of the object code with a copy of the written | ||
| 275 | offer to provide the Corresponding Source. This alternative is | ||
| 276 | allowed only occasionally and noncommercially, and only if you | ||
| 277 | received the object code with such an offer, in accord with subsection | ||
| 278 | 6b. | ||
| 279 | |||
| 280 | @item | ||
| 281 | Convey the object code by offering access from a designated place | ||
| 282 | (gratis or for a charge), and offer equivalent access to the | ||
| 283 | Corresponding Source in the same way through the same place at no | ||
| 284 | further charge. You need not require recipients to copy the | ||
| 285 | Corresponding Source along with the object code. If the place to copy | ||
| 286 | the object code is a network server, the Corresponding Source may be | ||
| 287 | on a different server (operated by you or a third party) that supports | ||
| 288 | equivalent copying facilities, provided you maintain clear directions | ||
| 289 | next to the object code saying where to find the Corresponding Source. | ||
| 290 | Regardless of what server hosts the Corresponding Source, you remain | ||
| 291 | obligated to ensure that it is available for as long as needed to | ||
| 292 | satisfy these requirements. | ||
| 293 | |||
| 294 | @item | ||
| 295 | Convey the object code using peer-to-peer transmission, provided you | ||
| 296 | inform other peers where the object code and Corresponding Source of | ||
| 297 | the work are being offered to the general public at no charge under | ||
| 298 | subsection 6d. | ||
| 299 | |||
| 300 | @end enumerate | ||
| 301 | |||
| 302 | A separable portion of the object code, whose source code is excluded | ||
| 303 | from the Corresponding Source as a System Library, need not be | ||
| 304 | included in conveying the object code work. | ||
| 305 | |||
| 306 | A ``User Product'' is either (1) a ``consumer product'', which means any | ||
| 307 | tangible personal property which is normally used for personal, | ||
| 308 | family, or household purposes, or (2) anything designed or sold for | ||
| 309 | incorporation into a dwelling. In determining whether a product is a | ||
| 310 | consumer product, doubtful cases shall be resolved in favor of | ||
| 311 | coverage. For a particular product received by a particular user, | ||
| 312 | ``normally used'' refers to a typical or common use of that class of | ||
| 313 | product, regardless of the status of the particular user or of the way | ||
| 314 | in which the particular user actually uses, or expects or is expected | ||
| 315 | to use, the product. A product is a consumer product regardless of | ||
| 316 | whether the product has substantial commercial, industrial or | ||
| 317 | non-consumer uses, unless such uses represent the only significant | ||
| 318 | mode of use of the product. | ||
| 319 | |||
| 320 | ``Installation Information'' for a User Product means any methods, | ||
| 321 | procedures, authorization keys, or other information required to | ||
| 322 | install and execute modified versions of a covered work in that User | ||
| 323 | Product from a modified version of its Corresponding Source. The | ||
| 324 | information must suffice to ensure that the continued functioning of | ||
| 325 | the modified object code is in no case prevented or interfered with | ||
| 326 | solely because modification has been made. | ||
| 327 | |||
| 328 | If you convey an object code work under this section in, or with, or | ||
| 329 | specifically for use in, a User Product, and the conveying occurs as | ||
| 330 | part of a transaction in which the right of possession and use of the | ||
| 331 | User Product is transferred to the recipient in perpetuity or for a | ||
| 332 | fixed term (regardless of how the transaction is characterized), the | ||
| 333 | Corresponding Source conveyed under this section must be accompanied | ||
| 334 | by the Installation Information. But this requirement does not apply | ||
| 335 | if neither you nor any third party retains the ability to install | ||
| 336 | modified object code on the User Product (for example, the work has | ||
| 337 | been installed in ROM). | ||
| 338 | |||
| 339 | The requirement to provide Installation Information does not include a | ||
| 340 | requirement to continue to provide support service, warranty, or | ||
| 341 | updates for a work that has been modified or installed by the | ||
| 342 | recipient, or for the User Product in which it has been modified or | ||
| 343 | installed. Access to a network may be denied when the modification | ||
| 344 | itself materially and adversely affects the operation of the network | ||
| 345 | or violates the rules and protocols for communication across the | ||
| 346 | network. | ||
| 347 | |||
| 348 | Corresponding Source conveyed, and Installation Information provided, | ||
| 349 | in accord with this section must be in a format that is publicly | ||
| 350 | documented (and with an implementation available to the public in | ||
| 351 | source code form), and must require no special password or key for | ||
| 352 | unpacking, reading or copying. | ||
| 353 | |||
| 354 | @item Additional Terms. | ||
| 355 | |||
| 356 | ``Additional permissions'' are terms that supplement the terms of this | ||
| 357 | License by making exceptions from one or more of its conditions. | ||
| 358 | Additional permissions that are applicable to the entire Program shall | ||
| 359 | be treated as though they were included in this License, to the extent | ||
| 360 | that they are valid under applicable law. If additional permissions | ||
| 361 | apply only to part of the Program, that part may be used separately | ||
| 362 | under those permissions, but the entire Program remains governed by | ||
| 363 | this License without regard to the additional permissions. | ||
| 364 | |||
| 365 | When you convey a copy of a covered work, you may at your option | ||
| 366 | remove any additional permissions from that copy, or from any part of | ||
| 367 | it. (Additional permissions may be written to require their own | ||
| 368 | removal in certain cases when you modify the work.) You may place | ||
| 369 | additional permissions on material, added by you to a covered work, | ||
| 370 | for which you have or can give appropriate copyright permission. | ||
| 371 | |||
| 372 | Notwithstanding any other provision of this License, for material you | ||
| 373 | add to a covered work, you may (if authorized by the copyright holders | ||
| 374 | of that material) supplement the terms of this License with terms: | ||
| 375 | |||
| 376 | @enumerate a | ||
| 377 | @item | ||
| 378 | Disclaiming warranty or limiting liability differently from the terms | ||
| 379 | of sections 15 and 16 of this License; or | ||
| 380 | |||
| 381 | @item | ||
| 382 | Requiring preservation of specified reasonable legal notices or author | ||
| 383 | attributions in that material or in the Appropriate Legal Notices | ||
| 384 | displayed by works containing it; or | ||
| 385 | |||
| 386 | @item | ||
| 387 | Prohibiting misrepresentation of the origin of that material, or | ||
| 388 | requiring that modified versions of such material be marked in | ||
| 389 | reasonable ways as different from the original version; or | ||
| 390 | |||
| 391 | @item | ||
| 392 | Limiting the use for publicity purposes of names of licensors or | ||
| 393 | authors of the material; or | ||
| 394 | |||
| 395 | @item | ||
| 396 | Declining to grant rights under trademark law for use of some trade | ||
| 397 | names, trademarks, or service marks; or | ||
| 398 | |||
| 399 | @item | ||
| 400 | Requiring indemnification of licensors and authors of that material by | ||
| 401 | anyone who conveys the material (or modified versions of it) with | ||
| 402 | contractual assumptions of liability to the recipient, for any | ||
| 403 | liability that these contractual assumptions directly impose on those | ||
| 404 | licensors and authors. | ||
| 405 | @end enumerate | ||
| 406 | |||
| 407 | All other non-permissive additional terms are considered ``further | ||
| 408 | restrictions'' within the meaning of section 10. If the Program as you | ||
| 409 | received it, or any part of it, contains a notice stating that it is | ||
| 410 | governed by this License along with a term that is a further | ||
| 411 | restriction, you may remove that term. If a license document contains | ||
| 412 | a further restriction but permits relicensing or conveying under this | ||
| 413 | License, you may add to a covered work material governed by the terms | ||
| 414 | of that license document, provided that the further restriction does | ||
| 415 | not survive such relicensing or conveying. | ||
| 416 | |||
| 417 | If you add terms to a covered work in accord with this section, you | ||
| 418 | must place, in the relevant source files, a statement of the | ||
| 419 | additional terms that apply to those files, or a notice indicating | ||
| 420 | where to find the applicable terms. | ||
| 421 | |||
| 422 | Additional terms, permissive or non-permissive, may be stated in the | ||
| 423 | form of a separately written license, or stated as exceptions; the | ||
| 424 | above requirements apply either way. | ||
| 425 | |||
| 426 | @item Termination. | ||
| 427 | |||
| 428 | You may not propagate or modify a covered work except as expressly | ||
| 429 | provided under this License. Any attempt otherwise to propagate or | ||
| 430 | modify it is void, and will automatically terminate your rights under | ||
| 431 | this License (including any patent licenses granted under the third | ||
| 432 | paragraph of section 11). | ||
| 433 | |||
| 434 | However, if you cease all violation of this License, then your license | ||
| 435 | from a particular copyright holder is reinstated (a) provisionally, | ||
| 436 | unless and until the copyright holder explicitly and finally | ||
| 437 | terminates your license, and (b) permanently, if the copyright holder | ||
| 438 | fails to notify you of the violation by some reasonable means prior to | ||
| 439 | 60 days after the cessation. | ||
| 440 | |||
| 441 | Moreover, your license from a particular copyright holder is | ||
| 442 | reinstated permanently if the copyright holder notifies you of the | ||
| 443 | violation by some reasonable means, this is the first time you have | ||
| 444 | received notice of violation of this License (for any work) from that | ||
| 445 | copyright holder, and you cure the violation prior to 30 days after | ||
| 446 | your receipt of the notice. | ||
| 447 | |||
| 448 | Termination of your rights under this section does not terminate the | ||
| 449 | licenses of parties who have received copies or rights from you under | ||
| 450 | this License. If your rights have been terminated and not permanently | ||
| 451 | reinstated, you do not qualify to receive new licenses for the same | ||
| 452 | material under section 10. | ||
| 453 | |||
| 454 | @item Acceptance Not Required for Having Copies. | ||
| 455 | |||
| 456 | You are not required to accept this License in order to receive or run | ||
| 457 | a copy of the Program. Ancillary propagation of a covered work | ||
| 458 | occurring solely as a consequence of using peer-to-peer transmission | ||
| 459 | to receive a copy likewise does not require acceptance. However, | ||
| 460 | nothing other than this License grants you permission to propagate or | ||
| 461 | modify any covered work. These actions infringe copyright if you do | ||
| 462 | not accept this License. Therefore, by modifying or propagating a | ||
| 463 | covered work, you indicate your acceptance of this License to do so. | ||
| 464 | |||
| 465 | @item Automatic Licensing of Downstream Recipients. | ||
| 466 | |||
| 467 | Each time you convey a covered work, the recipient automatically | ||
| 468 | receives a license from the original licensors, to run, modify and | ||
| 469 | propagate that work, subject to this License. You are not responsible | ||
| 470 | for enforcing compliance by third parties with this License. | ||
| 471 | |||
| 472 | An ``entity transaction'' is a transaction transferring control of an | ||
| 473 | organization, or substantially all assets of one, or subdividing an | ||
| 474 | organization, or merging organizations. If propagation of a covered | ||
| 475 | work results from an entity transaction, each party to that | ||
| 476 | transaction who receives a copy of the work also receives whatever | ||
| 477 | licenses to the work the party's predecessor in interest had or could | ||
| 478 | give under the previous paragraph, plus a right to possession of the | ||
| 479 | Corresponding Source of the work from the predecessor in interest, if | ||
| 480 | the predecessor has it or can get it with reasonable efforts. | ||
| 481 | |||
| 482 | You may not impose any further restrictions on the exercise of the | ||
| 483 | rights granted or affirmed under this License. For example, you may | ||
| 484 | not impose a license fee, royalty, or other charge for exercise of | ||
| 485 | rights granted under this License, and you may not initiate litigation | ||
| 486 | (including a cross-claim or counterclaim in a lawsuit) alleging that | ||
| 487 | any patent claim is infringed by making, using, selling, offering for | ||
| 488 | sale, or importing the Program or any portion of it. | ||
| 489 | |||
| 490 | @item Patents. | ||
| 491 | |||
| 492 | A ``contributor'' is a copyright holder who authorizes use under this | ||
| 493 | License of the Program or a work on which the Program is based. The | ||
| 494 | work thus licensed is called the contributor's ``contributor version''. | ||
| 495 | |||
| 496 | A contributor's ``essential patent claims'' are all patent claims owned | ||
| 497 | or controlled by the contributor, whether already acquired or | ||
| 498 | hereafter acquired, that would be infringed by some manner, permitted | ||
| 499 | by this License, of making, using, or selling its contributor version, | ||
| 500 | but do not include claims that would be infringed only as a | ||
| 501 | consequence of further modification of the contributor version. For | ||
| 502 | purposes of this definition, ``control'' includes the right to grant | ||
| 503 | patent sublicenses in a manner consistent with the requirements of | ||
| 504 | this License. | ||
| 505 | |||
| 506 | Each contributor grants you a non-exclusive, worldwide, royalty-free | ||
| 507 | patent license under the contributor's essential patent claims, to | ||
| 508 | make, use, sell, offer for sale, import and otherwise run, modify and | ||
| 509 | propagate the contents of its contributor version. | ||
| 510 | |||
| 511 | In the following three paragraphs, a ``patent license'' is any express | ||
| 512 | agreement or commitment, however denominated, not to enforce a patent | ||
| 513 | (such as an express permission to practice a patent or covenant not to | ||
| 514 | sue for patent infringement). To ``grant'' such a patent license to a | ||
| 515 | party means to make such an agreement or commitment not to enforce a | ||
| 516 | patent against the party. | ||
| 517 | |||
| 518 | If you convey a covered work, knowingly relying on a patent license, | ||
| 519 | and the Corresponding Source of the work is not available for anyone | ||
| 520 | to copy, free of charge and under the terms of this License, through a | ||
| 521 | publicly available network server or other readily accessible means, | ||
| 522 | then you must either (1) cause the Corresponding Source to be so | ||
| 523 | available, or (2) arrange to deprive yourself of the benefit of the | ||
| 524 | patent license for this particular work, or (3) arrange, in a manner | ||
| 525 | consistent with the requirements of this License, to extend the patent | ||
| 526 | license to downstream recipients. ``Knowingly relying'' means you have | ||
| 527 | actual knowledge that, but for the patent license, your conveying the | ||
| 528 | covered work in a country, or your recipient's use of the covered work | ||
| 529 | in a country, would infringe one or more identifiable patents in that | ||
| 530 | country that you have reason to believe are valid. | ||
| 531 | |||
| 532 | If, pursuant to or in connection with a single transaction or | ||
| 533 | arrangement, you convey, or propagate by procuring conveyance of, a | ||
| 534 | covered work, and grant a patent license to some of the parties | ||
| 535 | receiving the covered work authorizing them to use, propagate, modify | ||
| 536 | or convey a specific copy of the covered work, then the patent license | ||
| 537 | you grant is automatically extended to all recipients of the covered | ||
| 538 | work and works based on it. | ||
| 539 | |||
| 540 | A patent license is ``discriminatory'' if it does not include within the | ||
| 541 | scope of its coverage, prohibits the exercise of, or is conditioned on | ||
| 542 | the non-exercise of one or more of the rights that are specifically | ||
| 543 | granted under this License. You may not convey a covered work if you | ||
| 544 | are a party to an arrangement with a third party that is in the | ||
| 545 | business of distributing software, under which you make payment to the | ||
| 546 | third party based on the extent of your activity of conveying the | ||
| 547 | work, and under which the third party grants, to any of the parties | ||
| 548 | who would receive the covered work from you, a discriminatory patent | ||
| 549 | license (a) in connection with copies of the covered work conveyed by | ||
| 550 | you (or copies made from those copies), or (b) primarily for and in | ||
| 551 | connection with specific products or compilations that contain the | ||
| 552 | covered work, unless you entered into that arrangement, or that patent | ||
| 553 | license was granted, prior to 28 March 2007. | ||
| 554 | |||
| 555 | Nothing in this License shall be construed as excluding or limiting | ||
| 556 | any implied license or other defenses to infringement that may | ||
| 557 | otherwise be available to you under applicable patent law. | ||
| 558 | |||
| 559 | @item No Surrender of Others' Freedom. | ||
| 560 | |||
| 561 | If conditions are imposed on you (whether by court order, agreement or | ||
| 562 | otherwise) that contradict the conditions of this License, they do not | ||
| 563 | excuse you from the conditions of this License. If you cannot convey | ||
| 564 | a covered work so as to satisfy simultaneously your obligations under | ||
| 565 | this License and any other pertinent obligations, then as a | ||
| 566 | consequence you may not convey it at all. For example, if you agree | ||
| 567 | to terms that obligate you to collect a royalty for further conveying | ||
| 568 | from those to whom you convey the Program, the only way you could | ||
| 569 | satisfy both those terms and this License would be to refrain entirely | ||
| 570 | from conveying the Program. | ||
| 571 | |||
| 572 | @item Remote Network Interaction; Use with the GNU General Public License. | ||
| 573 | |||
| 574 | Notwithstanding any other provision of this License, if you modify the | ||
| 575 | Program, your modified version must prominently offer all users interacting | ||
| 576 | with it remotely through a computer network (if your version supports such | ||
| 577 | interaction) an opportunity to receive the Corresponding Source of your | ||
| 578 | version by providing access to the Corresponding Source from a network | ||
| 579 | server at no charge, through some standard or customary means of | ||
| 580 | facilitating copying of software. This Corresponding Source shall include | ||
| 581 | the Corresponding Source for any work covered by version 3 of the GNU | ||
| 582 | General Public License that is incorporated pursuant to the following | ||
| 583 | paragraph. | ||
| 584 | |||
| 585 | Notwithstanding any other provision of this License, you have permission to | ||
| 586 | link or combine any covered work with a work licensed under version 3 of | ||
| 587 | the GNU General Public License into a single combined work, and to convey | ||
| 588 | the resulting work. The terms of this License will continue to apply to | ||
| 589 | the part which is the covered work, but the work with which it is combined | ||
| 590 | will remain governed by version 3 of the GNU General Public License. | ||
| 591 | |||
| 592 | @item Revised Versions of this License. | ||
| 593 | |||
| 594 | The Free Software Foundation may publish revised and/or new versions | ||
| 595 | of the GNU Affero General Public License from time to time. Such new | ||
| 596 | versions will be similar in spirit to the present version, but may | ||
| 597 | differ in detail to address new problems or concerns. | ||
| 598 | |||
| 599 | Each version is given a distinguishing version number. If the Program | ||
| 600 | specifies that a certain numbered version of the GNU Affero General Public | ||
| 601 | License ``or any later version'' applies to it, you have the option of | ||
| 602 | following the terms and conditions either of that numbered version or | ||
| 603 | of any later version published by the Free Software Foundation. If | ||
| 604 | the Program does not specify a version number of the GNU Affero General | ||
| 605 | Public License, you may choose any version ever published by the Free | ||
| 606 | Software Foundation. | ||
| 607 | |||
| 608 | If the Program specifies that a proxy can decide which future versions | ||
| 609 | of the GNU Affero General Public License can be used, that proxy's public | ||
| 610 | statement of acceptance of a version permanently authorizes you to | ||
| 611 | choose that version for the Program. | ||
| 612 | |||
| 613 | Later license versions may give you additional or different | ||
| 614 | permissions. However, no additional obligations are imposed on any | ||
| 615 | author or copyright holder as a result of your choosing to follow a | ||
| 616 | later version. | ||
| 617 | |||
| 618 | @item Disclaimer of Warranty. | ||
| 619 | |||
| 620 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY | ||
| 621 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT | ||
| 622 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT | ||
| 623 | WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT | ||
| 624 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
| 625 | A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND | ||
| 626 | PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE | ||
| 627 | DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR | ||
| 628 | CORRECTION. | ||
| 629 | |||
| 630 | @item Limitation of Liability. | ||
| 631 | |||
| 632 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING | ||
| 633 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR | ||
| 634 | CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, | ||
| 635 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES | ||
| 636 | ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT | ||
| 637 | NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR | ||
| 638 | LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM | ||
| 639 | TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER | ||
| 640 | PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. | ||
| 641 | |||
| 642 | @item Interpretation of Sections 15 and 16. | ||
| 643 | |||
| 644 | If the disclaimer of warranty and limitation of liability provided | ||
| 645 | above cannot be given local legal effect according to their terms, | ||
| 646 | reviewing courts shall apply local law that most closely approximates | ||
| 647 | an absolute waiver of all civil liability in connection with the | ||
| 648 | Program, unless a warranty or assumption of liability accompanies a | ||
| 649 | copy of the Program in return for a fee. | ||
| 650 | |||
| 651 | @end enumerate | ||
| 652 | |||
| 653 | @heading END OF TERMS AND CONDITIONS | ||
| 654 | |||
| 655 | @heading How to Apply These Terms to Your New Programs | ||
| 656 | |||
| 657 | If you develop a new program, and you want it to be of the greatest | ||
| 658 | possible use to the public, the best way to achieve this is to make it | ||
| 659 | free software which everyone can redistribute and change under these | ||
| 660 | terms. | ||
| 661 | |||
| 662 | To do so, attach the following notices to the program. It is safest | ||
| 663 | to attach them to the start of each source file to most effectively | ||
| 664 | state the exclusion of warranty; and each file should have at least | ||
| 665 | the ``copyright'' line and a pointer to where the full notice is found. | ||
| 666 | |||
| 667 | @smallexample | ||
| 668 | @var{one line to give the program's name and a brief idea of what it does.} | ||
| 669 | Copyright (C) @var{year} @var{name of author} | ||
| 670 | |||
| 671 | This program is free software: you can redistribute it and/or modify | ||
| 672 | it under the terms of the GNU Affero General Public License as published by | ||
| 673 | the Free Software Foundation, either version 3 of the License, or (at | ||
| 674 | your option) any later version. | ||
| 675 | |||
| 676 | This program is distributed in the hope that it will be useful, but | ||
| 677 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 678 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| 679 | Affero General Public License for more details. | ||
| 680 | |||
| 681 | You should have received a copy of the GNU Affero General Public License | ||
| 682 | along with this program. If not, see @url{https://www.gnu.org/licenses/}. | ||
| 683 | @end smallexample | ||
| 684 | |||
| 685 | Also add information on how to contact you by electronic and paper mail. | ||
| 686 | |||
| 687 | If your software can interact with users remotely through a computer | ||
| 688 | network, you should also make sure that it provides a way for users to | ||
| 689 | get its source. For example, if your program is a web application, its | ||
| 690 | interface could display a ``Source'' link that leads users to an archive | ||
| 691 | of the code. There are many ways you could offer source, and different | ||
| 692 | solutions will be better for different programs; see section 13 for the | ||
| 693 | specific requirements. | ||
| 694 | |||
| 695 | You should also get your employer (if you work as a programmer) or school, | ||
| 696 | if any, to sign a ``copyright disclaimer'' for the program, if necessary. | ||
| 697 | For more information on this, and how to apply and follow the GNU AGPL, see | ||
| 698 | @url{https://www.gnu.org/licenses/}. | ||
diff --git a/doc/documentation/chapters/configuration.texi b/doc/documentation/chapters/configuration.texi deleted file mode 100644 index 286c72e7a..000000000 --- a/doc/documentation/chapters/configuration.texi +++ /dev/null | |||
| @@ -1,5 +0,0 @@ | |||
| 1 | @node Configuration Handbook | ||
| 2 | @chapter Configuration Handbook | ||
| 3 | |||
| 4 | This chapter has yet to be written. It is intended to be about in-depth | ||
| 5 | configuration of GNUnet. | ||
diff --git a/doc/documentation/chapters/contributing.texi b/doc/documentation/chapters/contributing.texi deleted file mode 100644 index f4493e6c1..000000000 --- a/doc/documentation/chapters/contributing.texi +++ /dev/null | |||
| @@ -1,117 +0,0 @@ | |||
| 1 | @node GNUnet Contributors Handbook | ||
| 2 | @chapter GNUnet Contributors Handbook | ||
| 3 | |||
| 4 | @menu | ||
| 5 | * Contributing to GNUnet:: | ||
| 6 | * Licenses of contributions:: | ||
| 7 | * Copyright Assignment:: | ||
| 8 | * Contributing to the Reference Manual:: | ||
| 9 | * Contributing testcases:: | ||
| 10 | @end menu | ||
| 11 | |||
| 12 | @node Contributing to GNUnet | ||
| 13 | @section Contributing to GNUnet | ||
| 14 | |||
| 15 | @cindex licenses | ||
| 16 | @cindex licenses of contributions | ||
| 17 | @node Licenses of contributions | ||
| 18 | @section Licenses of contributions | ||
| 19 | |||
| 20 | GNUnet is a @uref{https://www.gnu.org/, GNU} package. | ||
| 21 | All code contributions must thus be put under the | ||
| 22 | @uref{https://www.gnu.org/licenses/agpl.html, GNU Affero Public License (AGPL)}. | ||
| 23 | All documentation should be put under FSF approved licenses | ||
| 24 | (see @uref{https://www.gnu.org/copyleft/fdl.html, fdl}). | ||
| 25 | |||
| 26 | By submitting documentation, translations, and other content to GNUnet | ||
| 27 | you automatically grant the right to publish code under the | ||
| 28 | GNU Public License and documentation under either or both the | ||
| 29 | GNU Public License or the GNU Free Documentation License. | ||
| 30 | When contributing to the GNUnet project, GNU standards and the | ||
| 31 | @uref{https://www.gnu.org/philosophy/philosophy.html, GNU philosophy} | ||
| 32 | should be adhered to. | ||
| 33 | |||
| 34 | @cindex copyright assignment | ||
| 35 | @node Copyright Assignment | ||
| 36 | @section Copyright Assignment | ||
| 37 | We require a formal copyright assignment for GNUnet contributors | ||
| 38 | to GNUnet e.V.; nevertheless, we do allow pseudonymous contributions. | ||
| 39 | By signing the copyright agreement and submitting your code (or | ||
| 40 | documentation) to us, you agree to share the rights to your code | ||
| 41 | with GNUnet e.V.; GNUnet e.V. receives non-exclusive ownership | ||
| 42 | rights, and in particular is allowed to dual-license the code. You | ||
| 43 | retain non-exclusive rights to your contributions, so you can also | ||
| 44 | share your contributions freely with other projects. | ||
| 45 | |||
| 46 | GNUnet e.V. will publish all accepted contributions under the AGPLv3 | ||
| 47 | or any later version. The association may decide to publish | ||
| 48 | contributions under additional licenses (dual-licensing). | ||
| 49 | |||
| 50 | We do not intentionally remove your name from your contributions; | ||
| 51 | however, due to extensive editing it is not always trivial to | ||
| 52 | attribute contributors properly. If you find that you significantly | ||
| 53 | contributed to a file (or the project as a whole) and are not listed | ||
| 54 | in the respective authors file or section, please do let us know. | ||
| 55 | |||
| 56 | @node Contributing to the Reference Manual | ||
| 57 | @section Contributing to the Reference Manual | ||
| 58 | |||
| 59 | @itemize @bullet | ||
| 60 | |||
| 61 | @item When writing documentation, please use | ||
| 62 | @uref{https://en.wikipedia.org/wiki/Singular_they, gender-neutral wording} | ||
| 63 | when referring to people, such as singular “they”, “their”, “them”, and so | ||
| 64 | forth. | ||
| 65 | |||
| 66 | @item Keep line length below 74 characters, except for URLs. | ||
| 67 | URLs break in the PDF output when they contain linebreaks. | ||
| 68 | |||
| 69 | @item Do not use tab characters (see chapter 2.1 texinfo manual) | ||
| 70 | |||
| 71 | @item Write texts in the third person perspective. | ||
| 72 | |||
| 73 | @c FIXME: This is questionable, it feels like bike shed painging to do | ||
| 74 | @c this for several k lines. It only helps to jump between sentences in | ||
| 75 | @c editors afaik. | ||
| 76 | @c @item Use 2 spaces between sentences, so instead of: | ||
| 77 | |||
| 78 | @c @example | ||
| 79 | @c We do this and the other thing. This is done by foo. | ||
| 80 | @c @end example | ||
| 81 | |||
| 82 | @c Write: | ||
| 83 | |||
| 84 | @c @example | ||
| 85 | @c We do this and the other thing. This is done by foo. | ||
| 86 | @c @end example | ||
| 87 | |||
| 88 | @end itemize | ||
| 89 | |||
| 90 | @node Contributing testcases | ||
| 91 | @section Contributing testcases | ||
| 92 | |||
| 93 | In the core of gnunet, we restrict new testcases to a small subset | ||
| 94 | of languages, in order of preference: | ||
| 95 | @enumerate | ||
| 96 | @item C | ||
| 97 | @item Portable Shell Scripts | ||
| 98 | @item Python (@geq{}3.6) | ||
| 99 | @end enumerate | ||
| 100 | |||
| 101 | We welcome efforts to remove our existing python-2.7 scripts to | ||
| 102 | replace them either with portable shell scripts or, | ||
| 103 | at your choice, python-3.6+. | ||
| 104 | |||
| 105 | If you contribute new python based testcases, we advise you to | ||
| 106 | not repeat our past misfortunes and write the tests in a standard | ||
| 107 | test framework like for example pytest. | ||
| 108 | |||
| 109 | For writing portable shell scripts, these tools are useful: | ||
| 110 | @uref{https://github.com/koalaman/shellcheck, Shellcheck}, | ||
| 111 | @uref{https://salsa.debian.org/debian/devscripts/blob/master/scripts/checkbashisms.pl, checkbashisms}, | ||
| 112 | @uref{http://www.etalabs.net/sh_tricks.html}, | ||
| 113 | @uref{https://wiki.ubuntu.com/DashAsBinSh}, | ||
| 114 | and @uref{https://mywiki.wooledge.org/Bashism} | ||
| 115 | |||
| 116 | @c You could also run "bin/check_shell_script" (which we still have | ||
| 117 | @c to write). | ||
diff --git a/doc/documentation/chapters/developer.texi b/doc/documentation/chapters/developer.texi deleted file mode 100644 index d9c92247b..000000000 --- a/doc/documentation/chapters/developer.texi +++ /dev/null | |||
| @@ -1,8817 +0,0 @@ | |||
| 1 | @c *********************************************************************** | ||
| 2 | @node GNUnet Developer Handbook | ||
| 3 | @chapter GNUnet Developer Handbook | ||
| 4 | |||
| 5 | This book is intended to be an introduction for programmers that want to | ||
| 6 | extend the GNUnet framework. GNUnet is more than a simple peer-to-peer | ||
| 7 | application. | ||
| 8 | |||
| 9 | For developers, GNUnet is: | ||
| 10 | |||
| 11 | @itemize @bullet | ||
| 12 | @item developed by a community that believes in the GNU philosophy | ||
| 13 | @item Free Software (Free as in Freedom), licensed under the | ||
| 14 | GNU Affero General Public License | ||
| 15 | (@uref{https://www.gnu.org/licenses/licenses.html#AGPL}) | ||
| 16 | @item A set of standards, including coding conventions and | ||
| 17 | architectural rules | ||
| 18 | @item A set of layered protocols, both specifying the communication | ||
| 19 | between peers as well as the communication between components | ||
| 20 | of a single peer | ||
| 21 | @item A set of libraries with well-defined APIs suitable for | ||
| 22 | writing extensions | ||
| 23 | @end itemize | ||
| 24 | |||
| 25 | In particular, the architecture specifies that a peer consists of many | ||
| 26 | processes communicating via protocols. Processes can be written in almost | ||
| 27 | any language. | ||
| 28 | @code{C}, @code{Java} and @code{Guile} APIs exist for accessing existing | ||
| 29 | services and for writing extensions. | ||
| 30 | It is possible to write extensions in other languages by | ||
| 31 | implementing the necessary IPC protocols. | ||
| 32 | |||
| 33 | GNUnet can be extended and improved along many possible dimensions, and | ||
| 34 | anyone interested in Free Software and Freedom-enhancing Networking is | ||
| 35 | welcome to join the effort. This Developer Handbook attempts to provide | ||
| 36 | an initial introduction to some of the key design choices and central | ||
| 37 | components of the system. | ||
| 38 | This part of the GNUNet documentation is far from complete, | ||
| 39 | and we welcome informed contributions, be it in the form of | ||
| 40 | new chapters, sections or insightful comments. | ||
| 41 | |||
| 42 | @menu | ||
| 43 | * Developer Introduction:: | ||
| 44 | * Internal dependencies:: | ||
| 45 | * Code overview:: | ||
| 46 | * System Architecture:: | ||
| 47 | * Subsystem stability:: | ||
| 48 | * Naming conventions and coding style guide:: | ||
| 49 | * Build-system:: | ||
| 50 | * Developing extensions for GNUnet using the gnunet-ext template:: | ||
| 51 | * Writing testcases:: | ||
| 52 | * Building GNUnet and its dependencies:: | ||
| 53 | * TESTING library:: | ||
| 54 | * Performance regression analysis with Gauger:: | ||
| 55 | * TESTBED Subsystem:: | ||
| 56 | * libgnunetutil:: | ||
| 57 | * Automatic Restart Manager (ARM):: | ||
| 58 | * TRANSPORT Subsystem:: | ||
| 59 | * NAT library:: | ||
| 60 | * Distance-Vector plugin:: | ||
| 61 | * SMTP plugin:: | ||
| 62 | * Bluetooth plugin:: | ||
| 63 | * WLAN plugin:: | ||
| 64 | * ATS Subsystem:: | ||
| 65 | * CORE Subsystem:: | ||
| 66 | * CADET Subsystem:: | ||
| 67 | * NSE Subsystem:: | ||
| 68 | * HOSTLIST Subsystem:: | ||
| 69 | * IDENTITY Subsystem:: | ||
| 70 | * NAMESTORE Subsystem:: | ||
| 71 | * PEERINFO Subsystem:: | ||
| 72 | * PEERSTORE Subsystem:: | ||
| 73 | * SET Subsystem:: | ||
| 74 | * STATISTICS Subsystem:: | ||
| 75 | * Distributed Hash Table (DHT):: | ||
| 76 | * GNU Name System (GNS):: | ||
| 77 | * GNS Namecache:: | ||
| 78 | * REVOCATION Subsystem:: | ||
| 79 | * File-sharing (FS) Subsystem:: | ||
| 80 | * REGEX Subsystem:: | ||
| 81 | * REST Subsystem:: | ||
| 82 | @end menu | ||
| 83 | |||
| 84 | @node Developer Introduction | ||
| 85 | @section Developer Introduction | ||
| 86 | |||
| 87 | This Developer Handbook is intended as first introduction to GNUnet for | ||
| 88 | new developers that want to extend the GNUnet framework. After the | ||
| 89 | introduction, each of the GNUnet subsystems (directories in the | ||
| 90 | @file{src/} tree) is (supposed to be) covered in its own chapter. In | ||
| 91 | addition to this documentation, GNUnet developers should be aware of the | ||
| 92 | services available on the GNUnet server to them. | ||
| 93 | |||
| 94 | New developers can have a look a the GNUnet tutorials for C and java | ||
| 95 | available in the @file{src/} directory of the repository or under the | ||
| 96 | following links: | ||
| 97 | |||
| 98 | @c ** FIXME: Link to files in source, not online. | ||
| 99 | @c ** FIXME: Where is the Java tutorial? | ||
| 100 | @itemize @bullet | ||
| 101 | @item @xref{Top, Introduction,, gnunet-c-tutorial, The GNUnet C Tutorial}. | ||
| 102 | @c broken link | ||
| 103 | @c @item @uref{https://gnunet.org/git/gnunet.git/plain/doc/gnunet-c-tutorial.pdf, GNUnet C tutorial} | ||
| 104 | @item GNUnet Java tutorial | ||
| 105 | @end itemize | ||
| 106 | |||
| 107 | In addition to the GNUnet Reference Documentation you are reading, | ||
| 108 | the GNUnet server at @uref{https://gnunet.org} contains | ||
| 109 | various resources for GNUnet developers and those | ||
| 110 | who aspire to become regular contributors. | ||
| 111 | They are all conveniently reachable via the "Developer" | ||
| 112 | entry in the navigation menu. Some additional tools (such as static | ||
| 113 | analysis reports) require a special developer access to perform certain | ||
| 114 | operations. If you want (or require) access, you should contact | ||
| 115 | @uref{http://grothoff.org/christian/, Christian Grothoff}, | ||
| 116 | GNUnet's maintainer. | ||
| 117 | |||
| 118 | @c FIXME: A good part of this belongs on the website or should be | ||
| 119 | @c extended in subsections explaining usage of this. A simple list | ||
| 120 | @c is just taking space people have to read. | ||
| 121 | The public subsystems on the GNUnet server that help developers are: | ||
| 122 | |||
| 123 | @itemize @bullet | ||
| 124 | |||
| 125 | @item The version control system (git) keeps our code and enables | ||
| 126 | distributed development. | ||
| 127 | It is publicly accessible at @uref{https://gnunet.org/git/}. | ||
| 128 | Only developers with write access can commit code, everyone else is | ||
| 129 | encouraged to submit patches to the GNUnet-developers mailinglist: | ||
| 130 | @uref{https://lists.gnu.org/mailman/listinfo/gnunet-developers, https://lists.gnu.org/mailman/listinfo/gnunet-developers} | ||
| 131 | |||
| 132 | @item The bugtracking system (Mantis). | ||
| 133 | We use it to track feature requests, open bug reports and their | ||
| 134 | resolutions. | ||
| 135 | It can be accessed at | ||
| 136 | @uref{https://gnunet.org/bugs/, https://gnunet.org/bugs/}. | ||
| 137 | Anyone can report bugs. | ||
| 138 | |||
| 139 | @item Our site installation of the | ||
| 140 | Continuous Integration (CI) system @code{Buildbot} is used | ||
| 141 | to check GNUnet builds automatically on a range of platforms. | ||
| 142 | The web interface of this CI is exposed at | ||
| 143 | @uref{https://gnunet.org/buildbot/, https://gnunet.org/buildbot/}. | ||
| 144 | Builds are triggered automatically 30 minutes after the last commit to | ||
| 145 | our repository was made. | ||
| 146 | |||
| 147 | @item The current quality of our automated test suite is assessed using | ||
| 148 | Code coverage analysis. This analysis is run daily; however the webpage | ||
| 149 | is only updated if all automated tests pass at that time. Testcases that | ||
| 150 | improve our code coverage are always welcome. | ||
| 151 | |||
| 152 | @item We try to automatically find bugs using a static analysis scan. | ||
| 153 | This scan is run daily; however the webpage is only updated if all | ||
| 154 | automated tests pass at the time. Note that not everything that is | ||
| 155 | flagged by the analysis is a bug, sometimes even good code can be marked | ||
| 156 | as possibly problematic. Nevertheless, developers are encouraged to at | ||
| 157 | least be aware of all issues in their code that are listed. | ||
| 158 | |||
| 159 | @item We use Gauger for automatic performance regression visualization. | ||
| 160 | @c FIXME: LINK! | ||
| 161 | Details on how to use Gauger are here. | ||
| 162 | |||
| 163 | @item We use @uref{http://junit.org/, junit} to automatically test | ||
| 164 | @command{gnunet-java}. | ||
| 165 | Automatically generated, current reports on the test suite are here. | ||
| 166 | @c FIXME: Likewise. | ||
| 167 | |||
| 168 | @item We use Cobertura to generate test coverage reports for gnunet-java. | ||
| 169 | Current reports on test coverage are here. | ||
| 170 | @c FIXME: Likewise. | ||
| 171 | |||
| 172 | @end itemize | ||
| 173 | |||
| 174 | |||
| 175 | |||
| 176 | @c *********************************************************************** | ||
| 177 | @menu | ||
| 178 | * Project overview:: | ||
| 179 | @end menu | ||
| 180 | |||
| 181 | @node Project overview | ||
| 182 | @subsection Project overview | ||
| 183 | |||
| 184 | The GNUnet project consists at this point of several sub-projects. This | ||
| 185 | section is supposed to give an initial overview about the various | ||
| 186 | sub-projects. Note that this description also lists projects that are far | ||
| 187 | from complete, including even those that have literally not a single line | ||
| 188 | of code in them yet. | ||
| 189 | |||
| 190 | GNUnet sub-projects in order of likely relevance are currently: | ||
| 191 | |||
| 192 | @table @asis | ||
| 193 | |||
| 194 | @item @command{gnunet} | ||
| 195 | Core of the P2P framework, including file-sharing, VPN and | ||
| 196 | chat applications; this is what the Developer Handbook covers mostly | ||
| 197 | @item @command{gnunet-gtk} | ||
| 198 | Gtk+-based user interfaces, including: | ||
| 199 | |||
| 200 | @itemize @bullet | ||
| 201 | @item @command{gnunet-fs-gtk} (file-sharing), | ||
| 202 | @item @command{gnunet-statistics-gtk} (statistics over time), | ||
| 203 | @item @command{gnunet-peerinfo-gtk} | ||
| 204 | (information about current connections and known peers), | ||
| 205 | @item @command{gnunet-chat-gtk} (chat GUI) and | ||
| 206 | @item @command{gnunet-setup} (setup tool for "everything") | ||
| 207 | @end itemize | ||
| 208 | |||
| 209 | @item @command{gnunet-fuse} | ||
| 210 | Mounting directories shared via GNUnet's file-sharing | ||
| 211 | on GNU/Linux distributions | ||
| 212 | @item @command{gnunet-update} | ||
| 213 | Installation and update tool | ||
| 214 | @item @command{gnunet-ext} | ||
| 215 | Template for starting 'external' GNUnet projects | ||
| 216 | @item @command{gnunet-java} | ||
| 217 | Java APIs for writing GNUnet services and applications | ||
| 218 | @item @command{gnunet-java-ext} | ||
| 219 | @item @command{eclectic} | ||
| 220 | Code to run GNUnet nodes on testbeds for research, development, | ||
| 221 | testing and evaluation | ||
| 222 | @c ** FIXME: Solve the status and location of gnunet-qt | ||
| 223 | @item @command{gnunet-qt} | ||
| 224 | Qt-based GNUnet GUI (is it deprecated?) | ||
| 225 | @item @command{gnunet-cocoa} | ||
| 226 | cocoa-based GNUnet GUI (is it deprecated?) | ||
| 227 | @item @command{gnunet-guile} | ||
| 228 | Guile bindings for GNUnet | ||
| 229 | @item @command{gnunet-python} | ||
| 230 | Python bindings for GNUnet | ||
| 231 | |||
| 232 | @end table | ||
| 233 | |||
| 234 | We are also working on various supporting libraries and tools: | ||
| 235 | @c ** FIXME: What about gauger, and what about libmwmodem? | ||
| 236 | |||
| 237 | @table @asis | ||
| 238 | @item @command{libextractor} | ||
| 239 | GNU libextractor (meta data extraction) | ||
| 240 | @item @command{libmicrohttpd} | ||
| 241 | GNU libmicrohttpd (embedded HTTP(S) server library) | ||
| 242 | @item @command{gauger} | ||
| 243 | Tool for performance regression analysis | ||
| 244 | @item @command{monkey} | ||
| 245 | Tool for automated debugging of distributed systems | ||
| 246 | @item @command{libmwmodem} | ||
| 247 | Library for accessing satellite connection quality reports | ||
| 248 | @item @command{libgnurl} | ||
| 249 | gnURL (feature-restricted variant of cURL/libcurl) | ||
| 250 | @item @command{www} | ||
| 251 | work in progress of the new gnunet.org website (Jinja2 framework based to | ||
| 252 | replace our current Drupal website) | ||
| 253 | @item @command{bibliography} | ||
| 254 | Our collected bibliography, papers, references, and so forth | ||
| 255 | @item @command{gnunet-videos-} | ||
| 256 | Videos about and around gnunet activities | ||
| 257 | @end table | ||
| 258 | |||
| 259 | Finally, there are various external projects (see links for a list of | ||
| 260 | those that have a public website) which build on top of the GNUnet | ||
| 261 | framework. | ||
| 262 | |||
| 263 | @c *********************************************************************** | ||
| 264 | @node Internal dependencies | ||
| 265 | @section Internal dependencies | ||
| 266 | |||
| 267 | This section tries to give an overview of what processes a typical GNUnet | ||
| 268 | peer running a particular application would consist of. All of the | ||
| 269 | processes listed here should be automatically started by | ||
| 270 | @command{gnunet-arm -s}. | ||
| 271 | The list is given as a rough first guide to users for failure diagnostics. | ||
| 272 | Ideally, end-users should never have to worry about these internal | ||
| 273 | dependencies. | ||
| 274 | |||
| 275 | In terms of internal dependencies, a minimum file-sharing system consists | ||
| 276 | of the following GNUnet processes (in order of dependency): | ||
| 277 | |||
| 278 | @itemize @bullet | ||
| 279 | @item gnunet-service-arm | ||
| 280 | @item gnunet-service-resolver (required by all) | ||
| 281 | @item gnunet-service-statistics (required by all) | ||
| 282 | @item gnunet-service-peerinfo | ||
| 283 | @item gnunet-service-transport (requires peerinfo) | ||
| 284 | @item gnunet-service-core (requires transport) | ||
| 285 | @item gnunet-daemon-hostlist (requires core) | ||
| 286 | @item gnunet-daemon-topology (requires hostlist, peerinfo) | ||
| 287 | @item gnunet-service-datastore | ||
| 288 | @item gnunet-service-dht (requires core) | ||
| 289 | @item gnunet-service-identity | ||
| 290 | @item gnunet-service-fs (requires identity, mesh, dht, datastore, core) | ||
| 291 | @end itemize | ||
| 292 | |||
| 293 | @noindent | ||
| 294 | A minimum VPN system consists of the following GNUnet processes (in | ||
| 295 | order of dependency): | ||
| 296 | |||
| 297 | @itemize @bullet | ||
| 298 | @item gnunet-service-arm | ||
| 299 | @item gnunet-service-resolver (required by all) | ||
| 300 | @item gnunet-service-statistics (required by all) | ||
| 301 | @item gnunet-service-peerinfo | ||
| 302 | @item gnunet-service-transport (requires peerinfo) | ||
| 303 | @item gnunet-service-core (requires transport) | ||
| 304 | @item gnunet-daemon-hostlist (requires core) | ||
| 305 | @item gnunet-service-dht (requires core) | ||
| 306 | @item gnunet-service-mesh (requires dht, core) | ||
| 307 | @item gnunet-service-dns (requires dht) | ||
| 308 | @item gnunet-service-regex (requires dht) | ||
| 309 | @item gnunet-service-vpn (requires regex, dns, mesh, dht) | ||
| 310 | @end itemize | ||
| 311 | |||
| 312 | @noindent | ||
| 313 | A minimum GNS system consists of the following GNUnet processes (in | ||
| 314 | order of dependency): | ||
| 315 | |||
| 316 | @itemize @bullet | ||
| 317 | @item gnunet-service-arm | ||
| 318 | @item gnunet-service-resolver (required by all) | ||
| 319 | @item gnunet-service-statistics (required by all) | ||
| 320 | @item gnunet-service-peerinfo | ||
| 321 | @item gnunet-service-transport (requires peerinfo) | ||
| 322 | @item gnunet-service-core (requires transport) | ||
| 323 | @item gnunet-daemon-hostlist (requires core) | ||
| 324 | @item gnunet-service-dht (requires core) | ||
| 325 | @item gnunet-service-mesh (requires dht, core) | ||
| 326 | @item gnunet-service-dns (requires dht) | ||
| 327 | @item gnunet-service-regex (requires dht) | ||
| 328 | @item gnunet-service-vpn (requires regex, dns, mesh, dht) | ||
| 329 | @item gnunet-service-identity | ||
| 330 | @item gnunet-service-namestore (requires identity) | ||
| 331 | @item gnunet-service-gns (requires vpn, dns, dht, namestore, identity) | ||
| 332 | @end itemize | ||
| 333 | |||
| 334 | @c *********************************************************************** | ||
| 335 | @node Code overview | ||
| 336 | @section Code overview | ||
| 337 | |||
| 338 | This section gives a brief overview of the GNUnet source code. | ||
| 339 | Specifically, we sketch the function of each of the subdirectories in | ||
| 340 | the @file{gnunet/src/} directory. The order given is roughly bottom-up | ||
| 341 | (in terms of the layers of the system). | ||
| 342 | |||
| 343 | @table @asis | ||
| 344 | @item @file{util/} --- libgnunetutil | ||
| 345 | Library with general utility functions, all | ||
| 346 | GNUnet binaries link against this library. Anything from memory | ||
| 347 | allocation and data structures to cryptography and inter-process | ||
| 348 | communication. The goal is to provide an OS-independent interface and | ||
| 349 | more 'secure' or convenient implementations of commonly used primitives. | ||
| 350 | The API is spread over more than a dozen headers, developers should study | ||
| 351 | those closely to avoid duplicating existing functions. | ||
| 352 | @pxref{libgnunetutil}. | ||
| 353 | @item @file{hello/} --- libgnunethello | ||
| 354 | HELLO messages are used to | ||
| 355 | describe under which addresses a peer can be reached (for example, | ||
| 356 | protocol, IP, port). This library manages parsing and generating of HELLO | ||
| 357 | messages. | ||
| 358 | @item @file{block/} --- libgnunetblock | ||
| 359 | The DHT and other components of GNUnet | ||
| 360 | store information in units called 'blocks'. Each block has a type and the | ||
| 361 | type defines a particular format and how that binary format is to be | ||
| 362 | linked to a hash code (the key for the DHT and for databases). The block | ||
| 363 | library is a wrapper around block plugins which provide the necessary | ||
| 364 | functions for each block type. | ||
| 365 | @item @file{statistics/} --- statistics service | ||
| 366 | The statistics service enables associating | ||
| 367 | values (of type uint64_t) with a component name and a string. The main | ||
| 368 | uses is debugging (counting events), performance tracking and user | ||
| 369 | entertainment (what did my peer do today?). | ||
| 370 | @item @file{arm/} --- Automatic Restart Manager (ARM) | ||
| 371 | The automatic-restart-manager (ARM) service | ||
| 372 | is the GNUnet master service. Its role is to start gnunet-services, to | ||
| 373 | re-start them when they crashed and finally to shut down the system when | ||
| 374 | requested. | ||
| 375 | @item @file{peerinfo/} --- peerinfo service | ||
| 376 | The peerinfo service keeps track of which peers are known | ||
| 377 | to the local peer and also tracks the validated addresses for each peer | ||
| 378 | (in the form of a HELLO message) for each of those peers. The peer is not | ||
| 379 | necessarily connected to all peers known to the peerinfo service. | ||
| 380 | Peerinfo provides persistent storage for peer identities --- peers are | ||
| 381 | not forgotten just because of a system restart. | ||
| 382 | @item @file{datacache/} --- libgnunetdatacache | ||
| 383 | The datacache library provides (temporary) block storage for the DHT. | ||
| 384 | Existing plugins can store blocks in Sqlite, Postgres or MySQL databases. | ||
| 385 | All data stored in the cache is lost when the peer is stopped or | ||
| 386 | restarted (datacache uses temporary tables). | ||
| 387 | @item @file{datastore/} --- datastore service | ||
| 388 | The datastore service stores file-sharing blocks in | ||
| 389 | databases for extended periods of time. In contrast to the datacache, data | ||
| 390 | is not lost when peers restart. However, quota restrictions may still | ||
| 391 | cause old, expired or low-priority data to be eventually discarded. | ||
| 392 | Existing plugins can store blocks in Sqlite, Postgres or MySQL databases. | ||
| 393 | @item @file{template/} --- service template | ||
| 394 | Template for writing a new service. Does nothing. | ||
| 395 | @item @file{ats/} --- Automatic Transport Selection | ||
| 396 | The automatic transport selection (ATS) service | ||
| 397 | is responsible for deciding which address (i.e. | ||
| 398 | which transport plugin) should be used for communication with other peers, | ||
| 399 | and at what bandwidth. | ||
| 400 | @item @file{nat/} --- libgnunetnat | ||
| 401 | Library that provides basic functions for NAT traversal. | ||
| 402 | The library supports NAT traversal with | ||
| 403 | manual hole-punching by the user, UPnP and ICMP-based autonomous NAT | ||
| 404 | traversal. The library also includes an API for testing if the current | ||
| 405 | configuration works and the @code{gnunet-nat-server} which provides an | ||
| 406 | external service to test the local configuration. | ||
| 407 | @item @file{fragmentation/} --- libgnunetfragmentation | ||
| 408 | Some transports (UDP and WLAN, mostly) have restrictions on the maximum | ||
| 409 | transfer unit (MTU) for packets. The fragmentation library can be used to | ||
| 410 | break larger packets into chunks of at most 1k and transmit the resulting | ||
| 411 | fragments reliably (with acknowledgment, retransmission, timeouts, | ||
| 412 | etc.). | ||
| 413 | @item @file{transport/} --- transport service | ||
| 414 | The transport service is responsible for managing the | ||
| 415 | basic P2P communication. It uses plugins to support P2P communication | ||
| 416 | over TCP, UDP, HTTP, HTTPS and other protocols.The transport service | ||
| 417 | validates peer addresses, enforces bandwidth restrictions, limits the | ||
| 418 | total number of connections and enforces connectivity restrictions (i.e. | ||
| 419 | friends-only). | ||
| 420 | @item @file{peerinfo-tool/} --- gnunet-peerinfo | ||
| 421 | This directory contains the gnunet-peerinfo binary which can be used to | ||
| 422 | inspect the peers and HELLOs known to the peerinfo service. | ||
| 423 | @item @file{core/} | ||
| 424 | The core service is responsible for establishing encrypted, authenticated | ||
| 425 | connections with other peers, encrypting and decrypting messages and | ||
| 426 | forwarding messages to higher-level services that are interested in them. | ||
| 427 | @item @file{testing/} --- libgnunettesting | ||
| 428 | The testing library allows starting (and stopping) peers | ||
| 429 | for writing testcases. | ||
| 430 | It also supports automatic generation of configurations for peers | ||
| 431 | ensuring that the ports and paths are disjoint. libgnunettesting is also | ||
| 432 | the foundation for the testbed service | ||
| 433 | @item @file{testbed/} --- testbed service | ||
| 434 | The testbed service is used for creating small or large scale deployments | ||
| 435 | of GNUnet peers for evaluation of protocols. | ||
| 436 | It facilitates peer deployments on multiple | ||
| 437 | hosts (for example, in a cluster) and establishing various network | ||
| 438 | topologies (both underlay and overlay). | ||
| 439 | @item @file{nse/} --- Network Size Estimation | ||
| 440 | The network size estimation (NSE) service | ||
| 441 | implements a protocol for (securely) estimating the current size of the | ||
| 442 | P2P network. | ||
| 443 | @item @file{dht/} --- distributed hash table | ||
| 444 | The distributed hash table (DHT) service provides a | ||
| 445 | distributed implementation of a hash table to store blocks under hash | ||
| 446 | keys in the P2P network. | ||
| 447 | @item @file{hostlist/} --- hostlist service | ||
| 448 | The hostlist service allows learning about | ||
| 449 | other peers in the network by downloading HELLO messages from an HTTP | ||
| 450 | server, can be configured to run such an HTTP server and also implements | ||
| 451 | a P2P protocol to advertise and automatically learn about other peers | ||
| 452 | that offer a public hostlist server. | ||
| 453 | @item @file{topology/} --- topology service | ||
| 454 | The topology service is responsible for | ||
| 455 | maintaining the mesh topology. It tries to maintain connections to friends | ||
| 456 | (depending on the configuration) and also tries to ensure that the peer | ||
| 457 | has a decent number of active connections at all times. If necessary, new | ||
| 458 | connections are added. All peers should run the topology service, | ||
| 459 | otherwise they may end up not being connected to any other peer (unless | ||
| 460 | some other service ensures that core establishes the required | ||
| 461 | connections). The topology service also tells the transport service which | ||
| 462 | connections are permitted (for friend-to-friend networking) | ||
| 463 | @item @file{fs/} --- file-sharing | ||
| 464 | The file-sharing (FS) service implements GNUnet's | ||
| 465 | file-sharing application. Both anonymous file-sharing (using gap) and | ||
| 466 | non-anonymous file-sharing (using dht) are supported. | ||
| 467 | @item @file{cadet/} --- cadet service | ||
| 468 | The CADET service provides a general-purpose routing abstraction to create | ||
| 469 | end-to-end encrypted tunnels in mesh networks. We wrote a paper | ||
| 470 | documenting key aspects of the design. | ||
| 471 | @item @file{tun/} --- libgnunettun | ||
| 472 | Library for building IPv4, IPv6 packets and creating | ||
| 473 | checksums for UDP, TCP and ICMP packets. The header | ||
| 474 | defines C structs for common Internet packet formats and in particular | ||
| 475 | structs for interacting with TUN (virtual network) interfaces. | ||
| 476 | @item @file{mysql/} --- libgnunetmysql | ||
| 477 | Library for creating and executing prepared MySQL | ||
| 478 | statements and to manage the connection to the MySQL database. | ||
| 479 | Essentially a lightweight wrapper for the interaction between GNUnet | ||
| 480 | components and libmysqlclient. | ||
| 481 | @item @file{dns/} | ||
| 482 | Service that allows intercepting and modifying DNS requests of | ||
| 483 | the local machine. Currently used for IPv4-IPv6 protocol translation | ||
| 484 | (DNS-ALG) as implemented by "pt/" and for the GNUnet naming system. The | ||
| 485 | service can also be configured to offer an exit service for DNS traffic. | ||
| 486 | @item @file{vpn/} --- VPN service | ||
| 487 | The virtual public network (VPN) service provides a virtual | ||
| 488 | tunnel interface (VTUN) for IP routing over GNUnet. | ||
| 489 | Needs some other peers to run an "exit" service to work. | ||
| 490 | Can be activated using the "gnunet-vpn" tool or integrated with DNS using | ||
| 491 | the "pt" daemon. | ||
| 492 | @item @file{exit/} | ||
| 493 | Daemon to allow traffic from the VPN to exit this | ||
| 494 | peer to the Internet or to specific IP-based services of the local peer. | ||
| 495 | Currently, an exit service can only be restricted to IPv4 or IPv6, not to | ||
| 496 | specific ports and or IP address ranges. If this is not acceptable, | ||
| 497 | additional firewall rules must be added manually. exit currently only | ||
| 498 | works for normal UDP, TCP and ICMP traffic; DNS queries need to leave the | ||
| 499 | system via a DNS service. | ||
| 500 | @item @file{pt/} | ||
| 501 | protocol translation daemon. This daemon enables 4-to-6, | ||
| 502 | 6-to-4, 4-over-6 or 6-over-4 transitions for the local system. It | ||
| 503 | essentially uses "DNS" to intercept DNS replies and then maps results to | ||
| 504 | those offered by the VPN, which then sends them using mesh to some daemon | ||
| 505 | offering an appropriate exit service. | ||
| 506 | @item @file{identity/} | ||
| 507 | Management of egos (alter egos) of a user; identities are | ||
| 508 | essentially named ECC private keys and used for zones in the GNU name | ||
| 509 | system and for namespaces in file-sharing, but might find other uses later | ||
| 510 | @item @file{revocation/} | ||
| 511 | Key revocation service, can be used to revoke the | ||
| 512 | private key of an identity if it has been compromised | ||
| 513 | @item @file{namecache/} | ||
| 514 | Cache for resolution results for the GNU name system; | ||
| 515 | data is encrypted and can be shared among users, | ||
| 516 | loss of the data should ideally only result in a | ||
| 517 | performance degradation (persistence not required) | ||
| 518 | @item @file{namestore/} | ||
| 519 | Database for the GNU name system with per-user private information, | ||
| 520 | persistence required | ||
| 521 | @item @file{gns/} | ||
| 522 | GNU name system, a GNU approach to DNS and PKI. | ||
| 523 | @item @file{dv/} | ||
| 524 | A plugin for distance-vector (DV)-based routing. | ||
| 525 | DV consists of a service and a transport plugin to provide peers | ||
| 526 | with the illusion of a direct P2P connection for connections | ||
| 527 | that use multiple (typically up to 3) hops in the actual underlay network. | ||
| 528 | @item @file{regex/} | ||
| 529 | Service for the (distributed) evaluation of regular expressions. | ||
| 530 | @item @file{scalarproduct/} | ||
| 531 | The scalar product service offers an API to perform a secure multiparty | ||
| 532 | computation which calculates a scalar product between two peers | ||
| 533 | without exposing the private input vectors of the peers to each other. | ||
| 534 | @item @file{consensus/} | ||
| 535 | The consensus service will allow a set of peers to agree | ||
| 536 | on a set of values via a distributed set union computation. | ||
| 537 | @item @file{rest/} | ||
| 538 | The rest API allows access to GNUnet services using RESTful interaction. | ||
| 539 | The services provide plugins that can exposed by the rest server. | ||
| 540 | @c FIXME: Where did this disappear to? | ||
| 541 | @c @item @file{experimentation/} | ||
| 542 | @c The experimentation daemon coordinates distributed | ||
| 543 | @c experimentation to evaluate transport and ATS properties. | ||
| 544 | @end table | ||
| 545 | |||
| 546 | @c *********************************************************************** | ||
| 547 | @node System Architecture | ||
| 548 | @section System Architecture | ||
| 549 | |||
| 550 | @c FIXME: For those irritated by the textflow, we are missing images here, | ||
| 551 | @c in the short term we should add them back, in the long term this should | ||
| 552 | @c work without images or have images with alt-text. | ||
| 553 | |||
| 554 | GNUnet developers like LEGOs. The blocks are indestructible, can be | ||
| 555 | stacked together to construct complex buildings and it is generally easy | ||
| 556 | to swap one block for a different one that has the same shape. GNUnet's | ||
| 557 | architecture is based on LEGOs: | ||
| 558 | |||
| 559 | @c @image{images/service_lego_block,5in,,picture of a LEGO block stack - 3 APIs as connectors upon Network Protocol on top of a Service} | ||
| 560 | |||
| 561 | This chapter documents the GNUnet LEGO system, also known as GNUnet's | ||
| 562 | system architecture. | ||
| 563 | |||
| 564 | The most common GNUnet component is a service. Services offer an API (or | ||
| 565 | several, depending on what you count as "an API") which is implemented as | ||
| 566 | a library. The library communicates with the main process of the service | ||
| 567 | using a service-specific network protocol. The main process of the service | ||
| 568 | typically doesn't fully provide everything that is needed --- it has holes | ||
| 569 | to be filled by APIs to other services. | ||
| 570 | |||
| 571 | A special kind of component in GNUnet are user interfaces and daemons. | ||
| 572 | Like services, they have holes to be filled by APIs of other services. | ||
| 573 | Unlike services, daemons do not implement their own network protocol and | ||
| 574 | they have no API: | ||
| 575 | |||
| 576 | The GNUnet system provides a range of services, daemons and user | ||
| 577 | interfaces, which are then combined into a layered GNUnet instance (also | ||
| 578 | known as a peer). | ||
| 579 | |||
| 580 | Note that while it is generally possible to swap one service for another | ||
| 581 | compatible service, there is often only one implementation. However, | ||
| 582 | during development we often have a "new" version of a service in parallel | ||
| 583 | with an "old" version. While the "new" version is not working, developers | ||
| 584 | working on other parts of the service can continue their development by | ||
| 585 | simply using the "old" service. Alternative design ideas can also be | ||
| 586 | easily investigated by swapping out individual components. This is | ||
| 587 | typically achieved by simply changing the name of the "BINARY" in the | ||
| 588 | respective configuration section. | ||
| 589 | |||
| 590 | Key properties of GNUnet services are that they must be separate | ||
| 591 | processes and that they must protect themselves by applying tight error | ||
| 592 | checking against the network protocol they implement (thereby achieving a | ||
| 593 | certain degree of robustness). | ||
| 594 | |||
| 595 | On the other hand, the APIs are implemented to tolerate failures of the | ||
| 596 | service, isolating their host process from errors by the service. If the | ||
| 597 | service process crashes, other services and daemons around it should not | ||
| 598 | also fail, but instead wait for the service process to be restarted by | ||
| 599 | ARM. | ||
| 600 | |||
| 601 | |||
| 602 | @c *********************************************************************** | ||
| 603 | @node Subsystem stability | ||
| 604 | @section Subsystem stability | ||
| 605 | |||
| 606 | This section documents the current stability of the various GNUnet | ||
| 607 | subsystems. Stability here describes the expected degree of compatibility | ||
| 608 | with future versions of GNUnet. For each subsystem we distinguish between | ||
| 609 | compatibility on the P2P network level (communication protocol between | ||
| 610 | peers), the IPC level (communication between the service and the service | ||
| 611 | library) and the API level (stability of the API). P2P compatibility is | ||
| 612 | relevant in terms of which applications are likely going to be able to | ||
| 613 | communicate with future versions of the network. IPC communication is | ||
| 614 | relevant for the implementation of language bindings that re-implement the | ||
| 615 | IPC messages. Finally, API compatibility is relevant to developers that | ||
| 616 | hope to be able to avoid changes to applications build on top of the APIs | ||
| 617 | of the framework. | ||
| 618 | |||
| 619 | The following table summarizes our current view of the stability of the | ||
| 620 | respective protocols or APIs: | ||
| 621 | |||
| 622 | @multitable @columnfractions .20 .20 .20 .20 | ||
| 623 | @headitem Subsystem @tab P2P @tab IPC @tab C API | ||
| 624 | @item util @tab n/a @tab n/a @tab stable | ||
| 625 | @item arm @tab n/a @tab stable @tab stable | ||
| 626 | @item ats @tab n/a @tab unstable @tab testing | ||
| 627 | @item block @tab n/a @tab n/a @tab stable | ||
| 628 | @item cadet @tab testing @tab testing @tab testing | ||
| 629 | @item consensus @tab experimental @tab experimental @tab experimental | ||
| 630 | @item core @tab stable @tab stable @tab stable | ||
| 631 | @item datacache @tab n/a @tab n/a @tab stable | ||
| 632 | @item datastore @tab n/a @tab stable @tab stable | ||
| 633 | @item dht @tab stable @tab stable @tab stable | ||
| 634 | @item dns @tab stable @tab stable @tab stable | ||
| 635 | @item dv @tab testing @tab testing @tab n/a | ||
| 636 | @item exit @tab testing @tab n/a @tab n/a | ||
| 637 | @item fragmentation @tab stable @tab n/a @tab stable | ||
| 638 | @item fs @tab stable @tab stable @tab stable | ||
| 639 | @item gns @tab stable @tab stable @tab stable | ||
| 640 | @item hello @tab n/a @tab n/a @tab testing | ||
| 641 | @item hostlist @tab stable @tab stable @tab n/a | ||
| 642 | @item identity @tab stable @tab stable @tab n/a | ||
| 643 | @item multicast @tab experimental @tab experimental @tab experimental | ||
| 644 | @item mysql @tab stable @tab n/a @tab stable | ||
| 645 | @item namestore @tab n/a @tab stable @tab stable | ||
| 646 | @item nat @tab n/a @tab n/a @tab stable | ||
| 647 | @item nse @tab stable @tab stable @tab stable | ||
| 648 | @item peerinfo @tab n/a @tab stable @tab stable | ||
| 649 | @item psyc @tab experimental @tab experimental @tab experimental | ||
| 650 | @item pt @tab n/a @tab n/a @tab n/a | ||
| 651 | @item regex @tab stable @tab stable @tab stable | ||
| 652 | @item revocation @tab stable @tab stable @tab stable | ||
| 653 | @item social @tab experimental @tab experimental @tab experimental | ||
| 654 | @item statistics @tab n/a @tab stable @tab stable | ||
| 655 | @item testbed @tab n/a @tab testing @tab testing | ||
| 656 | @item testing @tab n/a @tab n/a @tab testing | ||
| 657 | @item topology @tab n/a @tab n/a @tab n/a | ||
| 658 | @item transport @tab stable @tab stable @tab stable | ||
| 659 | @item tun @tab n/a @tab n/a @tab stable | ||
| 660 | @item vpn @tab testing @tab n/a @tab n/a | ||
| 661 | @end multitable | ||
| 662 | |||
| 663 | Here is a rough explanation of the values: | ||
| 664 | |||
| 665 | @table @samp | ||
| 666 | @item stable | ||
| 667 | No incompatible changes are planned at this time; for IPC/APIs, if | ||
| 668 | there are incompatible changes, they will be minor and might only require | ||
| 669 | minimal changes to existing code; for P2P, changes will be avoided if at | ||
| 670 | all possible for the 0.10.x-series | ||
| 671 | |||
| 672 | @item testing | ||
| 673 | No incompatible changes are | ||
| 674 | planned at this time, but the code is still known to be in flux; so while | ||
| 675 | we have no concrete plans, our expectation is that there will still be | ||
| 676 | minor modifications; for P2P, changes will likely be extensions that | ||
| 677 | should not break existing code | ||
| 678 | |||
| 679 | @item unstable | ||
| 680 | Changes are planned and will happen; however, they | ||
| 681 | will not be totally radical and the result should still resemble what is | ||
| 682 | there now; nevertheless, anticipated changes will break protocol/API | ||
| 683 | compatibility | ||
| 684 | |||
| 685 | @item experimental | ||
| 686 | Changes are planned and the result may look nothing like | ||
| 687 | what the API/protocol looks like today | ||
| 688 | |||
| 689 | @item unknown | ||
| 690 | Someone should think about where this subsystem headed | ||
| 691 | |||
| 692 | @item n/a | ||
| 693 | This subsystem does not have an API/IPC-protocol/P2P-protocol | ||
| 694 | @end table | ||
| 695 | |||
| 696 | @c *********************************************************************** | ||
| 697 | @node Naming conventions and coding style guide | ||
| 698 | @section Naming conventions and coding style guide | ||
| 699 | |||
| 700 | Here you can find some rules to help you write code for GNUnet. | ||
| 701 | |||
| 702 | @c *********************************************************************** | ||
| 703 | @menu | ||
| 704 | * Naming conventions:: | ||
| 705 | * Coding style:: | ||
| 706 | @end menu | ||
| 707 | |||
| 708 | @node Naming conventions | ||
| 709 | @subsection Naming conventions | ||
| 710 | |||
| 711 | |||
| 712 | @c *********************************************************************** | ||
| 713 | @menu | ||
| 714 | * include files:: | ||
| 715 | * binaries:: | ||
| 716 | * logging:: | ||
| 717 | * configuration:: | ||
| 718 | * exported symbols:: | ||
| 719 | * private (library-internal) symbols (including structs and macros):: | ||
| 720 | * testcases:: | ||
| 721 | * performance tests:: | ||
| 722 | * src/ directories:: | ||
| 723 | @end menu | ||
| 724 | |||
| 725 | @node include files | ||
| 726 | @subsubsection include files | ||
| 727 | |||
| 728 | @itemize @bullet | ||
| 729 | @item _lib: library without need for a process | ||
| 730 | @item _service: library that needs a service process | ||
| 731 | @item _plugin: plugin definition | ||
| 732 | @item _protocol: structs used in network protocol | ||
| 733 | @item exceptions: | ||
| 734 | @itemize @bullet | ||
| 735 | @item gnunet_config.h --- generated | ||
| 736 | @item platform.h --- first included | ||
| 737 | @item plibc.h --- external library | ||
| 738 | @item gnunet_common.h --- fundamental routines | ||
| 739 | @item gnunet_directories.h --- generated | ||
| 740 | @item gettext.h --- external library | ||
| 741 | @end itemize | ||
| 742 | @end itemize | ||
| 743 | |||
| 744 | @c *********************************************************************** | ||
| 745 | @node binaries | ||
| 746 | @subsubsection binaries | ||
| 747 | |||
| 748 | @itemize @bullet | ||
| 749 | @item gnunet-service-xxx: service process (has listen socket) | ||
| 750 | @item gnunet-daemon-xxx: daemon process (no listen socket) | ||
| 751 | @item gnunet-helper-xxx[-yyy]: SUID helper for module xxx | ||
| 752 | @item gnunet-yyy: command-line tool for end-users | ||
| 753 | @item libgnunet_plugin_xxx_yyy.so: plugin for API xxx | ||
| 754 | @item libgnunetxxx.so: library for API xxx | ||
| 755 | @end itemize | ||
| 756 | |||
| 757 | @c *********************************************************************** | ||
| 758 | @node logging | ||
| 759 | @subsubsection logging | ||
| 760 | |||
| 761 | @itemize @bullet | ||
| 762 | @item services and daemons use their directory name in | ||
| 763 | @code{GNUNET_log_setup} (i.e. 'core') and log using | ||
| 764 | plain 'GNUNET_log'. | ||
| 765 | @item command-line tools use their full name in | ||
| 766 | @code{GNUNET_log_setup} (i.e. 'gnunet-publish') and log using | ||
| 767 | plain 'GNUNET_log'. | ||
| 768 | @item service access libraries log using | ||
| 769 | '@code{GNUNET_log_from}' and use '@code{DIRNAME-api}' for the | ||
| 770 | component (i.e. 'core-api') | ||
| 771 | @item pure libraries (without associated service) use | ||
| 772 | '@code{GNUNET_log_from}' with the component set to their | ||
| 773 | library name (without lib or '@file{.so}'), | ||
| 774 | which should also be their directory name (i.e. '@file{nat}') | ||
| 775 | @item plugins should use '@code{GNUNET_log_from}' | ||
| 776 | with the directory name and the plugin name combined to produce | ||
| 777 | the component name (i.e. 'transport-tcp'). | ||
| 778 | @item logging should be unified per-file by defining a | ||
| 779 | @code{LOG} macro with the appropriate arguments, | ||
| 780 | along these lines: | ||
| 781 | |||
| 782 | @example | ||
| 783 | #define LOG(kind,...) | ||
| 784 | GNUNET_log_from (kind, "example-api",__VA_ARGS__) | ||
| 785 | @end example | ||
| 786 | |||
| 787 | @end itemize | ||
| 788 | |||
| 789 | @c *********************************************************************** | ||
| 790 | @node configuration | ||
| 791 | @subsubsection configuration | ||
| 792 | |||
| 793 | @itemize @bullet | ||
| 794 | @item paths (that are substituted in all filenames) are in PATHS | ||
| 795 | (have as few as possible) | ||
| 796 | @item all options for a particular module (@file{src/MODULE}) | ||
| 797 | are under @code{[MODULE]} | ||
| 798 | @item options for a plugin of a module | ||
| 799 | are under @code{[MODULE-PLUGINNAME]} | ||
| 800 | @end itemize | ||
| 801 | |||
| 802 | @c *********************************************************************** | ||
| 803 | @node exported symbols | ||
| 804 | @subsubsection exported symbols | ||
| 805 | |||
| 806 | @itemize @bullet | ||
| 807 | @item must start with @code{GNUNET_modulename_} and be defined in | ||
| 808 | @file{modulename.c} | ||
| 809 | @item exceptions: those defined in @file{gnunet_common.h} | ||
| 810 | @end itemize | ||
| 811 | |||
| 812 | @c *********************************************************************** | ||
| 813 | @node private (library-internal) symbols (including structs and macros) | ||
| 814 | @subsubsection private (library-internal) symbols (including structs and macros) | ||
| 815 | |||
| 816 | @itemize @bullet | ||
| 817 | @item must NOT start with any prefix | ||
| 818 | @item must not be exported in a way that linkers could use them or@ other | ||
| 819 | libraries might see them via headers; they must be either | ||
| 820 | declared/defined in C source files or in headers that are in the | ||
| 821 | respective directory under @file{src/modulename/} and NEVER be declared | ||
| 822 | in @file{src/include/}. | ||
| 823 | @end itemize | ||
| 824 | |||
| 825 | @node testcases | ||
| 826 | @subsubsection testcases | ||
| 827 | |||
| 828 | @itemize @bullet | ||
| 829 | @item must be called @file{test_module-under-test_case-description.c} | ||
| 830 | @item "case-description" maybe omitted if there is only one test | ||
| 831 | @end itemize | ||
| 832 | |||
| 833 | @c *********************************************************************** | ||
| 834 | @node performance tests | ||
| 835 | @subsubsection performance tests | ||
| 836 | |||
| 837 | @itemize @bullet | ||
| 838 | @item must be called @file{perf_module-under-test_case-description.c} | ||
| 839 | @item "case-description" maybe omitted if there is only one performance | ||
| 840 | test | ||
| 841 | @item Must only be run if @code{HAVE_BENCHMARKS} is satisfied | ||
| 842 | @end itemize | ||
| 843 | |||
| 844 | @c *********************************************************************** | ||
| 845 | @node src/ directories | ||
| 846 | @subsubsection src/ directories | ||
| 847 | |||
| 848 | @itemize @bullet | ||
| 849 | @item gnunet-NAME: end-user applications (i.e., gnunet-search, gnunet-arm) | ||
| 850 | @item gnunet-service-NAME: service processes with accessor library (i.e., | ||
| 851 | gnunet-service-arm) | ||
| 852 | @item libgnunetNAME: accessor library (_service.h-header) or standalone | ||
| 853 | library (_lib.h-header) | ||
| 854 | @item gnunet-daemon-NAME: daemon process without accessor library (i.e., | ||
| 855 | gnunet-daemon-hostlist) and no GNUnet management port | ||
| 856 | @item libgnunet_plugin_DIR_NAME: loadable plugins (i.e., | ||
| 857 | libgnunet_plugin_transport_tcp) | ||
| 858 | @end itemize | ||
| 859 | |||
| 860 | @cindex Coding style | ||
| 861 | @node Coding style | ||
| 862 | @subsection Coding style | ||
| 863 | |||
| 864 | @c XXX: Adjust examples to GNU Standards! | ||
| 865 | @itemize @bullet | ||
| 866 | @item We follow the GNU Coding Standards (@pxref{Top, The GNU Coding Standards,, standards, The GNU Coding Standards}); | ||
| 867 | @item Indentation is done with spaces, two per level, no tabs; | ||
| 868 | @item C99 struct initialization is fine; | ||
| 869 | @item declare only one variable per line, for example: | ||
| 870 | |||
| 871 | @noindent | ||
| 872 | instead of | ||
| 873 | |||
| 874 | @example | ||
| 875 | int i,j; | ||
| 876 | @end example | ||
| 877 | |||
| 878 | @noindent | ||
| 879 | write: | ||
| 880 | |||
| 881 | @example | ||
| 882 | int i; | ||
| 883 | int j; | ||
| 884 | @end example | ||
| 885 | |||
| 886 | @c TODO: include actual example from a file in source | ||
| 887 | |||
| 888 | @noindent | ||
| 889 | This helps keep diffs small and forces developers to think precisely about | ||
| 890 | the type of every variable. | ||
| 891 | Note that @code{char *} is different from @code{const char*} and | ||
| 892 | @code{int} is different from @code{unsigned int} or @code{uint32_t}. | ||
| 893 | Each variable type should be chosen with care. | ||
| 894 | |||
| 895 | @item While @code{goto} should generally be avoided, having a | ||
| 896 | @code{goto} to the end of a function to a block of clean up | ||
| 897 | statements (free, close, etc.) can be acceptable. | ||
| 898 | |||
| 899 | @item Conditions should be written with constants on the left (to avoid | ||
| 900 | accidental assignment) and with the @code{true} target being either the | ||
| 901 | @code{error} case or the significantly simpler continuation. For example: | ||
| 902 | |||
| 903 | @example | ||
| 904 | if (0 != stat ("filename," &sbuf)) @{ | ||
| 905 | error(); | ||
| 906 | @} | ||
| 907 | else @{ | ||
| 908 | /* handle normal case here */ | ||
| 909 | @} | ||
| 910 | @end example | ||
| 911 | |||
| 912 | @noindent | ||
| 913 | instead of | ||
| 914 | |||
| 915 | @example | ||
| 916 | if (stat ("filename," &sbuf) == 0) @{ | ||
| 917 | /* handle normal case here */ | ||
| 918 | @} else @{ | ||
| 919 | error(); | ||
| 920 | @} | ||
| 921 | @end example | ||
| 922 | |||
| 923 | @noindent | ||
| 924 | If possible, the error clause should be terminated with a @code{return} (or | ||
| 925 | @code{goto} to some cleanup routine) and in this case, the @code{else} clause | ||
| 926 | should be omitted: | ||
| 927 | |||
| 928 | @example | ||
| 929 | if (0 != stat ("filename," &sbuf)) @{ | ||
| 930 | error(); | ||
| 931 | return; | ||
| 932 | @} | ||
| 933 | /* handle normal case here */ | ||
| 934 | @end example | ||
| 935 | |||
| 936 | This serves to avoid deep nesting. The 'constants on the left' rule | ||
| 937 | applies to all constants (including. @code{GNUNET_SCHEDULER_NO_TASK}), | ||
| 938 | NULL, and enums). With the two above rules (constants on left, errors in | ||
| 939 | 'true' branch), there is only one way to write most branches correctly. | ||
| 940 | |||
| 941 | @item Combined assignments and tests are allowed if they do not hinder | ||
| 942 | code clarity. For example, one can write: | ||
| 943 | |||
| 944 | @example | ||
| 945 | if (NULL == (value = lookup_function())) @{ | ||
| 946 | error(); | ||
| 947 | return; | ||
| 948 | @} | ||
| 949 | @end example | ||
| 950 | |||
| 951 | @item Use @code{break} and @code{continue} wherever possible to avoid | ||
| 952 | deep(er) nesting. Thus, we would write: | ||
| 953 | |||
| 954 | @example | ||
| 955 | next = head; | ||
| 956 | while (NULL != (pos = next)) @{ | ||
| 957 | next = pos->next; | ||
| 958 | if (! should_free (pos)) | ||
| 959 | continue; | ||
| 960 | GNUNET_CONTAINER_DLL_remove (head, tail, pos); | ||
| 961 | GNUNET_free (pos); | ||
| 962 | @} | ||
| 963 | @end example | ||
| 964 | |||
| 965 | instead of | ||
| 966 | |||
| 967 | @example | ||
| 968 | next = head; while (NULL != (pos = next)) @{ | ||
| 969 | next = pos->next; | ||
| 970 | if (should_free (pos)) @{ | ||
| 971 | /* unnecessary nesting! */ | ||
| 972 | GNUNET_CONTAINER_DLL_remove (head, tail, pos); | ||
| 973 | GNUNET_free (pos); | ||
| 974 | @} | ||
| 975 | @} | ||
| 976 | @end example | ||
| 977 | |||
| 978 | @item We primarily use @code{for} and @code{while} loops. | ||
| 979 | A @code{while} loop is used if the method for advancing in the loop is | ||
| 980 | not a straightforward increment operation. In particular, we use: | ||
| 981 | |||
| 982 | @example | ||
| 983 | next = head; | ||
| 984 | while (NULL != (pos = next)) | ||
| 985 | @{ | ||
| 986 | next = pos->next; | ||
| 987 | if (! should_free (pos)) | ||
| 988 | continue; | ||
| 989 | GNUNET_CONTAINER_DLL_remove (head, tail, pos); | ||
| 990 | GNUNET_free (pos); | ||
| 991 | @} | ||
| 992 | @end example | ||
| 993 | |||
| 994 | to free entries in a list (as the iteration changes the structure of the | ||
| 995 | list due to the free; the equivalent @code{for} loop does no longer | ||
| 996 | follow the simple @code{for} paradigm of @code{for(INIT;TEST;INC)}). | ||
| 997 | However, for loops that do follow the simple @code{for} paradigm we do | ||
| 998 | use @code{for}, even if it involves linked lists: | ||
| 999 | |||
| 1000 | @example | ||
| 1001 | /* simple iteration over a linked list */ | ||
| 1002 | for (pos = head; | ||
| 1003 | NULL != pos; | ||
| 1004 | pos = pos->next) | ||
| 1005 | @{ | ||
| 1006 | use (pos); | ||
| 1007 | @} | ||
| 1008 | @end example | ||
| 1009 | |||
| 1010 | |||
| 1011 | @item The first argument to all higher-order functions in GNUnet must be | ||
| 1012 | declared to be of type @code{void *} and is reserved for a closure. We do | ||
| 1013 | not use inner functions, as trampolines would conflict with setups that | ||
| 1014 | use non-executable stacks. | ||
| 1015 | The first statement in a higher-order function, which unusually should | ||
| 1016 | be part of the variable declarations, should assign the | ||
| 1017 | @code{cls} argument to the precise expected type. For example: | ||
| 1018 | |||
| 1019 | @example | ||
| 1020 | int callback (void *cls, char *args) @{ | ||
| 1021 | struct Foo *foo = cls; | ||
| 1022 | int other_variables; | ||
| 1023 | |||
| 1024 | /* rest of function */ | ||
| 1025 | @} | ||
| 1026 | @end example | ||
| 1027 | |||
| 1028 | |||
| 1029 | @item It is good practice to write complex @code{if} expressions instead | ||
| 1030 | of using deeply nested @code{if} statements. However, except for addition | ||
| 1031 | and multiplication, all operators should use parens. This is fine: | ||
| 1032 | |||
| 1033 | @example | ||
| 1034 | if ( (1 == foo) || ((0 == bar) && (x != y)) ) | ||
| 1035 | return x; | ||
| 1036 | @end example | ||
| 1037 | |||
| 1038 | |||
| 1039 | However, this is not: | ||
| 1040 | |||
| 1041 | @example | ||
| 1042 | if (1 == foo) | ||
| 1043 | return x; | ||
| 1044 | if (0 == bar && x != y) | ||
| 1045 | return x; | ||
| 1046 | @end example | ||
| 1047 | |||
| 1048 | @noindent | ||
| 1049 | Note that splitting the @code{if} statement above is debatable as the | ||
| 1050 | @code{return x} is a very trivial statement. However, once the logic after | ||
| 1051 | the branch becomes more complicated (and is still identical), the "or" | ||
| 1052 | formulation should be used for sure. | ||
| 1053 | |||
| 1054 | @item There should be two empty lines between the end of the function and | ||
| 1055 | the comments describing the following function. There should be a single | ||
| 1056 | empty line after the initial variable declarations of a function. If a | ||
| 1057 | function has no local variables, there should be no initial empty line. If | ||
| 1058 | a long function consists of several complex steps, those steps might be | ||
| 1059 | separated by an empty line (possibly followed by a comment describing the | ||
| 1060 | following step). The code should not contain empty lines in arbitrary | ||
| 1061 | places; if in doubt, it is likely better to NOT have an empty line (this | ||
| 1062 | way, more code will fit on the screen). | ||
| 1063 | @end itemize | ||
| 1064 | |||
| 1065 | @c *********************************************************************** | ||
| 1066 | @node Build-system | ||
| 1067 | @section Build-system | ||
| 1068 | |||
| 1069 | If you have code that is likely not to compile or build rules you might | ||
| 1070 | want to not trigger for most developers, use @code{if HAVE_EXPERIMENTAL} | ||
| 1071 | in your @file{Makefile.am}. | ||
| 1072 | Then it is OK to (temporarily) add non-compiling (or known-to-not-port) | ||
| 1073 | code. | ||
| 1074 | |||
| 1075 | If you want to compile all testcases but NOT run them, run configure with | ||
| 1076 | the @code{--enable-test-suppression} option. | ||
| 1077 | |||
| 1078 | If you want to run all testcases, including those that take a while, run | ||
| 1079 | configure with the @code{--enable-expensive-testcases} option. | ||
| 1080 | |||
| 1081 | If you want to compile and run benchmarks, run configure with the | ||
| 1082 | @code{--enable-benchmarks} option. | ||
| 1083 | |||
| 1084 | If you want to obtain code coverage results, run configure with the | ||
| 1085 | @code{--enable-coverage} option and run the @file{coverage.sh} script in | ||
| 1086 | the @file{contrib/} directory. | ||
| 1087 | |||
| 1088 | @cindex gnunet-ext | ||
| 1089 | @node Developing extensions for GNUnet using the gnunet-ext template | ||
| 1090 | @section Developing extensions for GNUnet using the gnunet-ext template | ||
| 1091 | |||
| 1092 | For developers who want to write extensions for GNUnet we provide the | ||
| 1093 | gnunet-ext template to provide an easy to use skeleton. | ||
| 1094 | |||
| 1095 | gnunet-ext contains the build environment and template files for the | ||
| 1096 | development of GNUnet services, command line tools, APIs and tests. | ||
| 1097 | |||
| 1098 | First of all you have to obtain gnunet-ext from git: | ||
| 1099 | |||
| 1100 | @example | ||
| 1101 | git clone https://gnunet.org/git/gnunet-ext.git | ||
| 1102 | @end example | ||
| 1103 | |||
| 1104 | The next step is to bootstrap and configure it. For configure you have to | ||
| 1105 | provide the path containing GNUnet with | ||
| 1106 | @code{--with-gnunet=/path/to/gnunet} and the prefix where you want the | ||
| 1107 | install the extension using @code{--prefix=/path/to/install}: | ||
| 1108 | |||
| 1109 | @example | ||
| 1110 | ./bootstrap | ||
| 1111 | ./configure --prefix=/path/to/install --with-gnunet=/path/to/gnunet | ||
| 1112 | @end example | ||
| 1113 | |||
| 1114 | When your GNUnet installation is not included in the default linker search | ||
| 1115 | path, you have to add @code{/path/to/gnunet} to the file | ||
| 1116 | @file{/etc/ld.so.conf} and run @code{ldconfig} or your add it to the | ||
| 1117 | environmental variable @code{LD_LIBRARY_PATH} by using | ||
| 1118 | |||
| 1119 | @example | ||
| 1120 | export LD_LIBRARY_PATH=/path/to/gnunet/lib | ||
| 1121 | @end example | ||
| 1122 | |||
| 1123 | @cindex writing testcases | ||
| 1124 | @node Writing testcases | ||
| 1125 | @section Writing testcases | ||
| 1126 | |||
| 1127 | Ideally, any non-trivial GNUnet code should be covered by automated | ||
| 1128 | testcases. Testcases should reside in the same place as the code that is | ||
| 1129 | being tested. The name of source files implementing tests should begin | ||
| 1130 | with @code{test_} followed by the name of the file that contains | ||
| 1131 | the code that is being tested. | ||
| 1132 | |||
| 1133 | Testcases in GNUnet should be integrated with the autotools build system. | ||
| 1134 | This way, developers and anyone building binary packages will be able to | ||
| 1135 | run all testcases simply by running @code{make check}. The final | ||
| 1136 | testcases shipped with the distribution should output at most some brief | ||
| 1137 | progress information and not display debug messages by default. The | ||
| 1138 | success or failure of a testcase must be indicated by returning zero | ||
| 1139 | (success) or non-zero (failure) from the main method of the testcase. | ||
| 1140 | The integration with the autotools is relatively straightforward and only | ||
| 1141 | requires modifications to the @file{Makefile.am} in the directory | ||
| 1142 | containing the testcase. For a testcase testing the code in @file{foo.c} | ||
| 1143 | the @file{Makefile.am} would contain the following lines: | ||
| 1144 | |||
| 1145 | @example | ||
| 1146 | check_PROGRAMS = test_foo | ||
| 1147 | TESTS = $(check_PROGRAMS) | ||
| 1148 | test_foo_SOURCES = test_foo.c | ||
| 1149 | test_foo_LDADD = $(top_builddir)/src/util/libgnunetutil.la | ||
| 1150 | @end example | ||
| 1151 | |||
| 1152 | Naturally, other libraries used by the testcase may be specified in the | ||
| 1153 | @code{LDADD} directive as necessary. | ||
| 1154 | |||
| 1155 | Often testcases depend on additional input files, such as a configuration | ||
| 1156 | file. These support files have to be listed using the @code{EXTRA_DIST} | ||
| 1157 | directive in order to ensure that they are included in the distribution. | ||
| 1158 | |||
| 1159 | Example: | ||
| 1160 | |||
| 1161 | @example | ||
| 1162 | EXTRA_DIST = test_foo_data.conf | ||
| 1163 | @end example | ||
| 1164 | |||
| 1165 | Executing @code{make check} will run all testcases in the current | ||
| 1166 | directory and all subdirectories. Testcases can be compiled individually | ||
| 1167 | by running @code{make test_foo} and then invoked directly using | ||
| 1168 | @code{./test_foo}. Note that due to the use of plugins in GNUnet, it is | ||
| 1169 | typically necessary to run @code{make install} before running any | ||
| 1170 | testcases. Thus the canonical command @code{make check install} has to be | ||
| 1171 | changed to @code{make install check} for GNUnet. | ||
| 1172 | |||
| 1173 | @c *********************************************************************** | ||
| 1174 | @cindex Building GNUnet | ||
| 1175 | @node Building GNUnet and its dependencies | ||
| 1176 | @section Building GNUnet and its dependencies | ||
| 1177 | |||
| 1178 | In the following section we will outline how to build GNUnet and | ||
| 1179 | some of its dependencies. We will assume a fair amount of knowledge | ||
| 1180 | for building applications under UNIX-like systems. Furthermore we | ||
| 1181 | assume that the build environment is sane and that you are aware of | ||
| 1182 | any implications actions in this process could have. | ||
| 1183 | Instructions here can be seen as notes for developers (an extension to | ||
| 1184 | the 'HACKING' section in README) as well as package maintainers. | ||
| 1185 | @b{Users should rely on the available binary packages.} | ||
| 1186 | We will use Debian as an example Operating System environment. Substitute | ||
| 1187 | accordingly with your own Operating System environment. | ||
| 1188 | |||
| 1189 | For the full list of dependencies, consult the appropriate, up-to-date | ||
| 1190 | section in the @file{README} file. | ||
| 1191 | |||
| 1192 | First, we need to build or install (depending on your OS) the following | ||
| 1193 | packages. If you build them from source, build them in this exact order: | ||
| 1194 | |||
| 1195 | @example | ||
| 1196 | libgpgerror, libgcrypt, libnettle, libunbound, GnuTLS (with libunbound | ||
| 1197 | support) | ||
| 1198 | @end example | ||
| 1199 | |||
| 1200 | After we have build and installed those packages, we continue with | ||
| 1201 | packages closer to GNUnet in this step: libgnurl (our libcurl fork), | ||
| 1202 | GNU libmicrohttpd, and GNU libextractor. Again, if your package manager | ||
| 1203 | provides one of these packages, use the packages provided from it | ||
| 1204 | unless you have good reasons (package version too old, conflicts, etc). | ||
| 1205 | We advise against compiling widely used packages such as GnuTLS | ||
| 1206 | yourself if your OS provides a variant already unless you take care | ||
| 1207 | of maintenance of the packages then. | ||
| 1208 | |||
| 1209 | In the optimistic case, this command will give you all the dependencies: | ||
| 1210 | |||
| 1211 | @example | ||
| 1212 | sudo apt-get install libgnurl libmicrohttpd libextractor | ||
| 1213 | @end example | ||
| 1214 | |||
| 1215 | From experience we know that at the very least libgnurl is not | ||
| 1216 | available in some environments. You could substitute libgnurl | ||
| 1217 | with libcurl, but we recommend to install libgnurl, as it gives | ||
| 1218 | you a predefined libcurl with the small set GNUnet requires. In | ||
| 1219 | the past namespaces of libcurl and libgnurl were shared, which | ||
| 1220 | caused problems when you wanted to integrate both of them in one | ||
| 1221 | Operating System. This has been resolved, and they can be installed | ||
| 1222 | side by side now. | ||
| 1223 | |||
| 1224 | @cindex libgnurl | ||
| 1225 | @cindex compiling libgnurl | ||
| 1226 | GNUnet and some of its function depend on a limited subset of cURL/libcurl. | ||
| 1227 | Rather than trying to enforce a certain configuration on the world, we | ||
| 1228 | opted to maintain a microfork of it that ensures we can link against the | ||
| 1229 | right set of features. We called this specialized set of libcurl | ||
| 1230 | ``libgnurl''. It is fully ABI compatible with libcurl and currently used | ||
| 1231 | by GNUnet and some of its dependencies. | ||
| 1232 | |||
| 1233 | We download libgnurl and its digital signature from the GNU fileserver, | ||
| 1234 | assuming @env{TMPDIR} exists. | ||
| 1235 | |||
| 1236 | Note: TMPDIR might be @file{/tmp}, @env{TMPDIR}, @env{TMP} or any other | ||
| 1237 | location. For consistency we assume @env{TMPDIR} points to @file{/tmp} | ||
| 1238 | for the remainder of this section. | ||
| 1239 | |||
| 1240 | @example | ||
| 1241 | cd \$TMPDIR | ||
| 1242 | wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z | ||
| 1243 | wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z.sig | ||
| 1244 | @end example | ||
| 1245 | |||
| 1246 | Next, verify the digital signature of the file: | ||
| 1247 | |||
| 1248 | @example | ||
| 1249 | gpg --verify gnurl-7.60.0.tar.Z.sig | ||
| 1250 | @end example | ||
| 1251 | |||
| 1252 | If gpg fails, you might try with @command{gpg2} on your OS. If the error | ||
| 1253 | states that ``the key can not be found'' or it is unknown, you have to | ||
| 1254 | retrieve the key (A88C8ADD129828D7EAC02E52E22F9BBFEE348588) from a | ||
| 1255 | keyserver first: | ||
| 1256 | |||
| 1257 | @example | ||
| 1258 | gpg --keyserver pgp.mit.edu --recv-keys A88C8ADD129828D7EAC02E52E22F9BBFEE348588 | ||
| 1259 | @end example | ||
| 1260 | |||
| 1261 | and rerun the verification command. | ||
| 1262 | |||
| 1263 | libgnurl will require the following packages to be present at runtime: | ||
| 1264 | gnutls (with DANE support / libunbound), libidn, zlib and at compile time: | ||
| 1265 | libtool, groff, perl, pkg-config, and python 2.7. | ||
| 1266 | |||
| 1267 | Once you have verified that all the required packages are present on your | ||
| 1268 | system, we can proceed to compile libgnurl: | ||
| 1269 | |||
| 1270 | @example | ||
| 1271 | tar -xvf gnurl-7.60.0.tar.Z | ||
| 1272 | cd gnurl-7.60.0 | ||
| 1273 | sh configure --disable-ntlm-wb | ||
| 1274 | make | ||
| 1275 | make -C tests test | ||
| 1276 | sudo make install | ||
| 1277 | @end example | ||
| 1278 | |||
| 1279 | After you've compiled and installed libgnurl, we can proceed to building | ||
| 1280 | GNUnet. | ||
| 1281 | |||
| 1282 | |||
| 1283 | |||
| 1284 | |||
| 1285 | First, in addition to the GNUnet sources you might require downloading the | ||
| 1286 | latest version of various dependencies, depending on how recent the | ||
| 1287 | software versions in your distribution of GNU/Linux are. | ||
| 1288 | Most distributions do not include sufficiently recent versions of these | ||
| 1289 | dependencies. | ||
| 1290 | Thus, a typically installation on a "modern" GNU/Linux distribution | ||
| 1291 | requires you to install the following dependencies (ideally in this | ||
| 1292 | order): | ||
| 1293 | |||
| 1294 | @itemize @bullet | ||
| 1295 | @item libgpgerror and libgcrypt | ||
| 1296 | @item libnettle and libunbound (possibly from distribution), GnuTLS | ||
| 1297 | @item libgnurl (read the README) | ||
| 1298 | @item GNU libmicrohttpd | ||
| 1299 | @item GNU libextractor | ||
| 1300 | @end itemize | ||
| 1301 | |||
| 1302 | Make sure to first install the various mandatory and optional | ||
| 1303 | dependencies including development headers from your distribution. | ||
| 1304 | |||
| 1305 | Other dependencies that you should strongly consider to install is a | ||
| 1306 | database (MySQL, sqlite or Postgres). | ||
| 1307 | The following instructions will assume that you installed at least sqlite. | ||
| 1308 | For most distributions you should be able to find pre-build packages for | ||
| 1309 | the database. Again, make sure to install the client libraries @b{and} the | ||
| 1310 | respective development headers (if they are packaged separately) as well. | ||
| 1311 | |||
| 1312 | You can find specific, detailed instructions for installing of the | ||
| 1313 | dependencies (and possibly the rest of the GNUnet installation) in the | ||
| 1314 | platform-specific descriptions, which can be found in the Index. | ||
| 1315 | Please consult them now. | ||
| 1316 | If your distribution is not listed, please study the build | ||
| 1317 | instructions for Debian stable, carefully as you try to install the | ||
| 1318 | dependencies for your own distribution. | ||
| 1319 | Contributing additional instructions for further platforms is always | ||
| 1320 | appreciated. | ||
| 1321 | Please take in mind that operating system development tends to move at | ||
| 1322 | a rather fast speed. Due to this you should be aware that some of | ||
| 1323 | the instructions could be outdated by the time you are reading this. | ||
| 1324 | If you find a mistake, please tell us about it (or even better: send | ||
| 1325 | a patch to the documentation to fix it!). | ||
| 1326 | |||
| 1327 | Before proceeding further, please double-check the dependency list. | ||
| 1328 | Note that in addition to satisfying the dependencies, you might have to | ||
| 1329 | make sure that development headers for the various libraries are also | ||
| 1330 | installed. | ||
| 1331 | There maybe files for other distributions, or you might be able to find | ||
| 1332 | equivalent packages for your distribution. | ||
| 1333 | |||
| 1334 | While it is possible to build and install GNUnet without having root | ||
| 1335 | access, we will assume that you have full control over your system in | ||
| 1336 | these instructions. | ||
| 1337 | First, you should create a system user @emph{gnunet} and an additional | ||
| 1338 | group @emph{gnunetdns}. On the GNU/Linux distributions Debian and Ubuntu, | ||
| 1339 | type: | ||
| 1340 | |||
| 1341 | @example | ||
| 1342 | sudo adduser --system --home /var/lib/gnunet --group \ | ||
| 1343 | --disabled-password gnunet | ||
| 1344 | sudo addgroup --system gnunetdns | ||
| 1345 | @end example | ||
| 1346 | |||
| 1347 | @noindent | ||
| 1348 | On other Unixes and GNU systems, this should have the same effect: | ||
| 1349 | |||
| 1350 | @example | ||
| 1351 | sudo useradd --system --groups gnunet --home-dir /var/lib/gnunet | ||
| 1352 | sudo addgroup --system gnunetdns | ||
| 1353 | @end example | ||
| 1354 | |||
| 1355 | Now compile and install GNUnet using: | ||
| 1356 | |||
| 1357 | @example | ||
| 1358 | tar xvf gnunet-@value{VERSION}.tar.gz | ||
| 1359 | cd gnunet-@value{VERSION} | ||
| 1360 | ./configure --with-sudo=sudo --with-nssdir=/lib | ||
| 1361 | make | ||
| 1362 | sudo make install | ||
| 1363 | @end example | ||
| 1364 | |||
| 1365 | If you want to be able to enable DEBUG-level log messages, add | ||
| 1366 | @code{--enable-logging=verbose} to the end of the | ||
| 1367 | @command{./configure} command. | ||
| 1368 | @code{DEBUG}-level log messages are in English only and | ||
| 1369 | should only be useful for developers (or for filing | ||
| 1370 | really detailed bug reports). | ||
| 1371 | |||
| 1372 | @noindent | ||
| 1373 | Next, edit the file @file{/etc/gnunet.conf} to contain the following: | ||
| 1374 | |||
| 1375 | @example | ||
| 1376 | [arm] | ||
| 1377 | START_SYSTEM_SERVICES = YES | ||
| 1378 | START_USER_SERVICES = NO | ||
| 1379 | @end example | ||
| 1380 | |||
| 1381 | @noindent | ||
| 1382 | You may need to update your @code{ld.so} cache to include | ||
| 1383 | files installed in @file{/usr/local/lib}: | ||
| 1384 | |||
| 1385 | @example | ||
| 1386 | # ldconfig | ||
| 1387 | @end example | ||
| 1388 | |||
| 1389 | @noindent | ||
| 1390 | Then, switch from user @code{root} to user @code{gnunet} to start | ||
| 1391 | the peer: | ||
| 1392 | |||
| 1393 | @example | ||
| 1394 | # su -s /bin/sh - gnunet | ||
| 1395 | $ gnunet-arm -c /etc/gnunet.conf -s | ||
| 1396 | @end example | ||
| 1397 | |||
| 1398 | You may also want to add the last line in the gnunet user's @file{crontab} | ||
| 1399 | prefixed with @code{@@reboot} so that it is executed whenever the system | ||
| 1400 | is booted: | ||
| 1401 | |||
| 1402 | @example | ||
| 1403 | @@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s | ||
| 1404 | @end example | ||
| 1405 | |||
| 1406 | @noindent | ||
| 1407 | This will only start the system-wide GNUnet services. | ||
| 1408 | Type @command{exit} to get back your root shell. | ||
| 1409 | Now, you need to configure the per-user part. For each | ||
| 1410 | user that should get access to GNUnet on the system, run | ||
| 1411 | (replace alice with your username): | ||
| 1412 | |||
| 1413 | @example | ||
| 1414 | sudo adduser alice gnunet | ||
| 1415 | @end example | ||
| 1416 | |||
| 1417 | @noindent | ||
| 1418 | to allow them to access the system-wide GNUnet services. Then, each | ||
| 1419 | user should create a configuration file @file{~/.config/gnunet.conf} | ||
| 1420 | with the lines: | ||
| 1421 | |||
| 1422 | @example | ||
| 1423 | [arm] | ||
| 1424 | START_SYSTEM_SERVICES = NO | ||
| 1425 | START_USER_SERVICES = YES | ||
| 1426 | DEFAULTSERVICES = gns | ||
| 1427 | @end example | ||
| 1428 | |||
| 1429 | @noindent | ||
| 1430 | and start the per-user services using | ||
| 1431 | |||
| 1432 | @example | ||
| 1433 | $ gnunet-arm -c ~/.config/gnunet.conf -s | ||
| 1434 | @end example | ||
| 1435 | |||
| 1436 | @noindent | ||
| 1437 | Again, adding a @code{crontab} entry to autostart the peer is advised: | ||
| 1438 | |||
| 1439 | @example | ||
| 1440 | @@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s | ||
| 1441 | @end example | ||
| 1442 | |||
| 1443 | @noindent | ||
| 1444 | Note that some GNUnet services (such as SOCKS5 proxies) may need a | ||
| 1445 | system-wide TCP port for each user. | ||
| 1446 | For those services, systems with more than one user may require each user | ||
| 1447 | to specify a different port number in their personal configuration file. | ||
| 1448 | |||
| 1449 | Finally, the user should perform the basic initial setup for the GNU Name | ||
| 1450 | System (GNS) certificate authority. This is done by running: | ||
| 1451 | |||
| 1452 | @example | ||
| 1453 | $ gnunet-gns-proxy-setup-ca | ||
| 1454 | @end example | ||
| 1455 | |||
| 1456 | @noindent | ||
| 1457 | The first generates the default zones, whereas the second setups the GNS | ||
| 1458 | Certificate Authority with the user's browser. Now, to activate GNS in the | ||
| 1459 | normal DNS resolution process, you need to edit your | ||
| 1460 | @file{/etc/nsswitch.conf} where you should find a line like this: | ||
| 1461 | |||
| 1462 | @example | ||
| 1463 | hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 | ||
| 1464 | @end example | ||
| 1465 | |||
| 1466 | @noindent | ||
| 1467 | The exact details may differ a bit, which is fine. Add the text | ||
| 1468 | @emph{"gns [NOTFOUND=return]"} after @emph{"files"}. | ||
| 1469 | Keep in mind that we included a backslash ("\") here just for | ||
| 1470 | markup reasons. You should write the text below on @b{one line} | ||
| 1471 | and @b{without} the "\": | ||
| 1472 | |||
| 1473 | @example | ||
| 1474 | hosts: files gns [NOTFOUND=return] mdns4_minimal \ | ||
| 1475 | [NOTFOUND=return] dns mdns4 | ||
| 1476 | @end example | ||
| 1477 | |||
| 1478 | @c FIXME: Document new behavior. | ||
| 1479 | You might want to make sure that @file{/lib/libnss_gns.so.2} exists on | ||
| 1480 | your system, it should have been created during the installation. | ||
| 1481 | |||
| 1482 | |||
| 1483 | @c ********************************************************************** | ||
| 1484 | @cindex TESTING library | ||
| 1485 | @node TESTING library | ||
| 1486 | @section TESTING library | ||
| 1487 | |||
| 1488 | The TESTING library is used for writing testcases which involve starting a | ||
| 1489 | single or multiple peers. While peers can also be started by testcases | ||
| 1490 | using the ARM subsystem, using TESTING library provides an elegant way to | ||
| 1491 | do this. The configurations of the peers are auto-generated from a given | ||
| 1492 | template to have non-conflicting port numbers ensuring that peers' | ||
| 1493 | services do not run into bind errors. This is achieved by testing ports' | ||
| 1494 | availability by binding a listening socket to them before allocating them | ||
| 1495 | to services in the generated configurations. | ||
| 1496 | |||
| 1497 | An another advantage while using TESTING is that it shortens the testcase | ||
| 1498 | startup time as the hostkeys for peers are copied from a pre-computed set | ||
| 1499 | of hostkeys instead of generating them at peer startup which may take a | ||
| 1500 | considerable amount of time when starting multiple peers or on an embedded | ||
| 1501 | processor. | ||
| 1502 | |||
| 1503 | TESTING also allows for certain services to be shared among peers. This | ||
| 1504 | feature is invaluable when testing with multiple peers as it helps to | ||
| 1505 | reduce the number of services run per each peer and hence the total | ||
| 1506 | number of processes run per testcase. | ||
| 1507 | |||
| 1508 | TESTING library only handles creating, starting and stopping peers. | ||
| 1509 | Features useful for testcases such as connecting peers in a topology are | ||
| 1510 | not available in TESTING but are available in the TESTBED subsystem. | ||
| 1511 | Furthermore, TESTING only creates peers on the localhost, however by | ||
| 1512 | using TESTBED testcases can benefit from creating peers across multiple | ||
| 1513 | hosts. | ||
| 1514 | |||
| 1515 | @menu | ||
| 1516 | * API:: | ||
| 1517 | * Finer control over peer stop:: | ||
| 1518 | * Helper functions:: | ||
| 1519 | * Testing with multiple processes:: | ||
| 1520 | @end menu | ||
| 1521 | |||
| 1522 | @cindex TESTING API | ||
| 1523 | @node API | ||
| 1524 | @subsection API | ||
| 1525 | |||
| 1526 | TESTING abstracts a group of peers as a TESTING system. All peers in a | ||
| 1527 | system have common hostname and no two services of these peers have a | ||
| 1528 | same port or a UNIX domain socket path. | ||
| 1529 | |||
| 1530 | TESTING system can be created with the function | ||
| 1531 | @code{GNUNET_TESTING_system_create()} which returns a handle to the | ||
| 1532 | system. This function takes a directory path which is used for generating | ||
| 1533 | the configurations of peers, an IP address from which connections to the | ||
| 1534 | peers' services should be allowed, the hostname to be used in peers' | ||
| 1535 | configuration, and an array of shared service specifications of type | ||
| 1536 | @code{struct GNUNET_TESTING_SharedService}. | ||
| 1537 | |||
| 1538 | The shared service specification must specify the name of the service to | ||
| 1539 | share, the configuration pertaining to that shared service and the | ||
| 1540 | maximum number of peers that are allowed to share a single instance of | ||
| 1541 | the shared service. | ||
| 1542 | |||
| 1543 | TESTING system created with @code{GNUNET_TESTING_system_create()} chooses | ||
| 1544 | ports from the default range @code{12000} - @code{56000} while | ||
| 1545 | auto-generating configurations for peers. | ||
| 1546 | This range can be customised with the function | ||
| 1547 | @code{GNUNET_TESTING_system_create_with_portrange()}. This function is | ||
| 1548 | similar to @code{GNUNET_TESTING_system_create()} except that it take 2 | ||
| 1549 | additional parameters --- the start and end of the port range to use. | ||
| 1550 | |||
| 1551 | A TESTING system is destroyed with the function | ||
| 1552 | @code{GNUNET_TESTING_system_destory()}. This function takes the handle of | ||
| 1553 | the system and a flag to remove the files created in the directory used | ||
| 1554 | to generate configurations. | ||
| 1555 | |||
| 1556 | A peer is created with the function | ||
| 1557 | @code{GNUNET_TESTING_peer_configure()}. This functions takes the system | ||
| 1558 | handle, a configuration template from which the configuration for the peer | ||
| 1559 | is auto-generated and the index from where the hostkey for the peer has to | ||
| 1560 | be copied from. When successful, this function returns a handle to the | ||
| 1561 | peer which can be used to start and stop it and to obtain the identity of | ||
| 1562 | the peer. If unsuccessful, a NULL pointer is returned with an error | ||
| 1563 | message. This function handles the generated configuration to have | ||
| 1564 | non-conflicting ports and paths. | ||
| 1565 | |||
| 1566 | Peers can be started and stopped by calling the functions | ||
| 1567 | @code{GNUNET_TESTING_peer_start()} and @code{GNUNET_TESTING_peer_stop()} | ||
| 1568 | respectively. A peer can be destroyed by calling the function | ||
| 1569 | @code{GNUNET_TESTING_peer_destroy}. When a peer is destroyed, the ports | ||
| 1570 | and paths in allocated in its configuration are reclaimed for usage in new | ||
| 1571 | peers. | ||
| 1572 | |||
| 1573 | @c *********************************************************************** | ||
| 1574 | @node Finer control over peer stop | ||
| 1575 | @subsection Finer control over peer stop | ||
| 1576 | |||
| 1577 | Using @code{GNUNET_TESTING_peer_stop()} is normally fine for testcases. | ||
| 1578 | However, calling this function for each peer is inefficient when trying to | ||
| 1579 | shutdown multiple peers as this function sends the termination signal to | ||
| 1580 | the given peer process and waits for it to terminate. It would be faster | ||
| 1581 | in this case to send the termination signals to the peers first and then | ||
| 1582 | wait on them. This is accomplished by the functions | ||
| 1583 | @code{GNUNET_TESTING_peer_kill()} which sends a termination signal to the | ||
| 1584 | peer, and the function @code{GNUNET_TESTING_peer_wait()} which waits on | ||
| 1585 | the peer. | ||
| 1586 | |||
| 1587 | Further finer control can be achieved by choosing to stop a peer | ||
| 1588 | asynchronously with the function @code{GNUNET_TESTING_peer_stop_async()}. | ||
| 1589 | This function takes a callback parameter and a closure for it in addition | ||
| 1590 | to the handle to the peer to stop. The callback function is called with | ||
| 1591 | the given closure when the peer is stopped. Using this function | ||
| 1592 | eliminates blocking while waiting for the peer to terminate. | ||
| 1593 | |||
| 1594 | An asynchronous peer stop can be canceled by calling the function | ||
| 1595 | @code{GNUNET_TESTING_peer_stop_async_cancel()}. Note that calling this | ||
| 1596 | function does not prevent the peer from terminating if the termination | ||
| 1597 | signal has already been sent to it. It does, however, cancels the | ||
| 1598 | callback to be called when the peer is stopped. | ||
| 1599 | |||
| 1600 | @c *********************************************************************** | ||
| 1601 | @node Helper functions | ||
| 1602 | @subsection Helper functions | ||
| 1603 | |||
| 1604 | Most of the testcases can benefit from an abstraction which configures a | ||
| 1605 | peer and starts it. This is provided by the function | ||
| 1606 | @code{GNUNET_TESTING_peer_run()}. This function takes the testing | ||
| 1607 | directory pathname, a configuration template, a callback and its closure. | ||
| 1608 | This function creates a peer in the given testing directory by using the | ||
| 1609 | configuration template, starts the peer and calls the given callback with | ||
| 1610 | the given closure. | ||
| 1611 | |||
| 1612 | The function @code{GNUNET_TESTING_peer_run()} starts the ARM service of | ||
| 1613 | the peer which starts the rest of the configured services. A similar | ||
| 1614 | function @code{GNUNET_TESTING_service_run} can be used to just start a | ||
| 1615 | single service of a peer. In this case, the peer's ARM service is not | ||
| 1616 | started; instead, only the given service is run. | ||
| 1617 | |||
| 1618 | @c *********************************************************************** | ||
| 1619 | @node Testing with multiple processes | ||
| 1620 | @subsection Testing with multiple processes | ||
| 1621 | |||
| 1622 | When testing GNUnet, the splitting of the code into a services and clients | ||
| 1623 | often complicates testing. The solution to this is to have the testcase | ||
| 1624 | fork @code{gnunet-service-arm}, ask it to start the required server and | ||
| 1625 | daemon processes and then execute appropriate client actions (to test the | ||
| 1626 | client APIs or the core module or both). If necessary, multiple ARM | ||
| 1627 | services can be forked using different ports (!) to simulate a network. | ||
| 1628 | However, most of the time only one ARM process is needed. Note that on | ||
| 1629 | exit, the testcase should shutdown ARM with a @code{TERM} signal (to give | ||
| 1630 | it the chance to cleanly stop its child processes). | ||
| 1631 | |||
| 1632 | The following code illustrates spawning and killing an ARM process from a | ||
| 1633 | testcase: | ||
| 1634 | |||
| 1635 | @example | ||
| 1636 | static void run (void *cls, | ||
| 1637 | char *const *args, | ||
| 1638 | const char *cfgfile, | ||
| 1639 | const struct GNUNET_CONFIGURATION_Handle *cfg) @{ | ||
| 1640 | struct GNUNET_OS_Process *arm_pid; | ||
| 1641 | arm_pid = GNUNET_OS_start_process (NULL, | ||
| 1642 | NULL, | ||
| 1643 | "gnunet-service-arm", | ||
| 1644 | "gnunet-service-arm", | ||
| 1645 | "-c", | ||
| 1646 | cfgname, | ||
| 1647 | NULL); | ||
| 1648 | /* do real test work here */ | ||
| 1649 | if (0 != GNUNET_OS_process_kill (arm_pid, SIGTERM)) | ||
| 1650 | GNUNET_log_strerror | ||
| 1651 | (GNUNET_ERROR_TYPE_WARNING, "kill"); | ||
| 1652 | GNUNET_assert (GNUNET_OK == GNUNET_OS_process_wait (arm_pid)); | ||
| 1653 | GNUNET_OS_process_close (arm_pid); @} | ||
| 1654 | |||
| 1655 | GNUNET_PROGRAM_run (argc, argv, | ||
| 1656 | "NAME-OF-TEST", | ||
| 1657 | "nohelp", | ||
| 1658 | options, | ||
| 1659 | &run, | ||
| 1660 | cls); | ||
| 1661 | @end example | ||
| 1662 | |||
| 1663 | |||
| 1664 | An alternative way that works well to test plugins is to implement a | ||
| 1665 | mock-version of the environment that the plugin expects and then to | ||
| 1666 | simply load the plugin directly. | ||
| 1667 | |||
| 1668 | @c *********************************************************************** | ||
| 1669 | @node Performance regression analysis with Gauger | ||
| 1670 | @section Performance regression analysis with Gauger | ||
| 1671 | |||
| 1672 | To help avoid performance regressions, GNUnet uses Gauger. Gauger is a | ||
| 1673 | simple logging tool that allows remote hosts to send performance data to | ||
| 1674 | a central server, where this data can be analyzed and visualized. Gauger | ||
| 1675 | shows graphs of the repository revisions and the performance data recorded | ||
| 1676 | for each revision, so sudden performance peaks or drops can be identified | ||
| 1677 | and linked to a specific revision number. | ||
| 1678 | |||
| 1679 | In the case of GNUnet, the buildbots log the performance data obtained | ||
| 1680 | during the tests after each build. The data can be accessed on GNUnet's | ||
| 1681 | Gauger page. | ||
| 1682 | |||
| 1683 | The menu on the left allows to select either the results of just one | ||
| 1684 | build bot (under "Hosts") or review the data from all hosts for a given | ||
| 1685 | test result (under "Metrics"). In case of very different absolute value | ||
| 1686 | of the results, for instance arm vs. amd64 machines, the option | ||
| 1687 | "Normalize" on a metric view can help to get an idea about the | ||
| 1688 | performance evolution across all hosts. | ||
| 1689 | |||
| 1690 | Using Gauger in GNUnet and having the performance of a module tracked over | ||
| 1691 | time is very easy. First of course, the testcase must generate some | ||
| 1692 | consistent metric, which makes sense to have logged. Highly volatile or | ||
| 1693 | random dependent metrics probably are not ideal candidates for meaningful | ||
| 1694 | regression detection. | ||
| 1695 | |||
| 1696 | To start logging any value, just include @code{gauger.h} in your testcase | ||
| 1697 | code. Then, use the macro @code{GAUGER()} to make the Buildbots log | ||
| 1698 | whatever value is of interest for you to @code{gnunet.org}'s Gauger | ||
| 1699 | server. No setup is necessary as most Buildbots have already everything | ||
| 1700 | in place and new metrics are created on demand. To delete a metric, you | ||
| 1701 | need to contact a member of the GNUnet development team (a file will need | ||
| 1702 | to be removed manually from the respective directory). | ||
| 1703 | |||
| 1704 | The code in the test should look like this: | ||
| 1705 | |||
| 1706 | @example | ||
| 1707 | [other includes] | ||
| 1708 | #include <gauger.h> | ||
| 1709 | |||
| 1710 | int main (int argc, char *argv[]) @{ | ||
| 1711 | |||
| 1712 | [run test, generate data] | ||
| 1713 | GAUGER("YOUR_MODULE", | ||
| 1714 | "METRIC_NAME", | ||
| 1715 | (float)value, | ||
| 1716 | "UNIT"); @} | ||
| 1717 | @end example | ||
| 1718 | |||
| 1719 | Where: | ||
| 1720 | |||
| 1721 | @table @asis | ||
| 1722 | |||
| 1723 | @item @strong{YOUR_MODULE} is a category in the gauger page and should be | ||
| 1724 | the name of the module or subsystem like "Core" or "DHT" | ||
| 1725 | @item @strong{METRIC} is | ||
| 1726 | the name of the metric being collected and should be concise and | ||
| 1727 | descriptive, like "PUT operations in sqlite-datastore". | ||
| 1728 | @item @strong{value} is the value | ||
| 1729 | of the metric that is logged for this run. | ||
| 1730 | @item @strong{UNIT} is the unit in | ||
| 1731 | which the value is measured, for instance "kb/s" or "kb of RAM/node". | ||
| 1732 | @end table | ||
| 1733 | |||
| 1734 | If you wish to use Gauger for your own project, you can grab a copy of the | ||
| 1735 | latest stable release or check out Gauger's Subversion repository. | ||
| 1736 | |||
| 1737 | @cindex TESTBED Subsystem | ||
| 1738 | @node TESTBED Subsystem | ||
| 1739 | @section TESTBED Subsystem | ||
| 1740 | |||
| 1741 | The TESTBED subsystem facilitates testing and measuring of multi-peer | ||
| 1742 | deployments on a single host or over multiple hosts. | ||
| 1743 | |||
| 1744 | The architecture of the testbed module is divided into the following: | ||
| 1745 | @itemize @bullet | ||
| 1746 | |||
| 1747 | @item Testbed API: An API which is used by the testing driver programs. It | ||
| 1748 | provides with functions for creating, destroying, starting, stopping | ||
| 1749 | peers, etc. | ||
| 1750 | |||
| 1751 | @item Testbed service (controller): A service which is started through the | ||
| 1752 | Testbed API. This service handles operations to create, destroy, start, | ||
| 1753 | stop peers, connect them, modify their configurations. | ||
| 1754 | |||
| 1755 | @item Testbed helper: When a controller has to be started on a host, the | ||
| 1756 | testbed API starts the testbed helper on that host which in turn starts | ||
| 1757 | the controller. The testbed helper receives a configuration for the | ||
| 1758 | controller through its stdin and changes it to ensure the controller | ||
| 1759 | doesn't run into any port conflict on that host. | ||
| 1760 | @end itemize | ||
| 1761 | |||
| 1762 | |||
| 1763 | The testbed service (controller) is different from the other GNUnet | ||
| 1764 | services in that it is not started by ARM and is not supposed to be run | ||
| 1765 | as a daemon. It is started by the testbed API through a testbed helper. | ||
| 1766 | In a typical scenario involving multiple hosts, a controller is started | ||
| 1767 | on each host. Controllers take up the actual task of creating peers, | ||
| 1768 | starting and stopping them on the hosts they run. | ||
| 1769 | |||
| 1770 | While running deployments on a single localhost the testbed API starts the | ||
| 1771 | testbed helper directly as a child process. When running deployments on | ||
| 1772 | remote hosts the testbed API starts Testbed Helpers on each remote host | ||
| 1773 | through remote shell. By default testbed API uses SSH as a remote shell. | ||
| 1774 | This can be changed by setting the environmental variable | ||
| 1775 | GNUNET_TESTBED_RSH_CMD to the required remote shell program. This | ||
| 1776 | variable can also contain parameters which are to be passed to the remote | ||
| 1777 | shell program. For e.g: | ||
| 1778 | |||
| 1779 | @example | ||
| 1780 | export GNUNET_TESTBED_RSH_CMD="ssh -o BatchMode=yes \ | ||
| 1781 | -o NoHostAuthenticationForLocalhost=yes %h" | ||
| 1782 | @end example | ||
| 1783 | |||
| 1784 | Substitutions are allowed in the command string above, | ||
| 1785 | this allows for substitutions through placemarks which begin with a `%'. | ||
| 1786 | At present the following substitutions are supported | ||
| 1787 | |||
| 1788 | @itemize @bullet | ||
| 1789 | @item %h: hostname | ||
| 1790 | @item %u: username | ||
| 1791 | @item %p: port | ||
| 1792 | @end itemize | ||
| 1793 | |||
| 1794 | Note that the substitution placemark is replaced only when the | ||
| 1795 | corresponding field is available and only once. Specifying | ||
| 1796 | |||
| 1797 | @example | ||
| 1798 | %u@@%h | ||
| 1799 | @end example | ||
| 1800 | |||
| 1801 | doesn't work either. If you want to user username substitutions for | ||
| 1802 | @command{SSH}, use the argument @code{-l} before the | ||
| 1803 | username substitution. | ||
| 1804 | |||
| 1805 | For example: | ||
| 1806 | @example | ||
| 1807 | ssh -l %u -p %p %h | ||
| 1808 | @end example | ||
| 1809 | |||
| 1810 | The testbed API and the helper communicate through the helpers stdin and | ||
| 1811 | stdout. As the helper is started through a remote shell on remote hosts | ||
| 1812 | any output messages from the remote shell interfere with the communication | ||
| 1813 | and results in a failure while starting the helper. For this reason, it is | ||
| 1814 | suggested to use flags to make the remote shells produce no output | ||
| 1815 | messages and to have password-less logins. The default remote shell, SSH, | ||
| 1816 | the default options are: | ||
| 1817 | |||
| 1818 | @example | ||
| 1819 | -o BatchMode=yes -o NoHostBasedAuthenticationForLocalhost=yes" | ||
| 1820 | @end example | ||
| 1821 | |||
| 1822 | Password-less logins should be ensured by using SSH keys. | ||
| 1823 | |||
| 1824 | Since the testbed API executes the remote shell as a non-interactive | ||
| 1825 | shell, certain scripts like .bashrc, .profiler may not be executed. If | ||
| 1826 | this is the case testbed API can be forced to execute an interactive | ||
| 1827 | shell by setting up the environmental variable | ||
| 1828 | @code{GNUNET_TESTBED_RSH_CMD_SUFFIX} to a shell program. | ||
| 1829 | |||
| 1830 | An example could be: | ||
| 1831 | |||
| 1832 | @example | ||
| 1833 | export GNUNET_TESTBED_RSH_CMD_SUFFIX="sh -lc" | ||
| 1834 | @end example | ||
| 1835 | |||
| 1836 | The testbed API will then execute the remote shell program as: | ||
| 1837 | |||
| 1838 | @example | ||
| 1839 | $GNUNET_TESTBED_RSH_CMD -p $port $dest $GNUNET_TESTBED_RSH_CMD_SUFFIX \ | ||
| 1840 | gnunet-helper-testbed | ||
| 1841 | @end example | ||
| 1842 | |||
| 1843 | On some systems, problems may arise while starting testbed helpers if | ||
| 1844 | GNUnet is installed into a custom location since the helper may not be | ||
| 1845 | found in the standard path. This can be addressed by setting the variable | ||
| 1846 | `@code{HELPER_BINARY_PATH}' to the path of the testbed helper. | ||
| 1847 | Testbed API will then use this path to start helper binaries both | ||
| 1848 | locally and remotely. | ||
| 1849 | |||
| 1850 | Testbed API can accessed by including the | ||
| 1851 | @file{gnunet_testbed_service.h} file and linking with | ||
| 1852 | @code{-lgnunettestbed}. | ||
| 1853 | |||
| 1854 | @c *********************************************************************** | ||
| 1855 | @menu | ||
| 1856 | * Supported Topologies:: | ||
| 1857 | * Hosts file format:: | ||
| 1858 | * Topology file format:: | ||
| 1859 | * Testbed Barriers:: | ||
| 1860 | * Automatic large-scale deployment in the PlanetLab testbed:: | ||
| 1861 | * TESTBED Caveats:: | ||
| 1862 | @end menu | ||
| 1863 | |||
| 1864 | @node Supported Topologies | ||
| 1865 | @subsection Supported Topologies | ||
| 1866 | |||
| 1867 | While testing multi-peer deployments, it is often needed that the peers | ||
| 1868 | are connected in some topology. This requirement is addressed by the | ||
| 1869 | function @code{GNUNET_TESTBED_overlay_connect()} which connects any given | ||
| 1870 | two peers in the testbed. | ||
| 1871 | |||
| 1872 | The API also provides a helper function | ||
| 1873 | @code{GNUNET_TESTBED_overlay_configure_topology()} to connect a given set | ||
| 1874 | of peers in any of the following supported topologies: | ||
| 1875 | |||
| 1876 | @itemize @bullet | ||
| 1877 | |||
| 1878 | @item @code{GNUNET_TESTBED_TOPOLOGY_CLIQUE}: All peers are connected with | ||
| 1879 | each other | ||
| 1880 | |||
| 1881 | @item @code{GNUNET_TESTBED_TOPOLOGY_LINE}: Peers are connected to form a | ||
| 1882 | line | ||
| 1883 | |||
| 1884 | @item @code{GNUNET_TESTBED_TOPOLOGY_RING}: Peers are connected to form a | ||
| 1885 | ring topology | ||
| 1886 | |||
| 1887 | @item @code{GNUNET_TESTBED_TOPOLOGY_2D_TORUS}: Peers are connected to | ||
| 1888 | form a 2 dimensional torus topology. The number of peers may not be a | ||
| 1889 | perfect square, in that case the resulting torus may not have the uniform | ||
| 1890 | poloidal and toroidal lengths | ||
| 1891 | |||
| 1892 | @item @code{GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI}: Topology is generated | ||
| 1893 | to form a random graph. The number of links to be present should be given | ||
| 1894 | |||
| 1895 | @item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD}: Peers are connected to | ||
| 1896 | form a 2D Torus with some random links among them. The number of random | ||
| 1897 | links are to be given | ||
| 1898 | |||
| 1899 | @item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING}: Peers are | ||
| 1900 | connected to form a ring with some random links among them. The number of | ||
| 1901 | random links are to be given | ||
| 1902 | |||
| 1903 | @item @code{GNUNET_TESTBED_TOPOLOGY_SCALE_FREE}: Connects peers in a | ||
| 1904 | topology where peer connectivity follows power law - new peers are | ||
| 1905 | connected with high probability to well connected peers. | ||
| 1906 | (See Emergence of Scaling in Random Networks. Science 286, | ||
| 1907 | 509-512, 1999 | ||
| 1908 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/emergence_of_scaling_in_random_networks__barabasi_albert_science_286__1999.pdf, pdf})) | ||
| 1909 | |||
| 1910 | @item @code{GNUNET_TESTBED_TOPOLOGY_FROM_FILE}: The topology information | ||
| 1911 | is loaded from a file. The path to the file has to be given. | ||
| 1912 | @xref{Topology file format}, for the format of this file. | ||
| 1913 | |||
| 1914 | @item @code{GNUNET_TESTBED_TOPOLOGY_NONE}: No topology | ||
| 1915 | @end itemize | ||
| 1916 | |||
| 1917 | |||
| 1918 | The above supported topologies can be specified respectively by setting | ||
| 1919 | the variable @code{OVERLAY_TOPOLOGY} to the following values in the | ||
| 1920 | configuration passed to Testbed API functions | ||
| 1921 | @code{GNUNET_TESTBED_test_run()} and | ||
| 1922 | @code{GNUNET_TESTBED_run()}: | ||
| 1923 | |||
| 1924 | @itemize @bullet | ||
| 1925 | @item @code{CLIQUE} | ||
| 1926 | @item @code{RING} | ||
| 1927 | @item @code{LINE} | ||
| 1928 | @item @code{2D_TORUS} | ||
| 1929 | @item @code{RANDOM} | ||
| 1930 | @item @code{SMALL_WORLD} | ||
| 1931 | @item @code{SMALL_WORLD_RING} | ||
| 1932 | @item @code{SCALE_FREE} | ||
| 1933 | @item @code{FROM_FILE} | ||
| 1934 | @item @code{NONE} | ||
| 1935 | @end itemize | ||
| 1936 | |||
| 1937 | |||
| 1938 | Topologies @code{RANDOM}, @code{SMALL_WORLD} and @code{SMALL_WORLD_RING} | ||
| 1939 | require the option @code{OVERLAY_RANDOM_LINKS} to be set to the number of | ||
| 1940 | random links to be generated in the configuration. The option will be | ||
| 1941 | ignored for the rest of the topologies. | ||
| 1942 | |||
| 1943 | Topology @code{SCALE_FREE} requires the options | ||
| 1944 | @code{SCALE_FREE_TOPOLOGY_CAP} to be set to the maximum number of peers | ||
| 1945 | which can connect to a peer and @code{SCALE_FREE_TOPOLOGY_M} to be set to | ||
| 1946 | how many peers a peer should be at least connected to. | ||
| 1947 | |||
| 1948 | Similarly, the topology @code{FROM_FILE} requires the option | ||
| 1949 | @code{OVERLAY_TOPOLOGY_FILE} to contain the path of the file containing | ||
| 1950 | the topology information. This option is ignored for the rest of the | ||
| 1951 | topologies. @xref{Topology file format}, for the format of this file. | ||
| 1952 | |||
| 1953 | @c *********************************************************************** | ||
| 1954 | @node Hosts file format | ||
| 1955 | @subsection Hosts file format | ||
| 1956 | |||
| 1957 | The testbed API offers the function | ||
| 1958 | @code{GNUNET_TESTBED_hosts_load_from_file()} to load from a given file | ||
| 1959 | details about the hosts which testbed can use for deploying peers. | ||
| 1960 | This function is useful to keep the data about hosts | ||
| 1961 | separate instead of hard coding them in code. | ||
| 1962 | |||
| 1963 | Another helper function from testbed API, @code{GNUNET_TESTBED_run()} | ||
| 1964 | also takes a hosts file name as its parameter. It uses the above | ||
| 1965 | function to populate the hosts data structures and start controllers to | ||
| 1966 | deploy peers. | ||
| 1967 | |||
| 1968 | These functions require the hosts file to be of the following format: | ||
| 1969 | @itemize @bullet | ||
| 1970 | @item Each line is interpreted to have details about a host | ||
| 1971 | @item Host details should include the username to use for logging into the | ||
| 1972 | host, the hostname of the host and the port number to use for the remote | ||
| 1973 | shell program. All thee values should be given. | ||
| 1974 | @item These details should be given in the following format: | ||
| 1975 | @example | ||
| 1976 | <username>@@<hostname>:<port> | ||
| 1977 | @end example | ||
| 1978 | @end itemize | ||
| 1979 | |||
| 1980 | Note that having canonical hostnames may cause problems while resolving | ||
| 1981 | the IP addresses (See this bug). Hence it is advised to provide the hosts' | ||
| 1982 | IP numerical addresses as hostnames whenever possible. | ||
| 1983 | |||
| 1984 | @c *********************************************************************** | ||
| 1985 | @node Topology file format | ||
| 1986 | @subsection Topology file format | ||
| 1987 | |||
| 1988 | A topology file describes how peers are to be connected. It should adhere | ||
| 1989 | to the following format for testbed to parse it correctly. | ||
| 1990 | |||
| 1991 | Each line should begin with the target peer id. This should be followed by | ||
| 1992 | a colon(`:') and origin peer ids separated by `|'. All spaces except for | ||
| 1993 | newline characters are ignored. The API will then try to connect each | ||
| 1994 | origin peer to the target peer. | ||
| 1995 | |||
| 1996 | For example, the following file will result in 5 overlay connections: | ||
| 1997 | [2->1], [3->1],[4->3], [0->3], [2->0]@ | ||
| 1998 | @code{@ 1:2|3@ 3:4| 0@ 0: 2@ } | ||
| 1999 | |||
| 2000 | @c *********************************************************************** | ||
| 2001 | @node Testbed Barriers | ||
| 2002 | @subsection Testbed Barriers | ||
| 2003 | |||
| 2004 | The testbed subsystem's barriers API facilitates coordination among the | ||
| 2005 | peers run by the testbed and the experiment driver. The concept is | ||
| 2006 | similar to the barrier synchronisation mechanism found in parallel | ||
| 2007 | programming or multi-threading paradigms - a peer waits at a barrier upon | ||
| 2008 | reaching it until the barrier is reached by a predefined number of peers. | ||
| 2009 | This predefined number of peers required to cross a barrier is also called | ||
| 2010 | quorum. We say a peer has reached a barrier if the peer is waiting for the | ||
| 2011 | barrier to be crossed. Similarly a barrier is said to be reached if the | ||
| 2012 | required quorum of peers reach the barrier. A barrier which is reached is | ||
| 2013 | deemed as crossed after all the peers waiting on it are notified. | ||
| 2014 | |||
| 2015 | The barriers API provides the following functions: | ||
| 2016 | @itemize @bullet | ||
| 2017 | @item @strong{@code{GNUNET_TESTBED_barrier_init()}:} function to | ||
| 2018 | initialize a barrier in the experiment | ||
| 2019 | @item @strong{@code{GNUNET_TESTBED_barrier_cancel()}:} function to cancel | ||
| 2020 | a barrier which has been initialized before | ||
| 2021 | @item @strong{@code{GNUNET_TESTBED_barrier_wait()}:} function to signal | ||
| 2022 | barrier service that the caller has reached a barrier and is waiting for | ||
| 2023 | it to be crossed | ||
| 2024 | @item @strong{@code{GNUNET_TESTBED_barrier_wait_cancel()}:} function to | ||
| 2025 | stop waiting for a barrier to be crossed | ||
| 2026 | @end itemize | ||
| 2027 | |||
| 2028 | |||
| 2029 | Among the above functions, the first two, namely | ||
| 2030 | @code{GNUNET_TESTBED_barrier_init()} and | ||
| 2031 | @code{GNUNET_TESTBED_barrier_cancel()} are used by experiment drivers. All | ||
| 2032 | barriers should be initialised by the experiment driver by calling | ||
| 2033 | @code{GNUNET_TESTBED_barrier_init()}. This function takes a name to | ||
| 2034 | identify the barrier, the quorum required for the barrier to be crossed | ||
| 2035 | and a notification callback for notifying the experiment driver when the | ||
| 2036 | barrier is crossed. @code{GNUNET_TESTBED_barrier_cancel()} cancels an | ||
| 2037 | initialised barrier and frees the resources allocated for it. This | ||
| 2038 | function can be called upon a initialised barrier before it is crossed. | ||
| 2039 | |||
| 2040 | The remaining two functions @code{GNUNET_TESTBED_barrier_wait()} and | ||
| 2041 | @code{GNUNET_TESTBED_barrier_wait_cancel()} are used in the peer's | ||
| 2042 | processes. @code{GNUNET_TESTBED_barrier_wait()} connects to the local | ||
| 2043 | barrier service running on the same host the peer is running on and | ||
| 2044 | registers that the caller has reached the barrier and is waiting for the | ||
| 2045 | barrier to be crossed. Note that this function can only be used by peers | ||
| 2046 | which are started by testbed as this function tries to access the local | ||
| 2047 | barrier service which is part of the testbed controller service. Calling | ||
| 2048 | @code{GNUNET_TESTBED_barrier_wait()} on an uninitialised barrier results | ||
| 2049 | in failure. @code{GNUNET_TESTBED_barrier_wait_cancel()} cancels the | ||
| 2050 | notification registered by @code{GNUNET_TESTBED_barrier_wait()}. | ||
| 2051 | |||
| 2052 | |||
| 2053 | @c *********************************************************************** | ||
| 2054 | @menu | ||
| 2055 | * Implementation:: | ||
| 2056 | @end menu | ||
| 2057 | |||
| 2058 | @node Implementation | ||
| 2059 | @subsubsection Implementation | ||
| 2060 | |||
| 2061 | Since barriers involve coordination between experiment driver and peers, | ||
| 2062 | the barrier service in the testbed controller is split into two | ||
| 2063 | components. The first component responds to the message generated by the | ||
| 2064 | barrier API used by the experiment driver (functions | ||
| 2065 | @code{GNUNET_TESTBED_barrier_init()} and | ||
| 2066 | @code{GNUNET_TESTBED_barrier_cancel()}) and the second component to the | ||
| 2067 | messages generated by barrier API used by peers (functions | ||
| 2068 | @code{GNUNET_TESTBED_barrier_wait()} and | ||
| 2069 | @code{GNUNET_TESTBED_barrier_wait_cancel()}). | ||
| 2070 | |||
| 2071 | Calling @code{GNUNET_TESTBED_barrier_init()} sends a | ||
| 2072 | @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_INIT} message to the master | ||
| 2073 | controller. The master controller then registers a barrier and calls | ||
| 2074 | @code{GNUNET_TESTBED_barrier_init()} for each its subcontrollers. In this | ||
| 2075 | way barrier initialisation is propagated to the controller hierarchy. | ||
| 2076 | While propagating initialisation, any errors at a subcontroller such as | ||
| 2077 | timeout during further propagation are reported up the hierarchy back to | ||
| 2078 | the experiment driver. | ||
| 2079 | |||
| 2080 | Similar to @code{GNUNET_TESTBED_barrier_init()}, | ||
| 2081 | @code{GNUNET_TESTBED_barrier_cancel()} propagates | ||
| 2082 | @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_CANCEL} message which causes | ||
| 2083 | controllers to remove an initialised barrier. | ||
| 2084 | |||
| 2085 | The second component is implemented as a separate service in the binary | ||
| 2086 | `gnunet-service-testbed' which already has the testbed controller service. | ||
| 2087 | Although this deviates from the gnunet process architecture of having one | ||
| 2088 | service per binary, it is needed in this case as this component needs | ||
| 2089 | access to barrier data created by the first component. This component | ||
| 2090 | responds to @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT} messages from | ||
| 2091 | local peers when they call @code{GNUNET_TESTBED_barrier_wait()}. Upon | ||
| 2092 | receiving @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT} message, the | ||
| 2093 | service checks if the requested barrier has been initialised before and | ||
| 2094 | if it was not initialised, an error status is sent through | ||
| 2095 | @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message to the local | ||
| 2096 | peer and the connection from the peer is terminated. If the barrier is | ||
| 2097 | initialised before, the barrier's counter for reached peers is incremented | ||
| 2098 | and a notification is registered to notify the peer when the barrier is | ||
| 2099 | reached. The connection from the peer is left open. | ||
| 2100 | |||
| 2101 | When enough peers required to attain the quorum send | ||
| 2102 | @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT} messages, the controller | ||
| 2103 | sends a @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message to its | ||
| 2104 | parent informing that the barrier is crossed. If the controller has | ||
| 2105 | started further subcontrollers, it delays this message until it receives | ||
| 2106 | a similar notification from each of those subcontrollers. Finally, the | ||
| 2107 | barriers API at the experiment driver receives the | ||
| 2108 | @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} when the barrier is | ||
| 2109 | reached at all the controllers. | ||
| 2110 | |||
| 2111 | The barriers API at the experiment driver responds to the | ||
| 2112 | @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message by echoing it | ||
| 2113 | back to the master controller and notifying the experiment controller | ||
| 2114 | through the notification callback that a barrier has been crossed. The | ||
| 2115 | echoed @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message is | ||
| 2116 | propagated by the master controller to the controller hierarchy. This | ||
| 2117 | propagation triggers the notifications registered by peers at each of the | ||
| 2118 | controllers in the hierarchy. Note the difference between this downward | ||
| 2119 | propagation of the @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} | ||
| 2120 | message from its upward propagation --- the upward propagation is needed | ||
| 2121 | for ensuring that the barrier is reached by all the controllers and the | ||
| 2122 | downward propagation is for triggering that the barrier is crossed. | ||
| 2123 | |||
| 2124 | @cindex PlanetLab testbed | ||
| 2125 | @node Automatic large-scale deployment in the PlanetLab testbed | ||
| 2126 | @subsection Automatic large-scale deployment in the PlanetLab testbed | ||
| 2127 | |||
| 2128 | PlanetLab is a testbed for computer networking and distributed systems | ||
| 2129 | research. It was established in 2002 and as of June 2010 was composed of | ||
| 2130 | 1090 nodes at 507 sites worldwide. | ||
| 2131 | |||
| 2132 | To automate the GNUnet we created a set of automation tools to simplify | ||
| 2133 | the large-scale deployment. We provide you a set of scripts you can use | ||
| 2134 | to deploy GNUnet on a set of nodes and manage your installation. | ||
| 2135 | |||
| 2136 | Please also check @uref{https://gnunet.org/installation-fedora8-svn} and | ||
| 2137 | @uref{https://gnunet.org/installation-fedora12-svn} to find detailed | ||
| 2138 | instructions how to install GNUnet on a PlanetLab node. | ||
| 2139 | |||
| 2140 | |||
| 2141 | @c *********************************************************************** | ||
| 2142 | @menu | ||
| 2143 | * PlanetLab Automation for Fedora8 nodes:: | ||
| 2144 | * Install buildslave on PlanetLab nodes running fedora core 8:: | ||
| 2145 | * Setup a new PlanetLab testbed using GPLMT:: | ||
| 2146 | * Why do i get an ssh error when using the regex profiler?:: | ||
| 2147 | @end menu | ||
| 2148 | |||
| 2149 | @node PlanetLab Automation for Fedora8 nodes | ||
| 2150 | @subsubsection PlanetLab Automation for Fedora8 nodes | ||
| 2151 | |||
| 2152 | @c *********************************************************************** | ||
| 2153 | @node Install buildslave on PlanetLab nodes running fedora core 8 | ||
| 2154 | @subsubsection Install buildslave on PlanetLab nodes running fedora core 8 | ||
| 2155 | @c ** Actually this is a subsubsubsection, but must be fixed differently | ||
| 2156 | @c ** as subsubsection is the lowest. | ||
| 2157 | |||
| 2158 | Since most of the PlanetLab nodes are running the very old Fedora core 8 | ||
| 2159 | image, installing the buildslave software is quite some pain. For our | ||
| 2160 | PlanetLab testbed we figured out how to install the buildslave software | ||
| 2161 | best. | ||
| 2162 | |||
| 2163 | @c This is a very terrible way to suggest installing software. | ||
| 2164 | @c FIXME: Is there an official, safer way instead of blind-piping a | ||
| 2165 | @c script? | ||
| 2166 | @c FIXME: Use newer pypi URLs below. | ||
| 2167 | Install Distribute for Python: | ||
| 2168 | |||
| 2169 | @example | ||
| 2170 | curl http://python-distribute.org/distribute_setup.py | sudo python | ||
| 2171 | @end example | ||
| 2172 | |||
| 2173 | Install Distribute for zope.interface <= 3.8.0 (4.0 and 4.0.1 will not | ||
| 2174 | work): | ||
| 2175 | |||
| 2176 | @example | ||
| 2177 | export PYPI=@value{PYPI-URL} | ||
| 2178 | wget $PYPI/z/zope.interface/zope.interface-3.8.0.tar.gz | ||
| 2179 | tar zvfz zope.interface-3.8.0.tar.gz | ||
| 2180 | cd zope.interface-3.8.0 | ||
| 2181 | sudo python setup.py install | ||
| 2182 | @end example | ||
| 2183 | |||
| 2184 | Install the buildslave software (0.8.6 was the latest version): | ||
| 2185 | |||
| 2186 | @example | ||
| 2187 | export GCODE="http://buildbot.googlecode.com/files" | ||
| 2188 | wget $GCODE/buildbot-slave-0.8.6p1.tar.gz | ||
| 2189 | tar xvfz buildbot-slave-0.8.6p1.tar.gz | ||
| 2190 | cd buildslave-0.8.6p1 | ||
| 2191 | sudo python setup.py install | ||
| 2192 | @end example | ||
| 2193 | |||
| 2194 | The setup will download the matching twisted package and install it. | ||
| 2195 | It will also try to install the latest version of zope.interface which | ||
| 2196 | will fail to install. Buildslave will work anyway since version 3.8.0 | ||
| 2197 | was installed before! | ||
| 2198 | |||
| 2199 | @c *********************************************************************** | ||
| 2200 | @node Setup a new PlanetLab testbed using GPLMT | ||
| 2201 | @subsubsection Setup a new PlanetLab testbed using GPLMT | ||
| 2202 | |||
| 2203 | @itemize @bullet | ||
| 2204 | @item Get a new slice and assign nodes | ||
| 2205 | Ask your PlanetLab PI to give you a new slice and assign the nodes you | ||
| 2206 | need | ||
| 2207 | @item Install a buildmaster | ||
| 2208 | You can stick to the buildbot documentation:@ | ||
| 2209 | @uref{http://buildbot.net/buildbot/docs/current/manual/installation.html} | ||
| 2210 | @item Install the buildslave software on all nodes | ||
| 2211 | To install the buildslave on all nodes assigned to your slice you can use | ||
| 2212 | the tasklist @code{install_buildslave_fc8.xml} provided with GPLMT: | ||
| 2213 | |||
| 2214 | @example | ||
| 2215 | ./gplmt.py -c contrib/tumple_gnunet.conf -t \ | ||
| 2216 | contrib/tasklists/install_buildslave_fc8.xml -a -p <planetlab password> | ||
| 2217 | @end example | ||
| 2218 | |||
| 2219 | @item Create the buildmaster configuration and the slave setup commands | ||
| 2220 | |||
| 2221 | The master and the and the slaves have need to have credentials and the | ||
| 2222 | master has to have all nodes configured. This can be done with the | ||
| 2223 | @file{create_buildbot_configuration.py} script in the @file{scripts} | ||
| 2224 | directory. | ||
| 2225 | |||
| 2226 | This scripts takes a list of nodes retrieved directly from PlanetLab or | ||
| 2227 | read from a file and a configuration template and creates: | ||
| 2228 | |||
| 2229 | @itemize @bullet | ||
| 2230 | @item a tasklist which can be executed with gplmt to setup the slaves | ||
| 2231 | @item a master.cfg file containing a PlanetLab nodes | ||
| 2232 | @end itemize | ||
| 2233 | |||
| 2234 | A configuration template is included in the <contrib>, most important is | ||
| 2235 | that the script replaces the following tags in the template: | ||
| 2236 | |||
| 2237 | %GPLMT_BUILDER_DEFINITION :@ GPLMT_BUILDER_SUMMARY@ GPLMT_SLAVES@ | ||
| 2238 | %GPLMT_SCHEDULER_BUILDERS | ||
| 2239 | |||
| 2240 | Create configuration for all nodes assigned to a slice: | ||
| 2241 | |||
| 2242 | @example | ||
| 2243 | ./create_buildbot_configuration.py -u <planetlab username> \ | ||
| 2244 | -p <planetlab password> -s <slice> -m <buildmaster+port> \ | ||
| 2245 | -t <template> | ||
| 2246 | @end example | ||
| 2247 | |||
| 2248 | Create configuration for some nodes in a file: | ||
| 2249 | |||
| 2250 | @example | ||
| 2251 | ./create_buildbot_configuration.p -f <node_file> \ | ||
| 2252 | -m <buildmaster+port> -t <template> | ||
| 2253 | @end example | ||
| 2254 | |||
| 2255 | @item Copy the @file{master.cfg} to the buildmaster and start it | ||
| 2256 | Use @code{buildbot start <basedir>} to start the server | ||
| 2257 | @item Setup the buildslaves | ||
| 2258 | @end itemize | ||
| 2259 | |||
| 2260 | @c *********************************************************************** | ||
| 2261 | @node Why do i get an ssh error when using the regex profiler? | ||
| 2262 | @subsubsection Why do i get an ssh error when using the regex profiler? | ||
| 2263 | |||
| 2264 | Why do i get an ssh error "Permission denied (publickey,password)." when | ||
| 2265 | using the regex profiler although passwordless ssh to localhost works | ||
| 2266 | using publickey and ssh-agent? | ||
| 2267 | |||
| 2268 | You have to generate a public/private-key pair with no password:@ | ||
| 2269 | @code{ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_localhost}@ | ||
| 2270 | and then add the following to your ~/.ssh/config file: | ||
| 2271 | |||
| 2272 | @code{Host 127.0.0.1@ IdentityFile ~/.ssh/id_localhost} | ||
| 2273 | |||
| 2274 | now make sure your hostsfile looks like | ||
| 2275 | |||
| 2276 | @example | ||
| 2277 | [USERNAME]@@127.0.0.1:22@ | ||
| 2278 | [USERNAME]@@127.0.0.1:22 | ||
| 2279 | @end example | ||
| 2280 | |||
| 2281 | You can test your setup by running @code{ssh 127.0.0.1} in a | ||
| 2282 | terminal and then in the opened session run it again. | ||
| 2283 | If you were not asked for a password on either login, | ||
| 2284 | then you should be good to go. | ||
| 2285 | |||
| 2286 | @cindex TESTBED Caveats | ||
| 2287 | @node TESTBED Caveats | ||
| 2288 | @subsection TESTBED Caveats | ||
| 2289 | |||
| 2290 | This section documents a few caveats when using the GNUnet testbed | ||
| 2291 | subsystem. | ||
| 2292 | |||
| 2293 | @c *********************************************************************** | ||
| 2294 | @menu | ||
| 2295 | * CORE must be started:: | ||
| 2296 | * ATS must want the connections:: | ||
| 2297 | @end menu | ||
| 2298 | |||
| 2299 | @node CORE must be started | ||
| 2300 | @subsubsection CORE must be started | ||
| 2301 | |||
| 2302 | A uncomplicated issue is bug #3993 | ||
| 2303 | (@uref{https://gnunet.org/bugs/view.php?id=3993, https://gnunet.org/bugs/view.php?id=3993}): | ||
| 2304 | Your configuration MUST somehow ensure that for each peer the | ||
| 2305 | @code{CORE} service is started when the peer is setup, otherwise | ||
| 2306 | @code{TESTBED} may fail to connect peers when the topology is initialized, | ||
| 2307 | as @code{TESTBED} will start some @code{CORE} services but not | ||
| 2308 | necessarily all (but it relies on all of them running). The easiest way | ||
| 2309 | is to set | ||
| 2310 | |||
| 2311 | @example | ||
| 2312 | [core] | ||
| 2313 | IMMEDIATE_START = YES | ||
| 2314 | @end example | ||
| 2315 | |||
| 2316 | @noindent | ||
| 2317 | in the configuration file. | ||
| 2318 | Alternatively, having any service that directly or indirectly depends on | ||
| 2319 | @code{CORE} being started with @code{IMMEDIATE_START} will also do. | ||
| 2320 | This issue largely arises if users try to over-optimize by not | ||
| 2321 | starting any services with @code{IMMEDIATE_START}. | ||
| 2322 | |||
| 2323 | @c *********************************************************************** | ||
| 2324 | @node ATS must want the connections | ||
| 2325 | @subsubsection ATS must want the connections | ||
| 2326 | |||
| 2327 | When TESTBED sets up connections, it only offers the respective HELLO | ||
| 2328 | information to the TRANSPORT service. It is then up to the ATS service to | ||
| 2329 | @strong{decide} to use the connection. The ATS service will typically | ||
| 2330 | eagerly establish any connection if the number of total connections is | ||
| 2331 | low (relative to bandwidth). Details may further depend on the | ||
| 2332 | specific ATS backend that was configured. If ATS decides to NOT establish | ||
| 2333 | a connection (even though TESTBED provided the required information), then | ||
| 2334 | that connection will count as failed for TESTBED. Note that you can | ||
| 2335 | configure TESTBED to tolerate a certain number of connection failures | ||
| 2336 | (see '-e' option of gnunet-testbed-profiler). This issue largely arises | ||
| 2337 | for dense overlay topologies, especially if you try to create cliques | ||
| 2338 | with more than 20 peers. | ||
| 2339 | |||
| 2340 | @cindex libgnunetutil | ||
| 2341 | @node libgnunetutil | ||
| 2342 | @section libgnunetutil | ||
| 2343 | |||
| 2344 | libgnunetutil is the fundamental library that all GNUnet code builds upon. | ||
| 2345 | Ideally, this library should contain most of the platform dependent code | ||
| 2346 | (except for user interfaces and really special needs that only few | ||
| 2347 | applications have). It is also supposed to offer basic services that most | ||
| 2348 | if not all GNUnet binaries require. The code of libgnunetutil is in the | ||
| 2349 | @file{src/util/} directory. The public interface to the library is in the | ||
| 2350 | gnunet_util.h header. The functions provided by libgnunetutil fall | ||
| 2351 | roughly into the following categories (in roughly the order of importance | ||
| 2352 | for new developers): | ||
| 2353 | |||
| 2354 | @itemize @bullet | ||
| 2355 | @item logging (common_logging.c) | ||
| 2356 | @item memory allocation (common_allocation.c) | ||
| 2357 | @item endianess conversion (common_endian.c) | ||
| 2358 | @item internationalization (common_gettext.c) | ||
| 2359 | @item String manipulation (string.c) | ||
| 2360 | @item file access (disk.c) | ||
| 2361 | @item buffered disk IO (bio.c) | ||
| 2362 | @item time manipulation (time.c) | ||
| 2363 | @item configuration parsing (configuration.c) | ||
| 2364 | @item command-line handling (getopt*.c) | ||
| 2365 | @item cryptography (crypto_*.c) | ||
| 2366 | @item data structures (container_*.c) | ||
| 2367 | @item CPS-style scheduling (scheduler.c) | ||
| 2368 | @item Program initialization (program.c) | ||
| 2369 | @item Networking (network.c, client.c, server*.c, service.c) | ||
| 2370 | @item message queuing (mq.c) | ||
| 2371 | @item bandwidth calculations (bandwidth.c) | ||
| 2372 | @item Other OS-related (os*.c, plugin.c, signal.c) | ||
| 2373 | @item Pseudonym management (pseudonym.c) | ||
| 2374 | @end itemize | ||
| 2375 | |||
| 2376 | It should be noted that only developers that fully understand this entire | ||
| 2377 | API will be able to write good GNUnet code. | ||
| 2378 | |||
| 2379 | Ideally, porting GNUnet should only require porting the gnunetutil | ||
| 2380 | library. More testcases for the gnunetutil APIs are therefore a great | ||
| 2381 | way to make porting of GNUnet easier. | ||
| 2382 | |||
| 2383 | @menu | ||
| 2384 | * Logging:: | ||
| 2385 | * Interprocess communication API (IPC):: | ||
| 2386 | * Cryptography API:: | ||
| 2387 | * Message Queue API:: | ||
| 2388 | * Service API:: | ||
| 2389 | * Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps:: | ||
| 2390 | * CONTAINER_MDLL API:: | ||
| 2391 | @end menu | ||
| 2392 | |||
| 2393 | @cindex Logging | ||
| 2394 | @cindex log levels | ||
| 2395 | @node Logging | ||
| 2396 | @subsection Logging | ||
| 2397 | |||
| 2398 | GNUnet is able to log its activity, mostly for the purposes of debugging | ||
| 2399 | the program at various levels. | ||
| 2400 | |||
| 2401 | @file{gnunet_common.h} defines several @strong{log levels}: | ||
| 2402 | @table @asis | ||
| 2403 | |||
| 2404 | @item ERROR for errors (really problematic situations, often leading to | ||
| 2405 | crashes) | ||
| 2406 | @item WARNING for warnings (troubling situations that might have | ||
| 2407 | negative consequences, although not fatal) | ||
| 2408 | @item INFO for various information. | ||
| 2409 | Used somewhat rarely, as GNUnet statistics is used to hold and display | ||
| 2410 | most of the information that users might find interesting. | ||
| 2411 | @item DEBUG for debugging. | ||
| 2412 | Does not produce much output on normal builds, but when extra logging is | ||
| 2413 | enabled at compile time, a staggering amount of data is outputted under | ||
| 2414 | this log level. | ||
| 2415 | @end table | ||
| 2416 | |||
| 2417 | |||
| 2418 | Normal builds of GNUnet (configured with @code{--enable-logging[=yes]}) | ||
| 2419 | are supposed to log nothing under DEBUG level. The | ||
| 2420 | @code{--enable-logging=verbose} configure option can be used to create a | ||
| 2421 | build with all logging enabled. However, such build will produce large | ||
| 2422 | amounts of log data, which is inconvenient when one tries to hunt down a | ||
| 2423 | specific problem. | ||
| 2424 | |||
| 2425 | To mitigate this problem, GNUnet provides facilities to apply a filter to | ||
| 2426 | reduce the logs: | ||
| 2427 | @table @asis | ||
| 2428 | |||
| 2429 | @item Logging by default When no log levels are configured in any other | ||
| 2430 | way (see below), GNUnet will default to the WARNING log level. This | ||
| 2431 | mostly applies to GNUnet command line utilities, services and daemons; | ||
| 2432 | tests will always set log level to WARNING or, if | ||
| 2433 | @code{--enable-logging=verbose} was passed to configure, to DEBUG. The | ||
| 2434 | default level is suggested for normal operation. | ||
| 2435 | @item The -L option Most GNUnet executables accept an "-L loglevel" or | ||
| 2436 | "--log=loglevel" option. If used, it makes the process set a global log | ||
| 2437 | level to "loglevel". Thus it is possible to run some processes | ||
| 2438 | with -L DEBUG, for example, and others with -L ERROR to enable specific | ||
| 2439 | settings to diagnose problems with a particular process. | ||
| 2440 | @item Configuration files. Because GNUnet | ||
| 2441 | service and daemon processes are usually launched by gnunet-arm, it is not | ||
| 2442 | possible to pass different custom command line options directly to every | ||
| 2443 | one of them. The options passed to @code{gnunet-arm} only affect | ||
| 2444 | gnunet-arm and not the rest of GNUnet. However, one can specify a | ||
| 2445 | configuration key "OPTIONS" in the section that corresponds to a service | ||
| 2446 | or a daemon, and put a value of "-L loglevel" there. This will make the | ||
| 2447 | respective service or daemon set its log level to "loglevel" (as the | ||
| 2448 | value of OPTIONS will be passed as a command-line argument). | ||
| 2449 | |||
| 2450 | To specify the same log level for all services without creating separate | ||
| 2451 | "OPTIONS" entries in the configuration for each one, the user can specify | ||
| 2452 | a config key "GLOBAL_POSTFIX" in the [arm] section of the configuration | ||
| 2453 | file. The value of GLOBAL_POSTFIX will be appended to all command lines | ||
| 2454 | used by the ARM service to run other services. It can contain any option | ||
| 2455 | valid for all GNUnet commands, thus in particular the "-L loglevel" | ||
| 2456 | option. The ARM service itself is, however, unaffected by GLOBAL_POSTFIX; | ||
| 2457 | to set log level for it, one has to specify "OPTIONS" key in the [arm] | ||
| 2458 | section. | ||
| 2459 | @item Environment variables. | ||
| 2460 | Setting global per-process log levels with "-L loglevel" does not offer | ||
| 2461 | sufficient log filtering granularity, as one service will call interface | ||
| 2462 | libraries and supporting libraries of other GNUnet services, potentially | ||
| 2463 | producing lots of debug log messages from these libraries. Also, changing | ||
| 2464 | the config file is not always convenient (especially when running the | ||
| 2465 | GNUnet test suite).@ To fix that, and to allow GNUnet to use different | ||
| 2466 | log filtering at runtime without re-compiling the whole source tree, the | ||
| 2467 | log calls were changed to be configurable at run time. To configure them | ||
| 2468 | one has to define environment variables "GNUNET_FORCE_LOGFILE", | ||
| 2469 | "GNUNET_LOG" and/or "GNUNET_FORCE_LOG": | ||
| 2470 | @itemize @bullet | ||
| 2471 | |||
| 2472 | @item "GNUNET_LOG" only affects the logging when no global log level is | ||
| 2473 | configured by any other means (that is, the process does not explicitly | ||
| 2474 | set its own log level, there are no "-L loglevel" options on command line | ||
| 2475 | or in configuration files), and can be used to override the default | ||
| 2476 | WARNING log level. | ||
| 2477 | |||
| 2478 | @item "GNUNET_FORCE_LOG" will completely override any other log | ||
| 2479 | configuration options given. | ||
| 2480 | |||
| 2481 | @item "GNUNET_FORCE_LOGFILE" will completely override the location of the | ||
| 2482 | file to log messages to. It should contain a relative or absolute file | ||
| 2483 | name. Setting GNUNET_FORCE_LOGFILE is equivalent to passing | ||
| 2484 | "--log-file=logfile" or "-l logfile" option (see below). It supports "[]" | ||
| 2485 | format in file names, but not "@{@}" (see below). | ||
| 2486 | @end itemize | ||
| 2487 | |||
| 2488 | |||
| 2489 | Because environment variables are inherited by child processes when they | ||
| 2490 | are launched, starting or re-starting the ARM service with these | ||
| 2491 | variables will propagate them to all other services. | ||
| 2492 | |||
| 2493 | "GNUNET_LOG" and "GNUNET_FORCE_LOG" variables must contain a specially | ||
| 2494 | formatted @strong{logging definition} string, which looks like this:@ | ||
| 2495 | |||
| 2496 | @c FIXME: Can we close this with [/component] instead? | ||
| 2497 | @example | ||
| 2498 | [component];[file];[function];[from_line[-to_line]];loglevel[/component...] | ||
| 2499 | @end example | ||
| 2500 | |||
| 2501 | That is, a logging definition consists of definition entries, separated by | ||
| 2502 | slashes ('/'). If only one entry is present, there is no need to add a | ||
| 2503 | slash to its end (although it is not forbidden either).@ All definition | ||
| 2504 | fields (component, file, function, lines and loglevel) are mandatory, but | ||
| 2505 | (except for the loglevel) they can be empty. An empty field means | ||
| 2506 | "match anything". Note that even if fields are empty, the semicolon (';') | ||
| 2507 | separators must be present.@ The loglevel field is mandatory, and must | ||
| 2508 | contain one of the log level names (ERROR, WARNING, INFO or DEBUG).@ | ||
| 2509 | The lines field might contain one non-negative number, in which case it | ||
| 2510 | matches only one line, or a range "from_line-to_line", in which case it | ||
| 2511 | matches any line in the interval [from_line;to_line] (that is, including | ||
| 2512 | both start and end line).@ GNUnet mostly defaults component name to the | ||
| 2513 | name of the service that is implemented in a process ('transport', | ||
| 2514 | 'core', 'peerinfo', etc), but logging calls can specify custom component | ||
| 2515 | names using @code{GNUNET_log_from}.@ File name and function name are | ||
| 2516 | provided by the compiler (__FILE__ and __FUNCTION__ built-ins). | ||
| 2517 | |||
| 2518 | Component, file and function fields are interpreted as non-extended | ||
| 2519 | regular expressions (GNU libc regex functions are used). Matching is | ||
| 2520 | case-sensitive, "^" and "$" will match the beginning and the end of the | ||
| 2521 | text. If a field is empty, its contents are automatically replaced with | ||
| 2522 | a ".*" regular expression, which matches anything. Matching is done in | ||
| 2523 | the default way, which means that the expression matches as long as it's | ||
| 2524 | contained anywhere in the string. Thus "GNUNET_" will match both | ||
| 2525 | "GNUNET_foo" and "BAR_GNUNET_BAZ". Use '^' and/or '$' to make sure that | ||
| 2526 | the expression matches at the start and/or at the end of the string. | ||
| 2527 | The semicolon (';') can't be escaped, and GNUnet will not use it in | ||
| 2528 | component names (it can't be used in function names and file names | ||
| 2529 | anyway). | ||
| 2530 | |||
| 2531 | @end table | ||
| 2532 | |||
| 2533 | |||
| 2534 | Every logging call in GNUnet code will be (at run time) matched against | ||
| 2535 | the log definitions passed to the process. If a log definition fields are | ||
| 2536 | matching the call arguments, then the call log level is compared the the | ||
| 2537 | log level of that definition. If the call log level is less or equal to | ||
| 2538 | the definition log level, the call is allowed to proceed. Otherwise the | ||
| 2539 | logging call is forbidden, and nothing is logged. If no definitions | ||
| 2540 | matched at all, GNUnet will use the global log level or (if a global log | ||
| 2541 | level is not specified) will default to WARNING (that is, it will allow | ||
| 2542 | the call to proceed, if its level is less or equal to the global log | ||
| 2543 | level or to WARNING). | ||
| 2544 | |||
| 2545 | That is, definitions are evaluated from left to right, and the first | ||
| 2546 | matching definition is used to allow or deny the logging call. Thus it is | ||
| 2547 | advised to place narrow definitions at the beginning of the logdef | ||
| 2548 | string, and generic definitions - at the end. | ||
| 2549 | |||
| 2550 | Whether a call is allowed or not is only decided the first time this | ||
| 2551 | particular call is made. The evaluation result is then cached, so that | ||
| 2552 | any attempts to make the same call later will be allowed or disallowed | ||
| 2553 | right away. Because of that runtime log level evaluation should not | ||
| 2554 | significantly affect the process performance. | ||
| 2555 | Log definition parsing is only done once, at the first call to | ||
| 2556 | @code{GNUNET_log_setup ()} made by the process (which is usually done soon after | ||
| 2557 | it starts). | ||
| 2558 | |||
| 2559 | At the moment of writing there is no way to specify logging definitions | ||
| 2560 | from configuration files, only via environment variables. | ||
| 2561 | |||
| 2562 | At the moment GNUnet will stop processing a log definition when it | ||
| 2563 | encounters an error in definition formatting or an error in regular | ||
| 2564 | expression syntax, and will not report the failure in any way. | ||
| 2565 | |||
| 2566 | |||
| 2567 | @c *********************************************************************** | ||
| 2568 | @menu | ||
| 2569 | * Examples:: | ||
| 2570 | * Log files:: | ||
| 2571 | * Updated behavior of GNUNET_log:: | ||
| 2572 | @end menu | ||
| 2573 | |||
| 2574 | @node Examples | ||
| 2575 | @subsubsection Examples | ||
| 2576 | |||
| 2577 | @table @asis | ||
| 2578 | |||
| 2579 | @item @code{GNUNET_FORCE_LOG=";;;;DEBUG" gnunet-arm -s} Start GNUnet | ||
| 2580 | process tree, running all processes with DEBUG level (one should be | ||
| 2581 | careful with it, as log files will grow at alarming rate!) | ||
| 2582 | @item @code{GNUNET_FORCE_LOG="core;;;;DEBUG" gnunet-arm -s} Start GNUnet | ||
| 2583 | process tree, running the core service under DEBUG level (everything else | ||
| 2584 | will use configured or default level). | ||
| 2585 | |||
| 2586 | @item Start GNUnet process tree, allowing any logging calls from | ||
| 2587 | gnunet-service-transport_validation.c (everything else will use | ||
| 2588 | configured or default level). | ||
| 2589 | |||
| 2590 | @example | ||
| 2591 | GNUNET_FORCE_LOG=";gnunet-service-transport_validation.c;;; DEBUG" \ | ||
| 2592 | gnunet-arm -s | ||
| 2593 | @end example | ||
| 2594 | |||
| 2595 | @item Start GNUnet process tree, allowing any logging calls from | ||
| 2596 | gnunet-gnunet-service-fs_push.c (everything else will use configured or | ||
| 2597 | default level). | ||
| 2598 | |||
| 2599 | @example | ||
| 2600 | GNUNET_FORCE_LOG="fs;gnunet-service-fs_push.c;;;DEBUG" gnunet-arm -s | ||
| 2601 | @end example | ||
| 2602 | |||
| 2603 | @item Start GNUnet process tree, allowing any logging calls from the | ||
| 2604 | GNUNET_NETWORK_socket_select function (everything else will use | ||
| 2605 | configured or default level). | ||
| 2606 | |||
| 2607 | @example | ||
| 2608 | GNUNET_FORCE_LOG=";;GNUNET_NETWORK_socket_select;;DEBUG" gnunet-arm -s | ||
| 2609 | @end example | ||
| 2610 | |||
| 2611 | @item Start GNUnet process tree, allowing any logging calls from the | ||
| 2612 | components that have "transport" in their names, and are made from | ||
| 2613 | function that have "send" in their names. Everything else will be allowed | ||
| 2614 | to be logged only if it has WARNING level. | ||
| 2615 | |||
| 2616 | @example | ||
| 2617 | GNUNET_FORCE_LOG="transport.*;;.*send.*;;DEBUG/;;;;WARNING" gnunet-arm -s | ||
| 2618 | @end example | ||
| 2619 | |||
| 2620 | @end table | ||
| 2621 | |||
| 2622 | |||
| 2623 | On Windows, one can use batch files to run GNUnet processes with special | ||
| 2624 | environment variables, without affecting the whole system. Such batch | ||
| 2625 | file will look like this: | ||
| 2626 | |||
| 2627 | @example | ||
| 2628 | set GNUNET_FORCE_LOG=;;do_transmit;;DEBUG@ gnunet-arm -s | ||
| 2629 | @end example | ||
| 2630 | |||
| 2631 | (note the absence of double quotes in the environment variable definition, | ||
| 2632 | as opposed to earlier examples, which use the shell). | ||
| 2633 | Another limitation, on Windows, GNUNET_FORCE_LOGFILE @strong{MUST} be set | ||
| 2634 | in order to GNUNET_FORCE_LOG to work. | ||
| 2635 | |||
| 2636 | |||
| 2637 | @cindex Log files | ||
| 2638 | @node Log files | ||
| 2639 | @subsubsection Log files | ||
| 2640 | |||
| 2641 | GNUnet can be told to log everything into a file instead of stderr (which | ||
| 2642 | is the default) using the "--log-file=logfile" or "-l logfile" option. | ||
| 2643 | This option can also be passed via command line, or from the "OPTION" and | ||
| 2644 | "GLOBAL_POSTFIX" configuration keys (see above). The file name passed | ||
| 2645 | with this option is subject to GNUnet filename expansion. If specified in | ||
| 2646 | "GLOBAL_POSTFIX", it is also subject to ARM service filename expansion, | ||
| 2647 | in particular, it may contain "@{@}" (left and right curly brace) | ||
| 2648 | sequence, which will be replaced by ARM with the name of the service. | ||
| 2649 | This is used to keep logs from more than one service separate, while only | ||
| 2650 | specifying one template containing "@{@}" in GLOBAL_POSTFIX. | ||
| 2651 | |||
| 2652 | As part of a secondary file name expansion, the first occurrence of "[]" | ||
| 2653 | sequence ("left square brace" followed by "right square brace") in the | ||
| 2654 | file name will be replaced with a process identifier or the process when | ||
| 2655 | it initializes its logging subsystem. As a result, all processes will log | ||
| 2656 | into different files. This is convenient for isolating messages of a | ||
| 2657 | particular process, and prevents I/O races when multiple processes try to | ||
| 2658 | write into the file at the same time. This expansion is done | ||
| 2659 | independently of "@{@}" expansion that ARM service does (see above). | ||
| 2660 | |||
| 2661 | The log file name that is specified via "-l" can contain format characters | ||
| 2662 | from the 'strftime' function family. For example, "%Y" will be replaced | ||
| 2663 | with the current year. Using "basename-%Y-%m-%d.log" would include the | ||
| 2664 | current year, month and day in the log file. If a GNUnet process runs for | ||
| 2665 | long enough to need more than one log file, it will eventually clean up | ||
| 2666 | old log files. Currently, only the last three log files (plus the current | ||
| 2667 | log file) are preserved. So once the fifth log file goes into use (so | ||
| 2668 | after 4 days if you use "%Y-%m-%d" as above), the first log file will be | ||
| 2669 | automatically deleted. Note that if your log file name only contains "%Y", | ||
| 2670 | then log files would be kept for 4 years and the logs from the first year | ||
| 2671 | would be deleted once year 5 begins. If you do not use any date-related | ||
| 2672 | string format codes, logs would never be automatically deleted by GNUnet. | ||
| 2673 | |||
| 2674 | |||
| 2675 | @c *********************************************************************** | ||
| 2676 | |||
| 2677 | @node Updated behavior of GNUNET_log | ||
| 2678 | @subsubsection Updated behavior of GNUNET_log | ||
| 2679 | |||
| 2680 | It's currently quite common to see constructions like this all over the | ||
| 2681 | code: | ||
| 2682 | |||
| 2683 | @example | ||
| 2684 | #if MESH_DEBUG | ||
| 2685 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "MESH: client disconnected\n"); | ||
| 2686 | #endif | ||
| 2687 | @end example | ||
| 2688 | |||
| 2689 | The reason for the #if is not to avoid displaying the message when | ||
| 2690 | disabled (GNUNET_ERROR_TYPE takes care of that), but to avoid the | ||
| 2691 | compiler including it in the binary at all, when compiling GNUnet for | ||
| 2692 | platforms with restricted storage space / memory (MIPS routers, | ||
| 2693 | ARM plug computers / dev boards, etc). | ||
| 2694 | |||
| 2695 | This presents several problems: the code gets ugly, hard to write and it | ||
| 2696 | is very easy to forget to include the #if guards, creating non-consistent | ||
| 2697 | code. A new change in GNUNET_log aims to solve these problems. | ||
| 2698 | |||
| 2699 | @strong{This change requires to @file{./configure} with at least | ||
| 2700 | @code{--enable-logging=verbose} to see debug messages.} | ||
| 2701 | |||
| 2702 | Here is an example of code with dense debug statements: | ||
| 2703 | |||
| 2704 | @example | ||
| 2705 | switch (restrict_topology) @{ | ||
| 2706 | case GNUNET_TESTING_TOPOLOGY_CLIQUE:#if VERBOSE_TESTING | ||
| 2707 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, _("Blacklisting all but clique | ||
| 2708 | topology\n")); #endif unblacklisted_connections = create_clique (pg, | ||
| 2709 | &remove_connections, BLACKLIST, GNUNET_NO); break; case | ||
| 2710 | GNUNET_TESTING_TOPOLOGY_SMALL_WORLD_RING: #if VERBOSE_TESTING GNUNET_log | ||
| 2711 | (GNUNET_ERROR_TYPE_DEBUG, _("Blacklisting all but small world (ring) | ||
| 2712 | topology\n")); #endif unblacklisted_connections = create_small_world_ring | ||
| 2713 | (pg,&remove_connections, BLACKLIST); break; | ||
| 2714 | @end example | ||
| 2715 | |||
| 2716 | |||
| 2717 | Pretty hard to follow, huh? | ||
| 2718 | |||
| 2719 | From now on, it is not necessary to include the #if / #endif statements to | ||
| 2720 | achieve the same behavior. The @code{GNUNET_log} and @code{GNUNET_log_from} | ||
| 2721 | macros take | ||
| 2722 | care of it for you, depending on the configure option: | ||
| 2723 | |||
| 2724 | @itemize @bullet | ||
| 2725 | @item If @code{--enable-logging} is set to @code{no}, the binary will | ||
| 2726 | contain no log messages at all. | ||
| 2727 | @item If @code{--enable-logging} is set to @code{yes}, the binary will | ||
| 2728 | contain no DEBUG messages, and therefore running with @command{-L DEBUG} | ||
| 2729 | will have | ||
| 2730 | no effect. Other messages (ERROR, WARNING, INFO, etc) will be included. | ||
| 2731 | @item If @code{--enable-logging} is set to @code{verbose}, or | ||
| 2732 | @code{veryverbose} the binary will contain DEBUG messages (still, it will | ||
| 2733 | be necessary to run with @command{-L DEBUG} or set the DEBUG config option | ||
| 2734 | to show | ||
| 2735 | them). | ||
| 2736 | @end itemize | ||
| 2737 | |||
| 2738 | |||
| 2739 | If you are a developer: | ||
| 2740 | @itemize @bullet | ||
| 2741 | @item please make sure that you @code{./configure | ||
| 2742 | --enable-logging=@{verbose,veryverbose@}}, so you can see DEBUG messages. | ||
| 2743 | @item please remove the @code{#if} statements around @code{GNUNET_log | ||
| 2744 | (GNUNET_ERROR_TYPE_DEBUG, ...)} lines, to improve the readability of your | ||
| 2745 | code. | ||
| 2746 | @end itemize | ||
| 2747 | |||
| 2748 | Since now activating DEBUG automatically makes it VERBOSE and activates | ||
| 2749 | @strong{all} debug messages by default, you probably want to use the | ||
| 2750 | https://gnunet.org/logging functionality to filter only relevant messages. | ||
| 2751 | A suitable configuration could be: | ||
| 2752 | |||
| 2753 | @example | ||
| 2754 | $ export GNUNET_FORCE_LOG="^YOUR_SUBSYSTEM$;;;;DEBUG/;;;;WARNING" | ||
| 2755 | @end example | ||
| 2756 | |||
| 2757 | Which will behave almost like enabling DEBUG in that subsystem before the | ||
| 2758 | change. Of course you can adapt it to your particular needs, this is only | ||
| 2759 | a quick example. | ||
| 2760 | |||
| 2761 | @cindex Interprocess communication API | ||
| 2762 | @cindex ICP | ||
| 2763 | @node Interprocess communication API (IPC) | ||
| 2764 | @subsection Interprocess communication API (IPC) | ||
| 2765 | |||
| 2766 | In GNUnet a variety of new message types might be defined and used in | ||
| 2767 | interprocess communication, in this tutorial we use the | ||
| 2768 | @code{struct AddressLookupMessage} as a example to introduce how to | ||
| 2769 | construct our own message type in GNUnet and how to implement the message | ||
| 2770 | communication between service and client. | ||
| 2771 | (Here, a client uses the @code{struct AddressLookupMessage} as a request | ||
| 2772 | to ask the server to return the address of any other peer connecting to | ||
| 2773 | the service.) | ||
| 2774 | |||
| 2775 | |||
| 2776 | @c *********************************************************************** | ||
| 2777 | @menu | ||
| 2778 | * Define new message types:: | ||
| 2779 | * Define message struct:: | ||
| 2780 | * Client - Establish connection:: | ||
| 2781 | * Client - Initialize request message:: | ||
| 2782 | * Client - Send request and receive response:: | ||
| 2783 | * Server - Startup service:: | ||
| 2784 | * Server - Add new handles for specified messages:: | ||
| 2785 | * Server - Process request message:: | ||
| 2786 | * Server - Response to client:: | ||
| 2787 | * Server - Notification of clients:: | ||
| 2788 | * Conversion between Network Byte Order (Big Endian) and Host Byte Order:: | ||
| 2789 | @end menu | ||
| 2790 | |||
| 2791 | @node Define new message types | ||
| 2792 | @subsubsection Define new message types | ||
| 2793 | |||
| 2794 | First of all, you should define the new message type in | ||
| 2795 | @file{gnunet_protocols.h}: | ||
| 2796 | |||
| 2797 | @example | ||
| 2798 | // Request to look addresses of peers in server. | ||
| 2799 | #define GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_LOOKUP 29 | ||
| 2800 | // Response to the address lookup request. | ||
| 2801 | #define GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY 30 | ||
| 2802 | @end example | ||
| 2803 | |||
| 2804 | @c *********************************************************************** | ||
| 2805 | @node Define message struct | ||
| 2806 | @subsubsection Define message struct | ||
| 2807 | |||
| 2808 | After the type definition, the specified message structure should also be | ||
| 2809 | described in the header file, e.g. transport.h in our case. | ||
| 2810 | |||
| 2811 | @example | ||
| 2812 | struct AddressLookupMessage @{ | ||
| 2813 | struct GNUNET_MessageHeader header; | ||
| 2814 | int32_t numeric_only GNUNET_PACKED; | ||
| 2815 | struct GNUNET_TIME_AbsoluteNBO timeout; | ||
| 2816 | uint32_t addrlen GNUNET_PACKED; | ||
| 2817 | /* followed by 'addrlen' bytes of the actual address, then | ||
| 2818 | followed by the 0-terminated name of the transport */ @}; | ||
| 2819 | GNUNET_NETWORK_STRUCT_END | ||
| 2820 | @end example | ||
| 2821 | |||
| 2822 | |||
| 2823 | Please note @code{GNUNET_NETWORK_STRUCT_BEGIN} and @code{GNUNET_PACKED} | ||
| 2824 | which both ensure correct alignment when sending structs over the network. | ||
| 2825 | |||
| 2826 | @menu | ||
| 2827 | @end menu | ||
| 2828 | |||
| 2829 | @c *********************************************************************** | ||
| 2830 | @node Client - Establish connection | ||
| 2831 | @subsubsection Client - Establish connection | ||
| 2832 | @c %**end of header | ||
| 2833 | |||
| 2834 | |||
| 2835 | At first, on the client side, the underlying API is employed to create a | ||
| 2836 | new connection to a service, in our example the transport service would be | ||
| 2837 | connected. | ||
| 2838 | |||
| 2839 | @example | ||
| 2840 | struct GNUNET_CLIENT_Connection *client; | ||
| 2841 | client = GNUNET_CLIENT_connect ("transport", cfg); | ||
| 2842 | @end example | ||
| 2843 | |||
| 2844 | @c *********************************************************************** | ||
| 2845 | @node Client - Initialize request message | ||
| 2846 | @subsubsection Client - Initialize request message | ||
| 2847 | @c %**end of header | ||
| 2848 | |||
| 2849 | When the connection is ready, we initialize the message. In this step, | ||
| 2850 | all the fields of the message should be properly initialized, namely the | ||
| 2851 | size, type, and some extra user-defined data, such as timeout, name of | ||
| 2852 | transport, address and name of transport. | ||
| 2853 | |||
| 2854 | @example | ||
| 2855 | struct AddressLookupMessage *msg; | ||
| 2856 | size_t len = sizeof (struct AddressLookupMessage) | ||
| 2857 | + addressLen | ||
| 2858 | + strlen (nameTrans) | ||
| 2859 | + 1; | ||
| 2860 | msg->header->size = htons (len); | ||
| 2861 | msg->header->type = htons | ||
| 2862 | (GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_LOOKUP); | ||
| 2863 | msg->timeout = GNUNET_TIME_absolute_hton (abs_timeout); | ||
| 2864 | msg->addrlen = htonl (addressLen); | ||
| 2865 | char *addrbuf = (char *) &msg[1]; | ||
| 2866 | memcpy (addrbuf, address, addressLen); | ||
| 2867 | char *tbuf = &addrbuf[addressLen]; | ||
| 2868 | memcpy (tbuf, nameTrans, strlen (nameTrans) + 1); | ||
| 2869 | @end example | ||
| 2870 | |||
| 2871 | Note that, here the functions @code{htonl}, @code{htons} and | ||
| 2872 | @code{GNUNET_TIME_absolute_hton} are applied to convert little endian | ||
| 2873 | into big endian, about the usage of the big/small endian order and the | ||
| 2874 | corresponding conversion function please refer to Introduction of | ||
| 2875 | Big Endian and Little Endian. | ||
| 2876 | |||
| 2877 | @c *********************************************************************** | ||
| 2878 | @node Client - Send request and receive response | ||
| 2879 | @subsubsection Client - Send request and receive response | ||
| 2880 | @c %**end of header | ||
| 2881 | |||
| 2882 | @b{FIXME: This is very outdated, see the tutorial for the current API!} | ||
| 2883 | |||
| 2884 | Next, the client would send the constructed message as a request to the | ||
| 2885 | service and wait for the response from the service. To accomplish this | ||
| 2886 | goal, there are a number of API calls that can be used. In this example, | ||
| 2887 | @code{GNUNET_CLIENT_transmit_and_get_response} is chosen as the most | ||
| 2888 | appropriate function to use. | ||
| 2889 | |||
| 2890 | @example | ||
| 2891 | GNUNET_CLIENT_transmit_and_get_response | ||
| 2892 | (client, msg->header, timeout, GNUNET_YES, &address_response_processor, | ||
| 2893 | arp_ctx); | ||
| 2894 | @end example | ||
| 2895 | |||
| 2896 | the argument @code{address_response_processor} is a function with | ||
| 2897 | @code{GNUNET_CLIENT_MessageHandler} type, which is used to process the | ||
| 2898 | reply message from the service. | ||
| 2899 | |||
| 2900 | @node Server - Startup service | ||
| 2901 | @subsubsection Server - Startup service | ||
| 2902 | |||
| 2903 | After receiving the request message, we run a standard GNUnet service | ||
| 2904 | startup sequence using @code{GNUNET_SERVICE_run}, as follows, | ||
| 2905 | |||
| 2906 | @example | ||
| 2907 | int main(int argc, char**argv) @{ | ||
| 2908 | GNUNET_SERVICE_run(argc, argv, "transport" | ||
| 2909 | GNUNET_SERVICE_OPTION_NONE, &run, NULL)); @} | ||
| 2910 | @end example | ||
| 2911 | |||
| 2912 | @c *********************************************************************** | ||
| 2913 | @node Server - Add new handles for specified messages | ||
| 2914 | @subsubsection Server - Add new handles for specified messages | ||
| 2915 | @c %**end of header | ||
| 2916 | |||
| 2917 | in the function above the argument @code{run} is used to initiate | ||
| 2918 | transport service,and defined like this: | ||
| 2919 | |||
| 2920 | @example | ||
| 2921 | static void run (void *cls, | ||
| 2922 | struct GNUNET_SERVER_Handle *serv, | ||
| 2923 | const struct GNUNET_CONFIGURATION_Handle *cfg) @{ | ||
| 2924 | GNUNET_SERVER_add_handlers (serv, handlers); @} | ||
| 2925 | @end example | ||
| 2926 | |||
| 2927 | |||
| 2928 | Here, @code{GNUNET_SERVER_add_handlers} must be called in the run | ||
| 2929 | function to add new handlers in the service. The parameter | ||
| 2930 | @code{handlers} is a list of @code{struct GNUNET_SERVER_MessageHandler} | ||
| 2931 | to tell the service which function should be called when a particular | ||
| 2932 | type of message is received, and should be defined in this way: | ||
| 2933 | |||
| 2934 | @example | ||
| 2935 | static struct GNUNET_SERVER_MessageHandler handlers[] = @{ | ||
| 2936 | @{&handle_start, | ||
| 2937 | NULL, | ||
| 2938 | GNUNET_MESSAGE_TYPE_TRANSPORT_START, | ||
| 2939 | 0@}, | ||
| 2940 | @{&handle_send, | ||
| 2941 | NULL, | ||
| 2942 | GNUNET_MESSAGE_TYPE_TRANSPORT_SEND, | ||
| 2943 | 0@}, | ||
| 2944 | @{&handle_try_connect, | ||
| 2945 | NULL, | ||
| 2946 | GNUNET_MESSAGE_TYPE_TRANSPORT_TRY_CONNECT, | ||
| 2947 | sizeof (struct TryConnectMessage) | ||
| 2948 | @}, | ||
| 2949 | @{&handle_address_lookup, | ||
| 2950 | NULL, | ||
| 2951 | GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_LOOKUP, | ||
| 2952 | 0@}, | ||
| 2953 | @{NULL, | ||
| 2954 | NULL, | ||
| 2955 | 0, | ||
| 2956 | 0@} | ||
| 2957 | @}; | ||
| 2958 | @end example | ||
| 2959 | |||
| 2960 | |||
| 2961 | As shown, the first member of the struct in the first area is a callback | ||
| 2962 | function, which is called to process the specified message types, given | ||
| 2963 | as the third member. The second parameter is the closure for the callback | ||
| 2964 | function, which is set to @code{NULL} in most cases, and the last | ||
| 2965 | parameter is the expected size of the message of this type, usually we | ||
| 2966 | set it to 0 to accept variable size, for special cases the exact size of | ||
| 2967 | the specified message also can be set. In addition, the terminator sign | ||
| 2968 | depicted as @code{@{NULL, NULL, 0, 0@}} is set in the last area. | ||
| 2969 | |||
| 2970 | @c *********************************************************************** | ||
| 2971 | @node Server - Process request message | ||
| 2972 | @subsubsection Server - Process request message | ||
| 2973 | @c %**end of header | ||
| 2974 | |||
| 2975 | After the initialization of transport service, the request message would | ||
| 2976 | be processed. Before handling the main message data, the validity of this | ||
| 2977 | message should be checked out, e.g., to check whether the size of message | ||
| 2978 | is correct. | ||
| 2979 | |||
| 2980 | @example | ||
| 2981 | size = ntohs (message->size); | ||
| 2982 | if (size < sizeof (struct AddressLookupMessage)) @{ | ||
| 2983 | GNUNET_break_op (0); | ||
| 2984 | GNUNET_SERVER_receive_done (client, GNUNET_SYSERR); | ||
| 2985 | return; @} | ||
| 2986 | @end example | ||
| 2987 | |||
| 2988 | |||
| 2989 | Note that, opposite to the construction method of the request message in | ||
| 2990 | the client, in the server the function @code{nothl} and @code{ntohs} | ||
| 2991 | should be employed during the extraction of the data from the message, so | ||
| 2992 | that the data in big endian order can be converted back into little | ||
| 2993 | endian order. See more in detail please refer to Introduction of | ||
| 2994 | Big Endian and Little Endian. | ||
| 2995 | |||
| 2996 | Moreover in this example, the name of the transport stored in the message | ||
| 2997 | is a 0-terminated string, so we should also check whether the name of the | ||
| 2998 | transport in the received message is 0-terminated: | ||
| 2999 | |||
| 3000 | @example | ||
| 3001 | nameTransport = (const char *) &address[addressLen]; | ||
| 3002 | if (nameTransport[size - sizeof | ||
| 3003 | (struct AddressLookupMessage) | ||
| 3004 | - addressLen - 1] != '\0') @{ | ||
| 3005 | GNUNET_break_op (0); | ||
| 3006 | GNUNET_SERVER_receive_done (client, | ||
| 3007 | GNUNET_SYSERR); | ||
| 3008 | return; @} | ||
| 3009 | @end example | ||
| 3010 | |||
| 3011 | Here, @code{GNUNET_SERVER_receive_done} should be called to tell the | ||
| 3012 | service that the request is done and can receive the next message. The | ||
| 3013 | argument @code{GNUNET_SYSERR} here indicates that the service didn't | ||
| 3014 | understand the request message, and the processing of this request would | ||
| 3015 | be terminated. | ||
| 3016 | |||
| 3017 | In comparison to the aforementioned situation, when the argument is equal | ||
| 3018 | to @code{GNUNET_OK}, the service would continue to process the request | ||
| 3019 | message. | ||
| 3020 | |||
| 3021 | @c *********************************************************************** | ||
| 3022 | @node Server - Response to client | ||
| 3023 | @subsubsection Server - Response to client | ||
| 3024 | @c %**end of header | ||
| 3025 | |||
| 3026 | Once the processing of current request is done, the server should give the | ||
| 3027 | response to the client. A new @code{struct AddressLookupMessage} would be | ||
| 3028 | produced by the server in a similar way as the client did and sent to the | ||
| 3029 | client, but here the type should be | ||
| 3030 | @code{GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY} rather than | ||
| 3031 | @code{GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_LOOKUP} in client. | ||
| 3032 | @example | ||
| 3033 | struct AddressLookupMessage *msg; | ||
| 3034 | size_t len = sizeof (struct AddressLookupMessage) | ||
| 3035 | + addressLen | ||
| 3036 | + strlen (nameTrans) + 1; | ||
| 3037 | msg->header->size = htons (len); | ||
| 3038 | msg->header->type = htons | ||
| 3039 | (GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY); | ||
| 3040 | |||
| 3041 | // ... | ||
| 3042 | |||
| 3043 | struct GNUNET_SERVER_TransmitContext *tc; | ||
| 3044 | tc = GNUNET_SERVER_transmit_context_create (client); | ||
| 3045 | GNUNET_SERVER_transmit_context_append_data | ||
| 3046 | (tc, | ||
| 3047 | NULL, | ||
| 3048 | 0, | ||
| 3049 | GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY); | ||
| 3050 | GNUNET_SERVER_transmit_context_run (tc, rtimeout); | ||
| 3051 | @end example | ||
| 3052 | |||
| 3053 | |||
| 3054 | Note that, there are also a number of other APIs provided to the service | ||
| 3055 | to send the message. | ||
| 3056 | |||
| 3057 | @c *********************************************************************** | ||
| 3058 | @node Server - Notification of clients | ||
| 3059 | @subsubsection Server - Notification of clients | ||
| 3060 | @c %**end of header | ||
| 3061 | |||
| 3062 | Often a service needs to (repeatedly) transmit notifications to a client | ||
| 3063 | or a group of clients. In these cases, the client typically has once | ||
| 3064 | registered for a set of events and then needs to receive a message | ||
| 3065 | whenever such an event happens (until the client disconnects). The use of | ||
| 3066 | a notification context can help manage message queues to clients and | ||
| 3067 | handle disconnects. Notification contexts can be used to send | ||
| 3068 | individualized messages to a particular client or to broadcast messages | ||
| 3069 | to a group of clients. An individualized notification might look like | ||
| 3070 | this: | ||
| 3071 | |||
| 3072 | @example | ||
| 3073 | GNUNET_SERVER_notification_context_unicast(nc, | ||
| 3074 | client, | ||
| 3075 | msg, | ||
| 3076 | GNUNET_YES); | ||
| 3077 | @end example | ||
| 3078 | |||
| 3079 | |||
| 3080 | Note that after processing the original registration message for | ||
| 3081 | notifications, the server code still typically needs to call | ||
| 3082 | @code{GNUNET_SERVER_receive_done} so that the client can transmit further | ||
| 3083 | messages to the server. | ||
| 3084 | |||
| 3085 | @c *********************************************************************** | ||
| 3086 | @node Conversion between Network Byte Order (Big Endian) and Host Byte Order | ||
| 3087 | @subsubsection Conversion between Network Byte Order (Big Endian) and Host Byte Order | ||
| 3088 | @c %** subsub? it's a referenced page on the ipc document. | ||
| 3089 | @c %**end of header | ||
| 3090 | |||
| 3091 | Here we can simply comprehend big endian and little endian as Network Byte | ||
| 3092 | Order and Host Byte Order respectively. What is the difference between | ||
| 3093 | both two? | ||
| 3094 | |||
| 3095 | Usually in our host computer we store the data byte as Host Byte Order, | ||
| 3096 | for example, we store a integer in the RAM which might occupies 4 Byte, | ||
| 3097 | as Host Byte Order the higher Byte would be stored at the lower address | ||
| 3098 | of RAM, and the lower Byte would be stored at the higher address of RAM. | ||
| 3099 | However, contrast to this, Network Byte Order just take the totally | ||
| 3100 | opposite way to store the data, says, it will store the lower Byte at the | ||
| 3101 | lower address, and the higher Byte will stay at higher address. | ||
| 3102 | |||
| 3103 | For the current communication of network, we normally exchange the | ||
| 3104 | information by surveying the data package, every two host wants to | ||
| 3105 | communicate with each other must send and receive data package through | ||
| 3106 | network. In order to maintain the identity of data through the | ||
| 3107 | transmission in the network, the order of the Byte storage must changed | ||
| 3108 | before sending and after receiving the data. | ||
| 3109 | |||
| 3110 | There ten convenient functions to realize the conversion of Byte Order in | ||
| 3111 | GNUnet, as following: | ||
| 3112 | |||
| 3113 | @table @asis | ||
| 3114 | |||
| 3115 | @item uint16_t htons(uint16_t hostshort) Convert host byte order to net | ||
| 3116 | byte order with short int | ||
| 3117 | @item uint32_t htonl(uint32_t hostlong) Convert host byte | ||
| 3118 | order to net byte order with long int | ||
| 3119 | @item uint16_t ntohs(uint16_t netshort) | ||
| 3120 | Convert net byte order to host byte order with short int | ||
| 3121 | @item uint32_t | ||
| 3122 | ntohl(uint32_t netlong) Convert net byte order to host byte order with | ||
| 3123 | long int | ||
| 3124 | @item unsigned long long GNUNET_ntohll (unsigned long long netlonglong) | ||
| 3125 | Convert net byte order to host byte order with long long int | ||
| 3126 | @item unsigned long long GNUNET_htonll (unsigned long long hostlonglong) | ||
| 3127 | Convert host byte order to net byte order with long long int | ||
| 3128 | @item struct GNUNET_TIME_RelativeNBO GNUNET_TIME_relative_hton | ||
| 3129 | (struct GNUNET_TIME_Relative a) Convert relative time to network byte | ||
| 3130 | order. | ||
| 3131 | @item struct GNUNET_TIME_Relative GNUNET_TIME_relative_ntoh | ||
| 3132 | (struct GNUNET_TIME_RelativeNBO a) Convert relative time from network | ||
| 3133 | byte order. | ||
| 3134 | @item struct GNUNET_TIME_AbsoluteNBO GNUNET_TIME_absolute_hton | ||
| 3135 | (struct GNUNET_TIME_Absolute a) Convert relative time to network byte | ||
| 3136 | order. | ||
| 3137 | @item struct GNUNET_TIME_Absolute GNUNET_TIME_absolute_ntoh | ||
| 3138 | (struct GNUNET_TIME_AbsoluteNBO a) Convert relative time from network | ||
| 3139 | byte order. | ||
| 3140 | @end table | ||
| 3141 | |||
| 3142 | @cindex Cryptography API | ||
| 3143 | @node Cryptography API | ||
| 3144 | @subsection Cryptography API | ||
| 3145 | @c %**end of header | ||
| 3146 | |||
| 3147 | The gnunetutil APIs provides the cryptographic primitives used in GNUnet. | ||
| 3148 | GNUnet uses 2048 bit RSA keys for the session key exchange and for signing | ||
| 3149 | messages by peers and most other public-key operations. Most researchers | ||
| 3150 | in cryptography consider 2048 bit RSA keys as secure and practically | ||
| 3151 | unbreakable for a long time. The API provides functions to create a fresh | ||
| 3152 | key pair, read a private key from a file (or create a new file if the | ||
| 3153 | file does not exist), encrypt, decrypt, sign, verify and extraction of | ||
| 3154 | the public key into a format suitable for network transmission. | ||
| 3155 | |||
| 3156 | For the encryption of files and the actual data exchanged between peers | ||
| 3157 | GNUnet uses 256-bit AES encryption. Fresh, session keys are negotiated | ||
| 3158 | for every new connection.@ Again, there is no published technique to | ||
| 3159 | break this cipher in any realistic amount of time. The API provides | ||
| 3160 | functions for generation of keys, validation of keys (important for | ||
| 3161 | checking that decryptions using RSA succeeded), encryption and decryption. | ||
| 3162 | |||
| 3163 | GNUnet uses SHA-512 for computing one-way hash codes. The API provides | ||
| 3164 | functions to compute a hash over a block in memory or over a file on disk. | ||
| 3165 | |||
| 3166 | The crypto API also provides functions for randomizing a block of memory, | ||
| 3167 | obtaining a single random number and for generating a permutation of the | ||
| 3168 | numbers 0 to n-1. Random number generation distinguishes between WEAK and | ||
| 3169 | STRONG random number quality; WEAK random numbers are pseudo-random | ||
| 3170 | whereas STRONG random numbers use entropy gathered from the operating | ||
| 3171 | system. | ||
| 3172 | |||
| 3173 | Finally, the crypto API provides a means to deterministically generate a | ||
| 3174 | 1024-bit RSA key from a hash code. These functions should most likely not | ||
| 3175 | be used by most applications; most importantly, | ||
| 3176 | GNUNET_CRYPTO_rsa_key_create_from_hash does not create an RSA-key that | ||
| 3177 | should be considered secure for traditional applications of RSA. | ||
| 3178 | |||
| 3179 | @cindex Message Queue API | ||
| 3180 | @node Message Queue API | ||
| 3181 | @subsection Message Queue API | ||
| 3182 | @c %**end of header | ||
| 3183 | |||
| 3184 | @strong{ Introduction }@ | ||
| 3185 | Often, applications need to queue messages that | ||
| 3186 | are to be sent to other GNUnet peers, clients or services. As all of | ||
| 3187 | GNUnet's message-based communication APIs, by design, do not allow | ||
| 3188 | messages to be queued, it is common to implement custom message queues | ||
| 3189 | manually when they are needed. However, writing very similar code in | ||
| 3190 | multiple places is tedious and leads to code duplication. | ||
| 3191 | |||
| 3192 | MQ (for Message Queue) is an API that provides the functionality to | ||
| 3193 | implement and use message queues. We intend to eventually replace all of | ||
| 3194 | the custom message queue implementations in GNUnet with MQ. | ||
| 3195 | |||
| 3196 | @strong{ Basic Concepts }@ | ||
| 3197 | The two most important entities in MQ are queues and envelopes. | ||
| 3198 | |||
| 3199 | Every queue is backed by a specific implementation (e.g. for mesh, stream, | ||
| 3200 | connection, server client, etc.) that will actually deliver the queued | ||
| 3201 | messages. For convenience,@ some queues also allow to specify a list of | ||
| 3202 | message handlers. The message queue will then also wait for incoming | ||
| 3203 | messages and dispatch them appropriately. | ||
| 3204 | |||
| 3205 | An envelope holds the the memory for a message, as well as metadata | ||
| 3206 | (Where is the envelope queued? What should happen after it has been | ||
| 3207 | sent?). Any envelope can only be queued in one message queue. | ||
| 3208 | |||
| 3209 | @strong{ Creating Queues }@ | ||
| 3210 | The following is a list of currently available message queues. Note that | ||
| 3211 | to avoid layering issues, message queues for higher level APIs are not | ||
| 3212 | part of @code{libgnunetutil}, but@ the respective API itself provides the | ||
| 3213 | queue implementation. | ||
| 3214 | |||
| 3215 | @table @asis | ||
| 3216 | |||
| 3217 | @item @code{GNUNET_MQ_queue_for_connection_client} | ||
| 3218 | Transmits queued messages over a @code{GNUNET_CLIENT_Connection} handle. | ||
| 3219 | Also supports receiving with message handlers. | ||
| 3220 | |||
| 3221 | @item @code{GNUNET_MQ_queue_for_server_client} | ||
| 3222 | Transmits queued messages over a @code{GNUNET_SERVER_Client} handle. Does | ||
| 3223 | not support incoming message handlers. | ||
| 3224 | |||
| 3225 | @item @code{GNUNET_MESH_mq_create} Transmits queued messages over a | ||
| 3226 | @code{GNUNET_MESH_Tunnel} handle. Does not support incoming message | ||
| 3227 | handlers. | ||
| 3228 | |||
| 3229 | @item @code{GNUNET_MQ_queue_for_callbacks} This is the most general | ||
| 3230 | implementation. Instead of delivering and receiving messages with one of | ||
| 3231 | GNUnet's communication APIs, implementation callbacks are called. Refer to | ||
| 3232 | "Implementing Queues" for a more detailed explanation. | ||
| 3233 | @end table | ||
| 3234 | |||
| 3235 | |||
| 3236 | @strong{ Allocating Envelopes }@ | ||
| 3237 | A GNUnet message (as defined by the GNUNET_MessageHeader) has three | ||
| 3238 | parts: The size, the type, and the body. | ||
| 3239 | |||
| 3240 | MQ provides macros to allocate an envelope containing a message | ||
| 3241 | conveniently, automatically setting the size and type fields of the | ||
| 3242 | message. | ||
| 3243 | |||
| 3244 | Consider the following simple message, with the body consisting of a | ||
| 3245 | single number value. | ||
| 3246 | @c why the empty code function? | ||
| 3247 | @code{} | ||
| 3248 | |||
| 3249 | @example | ||
| 3250 | struct NumberMessage @{ | ||
| 3251 | /** Type: GNUNET_MESSAGE_TYPE_EXAMPLE_1 */ | ||
| 3252 | struct GNUNET_MessageHeader header; | ||
| 3253 | uint32_t number GNUNET_PACKED; | ||
| 3254 | @}; | ||
| 3255 | @end example | ||
| 3256 | |||
| 3257 | An envelope containing an instance of the NumberMessage can be | ||
| 3258 | constructed like this: | ||
| 3259 | |||
| 3260 | @example | ||
| 3261 | struct GNUNET_MQ_Envelope *ev; | ||
| 3262 | struct NumberMessage *msg; | ||
| 3263 | ev = GNUNET_MQ_msg (msg, GNUNET_MESSAGE_TYPE_EXAMPLE_1); | ||
| 3264 | msg->number = htonl (42); | ||
| 3265 | @end example | ||
| 3266 | |||
| 3267 | In the above code, @code{GNUNET_MQ_msg} is a macro. The return value is | ||
| 3268 | the newly allocated envelope. The first argument must be a pointer to some | ||
| 3269 | @code{struct} containing a @code{struct GNUNET_MessageHeader header} | ||
| 3270 | field, while the second argument is the desired message type, in host | ||
| 3271 | byte order. | ||
| 3272 | |||
| 3273 | The @code{msg} pointer now points to an allocated message, where the | ||
| 3274 | message type and the message size are already set. The message's size is | ||
| 3275 | inferred from the type of the @code{msg} pointer: It will be set to | ||
| 3276 | 'sizeof(*msg)', properly converted to network byte order. | ||
| 3277 | |||
| 3278 | If the message body's size is dynamic, the the macro | ||
| 3279 | @code{GNUNET_MQ_msg_extra} can be used to allocate an envelope whose | ||
| 3280 | message has additional space allocated after the @code{msg} structure. | ||
| 3281 | |||
| 3282 | If no structure has been defined for the message, | ||
| 3283 | @code{GNUNET_MQ_msg_header_extra} can be used to allocate additional space | ||
| 3284 | after the message header. The first argument then must be a pointer to a | ||
| 3285 | @code{GNUNET_MessageHeader}. | ||
| 3286 | |||
| 3287 | @strong{Envelope Properties}@ | ||
| 3288 | A few functions in MQ allow to set additional properties on envelopes: | ||
| 3289 | |||
| 3290 | @table @asis | ||
| 3291 | |||
| 3292 | @item @code{GNUNET_MQ_notify_sent} Allows to specify a function that will | ||
| 3293 | be called once the envelope's message has been sent irrevocably. | ||
| 3294 | An envelope can be canceled precisely up to the@ point where the notify | ||
| 3295 | sent callback has been called. | ||
| 3296 | |||
| 3297 | @item @code{GNUNET_MQ_disable_corking} No corking will be used when | ||
| 3298 | sending the message. Not every@ queue supports this flag, per default, | ||
| 3299 | envelopes are sent with corking.@ | ||
| 3300 | |||
| 3301 | @end table | ||
| 3302 | |||
| 3303 | |||
| 3304 | @strong{Sending Envelopes}@ | ||
| 3305 | Once an envelope has been constructed, it can be queued for sending with | ||
| 3306 | @code{GNUNET_MQ_send}. | ||
| 3307 | |||
| 3308 | Note that in order to avoid memory leaks, an envelope must either be sent | ||
| 3309 | (the queue will free it) or destroyed explicitly with | ||
| 3310 | @code{GNUNET_MQ_discard}. | ||
| 3311 | |||
| 3312 | @strong{Canceling Envelopes}@ | ||
| 3313 | An envelope queued with @code{GNUNET_MQ_send} can be canceled with | ||
| 3314 | @code{GNUNET_MQ_cancel}. Note that after the notify sent callback has | ||
| 3315 | been called, canceling a message results in undefined behavior. | ||
| 3316 | Thus it is unsafe to cancel an envelope that does not have a notify sent | ||
| 3317 | callback. When canceling an envelope, it is not necessary@ to call | ||
| 3318 | @code{GNUNET_MQ_discard}, and the envelope can't be sent again. | ||
| 3319 | |||
| 3320 | @strong{ Implementing Queues }@ | ||
| 3321 | @code{TODO} | ||
| 3322 | |||
| 3323 | @cindex Service API | ||
| 3324 | @node Service API | ||
| 3325 | @subsection Service API | ||
| 3326 | @c %**end of header | ||
| 3327 | |||
| 3328 | Most GNUnet code lives in the form of services. Services are processes | ||
| 3329 | that offer an API for other components of the system to build on. Those | ||
| 3330 | other components can be command-line tools for users, graphical user | ||
| 3331 | interfaces or other services. Services provide their API using an IPC | ||
| 3332 | protocol. For this, each service must listen on either a TCP port or a | ||
| 3333 | UNIX domain socket; for this, the service implementation uses the server | ||
| 3334 | API. This use of server is exposed directly to the users of the service | ||
| 3335 | API. Thus, when using the service API, one is usually also often using | ||
| 3336 | large parts of the server API. The service API provides various | ||
| 3337 | convenience functions, such as parsing command-line arguments and the | ||
| 3338 | configuration file, which are not found in the server API. | ||
| 3339 | The dual to the service/server API is the client API, which can be used to | ||
| 3340 | access services. | ||
| 3341 | |||
| 3342 | The most common way to start a service is to use the | ||
| 3343 | @code{GNUNET_SERVICE_run} function from the program's main function. | ||
| 3344 | @code{GNUNET_SERVICE_run} will then parse the command line and | ||
| 3345 | configuration files and, based on the options found there, | ||
| 3346 | start the server. It will then give back control to the main | ||
| 3347 | program, passing the server and the configuration to the | ||
| 3348 | @code{GNUNET_SERVICE_Main} callback. @code{GNUNET_SERVICE_run} | ||
| 3349 | will also take care of starting the scheduler loop. | ||
| 3350 | If this is inappropriate (for example, because the scheduler loop | ||
| 3351 | is already running), @code{GNUNET_SERVICE_start} and | ||
| 3352 | related functions provide an alternative to @code{GNUNET_SERVICE_run}. | ||
| 3353 | |||
| 3354 | When starting a service, the service_name option is used to determine | ||
| 3355 | which sections in the configuration file should be used to configure the | ||
| 3356 | service. A typical value here is the name of the @file{src/} | ||
| 3357 | sub-directory, for example @file{statistics}. | ||
| 3358 | The same string would also be given to | ||
| 3359 | @code{GNUNET_CLIENT_connect} to access the service. | ||
| 3360 | |||
| 3361 | Once a service has been initialized, the program should use the | ||
| 3362 | @code{GNUNET_SERVICE_Main} callback to register message handlers | ||
| 3363 | using @code{GNUNET_SERVER_add_handlers}. | ||
| 3364 | The service will already have registered a handler for the | ||
| 3365 | "TEST" message. | ||
| 3366 | |||
| 3367 | @findex GNUNET_SERVICE_Options | ||
| 3368 | The option bitfield (@code{enum GNUNET_SERVICE_Options}) | ||
| 3369 | determines how a service should behave during shutdown. | ||
| 3370 | There are three key strategies: | ||
| 3371 | |||
| 3372 | @table @asis | ||
| 3373 | |||
| 3374 | @item instant (@code{GNUNET_SERVICE_OPTION_NONE}) | ||
| 3375 | Upon receiving the shutdown | ||
| 3376 | signal from the scheduler, the service immediately terminates the server, | ||
| 3377 | closing all existing connections with clients. | ||
| 3378 | @item manual (@code{GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN}) | ||
| 3379 | The service does nothing by itself | ||
| 3380 | during shutdown. The main program will need to take the appropriate | ||
| 3381 | action by calling GNUNET_SERVER_destroy or GNUNET_SERVICE_stop (depending | ||
| 3382 | on how the service was initialized) to terminate the service. This method | ||
| 3383 | is used by gnunet-service-arm and rather uncommon. | ||
| 3384 | @item soft (@code{GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN}) | ||
| 3385 | Upon receiving the shutdown signal from the scheduler, | ||
| 3386 | the service immediately tells the server to stop | ||
| 3387 | listening for incoming clients. Requests from normal existing clients are | ||
| 3388 | still processed and the server/service terminates once all normal clients | ||
| 3389 | have disconnected. Clients that are not expected to ever disconnect (such | ||
| 3390 | as clients that monitor performance values) can be marked as 'monitor' | ||
| 3391 | clients using GNUNET_SERVER_client_mark_monitor. Those clients will | ||
| 3392 | continue to be processed until all 'normal' clients have disconnected. | ||
| 3393 | Then, the server will terminate, closing the monitor connections. | ||
| 3394 | This mode is for example used by 'statistics', allowing existing 'normal' | ||
| 3395 | clients to set (possibly persistent) statistic values before terminating. | ||
| 3396 | |||
| 3397 | @end table | ||
| 3398 | |||
| 3399 | @c *********************************************************************** | ||
| 3400 | @node Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps | ||
| 3401 | @subsection Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps | ||
| 3402 | @c %**end of header | ||
| 3403 | |||
| 3404 | A commonly used data structure in GNUnet is a (multi-)hash map. It is most | ||
| 3405 | often used to map a peer identity to some data structure, but also to map | ||
| 3406 | arbitrary keys to values (for example to track requests in the distributed | ||
| 3407 | hash table or in file-sharing). As it is commonly used, the DHT is | ||
| 3408 | actually sometimes responsible for a large share of GNUnet's overall | ||
| 3409 | memory consumption (for some processes, 30% is not uncommon). The | ||
| 3410 | following text documents some API quirks (and their implications for | ||
| 3411 | applications) that were recently introduced to minimize the footprint of | ||
| 3412 | the hash map. | ||
| 3413 | |||
| 3414 | |||
| 3415 | @c *********************************************************************** | ||
| 3416 | @menu | ||
| 3417 | * Analysis:: | ||
| 3418 | * Solution:: | ||
| 3419 | * Migration:: | ||
| 3420 | * Conclusion:: | ||
| 3421 | * Availability:: | ||
| 3422 | @end menu | ||
| 3423 | |||
| 3424 | @node Analysis | ||
| 3425 | @subsubsection Analysis | ||
| 3426 | @c %**end of header | ||
| 3427 | |||
| 3428 | The main reason for the "excessive" memory consumption by the hash map is | ||
| 3429 | that GNUnet uses 512-bit cryptographic hash codes --- and the | ||
| 3430 | (multi-)hash map also uses the same 512-bit 'struct GNUNET_HashCode'. As | ||
| 3431 | a result, storing just the keys requires 64 bytes of memory for each key. | ||
| 3432 | As some applications like to keep a large number of entries in the hash | ||
| 3433 | map (after all, that's what maps are good for), 64 bytes per hash is | ||
| 3434 | significant: keeping a pointer to the value and having a linked list for | ||
| 3435 | collisions consume between 8 and 16 bytes, and 'malloc' may add about the | ||
| 3436 | same overhead per allocation, putting us in the 16 to 32 byte per entry | ||
| 3437 | ballpark. Adding a 64-byte key then triples the overall memory | ||
| 3438 | requirement for the hash map. | ||
| 3439 | |||
| 3440 | To make things "worse", most of the time storing the key in the hash map | ||
| 3441 | is not required: it is typically already in memory elsewhere! In most | ||
| 3442 | cases, the values stored in the hash map are some application-specific | ||
| 3443 | struct that _also_ contains the hash. Here is a simplified example: | ||
| 3444 | |||
| 3445 | @example | ||
| 3446 | struct MyValue @{ | ||
| 3447 | struct GNUNET_HashCode key; | ||
| 3448 | unsigned int my_data; @}; | ||
| 3449 | |||
| 3450 | // ... | ||
| 3451 | val = GNUNET_malloc (sizeof (struct MyValue)); | ||
| 3452 | val->key = key; | ||
| 3453 | val->my_data = 42; | ||
| 3454 | GNUNET_CONTAINER_multihashmap_put (map, &key, val, ...); | ||
| 3455 | @end example | ||
| 3456 | |||
| 3457 | This is a common pattern as later the entries might need to be removed, | ||
| 3458 | and at that time it is convenient to have the key immediately at hand: | ||
| 3459 | |||
| 3460 | @example | ||
| 3461 | GNUNET_CONTAINER_multihashmap_remove (map, &val->key, val); | ||
| 3462 | @end example | ||
| 3463 | |||
| 3464 | |||
| 3465 | Note that here we end up with two times 64 bytes for the key, plus maybe | ||
| 3466 | 64 bytes total for the rest of the 'struct MyValue' and the map entry in | ||
| 3467 | the hash map. The resulting redundant storage of the key increases | ||
| 3468 | overall memory consumption per entry from the "optimal" 128 bytes to 192 | ||
| 3469 | bytes. This is not just an extreme example: overheads in practice are | ||
| 3470 | actually sometimes close to those highlighted in this example. This is | ||
| 3471 | especially true for maps with a significant number of entries, as there | ||
| 3472 | we tend to really try to keep the entries small. | ||
| 3473 | |||
| 3474 | @c *********************************************************************** | ||
| 3475 | @node Solution | ||
| 3476 | @subsubsection Solution | ||
| 3477 | @c %**end of header | ||
| 3478 | |||
| 3479 | The solution that has now been implemented is to @strong{optionally} | ||
| 3480 | allow the hash map to not make a (deep) copy of the hash but instead have | ||
| 3481 | a pointer to the hash/key in the entry. This reduces the memory | ||
| 3482 | consumption for the key from 64 bytes to 4 to 8 bytes. However, it can | ||
| 3483 | also only work if the key is actually stored in the entry (which is the | ||
| 3484 | case most of the time) and if the entry does not modify the key (which in | ||
| 3485 | all of the code I'm aware of has been always the case if there key is | ||
| 3486 | stored in the entry). Finally, when the client stores an entry in the | ||
| 3487 | hash map, it @strong{must} provide a pointer to the key within the entry, | ||
| 3488 | not just a pointer to a transient location of the key. If | ||
| 3489 | the client code does not meet these requirements, the result is a dangling | ||
| 3490 | pointer and undefined behavior of the (multi-)hash map API. | ||
| 3491 | |||
| 3492 | @c *********************************************************************** | ||
| 3493 | @node Migration | ||
| 3494 | @subsubsection Migration | ||
| 3495 | @c %**end of header | ||
| 3496 | |||
| 3497 | To use the new feature, first check that the values contain the respective | ||
| 3498 | key (and never modify it). Then, all calls to | ||
| 3499 | @code{GNUNET_CONTAINER_multihashmap_put} on the respective map must be | ||
| 3500 | audited and most likely changed to pass a pointer into the value's struct. | ||
| 3501 | For the initial example, the new code would look like this: | ||
| 3502 | |||
| 3503 | @example | ||
| 3504 | struct MyValue @{ | ||
| 3505 | struct GNUNET_HashCode key; | ||
| 3506 | unsigned int my_data; @}; | ||
| 3507 | |||
| 3508 | // ... | ||
| 3509 | val = GNUNET_malloc (sizeof (struct MyValue)); | ||
| 3510 | val->key = key; val->my_data = 42; | ||
| 3511 | GNUNET_CONTAINER_multihashmap_put (map, &val->key, val, ...); | ||
| 3512 | @end example | ||
| 3513 | |||
| 3514 | |||
| 3515 | Note that @code{&val} was changed to @code{&val->key} in the argument to | ||
| 3516 | the @code{put} call. This is critical as often @code{key} is on the stack | ||
| 3517 | or in some other transient data structure and thus having the hash map | ||
| 3518 | keep a pointer to @code{key} would not work. Only the key inside of | ||
| 3519 | @code{val} has the same lifetime as the entry in the map (this must of | ||
| 3520 | course be checked as well). Naturally, @code{val->key} must be | ||
| 3521 | initialized before the @code{put} call. Once all @code{put} calls have | ||
| 3522 | been converted and double-checked, you can change the call to create the | ||
| 3523 | hash map from | ||
| 3524 | |||
| 3525 | @example | ||
| 3526 | map = | ||
| 3527 | GNUNET_CONTAINER_multihashmap_create (SIZE, GNUNET_NO); | ||
| 3528 | @end example | ||
| 3529 | |||
| 3530 | to | ||
| 3531 | |||
| 3532 | @example | ||
| 3533 | map = GNUNET_CONTAINER_multihashmap_create (SIZE, GNUNET_YES); | ||
| 3534 | @end example | ||
| 3535 | |||
| 3536 | If everything was done correctly, you now use about 60 bytes less memory | ||
| 3537 | per entry in @code{map}. However, if now (or in the future) any call to | ||
| 3538 | @code{put} does not ensure that the given key is valid until the entry is | ||
| 3539 | removed from the map, undefined behavior is likely to be observed. | ||
| 3540 | |||
| 3541 | @c *********************************************************************** | ||
| 3542 | @node Conclusion | ||
| 3543 | @subsubsection Conclusion | ||
| 3544 | @c %**end of header | ||
| 3545 | |||
| 3546 | The new optimization can is often applicable and can result in a | ||
| 3547 | reduction in memory consumption of up to 30% in practice. However, it | ||
| 3548 | makes the code less robust as additional invariants are imposed on the | ||
| 3549 | multi hash map client. Thus applications should refrain from enabling the | ||
| 3550 | new mode unless the resulting performance increase is deemed significant | ||
| 3551 | enough. In particular, it should generally not be used in new code (wait | ||
| 3552 | at least until benchmarks exist). | ||
| 3553 | |||
| 3554 | @c *********************************************************************** | ||
| 3555 | @node Availability | ||
| 3556 | @subsubsection Availability | ||
| 3557 | @c %**end of header | ||
| 3558 | |||
| 3559 | The new multi hash map code was committed in SVN 24319 (will be in GNUnet | ||
| 3560 | 0.9.4). Various subsystems (transport, core, dht, file-sharing) were | ||
| 3561 | previously audited and modified to take advantage of the new capability. | ||
| 3562 | In particular, memory consumption of the file-sharing service is expected | ||
| 3563 | to drop by 20-30% due to this change. | ||
| 3564 | |||
| 3565 | |||
| 3566 | @cindex CONTAINER_MDLL API | ||
| 3567 | @node CONTAINER_MDLL API | ||
| 3568 | @subsection CONTAINER_MDLL API | ||
| 3569 | @c %**end of header | ||
| 3570 | |||
| 3571 | This text documents the GNUNET_CONTAINER_MDLL API. The | ||
| 3572 | GNUNET_CONTAINER_MDLL API is similar to the GNUNET_CONTAINER_DLL API in | ||
| 3573 | that it provides operations for the construction and manipulation of | ||
| 3574 | doubly-linked lists. The key difference to the (simpler) DLL-API is that | ||
| 3575 | the MDLL-version allows a single element (instance of a "struct") to be | ||
| 3576 | in multiple linked lists at the same time. | ||
| 3577 | |||
| 3578 | Like the DLL API, the MDLL API stores (most of) the data structures for | ||
| 3579 | the doubly-linked list with the respective elements; only the 'head' and | ||
| 3580 | 'tail' pointers are stored "elsewhere" --- and the application needs to | ||
| 3581 | provide the locations of head and tail to each of the calls in the | ||
| 3582 | MDLL API. The key difference for the MDLL API is that the "next" and | ||
| 3583 | "previous" pointers in the struct can no longer be simply called "next" | ||
| 3584 | and "prev" --- after all, the element may be in multiple doubly-linked | ||
| 3585 | lists, so we cannot just have one "next" and one "prev" pointer! | ||
| 3586 | |||
| 3587 | The solution is to have multiple fields that must have a name of the | ||
| 3588 | format "next_XX" and "prev_XX" where "XX" is the name of one of the | ||
| 3589 | doubly-linked lists. Here is a simple example: | ||
| 3590 | |||
| 3591 | @example | ||
| 3592 | struct MyMultiListElement @{ | ||
| 3593 | struct MyMultiListElement *next_ALIST; | ||
| 3594 | struct MyMultiListElement *prev_ALIST; | ||
| 3595 | struct MyMultiListElement *next_BLIST; | ||
| 3596 | struct MyMultiListElement *prev_BLIST; | ||
| 3597 | void | ||
| 3598 | *data; | ||
| 3599 | @}; | ||
| 3600 | @end example | ||
| 3601 | |||
| 3602 | |||
| 3603 | Note that by convention, we use all-uppercase letters for the list names. | ||
| 3604 | In addition, the program needs to have a location for the head and tail | ||
| 3605 | pointers for both lists, for example: | ||
| 3606 | |||
| 3607 | @example | ||
| 3608 | static struct MyMultiListElement *head_ALIST; | ||
| 3609 | static struct MyMultiListElement *tail_ALIST; | ||
| 3610 | static struct MyMultiListElement *head_BLIST; | ||
| 3611 | static struct MyMultiListElement *tail_BLIST; | ||
| 3612 | @end example | ||
| 3613 | |||
| 3614 | |||
| 3615 | Using the MDLL-macros, we can now insert an element into the ALIST: | ||
| 3616 | |||
| 3617 | @example | ||
| 3618 | GNUNET_CONTAINER_MDLL_insert (ALIST, head_ALIST, tail_ALIST, element); | ||
| 3619 | @end example | ||
| 3620 | |||
| 3621 | |||
| 3622 | Passing "ALIST" as the first argument to MDLL specifies which of the | ||
| 3623 | next/prev fields in the 'struct MyMultiListElement' should be used. The | ||
| 3624 | extra "ALIST" argument and the "_ALIST" in the names of the | ||
| 3625 | next/prev-members are the only differences between the MDDL and DLL-API. | ||
| 3626 | Like the DLL-API, the MDLL-API offers functions for inserting (at head, | ||
| 3627 | at tail, after a given element) and removing elements from the list. | ||
| 3628 | Iterating over the list should be done by directly accessing the | ||
| 3629 | "next_XX" and/or "prev_XX" members. | ||
| 3630 | |||
| 3631 | @cindex Automatic Restart Manager | ||
| 3632 | @cindex ARM | ||
| 3633 | @node Automatic Restart Manager (ARM) | ||
| 3634 | @section Automatic Restart Manager (ARM) | ||
| 3635 | @c %**end of header | ||
| 3636 | |||
| 3637 | GNUnet's Automated Restart Manager (ARM) is the GNUnet service responsible | ||
| 3638 | for system initialization and service babysitting. ARM starts and halts | ||
| 3639 | services, detects configuration changes and restarts services impacted by | ||
| 3640 | the changes as needed. It's also responsible for restarting services in | ||
| 3641 | case of crashes and is planned to incorporate automatic debugging for | ||
| 3642 | diagnosing service crashes providing developers insights about crash | ||
| 3643 | reasons. The purpose of this document is to give GNUnet developer an idea | ||
| 3644 | about how ARM works and how to interact with it. | ||
| 3645 | |||
| 3646 | @menu | ||
| 3647 | * Basic functionality:: | ||
| 3648 | * Key configuration options:: | ||
| 3649 | * ARM - Availability:: | ||
| 3650 | * Reliability:: | ||
| 3651 | @end menu | ||
| 3652 | |||
| 3653 | @c *********************************************************************** | ||
| 3654 | @node Basic functionality | ||
| 3655 | @subsection Basic functionality | ||
| 3656 | @c %**end of header | ||
| 3657 | |||
| 3658 | @itemize @bullet | ||
| 3659 | @item ARM source code can be found under "src/arm".@ Service processes are | ||
| 3660 | managed by the functions in "gnunet-service-arm.c" which is controlled | ||
| 3661 | with "gnunet-arm.c" (main function in that file is ARM's entry point). | ||
| 3662 | |||
| 3663 | @item The functions responsible for communicating with ARM , starting and | ||
| 3664 | stopping services -including ARM service itself- are provided by the | ||
| 3665 | ARM API "arm_api.c".@ Function: GNUNET_ARM_connect() returns to the caller | ||
| 3666 | an ARM handle after setting it to the caller's context (configuration and | ||
| 3667 | scheduler in use). This handle can be used afterwards by the caller to | ||
| 3668 | communicate with ARM. Functions GNUNET_ARM_start_service() and | ||
| 3669 | GNUNET_ARM_stop_service() are used for starting and stopping services | ||
| 3670 | respectively. | ||
| 3671 | |||
| 3672 | @item A typical example of using these basic ARM services can be found in | ||
| 3673 | file test_arm_api.c. The test case connects to ARM, starts it, then uses | ||
| 3674 | it to start a service "resolver", stops the "resolver" then stops "ARM". | ||
| 3675 | @end itemize | ||
| 3676 | |||
| 3677 | @c *********************************************************************** | ||
| 3678 | @node Key configuration options | ||
| 3679 | @subsection Key configuration options | ||
| 3680 | @c %**end of header | ||
| 3681 | |||
| 3682 | Configurations for ARM and services should be available in a .conf file | ||
| 3683 | (As an example, see test_arm_api_data.conf). When running ARM, the | ||
| 3684 | configuration file to use should be passed to the command: | ||
| 3685 | |||
| 3686 | @example | ||
| 3687 | $ gnunet-arm -s -c configuration_to_use.conf | ||
| 3688 | @end example | ||
| 3689 | |||
| 3690 | If no configuration is passed, the default configuration file will be used | ||
| 3691 | (see GNUNET_PREFIX/share/gnunet/defaults.conf which is created from | ||
| 3692 | contrib/defaults.conf).@ Each of the services is having a section starting | ||
| 3693 | by the service name between square brackets, for example: "[arm]". | ||
| 3694 | The following options configure how ARM configures or interacts with the | ||
| 3695 | various services: | ||
| 3696 | |||
| 3697 | @table @asis | ||
| 3698 | |||
| 3699 | @item PORT Port number on which the service is listening for incoming TCP | ||
| 3700 | connections. ARM will start the services should it notice a request at | ||
| 3701 | this port. | ||
| 3702 | |||
| 3703 | @item HOSTNAME Specifies on which host the service is deployed. Note | ||
| 3704 | that ARM can only start services that are running on the local system | ||
| 3705 | (but will not check that the hostname matches the local machine name). | ||
| 3706 | This option is used by the @code{gnunet_client_lib.h} implementation to | ||
| 3707 | determine which system to connect to. The default is "localhost". | ||
| 3708 | |||
| 3709 | @item BINARY The name of the service binary file. | ||
| 3710 | |||
| 3711 | @item OPTIONS To be passed to the service. | ||
| 3712 | |||
| 3713 | @item PREFIX A command to pre-pend to the actual command, for example, | ||
| 3714 | running a service with "valgrind" or "gdb" | ||
| 3715 | |||
| 3716 | @item DEBUG Run in debug mode (much verbosity). | ||
| 3717 | |||
| 3718 | @item START_ON_DEMAND ARM will listen to UNIX domain socket and/or TCP port of | ||
| 3719 | the service and start the service on-demand. | ||
| 3720 | |||
| 3721 | @item IMMEDIATE_START ARM will always start this service when the peer | ||
| 3722 | is started. | ||
| 3723 | |||
| 3724 | @item ACCEPT_FROM IPv4 addresses the service accepts connections from. | ||
| 3725 | |||
| 3726 | @item ACCEPT_FROM6 IPv6 addresses the service accepts connections from. | ||
| 3727 | |||
| 3728 | @end table | ||
| 3729 | |||
| 3730 | |||
| 3731 | Options that impact the operation of ARM overall are in the "[arm]" | ||
| 3732 | section. ARM is a normal service and has (except for START_ON_DEMAND) all of the | ||
| 3733 | options that other services do. In addition, ARM has the | ||
| 3734 | following options: | ||
| 3735 | |||
| 3736 | @table @asis | ||
| 3737 | |||
| 3738 | @item GLOBAL_PREFIX Command to be pre-pended to all services that are | ||
| 3739 | going to run. | ||
| 3740 | |||
| 3741 | @item GLOBAL_POSTFIX Global option that will be supplied to all the | ||
| 3742 | services that are going to run. | ||
| 3743 | |||
| 3744 | @end table | ||
| 3745 | |||
| 3746 | @c *********************************************************************** | ||
| 3747 | @node ARM - Availability | ||
| 3748 | @subsection ARM - Availability | ||
| 3749 | @c %**end of header | ||
| 3750 | |||
| 3751 | As mentioned before, one of the features provided by ARM is starting | ||
| 3752 | services on demand. Consider the example of one service "client" that | ||
| 3753 | wants to connect to another service a "server". The "client" will ask ARM | ||
| 3754 | to run the "server". ARM starts the "server". The "server" starts | ||
| 3755 | listening to incoming connections. The "client" will establish a | ||
| 3756 | connection with the "server". And then, they will start to communicate | ||
| 3757 | together.@ One problem with that scheme is that it's slow!@ | ||
| 3758 | The "client" service wants to communicate with the "server" service at | ||
| 3759 | once and is not willing wait for it to be started and listening to | ||
| 3760 | incoming connections before serving its request.@ One solution for that | ||
| 3761 | problem will be that ARM starts all services as default services. That | ||
| 3762 | solution will solve the problem, yet, it's not quite practical, for some | ||
| 3763 | services that are going to be started can never be used or are going to | ||
| 3764 | be used after a relatively long time.@ | ||
| 3765 | The approach followed by ARM to solve this problem is as follows: | ||
| 3766 | |||
| 3767 | @itemize @bullet | ||
| 3768 | |||
| 3769 | @item For each service having a PORT field in the configuration file and | ||
| 3770 | that is not one of the default services ( a service that accepts incoming | ||
| 3771 | connections from clients), ARM creates listening sockets for all addresses | ||
| 3772 | associated with that service. | ||
| 3773 | |||
| 3774 | @item The "client" will immediately establish a connection with | ||
| 3775 | the "server". | ||
| 3776 | |||
| 3777 | @item ARM --- pretending to be the "server" --- will listen on the | ||
| 3778 | respective port and notice the incoming connection from the "client" | ||
| 3779 | (but not accept it), instead | ||
| 3780 | |||
| 3781 | @item Once there is an incoming connection, ARM will start the "server", | ||
| 3782 | passing on the listen sockets (now, the service is started and can do its | ||
| 3783 | work). | ||
| 3784 | |||
| 3785 | @item Other client services now can directly connect directly to the | ||
| 3786 | "server". | ||
| 3787 | |||
| 3788 | @end itemize | ||
| 3789 | |||
| 3790 | @c *********************************************************************** | ||
| 3791 | @node Reliability | ||
| 3792 | @subsection Reliability | ||
| 3793 | |||
| 3794 | One of the features provided by ARM, is the automatic restart of crashed | ||
| 3795 | services.@ ARM needs to know which of the running services died. Function | ||
| 3796 | "gnunet-service-arm.c/maint_child_death()" is responsible for that. The | ||
| 3797 | function is scheduled to run upon receiving a SIGCHLD signal. The | ||
| 3798 | function, then, iterates ARM's list of services running and monitors | ||
| 3799 | which service has died (crashed). For all crashing services, ARM restarts | ||
| 3800 | them.@ | ||
| 3801 | Now, considering the case of a service having a serious problem causing it | ||
| 3802 | to crash each time it's started by ARM. If ARM keeps blindly restarting | ||
| 3803 | such a service, we are going to have the pattern: | ||
| 3804 | start-crash-restart-crash-restart-crash and so forth!! Which is of course | ||
| 3805 | not practical.@ | ||
| 3806 | For that reason, ARM schedules the service to be restarted after waiting | ||
| 3807 | for some delay that grows exponentially with each crash/restart of that | ||
| 3808 | service.@ To clarify the idea, considering the following example: | ||
| 3809 | |||
| 3810 | @itemize @bullet | ||
| 3811 | |||
| 3812 | @item Service S crashed. | ||
| 3813 | |||
| 3814 | @item ARM receives the SIGCHLD and inspects its list of services to find | ||
| 3815 | the dead one(s). | ||
| 3816 | |||
| 3817 | @item ARM finds S dead and schedules it for restarting after "backoff" | ||
| 3818 | time which is initially set to 1ms. ARM will double the backoff time | ||
| 3819 | correspondent to S (now backoff(S) = 2ms) | ||
| 3820 | |||
| 3821 | @item Because there is a severe problem with S, it crashed again. | ||
| 3822 | |||
| 3823 | @item Again ARM receives the SIGCHLD and detects that it's S again that's | ||
| 3824 | crashed. ARM schedules it for restarting but after its new backoff time | ||
| 3825 | (which became 2ms), and doubles its backoff time (now backoff(S) = 4). | ||
| 3826 | |||
| 3827 | @item and so on, until backoff(S) reaches a certain threshold | ||
| 3828 | (@code{EXPONENTIAL_BACKOFF_THRESHOLD} is set to half an hour), | ||
| 3829 | after reaching it, backoff(S) will remain half an hour, | ||
| 3830 | hence ARM won't be busy for a lot of time trying to restart a | ||
| 3831 | problematic service. | ||
| 3832 | @end itemize | ||
| 3833 | |||
| 3834 | @cindex TRANSPORT Subsystem | ||
| 3835 | @node TRANSPORT Subsystem | ||
| 3836 | @section TRANSPORT Subsystem | ||
| 3837 | @c %**end of header | ||
| 3838 | |||
| 3839 | This chapter documents how the GNUnet transport subsystem works. The | ||
| 3840 | GNUnet transport subsystem consists of three main components: the | ||
| 3841 | transport API (the interface used by the rest of the system to access the | ||
| 3842 | transport service), the transport service itself (most of the interesting | ||
| 3843 | functions, such as choosing transports, happens here) and the transport | ||
| 3844 | plugins. A transport plugin is a concrete implementation for how two | ||
| 3845 | GNUnet peers communicate; many plugins exist, for example for | ||
| 3846 | communication via TCP, UDP, HTTP, HTTPS and others. Finally, the | ||
| 3847 | transport subsystem uses supporting code, especially the NAT/UPnP | ||
| 3848 | library to help with tasks such as NAT traversal. | ||
| 3849 | |||
| 3850 | Key tasks of the transport service include: | ||
| 3851 | |||
| 3852 | @itemize @bullet | ||
| 3853 | |||
| 3854 | @item Create our HELLO message, notify clients and neighbours if our HELLO | ||
| 3855 | changes (using NAT library as necessary) | ||
| 3856 | |||
| 3857 | @item Validate HELLOs from other peers (send PING), allow other peers to | ||
| 3858 | validate our HELLO's addresses (send PONG) | ||
| 3859 | |||
| 3860 | @item Upon request, establish connections to other peers (using address | ||
| 3861 | selection from ATS subsystem) and maintain them (again using PINGs and | ||
| 3862 | PONGs) as long as desired | ||
| 3863 | |||
| 3864 | @item Accept incoming connections, give ATS service the opportunity to | ||
| 3865 | switch communication channels | ||
| 3866 | |||
| 3867 | @item Notify clients about peers that have connected to us or that have | ||
| 3868 | been disconnected from us | ||
| 3869 | |||
| 3870 | @item If a (stateful) connection goes down unexpectedly (without explicit | ||
| 3871 | DISCONNECT), quickly attempt to recover (without notifying clients) but do | ||
| 3872 | notify clients quickly if reconnecting fails | ||
| 3873 | |||
| 3874 | @item Send (payload) messages arriving from clients to other peers via | ||
| 3875 | transport plugins and receive messages from other peers, forwarding | ||
| 3876 | those to clients | ||
| 3877 | |||
| 3878 | @item Enforce inbound traffic limits (using flow-control if it is | ||
| 3879 | applicable); outbound traffic limits are enforced by CORE, not by us (!) | ||
| 3880 | |||
| 3881 | @item Enforce restrictions on P2P connection as specified by the blacklist | ||
| 3882 | configuration and blacklisting clients | ||
| 3883 | @end itemize | ||
| 3884 | |||
| 3885 | Note that the term "clients" in the list above really refers to the | ||
| 3886 | GNUnet-CORE service, as CORE is typically the only client of the | ||
| 3887 | transport service. | ||
| 3888 | |||
| 3889 | @menu | ||
| 3890 | * Address validation protocol:: | ||
| 3891 | @end menu | ||
| 3892 | |||
| 3893 | @node Address validation protocol | ||
| 3894 | @subsection Address validation protocol | ||
| 3895 | @c %**end of header | ||
| 3896 | |||
| 3897 | This section documents how the GNUnet transport service validates | ||
| 3898 | connections with other peers. It is a high-level description of the | ||
| 3899 | protocol necessary to understand the details of the implementation. It | ||
| 3900 | should be noted that when we talk about PING and PONG messages in this | ||
| 3901 | section, we refer to transport-level PING and PONG messages, which are | ||
| 3902 | different from core-level PING and PONG messages (both in implementation | ||
| 3903 | and function). | ||
| 3904 | |||
| 3905 | The goal of transport-level address validation is to minimize the chances | ||
| 3906 | of a successful man-in-the-middle attack against GNUnet peers on the | ||
| 3907 | transport level. Such an attack would not allow the adversary to decrypt | ||
| 3908 | the P2P transmissions, but a successful attacker could at least measure | ||
| 3909 | traffic volumes and latencies (raising the adversaries capabilities by | ||
| 3910 | those of a global passive adversary in the worst case). The scenarios we | ||
| 3911 | are concerned about is an attacker, Mallory, giving a @code{HELLO} to | ||
| 3912 | Alice that claims to be for Bob, but contains Mallory's IP address | ||
| 3913 | instead of Bobs (for some transport). | ||
| 3914 | Mallory would then forward the traffic to Bob (by initiating a | ||
| 3915 | connection to Bob and claiming to be Alice). As a further | ||
| 3916 | complication, the scheme has to work even if say Alice is behind a NAT | ||
| 3917 | without traversal support and hence has no address of her own (and thus | ||
| 3918 | Alice must always initiate the connection to Bob). | ||
| 3919 | |||
| 3920 | An additional constraint is that @code{HELLO} messages do not contain a | ||
| 3921 | cryptographic signature since other peers must be able to edit | ||
| 3922 | (i.e. remove) addresses from the @code{HELLO} at any time (this was | ||
| 3923 | not true in GNUnet 0.8.x). A basic @strong{assumption} is that each peer | ||
| 3924 | knows the set of possible network addresses that it @strong{might} | ||
| 3925 | be reachable under (so for example, the external IP address of the | ||
| 3926 | NAT plus the LAN address(es) with the respective ports). | ||
| 3927 | |||
| 3928 | The solution is the following. If Alice wants to validate that a given | ||
| 3929 | address for Bob is valid (i.e. is actually established @strong{directly} | ||
| 3930 | with the intended target), she sends a PING message over that connection | ||
| 3931 | to Bob. Note that in this case, Alice initiated the connection so only | ||
| 3932 | Alice knows which address was used for sure (Alice may be behind NAT, so | ||
| 3933 | whatever address Bob sees may not be an address Alice knows she has). | ||
| 3934 | Bob checks that the address given in the @code{PING} is actually one | ||
| 3935 | of Bob's addresses (ie: does not belong to Mallory), and if it is, | ||
| 3936 | sends back a @code{PONG} (with a signature that says that Bob | ||
| 3937 | owns/uses the address from the @code{PING}). | ||
| 3938 | Alice checks the signature and is happy if it is valid and the address | ||
| 3939 | in the @code{PONG} is the address Alice used. | ||
| 3940 | This is similar to the 0.8.x protocol where the @code{HELLO} contained a | ||
| 3941 | signature from Bob for each address used by Bob. | ||
| 3942 | Here, the purpose code for the signature is | ||
| 3943 | @code{GNUNET_SIGNATURE_PURPOSE_TRANSPORT_PONG_OWN}. After this, Alice will | ||
| 3944 | remember Bob's address and consider the address valid for a while (12h in | ||
| 3945 | the current implementation). Note that after this exchange, Alice only | ||
| 3946 | considers Bob's address to be valid, the connection itself is not | ||
| 3947 | considered 'established'. In particular, Alice may have many addresses | ||
| 3948 | for Bob that Alice considers valid. | ||
| 3949 | |||
| 3950 | The @code{PONG} message is protected with a nonce/challenge against replay | ||
| 3951 | attacks (@uref{http://en.wikipedia.org/wiki/Replay_attack, replay}) | ||
| 3952 | and uses an expiration time for the signature (but those are almost | ||
| 3953 | implementation details). | ||
| 3954 | |||
| 3955 | @cindex NAT library | ||
| 3956 | @node NAT library | ||
| 3957 | @section NAT library | ||
| 3958 | @c %**end of header | ||
| 3959 | |||
| 3960 | The goal of the GNUnet NAT library is to provide a general-purpose API for | ||
| 3961 | NAT traversal @strong{without} third-party support. So protocols that | ||
| 3962 | involve contacting a third peer to help establish a connection between | ||
| 3963 | two peers are outside of the scope of this API. That does not mean that | ||
| 3964 | GNUnet doesn't support involving a third peer (we can do this with the | ||
| 3965 | distance-vector transport or using application-level protocols), it just | ||
| 3966 | means that the NAT API is not concerned with this possibility. The API is | ||
| 3967 | written so that it will work for IPv6-NAT in the future as well as | ||
| 3968 | current IPv4-NAT. Furthermore, the NAT API is always used, even for peers | ||
| 3969 | that are not behind NAT --- in that case, the mapping provided is simply | ||
| 3970 | the identity. | ||
| 3971 | |||
| 3972 | NAT traversal is initiated by calling @code{GNUNET_NAT_register}. Given a | ||
| 3973 | set of addresses that the peer has locally bound to (TCP or UDP), the NAT | ||
| 3974 | library will return (via callback) a (possibly longer) list of addresses | ||
| 3975 | the peer @strong{might} be reachable under. Internally, depending on the | ||
| 3976 | configuration, the NAT library will try to punch a hole (using UPnP) or | ||
| 3977 | just "know" that the NAT was manually punched and generate the respective | ||
| 3978 | external IP address (the one that should be globally visible) based on | ||
| 3979 | the given information. | ||
| 3980 | |||
| 3981 | The NAT library also supports ICMP-based NAT traversal. Here, the other | ||
| 3982 | peer can request connection-reversal by this peer (in this special case, | ||
| 3983 | the peer is even allowed to configure a port number of zero). If the NAT | ||
| 3984 | library detects a connection-reversal request, it returns the respective | ||
| 3985 | target address to the client as well. It should be noted that | ||
| 3986 | connection-reversal is currently only intended for TCP, so other plugins | ||
| 3987 | @strong{must} pass @code{NULL} for the reversal callback. Naturally, the | ||
| 3988 | NAT library also supports requesting connection reversal from a remote | ||
| 3989 | peer (@code{GNUNET_NAT_run_client}). | ||
| 3990 | |||
| 3991 | Once initialized, the NAT handle can be used to test if a given address is | ||
| 3992 | possibly a valid address for this peer (@code{GNUNET_NAT_test_address}). | ||
| 3993 | This is used for validating our addresses when generating PONGs. | ||
| 3994 | |||
| 3995 | Finally, the NAT library contains an API to test if our NAT configuration | ||
| 3996 | is correct. Using @code{GNUNET_NAT_test_start} @strong{before} binding to | ||
| 3997 | the respective port, the NAT library can be used to test if the | ||
| 3998 | configuration works. The test function act as a local client, initialize | ||
| 3999 | the NAT traversal and then contact a @code{gnunet-nat-server} (running by | ||
| 4000 | default on @code{gnunet.org}) and ask for a connection to be established. | ||
| 4001 | This way, it is easy to test if the current NAT configuration is valid. | ||
| 4002 | |||
| 4003 | @node Distance-Vector plugin | ||
| 4004 | @section Distance-Vector plugin | ||
| 4005 | @c %**end of header | ||
| 4006 | |||
| 4007 | The Distance Vector (DV) transport is a transport mechanism that allows | ||
| 4008 | peers to act as relays for each other, thereby connecting peers that would | ||
| 4009 | otherwise be unable to connect. This gives a larger connection set to | ||
| 4010 | applications that may work better with more peers to choose from (for | ||
| 4011 | example, File Sharing and/or DHT). | ||
| 4012 | |||
| 4013 | The Distance Vector transport essentially has two functions. The first is | ||
| 4014 | "gossiping" connection information about more distant peers to directly | ||
| 4015 | connected peers. The second is taking messages intended for non-directly | ||
| 4016 | connected peers and encapsulating them in a DV wrapper that contains the | ||
| 4017 | required information for routing the message through forwarding peers. Via | ||
| 4018 | gossiping, optimal routes through the known DV neighborhood are discovered | ||
| 4019 | and utilized and the message encapsulation provides some benefits in | ||
| 4020 | addition to simply getting the message from the correct source to the | ||
| 4021 | proper destination. | ||
| 4022 | |||
| 4023 | The gossiping function of DV provides an up to date routing table of | ||
| 4024 | peers that are available up to some number of hops. We call this a | ||
| 4025 | fisheye view of the network (like a fish, nearby objects are known while | ||
| 4026 | more distant ones unknown). Gossip messages are sent only to directly | ||
| 4027 | connected peers, but they are sent about other knowns peers within the | ||
| 4028 | "fisheye distance". Whenever two peers connect, they immediately gossip | ||
| 4029 | to each other about their appropriate other neighbors. They also gossip | ||
| 4030 | about the newly connected peer to previously | ||
| 4031 | connected neighbors. In order to keep the routing tables up to date, | ||
| 4032 | disconnect notifications are propagated as gossip as well (because | ||
| 4033 | disconnects may not be sent/received, timeouts are also used remove | ||
| 4034 | stagnant routing table entries). | ||
| 4035 | |||
| 4036 | Routing of messages via DV is straightforward. When the DV transport is | ||
| 4037 | notified of a message destined for a non-direct neighbor, the appropriate | ||
| 4038 | forwarding peer is selected, and the base message is encapsulated in a DV | ||
| 4039 | message which contains information about the initial peer and the intended | ||
| 4040 | recipient. At each forwarding hop, the initial peer is validated (the | ||
| 4041 | forwarding peer ensures that it has the initial peer in its neighborhood, | ||
| 4042 | otherwise the message is dropped). Next the base message is | ||
| 4043 | re-encapsulated in a new DV message for the next hop in the forwarding | ||
| 4044 | chain (or delivered to the current peer, if it has arrived at the | ||
| 4045 | destination). | ||
| 4046 | |||
| 4047 | Assume a three peer network with peers Alice, Bob and Carol. Assume that | ||
| 4048 | |||
| 4049 | @example | ||
| 4050 | Alice <-> Bob and Bob <-> Carol | ||
| 4051 | @end example | ||
| 4052 | |||
| 4053 | @noindent | ||
| 4054 | are direct (e.g. over TCP or UDP transports) connections, but that | ||
| 4055 | Alice cannot directly connect to Carol. | ||
| 4056 | This may be the case due to NAT or firewall restrictions, or perhaps | ||
| 4057 | based on one of the peers respective configurations. If the Distance | ||
| 4058 | Vector transport is enabled on all three peers, it will automatically | ||
| 4059 | discover (from the gossip protocol) that Alice and Carol can connect via | ||
| 4060 | Bob and provide a "virtual" Alice <-> Carol connection. Routing between | ||
| 4061 | Alice and Carol happens as follows; Alice creates a message destined for | ||
| 4062 | Carol and notifies the DV transport about it. The DV transport at Alice | ||
| 4063 | looks up Carol in the routing table and finds that the message must be | ||
| 4064 | sent through Bob for Carol. The message is encapsulated setting Alice as | ||
| 4065 | the initiator and Carol as the destination and sent to Bob. Bob receives | ||
| 4066 | the messages, verifies that both Alice and Carol are known to Bob, and | ||
| 4067 | re-wraps the message in a new DV message for Carol. | ||
| 4068 | The DV transport at Carol receives this message, unwraps the original | ||
| 4069 | message, and delivers it to Carol as though it came directly from Alice. | ||
| 4070 | |||
| 4071 | @cindex SMTP plugin | ||
| 4072 | @node SMTP plugin | ||
| 4073 | @section SMTP plugin | ||
| 4074 | @c %**end of header | ||
| 4075 | |||
| 4076 | This section describes the new SMTP transport plugin for GNUnet as it | ||
| 4077 | exists in the 0.7.x and 0.8.x branch. SMTP support is currently not | ||
| 4078 | available in GNUnet 0.9.x. This page also describes the transport layer | ||
| 4079 | abstraction (as it existed in 0.7.x and 0.8.x) in more detail and gives | ||
| 4080 | some benchmarking results. The performance results presented are quite | ||
| 4081 | old and maybe outdated at this point. | ||
| 4082 | |||
| 4083 | @itemize @bullet | ||
| 4084 | @item Why use SMTP for a peer-to-peer transport? | ||
| 4085 | @item SMTPHow does it work? | ||
| 4086 | @item How do I configure my peer? | ||
| 4087 | @item How do I test if it works? | ||
| 4088 | @item How fast is it? | ||
| 4089 | @item Is there any additional documentation? | ||
| 4090 | @end itemize | ||
| 4091 | |||
| 4092 | |||
| 4093 | @menu | ||
| 4094 | * Why use SMTP for a peer-to-peer transport?:: | ||
| 4095 | * How does it work?:: | ||
| 4096 | * How do I configure my peer?:: | ||
| 4097 | * How do I test if it works?:: | ||
| 4098 | * How fast is it?:: | ||
| 4099 | @end menu | ||
| 4100 | |||
| 4101 | @node Why use SMTP for a peer-to-peer transport? | ||
| 4102 | @subsection Why use SMTP for a peer-to-peer transport? | ||
| 4103 | @c %**end of header | ||
| 4104 | |||
| 4105 | There are many reasons why one would not want to use SMTP: | ||
| 4106 | |||
| 4107 | @itemize @bullet | ||
| 4108 | @item SMTP is using more bandwidth than TCP, UDP or HTTP | ||
| 4109 | @item SMTP has a much higher latency. | ||
| 4110 | @item SMTP requires significantly more computation (encoding and decoding | ||
| 4111 | time) for the peers. | ||
| 4112 | @item SMTP is significantly more complicated to configure. | ||
| 4113 | @item SMTP may be abused by tricking GNUnet into sending mail to@ | ||
| 4114 | non-participating third parties. | ||
| 4115 | @end itemize | ||
| 4116 | |||
| 4117 | So why would anybody want to use SMTP? | ||
| 4118 | @itemize @bullet | ||
| 4119 | @item SMTP can be used to contact peers behind NAT boxes (in virtual | ||
| 4120 | private networks). | ||
| 4121 | @item SMTP can be used to circumvent policies that limit or prohibit | ||
| 4122 | peer-to-peer traffic by masking as "legitimate" traffic. | ||
| 4123 | @item SMTP uses E-mail addresses which are independent of a specific IP, | ||
| 4124 | which can be useful to address peers that use dynamic IP addresses. | ||
| 4125 | @item SMTP can be used to initiate a connection (e.g. initial address | ||
| 4126 | exchange) and peers can then negotiate the use of a more efficient | ||
| 4127 | protocol (e.g. TCP) for the actual communication. | ||
| 4128 | @end itemize | ||
| 4129 | |||
| 4130 | In summary, SMTP can for example be used to send a message to a peer | ||
| 4131 | behind a NAT box that has a dynamic IP to tell the peer to establish a | ||
| 4132 | TCP connection to a peer outside of the private network. Even an | ||
| 4133 | extraordinary overhead for this first message would be irrelevant in this | ||
| 4134 | type of situation. | ||
| 4135 | |||
| 4136 | @node How does it work? | ||
| 4137 | @subsection How does it work? | ||
| 4138 | @c %**end of header | ||
| 4139 | |||
| 4140 | When a GNUnet peer needs to send a message to another GNUnet peer that has | ||
| 4141 | advertised (only) an SMTP transport address, GNUnet base64-encodes the | ||
| 4142 | message and sends it in an E-mail to the advertised address. The | ||
| 4143 | advertisement contains a filter which is placed in the E-mail header, | ||
| 4144 | such that the receiving host can filter the tagged E-mails and forward it | ||
| 4145 | to the GNUnet peer process. The filter can be specified individually by | ||
| 4146 | each peer and be changed over time. This makes it impossible to censor | ||
| 4147 | GNUnet E-mail messages by searching for a generic filter. | ||
| 4148 | |||
| 4149 | @node How do I configure my peer? | ||
| 4150 | @subsection How do I configure my peer? | ||
| 4151 | @c %**end of header | ||
| 4152 | |||
| 4153 | First, you need to configure @code{procmail} to filter your inbound E-mail | ||
| 4154 | for GNUnet traffic. The GNUnet messages must be delivered into a pipe, for | ||
| 4155 | example @code{/tmp/gnunet.smtp}. You also need to define a filter that is | ||
| 4156 | used by @command{procmail} to detect GNUnet messages. You are free to | ||
| 4157 | choose whichever filter you like, but you should make sure that it does | ||
| 4158 | not occur in your other E-mail. In our example, we will use | ||
| 4159 | @code{X-mailer: GNUnet}. The @code{~/.procmailrc} configuration file then | ||
| 4160 | looks like this: | ||
| 4161 | |||
| 4162 | @example | ||
| 4163 | :0: | ||
| 4164 | * ^X-mailer: GNUnet | ||
| 4165 | /tmp/gnunet.smtp | ||
| 4166 | # where do you want your other e-mail delivered to | ||
| 4167 | # (default: /var/spool/mail/) | ||
| 4168 | :0: /var/spool/mail/ | ||
| 4169 | @end example | ||
| 4170 | |||
| 4171 | After adding this file, first make sure that your regular E-mail still | ||
| 4172 | works (e.g. by sending an E-mail to yourself). Then edit the GNUnet | ||
| 4173 | configuration. In the section @code{SMTP} you need to specify your E-mail | ||
| 4174 | address under @code{EMAIL}, your mail server (for outgoing mail) under | ||
| 4175 | @code{SERVER}, the filter (X-mailer: GNUnet in the example) under | ||
| 4176 | @code{FILTER} and the name of the pipe under @code{PIPE}.@ The completed | ||
| 4177 | section could then look like this: | ||
| 4178 | |||
| 4179 | @example | ||
| 4180 | EMAIL = me@@mail.gnu.org MTU = 65000 SERVER = mail.gnu.org:25 FILTER = | ||
| 4181 | "X-mailer: GNUnet" PIPE = /tmp/gnunet.smtp | ||
| 4182 | @end example | ||
| 4183 | |||
| 4184 | Finally, you need to add @code{smtp} to the list of @code{TRANSPORTS} in | ||
| 4185 | the @code{GNUNETD} section. GNUnet peers will use the E-mail address that | ||
| 4186 | you specified to contact your peer until the advertisement times out. | ||
| 4187 | Thus, if you are not sure if everything works properly or if you are not | ||
| 4188 | planning to be online for a long time, you may want to configure this | ||
| 4189 | timeout to be short, e.g. just one hour. For this, set | ||
| 4190 | @code{HELLOEXPIRES} to @code{1} in the @code{GNUNETD} section. | ||
| 4191 | |||
| 4192 | This should be it, but you may probably want to test it first. | ||
| 4193 | |||
| 4194 | @node How do I test if it works? | ||
| 4195 | @subsection How do I test if it works? | ||
| 4196 | @c %**end of header | ||
| 4197 | |||
| 4198 | Any transport can be subjected to some rudimentary tests using the | ||
| 4199 | @code{gnunet-transport-check} tool. The tool sends a message to the local | ||
| 4200 | node via the transport and checks that a valid message is received. While | ||
| 4201 | this test does not involve other peers and can not check if firewalls or | ||
| 4202 | other network obstacles prohibit proper operation, this is a great | ||
| 4203 | testcase for the SMTP transport since it tests pretty much nearly all of | ||
| 4204 | the functionality. | ||
| 4205 | |||
| 4206 | @code{gnunet-transport-check} should only be used without running | ||
| 4207 | @code{gnunetd} at the same time. By default, @code{gnunet-transport-check} | ||
| 4208 | tests all transports that are specified in the configuration file. But | ||
| 4209 | you can specifically test SMTP by giving the option | ||
| 4210 | @code{--transport=smtp}. | ||
| 4211 | |||
| 4212 | Note that this test always checks if a transport can receive and send. | ||
| 4213 | While you can configure most transports to only receive or only send | ||
| 4214 | messages, this test will only work if you have configured the transport | ||
| 4215 | to send and receive messages. | ||
| 4216 | |||
| 4217 | @node How fast is it? | ||
| 4218 | @subsection How fast is it? | ||
| 4219 | @c %**end of header | ||
| 4220 | |||
| 4221 | We have measured the performance of the UDP, TCP and SMTP transport layer | ||
| 4222 | directly and when used from an application using the GNUnet core. | ||
| 4223 | Measuring just the transport layer gives the better view of the actual | ||
| 4224 | overhead of the protocol, whereas evaluating the transport from the | ||
| 4225 | application puts the overhead into perspective from a practical point of | ||
| 4226 | view. | ||
| 4227 | |||
| 4228 | The loopback measurements of the SMTP transport were performed on three | ||
| 4229 | different machines spanning a range of modern SMTP configurations. We | ||
| 4230 | used a PIII-800 running RedHat 7.3 with the Purdue Computer Science | ||
| 4231 | configuration which includes filters for spam. We also used a Xenon 2 GHZ | ||
| 4232 | with a vanilla RedHat 8.0 sendmail configuration. Furthermore, we used | ||
| 4233 | qmail on a PIII-1000 running Sorcerer GNU Linux (SGL). The numbers for | ||
| 4234 | UDP and TCP are provided using the SGL configuration. The qmail benchmark | ||
| 4235 | uses qmail's internal filtering whereas the sendmail benchmarks relies on | ||
| 4236 | procmail to filter and deliver the mail. We used the transport layer to | ||
| 4237 | send a message of b bytes (excluding transport protocol headers) directly | ||
| 4238 | to the local machine. This way, network latency and packet loss on the | ||
| 4239 | wire have no impact on the timings. n messages were sent sequentially over | ||
| 4240 | the transport layer, sending message i+1 after the i-th message was | ||
| 4241 | received. All messages were sent over the same connection and the time to | ||
| 4242 | establish the connection was not taken into account since this overhead is | ||
| 4243 | minuscule in practice --- as long as a connection is used for a | ||
| 4244 | significant number of messages. | ||
| 4245 | |||
| 4246 | @multitable @columnfractions .20 .15 .15 .15 .15 .15 | ||
| 4247 | @headitem Transport @tab UDP @tab TCP @tab SMTP (Purdue sendmail) | ||
| 4248 | @tab SMTP (RH 8.0) @tab SMTP (SGL qmail) | ||
| 4249 | @item 11 bytes @tab 31 ms @tab 55 ms @tab 781 s @tab 77 s @tab 24 s | ||
| 4250 | @item 407 bytes @tab 37 ms @tab 62 ms @tab 789 s @tab 78 s @tab 25 s | ||
| 4251 | @item 1,221 bytes @tab 46 ms @tab 73 ms @tab 804 s @tab 78 s @tab 25 s | ||
| 4252 | @end multitable | ||
| 4253 | |||
| 4254 | The benchmarks show that UDP and TCP are, as expected, both significantly | ||
| 4255 | faster compared with any of the SMTP services. Among the SMTP | ||
| 4256 | implementations, there can be significant differences depending on the | ||
| 4257 | SMTP configuration. Filtering with an external tool like procmail that | ||
| 4258 | needs to re-parse its configuration for each mail can be very expensive. | ||
| 4259 | Applying spam filters can also significantly impact the performance of | ||
| 4260 | the underlying SMTP implementation. The microbenchmark shows that SMTP | ||
| 4261 | can be a viable solution for initiating peer-to-peer sessions: a couple of | ||
| 4262 | seconds to connect to a peer are probably not even going to be noticed by | ||
| 4263 | users. The next benchmark measures the possible throughput for a | ||
| 4264 | transport. Throughput can be measured by sending multiple messages in | ||
| 4265 | parallel and measuring packet loss. Note that not only UDP but also the | ||
| 4266 | TCP transport can actually loose messages since the TCP implementation | ||
| 4267 | drops messages if the @code{write} to the socket would block. While the | ||
| 4268 | SMTP protocol never drops messages itself, it is often so | ||
| 4269 | slow that only a fraction of the messages can be sent and received in the | ||
| 4270 | given time-bounds. For this benchmark we report the message loss after | ||
| 4271 | allowing t time for sending m messages. If messages were not sent (or | ||
| 4272 | received) after an overall timeout of t, they were considered lost. The | ||
| 4273 | benchmark was performed using two Xeon 2 GHZ machines running RedHat 8.0 | ||
| 4274 | with sendmail. The machines were connected with a direct 100 MBit Ethernet | ||
| 4275 | connection.@ Figures udp1200, tcp1200 and smtp-MTUs show that the | ||
| 4276 | throughput for messages of size 1,200 octets is 2,343 kbps, 3,310 kbps | ||
| 4277 | and 6 kbps for UDP, TCP and SMTP respectively. The high per-message | ||
| 4278 | overhead of SMTP can be improved by increasing the MTU, for example, an | ||
| 4279 | MTU of 12,000 octets improves the throughput to 13 kbps as figure | ||
| 4280 | smtp-MTUs shows. Our research paper) has some more details on the | ||
| 4281 | benchmarking results. | ||
| 4282 | |||
| 4283 | @cindex Bluetooth plugin | ||
| 4284 | @node Bluetooth plugin | ||
| 4285 | @section Bluetooth plugin | ||
| 4286 | @c %**end of header | ||
| 4287 | |||
| 4288 | This page describes the new Bluetooth transport plugin for GNUnet. The | ||
| 4289 | plugin is still in the testing stage so don't expect it to work | ||
| 4290 | perfectly. If you have any questions or problems just post them here or | ||
| 4291 | ask on the IRC channel. | ||
| 4292 | |||
| 4293 | @itemize @bullet | ||
| 4294 | @item What do I need to use the Bluetooth plugin transport? | ||
| 4295 | @item BluetoothHow does it work? | ||
| 4296 | @item What possible errors should I be aware of? | ||
| 4297 | @item How do I configure my peer? | ||
| 4298 | @item How can I test it? | ||
| 4299 | @end itemize | ||
| 4300 | |||
| 4301 | @menu | ||
| 4302 | * What do I need to use the Bluetooth plugin transport?:: | ||
| 4303 | * How does it work2?:: | ||
| 4304 | * What possible errors should I be aware of?:: | ||
| 4305 | * How do I configure my peer2?:: | ||
| 4306 | * How can I test it?:: | ||
| 4307 | * The implementation of the Bluetooth transport plugin:: | ||
| 4308 | @end menu | ||
| 4309 | |||
| 4310 | @node What do I need to use the Bluetooth plugin transport? | ||
| 4311 | @subsection What do I need to use the Bluetooth plugin transport? | ||
| 4312 | @c %**end of header | ||
| 4313 | |||
| 4314 | If you are a GNU/Linux user and you want to use the Bluetooth | ||
| 4315 | transport plugin you should install the | ||
| 4316 | @command{BlueZ development libraries} (if they aren't already | ||
| 4317 | installed). | ||
| 4318 | For instructions about how to install the libraries you should | ||
| 4319 | check out the BlueZ site | ||
| 4320 | (@uref{http://www.bluez.org/, http://www.bluez.org}). If you don't know if | ||
| 4321 | you have the necessary libraries, don't worry, just run the GNUnet | ||
| 4322 | configure script and you will be able to see a notification at the end | ||
| 4323 | which will warn you if you don't have the necessary libraries. | ||
| 4324 | |||
| 4325 | If you are a Windows user you should have installed the | ||
| 4326 | @emph{MinGW}/@emph{MSys2} with the latest updates (especially the | ||
| 4327 | @emph{ws2bth} header). If this is your first build of GNUnet on Windows | ||
| 4328 | you should check out the SBuild repository. It will semi-automatically | ||
| 4329 | assembles a @emph{MinGW}/@emph{MSys2} installation with a lot of extra | ||
| 4330 | packages which are needed for the GNUnet build. So this will ease your | ||
| 4331 | work!@ Finally you just have to be sure that you have the correct drivers | ||
| 4332 | for your Bluetooth device installed and that your device is on and in a | ||
| 4333 | discoverable mode. The Windows Bluetooth Stack supports only the RFCOMM | ||
| 4334 | protocol so we cannot turn on your device programatically! | ||
| 4335 | |||
| 4336 | @c FIXME: Change to unique title | ||
| 4337 | @node How does it work2? | ||
| 4338 | @subsection How does it work2? | ||
| 4339 | @c %**end of header | ||
| 4340 | |||
| 4341 | The Bluetooth transport plugin uses virtually the same code as the WLAN | ||
| 4342 | plugin and only the helper binary is different. The helper takes a single | ||
| 4343 | argument, which represents the interface name and is specified in the | ||
| 4344 | configuration file. Here are the basic steps that are followed by the | ||
| 4345 | helper binary used on GNU/Linux: | ||
| 4346 | |||
| 4347 | @itemize @bullet | ||
| 4348 | @item it verifies if the name corresponds to a Bluetooth interface name | ||
| 4349 | @item it verifies if the interface is up (if it is not, it tries to bring | ||
| 4350 | it up) | ||
| 4351 | @item it tries to enable the page and inquiry scan in order to make the | ||
| 4352 | device discoverable and to accept incoming connection requests | ||
| 4353 | @emph{The above operations require root access so you should start the | ||
| 4354 | transport plugin with root privileges.} | ||
| 4355 | @item it finds an available port number and registers a SDP service which | ||
| 4356 | will be used to find out on which port number is the server listening on | ||
| 4357 | and switch the socket in listening mode | ||
| 4358 | @item it sends a HELLO message with its address | ||
| 4359 | @item finally it forwards traffic from the reading sockets to the STDOUT | ||
| 4360 | and from the STDIN to the writing socket | ||
| 4361 | @end itemize | ||
| 4362 | |||
| 4363 | Once in a while the device will make an inquiry scan to discover the | ||
| 4364 | nearby devices and it will send them randomly HELLO messages for peer | ||
| 4365 | discovery. | ||
| 4366 | |||
| 4367 | @node What possible errors should I be aware of? | ||
| 4368 | @subsection What possible errors should I be aware of? | ||
| 4369 | @c %**end of header | ||
| 4370 | |||
| 4371 | @emph{This section is dedicated for GNU/Linux users} | ||
| 4372 | |||
| 4373 | Well there are many ways in which things could go wrong but I will try to | ||
| 4374 | present some tools that you could use to debug and some scenarios. | ||
| 4375 | |||
| 4376 | @itemize @bullet | ||
| 4377 | |||
| 4378 | @item @code{bluetoothd -n -d} : use this command to enable logging in the | ||
| 4379 | foreground and to print the logging messages | ||
| 4380 | |||
| 4381 | @item @code{hciconfig}: can be used to configure the Bluetooth devices. | ||
| 4382 | If you run it without any arguments it will print information about the | ||
| 4383 | state of the interfaces. So if you receive an error that the device | ||
| 4384 | couldn't be brought up you should try to bring it manually and to see if | ||
| 4385 | it works (use @code{hciconfig -a hciX up}). If you can't and the | ||
| 4386 | Bluetooth address has the form 00:00:00:00:00:00 it means that there is | ||
| 4387 | something wrong with the D-Bus daemon or with the Bluetooth daemon. Use | ||
| 4388 | @code{bluetoothd} tool to see the logs | ||
| 4389 | |||
| 4390 | @item @code{sdptool} can be used to control and interrogate SDP servers. | ||
| 4391 | If you encounter problems regarding the SDP server (like the SDP server is | ||
| 4392 | down) you should check out if the D-Bus daemon is running correctly and to | ||
| 4393 | see if the Bluetooth daemon started correctly(use @code{bluetoothd} tool). | ||
| 4394 | Also, sometimes the SDP service could work but somehow the device couldn't | ||
| 4395 | register its service. Use @code{sdptool browse [dev-address]} to see if | ||
| 4396 | the service is registered. There should be a service with the name of the | ||
| 4397 | interface and GNUnet as provider. | ||
| 4398 | |||
| 4399 | @item @code{hcitool} : another useful tool which can be used to configure | ||
| 4400 | the device and to send some particular commands to it. | ||
| 4401 | |||
| 4402 | @item @code{hcidump} : could be used for low level debugging | ||
| 4403 | @end itemize | ||
| 4404 | |||
| 4405 | @c FIXME: A more unique name | ||
| 4406 | @node How do I configure my peer2? | ||
| 4407 | @subsection How do I configure my peer2? | ||
| 4408 | @c %**end of header | ||
| 4409 | |||
| 4410 | On GNU/Linux, you just have to be sure that the interface name | ||
| 4411 | corresponds to the one that you want to use. | ||
| 4412 | Use the @code{hciconfig} tool to check that. | ||
| 4413 | By default it is set to hci0 but you can change it. | ||
| 4414 | |||
| 4415 | A basic configuration looks like this: | ||
| 4416 | |||
| 4417 | @example | ||
| 4418 | [transport-bluetooth] | ||
| 4419 | # Name of the interface (typically hciX) | ||
| 4420 | INTERFACE = hci0 | ||
| 4421 | # Real hardware, no testing | ||
| 4422 | TESTMODE = 0 TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
| 4423 | @end example | ||
| 4424 | |||
| 4425 | In order to use the Bluetooth transport plugin when the transport service | ||
| 4426 | is started, you must add the plugin name to the default transport service | ||
| 4427 | plugins list. For example: | ||
| 4428 | |||
| 4429 | @example | ||
| 4430 | [transport] ... PLUGINS = dns bluetooth ... | ||
| 4431 | @end example | ||
| 4432 | |||
| 4433 | If you want to use only the Bluetooth plugin set | ||
| 4434 | @emph{PLUGINS = bluetooth} | ||
| 4435 | |||
| 4436 | On Windows, you cannot specify which device to use. The only thing that | ||
| 4437 | you should do is to add @emph{bluetooth} on the plugins list of the | ||
| 4438 | transport service. | ||
| 4439 | |||
| 4440 | @node How can I test it? | ||
| 4441 | @subsection How can I test it? | ||
| 4442 | @c %**end of header | ||
| 4443 | |||
| 4444 | If you have two Bluetooth devices on the same machine and you are using | ||
| 4445 | GNU/Linux you must: | ||
| 4446 | |||
| 4447 | @itemize @bullet | ||
| 4448 | |||
| 4449 | @item create two different file configuration (one which will use the | ||
| 4450 | first interface (@emph{hci0}) and the other which will use the second | ||
| 4451 | interface (@emph{hci1})). Let's name them @emph{peer1.conf} and | ||
| 4452 | @emph{peer2.conf}. | ||
| 4453 | |||
| 4454 | @item run @emph{gnunet-peerinfo -c peerX.conf -s} in order to generate the | ||
| 4455 | peers private keys. The @strong{X} must be replace with 1 or 2. | ||
| 4456 | |||
| 4457 | @item run @emph{gnunet-arm -c peerX.conf -s -i=transport} in order to | ||
| 4458 | start the transport service. (Make sure that you have "bluetooth" on the | ||
| 4459 | transport plugins list if the Bluetooth transport service doesn't start.) | ||
| 4460 | |||
| 4461 | @item run @emph{gnunet-peerinfo -c peer1.conf -s} to get the first peer's | ||
| 4462 | ID. If you already know your peer ID (you saved it from the first | ||
| 4463 | command), this can be skipped. | ||
| 4464 | |||
| 4465 | @item run @emph{gnunet-transport -c peer2.conf -p=PEER1_ID -s} to start | ||
| 4466 | sending data for benchmarking to the other peer. | ||
| 4467 | |||
| 4468 | @end itemize | ||
| 4469 | |||
| 4470 | |||
| 4471 | This scenario will try to connect the second peer to the first one and | ||
| 4472 | then start sending data for benchmarking. | ||
| 4473 | |||
| 4474 | On Windows you cannot test the plugin functionality using two Bluetooth | ||
| 4475 | devices from the same machine because after you install the drivers there | ||
| 4476 | will occur some conflicts between the Bluetooth stacks. (At least that is | ||
| 4477 | what happened on my machine : I wasn't able to use the Bluesoleil stack and | ||
| 4478 | the WINDCOMM one in the same time). | ||
| 4479 | |||
| 4480 | If you have two different machines and your configuration files are good | ||
| 4481 | you can use the same scenario presented on the beginning of this section. | ||
| 4482 | |||
| 4483 | Another way to test the plugin functionality is to create your own | ||
| 4484 | application which will use the GNUnet framework with the Bluetooth | ||
| 4485 | transport service. | ||
| 4486 | |||
| 4487 | @node The implementation of the Bluetooth transport plugin | ||
| 4488 | @subsection The implementation of the Bluetooth transport plugin | ||
| 4489 | @c %**end of header | ||
| 4490 | |||
| 4491 | This page describes the implementation of the Bluetooth transport plugin. | ||
| 4492 | |||
| 4493 | First I want to remind you that the Bluetooth transport plugin uses | ||
| 4494 | virtually the same code as the WLAN plugin and only the helper binary is | ||
| 4495 | different. Also the scope of the helper binary from the Bluetooth | ||
| 4496 | transport plugin is the same as the one used for the WLAN transport | ||
| 4497 | plugin: it accesses the interface and then it forwards traffic in both | ||
| 4498 | directions between the Bluetooth interface and stdin/stdout of the | ||
| 4499 | process involved. | ||
| 4500 | |||
| 4501 | The Bluetooth plugin transport could be used both on GNU/Linux and Windows | ||
| 4502 | platforms. | ||
| 4503 | |||
| 4504 | @itemize @bullet | ||
| 4505 | @item Linux functionality | ||
| 4506 | @item Windows functionality | ||
| 4507 | @item Pending Features | ||
| 4508 | @end itemize | ||
| 4509 | |||
| 4510 | |||
| 4511 | |||
| 4512 | @menu | ||
| 4513 | * Linux functionality:: | ||
| 4514 | * THE INITIALIZATION:: | ||
| 4515 | * THE LOOP:: | ||
| 4516 | * Details about the broadcast implementation:: | ||
| 4517 | * Windows functionality:: | ||
| 4518 | * Pending features:: | ||
| 4519 | @end menu | ||
| 4520 | |||
| 4521 | @node Linux functionality | ||
| 4522 | @subsubsection Linux functionality | ||
| 4523 | @c %**end of header | ||
| 4524 | |||
| 4525 | In order to implement the plugin functionality on GNU/Linux I | ||
| 4526 | used the BlueZ stack. | ||
| 4527 | For the communication with the other devices I used the RFCOMM | ||
| 4528 | protocol. Also I used the HCI protocol to gain some control over the | ||
| 4529 | device. The helper binary takes a single argument (the name of the | ||
| 4530 | Bluetooth interface) and is separated in two stages: | ||
| 4531 | |||
| 4532 | @c %** 'THE INITIALIZATION' should be in bigger letters or stand out, not | ||
| 4533 | @c %** starting a new section? | ||
| 4534 | @node THE INITIALIZATION | ||
| 4535 | @subsubsection THE INITIALIZATION | ||
| 4536 | |||
| 4537 | @itemize @bullet | ||
| 4538 | @item first, it checks if we have root privileges | ||
| 4539 | (@emph{Remember that we need to have root privileges in order to be able | ||
| 4540 | to bring the interface up if it is down or to change its state.}). | ||
| 4541 | |||
| 4542 | @item second, it verifies if the interface with the given name exists. | ||
| 4543 | |||
| 4544 | @strong{If the interface with that name exists and it is a Bluetooth | ||
| 4545 | interface:} | ||
| 4546 | |||
| 4547 | @item it creates a RFCOMM socket which will be used for listening and call | ||
| 4548 | the @emph{open_device} method | ||
| 4549 | |||
| 4550 | On the @emph{open_device} method: | ||
| 4551 | @itemize @bullet | ||
| 4552 | @item creates a HCI socket used to send control events to the the device | ||
| 4553 | @item searches for the device ID using the interface name | ||
| 4554 | @item saves the device MAC address | ||
| 4555 | @item checks if the interface is down and tries to bring it UP | ||
| 4556 | @item checks if the interface is in discoverable mode and tries to make it | ||
| 4557 | discoverable | ||
| 4558 | @item closes the HCI socket and binds the RFCOMM one | ||
| 4559 | @item switches the RFCOMM socket in listening mode | ||
| 4560 | @item registers the SDP service (the service will be used by the other | ||
| 4561 | devices to get the port on which this device is listening on) | ||
| 4562 | @end itemize | ||
| 4563 | |||
| 4564 | @item drops the root privileges | ||
| 4565 | |||
| 4566 | @strong{If the interface is not a Bluetooth interface the helper exits | ||
| 4567 | with a suitable error} | ||
| 4568 | @end itemize | ||
| 4569 | |||
| 4570 | @c %** Same as for @node entry above | ||
| 4571 | @node THE LOOP | ||
| 4572 | @subsubsection THE LOOP | ||
| 4573 | |||
| 4574 | The helper binary uses a list where it saves all the connected neighbour | ||
| 4575 | devices (@emph{neighbours.devices}) and two buffers (@emph{write_pout} and | ||
| 4576 | @emph{write_std}). The first message which is send is a control message | ||
| 4577 | with the device's MAC address in order to announce the peer presence to | ||
| 4578 | the neighbours. Here are a short description of what happens in the main | ||
| 4579 | loop: | ||
| 4580 | |||
| 4581 | @itemize @bullet | ||
| 4582 | @item Every time when it receives something from the STDIN it processes | ||
| 4583 | the data and saves the message in the first buffer (@emph{write_pout}). | ||
| 4584 | When it has something in the buffer, it gets the destination address from | ||
| 4585 | the buffer, searches the destination address in the list (if there is no | ||
| 4586 | connection with that device, it creates a new one and saves it to the | ||
| 4587 | list) and sends the message. | ||
| 4588 | @item Every time when it receives something on the listening socket it | ||
| 4589 | accepts the connection and saves the socket on a list with the reading | ||
| 4590 | sockets. @item Every time when it receives something from a reading | ||
| 4591 | socket it parses the message, verifies the CRC and saves it in the | ||
| 4592 | @emph{write_std} buffer in order to be sent later to the STDOUT. | ||
| 4593 | @end itemize | ||
| 4594 | |||
| 4595 | So in the main loop we use the select function to wait until one of the | ||
| 4596 | file descriptor saved in one of the two file descriptors sets used is | ||
| 4597 | ready to use. The first set (@emph{rfds}) represents the reading set and | ||
| 4598 | it could contain the list with the reading sockets, the STDIN file | ||
| 4599 | descriptor or the listening socket. The second set (@emph{wfds}) is the | ||
| 4600 | writing set and it could contain the sending socket or the STDOUT file | ||
| 4601 | descriptor. After the select function returns, we check which file | ||
| 4602 | descriptor is ready to use and we do what is supposed to do on that kind | ||
| 4603 | of event. @emph{For example:} if it is the listening socket then we | ||
| 4604 | accept a new connection and save the socket in the reading list; if it is | ||
| 4605 | the STDOUT file descriptor, then we write to STDOUT the message from the | ||
| 4606 | @emph{write_std} buffer. | ||
| 4607 | |||
| 4608 | To find out on which port a device is listening on we connect to the local | ||
| 4609 | SDP server and search the registered service for that device. | ||
| 4610 | |||
| 4611 | @emph{You should be aware of the fact that if the device fails to connect | ||
| 4612 | to another one when trying to send a message it will attempt one more | ||
| 4613 | time. If it fails again, then it skips the message.} | ||
| 4614 | @emph{Also you should know that the transport Bluetooth plugin has | ||
| 4615 | support for @strong{broadcast messages}.} | ||
| 4616 | |||
| 4617 | @node Details about the broadcast implementation | ||
| 4618 | @subsubsection Details about the broadcast implementation | ||
| 4619 | @c %**end of header | ||
| 4620 | |||
| 4621 | First I want to point out that the broadcast functionality for the CONTROL | ||
| 4622 | messages is not implemented in a conventional way. Since the inquiry scan | ||
| 4623 | time is too big and it will take some time to send a message to all the | ||
| 4624 | discoverable devices I decided to tackle the problem in a different way. | ||
| 4625 | Here is how I did it: | ||
| 4626 | |||
| 4627 | @itemize @bullet | ||
| 4628 | @item If it is the first time when I have to broadcast a message I make an | ||
| 4629 | inquiry scan and save all the devices' addresses to a vector. | ||
| 4630 | @item After the inquiry scan ends I take the first address from the list | ||
| 4631 | and I try to connect to it. If it fails, I try to connect to the next one. | ||
| 4632 | If it succeeds, I save the socket to a list and send the message to the | ||
| 4633 | device. | ||
| 4634 | @item When I have to broadcast another message, first I search on the list | ||
| 4635 | for a new device which I'm not connected to. If there is no new device on | ||
| 4636 | the list I go to the beginning of the list and send the message to the | ||
| 4637 | old devices. After 5 cycles I make a new inquiry scan to check out if | ||
| 4638 | there are new discoverable devices and save them to the list. If there | ||
| 4639 | are no new discoverable devices I reset the cycling counter and go again | ||
| 4640 | through the old list and send messages to the devices saved in it. | ||
| 4641 | @end itemize | ||
| 4642 | |||
| 4643 | @strong{Therefore}: | ||
| 4644 | |||
| 4645 | @itemize @bullet | ||
| 4646 | @item every time when I have a broadcast message I look up on the list | ||
| 4647 | for a new device and send the message to it | ||
| 4648 | @item if I reached the end of the list for 5 times and I'm connected to | ||
| 4649 | all the devices from the list I make a new inquiry scan. | ||
| 4650 | @emph{The number of the list's cycles after an inquiry scan could be | ||
| 4651 | increased by redefining the MAX_LOOPS variable} | ||
| 4652 | @item when there are no new devices I send messages to the old ones. | ||
| 4653 | @end itemize | ||
| 4654 | |||
| 4655 | Doing so, the broadcast control messages will reach the devices but with | ||
| 4656 | delay. | ||
| 4657 | |||
| 4658 | @emph{NOTICE:} When I have to send a message to a certain device first I | ||
| 4659 | check on the broadcast list to see if we are connected to that device. If | ||
| 4660 | not we try to connect to it and in case of success we save the address and | ||
| 4661 | the socket on the list. If we are already connected to that device we | ||
| 4662 | simply use the socket. | ||
| 4663 | |||
| 4664 | @node Windows functionality | ||
| 4665 | @subsubsection Windows functionality | ||
| 4666 | @c %**end of header | ||
| 4667 | |||
| 4668 | For Windows I decided to use the Microsoft Bluetooth stack which has the | ||
| 4669 | advantage of coming standard from Windows XP SP2. The main disadvantage is | ||
| 4670 | that it only supports the RFCOMM protocol so we will not be able to have | ||
| 4671 | a low level control over the Bluetooth device. Therefore it is the user | ||
| 4672 | responsibility to check if the device is up and in the discoverable mode. | ||
| 4673 | Also there are no tools which could be used for debugging in order to read | ||
| 4674 | the data coming from and going to a Bluetooth device, which obviously | ||
| 4675 | hindered my work. Another thing that slowed down the implementation of the | ||
| 4676 | plugin (besides that I wasn't too accommodated with the win32 API) was that | ||
| 4677 | there were some bugs on MinGW regarding the Bluetooth. Now they are solved | ||
| 4678 | but you should keep in mind that you should have the latest updates | ||
| 4679 | (especially the @emph{ws2bth} header). | ||
| 4680 | |||
| 4681 | Besides the fact that it uses the Windows Sockets, the Windows | ||
| 4682 | implementation follows the same principles as the GNU/Linux one: | ||
| 4683 | |||
| 4684 | @itemize @bullet | ||
| 4685 | @item It has a initalization part where it initializes the | ||
| 4686 | Windows Sockets, creates a RFCOMM socket which will be binded and switched | ||
| 4687 | to the listening mode and registers a SDP service. In the Microsoft | ||
| 4688 | Bluetooth API there are two ways to work with the SDP: | ||
| 4689 | @itemize @bullet | ||
| 4690 | @item an easy way which works with very simple service records | ||
| 4691 | @item a hard way which is useful when you need to update or to delete the | ||
| 4692 | record | ||
| 4693 | @end itemize | ||
| 4694 | @end itemize | ||
| 4695 | |||
| 4696 | Since I only needed the SDP service to find out on which port the device | ||
| 4697 | is listening on and that did not change, I decided to use the easy way. | ||
| 4698 | In order to register the service I used the @emph{WSASetService} function | ||
| 4699 | and I generated the @emph{Universally Unique Identifier} with the | ||
| 4700 | @emph{guidgen.exe} Windows's tool. | ||
| 4701 | |||
| 4702 | In the loop section the only difference from the GNU/Linux implementation | ||
| 4703 | is that I used the @code{GNUNET_NETWORK} library for | ||
| 4704 | functions like @emph{accept}, @emph{bind}, @emph{connect} or | ||
| 4705 | @emph{select}. I decided to use the | ||
| 4706 | @code{GNUNET_NETWORK} library because I also needed to interact | ||
| 4707 | with the STDIN and STDOUT handles and on Windows | ||
| 4708 | the select function is only defined for sockets, | ||
| 4709 | and it will not work for arbitrary file handles. | ||
| 4710 | |||
| 4711 | Another difference between GNU/Linux and Windows implementation is that in | ||
| 4712 | GNU/Linux, the Bluetooth address is represented in 48 bits | ||
| 4713 | while in Windows is represented in 64 bits. | ||
| 4714 | Therefore I had to do some changes on @emph{plugin_transport_wlan} header. | ||
| 4715 | |||
| 4716 | Also, currently on Windows the Bluetooth plugin doesn't have support for | ||
| 4717 | broadcast messages. When it receives a broadcast message it will skip it. | ||
| 4718 | |||
| 4719 | @node Pending features | ||
| 4720 | @subsubsection Pending features | ||
| 4721 | @c %**end of header | ||
| 4722 | |||
| 4723 | @itemize @bullet | ||
| 4724 | @item Implement the broadcast functionality on Windows @emph{(currently | ||
| 4725 | working on)} | ||
| 4726 | @item Implement a testcase for the helper :@ @emph{The testcase | ||
| 4727 | consists of a program which emulates the plugin and uses the helper. It | ||
| 4728 | will simulate connections, disconnections and data transfers.} | ||
| 4729 | @end itemize | ||
| 4730 | |||
| 4731 | If you have a new idea about a feature of the plugin or suggestions about | ||
| 4732 | how I could improve the implementation you are welcome to comment or to | ||
| 4733 | contact me. | ||
| 4734 | |||
| 4735 | @node WLAN plugin | ||
| 4736 | @section WLAN plugin | ||
| 4737 | @c %**end of header | ||
| 4738 | |||
| 4739 | This section documents how the wlan transport plugin works. Parts which | ||
| 4740 | are not implemented yet or could be better implemented are described at | ||
| 4741 | the end. | ||
| 4742 | |||
| 4743 | @cindex ATS Subsystem | ||
| 4744 | @node ATS Subsystem | ||
| 4745 | @section ATS Subsystem | ||
| 4746 | @c %**end of header | ||
| 4747 | |||
| 4748 | ATS stands for "automatic transport selection", and the function of ATS in | ||
| 4749 | GNUnet is to decide on which address (and thus transport plugin) should | ||
| 4750 | be used for two peers to communicate, and what bandwidth limits should be | ||
| 4751 | imposed on such an individual connection. To help ATS make an informed | ||
| 4752 | decision, higher-level services inform the ATS service about their | ||
| 4753 | requirements and the quality of the service rendered. The ATS service | ||
| 4754 | also interacts with the transport service to be appraised of working | ||
| 4755 | addresses and to communicate its resource allocation decisions. Finally, | ||
| 4756 | the ATS service's operation can be observed using a monitoring API. | ||
| 4757 | |||
| 4758 | The main logic of the ATS service only collects the available addresses, | ||
| 4759 | their performance characteristics and the applications requirements, but | ||
| 4760 | does not make the actual allocation decision. This last critical step is | ||
| 4761 | left to an ATS plugin, as we have implemented (currently three) different | ||
| 4762 | allocation strategies which differ significantly in their performance and | ||
| 4763 | maturity, and it is still unclear if any particular plugin is generally | ||
| 4764 | superior. | ||
| 4765 | |||
| 4766 | @cindex CORE Subsystem | ||
| 4767 | @node CORE Subsystem | ||
| 4768 | @section CORE Subsystem | ||
| 4769 | @c %**end of header | ||
| 4770 | |||
| 4771 | The CORE subsystem in GNUnet is responsible for securing link-layer | ||
| 4772 | communications between nodes in the GNUnet overlay network. CORE builds | ||
| 4773 | on the TRANSPORT subsystem which provides for the actual, insecure, | ||
| 4774 | unreliable link-layer communication (for example, via UDP or WLAN), and | ||
| 4775 | then adds fundamental security to the connections: | ||
| 4776 | |||
| 4777 | @itemize @bullet | ||
| 4778 | @item confidentiality with so-called perfect forward secrecy; we use | ||
| 4779 | ECDHE | ||
| 4780 | (@uref{http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman, Elliptic-curve Diffie---Hellman}) | ||
| 4781 | powered by Curve25519 | ||
| 4782 | (@uref{http://cr.yp.to/ecdh.html, Curve25519}) for the key | ||
| 4783 | exchange and then use symmetric encryption, encrypting with both AES-256 | ||
| 4784 | (@uref{http://en.wikipedia.org/wiki/Rijndael, AES-256}) and | ||
| 4785 | Twofish (@uref{http://en.wikipedia.org/wiki/Twofish, Twofish}) | ||
| 4786 | @item @uref{http://en.wikipedia.org/wiki/Authentication, authentication} | ||
| 4787 | is achieved by signing the ephemeral keys using Ed25519 | ||
| 4788 | (@uref{http://ed25519.cr.yp.to/, Ed25519}), a deterministic | ||
| 4789 | variant of ECDSA | ||
| 4790 | (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}) | ||
| 4791 | @item integrity protection (using SHA-512 | ||
| 4792 | (@uref{http://en.wikipedia.org/wiki/SHA-2, SHA-512}) to do | ||
| 4793 | encrypt-then-MAC | ||
| 4794 | (@uref{http://en.wikipedia.org/wiki/Authenticated_encryption, encrypt-then-MAC})) | ||
| 4795 | @item Replay | ||
| 4796 | (@uref{http://en.wikipedia.org/wiki/Replay_attack, replay}) | ||
| 4797 | protection (using nonces, timestamps, challenge-response, | ||
| 4798 | message counters and ephemeral keys) | ||
| 4799 | @item liveness (keep-alive messages, timeout) | ||
| 4800 | @end itemize | ||
| 4801 | |||
| 4802 | @menu | ||
| 4803 | * Limitations:: | ||
| 4804 | * When is a peer "connected"?:: | ||
| 4805 | * libgnunetcore:: | ||
| 4806 | * The CORE Client-Service Protocol:: | ||
| 4807 | * The CORE Peer-to-Peer Protocol:: | ||
| 4808 | @end menu | ||
| 4809 | |||
| 4810 | @cindex core subsystem limitations | ||
| 4811 | @node Limitations | ||
| 4812 | @subsection Limitations | ||
| 4813 | @c %**end of header | ||
| 4814 | |||
| 4815 | CORE does not perform | ||
| 4816 | @uref{http://en.wikipedia.org/wiki/Routing, routing}; using CORE it is | ||
| 4817 | only possible to communicate with peers that happen to already be | ||
| 4818 | "directly" connected with each other. CORE also does not have an | ||
| 4819 | API to allow applications to establish such "direct" connections --- for | ||
| 4820 | this, applications can ask TRANSPORT, but TRANSPORT might not be able to | ||
| 4821 | establish a "direct" connection. The TOPOLOGY subsystem is responsible for | ||
| 4822 | trying to keep a few "direct" connections open at all times. Applications | ||
| 4823 | that need to talk to particular peers should use the CADET subsystem, as | ||
| 4824 | it can establish arbitrary "indirect" connections. | ||
| 4825 | |||
| 4826 | Because CORE does not perform routing, CORE must only be used directly by | ||
| 4827 | applications that either perform their own routing logic (such as | ||
| 4828 | anonymous file-sharing) or that do not require routing, for example | ||
| 4829 | because they are based on flooding the network. CORE communication is | ||
| 4830 | unreliable and delivery is possibly out-of-order. Applications that | ||
| 4831 | require reliable communication should use the CADET service. Each | ||
| 4832 | application can only queue one message per target peer with the CORE | ||
| 4833 | service at any time; messages cannot be larger than approximately | ||
| 4834 | 63 kilobytes. If messages are small, CORE may group multiple messages | ||
| 4835 | (possibly from different applications) prior to encryption. If permitted | ||
| 4836 | by the application (using the @uref{http://baus.net/on-tcp_cork/, cork} | ||
| 4837 | option), CORE may delay transmissions to facilitate grouping of multiple | ||
| 4838 | small messages. If cork is not enabled, CORE will transmit the message as | ||
| 4839 | soon as TRANSPORT allows it (TRANSPORT is responsible for limiting | ||
| 4840 | bandwidth and congestion control). CORE does not allow flow control; | ||
| 4841 | applications are expected to process messages at line-speed. If flow | ||
| 4842 | control is needed, applications should use the CADET service. | ||
| 4843 | |||
| 4844 | @cindex when is a peer connected | ||
| 4845 | @node When is a peer "connected"? | ||
| 4846 | @subsection When is a peer "connected"? | ||
| 4847 | @c %**end of header | ||
| 4848 | |||
| 4849 | In addition to the security features mentioned above, CORE also provides | ||
| 4850 | one additional key feature to applications using it, and that is a | ||
| 4851 | limited form of protocol-compatibility checking. CORE distinguishes | ||
| 4852 | between TRANSPORT-level connections (which enable communication with other | ||
| 4853 | peers) and application-level connections. Applications using the CORE API | ||
| 4854 | will (typically) learn about application-level connections from CORE, and | ||
| 4855 | not about TRANSPORT-level connections. When a typical application uses | ||
| 4856 | CORE, it will specify a set of message types | ||
| 4857 | (from @code{gnunet_protocols.h}) that it understands. CORE will then | ||
| 4858 | notify the application about connections it has with other peers if and | ||
| 4859 | only if those applications registered an intersecting set of message | ||
| 4860 | types with their CORE service. Thus, it is quite possible that CORE only | ||
| 4861 | exposes a subset of the established direct connections to a particular | ||
| 4862 | application --- and different applications running above CORE might see | ||
| 4863 | different sets of connections at the same time. | ||
| 4864 | |||
| 4865 | A special case are applications that do not register a handler for any | ||
| 4866 | message type. | ||
| 4867 | CORE assumes that these applications merely want to monitor connections | ||
| 4868 | (or "all" messages via other callbacks) and will notify those applications | ||
| 4869 | about all connections. This is used, for example, by the | ||
| 4870 | @code{gnunet-core} command-line tool to display the active connections. | ||
| 4871 | Note that it is also possible that the TRANSPORT service has more active | ||
| 4872 | connections than the CORE service, as the CORE service first has to | ||
| 4873 | perform a key exchange with connecting peers before exchanging information | ||
| 4874 | about supported message types and notifying applications about the new | ||
| 4875 | connection. | ||
| 4876 | |||
| 4877 | @cindex libgnunetcore | ||
| 4878 | @node libgnunetcore | ||
| 4879 | @subsection libgnunetcore | ||
| 4880 | @c %**end of header | ||
| 4881 | |||
| 4882 | The CORE API (defined in @file{gnunet_core_service.h}) is the basic | ||
| 4883 | messaging API used by P2P applications built using GNUnet. It provides | ||
| 4884 | applications the ability to send and receive encrypted messages to the | ||
| 4885 | peer's "directly" connected neighbours. | ||
| 4886 | |||
| 4887 | As CORE connections are generally "direct" connections,@ applications must | ||
| 4888 | not assume that they can connect to arbitrary peers this way, as "direct" | ||
| 4889 | connections may not always be possible. Applications using CORE are | ||
| 4890 | notified about which peers are connected. Creating new "direct" | ||
| 4891 | connections must be done using the TRANSPORT API. | ||
| 4892 | |||
| 4893 | The CORE API provides unreliable, out-of-order delivery. While the | ||
| 4894 | implementation tries to ensure timely, in-order delivery, both message | ||
| 4895 | losses and reordering are not detected and must be tolerated by the | ||
| 4896 | application. Most important, the core will NOT perform retransmission if | ||
| 4897 | messages could not be delivered. | ||
| 4898 | |||
| 4899 | Note that CORE allows applications to queue one message per connected | ||
| 4900 | peer. The rate at which each connection operates is influenced by the | ||
| 4901 | preferences expressed by local application as well as restrictions | ||
| 4902 | imposed by the other peer. Local applications can express their | ||
| 4903 | preferences for particular connections using the "performance" API of the | ||
| 4904 | ATS service. | ||
| 4905 | |||
| 4906 | Applications that require more sophisticated transmission capabilities | ||
| 4907 | such as TCP-like behavior, or if you intend to send messages to arbitrary | ||
| 4908 | remote peers, should use the CADET API. | ||
| 4909 | |||
| 4910 | The typical use of the CORE API is to connect to the CORE service using | ||
| 4911 | @code{GNUNET_CORE_connect}, process events from the CORE service (such as | ||
| 4912 | peers connecting, peers disconnecting and incoming messages) and send | ||
| 4913 | messages to connected peers using | ||
| 4914 | @code{GNUNET_CORE_notify_transmit_ready}. Note that applications must | ||
| 4915 | cancel pending transmission requests if they receive a disconnect event | ||
| 4916 | for a peer that had a transmission pending; furthermore, queuing more | ||
| 4917 | than one transmission request per peer per application using the | ||
| 4918 | service is not permitted. | ||
| 4919 | |||
| 4920 | The CORE API also allows applications to monitor all communications of the | ||
| 4921 | peer prior to encryption (for outgoing messages) or after decryption (for | ||
| 4922 | incoming messages). This can be useful for debugging, diagnostics or to | ||
| 4923 | establish the presence of cover traffic (for anonymity). As monitoring | ||
| 4924 | applications are often not interested in the payload, the monitoring | ||
| 4925 | callbacks can be configured to only provide the message headers (including | ||
| 4926 | the message type and size) instead of copying the full data stream to the | ||
| 4927 | monitoring client. | ||
| 4928 | |||
| 4929 | The init callback of the @code{GNUNET_CORE_connect} function is called | ||
| 4930 | with the hash of the public key of the peer. This public key is used to | ||
| 4931 | identify the peer globally in the GNUnet network. Applications are | ||
| 4932 | encouraged to check that the provided hash matches the hash that they are | ||
| 4933 | using (as theoretically the application may be using a different | ||
| 4934 | configuration file with a different private key, which would result in | ||
| 4935 | hard to find bugs). | ||
| 4936 | |||
| 4937 | As with most service APIs, the CORE API isolates applications from crashes | ||
| 4938 | of the CORE service. If the CORE service crashes, the application will see | ||
| 4939 | disconnect events for all existing connections. Once the connections are | ||
| 4940 | re-established, the applications will be receive matching connect events. | ||
| 4941 | |||
| 4942 | @cindex core clinet-service protocol | ||
| 4943 | @node The CORE Client-Service Protocol | ||
| 4944 | @subsection The CORE Client-Service Protocol | ||
| 4945 | @c %**end of header | ||
| 4946 | |||
| 4947 | This section describes the protocol between an application using the CORE | ||
| 4948 | service (the client) and the CORE service process itself. | ||
| 4949 | |||
| 4950 | |||
| 4951 | @menu | ||
| 4952 | * Setup2:: | ||
| 4953 | * Notifications:: | ||
| 4954 | * Sending:: | ||
| 4955 | @end menu | ||
| 4956 | |||
| 4957 | @node Setup2 | ||
| 4958 | @subsubsection Setup2 | ||
| 4959 | @c %**end of header | ||
| 4960 | |||
| 4961 | When a client connects to the CORE service, it first sends a | ||
| 4962 | @code{InitMessage} which specifies options for the connection and a set of | ||
| 4963 | message type values which are supported by the application. The options | ||
| 4964 | bitmask specifies which events the client would like to be notified about. | ||
| 4965 | The options include: | ||
| 4966 | |||
| 4967 | @table @asis | ||
| 4968 | @item GNUNET_CORE_OPTION_NOTHING No notifications | ||
| 4969 | @item GNUNET_CORE_OPTION_STATUS_CHANGE Peers connecting and disconnecting | ||
| 4970 | @item GNUNET_CORE_OPTION_FULL_INBOUND All inbound messages (after | ||
| 4971 | decryption) with full payload | ||
| 4972 | @item GNUNET_CORE_OPTION_HDR_INBOUND Just the @code{MessageHeader} | ||
| 4973 | of all inbound messages | ||
| 4974 | @item GNUNET_CORE_OPTION_FULL_OUTBOUND All outbound | ||
| 4975 | messages (prior to encryption) with full payload | ||
| 4976 | @item GNUNET_CORE_OPTION_HDR_OUTBOUND Just the @code{MessageHeader} of all | ||
| 4977 | outbound messages | ||
| 4978 | @end table | ||
| 4979 | |||
| 4980 | Typical applications will only monitor for connection status changes. | ||
| 4981 | |||
| 4982 | The CORE service responds to the @code{InitMessage} with an | ||
| 4983 | @code{InitReplyMessage} which contains the peer's identity. Afterwards, | ||
| 4984 | both CORE and the client can send messages. | ||
| 4985 | |||
| 4986 | @node Notifications | ||
| 4987 | @subsubsection Notifications | ||
| 4988 | @c %**end of header | ||
| 4989 | |||
| 4990 | The CORE will send @code{ConnectNotifyMessage}s and | ||
| 4991 | @code{DisconnectNotifyMessage}s whenever peers connect or disconnect from | ||
| 4992 | the CORE (assuming their type maps overlap with the message types | ||
| 4993 | registered by the client). When the CORE receives a message that matches | ||
| 4994 | the set of message types specified during the @code{InitMessage} (or if | ||
| 4995 | monitoring is enabled in for inbound messages in the options), it sends a | ||
| 4996 | @code{NotifyTrafficMessage} with the peer identity of the sender and the | ||
| 4997 | decrypted payload. The same message format (except with | ||
| 4998 | @code{GNUNET_MESSAGE_TYPE_CORE_NOTIFY_OUTBOUND} for the message type) is | ||
| 4999 | used to notify clients monitoring outbound messages; here, the peer | ||
| 5000 | identity given is that of the receiver. | ||
| 5001 | |||
| 5002 | @node Sending | ||
| 5003 | @subsubsection Sending | ||
| 5004 | @c %**end of header | ||
| 5005 | |||
| 5006 | When a client wants to transmit a message, it first requests a | ||
| 5007 | transmission slot by sending a @code{SendMessageRequest} which specifies | ||
| 5008 | the priority, deadline and size of the message. Note that these values | ||
| 5009 | may be ignored by CORE. When CORE is ready for the message, it answers | ||
| 5010 | with a @code{SendMessageReady} response. The client can then transmit the | ||
| 5011 | payload with a @code{SendMessage} message. Note that the actual message | ||
| 5012 | size in the @code{SendMessage} is allowed to be smaller than the size in | ||
| 5013 | the original request. A client may at any time send a fresh | ||
| 5014 | @code{SendMessageRequest}, which then superceeds the previous | ||
| 5015 | @code{SendMessageRequest}, which is then no longer valid. The client can | ||
| 5016 | tell which @code{SendMessageRequest} the CORE service's | ||
| 5017 | @code{SendMessageReady} message is for as all of these messages contain a | ||
| 5018 | "unique" request ID (based on a counter incremented by the client | ||
| 5019 | for each request). | ||
| 5020 | |||
| 5021 | @cindex CORE Peer-to-Peer Protocol | ||
| 5022 | @node The CORE Peer-to-Peer Protocol | ||
| 5023 | @subsection The CORE Peer-to-Peer Protocol | ||
| 5024 | @c %**end of header | ||
| 5025 | |||
| 5026 | |||
| 5027 | @menu | ||
| 5028 | * Creating the EphemeralKeyMessage:: | ||
| 5029 | * Establishing a connection:: | ||
| 5030 | * Encryption and Decryption:: | ||
| 5031 | * Type maps:: | ||
| 5032 | @end menu | ||
| 5033 | |||
| 5034 | @cindex EphemeralKeyMessage creation | ||
| 5035 | @node Creating the EphemeralKeyMessage | ||
| 5036 | @subsubsection Creating the EphemeralKeyMessage | ||
| 5037 | @c %**end of header | ||
| 5038 | |||
| 5039 | When the CORE service starts, each peer creates a fresh ephemeral (ECC) | ||
| 5040 | public-private key pair and signs the corresponding | ||
| 5041 | @code{EphemeralKeyMessage} with its long-term key (which we usually call | ||
| 5042 | the peer's identity; the hash of the public long term key is what results | ||
| 5043 | in a @code{struct GNUNET_PeerIdentity} in all GNUnet APIs. The ephemeral | ||
| 5044 | key is ONLY used for an ECDHE | ||
| 5045 | (@uref{http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman, Elliptic-curve Diffie---Hellman}) | ||
| 5046 | exchange by the CORE service to establish symmetric session keys. A peer | ||
| 5047 | will use the same @code{EphemeralKeyMessage} for all peers for | ||
| 5048 | @code{REKEY_FREQUENCY}, which is usually 12 hours. After that time, it | ||
| 5049 | will create a fresh ephemeral key (forgetting the old one) and broadcast | ||
| 5050 | the new @code{EphemeralKeyMessage} to all connected peers, resulting in | ||
| 5051 | fresh symmetric session keys. Note that peers independently decide on | ||
| 5052 | when to discard ephemeral keys; it is not a protocol violation to discard | ||
| 5053 | keys more often. Ephemeral keys are also never stored to disk; restarting | ||
| 5054 | a peer will thus always create a fresh ephemeral key. The use of ephemeral | ||
| 5055 | keys is what provides @uref{http://en.wikipedia.org/wiki/Forward_secrecy, forward secrecy}. | ||
| 5056 | |||
| 5057 | Just before transmission, the @code{EphemeralKeyMessage} is patched to | ||
| 5058 | reflect the current sender_status, which specifies the current state of | ||
| 5059 | the connection from the point of view of the sender. The possible values | ||
| 5060 | are: | ||
| 5061 | |||
| 5062 | @itemize @bullet | ||
| 5063 | @item @code{KX_STATE_DOWN} Initial value, never used on the network | ||
| 5064 | @item @code{KX_STATE_KEY_SENT} We sent our ephemeral key, do not know the | ||
| 5065 | key of the other peer | ||
| 5066 | @item @code{KX_STATE_KEY_RECEIVED} This peer has received a valid | ||
| 5067 | ephemeral key of the other peer, but we are waiting for the other peer to | ||
| 5068 | confirm it's authenticity (ability to decode) via challenge-response. | ||
| 5069 | @item @code{KX_STATE_UP} The connection is fully up from the point of | ||
| 5070 | view of the sender (now performing keep-alives) | ||
| 5071 | @item @code{KX_STATE_REKEY_SENT} The sender has initiated a rekeying | ||
| 5072 | operation; the other peer has so far failed to confirm a working | ||
| 5073 | connection using the new ephemeral key | ||
| 5074 | @end itemize | ||
| 5075 | |||
| 5076 | @node Establishing a connection | ||
| 5077 | @subsubsection Establishing a connection | ||
| 5078 | @c %**end of header | ||
| 5079 | |||
| 5080 | Peers begin their interaction by sending a @code{EphemeralKeyMessage} to | ||
| 5081 | the other peer once the TRANSPORT service notifies the CORE service about | ||
| 5082 | the connection. | ||
| 5083 | A peer receiving an @code{EphemeralKeyMessage} with a status | ||
| 5084 | indicating that the sender does not have the receiver's ephemeral key, the | ||
| 5085 | receiver's @code{EphemeralKeyMessage} is sent in response. | ||
| 5086 | Additionally, if the receiver has not yet confirmed the authenticity of | ||
| 5087 | the sender, it also sends an (encrypted)@code{PingMessage} with a | ||
| 5088 | challenge (and the identity of the target) to the other peer. Peers | ||
| 5089 | receiving a @code{PingMessage} respond with an (encrypted) | ||
| 5090 | @code{PongMessage} which includes the challenge. Peers receiving a | ||
| 5091 | @code{PongMessage} check the challenge, and if it matches set the | ||
| 5092 | connection to @code{KX_STATE_UP}. | ||
| 5093 | |||
| 5094 | @node Encryption and Decryption | ||
| 5095 | @subsubsection Encryption and Decryption | ||
| 5096 | @c %**end of header | ||
| 5097 | |||
| 5098 | All functions related to the key exchange and encryption/decryption of | ||
| 5099 | messages can be found in @file{gnunet-service-core_kx.c} (except for the | ||
| 5100 | cryptographic primitives, which are in @file{util/crypto*.c}). | ||
| 5101 | Given the key material from ECDHE, a Key derivation function | ||
| 5102 | (@uref{https://en.wikipedia.org/wiki/Key_derivation_function, Key derivation function}) | ||
| 5103 | is used to derive two pairs of encryption and decryption keys for AES-256 | ||
| 5104 | and TwoFish, as well as initialization vectors and authentication keys | ||
| 5105 | (for HMAC | ||
| 5106 | (@uref{https://en.wikipedia.org/wiki/HMAC, HMAC})). | ||
| 5107 | The HMAC is computed over the encrypted payload. | ||
| 5108 | Encrypted messages include an iv_seed and the HMAC in the header. | ||
| 5109 | |||
| 5110 | Each encrypted message in the CORE service includes a sequence number and | ||
| 5111 | a timestamp in the encrypted payload. The CORE service remembers the | ||
| 5112 | largest observed sequence number and a bit-mask which represents which of | ||
| 5113 | the previous 32 sequence numbers were already used. | ||
| 5114 | Messages with sequence numbers lower than the largest observed sequence | ||
| 5115 | number minus 32 are discarded. Messages with a timestamp that is less | ||
| 5116 | than @code{REKEY_TOLERANCE} off (5 minutes) are also discarded. This of | ||
| 5117 | course means that system clocks need to be reasonably synchronized for | ||
| 5118 | peers to be able to communicate. Additionally, as the ephemeral key | ||
| 5119 | changes every 12 hours, a peer would not even be able to decrypt messages | ||
| 5120 | older than 12 hours. | ||
| 5121 | |||
| 5122 | @node Type maps | ||
| 5123 | @subsubsection Type maps | ||
| 5124 | @c %**end of header | ||
| 5125 | |||
| 5126 | Once an encrypted connection has been established, peers begin to exchange | ||
| 5127 | type maps. Type maps are used to allow the CORE service to determine which | ||
| 5128 | (encrypted) connections should be shown to which applications. A type map | ||
| 5129 | is an array of 65536 bits representing the different types of messages | ||
| 5130 | understood by applications using the CORE service. Each CORE service | ||
| 5131 | maintains this map, simply by setting the respective bit for each message | ||
| 5132 | type supported by any of the applications using the CORE service. Note | ||
| 5133 | that bits for message types embedded in higher-level protocols (such as | ||
| 5134 | MESH) will not be included in these type maps. | ||
| 5135 | |||
| 5136 | Typically, the type map of a peer will be sparse. Thus, the CORE service | ||
| 5137 | attempts to compress its type map using @code{gzip}-style compression | ||
| 5138 | ("deflate") prior to transmission. However, if the compression fails to | ||
| 5139 | compact the map, the map may also be transmitted without compression | ||
| 5140 | (resulting in @code{GNUNET_MESSAGE_TYPE_CORE_COMPRESSED_TYPE_MAP} or | ||
| 5141 | @code{GNUNET_MESSAGE_TYPE_CORE_BINARY_TYPE_MAP} messages respectively). | ||
| 5142 | Upon receiving a type map, the respective CORE service notifies | ||
| 5143 | applications about the connection to the other peer if they support any | ||
| 5144 | message type indicated in the type map (or no message type at all). | ||
| 5145 | If the CORE service experience a connect or disconnect event from an | ||
| 5146 | application, it updates its type map (setting or unsetting the respective | ||
| 5147 | bits) and notifies its neighbours about the change. | ||
| 5148 | The CORE services of the neighbours then in turn generate connect and | ||
| 5149 | disconnect events for the peer that sent the type map for their respective | ||
| 5150 | applications. As CORE messages may be lost, the CORE service confirms | ||
| 5151 | receiving a type map by sending back a | ||
| 5152 | @code{GNUNET_MESSAGE_TYPE_CORE_CONFIRM_TYPE_MAP}. If such a confirmation | ||
| 5153 | (with the correct hash of the type map) is not received, the sender will | ||
| 5154 | retransmit the type map (with exponential back-off). | ||
| 5155 | |||
| 5156 | @cindex CADET Subsystem | ||
| 5157 | @node CADET Subsystem | ||
| 5158 | @section CADET Subsystem | ||
| 5159 | |||
| 5160 | The CADET subsystem in GNUnet is responsible for secure end-to-end | ||
| 5161 | communications between nodes in the GNUnet overlay network. CADET builds | ||
| 5162 | on the CORE subsystem which provides for the link-layer communication and | ||
| 5163 | then adds routing, forwarding and additional security to the connections. | ||
| 5164 | CADET offers the same cryptographic services as CORE, but on an | ||
| 5165 | end-to-end level. This is done so peers retransmitting traffic on behalf | ||
| 5166 | of other peers cannot access the payload data. | ||
| 5167 | |||
| 5168 | @itemize @bullet | ||
| 5169 | @item CADET provides confidentiality with so-called perfect forward | ||
| 5170 | secrecy; we use ECDHE powered by Curve25519 for the key exchange and then | ||
| 5171 | use symmetric encryption, encrypting with both AES-256 and Twofish | ||
| 5172 | @item authentication is achieved by signing the ephemeral keys using | ||
| 5173 | Ed25519, a deterministic variant of ECDSA | ||
| 5174 | @item integrity protection (using SHA-512 to do encrypt-then-MAC, although | ||
| 5175 | only 256 bits are sent to reduce overhead) | ||
| 5176 | @item replay protection (using nonces, timestamps, challenge-response, | ||
| 5177 | message counters and ephemeral keys) | ||
| 5178 | @item liveness (keep-alive messages, timeout) | ||
| 5179 | @end itemize | ||
| 5180 | |||
| 5181 | Additional to the CORE-like security benefits, CADET offers other | ||
| 5182 | properties that make it a more universal service than CORE. | ||
| 5183 | |||
| 5184 | @itemize @bullet | ||
| 5185 | @item CADET can establish channels to arbitrary peers in GNUnet. If a | ||
| 5186 | peer is not immediately reachable, CADET will find a path through the | ||
| 5187 | network and ask other peers to retransmit the traffic on its behalf. | ||
| 5188 | @item CADET offers (optional) reliability mechanisms. In a reliable | ||
| 5189 | channel traffic is guaranteed to arrive complete, unchanged and in-order. | ||
| 5190 | @item CADET takes care of flow and congestion control mechanisms, not | ||
| 5191 | allowing the sender to send more traffic than the receiver or the network | ||
| 5192 | are able to process. | ||
| 5193 | @end itemize | ||
| 5194 | |||
| 5195 | @menu | ||
| 5196 | * libgnunetcadet:: | ||
| 5197 | @end menu | ||
| 5198 | |||
| 5199 | @cindex libgnunetcadet | ||
| 5200 | @node libgnunetcadet | ||
| 5201 | @subsection libgnunetcadet | ||
| 5202 | |||
| 5203 | |||
| 5204 | The CADET API (defined in @file{gnunet_cadet_service.h}) is the | ||
| 5205 | messaging API used by P2P applications built using GNUnet. | ||
| 5206 | It provides applications the ability to send and receive encrypted | ||
| 5207 | messages to any peer participating in GNUnet. | ||
| 5208 | The API is heavily base on the CORE API. | ||
| 5209 | |||
| 5210 | CADET delivers messages to other peers in "channels". | ||
| 5211 | A channel is a permanent connection defined by a destination peer | ||
| 5212 | (identified by its public key) and a port number. | ||
| 5213 | Internally, CADET tunnels all channels towards a destination peer | ||
| 5214 | using one session key and relays the data on multiple "connections", | ||
| 5215 | independent from the channels. | ||
| 5216 | |||
| 5217 | Each channel has optional parameters, the most important being the | ||
| 5218 | reliability flag. | ||
| 5219 | Should a message get lost on TRANSPORT/CORE level, if a channel is | ||
| 5220 | created with as reliable, CADET will retransmit the lost message and | ||
| 5221 | deliver it in order to the destination application. | ||
| 5222 | |||
| 5223 | To communicate with other peers using CADET, it is necessary to first | ||
| 5224 | connect to the service using @code{GNUNET_CADET_connect}. | ||
| 5225 | This function takes several parameters in form of callbacks, to allow the | ||
| 5226 | client to react to various events, like incoming channels or channels that | ||
| 5227 | terminate, as well as specify a list of ports the client wishes to listen | ||
| 5228 | to (at the moment it is not possible to start listening on further ports | ||
| 5229 | once connected, but nothing prevents a client to connect several times to | ||
| 5230 | CADET, even do one connection per listening port). | ||
| 5231 | The function returns a handle which has to be used for any further | ||
| 5232 | interaction with the service. | ||
| 5233 | |||
| 5234 | To connect to a remote peer a client has to call the | ||
| 5235 | @code{GNUNET_CADET_channel_create} function. The most important parameters | ||
| 5236 | given are the remote peer's identity (it public key) and a port, which | ||
| 5237 | specifies which application on the remote peer to connect to, similar to | ||
| 5238 | TCP/UDP ports. CADET will then find the peer in the GNUnet network and | ||
| 5239 | establish the proper low-level connections and do the necessary key | ||
| 5240 | exchanges to assure and authenticated, secure and verified communication. | ||
| 5241 | Similar to @code{GNUNET_CADET_connect},@code{GNUNET_CADET_create_channel} | ||
| 5242 | returns a handle to interact with the created channel. | ||
| 5243 | |||
| 5244 | For every message the client wants to send to the remote application, | ||
| 5245 | @code{GNUNET_CADET_notify_transmit_ready} must be called, indicating the | ||
| 5246 | channel on which the message should be sent and the size of the message | ||
| 5247 | (but not the message itself!). Once CADET is ready to send the message, | ||
| 5248 | the provided callback will fire, and the message contents are provided to | ||
| 5249 | this callback. | ||
| 5250 | |||
| 5251 | Please note the CADET does not provide an explicit notification of when a | ||
| 5252 | channel is connected. In loosely connected networks, like big wireless | ||
| 5253 | mesh networks, this can take several seconds, even minutes in the worst | ||
| 5254 | case. To be alerted when a channel is online, a client can call | ||
| 5255 | @code{GNUNET_CADET_notify_transmit_ready} immediately after | ||
| 5256 | @code{GNUNET_CADET_create_channel}. When the callback is activated, it | ||
| 5257 | means that the channel is online. The callback can give 0 bytes to CADET | ||
| 5258 | if no message is to be sent, this is OK. | ||
| 5259 | |||
| 5260 | If a transmission was requested but before the callback fires it is no | ||
| 5261 | longer needed, it can be canceled with | ||
| 5262 | @code{GNUNET_CADET_notify_transmit_ready_cancel}, which uses the handle | ||
| 5263 | given back by @code{GNUNET_CADET_notify_transmit_ready}. | ||
| 5264 | As in the case of CORE, only one message can be requested at a time: a | ||
| 5265 | client must not call @code{GNUNET_CADET_notify_transmit_ready} again until | ||
| 5266 | the callback is called or the request is canceled. | ||
| 5267 | |||
| 5268 | When a channel is no longer needed, a client can call | ||
| 5269 | @code{GNUNET_CADET_channel_destroy} to get rid of it. | ||
| 5270 | Note that CADET will try to transmit all pending traffic before notifying | ||
| 5271 | the remote peer of the destruction of the channel, including | ||
| 5272 | retransmitting lost messages if the channel was reliable. | ||
| 5273 | |||
| 5274 | Incoming channels, channels being closed by the remote peer, and traffic | ||
| 5275 | on any incoming or outgoing channels are given to the client when CADET | ||
| 5276 | executes the callbacks given to it at the time of | ||
| 5277 | @code{GNUNET_CADET_connect}. | ||
| 5278 | |||
| 5279 | Finally, when an application no longer wants to use CADET, it should call | ||
| 5280 | @code{GNUNET_CADET_disconnect}, but first all channels and pending | ||
| 5281 | transmissions must be closed (otherwise CADET will complain). | ||
| 5282 | |||
| 5283 | @cindex NSE Subsystem | ||
| 5284 | @node NSE Subsystem | ||
| 5285 | @section NSE Subsystem | ||
| 5286 | |||
| 5287 | |||
| 5288 | NSE stands for @dfn{Network Size Estimation}. The NSE subsystem provides | ||
| 5289 | other subsystems and users with a rough estimate of the number of peers | ||
| 5290 | currently participating in the GNUnet overlay. | ||
| 5291 | The computed value is not a precise number as producing a precise number | ||
| 5292 | in a decentralized, efficient and secure way is impossible. | ||
| 5293 | While NSE's estimate is inherently imprecise, NSE also gives the expected | ||
| 5294 | range. For a peer that has been running in a stable network for a | ||
| 5295 | while, the real network size will typically (99.7% of the time) be in the | ||
| 5296 | range of [2/3 estimate, 3/2 estimate]. We will now give an overview of the | ||
| 5297 | algorithm used to calculate the estimate; | ||
| 5298 | all of the details can be found in this technical report. | ||
| 5299 | |||
| 5300 | @c FIXME: link to the report. | ||
| 5301 | |||
| 5302 | @menu | ||
| 5303 | * Motivation:: | ||
| 5304 | * Principle:: | ||
| 5305 | * libgnunetnse:: | ||
| 5306 | * The NSE Client-Service Protocol:: | ||
| 5307 | * The NSE Peer-to-Peer Protocol:: | ||
| 5308 | @end menu | ||
| 5309 | |||
| 5310 | @node Motivation | ||
| 5311 | @subsection Motivation | ||
| 5312 | |||
| 5313 | |||
| 5314 | Some subsystems, like DHT, need to know the size of the GNUnet network to | ||
| 5315 | optimize some parameters of their own protocol. The decentralized nature | ||
| 5316 | of GNUnet makes efficient and securely counting the exact number of peers | ||
| 5317 | infeasible. Although there are several decentralized algorithms to count | ||
| 5318 | the number of peers in a system, so far there is none to do so securely. | ||
| 5319 | Other protocols may allow any malicious peer to manipulate the final | ||
| 5320 | result or to take advantage of the system to perform | ||
| 5321 | @dfn{Denial of Service} (DoS) attacks against the network. | ||
| 5322 | GNUnet's NSE protocol avoids these drawbacks. | ||
| 5323 | |||
| 5324 | |||
| 5325 | |||
| 5326 | @menu | ||
| 5327 | * Security:: | ||
| 5328 | @end menu | ||
| 5329 | |||
| 5330 | @cindex NSE security | ||
| 5331 | @cindex nse security | ||
| 5332 | @node Security | ||
| 5333 | @subsubsection Security | ||
| 5334 | |||
| 5335 | |||
| 5336 | The NSE subsystem is designed to be resilient against these attacks. | ||
| 5337 | It uses @uref{http://en.wikipedia.org/wiki/Proof-of-work_system, proofs of work} | ||
| 5338 | to prevent one peer from impersonating a large number of participants, | ||
| 5339 | which would otherwise allow an adversary to artificially inflate the | ||
| 5340 | estimate. | ||
| 5341 | The DoS protection comes from the time-based nature of the protocol: | ||
| 5342 | the estimates are calculated periodically and out-of-time traffic is | ||
| 5343 | either ignored or stored for later retransmission by benign peers. | ||
| 5344 | In particular, peers cannot trigger global network communication at will. | ||
| 5345 | |||
| 5346 | @cindex NSE principle | ||
| 5347 | @cindex nse principle | ||
| 5348 | @node Principle | ||
| 5349 | @subsection Principle | ||
| 5350 | |||
| 5351 | |||
| 5352 | The algorithm calculates the estimate by finding the globally closest | ||
| 5353 | peer ID to a random, time-based value. | ||
| 5354 | |||
| 5355 | The idea is that the closer the ID is to the random value, the more | ||
| 5356 | "densely packed" the ID space is, and therefore, more peers are in the | ||
| 5357 | network. | ||
| 5358 | |||
| 5359 | |||
| 5360 | |||
| 5361 | @menu | ||
| 5362 | * Example:: | ||
| 5363 | * Algorithm:: | ||
| 5364 | * Target value:: | ||
| 5365 | * Timing:: | ||
| 5366 | * Controlled Flooding:: | ||
| 5367 | * Calculating the estimate:: | ||
| 5368 | @end menu | ||
| 5369 | |||
| 5370 | @node Example | ||
| 5371 | @subsubsection Example | ||
| 5372 | |||
| 5373 | |||
| 5374 | Suppose all peers have IDs between 0 and 100 (our ID space), and the | ||
| 5375 | random value is 42. | ||
| 5376 | If the closest peer has the ID 70 we can imagine that the average | ||
| 5377 | "distance" between peers is around 30 and therefore the are around 3 | ||
| 5378 | peers in the whole ID space. On the other hand, if the closest peer has | ||
| 5379 | the ID 44, we can imagine that the space is rather packed with peers, | ||
| 5380 | maybe as much as 50 of them. | ||
| 5381 | Naturally, we could have been rather unlucky, and there is only one peer | ||
| 5382 | and happens to have the ID 44. Thus, the current estimate is calculated | ||
| 5383 | as the average over multiple rounds, and not just a single sample. | ||
| 5384 | |||
| 5385 | @node Algorithm | ||
| 5386 | @subsubsection Algorithm | ||
| 5387 | |||
| 5388 | |||
| 5389 | Given that example, one can imagine that the job of the subsystem is to | ||
| 5390 | efficiently communicate the ID of the closest peer to the target value | ||
| 5391 | to all the other peers, who will calculate the estimate from it. | ||
| 5392 | |||
| 5393 | @node Target value | ||
| 5394 | @subsubsection Target value | ||
| 5395 | |||
| 5396 | @c %**end of header | ||
| 5397 | |||
| 5398 | The target value itself is generated by hashing the current time, rounded | ||
| 5399 | down to an agreed value. If the rounding amount is 1h (default) and the | ||
| 5400 | time is 12:34:56, the time to hash would be 12:00:00. The process is | ||
| 5401 | repeated each rounding amount (in this example would be every hour). | ||
| 5402 | Every repetition is called a round. | ||
| 5403 | |||
| 5404 | @node Timing | ||
| 5405 | @subsubsection Timing | ||
| 5406 | @c %**end of header | ||
| 5407 | |||
| 5408 | The NSE subsystem has some timing control to avoid everybody broadcasting | ||
| 5409 | its ID all at one. Once each peer has the target random value, it | ||
| 5410 | compares its own ID to the target and calculates the hypothetical size of | ||
| 5411 | the network if that peer were to be the closest. | ||
| 5412 | Then it compares the hypothetical size with the estimate from the previous | ||
| 5413 | rounds. For each value there is an associated point in the period, | ||
| 5414 | let's call it "broadcast time". If its own hypothetical estimate | ||
| 5415 | is the same as the previous global estimate, its "broadcast time" will be | ||
| 5416 | in the middle of the round. If its bigger it will be earlier and if its | ||
| 5417 | smaller (the most likely case) it will be later. This ensures that the | ||
| 5418 | peers closest to the target value start broadcasting their ID the first. | ||
| 5419 | |||
| 5420 | @node Controlled Flooding | ||
| 5421 | @subsubsection Controlled Flooding | ||
| 5422 | |||
| 5423 | @c %**end of header | ||
| 5424 | |||
| 5425 | When a peer receives a value, first it verifies that it is closer than the | ||
| 5426 | closest value it had so far, otherwise it answers the incoming message | ||
| 5427 | with a message containing the better value. Then it checks a proof of | ||
| 5428 | work that must be included in the incoming message, to ensure that the | ||
| 5429 | other peer's ID is not made up (otherwise a malicious peer could claim to | ||
| 5430 | have an ID of exactly the target value every round). Once validated, it | ||
| 5431 | compares the broadcast time of the received value with the current time | ||
| 5432 | and if it's not too early, sends the received value to its neighbors. | ||
| 5433 | Otherwise it stores the value until the correct broadcast time comes. | ||
| 5434 | This prevents unnecessary traffic of sub-optimal values, since a better | ||
| 5435 | value can come before the broadcast time, rendering the previous one | ||
| 5436 | obsolete and saving the traffic that would have been used to broadcast it | ||
| 5437 | to the neighbors. | ||
| 5438 | |||
| 5439 | @node Calculating the estimate | ||
| 5440 | @subsubsection Calculating the estimate | ||
| 5441 | |||
| 5442 | @c %**end of header | ||
| 5443 | |||
| 5444 | Once the closest ID has been spread across the network each peer gets the | ||
| 5445 | exact distance between this ID and the target value of the round and | ||
| 5446 | calculates the estimate with a mathematical formula described in the tech | ||
| 5447 | report. The estimate generated with this method for a single round is not | ||
| 5448 | very precise. Remember the case of the example, where the only peer is the | ||
| 5449 | ID 44 and we happen to generate the target value 42, thinking there are | ||
| 5450 | 50 peers in the network. Therefore, the NSE subsystem remembers the last | ||
| 5451 | 64 estimates and calculates an average over them, giving a result of which | ||
| 5452 | usually has one bit of uncertainty (the real size could be half of the | ||
| 5453 | estimate or twice as much). Note that the actual network size is | ||
| 5454 | calculated in powers of two of the raw input, thus one bit of uncertainty | ||
| 5455 | means a factor of two in the size estimate. | ||
| 5456 | |||
| 5457 | @cindex libgnunetnse | ||
| 5458 | @node libgnunetnse | ||
| 5459 | @subsection libgnunetnse | ||
| 5460 | |||
| 5461 | @c %**end of header | ||
| 5462 | |||
| 5463 | The NSE subsystem has the simplest API of all services, with only two | ||
| 5464 | calls: @code{GNUNET_NSE_connect} and @code{GNUNET_NSE_disconnect}. | ||
| 5465 | |||
| 5466 | The connect call gets a callback function as a parameter and this function | ||
| 5467 | is called each time the network agrees on an estimate. This usually is | ||
| 5468 | once per round, with some exceptions: if the closest peer has a late | ||
| 5469 | local clock and starts spreading its ID after everyone else agreed on a | ||
| 5470 | value, the callback might be activated twice in a round, the second value | ||
| 5471 | being always bigger than the first. The default round time is set to | ||
| 5472 | 1 hour. | ||
| 5473 | |||
| 5474 | The disconnect call disconnects from the NSE subsystem and the callback | ||
| 5475 | is no longer called with new estimates. | ||
| 5476 | |||
| 5477 | |||
| 5478 | |||
| 5479 | @menu | ||
| 5480 | * Results:: | ||
| 5481 | * libgnunetnse - Examples:: | ||
| 5482 | @end menu | ||
| 5483 | |||
| 5484 | @node Results | ||
| 5485 | @subsubsection Results | ||
| 5486 | |||
| 5487 | @c %**end of header | ||
| 5488 | |||
| 5489 | The callback provides two values: the average and the | ||
| 5490 | @uref{http://en.wikipedia.org/wiki/Standard_deviation, standard deviation} | ||
| 5491 | of the last 64 rounds. The values provided by the callback function are | ||
| 5492 | logarithmic, this means that the real estimate numbers can be obtained by | ||
| 5493 | calculating 2 to the power of the given value (2average). From a | ||
| 5494 | statistics point of view this means that: | ||
| 5495 | |||
| 5496 | @itemize @bullet | ||
| 5497 | @item 68% of the time the real size is included in the interval | ||
| 5498 | [(2average-stddev), 2] | ||
| 5499 | @item 95% of the time the real size is included in the interval | ||
| 5500 | [(2average-2*stddev, 2^average+2*stddev] | ||
| 5501 | @item 99.7% of the time the real size is included in the interval | ||
| 5502 | [(2average-3*stddev, 2average+3*stddev] | ||
| 5503 | @end itemize | ||
| 5504 | |||
| 5505 | The expected standard variation for 64 rounds in a network of stable size | ||
| 5506 | is 0.2. Thus, we can say that normally: | ||
| 5507 | |||
| 5508 | @itemize @bullet | ||
| 5509 | @item 68% of the time the real size is in the range [-13%, +15%] | ||
| 5510 | @item 95% of the time the real size is in the range [-24%, +32%] | ||
| 5511 | @item 99.7% of the time the real size is in the range [-34%, +52%] | ||
| 5512 | @end itemize | ||
| 5513 | |||
| 5514 | As said in the introduction, we can be quite sure that usually the real | ||
| 5515 | size is between one third and three times the estimate. This can of | ||
| 5516 | course vary with network conditions. | ||
| 5517 | Thus, applications may want to also consider the provided standard | ||
| 5518 | deviation value, not only the average (in particular, if the standard | ||
| 5519 | variation is very high, the average maybe meaningless: the network size is | ||
| 5520 | changing rapidly). | ||
| 5521 | |||
| 5522 | @node libgnunetnse - Examples | ||
| 5523 | @subsubsection libgnunetnse -Examples | ||
| 5524 | |||
| 5525 | @c %**end of header | ||
| 5526 | |||
| 5527 | Let's close with a couple examples. | ||
| 5528 | |||
| 5529 | @table @asis | ||
| 5530 | |||
| 5531 | @item Average: 10, std dev: 1 Here the estimate would be | ||
| 5532 | 2^10 = 1024 peers. (The range in which we can be 95% sure is: | ||
| 5533 | [2^8, 2^12] = [256, 4096]. We can be very (>99.7%) sure that the network | ||
| 5534 | is not a hundred peers and absolutely sure that it is not a million peers, | ||
| 5535 | but somewhere around a thousand.) | ||
| 5536 | |||
| 5537 | @item Average 22, std dev: 0.2 Here the estimate would be | ||
| 5538 | 2^22 = 4 Million peers. (The range in which we can be 99.7% sure | ||
| 5539 | is: [2^21.4, 2^22.6] = [2.8M, 6.3M]. We can be sure that the network size | ||
| 5540 | is around four million, with absolutely way of it being 1 million.) | ||
| 5541 | |||
| 5542 | @end table | ||
| 5543 | |||
| 5544 | To put this in perspective, if someone remembers the LHC Higgs boson | ||
| 5545 | results, were announced with "5 sigma" and "6 sigma" certainties. In this | ||
| 5546 | case a 5 sigma minimum would be 2 million and a 6 sigma minimum, | ||
| 5547 | 1.8 million. | ||
| 5548 | |||
| 5549 | @node The NSE Client-Service Protocol | ||
| 5550 | @subsection The NSE Client-Service Protocol | ||
| 5551 | |||
| 5552 | @c %**end of header | ||
| 5553 | |||
| 5554 | As with the API, the client-service protocol is very simple, only has 2 | ||
| 5555 | different messages, defined in @code{src/nse/nse.h}: | ||
| 5556 | |||
| 5557 | @itemize @bullet | ||
| 5558 | @item @code{GNUNET_MESSAGE_TYPE_NSE_START}@ This message has no parameters | ||
| 5559 | and is sent from the client to the service upon connection. | ||
| 5560 | @item @code{GNUNET_MESSAGE_TYPE_NSE_ESTIMATE}@ This message is sent from | ||
| 5561 | the service to the client for every new estimate and upon connection. | ||
| 5562 | Contains a timestamp for the estimate, the average and the standard | ||
| 5563 | deviation for the respective round. | ||
| 5564 | @end itemize | ||
| 5565 | |||
| 5566 | When the @code{GNUNET_NSE_disconnect} API call is executed, the client | ||
| 5567 | simply disconnects from the service, with no message involved. | ||
| 5568 | |||
| 5569 | @cindex NSE Peer-to-Peer Protocol | ||
| 5570 | @node The NSE Peer-to-Peer Protocol | ||
| 5571 | @subsection The NSE Peer-to-Peer Protocol | ||
| 5572 | |||
| 5573 | @c %**end of header | ||
| 5574 | |||
| 5575 | The NSE subsystem only has one message in the P2P protocol, the | ||
| 5576 | @code{GNUNET_MESSAGE_TYPE_NSE_P2P_FLOOD} message. | ||
| 5577 | |||
| 5578 | This message key contents are the timestamp to identify the round | ||
| 5579 | (differences in system clocks may cause some peers to send messages way | ||
| 5580 | too early or way too late, so the timestamp allows other peers to | ||
| 5581 | identify such messages easily), the | ||
| 5582 | @uref{http://en.wikipedia.org/wiki/Proof-of-work_system, proof of work} | ||
| 5583 | used to make it difficult to mount a | ||
| 5584 | @uref{http://en.wikipedia.org/wiki/Sybil_attack, Sybil attack}, and the | ||
| 5585 | public key, which is used to verify the signature on the message. | ||
| 5586 | |||
| 5587 | Every peer stores a message for the previous, current and next round. The | ||
| 5588 | messages for the previous and current round are given to peers that | ||
| 5589 | connect to us. The message for the next round is simply stored until our | ||
| 5590 | system clock advances to the next round. The message for the current round | ||
| 5591 | is what we are flooding the network with right now. | ||
| 5592 | At the beginning of each round the peer does the following: | ||
| 5593 | |||
| 5594 | @itemize @bullet | ||
| 5595 | @item calculates its own distance to the target value | ||
| 5596 | @item creates, signs and stores the message for the current round (unless | ||
| 5597 | it has a better message in the "next round" slot which came early in the | ||
| 5598 | previous round) | ||
| 5599 | @item calculates, based on the stored round message (own or received) when | ||
| 5600 | to start flooding it to its neighbors | ||
| 5601 | @end itemize | ||
| 5602 | |||
| 5603 | Upon receiving a message the peer checks the validity of the message | ||
| 5604 | (round, proof of work, signature). The next action depends on the | ||
| 5605 | contents of the incoming message: | ||
| 5606 | |||
| 5607 | @itemize @bullet | ||
| 5608 | @item if the message is worse than the current stored message, the peer | ||
| 5609 | sends the current message back immediately, to stop the other peer from | ||
| 5610 | spreading suboptimal results | ||
| 5611 | @item if the message is better than the current stored message, the peer | ||
| 5612 | stores the new message and calculates the new target time to start | ||
| 5613 | spreading it to its neighbors (excluding the one the message came from) | ||
| 5614 | @item if the message is for the previous round, it is compared to the | ||
| 5615 | message stored in the "previous round slot", which may then be updated | ||
| 5616 | @item if the message is for the next round, it is compared to the message | ||
| 5617 | stored in the "next round slot", which again may then be updated | ||
| 5618 | @end itemize | ||
| 5619 | |||
| 5620 | Finally, when it comes to send the stored message for the current round to | ||
| 5621 | the neighbors there is a random delay added for each neighbor, to avoid | ||
| 5622 | traffic spikes and minimize cross-messages. | ||
| 5623 | |||
| 5624 | @cindex HOSTLIST Subsystem | ||
| 5625 | @node HOSTLIST Subsystem | ||
| 5626 | @section HOSTLIST Subsystem | ||
| 5627 | |||
| 5628 | @c %**end of header | ||
| 5629 | |||
| 5630 | Peers in the GNUnet overlay network need address information so that they | ||
| 5631 | can connect with other peers. GNUnet uses so called HELLO messages to | ||
| 5632 | store and exchange peer addresses. | ||
| 5633 | GNUnet provides several methods for peers to obtain this information: | ||
| 5634 | |||
| 5635 | @itemize @bullet | ||
| 5636 | @item out-of-band exchange of HELLO messages (manually, using for example | ||
| 5637 | gnunet-peerinfo) | ||
| 5638 | @item HELLO messages shipped with GNUnet (automatic with distribution) | ||
| 5639 | @item UDP neighbor discovery in LAN (IPv4 broadcast, IPv6 multicast) | ||
| 5640 | @item topology gossiping (learning from other peers we already connected | ||
| 5641 | to), and | ||
| 5642 | @item the HOSTLIST daemon covered in this section, which is particularly | ||
| 5643 | relevant for bootstrapping new peers. | ||
| 5644 | @end itemize | ||
| 5645 | |||
| 5646 | New peers have no existing connections (and thus cannot learn from gossip | ||
| 5647 | among peers), may not have other peers in their LAN and might be started | ||
| 5648 | with an outdated set of HELLO messages from the distribution. | ||
| 5649 | In this case, getting new peers to connect to the network requires either | ||
| 5650 | manual effort or the use of a HOSTLIST to obtain HELLOs. | ||
| 5651 | |||
| 5652 | @menu | ||
| 5653 | * HELLOs:: | ||
| 5654 | * Overview for the HOSTLIST subsystem:: | ||
| 5655 | * Interacting with the HOSTLIST daemon:: | ||
| 5656 | * Hostlist security address validation:: | ||
| 5657 | * The HOSTLIST daemon:: | ||
| 5658 | * The HOSTLIST server:: | ||
| 5659 | * The HOSTLIST client:: | ||
| 5660 | * Usage:: | ||
| 5661 | @end menu | ||
| 5662 | |||
| 5663 | @node HELLOs | ||
| 5664 | @subsection HELLOs | ||
| 5665 | |||
| 5666 | @c %**end of header | ||
| 5667 | |||
| 5668 | The basic information peers require to connect to other peers are | ||
| 5669 | contained in so called HELLO messages you can think of as a business card. | ||
| 5670 | Besides the identity of the peer (based on the cryptographic public key) a | ||
| 5671 | HELLO message may contain address information that specifies ways to | ||
| 5672 | contact a peer. By obtaining HELLO messages, a peer can learn how to | ||
| 5673 | contact other peers. | ||
| 5674 | |||
| 5675 | @node Overview for the HOSTLIST subsystem | ||
| 5676 | @subsection Overview for the HOSTLIST subsystem | ||
| 5677 | |||
| 5678 | @c %**end of header | ||
| 5679 | |||
| 5680 | The HOSTLIST subsystem provides a way to distribute and obtain contact | ||
| 5681 | information to connect to other peers using a simple HTTP GET request. | ||
| 5682 | It's implementation is split in three parts, the main file for the daemon | ||
| 5683 | itself (@file{gnunet-daemon-hostlist.c}), the HTTP client used to download | ||
| 5684 | peer information (@file{hostlist-client.c}) and the server component used | ||
| 5685 | to provide this information to other peers (@file{hostlist-server.c}). | ||
| 5686 | The server is basically a small HTTP web server (based on GNU | ||
| 5687 | libmicrohttpd) which provides a list of HELLOs known to the local peer for | ||
| 5688 | download. The client component is basically a HTTP client | ||
| 5689 | (based on libcurl) which can download hostlists from one or more websites. | ||
| 5690 | The hostlist format is a binary blob containing a sequence of HELLO | ||
| 5691 | messages. Note that any HTTP server can theoretically serve a hostlist, | ||
| 5692 | the build-in hostlist server makes it simply convenient to offer this | ||
| 5693 | service. | ||
| 5694 | |||
| 5695 | |||
| 5696 | @menu | ||
| 5697 | * Features:: | ||
| 5698 | * HOSTLIST - Limitations:: | ||
| 5699 | @end menu | ||
| 5700 | |||
| 5701 | @node Features | ||
| 5702 | @subsubsection Features | ||
| 5703 | |||
| 5704 | @c %**end of header | ||
| 5705 | |||
| 5706 | The HOSTLIST daemon can: | ||
| 5707 | |||
| 5708 | @itemize @bullet | ||
| 5709 | @item provide HELLO messages with validated addresses obtained from | ||
| 5710 | PEERINFO to download for other peers | ||
| 5711 | @item download HELLO messages and forward these message to the TRANSPORT | ||
| 5712 | subsystem for validation | ||
| 5713 | @item advertises the URL of this peer's hostlist address to other peers | ||
| 5714 | via gossip | ||
| 5715 | @item automatically learn about hostlist servers from the gossip of other | ||
| 5716 | peers | ||
| 5717 | @end itemize | ||
| 5718 | |||
| 5719 | @node HOSTLIST - Limitations | ||
| 5720 | @subsubsection HOSTLIST - Limitations | ||
| 5721 | |||
| 5722 | @c %**end of header | ||
| 5723 | |||
| 5724 | The HOSTLIST daemon does not: | ||
| 5725 | |||
| 5726 | @itemize @bullet | ||
| 5727 | @item verify the cryptographic information in the HELLO messages | ||
| 5728 | @item verify the address information in the HELLO messages | ||
| 5729 | @end itemize | ||
| 5730 | |||
| 5731 | @node Interacting with the HOSTLIST daemon | ||
| 5732 | @subsection Interacting with the HOSTLIST daemon | ||
| 5733 | |||
| 5734 | @c %**end of header | ||
| 5735 | |||
| 5736 | The HOSTLIST subsystem is currently implemented as a daemon, so there is | ||
| 5737 | no need for the user to interact with it and therefore there is no | ||
| 5738 | command line tool and no API to communicate with the daemon. In the | ||
| 5739 | future, we can envision changing this to allow users to manually trigger | ||
| 5740 | the download of a hostlist. | ||
| 5741 | |||
| 5742 | Since there is no command line interface to interact with HOSTLIST, the | ||
| 5743 | only way to interact with the hostlist is to use STATISTICS to obtain or | ||
| 5744 | modify information about the status of HOSTLIST: | ||
| 5745 | |||
| 5746 | @example | ||
| 5747 | $ gnunet-statistics -s hostlist | ||
| 5748 | @end example | ||
| 5749 | |||
| 5750 | @noindent | ||
| 5751 | In particular, HOSTLIST includes a @strong{persistent} value in statistics | ||
| 5752 | that specifies when the hostlist server might be queried next. As this | ||
| 5753 | value is exponentially increasing during runtime, developers may want to | ||
| 5754 | reset or manually adjust it. Note that HOSTLIST (but not STATISTICS) needs | ||
| 5755 | to be shutdown if changes to this value are to have any effect on the | ||
| 5756 | daemon (as HOSTLIST does not monitor STATISTICS for changes to the | ||
| 5757 | download frequency). | ||
| 5758 | |||
| 5759 | @node Hostlist security address validation | ||
| 5760 | @subsection Hostlist security address validation | ||
| 5761 | |||
| 5762 | @c %**end of header | ||
| 5763 | |||
| 5764 | Since information obtained from other parties cannot be trusted without | ||
| 5765 | validation, we have to distinguish between @emph{validated} and | ||
| 5766 | @emph{not validated} addresses. Before using (and so trusting) | ||
| 5767 | information from other parties, this information has to be double-checked | ||
| 5768 | (validated). Address validation is not done by HOSTLIST but by the | ||
| 5769 | TRANSPORT service. | ||
| 5770 | |||
| 5771 | The HOSTLIST component is functionally located between the PEERINFO and | ||
| 5772 | the TRANSPORT subsystem. When acting as a server, the daemon obtains valid | ||
| 5773 | (@emph{validated}) peer information (HELLO messages) from the PEERINFO | ||
| 5774 | service and provides it to other peers. When acting as a client, it | ||
| 5775 | contacts the HOSTLIST servers specified in the configuration, downloads | ||
| 5776 | the (unvalidated) list of HELLO messages and forwards these information | ||
| 5777 | to the TRANSPORT server to validate the addresses. | ||
| 5778 | |||
| 5779 | @cindex HOSTLIST daemon | ||
| 5780 | @node The HOSTLIST daemon | ||
| 5781 | @subsection The HOSTLIST daemon | ||
| 5782 | |||
| 5783 | @c %**end of header | ||
| 5784 | |||
| 5785 | The hostlist daemon is the main component of the HOSTLIST subsystem. It is | ||
| 5786 | started by the ARM service and (if configured) starts the HOSTLIST client | ||
| 5787 | and server components. | ||
| 5788 | |||
| 5789 | If the daemon provides a hostlist itself it can advertise it's own | ||
| 5790 | hostlist to other peers. To do so it sends a | ||
| 5791 | @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} message to other peers | ||
| 5792 | when they connect to this peer on the CORE level. This hostlist | ||
| 5793 | advertisement message contains the URL to access the HOSTLIST HTTP | ||
| 5794 | server of the sender. The daemon may also subscribe to this type of | ||
| 5795 | message from CORE service, and then forward these kind of message to the | ||
| 5796 | HOSTLIST client. The client then uses all available URLs to download peer | ||
| 5797 | information when necessary. | ||
| 5798 | |||
| 5799 | When starting, the HOSTLIST daemon first connects to the CORE subsystem | ||
| 5800 | and if hostlist learning is enabled, registers a CORE handler to receive | ||
| 5801 | this kind of messages. Next it starts (if configured) the client and | ||
| 5802 | server. It passes pointers to CORE connect and disconnect and receive | ||
| 5803 | handlers where the client and server store their functions, so the daemon | ||
| 5804 | can notify them about CORE events. | ||
| 5805 | |||
| 5806 | To clean up on shutdown, the daemon has a cleaning task, shutting down all | ||
| 5807 | subsystems and disconnecting from CORE. | ||
| 5808 | |||
| 5809 | @cindex HOSTLIST server | ||
| 5810 | @node The HOSTLIST server | ||
| 5811 | @subsection The HOSTLIST server | ||
| 5812 | |||
| 5813 | @c %**end of header | ||
| 5814 | |||
| 5815 | The server provides a way for other peers to obtain HELLOs. Basically it | ||
| 5816 | is a small web server other peers can connect to and download a list of | ||
| 5817 | HELLOs using standard HTTP; it may also advertise the URL of the hostlist | ||
| 5818 | to other peers connecting on CORE level. | ||
| 5819 | |||
| 5820 | |||
| 5821 | @menu | ||
| 5822 | * The HTTP Server:: | ||
| 5823 | * Advertising the URL:: | ||
| 5824 | @end menu | ||
| 5825 | |||
| 5826 | @node The HTTP Server | ||
| 5827 | @subsubsection The HTTP Server | ||
| 5828 | |||
| 5829 | @c %**end of header | ||
| 5830 | |||
| 5831 | During startup, the server starts a web server listening on the port | ||
| 5832 | specified with the HTTPPORT value (default 8080). In addition it connects | ||
| 5833 | to the PEERINFO service to obtain peer information. The HOSTLIST server | ||
| 5834 | uses the GNUNET_PEERINFO_iterate function to request HELLO information for | ||
| 5835 | all peers and adds their information to a new hostlist if they are | ||
| 5836 | suitable (expired addresses and HELLOs without addresses are both not | ||
| 5837 | suitable) and the maximum size for a hostlist is not exceeded | ||
| 5838 | (MAX_BYTES_PER_HOSTLISTS = 500000). | ||
| 5839 | When PEERINFO finishes (with a last NULL callback), the server destroys | ||
| 5840 | the previous hostlist response available for download on the web server | ||
| 5841 | and replaces it with the updated hostlist. The hostlist format is | ||
| 5842 | basically a sequence of HELLO messages (as obtained from PEERINFO) without | ||
| 5843 | any special tokenization. Since each HELLO message contains a size field, | ||
| 5844 | the response can easily be split into separate HELLO messages by the | ||
| 5845 | client. | ||
| 5846 | |||
| 5847 | A HOSTLIST client connecting to the HOSTLIST server will receive the | ||
| 5848 | hostlist as a HTTP response and the the server will terminate the | ||
| 5849 | connection with the result code @code{HTTP 200 OK}. | ||
| 5850 | The connection will be closed immediately if no hostlist is available. | ||
| 5851 | |||
| 5852 | @node Advertising the URL | ||
| 5853 | @subsubsection Advertising the URL | ||
| 5854 | |||
| 5855 | @c %**end of header | ||
| 5856 | |||
| 5857 | The server also advertises the URL to download the hostlist to other peers | ||
| 5858 | if hostlist advertisement is enabled. | ||
| 5859 | When a new peer connects and has hostlist learning enabled, the server | ||
| 5860 | sends a @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} message to this | ||
| 5861 | peer using the CORE service. | ||
| 5862 | |||
| 5863 | @cindex HOSTLIST client | ||
| 5864 | @node The HOSTLIST client | ||
| 5865 | @subsection The HOSTLIST client | ||
| 5866 | |||
| 5867 | @c %**end of header | ||
| 5868 | |||
| 5869 | The client provides the functionality to download the list of HELLOs from | ||
| 5870 | a set of URLs. | ||
| 5871 | It performs a standard HTTP request to the URLs configured and learned | ||
| 5872 | from advertisement messages received from other peers. When a HELLO is | ||
| 5873 | downloaded, the HOSTLIST client forwards the HELLO to the TRANSPORT | ||
| 5874 | service for validation. | ||
| 5875 | |||
| 5876 | The client supports two modes of operation: | ||
| 5877 | |||
| 5878 | @itemize @bullet | ||
| 5879 | @item download of HELLOs (bootstrapping) | ||
| 5880 | @item learning of URLs | ||
| 5881 | @end itemize | ||
| 5882 | |||
| 5883 | @menu | ||
| 5884 | * Bootstrapping:: | ||
| 5885 | * Learning:: | ||
| 5886 | @end menu | ||
| 5887 | |||
| 5888 | @node Bootstrapping | ||
| 5889 | @subsubsection Bootstrapping | ||
| 5890 | |||
| 5891 | @c %**end of header | ||
| 5892 | |||
| 5893 | For bootstrapping, it schedules a task to download the hostlist from the | ||
| 5894 | set of known URLs. | ||
| 5895 | The downloads are only performed if the number of current | ||
| 5896 | connections is smaller than a minimum number of connections | ||
| 5897 | (at the moment 4). | ||
| 5898 | The interval between downloads increases exponentially; however, the | ||
| 5899 | exponential growth is limited if it becomes longer than an hour. | ||
| 5900 | At that point, the frequency growth is capped at | ||
| 5901 | (#number of connections * 1h). | ||
| 5902 | |||
| 5903 | Once the decision has been taken to download HELLOs, the daemon chooses a | ||
| 5904 | random URL from the list of known URLs. URLs can be configured in the | ||
| 5905 | configuration or be learned from advertisement messages. | ||
| 5906 | The client uses a HTTP client library (libcurl) to initiate the download | ||
| 5907 | using the libcurl multi interface. | ||
| 5908 | Libcurl passes the data to the callback_download function which | ||
| 5909 | stores the data in a buffer if space is available and the maximum size for | ||
| 5910 | a hostlist download is not exceeded (MAX_BYTES_PER_HOSTLISTS = 500000). | ||
| 5911 | When a full HELLO was downloaded, the HOSTLIST client offers this | ||
| 5912 | HELLO message to the TRANSPORT service for validation. | ||
| 5913 | When the download is finished or failed, statistical information about the | ||
| 5914 | quality of this URL is updated. | ||
| 5915 | |||
| 5916 | @cindex HOSTLIST learning | ||
| 5917 | @node Learning | ||
| 5918 | @subsubsection Learning | ||
| 5919 | |||
| 5920 | @c %**end of header | ||
| 5921 | |||
| 5922 | The client also manages hostlist advertisements from other peers. The | ||
| 5923 | HOSTLIST daemon forwards @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} | ||
| 5924 | messages to the client subsystem, which extracts the URL from the message. | ||
| 5925 | Next, a test of the newly obtained URL is performed by triggering a | ||
| 5926 | download from the new URL. If the URL works correctly, it is added to the | ||
| 5927 | list of working URLs. | ||
| 5928 | |||
| 5929 | The size of the list of URLs is restricted, so if an additional server is | ||
| 5930 | added and the list is full, the URL with the worst quality ranking | ||
| 5931 | (determined through successful downloads and number of HELLOs e.g.) is | ||
| 5932 | discarded. During shutdown the list of URLs is saved to a file for | ||
| 5933 | persistance and loaded on startup. URLs from the configuration file are | ||
| 5934 | never discarded. | ||
| 5935 | |||
| 5936 | @node Usage | ||
| 5937 | @subsection Usage | ||
| 5938 | |||
| 5939 | @c %**end of header | ||
| 5940 | |||
| 5941 | To start HOSTLIST by default, it has to be added to the DEFAULTSERVICES | ||
| 5942 | section for the ARM services. This is done in the default configuration. | ||
| 5943 | |||
| 5944 | For more information on how to configure the HOSTLIST subsystem see the | ||
| 5945 | installation handbook:@ | ||
| 5946 | Configuring the hostlist to bootstrap@ | ||
| 5947 | Configuring your peer to provide a hostlist | ||
| 5948 | |||
| 5949 | @cindex IDENTITY Subsystem | ||
| 5950 | @node IDENTITY Subsystem | ||
| 5951 | @section IDENTITY Subsystem | ||
| 5952 | |||
| 5953 | @c %**end of header | ||
| 5954 | |||
| 5955 | Identities of "users" in GNUnet are called egos. | ||
| 5956 | Egos can be used as pseudonyms ("fake names") or be tied to an | ||
| 5957 | organization (for example, "GNU") or even the actual identity of a human. | ||
| 5958 | GNUnet users are expected to have many egos. They might have one tied to | ||
| 5959 | their real identity, some for organizations they manage, and more for | ||
| 5960 | different domains where they want to operate under a pseudonym. | ||
| 5961 | |||
| 5962 | The IDENTITY service allows users to manage their egos. The identity | ||
| 5963 | service manages the private keys egos of the local user; it does not | ||
| 5964 | manage identities of other users (public keys). Public keys for other | ||
| 5965 | users need names to become manageable. GNUnet uses the | ||
| 5966 | @dfn{GNU Name System} (GNS) to give names to other users and manage their | ||
| 5967 | public keys securely. This chapter is about the IDENTITY service, | ||
| 5968 | which is about the management of private keys. | ||
| 5969 | |||
| 5970 | On the network, an ego corresponds to an ECDSA key (over Curve25519, | ||
| 5971 | using RFC 6979, as required by GNS). Thus, users can perform actions | ||
| 5972 | under a particular ego by using (signing with) a particular private key. | ||
| 5973 | Other users can then confirm that the action was really performed by that | ||
| 5974 | ego by checking the signature against the respective public key. | ||
| 5975 | |||
| 5976 | The IDENTITY service allows users to associate a human-readable name with | ||
| 5977 | each ego. This way, users can use names that will remind them of the | ||
| 5978 | purpose of a particular ego. | ||
| 5979 | The IDENTITY service will store the respective private keys and | ||
| 5980 | allows applications to access key information by name. | ||
| 5981 | Users can change the name that is locally (!) associated with an ego. | ||
| 5982 | Egos can also be deleted, which means that the private key will be removed | ||
| 5983 | and it thus will not be possible to perform actions with that ego in the | ||
| 5984 | future. | ||
| 5985 | |||
| 5986 | Additionally, the IDENTITY subsystem can associate service functions with | ||
| 5987 | egos. | ||
| 5988 | For example, GNS requires the ego that should be used for the shorten | ||
| 5989 | zone. GNS will ask IDENTITY for an ego for the "gns-short" service. | ||
| 5990 | The IDENTITY service has a mapping of such service strings to the name of | ||
| 5991 | the ego that the user wants to use for this service, for example | ||
| 5992 | "my-short-zone-ego". | ||
| 5993 | |||
| 5994 | Finally, the IDENTITY API provides access to a special ego, the | ||
| 5995 | anonymous ego. The anonymous ego is special in that its private key is not | ||
| 5996 | really private, but fixed and known to everyone. | ||
| 5997 | Thus, anyone can perform actions as anonymous. This can be useful as with | ||
| 5998 | this trick, code does not have to contain a special case to distinguish | ||
| 5999 | between anonymous and pseudonymous egos. | ||
| 6000 | |||
| 6001 | @menu | ||
| 6002 | * libgnunetidentity:: | ||
| 6003 | * The IDENTITY Client-Service Protocol:: | ||
| 6004 | @end menu | ||
| 6005 | |||
| 6006 | @cindex libgnunetidentity | ||
| 6007 | @node libgnunetidentity | ||
| 6008 | @subsection libgnunetidentity | ||
| 6009 | @c %**end of header | ||
| 6010 | |||
| 6011 | |||
| 6012 | @menu | ||
| 6013 | * Connecting to the service:: | ||
| 6014 | * Operations on Egos:: | ||
| 6015 | * The anonymous Ego:: | ||
| 6016 | * Convenience API to lookup a single ego:: | ||
| 6017 | * Associating egos with service functions:: | ||
| 6018 | @end menu | ||
| 6019 | |||
| 6020 | @node Connecting to the service | ||
| 6021 | @subsubsection Connecting to the service | ||
| 6022 | |||
| 6023 | @c %**end of header | ||
| 6024 | |||
| 6025 | First, typical clients connect to the identity service using | ||
| 6026 | @code{GNUNET_IDENTITY_connect}. This function takes a callback as a | ||
| 6027 | parameter. | ||
| 6028 | If the given callback parameter is non-null, it will be invoked to notify | ||
| 6029 | the application about the current state of the identities in the system. | ||
| 6030 | |||
| 6031 | @itemize @bullet | ||
| 6032 | @item First, it will be invoked on all known egos at the time of the | ||
| 6033 | connection. For each ego, a handle to the ego and the user's name for the | ||
| 6034 | ego will be passed to the callback. Furthermore, a @code{void **} context | ||
| 6035 | argument will be provided which gives the client the opportunity to | ||
| 6036 | associate some state with the ego. | ||
| 6037 | @item Second, the callback will be invoked with NULL for the ego, the name | ||
| 6038 | and the context. This signals that the (initial) iteration over all egos | ||
| 6039 | has completed. | ||
| 6040 | @item Then, the callback will be invoked whenever something changes about | ||
| 6041 | an ego. | ||
| 6042 | If an ego is renamed, the callback is invoked with the ego handle of the | ||
| 6043 | ego that was renamed, and the new name. If an ego is deleted, the callback | ||
| 6044 | is invoked with the ego handle and a name of NULL. In the deletion case, | ||
| 6045 | the application should also release resources stored in the context. | ||
| 6046 | @item When the application destroys the connection to the identity service | ||
| 6047 | using @code{GNUNET_IDENTITY_disconnect}, the callback is again invoked | ||
| 6048 | with the ego and a name of NULL (equivalent to deletion of the egos). | ||
| 6049 | This should again be used to clean up the per-ego context. | ||
| 6050 | @end itemize | ||
| 6051 | |||
| 6052 | The ego handle passed to the callback remains valid until the callback is | ||
| 6053 | invoked with a name of NULL, so it is safe to store a reference to the | ||
| 6054 | ego's handle. | ||
| 6055 | |||
| 6056 | @node Operations on Egos | ||
| 6057 | @subsubsection Operations on Egos | ||
| 6058 | |||
| 6059 | @c %**end of header | ||
| 6060 | |||
| 6061 | Given an ego handle, the main operations are to get its associated private | ||
| 6062 | key using @code{GNUNET_IDENTITY_ego_get_private_key} or its associated | ||
| 6063 | public key using @code{GNUNET_IDENTITY_ego_get_public_key}. | ||
| 6064 | |||
| 6065 | The other operations on egos are pretty straightforward. | ||
| 6066 | Using @code{GNUNET_IDENTITY_create}, an application can request the | ||
| 6067 | creation of an ego by specifying the desired name. | ||
| 6068 | The operation will fail if that name is | ||
| 6069 | already in use. Using @code{GNUNET_IDENTITY_rename} the name of an | ||
| 6070 | existing ego can be changed. Finally, egos can be deleted using | ||
| 6071 | @code{GNUNET_IDENTITY_delete}. All of these operations will trigger | ||
| 6072 | updates to the callback given to the @code{GNUNET_IDENTITY_connect} | ||
| 6073 | function of all applications that are connected with the identity service | ||
| 6074 | at the time. @code{GNUNET_IDENTITY_cancel} can be used to cancel the | ||
| 6075 | operations before the respective continuations would be called. | ||
| 6076 | It is not guaranteed that the operation will not be completed anyway, | ||
| 6077 | only the continuation will no longer be called. | ||
| 6078 | |||
| 6079 | @node The anonymous Ego | ||
| 6080 | @subsubsection The anonymous Ego | ||
| 6081 | |||
| 6082 | @c %**end of header | ||
| 6083 | |||
| 6084 | A special way to obtain an ego handle is to call | ||
| 6085 | @code{GNUNET_IDENTITY_ego_get_anonymous}, which returns an ego for the | ||
| 6086 | "anonymous" user --- anyone knows and can get the private key for this | ||
| 6087 | user, so it is suitable for operations that are supposed to be anonymous | ||
| 6088 | but require signatures (for example, to avoid a special path in the code). | ||
| 6089 | The anonymous ego is always valid and accessing it does not require a | ||
| 6090 | connection to the identity service. | ||
| 6091 | |||
| 6092 | @node Convenience API to lookup a single ego | ||
| 6093 | @subsubsection Convenience API to lookup a single ego | ||
| 6094 | |||
| 6095 | |||
| 6096 | As applications commonly simply have to lookup a single ego, there is a | ||
| 6097 | convenience API to do just that. Use @code{GNUNET_IDENTITY_ego_lookup} to | ||
| 6098 | lookup a single ego by name. Note that this is the user's name for the | ||
| 6099 | ego, not the service function. The resulting ego will be returned via a | ||
| 6100 | callback and will only be valid during that callback. The operation can | ||
| 6101 | be canceled via @code{GNUNET_IDENTITY_ego_lookup_cancel} | ||
| 6102 | (cancellation is only legal before the callback is invoked). | ||
| 6103 | |||
| 6104 | @node Associating egos with service functions | ||
| 6105 | @subsubsection Associating egos with service functions | ||
| 6106 | |||
| 6107 | |||
| 6108 | The @code{GNUNET_IDENTITY_set} function is used to associate a particular | ||
| 6109 | ego with a service function. The name used by the service and the ego are | ||
| 6110 | given as arguments. | ||
| 6111 | Afterwards, the service can use its name to lookup the associated ego | ||
| 6112 | using @code{GNUNET_IDENTITY_get}. | ||
| 6113 | |||
| 6114 | @node The IDENTITY Client-Service Protocol | ||
| 6115 | @subsection The IDENTITY Client-Service Protocol | ||
| 6116 | |||
| 6117 | @c %**end of header | ||
| 6118 | |||
| 6119 | A client connecting to the identity service first sends a message with | ||
| 6120 | type | ||
| 6121 | @code{GNUNET_MESSAGE_TYPE_IDENTITY_START} to the service. After that, the | ||
| 6122 | client will receive information about changes to the egos by receiving | ||
| 6123 | messages of type @code{GNUNET_MESSAGE_TYPE_IDENTITY_UPDATE}. | ||
| 6124 | Those messages contain the private key of the ego and the user's name of | ||
| 6125 | the ego (or zero bytes for the name to indicate that the ego was deleted). | ||
| 6126 | A special bit @code{end_of_list} is used to indicate the end of the | ||
| 6127 | initial iteration over the identity service's egos. | ||
| 6128 | |||
| 6129 | The client can trigger changes to the egos by sending @code{CREATE}, | ||
| 6130 | @code{RENAME} or @code{DELETE} messages. | ||
| 6131 | The CREATE message contains the private key and the desired name.@ | ||
| 6132 | The RENAME message contains the old name and the new name.@ | ||
| 6133 | The DELETE message only needs to include the name of the ego to delete.@ | ||
| 6134 | The service responds to each of these messages with a @code{RESULT_CODE} | ||
| 6135 | message which indicates success or error of the operation, and possibly | ||
| 6136 | a human-readable error message. | ||
| 6137 | |||
| 6138 | Finally, the client can bind the name of a service function to an ego by | ||
| 6139 | sending a @code{SET_DEFAULT} message with the name of the service function | ||
| 6140 | and the private key of the ego. | ||
| 6141 | Such bindings can then be resolved using a @code{GET_DEFAULT} message, | ||
| 6142 | which includes the name of the service function. The identity service | ||
| 6143 | will respond to a GET_DEFAULT request with a SET_DEFAULT message | ||
| 6144 | containing the respective information, or with a RESULT_CODE to | ||
| 6145 | indicate an error. | ||
| 6146 | |||
| 6147 | @cindex NAMESTORE Subsystem | ||
| 6148 | @node NAMESTORE Subsystem | ||
| 6149 | @section NAMESTORE Subsystem | ||
| 6150 | |||
| 6151 | The NAMESTORE subsystem provides persistent storage for local GNS zone | ||
| 6152 | information. All local GNS zone information are managed by NAMESTORE. It | ||
| 6153 | provides both the functionality to administer local GNS information (e.g. | ||
| 6154 | delete and add records) as well as to retrieve GNS information (e.g to | ||
| 6155 | list name information in a client). | ||
| 6156 | NAMESTORE does only manage the persistent storage of zone information | ||
| 6157 | belonging to the user running the service: GNS information from other | ||
| 6158 | users obtained from the DHT are stored by the NAMECACHE subsystem. | ||
| 6159 | |||
| 6160 | NAMESTORE uses a plugin-based database backend to store GNS information | ||
| 6161 | with good performance. Here sqlite, MySQL and PostgreSQL are supported | ||
| 6162 | database backends. | ||
| 6163 | NAMESTORE clients interact with the IDENTITY subsystem to obtain | ||
| 6164 | cryptographic information about zones based on egos as described with the | ||
| 6165 | IDENTITY subsystem, but internally NAMESTORE refers to zones using the | ||
| 6166 | ECDSA private key. | ||
| 6167 | In addition, it collaborates with the NAMECACHE subsystem and | ||
| 6168 | stores zone information when local information are modified in the | ||
| 6169 | GNS cache to increase look-up performance for local information. | ||
| 6170 | |||
| 6171 | NAMESTORE provides functionality to look-up and store records, to iterate | ||
| 6172 | over a specific or all zones and to monitor zones for changes. NAMESTORE | ||
| 6173 | functionality can be accessed using the NAMESTORE api or the NAMESTORE | ||
| 6174 | command line tool. | ||
| 6175 | |||
| 6176 | @menu | ||
| 6177 | * libgnunetnamestore:: | ||
| 6178 | @end menu | ||
| 6179 | |||
| 6180 | @cindex libgnunetnamestore | ||
| 6181 | @node libgnunetnamestore | ||
| 6182 | @subsection libgnunetnamestore | ||
| 6183 | |||
| 6184 | To interact with NAMESTORE clients first connect to the NAMESTORE service | ||
| 6185 | using the @code{GNUNET_NAMESTORE_connect} passing a configuration handle. | ||
| 6186 | As a result they obtain a NAMESTORE handle, they can use for operations, | ||
| 6187 | or NULL is returned if the connection failed. | ||
| 6188 | |||
| 6189 | To disconnect from NAMESTORE, clients use | ||
| 6190 | @code{GNUNET_NAMESTORE_disconnect} and specify the handle to disconnect. | ||
| 6191 | |||
| 6192 | NAMESTORE internally uses the ECDSA private key to refer to zones. These | ||
| 6193 | private keys can be obtained from the IDENTITY subsytem. | ||
| 6194 | Here @emph{egos} @emph{can be used to refer to zones or the default ego | ||
| 6195 | assigned to the GNS subsystem can be used to obtained the master zone's | ||
| 6196 | private key.} | ||
| 6197 | |||
| 6198 | |||
| 6199 | @menu | ||
| 6200 | * Editing Zone Information:: | ||
| 6201 | * Iterating Zone Information:: | ||
| 6202 | * Monitoring Zone Information:: | ||
| 6203 | @end menu | ||
| 6204 | |||
| 6205 | @node Editing Zone Information | ||
| 6206 | @subsubsection Editing Zone Information | ||
| 6207 | |||
| 6208 | @c %**end of header | ||
| 6209 | |||
| 6210 | NAMESTORE provides functions to lookup records stored under a label in a | ||
| 6211 | zone and to store records under a label in a zone. | ||
| 6212 | |||
| 6213 | To store (and delete) records, the client uses the | ||
| 6214 | @code{GNUNET_NAMESTORE_records_store} function and has to provide | ||
| 6215 | namestore handle to use, the private key of the zone, the label to store | ||
| 6216 | the records under, the records and number of records plus an callback | ||
| 6217 | function. | ||
| 6218 | After the operation is performed NAMESTORE will call the provided | ||
| 6219 | callback function with the result GNUNET_SYSERR on failure | ||
| 6220 | (including timeout/queue drop/failure to validate), GNUNET_NO if content | ||
| 6221 | was already there or not found GNUNET_YES (or other positive value) on | ||
| 6222 | success plus an additional error message. | ||
| 6223 | |||
| 6224 | Records are deleted by using the store command with 0 records to store. | ||
| 6225 | It is important to note, that records are not merged when records exist | ||
| 6226 | with the label. | ||
| 6227 | So a client has first to retrieve records, merge with existing records | ||
| 6228 | and then store the result. | ||
| 6229 | |||
| 6230 | To perform a lookup operation, the client uses the | ||
| 6231 | @code{GNUNET_NAMESTORE_records_store} function. Here it has to pass the | ||
| 6232 | namestore handle, the private key of the zone and the label. It also has | ||
| 6233 | to provide a callback function which will be called with the result of | ||
| 6234 | the lookup operation: | ||
| 6235 | the zone for the records, the label, and the records including the | ||
| 6236 | number of records included. | ||
| 6237 | |||
| 6238 | A special operation is used to set the preferred nickname for a zone. | ||
| 6239 | This nickname is stored with the zone and is automatically merged with | ||
| 6240 | all labels and records stored in a zone. Here the client uses the | ||
| 6241 | @code{GNUNET_NAMESTORE_set_nick} function and passes the private key of | ||
| 6242 | the zone, the nickname as string plus a the callback with the result of | ||
| 6243 | the operation. | ||
| 6244 | |||
| 6245 | @node Iterating Zone Information | ||
| 6246 | @subsubsection Iterating Zone Information | ||
| 6247 | |||
| 6248 | @c %**end of header | ||
| 6249 | |||
| 6250 | A client can iterate over all information in a zone or all zones managed | ||
| 6251 | by NAMESTORE. | ||
| 6252 | Here a client uses the @code{GNUNET_NAMESTORE_zone_iteration_start} | ||
| 6253 | function and passes the namestore handle, the zone to iterate over and a | ||
| 6254 | callback function to call with the result. | ||
| 6255 | If the client wants to iterate over all the WHAT!? FIXME, it passes NULL for the zone. | ||
| 6256 | A @code{GNUNET_NAMESTORE_ZoneIterator} handle is returned to be used to | ||
| 6257 | continue iteration. | ||
| 6258 | |||
| 6259 | NAMESTORE calls the callback for every result and expects the client to | ||
| 6260 | call @code{GNUNET_NAMESTORE_zone_iterator_next} to continue to iterate or | ||
| 6261 | @code{GNUNET_NAMESTORE_zone_iterator_stop} to interrupt the iteration. | ||
| 6262 | When NAMESTORE reached the last item it will call the callback with a | ||
| 6263 | NULL value to indicate. | ||
| 6264 | |||
| 6265 | @node Monitoring Zone Information | ||
| 6266 | @subsubsection Monitoring Zone Information | ||
| 6267 | |||
| 6268 | @c %**end of header | ||
| 6269 | |||
| 6270 | Clients can also monitor zones to be notified about changes. Here the | ||
| 6271 | clients uses the @code{GNUNET_NAMESTORE_zone_monitor_start} function and | ||
| 6272 | passes the private key of the zone and and a callback function to call | ||
| 6273 | with updates for a zone. | ||
| 6274 | The client can specify to obtain zone information first by iterating over | ||
| 6275 | the zone and specify a synchronization callback to be called when the | ||
| 6276 | client and the namestore are synced. | ||
| 6277 | |||
| 6278 | On an update, NAMESTORE will call the callback with the private key of the | ||
| 6279 | zone, the label and the records and their number. | ||
| 6280 | |||
| 6281 | To stop monitoring, the client calls | ||
| 6282 | @code{GNUNET_NAMESTORE_zone_monitor_stop} and passes the handle obtained | ||
| 6283 | from the function to start the monitoring. | ||
| 6284 | |||
| 6285 | @cindex PEERINFO Subsystem | ||
| 6286 | @node PEERINFO Subsystem | ||
| 6287 | @section PEERINFO Subsystem | ||
| 6288 | |||
| 6289 | @c %**end of header | ||
| 6290 | |||
| 6291 | The PEERINFO subsystem is used to store verified (validated) information | ||
| 6292 | about known peers in a persistent way. It obtains these addresses for | ||
| 6293 | example from TRANSPORT service which is in charge of address validation. | ||
| 6294 | Validation means that the information in the HELLO message are checked by | ||
| 6295 | connecting to the addresses and performing a cryptographic handshake to | ||
| 6296 | authenticate the peer instance stating to be reachable with these | ||
| 6297 | addresses. | ||
| 6298 | Peerinfo does not validate the HELLO messages itself but only stores them | ||
| 6299 | and gives them to interested clients. | ||
| 6300 | |||
| 6301 | As future work, we think about moving from storing just HELLO messages to | ||
| 6302 | providing a generic persistent per-peer information store. | ||
| 6303 | More and more subsystems tend to need to store per-peer information in | ||
| 6304 | persistent way. | ||
| 6305 | To not duplicate this functionality we plan to provide a PEERSTORE | ||
| 6306 | service providing this functionality. | ||
| 6307 | |||
| 6308 | @menu | ||
| 6309 | * PEERINFO - Features:: | ||
| 6310 | * PEERINFO - Limitations:: | ||
| 6311 | * DeveloperPeer Information:: | ||
| 6312 | * Startup:: | ||
| 6313 | * Managing Information:: | ||
| 6314 | * Obtaining Information:: | ||
| 6315 | * The PEERINFO Client-Service Protocol:: | ||
| 6316 | * libgnunetpeerinfo:: | ||
| 6317 | @end menu | ||
| 6318 | |||
| 6319 | @node PEERINFO - Features | ||
| 6320 | @subsection PEERINFO - Features | ||
| 6321 | |||
| 6322 | @c %**end of header | ||
| 6323 | |||
| 6324 | @itemize @bullet | ||
| 6325 | @item Persistent storage | ||
| 6326 | @item Client notification mechanism on update | ||
| 6327 | @item Periodic clean up for expired information | ||
| 6328 | @item Differentiation between public and friend-only HELLO | ||
| 6329 | @end itemize | ||
| 6330 | |||
| 6331 | @node PEERINFO - Limitations | ||
| 6332 | @subsection PEERINFO - Limitations | ||
| 6333 | |||
| 6334 | |||
| 6335 | @itemize @bullet | ||
| 6336 | @item Does not perform HELLO validation | ||
| 6337 | @end itemize | ||
| 6338 | |||
| 6339 | @node DeveloperPeer Information | ||
| 6340 | @subsection DeveloperPeer Information | ||
| 6341 | |||
| 6342 | @c %**end of header | ||
| 6343 | |||
| 6344 | The PEERINFO subsystem stores these information in the form of HELLO | ||
| 6345 | messages you can think of as business cards. | ||
| 6346 | These HELLO messages contain the public key of a peer and the addresses | ||
| 6347 | a peer can be reached under. | ||
| 6348 | The addresses include an expiration date describing how long they are | ||
| 6349 | valid. This information is updated regularly by the TRANSPORT service by | ||
| 6350 | revalidating the address. | ||
| 6351 | If an address is expired and not renewed, it can be removed from the | ||
| 6352 | HELLO message. | ||
| 6353 | |||
| 6354 | Some peer do not want to have their HELLO messages distributed to other | ||
| 6355 | peers, especially when GNUnet's friend-to-friend modus is enabled. | ||
| 6356 | To prevent this undesired distribution. PEERINFO distinguishes between | ||
| 6357 | @emph{public} and @emph{friend-only} HELLO messages. | ||
| 6358 | Public HELLO messages can be freely distributed to other (possibly | ||
| 6359 | unknown) peers (for example using the hostlist, gossiping, broadcasting), | ||
| 6360 | whereas friend-only HELLO messages may not be distributed to other peers. | ||
| 6361 | Friend-only HELLO messages have an additional flag @code{friend_only} set | ||
| 6362 | internally. For public HELLO message this flag is not set. | ||
| 6363 | PEERINFO does and cannot not check if a client is allowed to obtain a | ||
| 6364 | specific HELLO type. | ||
| 6365 | |||
| 6366 | The HELLO messages can be managed using the GNUnet HELLO library. | ||
| 6367 | Other GNUnet systems can obtain these information from PEERINFO and use | ||
| 6368 | it for their purposes. | ||
| 6369 | Clients are for example the HOSTLIST component providing these | ||
| 6370 | information to other peers in form of a hostlist or the TRANSPORT | ||
| 6371 | subsystem using these information to maintain connections to other peers. | ||
| 6372 | |||
| 6373 | @node Startup | ||
| 6374 | @subsection Startup | ||
| 6375 | |||
| 6376 | @c %**end of header | ||
| 6377 | |||
| 6378 | During startup the PEERINFO services loads persistent HELLOs from disk. | ||
| 6379 | First PEERINFO parses the directory configured in the HOSTS value of the | ||
| 6380 | @code{PEERINFO} configuration section to store PEERINFO information. | ||
| 6381 | For all files found in this directory valid HELLO messages are extracted. | ||
| 6382 | In addition it loads HELLO messages shipped with the GNUnet distribution. | ||
| 6383 | These HELLOs are used to simplify network bootstrapping by providing | ||
| 6384 | valid peer information with the distribution. | ||
| 6385 | The use of these HELLOs can be prevented by setting the | ||
| 6386 | @code{USE_INCLUDED_HELLOS} in the @code{PEERINFO} configuration section to | ||
| 6387 | @code{NO}. Files containing invalid information are removed. | ||
| 6388 | |||
| 6389 | @node Managing Information | ||
| 6390 | @subsection Managing Information | ||
| 6391 | |||
| 6392 | @c %**end of header | ||
| 6393 | |||
| 6394 | The PEERINFO services stores information about known PEERS and a single | ||
| 6395 | HELLO message for every peer. | ||
| 6396 | A peer does not need to have a HELLO if no information are available. | ||
| 6397 | HELLO information from different sources, for example a HELLO obtained | ||
| 6398 | from a remote HOSTLIST and a second HELLO stored on disk, are combined | ||
| 6399 | and merged into one single HELLO message per peer which will be given to | ||
| 6400 | clients. During this merge process the HELLO is immediately written to | ||
| 6401 | disk to ensure persistence. | ||
| 6402 | |||
| 6403 | PEERINFO in addition periodically scans the directory where information | ||
| 6404 | are stored for empty HELLO messages with expired TRANSPORT addresses. | ||
| 6405 | This periodic task scans all files in the directory and recreates the | ||
| 6406 | HELLO messages it finds. | ||
| 6407 | Expired TRANSPORT addresses are removed from the HELLO and if the | ||
| 6408 | HELLO does not contain any valid addresses, it is discarded and removed | ||
| 6409 | from the disk. | ||
| 6410 | |||
| 6411 | @node Obtaining Information | ||
| 6412 | @subsection Obtaining Information | ||
| 6413 | |||
| 6414 | @c %**end of header | ||
| 6415 | |||
| 6416 | When a client requests information from PEERINFO, PEERINFO performs a | ||
| 6417 | lookup for the respective peer or all peers if desired and transmits this | ||
| 6418 | information to the client. | ||
| 6419 | The client can specify if friend-only HELLOs have to be included or not | ||
| 6420 | and PEERINFO filters the respective HELLO messages before transmitting | ||
| 6421 | information. | ||
| 6422 | |||
| 6423 | To notify clients about changes to PEERINFO information, PEERINFO | ||
| 6424 | maintains a list of clients interested in this notifications. | ||
| 6425 | Such a notification occurs if a HELLO for a peer was updated (due to a | ||
| 6426 | merge for example) or a new peer was added. | ||
| 6427 | |||
| 6428 | @node The PEERINFO Client-Service Protocol | ||
| 6429 | @subsection The PEERINFO Client-Service Protocol | ||
| 6430 | |||
| 6431 | @c %**end of header | ||
| 6432 | |||
| 6433 | To connect and disconnect to and from the PEERINFO Service PEERINFO | ||
| 6434 | utilizes the util client/server infrastructure, so no special messages | ||
| 6435 | types are used here. | ||
| 6436 | |||
| 6437 | To add information for a peer, the plain HELLO message is transmitted to | ||
| 6438 | the service without any wrapping. All pieces of information required are | ||
| 6439 | stored within the HELLO message. | ||
| 6440 | The PEERINFO service provides a message handler accepting and processing | ||
| 6441 | these HELLO messages. | ||
| 6442 | |||
| 6443 | When obtaining PEERINFO information using the iterate functionality | ||
| 6444 | specific messages are used. To obtain information for all peers, a | ||
| 6445 | @code{struct ListAllPeersMessage} with message type | ||
| 6446 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_GET_ALL} and a flag | ||
| 6447 | include_friend_only to indicate if friend-only HELLO messages should be | ||
| 6448 | included are transmitted. If information for a specific peer is required | ||
| 6449 | a @code{struct ListAllPeersMessage} with | ||
| 6450 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_GET} containing the peer identity is | ||
| 6451 | used. | ||
| 6452 | |||
| 6453 | For both variants the PEERINFO service replies for each HELLO message it | ||
| 6454 | wants to transmit with a @code{struct ListAllPeersMessage} with type | ||
| 6455 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_INFO} containing the plain HELLO. | ||
| 6456 | The final message is @code{struct GNUNET_MessageHeader} with type | ||
| 6457 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_INFO}. If the client receives this | ||
| 6458 | message, it can proceed with the next request if any is pending. | ||
| 6459 | |||
| 6460 | @node libgnunetpeerinfo | ||
| 6461 | @subsection libgnunetpeerinfo | ||
| 6462 | |||
| 6463 | @c %**end of header | ||
| 6464 | |||
| 6465 | The PEERINFO API consists mainly of three different functionalities: | ||
| 6466 | |||
| 6467 | @itemize @bullet | ||
| 6468 | @item maintaining a connection to the service | ||
| 6469 | @item adding new information to the PEERINFO service | ||
| 6470 | @item retrieving information from the PEERINFO service | ||
| 6471 | @end itemize | ||
| 6472 | |||
| 6473 | @menu | ||
| 6474 | * Connecting to the PEERINFO Service:: | ||
| 6475 | * Adding Information to the PEERINFO Service:: | ||
| 6476 | * Obtaining Information from the PEERINFO Service:: | ||
| 6477 | @end menu | ||
| 6478 | |||
| 6479 | @node Connecting to the PEERINFO Service | ||
| 6480 | @subsubsection Connecting to the PEERINFO Service | ||
| 6481 | |||
| 6482 | @c %**end of header | ||
| 6483 | |||
| 6484 | To connect to the PEERINFO service the function | ||
| 6485 | @code{GNUNET_PEERINFO_connect} is used, taking a configuration handle as | ||
| 6486 | an argument, and to disconnect from PEERINFO the function | ||
| 6487 | @code{GNUNET_PEERINFO_disconnect}, taking the PEERINFO | ||
| 6488 | handle returned from the connect function has to be called. | ||
| 6489 | |||
| 6490 | @node Adding Information to the PEERINFO Service | ||
| 6491 | @subsubsection Adding Information to the PEERINFO Service | ||
| 6492 | |||
| 6493 | @c %**end of header | ||
| 6494 | |||
| 6495 | @code{GNUNET_PEERINFO_add_peer} adds a new peer to the PEERINFO subsystem | ||
| 6496 | storage. This function takes the PEERINFO handle as an argument, the HELLO | ||
| 6497 | message to store and a continuation with a closure to be called with the | ||
| 6498 | result of the operation. | ||
| 6499 | The @code{GNUNET_PEERINFO_add_peer} returns a handle to this operation | ||
| 6500 | allowing to cancel the operation with the respective cancel function | ||
| 6501 | @code{GNUNET_PEERINFO_add_peer_cancel}. To retrieve information from | ||
| 6502 | PEERINFO you can iterate over all information stored with PEERINFO or you | ||
| 6503 | can tell PEERINFO to notify if new peer information are available. | ||
| 6504 | |||
| 6505 | @node Obtaining Information from the PEERINFO Service | ||
| 6506 | @subsubsection Obtaining Information from the PEERINFO Service | ||
| 6507 | |||
| 6508 | @c %**end of header | ||
| 6509 | |||
| 6510 | To iterate over information in PEERINFO you use | ||
| 6511 | @code{GNUNET_PEERINFO_iterate}. | ||
| 6512 | This function expects the PEERINFO handle, a flag if HELLO messages | ||
| 6513 | intended for friend only mode should be included, a timeout how long the | ||
| 6514 | operation should take and a callback with a callback closure to be called | ||
| 6515 | for the results. | ||
| 6516 | If you want to obtain information for a specific peer, you can specify | ||
| 6517 | the peer identity, if this identity is NULL, information for all peers are | ||
| 6518 | returned. The function returns a handle to allow to cancel the operation | ||
| 6519 | using @code{GNUNET_PEERINFO_iterate_cancel}. | ||
| 6520 | |||
| 6521 | To get notified when peer information changes, you can use | ||
| 6522 | @code{GNUNET_PEERINFO_notify}. | ||
| 6523 | This function expects a configuration handle and a flag if friend-only | ||
| 6524 | HELLO messages should be included. The PEERINFO service will notify you | ||
| 6525 | about every change and the callback function will be called to notify you | ||
| 6526 | about changes. The function returns a handle to cancel notifications | ||
| 6527 | with @code{GNUNET_PEERINFO_notify_cancel}. | ||
| 6528 | |||
| 6529 | @cindex PEERSTORE Subsystem | ||
| 6530 | @node PEERSTORE Subsystem | ||
| 6531 | @section PEERSTORE Subsystem | ||
| 6532 | |||
| 6533 | @c %**end of header | ||
| 6534 | |||
| 6535 | GNUnet's PEERSTORE subsystem offers persistent per-peer storage for other | ||
| 6536 | GNUnet subsystems. GNUnet subsystems can use PEERSTORE to persistently | ||
| 6537 | store and retrieve arbitrary data. | ||
| 6538 | Each data record stored with PEERSTORE contains the following fields: | ||
| 6539 | |||
| 6540 | @itemize @bullet | ||
| 6541 | @item subsystem: Name of the subsystem responsible for the record. | ||
| 6542 | @item peerid: Identity of the peer this record is related to. | ||
| 6543 | @item key: a key string identifying the record. | ||
| 6544 | @item value: binary record value. | ||
| 6545 | @item expiry: record expiry date. | ||
| 6546 | @end itemize | ||
| 6547 | |||
| 6548 | @menu | ||
| 6549 | * Functionality:: | ||
| 6550 | * Architecture:: | ||
| 6551 | * libgnunetpeerstore:: | ||
| 6552 | @end menu | ||
| 6553 | |||
| 6554 | @node Functionality | ||
| 6555 | @subsection Functionality | ||
| 6556 | |||
| 6557 | @c %**end of header | ||
| 6558 | |||
| 6559 | Subsystems can store any type of value under a (subsystem, peerid, key) | ||
| 6560 | combination. A "replace" flag set during store operations forces the | ||
| 6561 | PEERSTORE to replace any old values stored under the same | ||
| 6562 | (subsystem, peerid, key) combination with the new value. | ||
| 6563 | Additionally, an expiry date is set after which the record is *possibly* | ||
| 6564 | deleted by PEERSTORE. | ||
| 6565 | |||
| 6566 | Subsystems can iterate over all values stored under any of the following | ||
| 6567 | combination of fields: | ||
| 6568 | |||
| 6569 | @itemize @bullet | ||
| 6570 | @item (subsystem) | ||
| 6571 | @item (subsystem, peerid) | ||
| 6572 | @item (subsystem, key) | ||
| 6573 | @item (subsystem, peerid, key) | ||
| 6574 | @end itemize | ||
| 6575 | |||
| 6576 | Subsystems can also request to be notified about any new values stored | ||
| 6577 | under a (subsystem, peerid, key) combination by sending a "watch" | ||
| 6578 | request to PEERSTORE. | ||
| 6579 | |||
| 6580 | @node Architecture | ||
| 6581 | @subsection Architecture | ||
| 6582 | |||
| 6583 | @c %**end of header | ||
| 6584 | |||
| 6585 | PEERSTORE implements the following components: | ||
| 6586 | |||
| 6587 | @itemize @bullet | ||
| 6588 | @item PEERSTORE service: Handles store, iterate and watch operations. | ||
| 6589 | @item PEERSTORE API: API to be used by other subsystems to communicate and | ||
| 6590 | issue commands to the PEERSTORE service. | ||
| 6591 | @item PEERSTORE plugins: Handles the persistent storage. At the moment, | ||
| 6592 | only an "sqlite" plugin is implemented. | ||
| 6593 | @end itemize | ||
| 6594 | |||
| 6595 | @cindex libgnunetpeerstore | ||
| 6596 | @node libgnunetpeerstore | ||
| 6597 | @subsection libgnunetpeerstore | ||
| 6598 | |||
| 6599 | @c %**end of header | ||
| 6600 | |||
| 6601 | libgnunetpeerstore is the library containing the PEERSTORE API. Subsystems | ||
| 6602 | wishing to communicate with the PEERSTORE service use this API to open a | ||
| 6603 | connection to PEERSTORE. This is done by calling | ||
| 6604 | @code{GNUNET_PEERSTORE_connect} which returns a handle to the newly | ||
| 6605 | created connection. | ||
| 6606 | This handle has to be used with any further calls to the API. | ||
| 6607 | |||
| 6608 | To store a new record, the function @code{GNUNET_PEERSTORE_store} is to | ||
| 6609 | be used which requires the record fields and a continuation function that | ||
| 6610 | will be called by the API after the STORE request is sent to the | ||
| 6611 | PEERSTORE service. | ||
| 6612 | Note that calling the continuation function does not mean that the record | ||
| 6613 | is successfully stored, only that the STORE request has been successfully | ||
| 6614 | sent to the PEERSTORE service. | ||
| 6615 | @code{GNUNET_PEERSTORE_store_cancel} can be called to cancel the STORE | ||
| 6616 | request only before the continuation function has been called. | ||
| 6617 | |||
| 6618 | To iterate over stored records, the function | ||
| 6619 | @code{GNUNET_PEERSTORE_iterate} is | ||
| 6620 | to be used. @emph{peerid} and @emph{key} can be set to NULL. An iterator | ||
| 6621 | callback function will be called with each matching record found and a | ||
| 6622 | NULL record at the end to signal the end of result set. | ||
| 6623 | @code{GNUNET_PEERSTORE_iterate_cancel} can be used to cancel the ITERATE | ||
| 6624 | request before the iterator callback is called with a NULL record. | ||
| 6625 | |||
| 6626 | To be notified with new values stored under a (subsystem, peerid, key) | ||
| 6627 | combination, the function @code{GNUNET_PEERSTORE_watch} is to be used. | ||
| 6628 | This will register the watcher with the PEERSTORE service, any new | ||
| 6629 | records matching the given combination will trigger the callback | ||
| 6630 | function passed to @code{GNUNET_PEERSTORE_watch}. This continues until | ||
| 6631 | @code{GNUNET_PEERSTORE_watch_cancel} is called or the connection to the | ||
| 6632 | service is destroyed. | ||
| 6633 | |||
| 6634 | After the connection is no longer needed, the function | ||
| 6635 | @code{GNUNET_PEERSTORE_disconnect} can be called to disconnect from the | ||
| 6636 | PEERSTORE service. | ||
| 6637 | Any pending ITERATE or WATCH requests will be destroyed. | ||
| 6638 | If the @code{sync_first} flag is set to @code{GNUNET_YES}, the API will | ||
| 6639 | delay the disconnection until all pending STORE requests are sent to | ||
| 6640 | the PEERSTORE service, otherwise, the pending STORE requests will be | ||
| 6641 | destroyed as well. | ||
| 6642 | |||
| 6643 | @cindex SET Subsystem | ||
| 6644 | @node SET Subsystem | ||
| 6645 | @section SET Subsystem | ||
| 6646 | |||
| 6647 | @c %**end of header | ||
| 6648 | |||
| 6649 | The SET service implements efficient set operations between two peers | ||
| 6650 | over a mesh tunnel. | ||
| 6651 | Currently, set union and set intersection are the only supported | ||
| 6652 | operations. Elements of a set consist of an @emph{element type} and | ||
| 6653 | arbitrary binary @emph{data}. | ||
| 6654 | The size of an element's data is limited to around 62 KB. | ||
| 6655 | |||
| 6656 | @menu | ||
| 6657 | * Local Sets:: | ||
| 6658 | * Set Modifications:: | ||
| 6659 | * Set Operations:: | ||
| 6660 | * Result Elements:: | ||
| 6661 | * libgnunetset:: | ||
| 6662 | * The SET Client-Service Protocol:: | ||
| 6663 | * The SET Intersection Peer-to-Peer Protocol:: | ||
| 6664 | * The SET Union Peer-to-Peer Protocol:: | ||
| 6665 | @end menu | ||
| 6666 | |||
| 6667 | @node Local Sets | ||
| 6668 | @subsection Local Sets | ||
| 6669 | |||
| 6670 | @c %**end of header | ||
| 6671 | |||
| 6672 | Sets created by a local client can be modified and reused for multiple | ||
| 6673 | operations. As each set operation requires potentially expensive special | ||
| 6674 | auxiliary data to be computed for each element of a set, a set can only | ||
| 6675 | participate in one type of set operation (i.e. union or intersection). | ||
| 6676 | The type of a set is determined upon its creation. | ||
| 6677 | If a the elements of a set are needed for an operation of a different | ||
| 6678 | type, all of the set's element must be copied to a new set of appropriate | ||
| 6679 | type. | ||
| 6680 | |||
| 6681 | @node Set Modifications | ||
| 6682 | @subsection Set Modifications | ||
| 6683 | |||
| 6684 | @c %**end of header | ||
| 6685 | |||
| 6686 | Even when set operations are active, one can add to and remove elements | ||
| 6687 | from a set. | ||
| 6688 | However, these changes will only be visible to operations that have been | ||
| 6689 | created after the changes have taken place. That is, every set operation | ||
| 6690 | only sees a snapshot of the set from the time the operation was started. | ||
| 6691 | This mechanism is @emph{not} implemented by copying the whole set, but by | ||
| 6692 | attaching @emph{generation information} to each element and operation. | ||
| 6693 | |||
| 6694 | @node Set Operations | ||
| 6695 | @subsection Set Operations | ||
| 6696 | |||
| 6697 | @c %**end of header | ||
| 6698 | |||
| 6699 | Set operations can be started in two ways: Either by accepting an | ||
| 6700 | operation request from a remote peer, or by requesting a set operation | ||
| 6701 | from a remote peer. | ||
| 6702 | Set operations are uniquely identified by the involved @emph{peers}, an | ||
| 6703 | @emph{application id} and the @emph{operation type}. | ||
| 6704 | |||
| 6705 | The client is notified of incoming set operations by @emph{set listeners}. | ||
| 6706 | A set listener listens for incoming operations of a specific operation | ||
| 6707 | type and application id. | ||
| 6708 | Once notified of an incoming set request, the client can accept the set | ||
| 6709 | request (providing a local set for the operation) or reject it. | ||
| 6710 | |||
| 6711 | @node Result Elements | ||
| 6712 | @subsection Result Elements | ||
| 6713 | |||
| 6714 | @c %**end of header | ||
| 6715 | |||
| 6716 | The SET service has three @emph{result modes} that determine how an | ||
| 6717 | operation's result set is delivered to the client: | ||
| 6718 | |||
| 6719 | @itemize @bullet | ||
| 6720 | @item @strong{Full Result Set.} All elements of set resulting from the set | ||
| 6721 | operation are returned to the client. | ||
| 6722 | @item @strong{Added Elements.} Only elements that result from the | ||
| 6723 | operation and are not already in the local peer's set are returned. | ||
| 6724 | Note that for some operations (like set intersection) this result mode | ||
| 6725 | will never return any elements. | ||
| 6726 | This can be useful if only the remove peer is actually interested in | ||
| 6727 | the result of the set operation. | ||
| 6728 | @item @strong{Removed Elements.} Only elements that are in the local | ||
| 6729 | peer's initial set but not in the operation's result set are returned. | ||
| 6730 | Note that for some operations (like set union) this result mode will | ||
| 6731 | never return any elements. This can be useful if only the remove peer is | ||
| 6732 | actually interested in the result of the set operation. | ||
| 6733 | @end itemize | ||
| 6734 | |||
| 6735 | @cindex libgnunetset | ||
| 6736 | @node libgnunetset | ||
| 6737 | @subsection libgnunetset | ||
| 6738 | |||
| 6739 | @c %**end of header | ||
| 6740 | |||
| 6741 | @menu | ||
| 6742 | * Sets:: | ||
| 6743 | * Listeners:: | ||
| 6744 | * Operations:: | ||
| 6745 | * Supplying a Set:: | ||
| 6746 | * The Result Callback:: | ||
| 6747 | @end menu | ||
| 6748 | |||
| 6749 | @node Sets | ||
| 6750 | @subsubsection Sets | ||
| 6751 | |||
| 6752 | @c %**end of header | ||
| 6753 | |||
| 6754 | New sets are created with @code{GNUNET_SET_create}. Both the local peer's | ||
| 6755 | configuration (as each set has its own client connection) and the | ||
| 6756 | operation type must be specified. | ||
| 6757 | The set exists until either the client calls @code{GNUNET_SET_destroy} or | ||
| 6758 | the client's connection to the service is disrupted. | ||
| 6759 | In the latter case, the client is notified by the return value of | ||
| 6760 | functions dealing with sets. This return value must always be checked. | ||
| 6761 | |||
| 6762 | Elements are added and removed with @code{GNUNET_SET_add_element} and | ||
| 6763 | @code{GNUNET_SET_remove_element}. | ||
| 6764 | |||
| 6765 | @node Listeners | ||
| 6766 | @subsubsection Listeners | ||
| 6767 | |||
| 6768 | @c %**end of header | ||
| 6769 | |||
| 6770 | Listeners are created with @code{GNUNET_SET_listen}. Each time time a | ||
| 6771 | remote peer suggests a set operation with an application id and operation | ||
| 6772 | type matching a listener, the listener's callback is invoked. | ||
| 6773 | The client then must synchronously call either @code{GNUNET_SET_accept} | ||
| 6774 | or @code{GNUNET_SET_reject}. Note that the operation will not be started | ||
| 6775 | until the client calls @code{GNUNET_SET_commit} | ||
| 6776 | (see Section "Supplying a Set"). | ||
| 6777 | |||
| 6778 | @node Operations | ||
| 6779 | @subsubsection Operations | ||
| 6780 | |||
| 6781 | @c %**end of header | ||
| 6782 | |||
| 6783 | Operations to be initiated by the local peer are created with | ||
| 6784 | @code{GNUNET_SET_prepare}. Note that the operation will not be started | ||
| 6785 | until the client calls @code{GNUNET_SET_commit} | ||
| 6786 | (see Section "Supplying a Set"). | ||
| 6787 | |||
| 6788 | @node Supplying a Set | ||
| 6789 | @subsubsection Supplying a Set | ||
| 6790 | |||
| 6791 | @c %**end of header | ||
| 6792 | |||
| 6793 | To create symmetry between the two ways of starting a set operation | ||
| 6794 | (accepting and initiating it), the operation handles returned by | ||
| 6795 | @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare} do not yet have a | ||
| 6796 | set to operate on, thus they can not do any work yet. | ||
| 6797 | |||
| 6798 | The client must call @code{GNUNET_SET_commit} to specify a set to use for | ||
| 6799 | an operation. @code{GNUNET_SET_commit} may only be called once per set | ||
| 6800 | operation. | ||
| 6801 | |||
| 6802 | @node The Result Callback | ||
| 6803 | @subsubsection The Result Callback | ||
| 6804 | |||
| 6805 | @c %**end of header | ||
| 6806 | |||
| 6807 | Clients must specify both a result mode and a result callback with | ||
| 6808 | @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare}. The result | ||
| 6809 | callback with a status indicating either that an element was received, or | ||
| 6810 | the operation failed or succeeded. | ||
| 6811 | The interpretation of the received element depends on the result mode. | ||
| 6812 | The callback needs to know which result mode it is used in, as the | ||
| 6813 | arguments do not indicate if an element is part of the full result set, | ||
| 6814 | or if it is in the difference between the original set and the final set. | ||
| 6815 | |||
| 6816 | @node The SET Client-Service Protocol | ||
| 6817 | @subsection The SET Client-Service Protocol | ||
| 6818 | |||
| 6819 | @c %**end of header | ||
| 6820 | |||
| 6821 | @menu | ||
| 6822 | * Creating Sets:: | ||
| 6823 | * Listeners2:: | ||
| 6824 | * Initiating Operations:: | ||
| 6825 | * Modifying Sets:: | ||
| 6826 | * Results and Operation Status:: | ||
| 6827 | * Iterating Sets:: | ||
| 6828 | @end menu | ||
| 6829 | |||
| 6830 | @node Creating Sets | ||
| 6831 | @subsubsection Creating Sets | ||
| 6832 | |||
| 6833 | @c %**end of header | ||
| 6834 | |||
| 6835 | For each set of a client, there exists a client connection to the service. | ||
| 6836 | Sets are created by sending the @code{GNUNET_SERVICE_SET_CREATE} message | ||
| 6837 | over a new client connection. Multiple operations for one set are | ||
| 6838 | multiplexed over one client connection, using a request id supplied by | ||
| 6839 | the client. | ||
| 6840 | |||
| 6841 | @node Listeners2 | ||
| 6842 | @subsubsection Listeners2 | ||
| 6843 | |||
| 6844 | @c %**end of header | ||
| 6845 | |||
| 6846 | Each listener also requires a seperate client connection. By sending the | ||
| 6847 | @code{GNUNET_SERVICE_SET_LISTEN} message, the client notifies the service | ||
| 6848 | of the application id and operation type it is interested in. A client | ||
| 6849 | rejects an incoming request by sending @code{GNUNET_SERVICE_SET_REJECT} | ||
| 6850 | on the listener's client connection. | ||
| 6851 | In contrast, when accepting an incoming request, a | ||
| 6852 | @code{GNUNET_SERVICE_SET_ACCEPT} message must be sent over the@ set that | ||
| 6853 | is supplied for the set operation. | ||
| 6854 | |||
| 6855 | @node Initiating Operations | ||
| 6856 | @subsubsection Initiating Operations | ||
| 6857 | |||
| 6858 | @c %**end of header | ||
| 6859 | |||
| 6860 | Operations with remote peers are initiated by sending a | ||
| 6861 | @code{GNUNET_SERVICE_SET_EVALUATE} message to the service. The@ client | ||
| 6862 | connection that this message is sent by determines the set to use. | ||
| 6863 | |||
| 6864 | @node Modifying Sets | ||
| 6865 | @subsubsection Modifying Sets | ||
| 6866 | |||
| 6867 | @c %**end of header | ||
| 6868 | |||
| 6869 | Sets are modified with the @code{GNUNET_SERVICE_SET_ADD} and | ||
| 6870 | @code{GNUNET_SERVICE_SET_REMOVE} messages. | ||
| 6871 | |||
| 6872 | |||
| 6873 | @c %@menu | ||
| 6874 | @c %* Results and Operation Status:: | ||
| 6875 | @c %* Iterating Sets:: | ||
| 6876 | @c %@end menu | ||
| 6877 | |||
| 6878 | @node Results and Operation Status | ||
| 6879 | @subsubsection Results and Operation Status | ||
| 6880 | @c %**end of header | ||
| 6881 | |||
| 6882 | The service notifies the client of result elements and success/failure of | ||
| 6883 | a set operation with the @code{GNUNET_SERVICE_SET_RESULT} message. | ||
| 6884 | |||
| 6885 | @node Iterating Sets | ||
| 6886 | @subsubsection Iterating Sets | ||
| 6887 | |||
| 6888 | @c %**end of header | ||
| 6889 | |||
| 6890 | All elements of a set can be requested by sending | ||
| 6891 | @code{GNUNET_SERVICE_SET_ITER_REQUEST}. The server responds with | ||
| 6892 | @code{GNUNET_SERVICE_SET_ITER_ELEMENT} and eventually terminates the | ||
| 6893 | iteration with @code{GNUNET_SERVICE_SET_ITER_DONE}. | ||
| 6894 | After each received element, the client | ||
| 6895 | must send @code{GNUNET_SERVICE_SET_ITER_ACK}. Note that only one set | ||
| 6896 | iteration may be active for a set at any given time. | ||
| 6897 | |||
| 6898 | @node The SET Intersection Peer-to-Peer Protocol | ||
| 6899 | @subsection The SET Intersection Peer-to-Peer Protocol | ||
| 6900 | |||
| 6901 | @c %**end of header | ||
| 6902 | |||
| 6903 | The intersection protocol operates over CADET and starts with a | ||
| 6904 | GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer | ||
| 6905 | initiating the operation to the peer listening for inbound requests. | ||
| 6906 | It includes the number of elements of the initiating peer, which is used | ||
| 6907 | to decide which side will send a Bloom filter first. | ||
| 6908 | |||
| 6909 | The listening peer checks if the operation type and application | ||
| 6910 | identifier are acceptable for its current state. | ||
| 6911 | If not, it responds with a GNUNET_MESSAGE_TYPE_SET_RESULT and a status of | ||
| 6912 | GNUNET_SET_STATUS_FAILURE (and terminates the CADET channel). | ||
| 6913 | |||
| 6914 | If the application accepts the request, the listener sends back a | ||
| 6915 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_ELEMENT_INFO} if it has | ||
| 6916 | more elements in the set than the client. | ||
| 6917 | Otherwise, it immediately starts with the Bloom filter exchange. | ||
| 6918 | If the initiator receives a | ||
| 6919 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_ELEMENT_INFO} response, | ||
| 6920 | it beings the Bloom filter exchange, unless the set size is indicated to | ||
| 6921 | be zero, in which case the intersection is considered finished after | ||
| 6922 | just the initial handshake. | ||
| 6923 | |||
| 6924 | |||
| 6925 | @menu | ||
| 6926 | * The Bloom filter exchange:: | ||
| 6927 | * Salt:: | ||
| 6928 | @end menu | ||
| 6929 | |||
| 6930 | @node The Bloom filter exchange | ||
| 6931 | @subsubsection The Bloom filter exchange | ||
| 6932 | |||
| 6933 | @c %**end of header | ||
| 6934 | |||
| 6935 | In this phase, each peer transmits a Bloom filter over the remaining | ||
| 6936 | keys of the local set to the other peer using a | ||
| 6937 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_BF} message. This | ||
| 6938 | message additionally includes the number of elements left in the sender's | ||
| 6939 | set, as well as the XOR over all of the keys in that set. | ||
| 6940 | |||
| 6941 | The number of bits 'k' set per element in the Bloom filter is calculated | ||
| 6942 | based on the relative size of the two sets. | ||
| 6943 | Furthermore, the size of the Bloom filter is calculated based on 'k' and | ||
| 6944 | the number of elements in the set to maximize the amount of data filtered | ||
| 6945 | per byte transmitted on the wire (while avoiding an excessively high | ||
| 6946 | number of iterations). | ||
| 6947 | |||
| 6948 | The receiver of the message removes all elements from its local set that | ||
| 6949 | do not pass the Bloom filter test. | ||
| 6950 | It then checks if the set size of the sender and the XOR over the keys | ||
| 6951 | match what is left of its own set. If they do, it sends a | ||
| 6952 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_DONE} back to indicate | ||
| 6953 | that the latest set is the final result. | ||
| 6954 | Otherwise, the receiver starts another Bloom filter exchange, except | ||
| 6955 | this time as the sender. | ||
| 6956 | |||
| 6957 | @node Salt | ||
| 6958 | @subsubsection Salt | ||
| 6959 | |||
| 6960 | @c %**end of header | ||
| 6961 | |||
| 6962 | Bloomfilter operations are probabilistic: With some non-zero probability | ||
| 6963 | the test may incorrectly say an element is in the set, even though it is | ||
| 6964 | not. | ||
| 6965 | |||
| 6966 | To mitigate this problem, the intersection protocol iterates exchanging | ||
| 6967 | Bloom filters using a different random 32-bit salt in each iteration (the | ||
| 6968 | salt is also included in the message). | ||
| 6969 | With different salts, set operations may fail for different elements. | ||
| 6970 | Merging the results from the executions, the probability of failure drops | ||
| 6971 | to zero. | ||
| 6972 | |||
| 6973 | The iterations terminate once both peers have established that they have | ||
| 6974 | sets of the same size, and where the XOR over all keys computes the same | ||
| 6975 | 512-bit value (leaving a failure probability of 2-511). | ||
| 6976 | |||
| 6977 | @node The SET Union Peer-to-Peer Protocol | ||
| 6978 | @subsection The SET Union Peer-to-Peer Protocol | ||
| 6979 | |||
| 6980 | @c %**end of header | ||
| 6981 | |||
| 6982 | The SET union protocol is based on Eppstein's efficient set reconciliation | ||
| 6983 | without prior context. You should read this paper first if you want to | ||
| 6984 | understand the protocol. | ||
| 6985 | |||
| 6986 | The union protocol operates over CADET and starts with a | ||
| 6987 | GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer | ||
| 6988 | initiating the operation to the peer listening for inbound requests. | ||
| 6989 | It includes the number of elements of the initiating peer, which is | ||
| 6990 | currently not used. | ||
| 6991 | |||
| 6992 | The listening peer checks if the operation type and application | ||
| 6993 | identifier are acceptable for its current state. If not, it responds with | ||
| 6994 | a @code{GNUNET_MESSAGE_TYPE_SET_RESULT} and a status of | ||
| 6995 | @code{GNUNET_SET_STATUS_FAILURE} (and terminates the CADET channel). | ||
| 6996 | |||
| 6997 | If the application accepts the request, it sends back a strata estimator | ||
| 6998 | using a message of type GNUNET_MESSAGE_TYPE_SET_UNION_P2P_SE. The | ||
| 6999 | initiator evaluates the strata estimator and initiates the exchange of | ||
| 7000 | invertible Bloom filters, sending a GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF. | ||
| 7001 | |||
| 7002 | During the IBF exchange, if the receiver cannot invert the Bloom filter or | ||
| 7003 | detects a cycle, it sends a larger IBF in response (up to a defined | ||
| 7004 | maximum limit; if that limit is reached, the operation fails). | ||
| 7005 | Elements decoded while processing the IBF are transmitted to the other | ||
| 7006 | peer using GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENTS, or requested from the | ||
| 7007 | other peer using GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENT_REQUESTS messages, | ||
| 7008 | depending on the sign observed during decoding of the IBF. | ||
| 7009 | Peers respond to a GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENT_REQUESTS message | ||
| 7010 | with the respective element in a GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENTS | ||
| 7011 | message. If the IBF fully decodes, the peer responds with a | ||
| 7012 | GNUNET_MESSAGE_TYPE_SET_UNION_P2P_DONE message instead of another | ||
| 7013 | GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF. | ||
| 7014 | |||
| 7015 | All Bloom filter operations use a salt to mingle keys before hashing them | ||
| 7016 | into buckets, such that future iterations have a fresh chance of | ||
| 7017 | succeeding if they failed due to collisions before. | ||
| 7018 | |||
| 7019 | @cindex STATISTICS Subsystem | ||
| 7020 | @node STATISTICS Subsystem | ||
| 7021 | @section STATISTICS Subsystem | ||
| 7022 | |||
| 7023 | @c %**end of header | ||
| 7024 | |||
| 7025 | In GNUnet, the STATISTICS subsystem offers a central place for all | ||
| 7026 | subsystems to publish unsigned 64-bit integer run-time statistics. | ||
| 7027 | Keeping this information centrally means that there is a unified way for | ||
| 7028 | the user to obtain data on all subsystems, and individual subsystems do | ||
| 7029 | not have to always include a custom data export method for performance | ||
| 7030 | metrics and other statistics. For example, the TRANSPORT system uses | ||
| 7031 | STATISTICS to update information about the number of directly connected | ||
| 7032 | peers and the bandwidth that has been consumed by the various plugins. | ||
| 7033 | This information is valuable for diagnosing connectivity and performance | ||
| 7034 | issues. | ||
| 7035 | |||
| 7036 | Following the GNUnet service architecture, the STATISTICS subsystem is | ||
| 7037 | divided into an API which is exposed through the header | ||
| 7038 | @strong{gnunet_statistics_service.h} and the STATISTICS service | ||
| 7039 | @strong{gnunet-service-statistics}. The @strong{gnunet-statistics} | ||
| 7040 | command-line tool can be used to obtain (and change) information about | ||
| 7041 | the values stored by the STATISTICS service. The STATISTICS service does | ||
| 7042 | not communicate with other peers. | ||
| 7043 | |||
| 7044 | Data is stored in the STATISTICS service in the form of tuples | ||
| 7045 | @strong{(subsystem, name, value, persistence)}. The subsystem determines | ||
| 7046 | to which other GNUnet's subsystem the data belongs. name is the name | ||
| 7047 | through which value is associated. It uniquely identifies the record | ||
| 7048 | from among other records belonging to the same subsystem. | ||
| 7049 | In some parts of the code, the pair @strong{(subsystem, name)} is called | ||
| 7050 | a @strong{statistic} as it identifies the values stored in the STATISTCS | ||
| 7051 | service.The persistence flag determines if the record has to be preserved | ||
| 7052 | across service restarts. A record is said to be persistent if this flag | ||
| 7053 | is set for it; if not, the record is treated as a non-persistent record | ||
| 7054 | and it is lost after service restart. Persistent records are written to | ||
| 7055 | and read from the file @strong{statistics.data} before shutdown | ||
| 7056 | and upon startup. The file is located in the HOME directory of the peer. | ||
| 7057 | |||
| 7058 | An anomaly of the STATISTICS service is that it does not terminate | ||
| 7059 | immediately upon receiving a shutdown signal if it has any clients | ||
| 7060 | connected to it. It waits for all the clients that are not monitors to | ||
| 7061 | close their connections before terminating itself. | ||
| 7062 | This is to prevent the loss of data during peer shutdown --- delaying the | ||
| 7063 | STATISTICS service shutdown helps other services to store important data | ||
| 7064 | to STATISTICS during shutdown. | ||
| 7065 | |||
| 7066 | @menu | ||
| 7067 | * libgnunetstatistics:: | ||
| 7068 | * The STATISTICS Client-Service Protocol:: | ||
| 7069 | @end menu | ||
| 7070 | |||
| 7071 | @cindex libgnunetstatistics | ||
| 7072 | @node libgnunetstatistics | ||
| 7073 | @subsection libgnunetstatistics | ||
| 7074 | |||
| 7075 | @c %**end of header | ||
| 7076 | |||
| 7077 | @strong{libgnunetstatistics} is the library containing the API for the | ||
| 7078 | STATISTICS subsystem. Any process requiring to use STATISTICS should use | ||
| 7079 | this API by to open a connection to the STATISTICS service. | ||
| 7080 | This is done by calling the function @code{GNUNET_STATISTICS_create()}. | ||
| 7081 | This function takes the subsystem's name which is trying to use STATISTICS | ||
| 7082 | and a configuration. | ||
| 7083 | All values written to STATISTICS with this connection will be placed in | ||
| 7084 | the section corresponding to the given subsystem's name. | ||
| 7085 | The connection to STATISTICS can be destroyed with the function | ||
| 7086 | @code{GNUNET_STATISTICS_destroy()}. This function allows for the | ||
| 7087 | connection to be destroyed immediately or upon transferring all | ||
| 7088 | pending write requests to the service. | ||
| 7089 | |||
| 7090 | Note: STATISTICS subsystem can be disabled by setting @code{DISABLE = YES} | ||
| 7091 | under the @code{[STATISTICS]} section in the configuration. With such a | ||
| 7092 | configuration all calls to @code{GNUNET_STATISTICS_create()} return | ||
| 7093 | @code{NULL} as the STATISTICS subsystem is unavailable and no other | ||
| 7094 | functions from the API can be used. | ||
| 7095 | |||
| 7096 | |||
| 7097 | @menu | ||
| 7098 | * Statistics retrieval:: | ||
| 7099 | * Setting statistics and updating them:: | ||
| 7100 | * Watches:: | ||
| 7101 | @end menu | ||
| 7102 | |||
| 7103 | @node Statistics retrieval | ||
| 7104 | @subsubsection Statistics retrieval | ||
| 7105 | |||
| 7106 | @c %**end of header | ||
| 7107 | |||
| 7108 | Once a connection to the statistics service is obtained, information | ||
| 7109 | about any other system which uses statistics can be retrieved with the | ||
| 7110 | function GNUNET_STATISTICS_get(). | ||
| 7111 | This function takes the connection handle, the name of the subsystem | ||
| 7112 | whose information we are interested in (a @code{NULL} value will | ||
| 7113 | retrieve information of all available subsystems using STATISTICS), the | ||
| 7114 | name of the statistic we are interested in (a @code{NULL} value will | ||
| 7115 | retrieve all available statistics), a continuation callback which is | ||
| 7116 | called when all of requested information is retrieved, an iterator | ||
| 7117 | callback which is called for each parameter in the retrieved information | ||
| 7118 | and a closure for the aforementioned callbacks. The library then invokes | ||
| 7119 | the iterator callback for each value matching the request. | ||
| 7120 | |||
| 7121 | Call to @code{GNUNET_STATISTICS_get()} is asynchronous and can be | ||
| 7122 | canceled with the function @code{GNUNET_STATISTICS_get_cancel()}. | ||
| 7123 | This is helpful when retrieving statistics takes too long and especially | ||
| 7124 | when we want to shutdown and cleanup everything. | ||
| 7125 | |||
| 7126 | @node Setting statistics and updating them | ||
| 7127 | @subsubsection Setting statistics and updating them | ||
| 7128 | |||
| 7129 | @c %**end of header | ||
| 7130 | |||
| 7131 | So far we have seen how to retrieve statistics, here we will learn how we | ||
| 7132 | can set statistics and update them so that other subsystems can retrieve | ||
| 7133 | them. | ||
| 7134 | |||
| 7135 | A new statistic can be set using the function | ||
| 7136 | @code{GNUNET_STATISTICS_set()}. | ||
| 7137 | This function takes the name of the statistic and its value and a flag to | ||
| 7138 | make the statistic persistent. | ||
| 7139 | The value of the statistic should be of the type @code{uint64_t}. | ||
| 7140 | The function does not take the name of the subsystem; it is determined | ||
| 7141 | from the previous @code{GNUNET_STATISTICS_create()} invocation. If | ||
| 7142 | the given statistic is already present, its value is overwritten. | ||
| 7143 | |||
| 7144 | An existing statistics can be updated, i.e its value can be increased or | ||
| 7145 | decreased by an amount with the function | ||
| 7146 | @code{GNUNET_STATISTICS_update()}. | ||
| 7147 | The parameters to this function are similar to | ||
| 7148 | @code{GNUNET_STATISTICS_set()}, except that it takes the amount to be | ||
| 7149 | changed as a type @code{int64_t} instead of the value. | ||
| 7150 | |||
| 7151 | The library will combine multiple set or update operations into one | ||
| 7152 | message if the client performs requests at a rate that is faster than the | ||
| 7153 | available IPC with the STATISTICS service. Thus, the client does not have | ||
| 7154 | to worry about sending requests too quickly. | ||
| 7155 | |||
| 7156 | @node Watches | ||
| 7157 | @subsubsection Watches | ||
| 7158 | |||
| 7159 | @c %**end of header | ||
| 7160 | |||
| 7161 | As interesting feature of STATISTICS lies in serving notifications | ||
| 7162 | whenever a statistic of our interest is modified. | ||
| 7163 | This is achieved by registering a watch through the function | ||
| 7164 | @code{GNUNET_STATISTICS_watch()}. | ||
| 7165 | The parameters of this function are similar to those of | ||
| 7166 | @code{GNUNET_STATISTICS_get()}. | ||
| 7167 | Changes to the respective statistic's value will then cause the given | ||
| 7168 | iterator callback to be called. | ||
| 7169 | Note: A watch can only be registered for a specific statistic. Hence | ||
| 7170 | the subsystem name and the parameter name cannot be @code{NULL} in a | ||
| 7171 | call to @code{GNUNET_STATISTICS_watch()}. | ||
| 7172 | |||
| 7173 | A registered watch will keep notifying any value changes until | ||
| 7174 | @code{GNUNET_STATISTICS_watch_cancel()} is called with the same | ||
| 7175 | parameters that are used for registering the watch. | ||
| 7176 | |||
| 7177 | @node The STATISTICS Client-Service Protocol | ||
| 7178 | @subsection The STATISTICS Client-Service Protocol | ||
| 7179 | @c %**end of header | ||
| 7180 | |||
| 7181 | |||
| 7182 | @menu | ||
| 7183 | * Statistics retrieval2:: | ||
| 7184 | * Setting and updating statistics:: | ||
| 7185 | * Watching for updates:: | ||
| 7186 | @end menu | ||
| 7187 | |||
| 7188 | @node Statistics retrieval2 | ||
| 7189 | @subsubsection Statistics retrieval2 | ||
| 7190 | |||
| 7191 | @c %**end of header | ||
| 7192 | |||
| 7193 | To retrieve statistics, the client transmits a message of type | ||
| 7194 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_GET} containing the given subsystem | ||
| 7195 | name and statistic parameter to the STATISTICS service. | ||
| 7196 | The service responds with a message of type | ||
| 7197 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_VALUE} for each of the statistics | ||
| 7198 | parameters that match the client request for the client. The end of | ||
| 7199 | information retrieved is signaled by the service by sending a message of | ||
| 7200 | type @code{GNUNET_MESSAGE_TYPE_STATISTICS_END}. | ||
| 7201 | |||
| 7202 | @node Setting and updating statistics | ||
| 7203 | @subsubsection Setting and updating statistics | ||
| 7204 | |||
| 7205 | @c %**end of header | ||
| 7206 | |||
| 7207 | The subsystem name, parameter name, its value and the persistence flag are | ||
| 7208 | communicated to the service through the message | ||
| 7209 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET}. | ||
| 7210 | |||
| 7211 | When the service receives a message of type | ||
| 7212 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET}, it retrieves the subsystem | ||
| 7213 | name and checks for a statistic parameter with matching the name given in | ||
| 7214 | the message. | ||
| 7215 | If a statistic parameter is found, the value is overwritten by the new | ||
| 7216 | value from the message; if not found then a new statistic parameter is | ||
| 7217 | created with the given name and value. | ||
| 7218 | |||
| 7219 | In addition to just setting an absolute value, it is possible to perform a | ||
| 7220 | relative update by sending a message of type | ||
| 7221 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET} with an update flag | ||
| 7222 | (@code{GNUNET_STATISTICS_SETFLAG_RELATIVE}) signifying that the value in | ||
| 7223 | the message should be treated as an update value. | ||
| 7224 | |||
| 7225 | @node Watching for updates | ||
| 7226 | @subsubsection Watching for updates | ||
| 7227 | |||
| 7228 | @c %**end of header | ||
| 7229 | |||
| 7230 | The function registers the watch at the service by sending a message of | ||
| 7231 | type @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH}. The service then sends | ||
| 7232 | notifications through messages of type | ||
| 7233 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH_VALUE} whenever the statistic | ||
| 7234 | parameter's value is changed. | ||
| 7235 | |||
| 7236 | @cindex DHT | ||
| 7237 | @cindex Distributed Hash Table | ||
| 7238 | @node Distributed Hash Table (DHT) | ||
| 7239 | @section Distributed Hash Table (DHT) | ||
| 7240 | |||
| 7241 | @c %**end of header | ||
| 7242 | |||
| 7243 | GNUnet includes a generic distributed hash table that can be used by | ||
| 7244 | developers building P2P applications in the framework. | ||
| 7245 | This section documents high-level features and how developers are | ||
| 7246 | expected to use the DHT. | ||
| 7247 | We have a research paper detailing how the DHT works. | ||
| 7248 | Also, Nate's thesis includes a detailed description and performance | ||
| 7249 | analysis (in chapter 6). | ||
| 7250 | |||
| 7251 | Key features of GNUnet's DHT include: | ||
| 7252 | |||
| 7253 | @itemize @bullet | ||
| 7254 | @item stores key-value pairs with values up to (approximately) 63k in size | ||
| 7255 | @item works with many underlay network topologies (small-world, random | ||
| 7256 | graph), underlay does not need to be a full mesh / clique | ||
| 7257 | @item support for extended queries (more than just a simple 'key'), | ||
| 7258 | filtering duplicate replies within the network (bloomfilter) and content | ||
| 7259 | validation (for details, please read the subsection on the block library) | ||
| 7260 | @item can (optionally) return paths taken by the PUT and GET operations | ||
| 7261 | to the application | ||
| 7262 | @item provides content replication to handle churn | ||
| 7263 | @end itemize | ||
| 7264 | |||
| 7265 | GNUnet's DHT is randomized and unreliable. Unreliable means that there is | ||
| 7266 | no strict guarantee that a value stored in the DHT is always | ||
| 7267 | found --- values are only found with high probability. | ||
| 7268 | While this is somewhat true in all P2P DHTs, GNUnet developers should be | ||
| 7269 | particularly wary of this fact (this will help you write secure, | ||
| 7270 | fault-tolerant code). Thus, when writing any application using the DHT, | ||
| 7271 | you should always consider the possibility that a value stored in the | ||
| 7272 | DHT by you or some other peer might simply not be returned, or returned | ||
| 7273 | with a significant delay. | ||
| 7274 | Your application logic must be written to tolerate this (naturally, some | ||
| 7275 | loss of performance or quality of service is expected in this case). | ||
| 7276 | |||
| 7277 | @menu | ||
| 7278 | * Block library and plugins:: | ||
| 7279 | * libgnunetdht:: | ||
| 7280 | * The DHT Client-Service Protocol:: | ||
| 7281 | * The DHT Peer-to-Peer Protocol:: | ||
| 7282 | @end menu | ||
| 7283 | |||
| 7284 | @node Block library and plugins | ||
| 7285 | @subsection Block library and plugins | ||
| 7286 | |||
| 7287 | @c %**end of header | ||
| 7288 | |||
| 7289 | @menu | ||
| 7290 | * What is a Block?:: | ||
| 7291 | * The API of libgnunetblock:: | ||
| 7292 | * Queries:: | ||
| 7293 | * Sample Code:: | ||
| 7294 | * Conclusion2:: | ||
| 7295 | @end menu | ||
| 7296 | |||
| 7297 | @node What is a Block? | ||
| 7298 | @subsubsection What is a Block? | ||
| 7299 | |||
| 7300 | @c %**end of header | ||
| 7301 | |||
| 7302 | Blocks are small (< 63k) pieces of data stored under a key (struct | ||
| 7303 | GNUNET_HashCode). Blocks have a type (enum GNUNET_BlockType) which defines | ||
| 7304 | their data format. Blocks are used in GNUnet as units of static data | ||
| 7305 | exchanged between peers and stored (or cached) locally. | ||
| 7306 | Uses of blocks include file-sharing (the files are broken up into blocks), | ||
| 7307 | the VPN (DNS information is stored in blocks) and the DHT (all | ||
| 7308 | information in the DHT and meta-information for the maintenance of the | ||
| 7309 | DHT are both stored using blocks). | ||
| 7310 | The block subsystem provides a few common functions that must be | ||
| 7311 | available for any type of block. | ||
| 7312 | |||
| 7313 | @cindex libgnunetblock API | ||
| 7314 | @node The API of libgnunetblock | ||
| 7315 | @subsubsection The API of libgnunetblock | ||
| 7316 | |||
| 7317 | @c %**end of header | ||
| 7318 | |||
| 7319 | The block library requires for each (family of) block type(s) a block | ||
| 7320 | plugin (implementing @file{gnunet_block_plugin.h}) that provides basic | ||
| 7321 | functions that are needed by the DHT (and possibly other subsystems) to | ||
| 7322 | manage the block. | ||
| 7323 | These block plugins are typically implemented within their respective | ||
| 7324 | subsystems. | ||
| 7325 | The main block library is then used to locate, load and query the | ||
| 7326 | appropriate block plugin. | ||
| 7327 | Which plugin is appropriate is determined by the block type (which is | ||
| 7328 | just a 32-bit integer). Block plugins contain code that specifies which | ||
| 7329 | block types are supported by a given plugin. The block library loads all | ||
| 7330 | block plugins that are installed at the local peer and forwards the | ||
| 7331 | application request to the respective plugin. | ||
| 7332 | |||
| 7333 | The central functions of the block APIs (plugin and main library) are to | ||
| 7334 | allow the mapping of blocks to their respective key (if possible) and the | ||
| 7335 | ability to check that a block is well-formed and matches a given | ||
| 7336 | request (again, if possible). | ||
| 7337 | This way, GNUnet can avoid storing invalid blocks, storing blocks under | ||
| 7338 | the wrong key and forwarding blocks in response to a query that they do | ||
| 7339 | not answer. | ||
| 7340 | |||
| 7341 | One key function of block plugins is that it allows GNUnet to detect | ||
| 7342 | duplicate replies (via the Bloom filter). All plugins MUST support | ||
| 7343 | detecting duplicate replies (by adding the current response to the | ||
| 7344 | Bloom filter and rejecting it if it is encountered again). | ||
| 7345 | If a plugin fails to do this, responses may loop in the network. | ||
| 7346 | |||
| 7347 | @node Queries | ||
| 7348 | @subsubsection Queries | ||
| 7349 | @c %**end of header | ||
| 7350 | |||
| 7351 | The query format for any block in GNUnet consists of four main components. | ||
| 7352 | First, the type of the desired block must be specified. Second, the query | ||
| 7353 | must contain a hash code. The hash code is used for lookups in hash | ||
| 7354 | tables and databases and must not be unique for the block (however, if | ||
| 7355 | possible a unique hash should be used as this would be best for | ||
| 7356 | performance). | ||
| 7357 | Third, an optional Bloom filter can be specified to exclude known results; | ||
| 7358 | replies that hash to the bits set in the Bloom filter are considered | ||
| 7359 | invalid. False-positives can be eliminated by sending the same query | ||
| 7360 | again with a different Bloom filter mutator value, which parameterizes | ||
| 7361 | the hash function that is used. | ||
| 7362 | Finally, an optional application-specific "eXtended query" (xquery) can | ||
| 7363 | be specified to further constrain the results. It is entirely up to | ||
| 7364 | the type-specific plugin to determine whether or not a given block | ||
| 7365 | matches a query (type, hash, Bloom filter, and xquery). | ||
| 7366 | Naturally, not all xquery's are valid and some types of blocks may not | ||
| 7367 | support Bloom filters either, so the plugin also needs to check if the | ||
| 7368 | query is valid in the first place. | ||
| 7369 | |||
| 7370 | Depending on the results from the plugin, the DHT will then discard the | ||
| 7371 | (invalid) query, forward the query, discard the (invalid) reply, cache the | ||
| 7372 | (valid) reply, and/or forward the (valid and non-duplicate) reply. | ||
| 7373 | |||
| 7374 | @node Sample Code | ||
| 7375 | @subsubsection Sample Code | ||
| 7376 | |||
| 7377 | @c %**end of header | ||
| 7378 | |||
| 7379 | The source code in @strong{plugin_block_test.c} is a good starting point | ||
| 7380 | for new block plugins --- it does the minimal work by implementing a | ||
| 7381 | plugin that performs no validation at all. | ||
| 7382 | The respective @strong{Makefile.am} shows how to build and install a | ||
| 7383 | block plugin. | ||
| 7384 | |||
| 7385 | @node Conclusion2 | ||
| 7386 | @subsubsection Conclusion2 | ||
| 7387 | |||
| 7388 | @c %**end of header | ||
| 7389 | |||
| 7390 | In conclusion, GNUnet subsystems that want to use the DHT need to define a | ||
| 7391 | block format and write a plugin to match queries and replies. For testing, | ||
| 7392 | the @code{GNUNET_BLOCK_TYPE_TEST} block type can be used; it accepts | ||
| 7393 | any query as valid and any reply as matching any query. | ||
| 7394 | This type is also used for the DHT command line tools. | ||
| 7395 | However, it should NOT be used for normal applications due to the lack | ||
| 7396 | of error checking that results from this primitive implementation. | ||
| 7397 | |||
| 7398 | @cindex libgnunetdht | ||
| 7399 | @node libgnunetdht | ||
| 7400 | @subsection libgnunetdht | ||
| 7401 | |||
| 7402 | @c %**end of header | ||
| 7403 | |||
| 7404 | The DHT API itself is pretty simple and offers the usual GET and PUT | ||
| 7405 | functions that work as expected. The specified block type refers to the | ||
| 7406 | block library which allows the DHT to run application-specific logic for | ||
| 7407 | data stored in the network. | ||
| 7408 | |||
| 7409 | |||
| 7410 | @menu | ||
| 7411 | * GET:: | ||
| 7412 | * PUT:: | ||
| 7413 | * MONITOR:: | ||
| 7414 | * DHT Routing Options:: | ||
| 7415 | @end menu | ||
| 7416 | |||
| 7417 | @node GET | ||
| 7418 | @subsubsection GET | ||
| 7419 | |||
| 7420 | @c %**end of header | ||
| 7421 | |||
| 7422 | When using GET, the main consideration for developers (other than the | ||
| 7423 | block library) should be that after issuing a GET, the DHT will | ||
| 7424 | continuously cause (small amounts of) network traffic until the operation | ||
| 7425 | is explicitly canceled. | ||
| 7426 | So GET does not simply send out a single network request once; instead, | ||
| 7427 | the DHT will continue to search for data. This is needed to achieve good | ||
| 7428 | success rates and also handles the case where the respective PUT | ||
| 7429 | operation happens after the GET operation was started. | ||
| 7430 | Developers should not cancel an existing GET operation and then | ||
| 7431 | explicitly re-start it to trigger a new round of network requests; | ||
| 7432 | this is simply inefficient, especially as the internal automated version | ||
| 7433 | can be more efficient, for example by filtering results in the network | ||
| 7434 | that have already been returned. | ||
| 7435 | |||
| 7436 | If an application that performs a GET request has a set of replies that it | ||
| 7437 | already knows and would like to filter, it can call@ | ||
| 7438 | @code{GNUNET_DHT_get_filter_known_results} with an array of hashes over | ||
| 7439 | the respective blocks to tell the DHT that these results are not | ||
| 7440 | desired (any more). | ||
| 7441 | This way, the DHT will filter the respective blocks using the block | ||
| 7442 | library in the network, which may result in a significant reduction in | ||
| 7443 | bandwidth consumption. | ||
| 7444 | |||
| 7445 | @node PUT | ||
| 7446 | @subsubsection PUT | ||
| 7447 | |||
| 7448 | @c %**end of header | ||
| 7449 | |||
| 7450 | @c inconsistent use of ``must'' above it's written ``MUST'' | ||
| 7451 | In contrast to GET operations, developers @strong{must} manually re-run | ||
| 7452 | PUT operations periodically (if they intend the content to continue to be | ||
| 7453 | available). Content stored in the DHT expires or might be lost due to | ||
| 7454 | churn. | ||
| 7455 | Furthermore, GNUnet's DHT typically requires multiple rounds of PUT | ||
| 7456 | operations before a key-value pair is consistently available to all | ||
| 7457 | peers (the DHT randomizes paths and thus storage locations, and only | ||
| 7458 | after multiple rounds of PUTs there will be a sufficient number of | ||
| 7459 | replicas in large DHTs). An explicit PUT operation using the DHT API will | ||
| 7460 | only cause network traffic once, so in order to ensure basic availability | ||
| 7461 | and resistance to churn (and adversaries), PUTs must be repeated. | ||
| 7462 | While the exact frequency depends on the application, a rule of thumb is | ||
| 7463 | that there should be at least a dozen PUT operations within the content | ||
| 7464 | lifetime. Content in the DHT typically expires after one day, so | ||
| 7465 | DHT PUT operations should be repeated at least every 1-2 hours. | ||
| 7466 | |||
| 7467 | @node MONITOR | ||
| 7468 | @subsubsection MONITOR | ||
| 7469 | |||
| 7470 | @c %**end of header | ||
| 7471 | |||
| 7472 | The DHT API also allows applications to monitor messages crossing the | ||
| 7473 | local DHT service. | ||
| 7474 | The types of messages used by the DHT are GET, PUT and RESULT messages. | ||
| 7475 | Using the monitoring API, applications can choose to monitor these | ||
| 7476 | requests, possibly limiting themselves to requests for a particular block | ||
| 7477 | type. | ||
| 7478 | |||
| 7479 | The monitoring API is not only useful for diagnostics, it can also be | ||
| 7480 | used to trigger application operations based on PUT operations. | ||
| 7481 | For example, an application may use PUTs to distribute work requests to | ||
| 7482 | other peers. | ||
| 7483 | The workers would then monitor for PUTs that give them work, instead of | ||
| 7484 | looking for work using GET operations. | ||
| 7485 | This can be beneficial, especially if the workers have no good way to | ||
| 7486 | guess the keys under which work would be stored. | ||
| 7487 | Naturally, additional protocols might be needed to ensure that the desired | ||
| 7488 | number of workers will process the distributed workload. | ||
| 7489 | |||
| 7490 | @node DHT Routing Options | ||
| 7491 | @subsubsection DHT Routing Options | ||
| 7492 | |||
| 7493 | @c %**end of header | ||
| 7494 | |||
| 7495 | There are two important options for GET and PUT requests: | ||
| 7496 | |||
| 7497 | @table @asis | ||
| 7498 | @item GNUNET_DHT_RO_DEMULITPLEX_EVERYWHERE This option means that all | ||
| 7499 | peers should process the request, even if their peer ID is not closest to | ||
| 7500 | the key. For a PUT request, this means that all peers that a request | ||
| 7501 | traverses may make a copy of the data. | ||
| 7502 | Similarly for a GET request, all peers will check their local database | ||
| 7503 | for a result. Setting this option can thus significantly improve caching | ||
| 7504 | and reduce bandwidth consumption --- at the expense of a larger DHT | ||
| 7505 | database. If in doubt, we recommend that this option should be used. | ||
| 7506 | @item GNUNET_DHT_RO_RECORD_ROUTE This option instructs the DHT to record | ||
| 7507 | the path that a GET or a PUT request is taking through the overlay | ||
| 7508 | network. The resulting paths are then returned to the application with | ||
| 7509 | the respective result. This allows the receiver of a result to construct | ||
| 7510 | a path to the originator of the data, which might then be used for | ||
| 7511 | routing. Naturally, setting this option requires additional bandwidth | ||
| 7512 | and disk space, so applications should only set this if the paths are | ||
| 7513 | needed by the application logic. | ||
| 7514 | @item GNUNET_DHT_RO_FIND_PEER This option is an internal option used by | ||
| 7515 | the DHT's peer discovery mechanism and should not be used by applications. | ||
| 7516 | @item GNUNET_DHT_RO_BART This option is currently not implemented. It may | ||
| 7517 | in the future offer performance improvements for clique topologies. | ||
| 7518 | @end table | ||
| 7519 | |||
| 7520 | @node The DHT Client-Service Protocol | ||
| 7521 | @subsection The DHT Client-Service Protocol | ||
| 7522 | |||
| 7523 | @c %**end of header | ||
| 7524 | |||
| 7525 | @menu | ||
| 7526 | * PUTting data into the DHT:: | ||
| 7527 | * GETting data from the DHT:: | ||
| 7528 | * Monitoring the DHT:: | ||
| 7529 | @end menu | ||
| 7530 | |||
| 7531 | @node PUTting data into the DHT | ||
| 7532 | @subsubsection PUTting data into the DHT | ||
| 7533 | |||
| 7534 | @c %**end of header | ||
| 7535 | |||
| 7536 | To store (PUT) data into the DHT, the client sends a | ||
| 7537 | @code{struct GNUNET_DHT_ClientPutMessage} to the service. | ||
| 7538 | This message specifies the block type, routing options, the desired | ||
| 7539 | replication level, the expiration time, key, | ||
| 7540 | value and a 64-bit unique ID for the operation. The service responds with | ||
| 7541 | a @code{struct GNUNET_DHT_ClientPutConfirmationMessage} with the same | ||
| 7542 | 64-bit unique ID. Note that the service sends the confirmation as soon as | ||
| 7543 | it has locally processed the PUT request. The PUT may still be | ||
| 7544 | propagating through the network at this time. | ||
| 7545 | |||
| 7546 | In the future, we may want to change this to provide (limited) feedback | ||
| 7547 | to the client, for example if we detect that the PUT operation had no | ||
| 7548 | effect because the same key-value pair was already stored in the DHT. | ||
| 7549 | However, changing this would also require additional state and messages | ||
| 7550 | in the P2P interaction. | ||
| 7551 | |||
| 7552 | @node GETting data from the DHT | ||
| 7553 | @subsubsection GETting data from the DHT | ||
| 7554 | |||
| 7555 | @c %**end of header | ||
| 7556 | |||
| 7557 | To retrieve (GET) data from the DHT, the client sends a | ||
| 7558 | @code{struct GNUNET_DHT_ClientGetMessage} to the service. The message | ||
| 7559 | specifies routing options, a replication level (for replicating the GET, | ||
| 7560 | not the content), the desired block type, the key, the (optional) | ||
| 7561 | extended query and unique 64-bit request ID. | ||
| 7562 | |||
| 7563 | Additionally, the client may send any number of | ||
| 7564 | @code{struct GNUNET_DHT_ClientGetResultSeenMessage}s to notify the | ||
| 7565 | service about results that the client is already aware of. | ||
| 7566 | These messages consist of the key, the unique 64-bit ID of the request, | ||
| 7567 | and an arbitrary number of hash codes over the blocks that the client is | ||
| 7568 | already aware of. As messages are restricted to 64k, a client that | ||
| 7569 | already knows more than about a thousand blocks may need to send | ||
| 7570 | several of these messages. Naturally, the client should transmit these | ||
| 7571 | messages as quickly as possible after the original GET request such that | ||
| 7572 | the DHT can filter those results in the network early on. Naturally, as | ||
| 7573 | these messages are sent after the original request, it is conceivable | ||
| 7574 | that the DHT service may return blocks that match those already known | ||
| 7575 | to the client anyway. | ||
| 7576 | |||
| 7577 | In response to a GET request, the service will send @code{struct | ||
| 7578 | GNUNET_DHT_ClientResultMessage}s to the client. These messages contain the | ||
| 7579 | block type, expiration, key, unique ID of the request and of course the | ||
| 7580 | value (a block). Depending on the options set for the respective | ||
| 7581 | operations, the replies may also contain the path the GET and/or the PUT | ||
| 7582 | took through the network. | ||
| 7583 | |||
| 7584 | A client can stop receiving replies either by disconnecting or by sending | ||
| 7585 | a @code{struct GNUNET_DHT_ClientGetStopMessage} which must contain the | ||
| 7586 | key and the 64-bit unique ID of the original request. Using an | ||
| 7587 | explicit "stop" message is more common as this allows a client to run | ||
| 7588 | many concurrent GET operations over the same connection with the DHT | ||
| 7589 | service --- and to stop them individually. | ||
| 7590 | |||
| 7591 | @node Monitoring the DHT | ||
| 7592 | @subsubsection Monitoring the DHT | ||
| 7593 | |||
| 7594 | @c %**end of header | ||
| 7595 | |||
| 7596 | To begin monitoring, the client sends a | ||
| 7597 | @code{struct GNUNET_DHT_MonitorStartStop} message to the DHT service. | ||
| 7598 | In this message, flags can be set to enable (or disable) monitoring of | ||
| 7599 | GET, PUT and RESULT messages that pass through a peer. The message can | ||
| 7600 | also restrict monitoring to a particular block type or a particular key. | ||
| 7601 | Once monitoring is enabled, the DHT service will notify the client about | ||
| 7602 | any matching event using @code{struct GNUNET_DHT_MonitorGetMessage}s for | ||
| 7603 | GET events, @code{struct GNUNET_DHT_MonitorPutMessage} for PUT events | ||
| 7604 | and @code{struct GNUNET_DHT_MonitorGetRespMessage} for RESULTs. Each of | ||
| 7605 | these messages contains all of the information about the event. | ||
| 7606 | |||
| 7607 | @node The DHT Peer-to-Peer Protocol | ||
| 7608 | @subsection The DHT Peer-to-Peer Protocol | ||
| 7609 | @c %**end of header | ||
| 7610 | |||
| 7611 | |||
| 7612 | @menu | ||
| 7613 | * Routing GETs or PUTs:: | ||
| 7614 | * PUTting data into the DHT2:: | ||
| 7615 | * GETting data from the DHT2:: | ||
| 7616 | @end menu | ||
| 7617 | |||
| 7618 | @node Routing GETs or PUTs | ||
| 7619 | @subsubsection Routing GETs or PUTs | ||
| 7620 | |||
| 7621 | @c %**end of header | ||
| 7622 | |||
| 7623 | When routing GETs or PUTs, the DHT service selects a suitable subset of | ||
| 7624 | neighbours for forwarding. The exact number of neighbours can be zero or | ||
| 7625 | more and depends on the hop counter of the query (initially zero) in | ||
| 7626 | relation to the (log of) the network size estimate, the desired | ||
| 7627 | replication level and the peer's connectivity. | ||
| 7628 | Depending on the hop counter and our network size estimate, the selection | ||
| 7629 | of the peers maybe randomized or by proximity to the key. | ||
| 7630 | Furthermore, requests include a set of peers that a request has already | ||
| 7631 | traversed; those peers are also excluded from the selection. | ||
| 7632 | |||
| 7633 | @node PUTting data into the DHT2 | ||
| 7634 | @subsubsection PUTting data into the DHT2 | ||
| 7635 | |||
| 7636 | @c %**end of header | ||
| 7637 | |||
| 7638 | To PUT data into the DHT, the service sends a @code{struct PeerPutMessage} | ||
| 7639 | of type @code{GNUNET_MESSAGE_TYPE_DHT_P2P_PUT} to the respective | ||
| 7640 | neighbour. | ||
| 7641 | In addition to the usual information about the content (type, routing | ||
| 7642 | options, desired replication level for the content, expiration time, key | ||
| 7643 | and value), the message contains a fixed-size Bloom filter with | ||
| 7644 | information about which peers (may) have already seen this request. | ||
| 7645 | This Bloom filter is used to ensure that DHT messages never loop back to | ||
| 7646 | a peer that has already processed the request. | ||
| 7647 | Additionally, the message includes the current hop counter and, depending | ||
| 7648 | on the routing options, the message may include the full path that the | ||
| 7649 | message has taken so far. | ||
| 7650 | The Bloom filter should already contain the identity of the previous hop; | ||
| 7651 | however, the path should not include the identity of the previous hop and | ||
| 7652 | the receiver should append the identity of the sender to the path, not | ||
| 7653 | its own identity (this is done to reduce bandwidth). | ||
| 7654 | |||
| 7655 | @node GETting data from the DHT2 | ||
| 7656 | @subsubsection GETting data from the DHT2 | ||
| 7657 | |||
| 7658 | @c %**end of header | ||
| 7659 | |||
| 7660 | A peer can search the DHT by sending @code{struct PeerGetMessage}s of type | ||
| 7661 | @code{GNUNET_MESSAGE_TYPE_DHT_P2P_GET} to other peers. In addition to the | ||
| 7662 | usual information about the request (type, routing options, desired | ||
| 7663 | replication level for the request, the key and the extended query), a GET | ||
| 7664 | request also contains a hop counter, a Bloom filter over the peers | ||
| 7665 | that have processed the request already and depending on the routing | ||
| 7666 | options the full path traversed by the GET. | ||
| 7667 | Finally, a GET request includes a variable-size second Bloom filter and a | ||
| 7668 | so-called Bloom filter mutator value which together indicate which | ||
| 7669 | replies the sender has already seen. During the lookup, each block that | ||
| 7670 | matches they block type, key and extended query is additionally subjected | ||
| 7671 | to a test against this Bloom filter. | ||
| 7672 | The block plugin is expected to take the hash of the block and combine it | ||
| 7673 | with the mutator value and check if the result is not yet in the Bloom | ||
| 7674 | filter. The originator of the query will from time to time modify the | ||
| 7675 | mutator to (eventually) allow false-positives filtered by the Bloom filter | ||
| 7676 | to be returned. | ||
| 7677 | |||
| 7678 | Peers that receive a GET request perform a local lookup (depending on | ||
| 7679 | their proximity to the key and the query options) and forward the request | ||
| 7680 | to other peers. | ||
| 7681 | They then remember the request (including the Bloom filter for blocking | ||
| 7682 | duplicate results) and when they obtain a matching, non-filtered response | ||
| 7683 | a @code{struct PeerResultMessage} of type | ||
| 7684 | @code{GNUNET_MESSAGE_TYPE_DHT_P2P_RESULT} is forwarded to the previous | ||
| 7685 | hop. | ||
| 7686 | Whenever a result is forwarded, the block plugin is used to update the | ||
| 7687 | Bloom filter accordingly, to ensure that the same result is never | ||
| 7688 | forwarded more than once. | ||
| 7689 | The DHT service may also cache forwarded results locally if the | ||
| 7690 | "CACHE_RESULTS" option is set to "YES" in the configuration. | ||
| 7691 | |||
| 7692 | @cindex GNS | ||
| 7693 | @cindex GNU Name System | ||
| 7694 | @node GNU Name System (GNS) | ||
| 7695 | @section GNU Name System (GNS) | ||
| 7696 | |||
| 7697 | @c %**end of header | ||
| 7698 | |||
| 7699 | The GNU Name System (GNS) is a decentralized database that enables users | ||
| 7700 | to securely resolve names to values. | ||
| 7701 | Names can be used to identify other users (for example, in social | ||
| 7702 | networking), or network services (for example, VPN services running at a | ||
| 7703 | peer in GNUnet, or purely IP-based services on the Internet). | ||
| 7704 | Users interact with GNS by typing in a hostname that ends in a | ||
| 7705 | top-level domain that is configured in the ``GNS'' section, matches | ||
| 7706 | an identity of the user or ends in a Base32-encoded public key. | ||
| 7707 | |||
| 7708 | Videos giving an overview of most of the GNS and the motivations behind | ||
| 7709 | it is available here and here. | ||
| 7710 | The remainder of this chapter targets developers that are familiar with | ||
| 7711 | high level concepts of GNS as presented in these talks. | ||
| 7712 | @c TODO: Add links to here and here and to these. | ||
| 7713 | |||
| 7714 | GNS-aware applications should use the GNS resolver to obtain the | ||
| 7715 | respective records that are stored under that name in GNS. | ||
| 7716 | Each record consists of a type, value, expiration time and flags. | ||
| 7717 | |||
| 7718 | The type specifies the format of the value. Types below 65536 correspond | ||
| 7719 | to DNS record types, larger values are used for GNS-specific records. | ||
| 7720 | Applications can define new GNS record types by reserving a number and | ||
| 7721 | implementing a plugin (which mostly needs to convert the binary value | ||
| 7722 | representation to a human-readable text format and vice-versa). | ||
| 7723 | The expiration time specifies how long the record is to be valid. | ||
| 7724 | The GNS API ensures that applications are only given non-expired values. | ||
| 7725 | The flags are typically irrelevant for applications, as GNS uses them | ||
| 7726 | internally to control visibility and validity of records. | ||
| 7727 | |||
| 7728 | Records are stored along with a signature. | ||
| 7729 | The signature is generated using the private key of the authoritative | ||
| 7730 | zone. This allows any GNS resolver to verify the correctness of a | ||
| 7731 | name-value mapping. | ||
| 7732 | |||
| 7733 | Internally, GNS uses the NAMECACHE to cache information obtained from | ||
| 7734 | other users, the NAMESTORE to store information specific to the local | ||
| 7735 | users, and the DHT to exchange data between users. | ||
| 7736 | A plugin API is used to enable applications to define new GNS | ||
| 7737 | record types. | ||
| 7738 | |||
| 7739 | @menu | ||
| 7740 | * libgnunetgns:: | ||
| 7741 | * libgnunetgnsrecord:: | ||
| 7742 | * GNS plugins:: | ||
| 7743 | * The GNS Client-Service Protocol:: | ||
| 7744 | * Hijacking the DNS-Traffic using gnunet-service-dns:: | ||
| 7745 | * Serving DNS lookups via GNS on W32:: | ||
| 7746 | @end menu | ||
| 7747 | |||
| 7748 | @node libgnunetgns | ||
| 7749 | @subsection libgnunetgns | ||
| 7750 | |||
| 7751 | @c %**end of header | ||
| 7752 | |||
| 7753 | The GNS API itself is extremely simple. Clients first connect to the | ||
| 7754 | GNS service using @code{GNUNET_GNS_connect}. | ||
| 7755 | They can then perform lookups using @code{GNUNET_GNS_lookup} or cancel | ||
| 7756 | pending lookups using @code{GNUNET_GNS_lookup_cancel}. | ||
| 7757 | Once finished, clients disconnect using @code{GNUNET_GNS_disconnect}. | ||
| 7758 | |||
| 7759 | @menu | ||
| 7760 | * Looking up records:: | ||
| 7761 | * Accessing the records:: | ||
| 7762 | * Creating records:: | ||
| 7763 | * Future work:: | ||
| 7764 | @end menu | ||
| 7765 | |||
| 7766 | @node Looking up records | ||
| 7767 | @subsubsection Looking up records | ||
| 7768 | |||
| 7769 | @c %**end of header | ||
| 7770 | |||
| 7771 | @code{GNUNET_GNS_lookup} takes a number of arguments: | ||
| 7772 | |||
| 7773 | @table @asis | ||
| 7774 | @item handle This is simply the GNS connection handle from | ||
| 7775 | @code{GNUNET_GNS_connect}. | ||
| 7776 | @item name The client needs to specify the name to | ||
| 7777 | be resolved. This can be any valid DNS or GNS hostname. | ||
| 7778 | @item zone The client | ||
| 7779 | needs to specify the public key of the GNS zone against which the | ||
| 7780 | resolution should be done. | ||
| 7781 | Note that a key must be provided, the client should | ||
| 7782 | look up plausible values using its configuration, | ||
| 7783 | the identity service and by attempting to interpret the | ||
| 7784 | TLD as a base32-encoded public key. | ||
| 7785 | @item type This is the desired GNS or DNS record type | ||
| 7786 | to look for. While all records for the given name will be returned, this | ||
| 7787 | can be important if the client wants to resolve record types that | ||
| 7788 | themselves delegate resolution, such as CNAME, PKEY or GNS2DNS. | ||
| 7789 | Resolving a record of any of these types will only work if the respective | ||
| 7790 | record type is specified in the request, as the GNS resolver will | ||
| 7791 | otherwise follow the delegation and return the records from the | ||
| 7792 | respective destination, instead of the delegating record. | ||
| 7793 | @item only_cached This argument should typically be set to | ||
| 7794 | @code{GNUNET_NO}. Setting it to @code{GNUNET_YES} disables resolution via | ||
| 7795 | the overlay network. | ||
| 7796 | @item shorten_zone_key If GNS encounters new names during resolution, | ||
| 7797 | their respective zones can automatically be learned and added to the | ||
| 7798 | "shorten zone". If this is desired, clients must pass the private key of | ||
| 7799 | the shorten zone. If NULL is passed, shortening is disabled. | ||
| 7800 | @item proc This argument identifies | ||
| 7801 | the function to call with the result. It is given proc_cls, the number of | ||
| 7802 | records found (possibly zero) and the array of the records as arguments. | ||
| 7803 | proc will only be called once. After proc,> has been called, the lookup | ||
| 7804 | must no longer be canceled. | ||
| 7805 | @item proc_cls The closure for proc. | ||
| 7806 | @end table | ||
| 7807 | |||
| 7808 | @node Accessing the records | ||
| 7809 | @subsubsection Accessing the records | ||
| 7810 | |||
| 7811 | @c %**end of header | ||
| 7812 | |||
| 7813 | The @code{libgnunetgnsrecord} library provides an API to manipulate the | ||
| 7814 | GNS record array that is given to proc. In particular, it offers | ||
| 7815 | functions such as converting record values to human-readable | ||
| 7816 | strings (and back). However, most @code{libgnunetgnsrecord} functions are | ||
| 7817 | not interesting to GNS client applications. | ||
| 7818 | |||
| 7819 | For DNS records, the @code{libgnunetdnsparser} library provides | ||
| 7820 | functions for parsing (and serializing) common types of DNS records. | ||
| 7821 | |||
| 7822 | @node Creating records | ||
| 7823 | @subsubsection Creating records | ||
| 7824 | |||
| 7825 | @c %**end of header | ||
| 7826 | |||
| 7827 | Creating GNS records is typically done by building the respective record | ||
| 7828 | information (possibly with the help of @code{libgnunetgnsrecord} and | ||
| 7829 | @code{libgnunetdnsparser}) and then using the @code{libgnunetnamestore} to | ||
| 7830 | publish the information. The GNS API is not involved in this | ||
| 7831 | operation. | ||
| 7832 | |||
| 7833 | @node Future work | ||
| 7834 | @subsubsection Future work | ||
| 7835 | |||
| 7836 | @c %**end of header | ||
| 7837 | |||
| 7838 | In the future, we want to expand @code{libgnunetgns} to allow | ||
| 7839 | applications to observe shortening operations performed during GNS | ||
| 7840 | resolution, for example so that users can receive visual feedback when | ||
| 7841 | this happens. | ||
| 7842 | |||
| 7843 | @node libgnunetgnsrecord | ||
| 7844 | @subsection libgnunetgnsrecord | ||
| 7845 | |||
| 7846 | @c %**end of header | ||
| 7847 | |||
| 7848 | The @code{libgnunetgnsrecord} library is used to manipulate GNS | ||
| 7849 | records (in plaintext or in their encrypted format). | ||
| 7850 | Applications mostly interact with @code{libgnunetgnsrecord} by using the | ||
| 7851 | functions to convert GNS record values to strings or vice-versa, or to | ||
| 7852 | lookup a GNS record type number by name (or vice-versa). | ||
| 7853 | The library also provides various other functions that are mostly | ||
| 7854 | used internally within GNS, such as converting keys to names, checking for | ||
| 7855 | expiration, encrypting GNS records to GNS blocks, verifying GNS block | ||
| 7856 | signatures and decrypting GNS records from GNS blocks. | ||
| 7857 | |||
| 7858 | We will now discuss the four commonly used functions of the API.@ | ||
| 7859 | @code{libgnunetgnsrecord} does not perform these operations itself, | ||
| 7860 | but instead uses plugins to perform the operation. | ||
| 7861 | GNUnet includes plugins to support common DNS record types as well as | ||
| 7862 | standard GNS record types. | ||
| 7863 | |||
| 7864 | @menu | ||
| 7865 | * Value handling:: | ||
| 7866 | * Type handling:: | ||
| 7867 | @end menu | ||
| 7868 | |||
| 7869 | @node Value handling | ||
| 7870 | @subsubsection Value handling | ||
| 7871 | |||
| 7872 | @c %**end of header | ||
| 7873 | |||
| 7874 | @code{GNUNET_GNSRECORD_value_to_string} can be used to convert | ||
| 7875 | the (binary) representation of a GNS record value to a human readable, | ||
| 7876 | 0-terminated UTF-8 string. | ||
| 7877 | NULL is returned if the specified record type is not supported by any | ||
| 7878 | available plugin. | ||
| 7879 | |||
| 7880 | @code{GNUNET_GNSRECORD_string_to_value} can be used to try to convert a | ||
| 7881 | human readable string to the respective (binary) representation of | ||
| 7882 | a GNS record value. | ||
| 7883 | |||
| 7884 | @node Type handling | ||
| 7885 | @subsubsection Type handling | ||
| 7886 | |||
| 7887 | @c %**end of header | ||
| 7888 | |||
| 7889 | @code{GNUNET_GNSRECORD_typename_to_number} can be used to obtain the | ||
| 7890 | numeric value associated with a given typename. For example, given the | ||
| 7891 | typename "A" (for DNS A reocrds), the function will return the number 1. | ||
| 7892 | A list of common DNS record types is | ||
| 7893 | @uref{http://en.wikipedia.org/wiki/List_of_DNS_record_types, here}. | ||
| 7894 | Note that not all DNS record types are supported by GNUnet GNSRECORD | ||
| 7895 | plugins at this time. | ||
| 7896 | |||
| 7897 | @code{GNUNET_GNSRECORD_number_to_typename} can be used to obtain the | ||
| 7898 | typename associated with a given numeric value. | ||
| 7899 | For example, given the type number 1, the function will return the | ||
| 7900 | typename "A". | ||
| 7901 | |||
| 7902 | @node GNS plugins | ||
| 7903 | @subsection GNS plugins | ||
| 7904 | |||
| 7905 | @c %**end of header | ||
| 7906 | |||
| 7907 | Adding a new GNS record type typically involves writing (or extending) a | ||
| 7908 | GNSRECORD plugin. The plugin needs to implement the | ||
| 7909 | @code{gnunet_gnsrecord_plugin.h} API which provides basic functions that | ||
| 7910 | are needed by GNSRECORD to convert typenames and values of the respective | ||
| 7911 | record type to strings (and back). | ||
| 7912 | These gnsrecord plugins are typically implemented within their respective | ||
| 7913 | subsystems. | ||
| 7914 | Examples for such plugins can be found in the GNSRECORD, GNS and | ||
| 7915 | CONVERSATION subsystems. | ||
| 7916 | |||
| 7917 | The @code{libgnunetgnsrecord} library is then used to locate, load and | ||
| 7918 | query the appropriate gnsrecord plugin. | ||
| 7919 | Which plugin is appropriate is determined by the record type (which is | ||
| 7920 | just a 32-bit integer). The @code{libgnunetgnsrecord} library loads all | ||
| 7921 | block plugins that are installed at the local peer and forwards the | ||
| 7922 | application request to the plugins. If the record type is not | ||
| 7923 | supported by the plugin, it should simply return an error code. | ||
| 7924 | |||
| 7925 | The central functions of the block APIs (plugin and main library) are the | ||
| 7926 | same four functions for converting between values and strings, and | ||
| 7927 | typenames and numbers documented in the previous subsection. | ||
| 7928 | |||
| 7929 | @node The GNS Client-Service Protocol | ||
| 7930 | @subsection The GNS Client-Service Protocol | ||
| 7931 | @c %**end of header | ||
| 7932 | |||
| 7933 | The GNS client-service protocol consists of two simple messages, the | ||
| 7934 | @code{LOOKUP} message and the @code{LOOKUP_RESULT}. Each @code{LOOKUP} | ||
| 7935 | message contains a unique 32-bit identifier, which will be included in the | ||
| 7936 | corresponding response. Thus, clients can send many lookup requests in | ||
| 7937 | parallel and receive responses out-of-order. | ||
| 7938 | A @code{LOOKUP} request also includes the public key of the GNS zone, | ||
| 7939 | the desired record type and fields specifying whether shortening is | ||
| 7940 | enabled or networking is disabled. Finally, the @code{LOOKUP} message | ||
| 7941 | includes the name to be resolved. | ||
| 7942 | |||
| 7943 | The response includes the number of records and the records themselves | ||
| 7944 | in the format created by @code{GNUNET_GNSRECORD_records_serialize}. | ||
| 7945 | They can thus be deserialized using | ||
| 7946 | @code{GNUNET_GNSRECORD_records_deserialize}. | ||
| 7947 | |||
| 7948 | @node Hijacking the DNS-Traffic using gnunet-service-dns | ||
| 7949 | @subsection Hijacking the DNS-Traffic using gnunet-service-dns | ||
| 7950 | |||
| 7951 | @c %**end of header | ||
| 7952 | |||
| 7953 | This section documents how the gnunet-service-dns (and the | ||
| 7954 | gnunet-helper-dns) intercepts DNS queries from the local system. | ||
| 7955 | This is merely one method for how we can obtain GNS queries. | ||
| 7956 | It is also possible to change @code{resolv.conf} to point to a machine | ||
| 7957 | running @code{gnunet-dns2gns} or to modify libc's name system switch | ||
| 7958 | (NSS) configuration to include a GNS resolution plugin. | ||
| 7959 | The method described in this chapter is more of a last-ditch catch-all | ||
| 7960 | approach. | ||
| 7961 | |||
| 7962 | @code{gnunet-service-dns} enables intercepting DNS traffic using policy | ||
| 7963 | based routing. | ||
| 7964 | We MARK every outgoing DNS-packet if it was not sent by our application. | ||
| 7965 | Using a second routing table in the Linux kernel these marked packets are | ||
| 7966 | then routed through our virtual network interface and can thus be | ||
| 7967 | captured unchanged. | ||
| 7968 | |||
| 7969 | Our application then reads the query and decides how to handle it. | ||
| 7970 | If the query can be addressed via GNS, it is passed to | ||
| 7971 | @code{gnunet-service-gns} and resolved internally using GNS. | ||
| 7972 | In the future, a reverse query for an address of the configured virtual | ||
| 7973 | network could be answered with records kept about previous forward | ||
| 7974 | queries. | ||
| 7975 | Queries that are not hijacked by some application using the DNS service | ||
| 7976 | will be sent to the original recipient. | ||
| 7977 | The answer to the query will always be sent back through the virtual | ||
| 7978 | interface with the original nameserver as source address. | ||
| 7979 | |||
| 7980 | |||
| 7981 | @menu | ||
| 7982 | * Network Setup Details:: | ||
| 7983 | @end menu | ||
| 7984 | |||
| 7985 | @node Network Setup Details | ||
| 7986 | @subsubsection Network Setup Details | ||
| 7987 | |||
| 7988 | @c %**end of header | ||
| 7989 | |||
| 7990 | The DNS interceptor adds the following rules to the Linux kernel: | ||
| 7991 | @example | ||
| 7992 | iptables -t mangle -I OUTPUT 1 -p udp --sport $LOCALPORT --dport 53 \ | ||
| 7993 | -j ACCEPT iptables -t mangle -I OUTPUT 2 -p udp --dport 53 -j MARK \ | ||
| 7994 | --set-mark 3 ip rule add fwmark 3 table2 ip route add default via \ | ||
| 7995 | $VIRTUALDNS table2 | ||
| 7996 | @end example | ||
| 7997 | |||
| 7998 | @c FIXME: Rewrite to reflect display which is no longer content by line | ||
| 7999 | @c FIXME: due to the < 74 characters limit. | ||
| 8000 | Line 1 makes sure that all packets coming from a port our application | ||
| 8001 | opened beforehand (@code{$LOCALPORT}) will be routed normally. | ||
| 8002 | Line 2 marks every other packet to a DNS-Server with mark 3 (chosen | ||
| 8003 | arbitrarily). The third line adds a routing policy based on this mark | ||
| 8004 | 3 via the routing table. | ||
| 8005 | |||
| 8006 | @node Serving DNS lookups via GNS on W32 | ||
| 8007 | @subsection Serving DNS lookups via GNS on W32 | ||
| 8008 | |||
| 8009 | @c %**end of header | ||
| 8010 | |||
| 8011 | This section documents how the libw32nsp (and | ||
| 8012 | gnunet-gns-helper-service-w32) do DNS resolutions of DNS queries on the | ||
| 8013 | local system. This only applies to GNUnet running on W32. | ||
| 8014 | |||
| 8015 | W32 has a concept of "Namespaces" and "Namespace providers". | ||
| 8016 | These are used to present various name systems to applications in a | ||
| 8017 | generic way. | ||
| 8018 | Namespaces include DNS, mDNS, NLA and others. For each namespace any | ||
| 8019 | number of providers could be registered, and they are queried in an order | ||
| 8020 | of priority (which is adjustable). | ||
| 8021 | |||
| 8022 | Applications can resolve names by using WSALookupService*() family of | ||
| 8023 | functions. | ||
| 8024 | |||
| 8025 | However, these are WSA-only facilities. Common BSD socket functions for | ||
| 8026 | namespace resolutions are gethostbyname and getaddrinfo (among others). | ||
| 8027 | These functions are implemented internally (by default - by mswsock, | ||
| 8028 | which also implements the default DNS provider) as wrappers around | ||
| 8029 | WSALookupService*() functions (see "Sample Code for a Service Provider" | ||
| 8030 | on MSDN). | ||
| 8031 | |||
| 8032 | On W32 GNUnet builds a libw32nsp - a namespace provider, which can then be | ||
| 8033 | installed into the system by using w32nsp-install (and uninstalled by | ||
| 8034 | w32nsp-uninstall), as described in "Installation Handbook". | ||
| 8035 | |||
| 8036 | libw32nsp is very simple and has almost no dependencies. As a response to | ||
| 8037 | NSPLookupServiceBegin(), it only checks that the provider GUID passed to | ||
| 8038 | it by the caller matches GNUnet DNS Provider GUID, | ||
| 8039 | then connects to | ||
| 8040 | gnunet-gns-helper-service-w32 at 127.0.0.1:5353 (hardcoded) and sends the | ||
| 8041 | name resolution request there, returning the connected socket to the | ||
| 8042 | caller. | ||
| 8043 | |||
| 8044 | When the caller invokes NSPLookupServiceNext(), libw32nsp reads a | ||
| 8045 | completely formed reply from that socket, unmarshalls it, then gives | ||
| 8046 | it back to the caller. | ||
| 8047 | |||
| 8048 | At the moment gnunet-gns-helper-service-w32 is implemented to ever give | ||
| 8049 | only one reply, and subsequent calls to NSPLookupServiceNext() will fail | ||
| 8050 | with WSA_NODATA (first call to NSPLookupServiceNext() might also fail if | ||
| 8051 | GNS failed to find the name, or there was an error connecting to it). | ||
| 8052 | |||
| 8053 | gnunet-gns-helper-service-w32 does most of the processing: | ||
| 8054 | |||
| 8055 | @itemize @bullet | ||
| 8056 | @item Maintains a connection to GNS. | ||
| 8057 | @item Reads GNS config and loads appropriate keys. | ||
| 8058 | @item Checks service GUID and decides on the type of record to look up, | ||
| 8059 | refusing to make a lookup outright when unsupported service GUID is | ||
| 8060 | passed. | ||
| 8061 | @item Launches the lookup | ||
| 8062 | @end itemize | ||
| 8063 | |||
| 8064 | When lookup result arrives, gnunet-gns-helper-service-w32 forms a complete | ||
| 8065 | reply (including filling a WSAQUERYSETW structure and, possibly, a binary | ||
| 8066 | blob with a hostent structure for gethostbyname() client), marshalls it, | ||
| 8067 | and sends it back to libw32nsp. If no records were found, it sends an | ||
| 8068 | empty header. | ||
| 8069 | |||
| 8070 | This works for most normal applications that use gethostbyname() or | ||
| 8071 | getaddrinfo() to resolve names, but fails to do anything with | ||
| 8072 | applications that use alternative means of resolving names (such as | ||
| 8073 | sending queries to a DNS server directly by themselves). | ||
| 8074 | This includes some of well known utilities, like "ping" and "nslookup". | ||
| 8075 | |||
| 8076 | @cindex GNS Namecache | ||
| 8077 | @node GNS Namecache | ||
| 8078 | @section GNS Namecache | ||
| 8079 | |||
| 8080 | @c %**end of header | ||
| 8081 | |||
| 8082 | The NAMECACHE subsystem is responsible for caching (encrypted) resolution | ||
| 8083 | results of the GNU Name System (GNS). GNS makes zone information available | ||
| 8084 | to other users via the DHT. However, as accessing the DHT for every | ||
| 8085 | lookup is expensive (and as the DHT's local cache is lost whenever the | ||
| 8086 | peer is restarted), GNS uses the NAMECACHE as a more persistent cache for | ||
| 8087 | DHT lookups. | ||
| 8088 | Thus, instead of always looking up every name in the DHT, GNS first | ||
| 8089 | checks if the result is already available locally in the NAMECACHE. | ||
| 8090 | Only if there is no result in the NAMECACHE, GNS queries the DHT. | ||
| 8091 | The NAMECACHE stores data in the same (encrypted) format as the DHT. | ||
| 8092 | It thus makes no sense to iterate over all items in the | ||
| 8093 | NAMECACHE --- the NAMECACHE does not have a way to provide the keys | ||
| 8094 | required to decrypt the entries. | ||
| 8095 | |||
| 8096 | Blocks in the NAMECACHE share the same expiration mechanism as blocks in | ||
| 8097 | the DHT --- the block expires wheneever any of the records in | ||
| 8098 | the (encrypted) block expires. | ||
| 8099 | The expiration time of the block is the only information stored in | ||
| 8100 | plaintext. The NAMECACHE service internally performs all of the required | ||
| 8101 | work to expire blocks, clients do not have to worry about this. | ||
| 8102 | Also, given that NAMECACHE stores only GNS blocks that local users | ||
| 8103 | requested, there is no configuration option to limit the size of the | ||
| 8104 | NAMECACHE. It is assumed to be always small enough (a few MB) to fit on | ||
| 8105 | the drive. | ||
| 8106 | |||
| 8107 | The NAMECACHE supports the use of different database backends via a | ||
| 8108 | plugin API. | ||
| 8109 | |||
| 8110 | @menu | ||
| 8111 | * libgnunetnamecache:: | ||
| 8112 | * The NAMECACHE Client-Service Protocol:: | ||
| 8113 | * The NAMECACHE Plugin API:: | ||
| 8114 | @end menu | ||
| 8115 | |||
| 8116 | @node libgnunetnamecache | ||
| 8117 | @subsection libgnunetnamecache | ||
| 8118 | |||
| 8119 | @c %**end of header | ||
| 8120 | |||
| 8121 | The NAMECACHE API consists of five simple functions. First, there is | ||
| 8122 | @code{GNUNET_NAMECACHE_connect} to connect to the NAMECACHE service. | ||
| 8123 | This returns the handle required for all other operations on the | ||
| 8124 | NAMECACHE. Using @code{GNUNET_NAMECACHE_block_cache} clients can insert a | ||
| 8125 | block into the cache. | ||
| 8126 | @code{GNUNET_NAMECACHE_lookup_block} can be used to lookup blocks that | ||
| 8127 | were stored in the NAMECACHE. Both operations can be canceled using | ||
| 8128 | @code{GNUNET_NAMECACHE_cancel}. Note that canceling a | ||
| 8129 | @code{GNUNET_NAMECACHE_block_cache} operation can result in the block | ||
| 8130 | being stored in the NAMECACHE --- or not. Cancellation primarily ensures | ||
| 8131 | that the continuation function with the result of the operation will no | ||
| 8132 | longer be invoked. | ||
| 8133 | Finally, @code{GNUNET_NAMECACHE_disconnect} closes the connection to the | ||
| 8134 | NAMECACHE. | ||
| 8135 | |||
| 8136 | The maximum size of a block that can be stored in the NAMECACHE is | ||
| 8137 | @code{GNUNET_NAMECACHE_MAX_VALUE_SIZE}, which is defined to be 63 kB. | ||
| 8138 | |||
| 8139 | @node The NAMECACHE Client-Service Protocol | ||
| 8140 | @subsection The NAMECACHE Client-Service Protocol | ||
| 8141 | |||
| 8142 | @c %**end of header | ||
| 8143 | |||
| 8144 | All messages in the NAMECACHE IPC protocol start with the | ||
| 8145 | @code{struct GNUNET_NAMECACHE_Header} which adds a request | ||
| 8146 | ID (32-bit integer) to the standard message header. | ||
| 8147 | The request ID is used to match requests with the | ||
| 8148 | respective responses from the NAMECACHE, as they are allowed to happen | ||
| 8149 | out-of-order. | ||
| 8150 | |||
| 8151 | |||
| 8152 | @menu | ||
| 8153 | * Lookup:: | ||
| 8154 | * Store:: | ||
| 8155 | @end menu | ||
| 8156 | |||
| 8157 | @node Lookup | ||
| 8158 | @subsubsection Lookup | ||
| 8159 | |||
| 8160 | @c %**end of header | ||
| 8161 | |||
| 8162 | The @code{struct LookupBlockMessage} is used to lookup a block stored in | ||
| 8163 | the cache. | ||
| 8164 | It contains the query hash. The NAMECACHE always responds with a | ||
| 8165 | @code{struct LookupBlockResponseMessage}. If the NAMECACHE has no | ||
| 8166 | response, it sets the expiration time in the response to zero. | ||
| 8167 | Otherwise, the response is expected to contain the expiration time, the | ||
| 8168 | ECDSA signature, the derived key and the (variable-size) encrypted data | ||
| 8169 | of the block. | ||
| 8170 | |||
| 8171 | @node Store | ||
| 8172 | @subsubsection Store | ||
| 8173 | |||
| 8174 | @c %**end of header | ||
| 8175 | |||
| 8176 | The @code{struct BlockCacheMessage} is used to cache a block in the | ||
| 8177 | NAMECACHE. | ||
| 8178 | It has the same structure as the @code{struct LookupBlockResponseMessage}. | ||
| 8179 | The service responds with a @code{struct BlockCacheResponseMessage} which | ||
| 8180 | contains the result of the operation (success or failure). | ||
| 8181 | In the future, we might want to make it possible to provide an error | ||
| 8182 | message as well. | ||
| 8183 | |||
| 8184 | @node The NAMECACHE Plugin API | ||
| 8185 | @subsection The NAMECACHE Plugin API | ||
| 8186 | @c %**end of header | ||
| 8187 | |||
| 8188 | The NAMECACHE plugin API consists of two functions, @code{cache_block} to | ||
| 8189 | store a block in the database, and @code{lookup_block} to lookup a block | ||
| 8190 | in the database. | ||
| 8191 | |||
| 8192 | |||
| 8193 | @menu | ||
| 8194 | * Lookup2:: | ||
| 8195 | * Store2:: | ||
| 8196 | @end menu | ||
| 8197 | |||
| 8198 | @node Lookup2 | ||
| 8199 | @subsubsection Lookup2 | ||
| 8200 | |||
| 8201 | @c %**end of header | ||
| 8202 | |||
| 8203 | The @code{lookup_block} function is expected to return at most one block | ||
| 8204 | to the iterator, and return @code{GNUNET_NO} if there were no non-expired | ||
| 8205 | results. | ||
| 8206 | If there are multiple non-expired results in the cache, the lookup is | ||
| 8207 | supposed to return the result with the largest expiration time. | ||
| 8208 | |||
| 8209 | @node Store2 | ||
| 8210 | @subsubsection Store2 | ||
| 8211 | |||
| 8212 | @c %**end of header | ||
| 8213 | |||
| 8214 | The @code{cache_block} function is expected to try to store the block in | ||
| 8215 | the database, and return @code{GNUNET_SYSERR} if this was not possible | ||
| 8216 | for any reason. | ||
| 8217 | Furthermore, @code{cache_block} is expected to implicitly perform cache | ||
| 8218 | maintenance and purge blocks from the cache that have expired. Note that | ||
| 8219 | @code{cache_block} might encounter the case where the database already has | ||
| 8220 | another block stored under the same key. In this case, the plugin must | ||
| 8221 | ensure that the block with the larger expiration time is preserved. | ||
| 8222 | Obviously, this can done either by simply adding new blocks and selecting | ||
| 8223 | for the most recent expiration time during lookup, or by checking which | ||
| 8224 | block is more recent during the store operation. | ||
| 8225 | |||
| 8226 | @cindex REVOCATION Subsystem | ||
| 8227 | @node REVOCATION Subsystem | ||
| 8228 | @section REVOCATION Subsystem | ||
| 8229 | @c %**end of header | ||
| 8230 | |||
| 8231 | The REVOCATION subsystem is responsible for key revocation of Egos. | ||
| 8232 | If a user learns that theis private key has been compromised or has lost | ||
| 8233 | it, they can use the REVOCATION system to inform all of the other users | ||
| 8234 | that their private key is no longer valid. | ||
| 8235 | The subsystem thus includes ways to query for the validity of keys and to | ||
| 8236 | propagate revocation messages. | ||
| 8237 | |||
| 8238 | @menu | ||
| 8239 | * Dissemination:: | ||
| 8240 | * Revocation Message Design Requirements:: | ||
| 8241 | * libgnunetrevocation:: | ||
| 8242 | * The REVOCATION Client-Service Protocol:: | ||
| 8243 | * The REVOCATION Peer-to-Peer Protocol:: | ||
| 8244 | @end menu | ||
| 8245 | |||
| 8246 | @node Dissemination | ||
| 8247 | @subsection Dissemination | ||
| 8248 | |||
| 8249 | @c %**end of header | ||
| 8250 | |||
| 8251 | When a revocation is performed, the revocation is first of all | ||
| 8252 | disseminated by flooding the overlay network. | ||
| 8253 | The goal is to reach every peer, so that when a peer needs to check if a | ||
| 8254 | key has been revoked, this will be purely a local operation where the | ||
| 8255 | peer looks at its local revocation list. Flooding the network is also the | ||
| 8256 | most robust form of key revocation --- an adversary would have to control | ||
| 8257 | a separator of the overlay graph to restrict the propagation of the | ||
| 8258 | revocation message. Flooding is also very easy to implement --- peers that | ||
| 8259 | receive a revocation message for a key that they have never seen before | ||
| 8260 | simply pass the message to all of their neighbours. | ||
| 8261 | |||
| 8262 | Flooding can only distribute the revocation message to peers that are | ||
| 8263 | online. | ||
| 8264 | In order to notify peers that join the network later, the revocation | ||
| 8265 | service performs efficient set reconciliation over the sets of known | ||
| 8266 | revocation messages whenever two peers (that both support REVOCATION | ||
| 8267 | dissemination) connect. | ||
| 8268 | The SET service is used to perform this operation efficiently. | ||
| 8269 | |||
| 8270 | @node Revocation Message Design Requirements | ||
| 8271 | @subsection Revocation Message Design Requirements | ||
| 8272 | |||
| 8273 | @c %**end of header | ||
| 8274 | |||
| 8275 | However, flooding is also quite costly, creating O(|E|) messages on a | ||
| 8276 | network with |E| edges. | ||
| 8277 | Thus, revocation messages are required to contain a proof-of-work, the | ||
| 8278 | result of an expensive computation (which, however, is cheap to verify). | ||
| 8279 | Only peers that have expended the CPU time necessary to provide | ||
| 8280 | this proof will be able to flood the network with the revocation message. | ||
| 8281 | This ensures that an attacker cannot simply flood the network with | ||
| 8282 | millions of revocation messages. The proof-of-work required by GNUnet is | ||
| 8283 | set to take days on a typical PC to compute; if the ability to quickly | ||
| 8284 | revoke a key is needed, users have the option to pre-compute revocation | ||
| 8285 | messages to store off-line and use instantly after their key has expired. | ||
| 8286 | |||
| 8287 | Revocation messages must also be signed by the private key that is being | ||
| 8288 | revoked. Thus, they can only be created while the private key is in the | ||
| 8289 | possession of the respective user. This is another reason to create a | ||
| 8290 | revocation message ahead of time and store it in a secure location. | ||
| 8291 | |||
| 8292 | @node libgnunetrevocation | ||
| 8293 | @subsection libgnunetrevocation | ||
| 8294 | |||
| 8295 | @c %**end of header | ||
| 8296 | |||
| 8297 | The REVOCATION API consists of two parts, to query and to issue | ||
| 8298 | revocations. | ||
| 8299 | |||
| 8300 | |||
| 8301 | @menu | ||
| 8302 | * Querying for revoked keys:: | ||
| 8303 | * Preparing revocations:: | ||
| 8304 | * Issuing revocations:: | ||
| 8305 | @end menu | ||
| 8306 | |||
| 8307 | @node Querying for revoked keys | ||
| 8308 | @subsubsection Querying for revoked keys | ||
| 8309 | |||
| 8310 | @c %**end of header | ||
| 8311 | |||
| 8312 | @code{GNUNET_REVOCATION_query} is used to check if a given ECDSA public | ||
| 8313 | key has been revoked. | ||
| 8314 | The given callback will be invoked with the result of the check. | ||
| 8315 | The query can be canceled using @code{GNUNET_REVOCATION_query_cancel} on | ||
| 8316 | the return value. | ||
| 8317 | |||
| 8318 | @node Preparing revocations | ||
| 8319 | @subsubsection Preparing revocations | ||
| 8320 | |||
| 8321 | @c %**end of header | ||
| 8322 | |||
| 8323 | It is often desirable to create a revocation record ahead-of-time and | ||
| 8324 | store it in an off-line location to be used later in an emergency. | ||
| 8325 | This is particularly true for GNUnet revocations, where performing the | ||
| 8326 | revocation operation itself is computationally expensive and thus is | ||
| 8327 | likely to take some time. | ||
| 8328 | Thus, if users want the ability to perform revocations quickly in an | ||
| 8329 | emergency, they must pre-compute the revocation message. | ||
| 8330 | The revocation API enables this with two functions that are used to | ||
| 8331 | compute the revocation message, but not trigger the actual revocation | ||
| 8332 | operation. | ||
| 8333 | |||
| 8334 | @code{GNUNET_REVOCATION_check_pow} should be used to calculate the | ||
| 8335 | proof-of-work required in the revocation message. This function takes the | ||
| 8336 | public key, the required number of bits for the proof of work (which in | ||
| 8337 | GNUnet is a network-wide constant) and finally a proof-of-work number as | ||
| 8338 | arguments. | ||
| 8339 | The function then checks if the given proof-of-work number is a valid | ||
| 8340 | proof of work for the given public key. Clients preparing a revocation | ||
| 8341 | are expected to call this function repeatedly (typically with a | ||
| 8342 | monotonically increasing sequence of numbers of the proof-of-work number) | ||
| 8343 | until a given number satisfies the check. | ||
| 8344 | That number should then be saved for later use in the revocation | ||
| 8345 | operation. | ||
| 8346 | |||
| 8347 | @code{GNUNET_REVOCATION_sign_revocation} is used to generate the | ||
| 8348 | signature that is required in a revocation message. | ||
| 8349 | It takes the private key that (possibly in the future) is to be revoked | ||
| 8350 | and returns the signature. | ||
| 8351 | The signature can again be saved to disk for later use, which will then | ||
| 8352 | allow performing a revocation even without access to the private key. | ||
| 8353 | |||
| 8354 | @node Issuing revocations | ||
| 8355 | @subsubsection Issuing revocations | ||
| 8356 | |||
| 8357 | |||
| 8358 | Given a ECDSA public key, the signature from @code{GNUNET_REVOCATION_sign} | ||
| 8359 | and the proof-of-work, | ||
| 8360 | @code{GNUNET_REVOCATION_revoke} can be used to perform the | ||
| 8361 | actual revocation. The given callback is called upon completion of the | ||
| 8362 | operation. @code{GNUNET_REVOCATION_revoke_cancel} can be used to stop the | ||
| 8363 | library from calling the continuation; however, in that case it is | ||
| 8364 | undefined whether or not the revocation operation will be executed. | ||
| 8365 | |||
| 8366 | @node The REVOCATION Client-Service Protocol | ||
| 8367 | @subsection The REVOCATION Client-Service Protocol | ||
| 8368 | |||
| 8369 | |||
| 8370 | The REVOCATION protocol consists of four simple messages. | ||
| 8371 | |||
| 8372 | A @code{QueryMessage} containing a public ECDSA key is used to check if a | ||
| 8373 | particular key has been revoked. The service responds with a | ||
| 8374 | @code{QueryResponseMessage} which simply contains a bit that says if the | ||
| 8375 | given public key is still valid, or if it has been revoked. | ||
| 8376 | |||
| 8377 | The second possible interaction is for a client to revoke a key by | ||
| 8378 | passing a @code{RevokeMessage} to the service. The @code{RevokeMessage} | ||
| 8379 | contains the ECDSA public key to be revoked, a signature by the | ||
| 8380 | corresponding private key and the proof-of-work, The service responds | ||
| 8381 | with a @code{RevocationResponseMessage} which can be used to indicate | ||
| 8382 | that the @code{RevokeMessage} was invalid (i.e. proof of work incorrect), | ||
| 8383 | or otherwise indicates that the revocation has been processed | ||
| 8384 | successfully. | ||
| 8385 | |||
| 8386 | @node The REVOCATION Peer-to-Peer Protocol | ||
| 8387 | @subsection The REVOCATION Peer-to-Peer Protocol | ||
| 8388 | |||
| 8389 | @c %**end of header | ||
| 8390 | |||
| 8391 | Revocation uses two disjoint ways to spread revocation information among | ||
| 8392 | peers. | ||
| 8393 | First of all, P2P gossip exchanged via CORE-level neighbours is used to | ||
| 8394 | quickly spread revocations to all connected peers. | ||
| 8395 | Second, whenever two peers (that both support revocations) connect, | ||
| 8396 | the SET service is used to compute the union of the respective revocation | ||
| 8397 | sets. | ||
| 8398 | |||
| 8399 | In both cases, the exchanged messages are @code{RevokeMessage}s which | ||
| 8400 | contain the public key that is being revoked, a matching ECDSA signature, | ||
| 8401 | and a proof-of-work. | ||
| 8402 | Whenever a peer learns about a new revocation this way, it first | ||
| 8403 | validates the signature and the proof-of-work, then stores it to disk | ||
| 8404 | (typically to a file $GNUNET_DATA_HOME/revocation.dat) and finally | ||
| 8405 | spreads the information to all directly connected neighbours. | ||
| 8406 | |||
| 8407 | For computing the union using the SET service, the peer with the smaller | ||
| 8408 | hashed peer identity will connect (as a "client" in the two-party set | ||
| 8409 | protocol) to the other peer after one second (to reduce traffic spikes | ||
| 8410 | on connect) and initiate the computation of the set union. | ||
| 8411 | All revocation services use a common hash to identify the SET operation | ||
| 8412 | over revocation sets. | ||
| 8413 | |||
| 8414 | The current implementation accepts revocation set union operations from | ||
| 8415 | all peers at any time; however, well-behaved peers should only initiate | ||
| 8416 | this operation once after establishing a connection to a peer with a | ||
| 8417 | larger hashed peer identity. | ||
| 8418 | |||
| 8419 | @cindex FS | ||
| 8420 | @cindex FS Subsystem | ||
| 8421 | @node File-sharing (FS) Subsystem | ||
| 8422 | @section File-sharing (FS) Subsystem | ||
| 8423 | |||
| 8424 | @c %**end of header | ||
| 8425 | |||
| 8426 | This chapter describes the details of how the file-sharing service works. | ||
| 8427 | As with all services, it is split into an API (libgnunetfs), the service | ||
| 8428 | process (gnunet-service-fs) and user interface(s). | ||
| 8429 | The file-sharing service uses the datastore service to store blocks and | ||
| 8430 | the DHT (and indirectly datacache) for lookups for non-anonymous | ||
| 8431 | file-sharing. | ||
| 8432 | Furthermore, the file-sharing service uses the block library (and the | ||
| 8433 | block fs plugin) for validation of DHT operations. | ||
| 8434 | |||
| 8435 | In contrast to many other services, libgnunetfs is rather complex since | ||
| 8436 | the client library includes a large number of high-level abstractions; | ||
| 8437 | this is necessary since the Fs service itself largely only operates on | ||
| 8438 | the block level. | ||
| 8439 | The FS library is responsible for providing a file-based abstraction to | ||
| 8440 | applications, including directories, meta data, keyword search, | ||
| 8441 | verification, and so on. | ||
| 8442 | |||
| 8443 | The method used by GNUnet to break large files into blocks and to use | ||
| 8444 | keyword search is called the | ||
| 8445 | "Encoding for Censorship Resistant Sharing" (ECRS). | ||
| 8446 | ECRS is largely implemented in the fs library; block validation is also | ||
| 8447 | reflected in the block FS plugin and the FS service. | ||
| 8448 | ECRS on-demand encoding is implemented in the FS service. | ||
| 8449 | |||
| 8450 | NOTE: The documentation in this chapter is quite incomplete. | ||
| 8451 | |||
| 8452 | @menu | ||
| 8453 | * Encoding for Censorship-Resistant Sharing (ECRS):: | ||
| 8454 | * File-sharing persistence directory structure:: | ||
| 8455 | @end menu | ||
| 8456 | |||
| 8457 | @cindex ECRS | ||
| 8458 | @cindex Encoding for Censorship-Resistant Sharing | ||
| 8459 | @node Encoding for Censorship-Resistant Sharing (ECRS) | ||
| 8460 | @subsection Encoding for Censorship-Resistant Sharing (ECRS) | ||
| 8461 | |||
| 8462 | @c %**end of header | ||
| 8463 | |||
| 8464 | When GNUnet shares files, it uses a content encoding that is called ECRS, | ||
| 8465 | the Encoding for Censorship-Resistant Sharing. | ||
| 8466 | Most of ECRS is described in the (so far unpublished) research paper | ||
| 8467 | attached to this page. ECRS obsoletes the previous ESED and ESED II | ||
| 8468 | encodings which were used in GNUnet before version 0.7.0. | ||
| 8469 | The rest of this page assumes that the reader is familiar with the | ||
| 8470 | attached paper. What follows is a description of some minor extensions | ||
| 8471 | that GNUnet makes over what is described in the paper. | ||
| 8472 | The reason why these extensions are not in the paper is that we felt | ||
| 8473 | that they were obvious or trivial extensions to the original scheme and | ||
| 8474 | thus did not warrant space in the research report. | ||
| 8475 | |||
| 8476 | @menu | ||
| 8477 | * Namespace Advertisements:: | ||
| 8478 | * KSBlocks:: | ||
| 8479 | @end menu | ||
| 8480 | |||
| 8481 | @node Namespace Advertisements | ||
| 8482 | @subsubsection Namespace Advertisements | ||
| 8483 | |||
| 8484 | @c %**end of header | ||
| 8485 | @c %**FIXME: all zeroses -> ? | ||
| 8486 | |||
| 8487 | An @code{SBlock} with identifier all zeros is a signed | ||
| 8488 | advertisement for a namespace. This special @code{SBlock} contains | ||
| 8489 | metadata describing the content of the namespace. | ||
| 8490 | Instead of the name of the identifier for a potential update, it contains | ||
| 8491 | the identifier for the root of the namespace. | ||
| 8492 | The URI should always be empty. The @code{SBlock} is signed with the | ||
| 8493 | content provider's RSA private key (just like any other SBlock). Peers | ||
| 8494 | can search for @code{SBlock}s in order to find out more about a namespace. | ||
| 8495 | |||
| 8496 | @node KSBlocks | ||
| 8497 | @subsubsection KSBlocks | ||
| 8498 | |||
| 8499 | @c %**end of header | ||
| 8500 | |||
| 8501 | GNUnet implements @code{KSBlocks} which are @code{KBlocks} that, instead | ||
| 8502 | of encrypting a CHK and metadata, encrypt an @code{SBlock} instead. | ||
| 8503 | In other words, @code{KSBlocks} enable GNUnet to find @code{SBlocks} | ||
| 8504 | using the global keyword search. | ||
| 8505 | Usually the encrypted @code{SBlock} is a namespace advertisement. | ||
| 8506 | The rationale behind @code{KSBlock}s and @code{SBlock}s is to enable | ||
| 8507 | peers to discover namespaces via keyword searches, and, to associate | ||
| 8508 | useful information with namespaces. When GNUnet finds @code{KSBlocks} | ||
| 8509 | during a normal keyword search, it adds the information to an internal | ||
| 8510 | list of discovered namespaces. Users looking for interesting namespaces | ||
| 8511 | can then inspect this list, reducing the need for out-of-band discovery | ||
| 8512 | of namespaces. | ||
| 8513 | Naturally, namespaces (or more specifically, namespace advertisements) can | ||
| 8514 | also be referenced from directories, but @code{KSBlock}s should make it | ||
| 8515 | easier to advertise namespaces for the owner of the pseudonym since they | ||
| 8516 | eliminate the need to first create a directory. | ||
| 8517 | |||
| 8518 | Collections are also advertised using @code{KSBlock}s. | ||
| 8519 | |||
| 8520 | @c https://gnunet.org/sites/default/files/ecrs.pdf | ||
| 8521 | |||
| 8522 | @node File-sharing persistence directory structure | ||
| 8523 | @subsection File-sharing persistence directory structure | ||
| 8524 | |||
| 8525 | @c %**end of header | ||
| 8526 | |||
| 8527 | This section documents how the file-sharing library implements | ||
| 8528 | persistence of file-sharing operations and specifically the resulting | ||
| 8529 | directory structure. | ||
| 8530 | This code is only active if the @code{GNUNET_FS_FLAGS_PERSISTENCE} flag | ||
| 8531 | was set when calling @code{GNUNET_FS_start}. | ||
| 8532 | In this case, the file-sharing library will try hard to ensure that all | ||
| 8533 | major operations (searching, downloading, publishing, unindexing) are | ||
| 8534 | persistent, that is, can live longer than the process itself. | ||
| 8535 | More specifically, an operation is supposed to live until it is | ||
| 8536 | explicitly stopped. | ||
| 8537 | |||
| 8538 | If @code{GNUNET_FS_stop} is called before an operation has been stopped, a | ||
| 8539 | @code{SUSPEND} event is generated and then when the process calls | ||
| 8540 | @code{GNUNET_FS_start} next time, a @code{RESUME} event is generated. | ||
| 8541 | Additionally, even if an application crashes (segfault, SIGKILL, system | ||
| 8542 | crash) and hence @code{GNUNET_FS_stop} is never called and no | ||
| 8543 | @code{SUSPEND} events are generated, operations are still resumed (with | ||
| 8544 | @code{RESUME} events). | ||
| 8545 | This is implemented by constantly writing the current state of the | ||
| 8546 | file-sharing operations to disk. | ||
| 8547 | Specifically, the current state is always written to disk whenever | ||
| 8548 | anything significant changes (the exception are block-wise progress in | ||
| 8549 | publishing and unindexing, since those operations would be slowed down | ||
| 8550 | significantly and can be resumed cheaply even without detailed | ||
| 8551 | accounting). | ||
| 8552 | Note that if the process crashes (or is killed) during a serialization | ||
| 8553 | operation, FS does not guarantee that this specific operation is | ||
| 8554 | recoverable (no strict transactional semantics, again for performance | ||
| 8555 | reasons). However, all other unrelated operations should resume nicely. | ||
| 8556 | |||
| 8557 | Since we need to serialize the state continuously and want to recover as | ||
| 8558 | much as possible even after crashing during a serialization operation, | ||
| 8559 | we do not use one large file for serialization. | ||
| 8560 | Instead, several directories are used for the various operations. | ||
| 8561 | When @code{GNUNET_FS_start} executes, the master directories are scanned | ||
| 8562 | for files describing operations to resume. | ||
| 8563 | Sometimes, these operations can refer to related operations in child | ||
| 8564 | directories which may also be resumed at this point. | ||
| 8565 | Note that corrupted files are cleaned up automatically. | ||
| 8566 | However, dangling files in child directories (those that are not | ||
| 8567 | referenced by files from the master directories) are not automatically | ||
| 8568 | removed. | ||
| 8569 | |||
| 8570 | Persistence data is kept in a directory that begins with the "STATE_DIR" | ||
| 8571 | prefix from the configuration file | ||
| 8572 | (by default, "$SERVICEHOME/persistence/") followed by the name of the | ||
| 8573 | client as given to @code{GNUNET_FS_start} (for example, "gnunet-gtk") | ||
| 8574 | followed by the actual name of the master or child directory. | ||
| 8575 | |||
| 8576 | The names for the master directories follow the names of the operations: | ||
| 8577 | |||
| 8578 | @itemize @bullet | ||
| 8579 | @item "search" | ||
| 8580 | @item "download" | ||
| 8581 | @item "publish" | ||
| 8582 | @item "unindex" | ||
| 8583 | @end itemize | ||
| 8584 | |||
| 8585 | Each of the master directories contains names (chosen at random) for each | ||
| 8586 | active top-level (master) operation. | ||
| 8587 | Note that a download that is associated with a search result is not a | ||
| 8588 | top-level operation. | ||
| 8589 | |||
| 8590 | In contrast to the master directories, the child directories are only | ||
| 8591 | consulted when another operation refers to them. | ||
| 8592 | For each search, a subdirectory (named after the master search | ||
| 8593 | synchronization file) contains the search results. | ||
| 8594 | Search results can have an associated download, which is then stored in | ||
| 8595 | the general "download-child" directory. | ||
| 8596 | Downloads can be recursive, in which case children are stored in | ||
| 8597 | subdirectories mirroring the structure of the recursive download | ||
| 8598 | (either starting in the master "download" directory or in the | ||
| 8599 | "download-child" directory depending on how the download was initiated). | ||
| 8600 | For publishing operations, the "publish-file" directory contains | ||
| 8601 | information about the individual files and directories that are part of | ||
| 8602 | the publication. | ||
| 8603 | However, this directory structure is flat and does not mirror the | ||
| 8604 | structure of the publishing operation. | ||
| 8605 | Note that unindex operations cannot have associated child operations. | ||
| 8606 | |||
| 8607 | @cindex REGEX subsystem | ||
| 8608 | @node REGEX Subsystem | ||
| 8609 | @section REGEX Subsystem | ||
| 8610 | |||
| 8611 | @c %**end of header | ||
| 8612 | |||
| 8613 | Using the REGEX subsystem, you can discover peers that offer a particular | ||
| 8614 | service using regular expressions. | ||
| 8615 | The peers that offer a service specify it using a regular expressions. | ||
| 8616 | Peers that want to patronize a service search using a string. | ||
| 8617 | The REGEX subsystem will then use the DHT to return a set of matching | ||
| 8618 | offerers to the patrons. | ||
| 8619 | |||
| 8620 | For the technical details, we have Max's defense talk and Max's Master's | ||
| 8621 | thesis. | ||
| 8622 | |||
| 8623 | @c An additional publication is under preparation and available to | ||
| 8624 | @c team members (in Git). | ||
| 8625 | @c FIXME: Where is the file? Point to it. Assuming that it's szengel2012ms | ||
| 8626 | |||
| 8627 | @menu | ||
| 8628 | * How to run the regex profiler:: | ||
| 8629 | @end menu | ||
| 8630 | |||
| 8631 | @node How to run the regex profiler | ||
| 8632 | @subsection How to run the regex profiler | ||
| 8633 | |||
| 8634 | @c %**end of header | ||
| 8635 | |||
| 8636 | The gnunet-regex-profiler can be used to profile the usage of mesh/regex | ||
| 8637 | for a given set of regular expressions and strings. | ||
| 8638 | Mesh/regex allows you to announce your peer ID under a certain regex and | ||
| 8639 | search for peers matching a particular regex using a string. | ||
| 8640 | See @uref{https://gnunet.org/szengel2012ms, szengel2012ms} for a full | ||
| 8641 | introduction. | ||
| 8642 | |||
| 8643 | First of all, the regex profiler uses GNUnet testbed, thus all the | ||
| 8644 | implications for testbed also apply to the regex profiler | ||
| 8645 | (for example you need password-less ssh login to the machines listed in | ||
| 8646 | your hosts file). | ||
| 8647 | |||
| 8648 | @strong{Configuration} | ||
| 8649 | |||
| 8650 | Moreover, an appropriate configuration file is needed. | ||
| 8651 | Generally you can refer to the | ||
| 8652 | @file{contrib/regex_profiler_infiniband.conf} file in the sourcecode | ||
| 8653 | of GNUnet for an example configuration. | ||
| 8654 | In the following paragraph the important details are highlighted. | ||
| 8655 | |||
| 8656 | Announcing of the regular expressions is done by the | ||
| 8657 | gnunet-daemon-regexprofiler, therefore you have to make sure it is | ||
| 8658 | started, by adding it to the START_ON_DEMAND set of ARM: | ||
| 8659 | |||
| 8660 | @example | ||
| 8661 | [regexprofiler] | ||
| 8662 | START_ON_DEMAND = YES | ||
| 8663 | @end example | ||
| 8664 | |||
| 8665 | @noindent | ||
| 8666 | Furthermore you have to specify the location of the binary: | ||
| 8667 | |||
| 8668 | @example | ||
| 8669 | [regexprofiler] | ||
| 8670 | # Location of the gnunet-daemon-regexprofiler binary. | ||
| 8671 | BINARY = /home/szengel/gnunet/src/mesh/.libs/gnunet-daemon-regexprofiler | ||
| 8672 | # Regex prefix that will be applied to all regular expressions and | ||
| 8673 | # search string. | ||
| 8674 | REGEX_PREFIX = "GNVPN-0001-PAD" | ||
| 8675 | @end example | ||
| 8676 | |||
| 8677 | @noindent | ||
| 8678 | When running the profiler with a large scale deployment, you probably | ||
| 8679 | want to reduce the workload of each peer. | ||
| 8680 | Use the following options to do this. | ||
| 8681 | |||
| 8682 | @example | ||
| 8683 | [dht] | ||
| 8684 | # Force network size estimation | ||
| 8685 | FORCE_NSE = 1 | ||
| 8686 | |||
| 8687 | [dhtcache] | ||
| 8688 | DATABASE = heap | ||
| 8689 | # Disable RC-file for Bloom filter? (for benchmarking with limited IO | ||
| 8690 | # availability) | ||
| 8691 | DISABLE_BF_RC = YES | ||
| 8692 | # Disable Bloom filter entirely | ||
| 8693 | DISABLE_BF = YES | ||
| 8694 | |||
| 8695 | [nse] | ||
| 8696 | # Minimize proof-of-work CPU consumption by NSE | ||
| 8697 | WORKBITS = 1 | ||
| 8698 | @end example | ||
| 8699 | |||
| 8700 | @noindent | ||
| 8701 | @strong{Options} | ||
| 8702 | |||
| 8703 | To finally run the profiler some options and the input data need to be | ||
| 8704 | specified on the command line. | ||
| 8705 | |||
| 8706 | @example | ||
| 8707 | gnunet-regex-profiler -c config-file -d log-file -n num-links \ | ||
| 8708 | -p path-compression-length -s search-delay -t matching-timeout \ | ||
| 8709 | -a num-search-strings hosts-file policy-dir search-strings-file | ||
| 8710 | @end example | ||
| 8711 | |||
| 8712 | @noindent | ||
| 8713 | Where... | ||
| 8714 | |||
| 8715 | @itemize @bullet | ||
| 8716 | @item ... @code{config-file} means the configuration file created earlier. | ||
| 8717 | @item ... @code{log-file} is the file where to write statistics output. | ||
| 8718 | @item ... @code{num-links} indicates the number of random links between | ||
| 8719 | started peers. | ||
| 8720 | @item ... @code{path-compression-length} is the maximum path compression | ||
| 8721 | length in the DFA. | ||
| 8722 | @item ... @code{search-delay} time to wait between peers finished linking | ||
| 8723 | and starting to match strings. | ||
| 8724 | @item ... @code{matching-timeout} timeout after which to cancel the | ||
| 8725 | searching. | ||
| 8726 | @item ... @code{num-search-strings} number of strings in the | ||
| 8727 | search-strings-file. | ||
| 8728 | @item ... the @code{hosts-file} should contain a list of hosts for the | ||
| 8729 | testbed, one per line in the following format: | ||
| 8730 | |||
| 8731 | @itemize @bullet | ||
| 8732 | @item @code{user@@host_ip:port} | ||
| 8733 | @end itemize | ||
| 8734 | @item ... the @code{policy-dir} is a folder containing text files | ||
| 8735 | containing one or more regular expressions. A peer is started for each | ||
| 8736 | file in that folder and the regular expressions in the corresponding file | ||
| 8737 | are announced by this peer. | ||
| 8738 | @item ... the @code{search-strings-file} is a text file containing search | ||
| 8739 | strings, one in each line. | ||
| 8740 | @end itemize | ||
| 8741 | |||
| 8742 | @noindent | ||
| 8743 | You can create regular expressions and search strings for every AS in the | ||
| 8744 | Internet using the attached scripts. You need one of the | ||
| 8745 | @uref{http://data.caida.org/datasets/routing/routeviews-prefix2as/, CAIDA routeviews prefix2as} | ||
| 8746 | data files for this. Run | ||
| 8747 | |||
| 8748 | @example | ||
| 8749 | create_regex.py <filename> <output path> | ||
| 8750 | @end example | ||
| 8751 | |||
| 8752 | @noindent | ||
| 8753 | to create the regular expressions and | ||
| 8754 | |||
| 8755 | @example | ||
| 8756 | create_strings.py <input path> <outfile> | ||
| 8757 | @end example | ||
| 8758 | |||
| 8759 | @noindent | ||
| 8760 | to create a search strings file from the previously created | ||
| 8761 | regular expressions. | ||
| 8762 | |||
| 8763 | @cindex REST subsystem | ||
| 8764 | @node REST Subsystem | ||
| 8765 | @section REST Subsystem | ||
| 8766 | |||
| 8767 | @c %**end of header | ||
| 8768 | |||
| 8769 | Using the REST subsystem, you can expose REST-based APIs or services. | ||
| 8770 | The REST service is designed as a pluggable architecture. | ||
| 8771 | To create a new REST endpoint, simply add a library in the form | ||
| 8772 | ``plugin_rest_*''. | ||
| 8773 | The REST service will automatically load all REST plugins on startup. | ||
| 8774 | |||
| 8775 | @strong{Configuration} | ||
| 8776 | |||
| 8777 | The REST service can be configured in various ways. | ||
| 8778 | The reference config file can be found in | ||
| 8779 | @file{src/rest/rest.conf}: | ||
| 8780 | @example | ||
| 8781 | [rest] | ||
| 8782 | REST_PORT=7776 | ||
| 8783 | REST_ALLOW_HEADERS=Authorization,Accept,Content-Type | ||
| 8784 | REST_ALLOW_ORIGIN=* | ||
| 8785 | REST_ALLOW_CREDENTIALS=true | ||
| 8786 | @end example | ||
| 8787 | |||
| 8788 | The port as well as | ||
| 8789 | @deffn{cross-origin resource sharing} (CORS) | ||
| 8790 | @end deffn | ||
| 8791 | headers that are supposed to be advertised by the rest service are | ||
| 8792 | configurable. | ||
| 8793 | |||
| 8794 | @menu | ||
| 8795 | * Namespace considerations:: | ||
| 8796 | * Endpoint documentation:: | ||
| 8797 | @end menu | ||
| 8798 | |||
| 8799 | @node Namespace considerations | ||
| 8800 | @subsection Namespace considerations | ||
| 8801 | |||
| 8802 | The @command{gnunet-rest-service} will load all plugins that are installed. | ||
| 8803 | As such it is important that the endpoint namespaces do not clash. | ||
| 8804 | |||
| 8805 | For example, plugin X might expose the endpoint ``/xxx'' while plugin Y | ||
| 8806 | exposes endpoint ``/xxx/yyy''. | ||
| 8807 | This is a problem if plugin X is also supposed to handle a call | ||
| 8808 | to ``/xxx/yyy''. | ||
| 8809 | Currently the REST service will not complain or warn about such clashes, | ||
| 8810 | so please make sure that endpoints are unambiguous. | ||
| 8811 | |||
| 8812 | @node Endpoint documentation | ||
| 8813 | @subsection Endpoint documentation | ||
| 8814 | |||
| 8815 | This is WIP. Endpoints should be documented appropriately. | ||
| 8816 | Preferably using annotations. | ||
| 8817 | |||
diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi deleted file mode 100644 index 6b68ac498..000000000 --- a/doc/documentation/chapters/installation.texi +++ /dev/null | |||
| @@ -1,2233 +0,0 @@ | |||
| 1 | @node Installing GNUnet | ||
| 2 | @chapter Installing GNUnet | ||
| 3 | |||
| 4 | This guide is intended for those who want to install Gnunet from | ||
| 5 | source. For instructions on how to install GNUnet as a binary package | ||
| 6 | please refer to the official documentation of your operating system or | ||
| 7 | package manager. | ||
| 8 | |||
| 9 | @menu | ||
| 10 | * Installing dependencies:: | ||
| 11 | * Getting the Source Code:: | ||
| 12 | * Create @code{gnunet} user and group:: | ||
| 13 | * Preparing and Compiling the Source Code:: | ||
| 14 | * Installation:: | ||
| 15 | * MOVED FROM USER Checking the Installation:: | ||
| 16 | * MOVED FROM USER The graphical configuration interface:: | ||
| 17 | * MOVED FROM USER Config Leftovers:: | ||
| 18 | @end menu | ||
| 19 | |||
| 20 | @c ----------------------------------------------------------------------- | ||
| 21 | @node Installing dependencies | ||
| 22 | @section Installing dependencies | ||
| 23 | GNUnet needs few libraries and applications for being able to run and | ||
| 24 | another few optional ones for using certain features. Preferably they | ||
| 25 | should be installed with a package manager. Just in case we include a | ||
| 26 | link to the project websites. | ||
| 27 | |||
| 28 | The mandatory libraries and applications are | ||
| 29 | @itemize @bullet | ||
| 30 | @item libtool | ||
| 31 | @item autoconf @geq{}2.59 | ||
| 32 | @item automake @geq{}1.11.1 | ||
| 33 | @item pkg-config | ||
| 34 | @item libgcrypt @geq{}1.6 | ||
| 35 | @item libextractor | ||
| 36 | @item libidn | ||
| 37 | @item libmicrohttpd @geq{}0.9.52 | ||
| 38 | @item libnss | ||
| 39 | @item libunistring | ||
| 40 | @item gettext | ||
| 41 | @item glibc | ||
| 42 | @item libgmp | ||
| 43 | @item gnutls | ||
| 44 | @item libcurl (has to be linked to GnuTLS) or libgnurl | ||
| 45 | @item zlib | ||
| 46 | @end itemize | ||
| 47 | |||
| 48 | In addition GNUnet needs one of of these three databases | ||
| 49 | @itemize @bullet | ||
| 50 | @item sqlite + libsqlite (the default, requires no further configuration) | ||
| 51 | @item postgres + libpq | ||
| 52 | @item mysql + libmysqlclient | ||
| 53 | @end itemize | ||
| 54 | |||
| 55 | These are the dependencies only required for certain features | ||
| 56 | @itemize @bullet | ||
| 57 | @item Texinfo (for building the documentation) | ||
| 58 | @item Texlive (for building the documentation) | ||
| 59 | @item miniupnpc (for traversing NAT boxes more reliably) | ||
| 60 | @item libopus (for running the GNUnet conversation telephony application) | ||
| 61 | @item libpulse (for running the GNUnet conversation telephony application) | ||
| 62 | @item libogg (for running the GNUnet conversation telephony application) | ||
| 63 | @item bluez (for bluetooth support) | ||
| 64 | @item libpbc | ||
| 65 | (for attribute-based encryption and the identity provider subsystem) | ||
| 66 | @item libgabe | ||
| 67 | (for attribute-based encryption and the identity provider subsystem) | ||
| 68 | @end itemize | ||
| 69 | |||
| 70 | @c ----------------------------------------------------------------------- | ||
| 71 | @node Getting the Source Code | ||
| 72 | @section Getting the Source Code | ||
| 73 | You can either download the source code using git (you obviously need | ||
| 74 | git installed) or as an archive. | ||
| 75 | |||
| 76 | Using git type | ||
| 77 | @example | ||
| 78 | git clone https://gnunet.org/git/gnunet.git | ||
| 79 | @end example | ||
| 80 | |||
| 81 | The archive can be found at | ||
| 82 | @uref{https://gnunet.org/downloads}. Extract it using a graphical | ||
| 83 | archive tool or @code{tar}: | ||
| 84 | @example | ||
| 85 | tar xzvf gnunet-0.11.0pre66.tar.gz | ||
| 86 | @end example | ||
| 87 | |||
| 88 | In the next chapter we will assume that the source code is available | ||
| 89 | in the home directory at @code{~/gnunet}. | ||
| 90 | |||
| 91 | @c ----------------------------------------------------------------------- | ||
| 92 | @node Create @code{gnunet} user and group | ||
| 93 | @section Create @code{gnunet} user and group | ||
| 94 | The GNUnet services should be run as a dedicated user called | ||
| 95 | @code{gnunet}. For using them a user should be in the same group as | ||
| 96 | this system user. | ||
| 97 | |||
| 98 | Create user @code{gnunet} who is member of the group @code{gnunet} and | ||
| 99 | specify a home directory where the GNUnet services will store | ||
| 100 | persistant data such as information about peers. | ||
| 101 | @example | ||
| 102 | $ sudo useradd --system --groups gnunet --home-dir /var/lib/gnunet | ||
| 103 | @end example | ||
| 104 | |||
| 105 | Now add your own user to the @code{gnunet} group. | ||
| 106 | @example | ||
| 107 | $ sudo adduser alice gnunet | ||
| 108 | @end example | ||
| 109 | |||
| 110 | @c ----------------------------------------------------------------------- | ||
| 111 | @node Preparing and Compiling the Source Code | ||
| 112 | @section Preparing and Compiling the Source Code | ||
| 113 | For preparing the source code for compilation a bootstrap script and | ||
| 114 | @code{configure} has to be run from the source code directory. When | ||
| 115 | running @code{configure} the following options can be specified to | ||
| 116 | customize the compilation and installation process: | ||
| 117 | |||
| 118 | @itemize @bullet | ||
| 119 | @item @code{--disable-documentation} - don't build the configuration documents | ||
| 120 | @item @code{--enable-looging=[LOGLEVEL]} - choose a loglevel (@code{debug}, @code{info}, @code{warning} or @code{error}) | ||
| 121 | @item @code{--prefix=[PATH]} - the directory where the GNUnet libraries and binaries will be installed | ||
| 122 | @item @code{--with-extractor=[PATH]} - the path to libextractor | ||
| 123 | @item @code{--with-libidn=[PATH]} - the path to libidn | ||
| 124 | @item @code{--with-microhttpd=[PATH]} - the path to libmicrohttpd | ||
| 125 | @item @code{--with-sqlite=[PATH]} - the path to libsqlite | ||
| 126 | @item @code{--with-zlib=[PATH]} - the path to zlib | ||
| 127 | @item @code{--with-sudo=[PATH]} - path to the sudo binary (no need to run @code{make install} as root if specified) | ||
| 128 | @end itemize | ||
| 129 | |||
| 130 | The following example configures the installation prefix | ||
| 131 | @code{/usr/lib} and disables building the documentation | ||
| 132 | @example | ||
| 133 | $ cd ~/gnunet | ||
| 134 | $ ./bootstrap | ||
| 135 | $ configure --prefix=/usr/lib --disable-configuration | ||
| 136 | @end example | ||
| 137 | |||
| 138 | After running the bootstrap script and @code{configure} successfully | ||
| 139 | the source code can be compiled with make. Here @code{-j5} specifies | ||
| 140 | that 5 threads should be used. | ||
| 141 | @example | ||
| 142 | $ make -j5 | ||
| 143 | @end example | ||
| 144 | |||
| 145 | @c ----------------------------------------------------------------------- | ||
| 146 | @node Installation | ||
| 147 | @section Installation | ||
| 148 | The compiled binaries can be installed using @code{make install}. It | ||
| 149 | needs to be run as root (or with sudo) because some binaries need the | ||
| 150 | @code{suid} bit set. Without that some GNUnet subsystems (such as VPN) | ||
| 151 | will not work. | ||
| 152 | |||
| 153 | @example | ||
| 154 | $ sudo make install | ||
| 155 | @end example | ||
| 156 | |||
| 157 | One important library is the GNS plugin for NSS (the name services | ||
| 158 | switch) which allows using GNS (the GNU name system) in the normal DNS | ||
| 159 | resolution process. Unfortunately NSS expects it in a specific | ||
| 160 | location (probably @code{/lib}) which may differ from the installation | ||
| 161 | prefix (see @code{--prefix} option in the previous section). This is | ||
| 162 | why the pugin has to be installed manually. | ||
| 163 | |||
| 164 | Find the directory where nss plugins are installed on your system, e.g. | ||
| 165 | |||
| 166 | @example | ||
| 167 | $ ls -l /lib/libnss_* | ||
| 168 | /lib/libnss_mymachines.so.2 | ||
| 169 | /lib/libnss_resolve.so.2 | ||
| 170 | /lib/libnss_myhostname.so.2 | ||
| 171 | /lib/libnss_systemd.so.2 | ||
| 172 | @end example | ||
| 173 | |||
| 174 | Copy the GNS NSS plugin to that directory: | ||
| 175 | |||
| 176 | @example | ||
| 177 | cp ~/gnunet/src/gns/nss/libnss_gns.so.2 /lib | ||
| 178 | @end example | ||
| 179 | |||
| 180 | Now, to activate the plugin, you need to edit your | ||
| 181 | @code{/etc/nsswitch.conf} where you should find a line like this: | ||
| 182 | |||
| 183 | @example | ||
| 184 | hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 | ||
| 185 | @end example | ||
| 186 | |||
| 187 | The exact details may differ a bit, which is fine. Add the text | ||
| 188 | @code{"gns [NOTFOUND=return]"} after @code{"files"}. | ||
| 189 | |||
| 190 | @example | ||
| 191 | hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 | ||
| 192 | @end example | ||
| 193 | |||
| 194 | Optionally, if GNS shall be used with a browser, execute the GNS | ||
| 195 | CA-setup script. It will isetup the GNS Certificate Authority with the | ||
| 196 | user's browser. | ||
| 197 | @example | ||
| 198 | $ gnunet-gns-proxy-setup-ca | ||
| 199 | @end example | ||
| 200 | |||
| 201 | Finally install a configuration file in | ||
| 202 | @code{~/.gnunet/gnunet.conf}. Below you find an example config which | ||
| 203 | allows you to start GNUnet. | ||
| 204 | |||
| 205 | @example | ||
| 206 | [arm] | ||
| 207 | SYSTEM_ONLY = NO | ||
| 208 | USER_ONLY = NO | ||
| 209 | |||
| 210 | [transport] | ||
| 211 | PLUGINS = tcp | ||
| 212 | @end example | ||
| 213 | |||
| 214 | |||
| 215 | |||
| 216 | |||
| 217 | |||
| 218 | |||
| 219 | @node MOVED FROM USER Checking the Installation | ||
| 220 | @section MOVED FROM USER Checking the Installation | ||
| 221 | @c %**end of header | ||
| 222 | |||
| 223 | This section describes a quick, casual way to check if your GNUnet | ||
| 224 | installation works. However, if it does not, we do not cover | ||
| 225 | steps for recovery --- for this, please study the instructions | ||
| 226 | provided in the developer handbook as well as the system-specific | ||
| 227 | instruction in the source code repository. | ||
| 228 | Please note that the system specific instructions are not provided | ||
| 229 | as part of this handbook!. | ||
| 230 | |||
| 231 | |||
| 232 | @menu | ||
| 233 | * gnunet-gtk:: | ||
| 234 | * Statistics:: | ||
| 235 | * Peer Information:: | ||
| 236 | @end menu | ||
| 237 | |||
| 238 | @cindex GNUnet GTK | ||
| 239 | @cindex GTK | ||
| 240 | @cindex GTK user interface | ||
| 241 | @node gnunet-gtk | ||
| 242 | @subsection gnunet-gtk | ||
| 243 | @c %**end of header | ||
| 244 | |||
| 245 | The @command{gnunet-gtk} package contains several graphical | ||
| 246 | user interfaces for the respective GNUnet applications. | ||
| 247 | Currently these interfaces cover: | ||
| 248 | |||
| 249 | @itemize @bullet | ||
| 250 | @item Statistics | ||
| 251 | @item Peer Information | ||
| 252 | @item GNU Name System | ||
| 253 | @item File Sharing | ||
| 254 | @item Identity Management | ||
| 255 | @item Conversation | ||
| 256 | @end itemize | ||
| 257 | |||
| 258 | @node Statistics | ||
| 259 | @subsection Statistics | ||
| 260 | @c %**end of header | ||
| 261 | |||
| 262 | We assume that you have started gnunet via @code{gnunet-arm} or via your | ||
| 263 | system-provided method for starting services. | ||
| 264 | First, you should launch GNUnet gtk. | ||
| 265 | You can do this from the command-line by typing | ||
| 266 | |||
| 267 | @example | ||
| 268 | gnunet-statistics-gtk | ||
| 269 | @end example | ||
| 270 | |||
| 271 | If your peer is running correctly, you should see a bunch | ||
| 272 | of lines, all of which should be ``significantly'' above zero (at | ||
| 273 | least if your peer has been running for more than a few seconds). The | ||
| 274 | lines indicate how many other peers your peer is connected to (via | ||
| 275 | different mechanisms) and how large the entire overlay network is | ||
| 276 | currently estimated to be. The X-axis represents time (in seconds | ||
| 277 | since the start of @command{gnunet-gtk}). | ||
| 278 | |||
| 279 | You can click on "Traffic" to see information about the amount of | ||
| 280 | bandwidth your peer has consumed, and on "Storage" to check the amount | ||
| 281 | of storage available and used by your peer. Note that "Traffic" is | ||
| 282 | plotted cumulatively, so you should see a strict upwards trend in the | ||
| 283 | traffic. | ||
| 284 | |||
| 285 | The term ``peer'' is a common word used in | ||
| 286 | federated and distributed networks to describe a participating device | ||
| 287 | which is connected to the network. Thus, your Personal Computer or | ||
| 288 | whatever it is you are looking at the Gtk+ interface describes a | ||
| 289 | ``Peer'' or a ``Node''. | ||
| 290 | |||
| 291 | @node Peer Information | ||
| 292 | @subsection Peer Information | ||
| 293 | @c %**end of header | ||
| 294 | |||
| 295 | First, you should launch the graphical user interface. You can do | ||
| 296 | this from the command-line by typing | ||
| 297 | |||
| 298 | @example | ||
| 299 | $ gnunet-peerinfo-gtk | ||
| 300 | @end example | ||
| 301 | |||
| 302 | Once you have done this, you will see a list of known peers (by the | ||
| 303 | first four characters of their public key), their friend status (all | ||
| 304 | should be marked as not-friends initially), their connectivity (green | ||
| 305 | is connected, red is disconnected), assigned bandwidth, country of | ||
| 306 | origin (if determined) and address information. If hardly any peers | ||
| 307 | are listed and/or if there are very few peers with a green light for | ||
| 308 | connectivity, there is likely a problem with your network | ||
| 309 | configuration. | ||
| 310 | |||
| 311 | @c NOTE: Inserted from Installation Handbook in original ``order'': | ||
| 312 | @c FIXME: Move this to User Handbook. | ||
| 313 | @node MOVED FROM USER The graphical configuration interface | ||
| 314 | @section MOVED FROM USER The graphical configuration interface | ||
| 315 | |||
| 316 | If you also would like to use @command{gnunet-gtk} and | ||
| 317 | @command{gnunet-setup} (highly recommended for beginners), do: | ||
| 318 | |||
| 319 | @menu | ||
| 320 | * Configuring your peer:: | ||
| 321 | * Configuring the Friend-to-Friend (F2F) mode:: | ||
| 322 | * Configuring the hostlist to bootstrap:: | ||
| 323 | * Configuration of the HOSTLIST proxy settings:: | ||
| 324 | * Configuring your peer to provide a hostlist :: | ||
| 325 | * Configuring the datastore:: | ||
| 326 | * Configuring the MySQL database:: | ||
| 327 | * Reasons for using MySQL:: | ||
| 328 | * Reasons for not using MySQL:: | ||
| 329 | * Setup Instructions:: | ||
| 330 | * Testing:: | ||
| 331 | * Performance Tuning:: | ||
| 332 | * Setup for running Testcases:: | ||
| 333 | * Configuring the Postgres database:: | ||
| 334 | * Reasons to use Postgres:: | ||
| 335 | * Reasons not to use Postgres:: | ||
| 336 | * Manual setup instructions:: | ||
| 337 | * Testing the setup manually:: | ||
| 338 | * Configuring the datacache:: | ||
| 339 | * Configuring the file-sharing service:: | ||
| 340 | * Configuring logging:: | ||
| 341 | * Configuring the transport service and plugins:: | ||
| 342 | * Configuring the WLAN transport plugin:: | ||
| 343 | * Configuring HTTP(S) reverse proxy functionality using Apache or nginx:: | ||
| 344 | * Blacklisting peers:: | ||
| 345 | * Configuration of the HTTP and HTTPS transport plugins:: | ||
| 346 | * Configuring the GNU Name System:: | ||
| 347 | * Configuring the GNUnet VPN:: | ||
| 348 | * Bandwidth Configuration:: | ||
| 349 | * Configuring NAT:: | ||
| 350 | * Peer configuration for distributions:: | ||
| 351 | @end menu | ||
| 352 | |||
| 353 | @node Configuring your peer | ||
| 354 | @subsection Configuring your peer | ||
| 355 | |||
| 356 | This chapter will describe the various configuration options in GNUnet. | ||
| 357 | |||
| 358 | The easiest way to configure your peer is to use the | ||
| 359 | @command{gnunet-setup} tool. | ||
| 360 | @command{gnunet-setup} is part of the @command{gnunet-gtk} | ||
| 361 | application. You might have to install it separately. | ||
| 362 | |||
| 363 | Many of the specific sections from this chapter actually are linked from | ||
| 364 | within @command{gnunet-setup} to help you while using the setup tool. | ||
| 365 | |||
| 366 | While you can also configure your peer by editing the configuration | ||
| 367 | file by hand, this is not recommended for anyone except for developers | ||
| 368 | as it requires a more in-depth understanding of the configuration files | ||
| 369 | and internal dependencies of GNUnet. | ||
| 370 | |||
| 371 | @node Configuring the Friend-to-Friend (F2F) mode | ||
| 372 | @subsection Configuring the Friend-to-Friend (F2F) mode | ||
| 373 | |||
| 374 | GNUnet knows three basic modes of operation: | ||
| 375 | @itemize @bullet | ||
| 376 | @item In standard "peer-to-peer" mode, | ||
| 377 | your peer will connect to any peer. | ||
| 378 | @item In the pure "friend-to-friend" | ||
| 379 | mode, your peer will ONLY connect to peers from a list of friends | ||
| 380 | specified in the configuration. | ||
| 381 | @item Finally, in mixed mode, | ||
| 382 | GNUnet will only connect to arbitrary peers if it | ||
| 383 | has at least a specified number of connections to friends. | ||
| 384 | @end itemize | ||
| 385 | |||
| 386 | When configuring any of the F2F ("friend-to-friend") modes, | ||
| 387 | you first need to create a file with the peer identities | ||
| 388 | of your friends. Ask your friends to run | ||
| 389 | |||
| 390 | @example | ||
| 391 | $ gnunet-peerinfo -sq | ||
| 392 | @end example | ||
| 393 | |||
| 394 | @noindent | ||
| 395 | The resulting output of this command needs to be added to your | ||
| 396 | @file{friends} file, which is simply a plain text file with one line | ||
| 397 | per friend with the output from the above command. | ||
| 398 | |||
| 399 | You then specify the location of your @file{friends} file in the | ||
| 400 | @code{FRIENDS} option of the "topology" section. | ||
| 401 | |||
| 402 | Once you have created the @file{friends} file, you can tell GNUnet to only | ||
| 403 | connect to your friends by setting the @code{FRIENDS-ONLY} option | ||
| 404 | (again in the "topology" section) to YES. | ||
| 405 | |||
| 406 | If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a | ||
| 407 | minimum number of friends to have (before connecting to arbitrary peers) | ||
| 408 | under the "MINIMUM-FRIENDS" option. | ||
| 409 | |||
| 410 | If you want to operate in normal P2P-only mode, simply set | ||
| 411 | @code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO. | ||
| 412 | This is the default. | ||
| 413 | |||
| 414 | @node Configuring the hostlist to bootstrap | ||
| 415 | @subsection Configuring the hostlist to bootstrap | ||
| 416 | |||
| 417 | After installing the software you need to get connected to the GNUnet | ||
| 418 | network. The configuration file included in your download is already | ||
| 419 | configured to connect you to the GNUnet network. | ||
| 420 | In this section the relevant configuration settings are explained. | ||
| 421 | |||
| 422 | To get an initial connection to the GNUnet network and to get to know | ||
| 423 | peers already connected to the network you can use the so called | ||
| 424 | "bootstrap servers". | ||
| 425 | These servers can give you a list of peers connected to the network. | ||
| 426 | To use these bootstrap servers you have to configure the hostlist daemon | ||
| 427 | to activate bootstrapping. | ||
| 428 | |||
| 429 | To activate bootstrapping, edit the @code{[hostlist]}-section in your | ||
| 430 | configuration file. You have to set the argument @command{-b} in the | ||
| 431 | options line: | ||
| 432 | |||
| 433 | @example | ||
| 434 | [hostlist] | ||
| 435 | OPTIONS = -b | ||
| 436 | @end example | ||
| 437 | |||
| 438 | Additionally you have to specify which server you want to use. | ||
| 439 | The default bootstrapping server is | ||
| 440 | "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}". | ||
| 441 | [^] To set the server you have to edit the line "SERVERS" in the hostlist | ||
| 442 | section. To use the default server you should set the lines to | ||
| 443 | |||
| 444 | @example | ||
| 445 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
| 446 | @end example | ||
| 447 | |||
| 448 | @noindent | ||
| 449 | To use bootstrapping your configuration file should include these lines: | ||
| 450 | |||
| 451 | @example | ||
| 452 | [hostlist] | ||
| 453 | OPTIONS = -b | ||
| 454 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
| 455 | @end example | ||
| 456 | |||
| 457 | @noindent | ||
| 458 | Besides using bootstrap servers you can configure your GNUnet peer to | ||
| 459 | receive hostlist advertisements. | ||
| 460 | Peers offering hostlists to other peers can send advertisement messages | ||
| 461 | to peers that connect to them. If you configure your peer to receive these | ||
| 462 | messages, your peer can download these lists and connect to the peers | ||
| 463 | included. These lists are persistent, which means that they are saved to | ||
| 464 | your hard disk regularly and are loaded during startup. | ||
| 465 | |||
| 466 | To activate hostlist learning you have to add the @command{-e} | ||
| 467 | switch to the @code{OPTIONS} line in the hostlist section: | ||
| 468 | |||
| 469 | @example | ||
| 470 | [hostlist] | ||
| 471 | OPTIONS = -b -e | ||
| 472 | @end example | ||
| 473 | |||
| 474 | @noindent | ||
| 475 | Furthermore you can specify in which file the lists are saved. | ||
| 476 | To save the lists in the file @file{hostlists.file} just add the line: | ||
| 477 | |||
| 478 | @example | ||
| 479 | HOSTLISTFILE = hostlists.file | ||
| 480 | @end example | ||
| 481 | |||
| 482 | @noindent | ||
| 483 | Best practice is to activate both bootstrapping and hostlist learning. | ||
| 484 | So your configuration file should include these lines: | ||
| 485 | |||
| 486 | @example | ||
| 487 | [hostlist] | ||
| 488 | OPTIONS = -b -e | ||
| 489 | HTTPPORT = 8080 | ||
| 490 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
| 491 | HOSTLISTFILE = $SERVICEHOME/hostlists.file | ||
| 492 | @end example | ||
| 493 | |||
| 494 | @node Configuration of the HOSTLIST proxy settings | ||
| 495 | @subsection Configuration of the HOSTLIST proxy settings | ||
| 496 | |||
| 497 | The hostlist client can be configured to use a proxy to connect to the | ||
| 498 | hostlist server. | ||
| 499 | This functionality can be configured in the configuration file directly | ||
| 500 | or using the @command{gnunet-setup} tool. | ||
| 501 | |||
| 502 | The hostlist client supports the following proxy types at the moment: | ||
| 503 | |||
| 504 | @itemize @bullet | ||
| 505 | @item HTTP and HTTP 1.0 only proxy | ||
| 506 | @item SOCKS 4/4a/5/5 with hostname | ||
| 507 | @end itemize | ||
| 508 | |||
| 509 | In addition authentication at the proxy with username and password can be | ||
| 510 | configured. | ||
| 511 | |||
| 512 | To configure proxy support for the hostlist client in the | ||
| 513 | @command{gnunet-setup} tool, select the "hostlist" tab and select | ||
| 514 | the appropriate proxy type. | ||
| 515 | The hostname or IP address (including port if required) has to be entered | ||
| 516 | in the "Proxy hostname" textbox. If required, enter username and password | ||
| 517 | in the "Proxy username" and "Proxy password" boxes. | ||
| 518 | Be aware that this information will be stored in the configuration in | ||
| 519 | plain text (TODO: Add explanation and generalize the part in Chapter 3.6 | ||
| 520 | about the encrypted home). | ||
| 521 | |||
| 522 | To provide these options directly in the configuration, you can | ||
| 523 | enter the following settings in the @code{[hostlist]} section of | ||
| 524 | the configuration: | ||
| 525 | |||
| 526 | @example | ||
| 527 | # Type of proxy server, | ||
| 528 | # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME | ||
| 529 | # Default: HTTP | ||
| 530 | # PROXY_TYPE = HTTP | ||
| 531 | |||
| 532 | # Hostname or IP of proxy server | ||
| 533 | # PROXY = | ||
| 534 | # User name for proxy server | ||
| 535 | # PROXY_USERNAME = | ||
| 536 | # User password for proxy server | ||
| 537 | # PROXY_PASSWORD = | ||
| 538 | @end example | ||
| 539 | |||
| 540 | @node Configuring your peer to provide a hostlist | ||
| 541 | @subsection Configuring your peer to provide a hostlist | ||
| 542 | |||
| 543 | If you operate a peer permanently connected to GNUnet you can configure | ||
| 544 | your peer to act as a hostlist server, providing other peers the list of | ||
| 545 | peers known to him. | ||
| 546 | |||
| 547 | Your server can act as a bootstrap server and peers needing to obtain a | ||
| 548 | list of peers can contact it to download this list. | ||
| 549 | To download this hostlist the peer uses HTTP. | ||
| 550 | For this reason you have to build your peer with libgnurl (or libcurl) | ||
| 551 | and microhttpd support. | ||
| 552 | |||
| 553 | To configure your peer to act as a bootstrap server you have to add the | ||
| 554 | @command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section | ||
| 555 | of your configuration file. | ||
| 556 | Besides that you have to specify a port number for the http server. | ||
| 557 | In conclusion you have to add the following lines: | ||
| 558 | |||
| 559 | @example | ||
| 560 | [hostlist] | ||
| 561 | HTTPPORT = 12980 | ||
| 562 | OPTIONS = -p | ||
| 563 | @end example | ||
| 564 | |||
| 565 | @noindent | ||
| 566 | If your peer acts as a bootstrap server other peers should know about | ||
| 567 | that. You can advertise the hostlist your are providing to other peers. | ||
| 568 | Peers connecting to your peer will get a message containing an | ||
| 569 | advertisement for your hostlist and the URL where it can be downloaded. | ||
| 570 | If this peer is in learning mode, it will test the hostlist and, in the | ||
| 571 | case it can obtain the list successfully, it will save it for | ||
| 572 | bootstrapping. | ||
| 573 | |||
| 574 | To activate hostlist advertisement on your peer, you have to set the | ||
| 575 | following lines in your configuration file: | ||
| 576 | |||
| 577 | @example | ||
| 578 | [hostlist] | ||
| 579 | EXTERNAL_DNS_NAME = example.org | ||
| 580 | HTTPPORT = 12981 | ||
| 581 | OPTIONS = -p -a | ||
| 582 | @end example | ||
| 583 | |||
| 584 | @noindent | ||
| 585 | With this configuration your peer will a act as a bootstrap server and | ||
| 586 | advertise this hostlist to other peers connecting to it. | ||
| 587 | The URL used to download the list will be | ||
| 588 | @code{@uref{http://example.org:12981/, http://example.org:12981/}}. | ||
| 589 | |||
| 590 | Please notice: | ||
| 591 | |||
| 592 | @itemize @bullet | ||
| 593 | @item The hostlist is @b{not} human readable, so you should not try to | ||
| 594 | download it using your webbrowser. Just point your GNUnet peer to the | ||
| 595 | address! | ||
| 596 | @item Advertising without providing a hostlist does not make sense and | ||
| 597 | will not work. | ||
| 598 | @end itemize | ||
| 599 | |||
| 600 | @node Configuring the datastore | ||
| 601 | @subsection Configuring the datastore | ||
| 602 | |||
| 603 | The datastore is what GNUnet uses for long-term storage of file-sharing | ||
| 604 | data. Note that long-term does not mean 'forever' since content does have | ||
| 605 | an expiration date, and of course storage space is finite (and hence | ||
| 606 | sometimes content may have to be discarded). | ||
| 607 | |||
| 608 | Use the @code{QUOTA} option to specify how many bytes of storage space | ||
| 609 | you are willing to dedicate to GNUnet. | ||
| 610 | |||
| 611 | In addition to specifying the maximum space GNUnet is allowed to use for | ||
| 612 | the datastore, you need to specify which database GNUnet should use to do | ||
| 613 | so. Currently, you have the choice between sqLite, MySQL and Postgres. | ||
| 614 | |||
| 615 | @node Configuring the MySQL database | ||
| 616 | @subsection Configuring the MySQL database | ||
| 617 | |||
| 618 | This section describes how to setup the MySQL database for GNUnet. | ||
| 619 | |||
| 620 | Note that the mysql plugin does NOT work with mysql before 4.1 since we | ||
| 621 | need prepared statements. | ||
| 622 | We are generally testing the code against MySQL 5.1 at this point. | ||
| 623 | |||
| 624 | @node Reasons for using MySQL | ||
| 625 | @subsection Reasons for using MySQL | ||
| 626 | |||
| 627 | @itemize @bullet | ||
| 628 | |||
| 629 | @item On up-to-date hardware wher | ||
| 630 | mysql can be used comfortably, this module | ||
| 631 | will have better performance than the other database choices (according | ||
| 632 | to our tests). | ||
| 633 | |||
| 634 | @item Its often possible to recover the mysql database from internal | ||
| 635 | inconsistencies. Some of the other databases do not support repair. | ||
| 636 | @end itemize | ||
| 637 | |||
| 638 | @node Reasons for not using MySQL | ||
| 639 | @subsection Reasons for not using MySQL | ||
| 640 | |||
| 641 | @itemize @bullet | ||
| 642 | @item Memory usage (likely not an issue if you have more than 1 GB) | ||
| 643 | @item Complex manual setup | ||
| 644 | @end itemize | ||
| 645 | |||
| 646 | @node Setup Instructions | ||
| 647 | @subsection Setup Instructions | ||
| 648 | |||
| 649 | @itemize @bullet | ||
| 650 | |||
| 651 | @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for | ||
| 652 | @code{DATABASE} to @code{mysql}. | ||
| 653 | |||
| 654 | @item Access mysql as root: | ||
| 655 | |||
| 656 | @example | ||
| 657 | $ mysql -u root -p | ||
| 658 | @end example | ||
| 659 | |||
| 660 | @noindent | ||
| 661 | and issue the following commands, replacing $USER with the username | ||
| 662 | that will be running @command{gnunet-arm} (so typically "gnunet"): | ||
| 663 | |||
| 664 | @example | ||
| 665 | CREATE DATABASE gnunet; | ||
| 666 | GRANT select,insert,update,delete,create,alter,drop,create \ | ||
| 667 | temporary tables ON gnunet.* TO $USER@@localhost; | ||
| 668 | SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); | ||
| 669 | FLUSH PRIVILEGES; | ||
| 670 | @end example | ||
| 671 | |||
| 672 | @item | ||
| 673 | In the $HOME directory of $USER, create a @file{.my.cnf} file with the | ||
| 674 | following lines | ||
| 675 | |||
| 676 | @example | ||
| 677 | [client] | ||
| 678 | user=$USER | ||
| 679 | password=$the_password_you_like | ||
| 680 | @end example | ||
| 681 | |||
| 682 | @end itemize | ||
| 683 | |||
| 684 | That's it. Note that @file{.my.cnf} file is a slight security risk unless | ||
| 685 | its on a safe partition. The @file{$HOME/.my.cnf} can of course be | ||
| 686 | a symbolic link. | ||
| 687 | Luckily $USER has only privileges to mess up GNUnet's tables, | ||
| 688 | which should be pretty harmless. | ||
| 689 | |||
| 690 | @node Testing | ||
| 691 | @subsection Testing | ||
| 692 | |||
| 693 | You should briefly try if the database connection works. First, login | ||
| 694 | as $USER. Then use: | ||
| 695 | |||
| 696 | @example | ||
| 697 | $ mysql -u $USER | ||
| 698 | mysql> use gnunet; | ||
| 699 | @end example | ||
| 700 | |||
| 701 | @noindent | ||
| 702 | If you get the message | ||
| 703 | |||
| 704 | @example | ||
| 705 | Database changed | ||
| 706 | @end example | ||
| 707 | |||
| 708 | @noindent | ||
| 709 | it probably works. | ||
| 710 | |||
| 711 | If you get | ||
| 712 | |||
| 713 | @example | ||
| 714 | ERROR 2002: Can't connect to local MySQL server | ||
| 715 | through socket '/tmp/mysql.sock' (2) | ||
| 716 | @end example | ||
| 717 | |||
| 718 | @noindent | ||
| 719 | it may be resolvable by | ||
| 720 | |||
| 721 | @example | ||
| 722 | ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock | ||
| 723 | @end example | ||
| 724 | |||
| 725 | @noindent | ||
| 726 | so there may be some additional trouble depending on your mysql setup. | ||
| 727 | |||
| 728 | @node Performance Tuning | ||
| 729 | @subsection Performance Tuning | ||
| 730 | |||
| 731 | For GNUnet, you probably want to set the option | ||
| 732 | |||
| 733 | @example | ||
| 734 | innodb_flush_log_at_trx_commit = 0 | ||
| 735 | @end example | ||
| 736 | |||
| 737 | @noindent | ||
| 738 | for a rather dramatic boost in MySQL performance. However, this reduces | ||
| 739 | the "safety" of your database as with this options you may loose | ||
| 740 | transactions during a power outage. | ||
| 741 | While this is totally harmless for GNUnet, the option applies to all | ||
| 742 | applications using MySQL. So you should set it if (and only if) GNUnet is | ||
| 743 | the only application on your system using MySQL. | ||
| 744 | |||
| 745 | @node Setup for running Testcases | ||
| 746 | @subsection Setup for running Testcases | ||
| 747 | |||
| 748 | If you want to run the testcases, you must create a second database | ||
| 749 | "gnunetcheck" with the same username and password. This database will | ||
| 750 | then be used for testing (@command{make check}). | ||
| 751 | |||
| 752 | @node Configuring the Postgres database | ||
| 753 | @subsection Configuring the Postgres database | ||
| 754 | |||
| 755 | This text describes how to setup the Postgres database for GNUnet. | ||
| 756 | |||
| 757 | This Postgres plugin was developed for Postgres 8.3 but might work for | ||
| 758 | earlier versions as well. | ||
| 759 | |||
| 760 | @node Reasons to use Postgres | ||
| 761 | @subsection Reasons to use Postgres | ||
| 762 | |||
| 763 | @itemize @bullet | ||
| 764 | @item Easier to setup than MySQL | ||
| 765 | @item Real database | ||
| 766 | @end itemize | ||
| 767 | |||
| 768 | @node Reasons not to use Postgres | ||
| 769 | @subsection Reasons not to use Postgres | ||
| 770 | |||
| 771 | @itemize @bullet | ||
| 772 | @item Quite slow | ||
| 773 | @item Still some manual setup required | ||
| 774 | @end itemize | ||
| 775 | |||
| 776 | @node Manual setup instructions | ||
| 777 | @subsection Manual setup instructions | ||
| 778 | |||
| 779 | @itemize @bullet | ||
| 780 | @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for | ||
| 781 | @code{DATABASE} to @code{postgres}. | ||
| 782 | @item Access Postgres to create a user: | ||
| 783 | |||
| 784 | @table @asis | ||
| 785 | @item with Postgres 8.x, use: | ||
| 786 | |||
| 787 | @example | ||
| 788 | # su - postgres | ||
| 789 | $ createuser | ||
| 790 | @end example | ||
| 791 | |||
| 792 | @noindent | ||
| 793 | and enter the name of the user running GNUnet for the role interactively. | ||
| 794 | Then, when prompted, do not set it to superuser, allow the creation of | ||
| 795 | databases, and do not allow the creation of new roles. | ||
| 796 | |||
| 797 | @item with Postgres 9.x, use: | ||
| 798 | |||
| 799 | @example | ||
| 800 | # su - postgres | ||
| 801 | $ createuser -d $GNUNET_USER | ||
| 802 | @end example | ||
| 803 | |||
| 804 | @noindent | ||
| 805 | where $GNUNET_USER is the name of the user running GNUnet. | ||
| 806 | |||
| 807 | @end table | ||
| 808 | |||
| 809 | |||
| 810 | @item | ||
| 811 | As that user (so typically as user "gnunet"), create a database (or two): | ||
| 812 | |||
| 813 | @example | ||
| 814 | $ createdb gnunet | ||
| 815 | # this way you can run "make check" | ||
| 816 | $ createdb gnunetcheck | ||
| 817 | @end example | ||
| 818 | |||
| 819 | @end itemize | ||
| 820 | |||
| 821 | Now you should be able to start @code{gnunet-arm}. | ||
| 822 | |||
| 823 | @node Testing the setup manually | ||
| 824 | @subsection Testing the setup manually | ||
| 825 | |||
| 826 | You may want to try if the database connection works. First, again login | ||
| 827 | as the user who will run @command{gnunet-arm}. Then use: | ||
| 828 | |||
| 829 | @example | ||
| 830 | $ psql gnunet # or gnunetcheck | ||
| 831 | gnunet=> \dt | ||
| 832 | @end example | ||
| 833 | |||
| 834 | @noindent | ||
| 835 | If, after you have started @command{gnunet-arm} at least once, you get | ||
| 836 | a @code{gn090} table here, it probably works. | ||
| 837 | |||
| 838 | @node Configuring the datacache | ||
| 839 | @subsection Configuring the datacache | ||
| 840 | @c %**end of header | ||
| 841 | |||
| 842 | The datacache is what GNUnet uses for storing temporary data. This data is | ||
| 843 | expected to be wiped completely each time GNUnet is restarted (or the | ||
| 844 | system is rebooted). | ||
| 845 | |||
| 846 | You need to specify how many bytes GNUnet is allowed to use for the | ||
| 847 | datacache using the @code{QUOTA} option in the section @code{[dhtcache]}. | ||
| 848 | Furthermore, you need to specify which database backend should be used to | ||
| 849 | store the data. Currently, you have the choice between | ||
| 850 | sqLite, MySQL and Postgres. | ||
| 851 | |||
| 852 | @node Configuring the file-sharing service | ||
| 853 | @subsection Configuring the file-sharing service | ||
| 854 | |||
| 855 | In order to use GNUnet for file-sharing, you first need to make sure | ||
| 856 | that the file-sharing service is loaded. | ||
| 857 | This is done by setting the @code{START_ON_DEMAND} option in | ||
| 858 | section @code{[fs]} to "YES". Alternatively, you can run | ||
| 859 | |||
| 860 | @example | ||
| 861 | $ gnunet-arm -i fs | ||
| 862 | @end example | ||
| 863 | |||
| 864 | @noindent | ||
| 865 | to start the file-sharing service by hand. | ||
| 866 | |||
| 867 | Except for configuring the database and the datacache the only important | ||
| 868 | option for file-sharing is content migration. | ||
| 869 | |||
| 870 | Content migration allows your peer to cache content from other peers as | ||
| 871 | well as send out content stored on your system without explicit requests. | ||
| 872 | This content replication has positive and negative impacts on both system | ||
| 873 | performance and privacy. | ||
| 874 | |||
| 875 | FIXME: discuss the trade-offs. Here is some older text about it... | ||
| 876 | |||
| 877 | Setting this option to YES allows gnunetd to migrate data to the local | ||
| 878 | machine. Setting this option to YES is highly recommended for efficiency. | ||
| 879 | Its also the default. If you set this value to YES, GNUnet will store | ||
| 880 | content on your machine that you cannot decrypt. | ||
| 881 | While this may protect you from liability if the judge is sane, it may | ||
| 882 | not (IANAL). If you put illegal content on your machine yourself, setting | ||
| 883 | this option to YES will probably increase your chances to get away with it | ||
| 884 | since you can plausibly deny that you inserted the content. | ||
| 885 | Note that in either case, your anonymity would have to be broken first | ||
| 886 | (which may be possible depending on the size of the GNUnet network and the | ||
| 887 | strength of the adversary). | ||
| 888 | |||
| 889 | @node Configuring logging | ||
| 890 | @subsection Configuring logging | ||
| 891 | |||
| 892 | Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. | ||
| 893 | Using @code{-L}, a log level can be specified. With log level | ||
| 894 | @code{ERROR} only serious errors are logged. | ||
| 895 | The default log level is @code{WARNING} which causes anything of | ||
| 896 | concern to be logged. | ||
| 897 | Log level @code{INFO} can be used to log anything that might be | ||
| 898 | interesting information whereas | ||
| 899 | @code{DEBUG} can be used by developers to log debugging messages | ||
| 900 | (but you need to run @code{./configure} with | ||
| 901 | @code{--enable-logging=verbose} to get them compiled). | ||
| 902 | The @code{-l} option is used to specify the log file. | ||
| 903 | |||
| 904 | Since most GNUnet services are managed by @code{gnunet-arm}, using the | ||
| 905 | @code{-l} or @code{-L} options directly is not possible. | ||
| 906 | Instead, they can be specified using the @code{OPTIONS} configuration | ||
| 907 | value in the respective section for the respective service. | ||
| 908 | In order to enable logging globally without editing the @code{OPTIONS} | ||
| 909 | values for each service, @command{gnunet-arm} supports a | ||
| 910 | @code{GLOBAL_POSTFIX} option. | ||
| 911 | The value specified here is given as an extra option to all services for | ||
| 912 | which the configuration does contain a service-specific @code{OPTIONS} | ||
| 913 | field. | ||
| 914 | |||
| 915 | @code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which | ||
| 916 | is replaced by the name of the service that is being started. | ||
| 917 | Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences | ||
| 918 | starting with "$" anywhere in the string are expanded (according | ||
| 919 | to options in @code{PATHS}); this expansion otherwise is | ||
| 920 | only happening for filenames and then the "$" must be the | ||
| 921 | first character in the option. Both of these restrictions do | ||
| 922 | not apply to @code{GLOBAL_POSTFIX}. | ||
| 923 | Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX} | ||
| 924 | disables both of these features. | ||
| 925 | |||
| 926 | In summary, in order to get all services to log at level | ||
| 927 | @code{INFO} to log-files called @code{SERVICENAME-logs}, the | ||
| 928 | following global prefix should be used: | ||
| 929 | |||
| 930 | @example | ||
| 931 | GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO | ||
| 932 | @end example | ||
| 933 | |||
| 934 | @node Configuring the transport service and plugins | ||
| 935 | @subsection Configuring the transport service and plugins | ||
| 936 | |||
| 937 | The transport service in GNUnet is responsible to maintain basic | ||
| 938 | connectivity to other peers. | ||
| 939 | Besides initiating and keeping connections alive it is also responsible | ||
| 940 | for address validation. | ||
| 941 | |||
| 942 | The GNUnet transport supports more than one transport protocol. | ||
| 943 | These protocols are configured together with the transport service. | ||
| 944 | |||
| 945 | The configuration section for the transport service itself is quite | ||
| 946 | similar to all the other services | ||
| 947 | |||
| 948 | @example | ||
| 949 | START_ON_DEMAND = YES | ||
| 950 | @@UNIXONLY@@ PORT = 2091 | ||
| 951 | HOSTNAME = localhost | ||
| 952 | HOME = $SERVICEHOME | ||
| 953 | CONFIG = $DEFAULTCONFIG | ||
| 954 | BINARY = gnunet-service-transport | ||
| 955 | #PREFIX = valgrind | ||
| 956 | NEIGHBOUR_LIMIT = 50 | ||
| 957 | ACCEPT_FROM = 127.0.0.1; | ||
| 958 | ACCEPT_FROM6 = ::1; | ||
| 959 | PLUGINS = tcp udp | ||
| 960 | UNIXPATH = /tmp/gnunet-service-transport.sock | ||
| 961 | @end example | ||
| 962 | |||
| 963 | Different are the settings for the plugins to load @code{PLUGINS}. | ||
| 964 | The first setting specifies which transport plugins to load. | ||
| 965 | |||
| 966 | @itemize @bullet | ||
| 967 | @item transport-unix | ||
| 968 | A plugin for local only communication with UNIX domain sockets. Used for | ||
| 969 | testing and available on unix systems only. Just set the port | ||
| 970 | |||
| 971 | @example | ||
| 972 | [transport-unix] | ||
| 973 | PORT = 22086 | ||
| 974 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
| 975 | @end example | ||
| 976 | |||
| 977 | @item transport-tcp | ||
| 978 | A plugin for communication with TCP. Set port to 0 for client mode with | ||
| 979 | outbound only connections | ||
| 980 | |||
| 981 | @example | ||
| 982 | [transport-tcp] | ||
| 983 | # Use 0 to ONLY advertise as a peer behind NAT (no port binding) | ||
| 984 | PORT = 2086 | ||
| 985 | ADVERTISED_PORT = 2086 | ||
| 986 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
| 987 | # Maximum number of open TCP connections allowed | ||
| 988 | MAX_CONNECTIONS = 128 | ||
| 989 | @end example | ||
| 990 | |||
| 991 | @item transport-udp | ||
| 992 | A plugin for communication with UDP. Supports peer discovery using | ||
| 993 | broadcasts. | ||
| 994 | |||
| 995 | @example | ||
| 996 | [transport-udp] | ||
| 997 | PORT = 2086 | ||
| 998 | BROADCAST = YES | ||
| 999 | BROADCAST_INTERVAL = 30 s | ||
| 1000 | MAX_BPS = 1000000 | ||
| 1001 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
| 1002 | @end example | ||
| 1003 | |||
| 1004 | @item transport-http | ||
| 1005 | HTTP and HTTPS support is split in two part: a client plugin initiating | ||
| 1006 | outbound connections and a server part accepting connections from the | ||
| 1007 | client. The client plugin just takes the maximum number of connections as | ||
| 1008 | an argument. | ||
| 1009 | |||
| 1010 | @example | ||
| 1011 | [transport-http_client] | ||
| 1012 | MAX_CONNECTIONS = 128 | ||
| 1013 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
| 1014 | @end example | ||
| 1015 | |||
| 1016 | @example | ||
| 1017 | [transport-https_client] | ||
| 1018 | MAX_CONNECTIONS = 128 | ||
| 1019 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
| 1020 | @end example | ||
| 1021 | |||
| 1022 | @noindent | ||
| 1023 | The server has a port configured and the maximum number of connections. | ||
| 1024 | The HTTPS part has two files with the certificate key and the certificate | ||
| 1025 | file. | ||
| 1026 | |||
| 1027 | The server plugin supports reverse proxies, so a external hostname can be | ||
| 1028 | set using the @code{EXTERNAL_HOSTNAME} setting. | ||
| 1029 | The webserver under this address should forward the request to the peer | ||
| 1030 | and the configure port. | ||
| 1031 | |||
| 1032 | @example | ||
| 1033 | [transport-http_server] | ||
| 1034 | EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet | ||
| 1035 | PORT = 1080 | ||
| 1036 | MAX_CONNECTIONS = 128 | ||
| 1037 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
| 1038 | @end example | ||
| 1039 | |||
| 1040 | @example | ||
| 1041 | [transport-https_server] | ||
| 1042 | PORT = 4433 | ||
| 1043 | CRYPTO_INIT = NORMAL | ||
| 1044 | KEY_FILE = https.key | ||
| 1045 | CERT_FILE = https.cert | ||
| 1046 | MAX_CONNECTIONS = 128 | ||
| 1047 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
| 1048 | @end example | ||
| 1049 | |||
| 1050 | @item transport-wlan | ||
| 1051 | |||
| 1052 | The next section describes how to setup the WLAN plugin, | ||
| 1053 | so here only the settings. Just specify the interface to use: | ||
| 1054 | |||
| 1055 | @example | ||
| 1056 | [transport-wlan] | ||
| 1057 | # Name of the interface in monitor mode (typically monX) | ||
| 1058 | INTERFACE = mon0 | ||
| 1059 | # Real hardware, no testing | ||
| 1060 | TESTMODE = 0 | ||
| 1061 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
| 1062 | @end example | ||
| 1063 | @end itemize | ||
| 1064 | |||
| 1065 | @node Configuring the WLAN transport plugin | ||
| 1066 | @subsection Configuring the WLAN transport plugin | ||
| 1067 | |||
| 1068 | The wlan transport plugin enables GNUnet to send and to receive data on a | ||
| 1069 | wlan interface. | ||
| 1070 | It has not to be connected to a wlan network as long as sender and | ||
| 1071 | receiver are on the same channel. This enables you to get connection to | ||
| 1072 | GNUnet where no internet access is possible, for example during | ||
| 1073 | catastrophes or when censorship cuts you off from the internet. | ||
| 1074 | |||
| 1075 | |||
| 1076 | @menu | ||
| 1077 | * Requirements for the WLAN plugin:: | ||
| 1078 | * Configuration:: | ||
| 1079 | * Before starting GNUnet:: | ||
| 1080 | * Limitations and known bugs:: | ||
| 1081 | @end menu | ||
| 1082 | |||
| 1083 | |||
| 1084 | @node Requirements for the WLAN plugin | ||
| 1085 | @subsubsection Requirements for the WLAN plugin | ||
| 1086 | |||
| 1087 | @itemize @bullet | ||
| 1088 | |||
| 1089 | @item wlan network card with monitor support and packet injection | ||
| 1090 | (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org}) | ||
| 1091 | |||
| 1092 | @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with | ||
| 1093 | 2.6.35 and 2.6.38 | ||
| 1094 | |||
| 1095 | @item Wlantools to create the a monitor interface, tested with airmon-ng | ||
| 1096 | of the aircrack-ng package | ||
| 1097 | @end itemize | ||
| 1098 | |||
| 1099 | @node Configuration | ||
| 1100 | @subsubsection Configuration | ||
| 1101 | |||
| 1102 | There are the following options for the wlan plugin (they should be like | ||
| 1103 | this in your default config file, you only need to adjust them if the | ||
| 1104 | values are incorrect for your system) | ||
| 1105 | |||
| 1106 | @example | ||
| 1107 | # section for the wlan transport plugin | ||
| 1108 | [transport-wlan] | ||
| 1109 | # interface to use, more information in the | ||
| 1110 | # "Before starting GNUnet" section of the handbook. | ||
| 1111 | INTERFACE = mon0 | ||
| 1112 | # testmode for developers: | ||
| 1113 | # 0 use wlan interface, | ||
| 1114 | #1 or 2 use loopback driver for tests 1 = server, 2 = client | ||
| 1115 | TESTMODE = 0 | ||
| 1116 | @end example | ||
| 1117 | |||
| 1118 | @node Before starting GNUnet | ||
| 1119 | @subsubsection Before starting GNUnet | ||
| 1120 | |||
| 1121 | Before starting GNUnet, you have to make sure that your wlan interface is | ||
| 1122 | in monitor mode. | ||
| 1123 | One way to put the wlan interface into monitor mode (if your interface | ||
| 1124 | name is wlan0) is by executing: | ||
| 1125 | |||
| 1126 | @example | ||
| 1127 | sudo airmon-ng start wlan0 | ||
| 1128 | @end example | ||
| 1129 | |||
| 1130 | @noindent | ||
| 1131 | Here is an example what the result should look like: | ||
| 1132 | |||
| 1133 | @example | ||
| 1134 | Interface Chipset Driver | ||
| 1135 | wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0] | ||
| 1136 | (monitor mode enabled on mon0) | ||
| 1137 | @end example | ||
| 1138 | |||
| 1139 | @noindent | ||
| 1140 | The monitor interface is mon0 is the one that you have to put into the | ||
| 1141 | configuration file. | ||
| 1142 | |||
| 1143 | @node Limitations and known bugs | ||
| 1144 | @subsubsection Limitations and known bugs | ||
| 1145 | |||
| 1146 | Wlan speed is at the maximum of 1 Mbit/s because support for choosing the | ||
| 1147 | wlan speed with packet injection was removed in newer kernels. | ||
| 1148 | Please pester the kernel developers about fixing this. | ||
| 1149 | |||
| 1150 | The interface channel depends on the wlan network that the card is | ||
| 1151 | connected to. If no connection has been made since the start of the | ||
| 1152 | computer, it is usually the first channel of the card. | ||
| 1153 | Peers will only find each other and communicate if they are on the same | ||
| 1154 | channel. Channels must be set manually, i.e. using: | ||
| 1155 | |||
| 1156 | @example | ||
| 1157 | iwconfig wlan0 channel 1 | ||
| 1158 | @end example | ||
| 1159 | |||
| 1160 | @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx | ||
| 1161 | @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx | ||
| 1162 | |||
| 1163 | The HTTP plugin supports data transfer using reverse proxies. A reverse | ||
| 1164 | proxy forwards the HTTP request he receives with a certain URL to another | ||
| 1165 | webserver, here a GNUnet peer. | ||
| 1166 | |||
| 1167 | So if you have a running Apache or nginx webserver you can configure it to | ||
| 1168 | be a GNUnet reverse proxy. Especially if you have a well-known webiste | ||
| 1169 | this improves censorship resistance since it looks as normal surfing | ||
| 1170 | behaviour. | ||
| 1171 | |||
| 1172 | To do so, you have to do two things: | ||
| 1173 | |||
| 1174 | @itemize @bullet | ||
| 1175 | @item Configure your webserver to forward the GNUnet HTTP traffic | ||
| 1176 | @item Configure your GNUnet peer to announce the respective address | ||
| 1177 | @end itemize | ||
| 1178 | |||
| 1179 | As an example we want to use GNUnet peer running: | ||
| 1180 | |||
| 1181 | @itemize @bullet | ||
| 1182 | |||
| 1183 | @item HTTP server plugin on @code{gnunet.foo.org:1080} | ||
| 1184 | |||
| 1185 | @item HTTPS server plugin on @code{gnunet.foo.org:4433} | ||
| 1186 | |||
| 1187 | @item A apache or nginx webserver on | ||
| 1188 | @uref{http://www.foo.org/, http://www.foo.org:80/} | ||
| 1189 | |||
| 1190 | @item A apache or nginx webserver on https://www.foo.org:443/ | ||
| 1191 | @end itemize | ||
| 1192 | |||
| 1193 | And we want the webserver to accept GNUnet traffic under | ||
| 1194 | @code{http://www.foo.org/bar/}. The required steps are described here: | ||
| 1195 | |||
| 1196 | @menu | ||
| 1197 | * Reverse Proxy - Configure your Apache2 HTTP webserver:: | ||
| 1198 | * Reverse Proxy - Configure your Apache2 HTTPS webserver:: | ||
| 1199 | * Reverse Proxy - Configure your nginx HTTPS webserver:: | ||
| 1200 | * Reverse Proxy - Configure your nginx HTTP webserver:: | ||
| 1201 | * Reverse Proxy - Configure your GNUnet peer:: | ||
| 1202 | @end menu | ||
| 1203 | |||
| 1204 | @node Reverse Proxy - Configure your Apache2 HTTP webserver | ||
| 1205 | @subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver | ||
| 1206 | |||
| 1207 | First of all you need mod_proxy installed. | ||
| 1208 | |||
| 1209 | Edit your webserver configuration. Edit | ||
| 1210 | @code{/etc/apache2/apache2.conf} or the site-specific configuration file. | ||
| 1211 | |||
| 1212 | In the respective @code{server config},@code{virtual host} or | ||
| 1213 | @code{directory} section add the following lines: | ||
| 1214 | |||
| 1215 | @example | ||
| 1216 | ProxyTimeout 300 | ||
| 1217 | ProxyRequests Off | ||
| 1218 | <Location /bar/ > | ||
| 1219 | ProxyPass http://gnunet.foo.org:1080/ | ||
| 1220 | ProxyPassReverse http://gnunet.foo.org:1080/ | ||
| 1221 | </Location> | ||
| 1222 | @end example | ||
| 1223 | |||
| 1224 | @node Reverse Proxy - Configure your Apache2 HTTPS webserver | ||
| 1225 | @subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver | ||
| 1226 | |||
| 1227 | We assume that you already have an HTTPS server running, if not please | ||
| 1228 | check how to configure a HTTPS host. An uncomplicated to use example | ||
| 1229 | is the example configuration file for Apache2/HTTPD provided in | ||
| 1230 | @file{apache2/sites-available/default-ssl}. | ||
| 1231 | |||
| 1232 | In the respective HTTPS @code{server config},@code{virtual host} or | ||
| 1233 | @code{directory} section add the following lines: | ||
| 1234 | |||
| 1235 | @example | ||
| 1236 | SSLProxyEngine On | ||
| 1237 | ProxyTimeout 300 | ||
| 1238 | ProxyRequests Off | ||
| 1239 | <Location /bar/ > | ||
| 1240 | ProxyPass https://gnunet.foo.org:4433/ | ||
| 1241 | ProxyPassReverse https://gnunet.foo.org:4433/ | ||
| 1242 | </Location> | ||
| 1243 | @end example | ||
| 1244 | |||
| 1245 | @noindent | ||
| 1246 | More information about the apache mod_proxy configuration can be found | ||
| 1247 | in the | ||
| 1248 | @uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, Apache documentation}. | ||
| 1249 | |||
| 1250 | @node Reverse Proxy - Configure your nginx HTTPS webserver | ||
| 1251 | @subsubsection Reverse Proxy - Configure your nginx HTTPS webserver | ||
| 1252 | |||
| 1253 | Since nginx does not support chunked encoding, you first of all have to | ||
| 1254 | install the @code{chunkin} | ||
| 1255 | @uref{http://wiki.nginx.org/HttpChunkinModule, module}. | ||
| 1256 | |||
| 1257 | To enable chunkin add: | ||
| 1258 | |||
| 1259 | @example | ||
| 1260 | chunkin on; | ||
| 1261 | error_page 411 = @@my_411_error; | ||
| 1262 | location @@my_411_error @{ | ||
| 1263 | chunkin_resume; | ||
| 1264 | @} | ||
| 1265 | @end example | ||
| 1266 | |||
| 1267 | @noindent | ||
| 1268 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or | ||
| 1269 | the site-specific configuration file. | ||
| 1270 | |||
| 1271 | In the @code{server} section add: | ||
| 1272 | |||
| 1273 | @example | ||
| 1274 | location /bar/ @{ | ||
| 1275 | proxy_pass http://gnunet.foo.org:1080/; | ||
| 1276 | proxy_buffering off; | ||
| 1277 | proxy_connect_timeout 5; # more than http_server | ||
| 1278 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout | ||
| 1279 | proxy_http_version 1.1; # 1.0 default | ||
| 1280 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; | ||
| 1281 | @} | ||
| 1282 | @end example | ||
| 1283 | |||
| 1284 | @node Reverse Proxy - Configure your nginx HTTP webserver | ||
| 1285 | @subsubsection Reverse Proxy - Configure your nginx HTTP webserver | ||
| 1286 | |||
| 1287 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or | ||
| 1288 | the site-specific configuration file. | ||
| 1289 | |||
| 1290 | In the @code{server} section add: | ||
| 1291 | |||
| 1292 | @example | ||
| 1293 | ssl_session_timeout 6m; | ||
| 1294 | location /bar/ | ||
| 1295 | @{ | ||
| 1296 | proxy_pass https://gnunet.foo.org:4433/; | ||
| 1297 | proxy_buffering off; | ||
| 1298 | proxy_connect_timeout 5; # more than http_server | ||
| 1299 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout | ||
| 1300 | proxy_http_version 1.1; # 1.0 default | ||
| 1301 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; | ||
| 1302 | @} | ||
| 1303 | @end example | ||
| 1304 | |||
| 1305 | @node Reverse Proxy - Configure your GNUnet peer | ||
| 1306 | @subsubsection Reverse Proxy - Configure your GNUnet peer | ||
| 1307 | |||
| 1308 | To have your GNUnet peer announce the address, you have to specify the | ||
| 1309 | @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]} | ||
| 1310 | section: | ||
| 1311 | |||
| 1312 | @example | ||
| 1313 | [transport-http_server] | ||
| 1314 | EXTERNAL_HOSTNAME = http://www.foo.org/bar/ | ||
| 1315 | @end example | ||
| 1316 | |||
| 1317 | @noindent | ||
| 1318 | and/or @code{[transport-https_server]} section: | ||
| 1319 | |||
| 1320 | @example | ||
| 1321 | [transport-https_server] | ||
| 1322 | EXTERNAL_HOSTNAME = https://www.foo.org/bar/ | ||
| 1323 | @end example | ||
| 1324 | |||
| 1325 | @noindent | ||
| 1326 | Now restart your webserver and your peer... | ||
| 1327 | |||
| 1328 | @node Blacklisting peers | ||
| 1329 | @subsection Blacklisting peers | ||
| 1330 | |||
| 1331 | Transport service supports to deny connecting to a specific peer of to a | ||
| 1332 | specific peer with a specific transport plugin using te blacklisting | ||
| 1333 | component of transport service. With@ blacklisting it is possible to deny | ||
| 1334 | connections to specific peers of@ to use a specific plugin to a specific | ||
| 1335 | peer. Peers can be blacklisted using@ the configuration or a blacklist | ||
| 1336 | client can be asked. | ||
| 1337 | |||
| 1338 | To blacklist peers using the configuration you have to add a section to | ||
| 1339 | your configuration containing the peer id of the peer to blacklist and | ||
| 1340 | the plugin@ if required. | ||
| 1341 | |||
| 1342 | Examples: | ||
| 1343 | |||
| 1344 | To blacklist connections to P565... on peer AG2P... using tcp add: | ||
| 1345 | |||
| 1346 | @c FIXME: This is too long and produces errors in the pdf. | ||
| 1347 | @example | ||
| 1348 | [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] | ||
| 1349 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp | ||
| 1350 | @end example | ||
| 1351 | |||
| 1352 | To blacklist connections to P565... on peer AG2P... using all plugins add: | ||
| 1353 | |||
| 1354 | @example | ||
| 1355 | [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] | ||
| 1356 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = | ||
| 1357 | @end example | ||
| 1358 | |||
| 1359 | You can also add a blacklist client usign the blacklist API. On a | ||
| 1360 | blacklist check, blacklisting first checks internally if the peer is | ||
| 1361 | blacklisted and if not, it asks the blacklisting clients. Clients are | ||
| 1362 | asked if it is OK to connect to a peer ID, the plugin is omitted. | ||
| 1363 | |||
| 1364 | On blacklist check for (peer, plugin) | ||
| 1365 | |||
| 1366 | @itemize @bullet | ||
| 1367 | @item Do we have a local blacklist entry for this peer and this plugin? | ||
| 1368 | @item YES: disallow connection | ||
| 1369 | @item Do we have a local blacklist entry for this peer and all plugins? | ||
| 1370 | @item YES: disallow connection | ||
| 1371 | @item Does one of the clients disallow? | ||
| 1372 | @item YES: disallow connection | ||
| 1373 | @end itemize | ||
| 1374 | |||
| 1375 | @node Configuration of the HTTP and HTTPS transport plugins | ||
| 1376 | @subsection Configuration of the HTTP and HTTPS transport plugins | ||
| 1377 | |||
| 1378 | The client parts of the http and https transport plugins can be configured | ||
| 1379 | to use a proxy to connect to the hostlist server. This functionality can | ||
| 1380 | be configured in the configuration file directly or using the | ||
| 1381 | gnunet-setup tool. | ||
| 1382 | |||
| 1383 | Both the HTTP and HTTPS clients support the following proxy types at | ||
| 1384 | the moment: | ||
| 1385 | |||
| 1386 | @itemize @bullet | ||
| 1387 | @item HTTP 1.1 proxy | ||
| 1388 | @item SOCKS 4/4a/5/5 with hostname | ||
| 1389 | @end itemize | ||
| 1390 | |||
| 1391 | In addition authentication at the proxy with username and password can be | ||
| 1392 | configured. | ||
| 1393 | |||
| 1394 | To configure proxy support for the clients in the gnunet-setup tool, | ||
| 1395 | select the "transport" tab and activate the respective plugin. Now you | ||
| 1396 | can select the appropriate proxy type. The hostname or IP address | ||
| 1397 | (including port if required) has to be entered in the "Proxy hostname" | ||
| 1398 | textbox. If required, enter username and password in the "Proxy username" | ||
| 1399 | and "Proxy password" boxes. Be aware that these information will be stored | ||
| 1400 | in the configuration in plain text. | ||
| 1401 | |||
| 1402 | To configure these options directly in the configuration, you can | ||
| 1403 | configure the following settings in the @code{[transport-http_client]} | ||
| 1404 | and @code{[transport-https_client]} section of the configuration: | ||
| 1405 | |||
| 1406 | @example | ||
| 1407 | # Type of proxy server, | ||
| 1408 | # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME | ||
| 1409 | # Default: HTTP | ||
| 1410 | # PROXY_TYPE = HTTP | ||
| 1411 | |||
| 1412 | # Hostname or IP of proxy server | ||
| 1413 | # PROXY = | ||
| 1414 | # User name for proxy server | ||
| 1415 | # PROXY_USERNAME = | ||
| 1416 | # User password for proxy server | ||
| 1417 | # PROXY_PASSWORD = | ||
| 1418 | @end example | ||
| 1419 | |||
| 1420 | @node Configuring the GNU Name System | ||
| 1421 | @subsection Configuring the GNU Name System | ||
| 1422 | |||
| 1423 | @menu | ||
| 1424 | * Configuring system-wide DNS interception:: | ||
| 1425 | * Configuring the GNS nsswitch plugin:: | ||
| 1426 | * Configuring GNS on W32:: | ||
| 1427 | * GNS Proxy Setup:: | ||
| 1428 | * Setup of the GNS CA:: | ||
| 1429 | * Testing the GNS setup:: | ||
| 1430 | @end menu | ||
| 1431 | |||
| 1432 | |||
| 1433 | @node Configuring system-wide DNS interception | ||
| 1434 | @subsubsection Configuring system-wide DNS interception | ||
| 1435 | |||
| 1436 | Before you install GNUnet, make sure you have a user and group 'gnunet' | ||
| 1437 | as well as an empty group 'gnunetdns'. | ||
| 1438 | |||
| 1439 | When using GNUnet with system-wide DNS interception, it is absolutely | ||
| 1440 | necessary for all GNUnet service processes to be started by | ||
| 1441 | @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be | ||
| 1442 | sure to run @code{make install} as root (or use the @code{sudo} option to | ||
| 1443 | configure) to grant GNUnet sufficient privileges. | ||
| 1444 | |||
| 1445 | With this setup, all that is required for enabling system-wide DNS | ||
| 1446 | interception is for some GNUnet component (VPN or GNS) to request it. | ||
| 1447 | The @code{gnunet-service-dns} will then start helper programs that will | ||
| 1448 | make the necessary changes to your firewall (@code{iptables}) rules. | ||
| 1449 | |||
| 1450 | Note that this will NOT work if your system sends out DNS traffic to a | ||
| 1451 | link-local IPv6 address, as in this case GNUnet can intercept the traffic, | ||
| 1452 | but not inject the responses from the link-local IPv6 address. Hence you | ||
| 1453 | cannot use system-wide DNS interception in conjunction with link-local | ||
| 1454 | IPv6-based DNS servers. If such a DNS server is used, it will bypass | ||
| 1455 | GNUnet's DNS traffic interception. | ||
| 1456 | |||
| 1457 | Using the GNU Name System (GNS) requires two different configuration | ||
| 1458 | steps. | ||
| 1459 | First of all, GNS needs to be integrated with the operating system. Most | ||
| 1460 | of this section is about the operating system level integration. | ||
| 1461 | |||
| 1462 | The remainder of this chapter will detail the various methods for | ||
| 1463 | configuring the use of GNS with your operating system. | ||
| 1464 | |||
| 1465 | At this point in time you have different options depending on your OS: | ||
| 1466 | |||
| 1467 | @table @asis | ||
| 1468 | |||
| 1469 | @item Use the gnunet-gns-proxy This approach works for all operating | ||
| 1470 | systems and is likely the easiest. However, it enables GNS only for | ||
| 1471 | browsers, not for other applications that might be using DNS, such as SSH. | ||
| 1472 | Still, using the proxy is required for using HTTP with GNS and is thus | ||
| 1473 | recommended for all users. To do this, you simply have to run the | ||
| 1474 | @code{gnunet-gns-proxy-setup-ca} script as the user who will run the | ||
| 1475 | browser (this will create a GNS certificate authority (CA) on your system | ||
| 1476 | and import its key into your browser), then start @code{gnunet-gns-proxy} | ||
| 1477 | and inform your browser to use the Socks5 proxy which | ||
| 1478 | @code{gnunet-gns-proxy} makes available by default on port 7777. | ||
| 1479 | @item Use a nsswitch plugin (recommended on GNU systems) | ||
| 1480 | This approach has the advantage of offering fully personalized resolution | ||
| 1481 | even on multi-user systems. A potential disadvantage is that some | ||
| 1482 | applications might be able to bypass GNS. | ||
| 1483 | @item Use a W32 resolver plugin (recommended on W32) | ||
| 1484 | This is currently the only option on W32 systems. | ||
| 1485 | @item Use system-wide DNS packet interception | ||
| 1486 | This approach is recommended for the GNUnet VPN. It can be used to handle | ||
| 1487 | GNS at the same time; however, if you only use this method, you will only | ||
| 1488 | get one root zone per machine (not so great for multi-user systems). | ||
| 1489 | @end table | ||
| 1490 | |||
| 1491 | You can combine system-wide DNS packet interception with the nsswitch | ||
| 1492 | plugin. | ||
| 1493 | The setup of the system-wide DNS interception is described here. All of | ||
| 1494 | the other GNS-specific configuration steps are described in the following | ||
| 1495 | sections. | ||
| 1496 | |||
| 1497 | @node Configuring the GNS nsswitch plugin | ||
| 1498 | @subsubsection Configuring the GNS nsswitch plugin | ||
| 1499 | |||
| 1500 | The Name Service Switch (NSS) is a facility in Unix-like operating systems | ||
| 1501 | (in most cases provided by the GNU C Library) | ||
| 1502 | that provides a variety of sources for common configuration databases and | ||
| 1503 | name resolution mechanisms. | ||
| 1504 | A superuser (system administrator) usually configures the | ||
| 1505 | operating system's name services using the file | ||
| 1506 | @file{/etc/nsswitch.conf}. | ||
| 1507 | |||
| 1508 | GNS provides a NSS plugin to integrate GNS name resolution with the | ||
| 1509 | operating system's name resolution process. | ||
| 1510 | To use the GNS NSS plugin you have to either | ||
| 1511 | |||
| 1512 | @itemize @bullet | ||
| 1513 | @item install GNUnet as root or | ||
| 1514 | @item compile GNUnet with the @code{--with-sudo=yes} switch. | ||
| 1515 | @end itemize | ||
| 1516 | |||
| 1517 | Name resolution is controlled by the @emph{hosts} section in the NSS | ||
| 1518 | configuration. By default this section first performs a lookup in the | ||
| 1519 | @file{/etc/hosts} file and then in DNS. | ||
| 1520 | The nsswitch file should contain a line similar to: | ||
| 1521 | |||
| 1522 | @example | ||
| 1523 | hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4 | ||
| 1524 | @end example | ||
| 1525 | |||
| 1526 | @noindent | ||
| 1527 | Here the GNS NSS plugin can be added to perform a GNS lookup before | ||
| 1528 | performing a DNS lookup. | ||
| 1529 | The GNS NSS plugin has to be added to the "hosts" section in | ||
| 1530 | @file{/etc/nsswitch.conf} file before DNS related plugins: | ||
| 1531 | |||
| 1532 | @example | ||
| 1533 | ... | ||
| 1534 | hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4 | ||
| 1535 | ... | ||
| 1536 | @end example | ||
| 1537 | |||
| 1538 | @noindent | ||
| 1539 | The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not | ||
| 1540 | found in GNS it will not be queried in DNS. | ||
| 1541 | |||
| 1542 | @node Configuring GNS on W32 | ||
| 1543 | @subsubsection Configuring GNS on W32 | ||
| 1544 | |||
| 1545 | This document is a guide to configuring GNU Name System on W32-compatible | ||
| 1546 | platforms. | ||
| 1547 | |||
| 1548 | After GNUnet is installed, run the w32nsp-install tool: | ||
| 1549 | |||
| 1550 | @example | ||
| 1551 | w32nsp-install.exe libw32nsp-0.dll | ||
| 1552 | @end example | ||
| 1553 | |||
| 1554 | @noindent | ||
| 1555 | ('0' is the library version of W32 NSP; it might increase in the future, | ||
| 1556 | change the invocation accordingly). | ||
| 1557 | |||
| 1558 | This will install GNS namespace provider into the system and allow other | ||
| 1559 | applications to resolve names that end in '@strong{gnu}' | ||
| 1560 | and '@strong{zkey}'. Note that namespace provider requires | ||
| 1561 | gnunet-gns-helper-service-w32 to be running, as well as gns service | ||
| 1562 | itself (and its usual dependencies). | ||
| 1563 | |||
| 1564 | Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353}, | ||
| 1565 | and this is where gnunet-gns-helper-service-w32 should be listening to | ||
| 1566 | (and is configured to listen to by default). | ||
| 1567 | |||
| 1568 | To uninstall the provider, run: | ||
| 1569 | |||
| 1570 | @example | ||
| 1571 | w32nsp-uninstall.exe | ||
| 1572 | @end example | ||
| 1573 | |||
| 1574 | @noindent | ||
| 1575 | (uses provider GUID to uninstall it, does not need a dll name). | ||
| 1576 | |||
| 1577 | Note that while MSDN claims that other applications will only be able to | ||
| 1578 | use the new namespace provider after re-starting, in reality they might | ||
| 1579 | stat to use it without that. Conversely, they might stop using the | ||
| 1580 | provider after it's been uninstalled, even if they were not re-started. | ||
| 1581 | W32 will not permit namespace provider library to be deleted or | ||
| 1582 | overwritten while the provider is installed, and while there is at least | ||
| 1583 | one process still using it (even after it was uninstalled). | ||
| 1584 | |||
| 1585 | @node GNS Proxy Setup | ||
| 1586 | @subsubsection GNS Proxy Setup | ||
| 1587 | |||
| 1588 | When using the GNU Name System (GNS) to browse the WWW, there are several | ||
| 1589 | issues that can be solved by adding the GNS Proxy to your setup: | ||
| 1590 | |||
| 1591 | @itemize @bullet | ||
| 1592 | |||
| 1593 | @item If the target website does not support GNS, it might assume that it | ||
| 1594 | is operating under some name in the legacy DNS system (such as | ||
| 1595 | example.com). It may then attempt to set cookies for that domain, and the | ||
| 1596 | web server might expect a @code{Host: example.com} header in the request | ||
| 1597 | from your browser. | ||
| 1598 | However, your browser might be using @code{example.gnu} for the | ||
| 1599 | @code{Host} header and might only accept (and send) cookies for | ||
| 1600 | @code{example.gnu}. The GNS Proxy will perform the necessary translations | ||
| 1601 | of the hostnames for cookies and HTTP headers (using the LEHO record for | ||
| 1602 | the target domain as the desired substitute). | ||
| 1603 | |||
| 1604 | @item If using HTTPS, the target site might include an SSL certificate | ||
| 1605 | which is either only valid for the LEHO domain or might match a TLSA | ||
| 1606 | record in GNS. However, your browser would expect a valid certificate for | ||
| 1607 | @code{example.gnu}, not for some legacy domain name. The proxy will | ||
| 1608 | validate the certificate (either against LEHO or TLSA) and then | ||
| 1609 | on-the-fly produce a valid certificate for the exchange, signed by your | ||
| 1610 | own CA. Assuming you installed the CA of your proxy in your browser's | ||
| 1611 | certificate authority list, your browser will then trust the | ||
| 1612 | HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy. | ||
| 1613 | |||
| 1614 | @item Finally, the proxy will in the future indicate to the server that it | ||
| 1615 | speaks GNS, which will enable server operators to deliver GNS-enabled web | ||
| 1616 | sites to your browser (and continue to deliver legacy links to legacy | ||
| 1617 | browsers) | ||
| 1618 | @end itemize | ||
| 1619 | |||
| 1620 | @node Setup of the GNS CA | ||
| 1621 | @subsubsection Setup of the GNS CA | ||
| 1622 | |||
| 1623 | First you need to create a CA certificate that the proxy can use. | ||
| 1624 | To do so use the provided script gnunet-gns-proxy-ca: | ||
| 1625 | |||
| 1626 | @example | ||
| 1627 | $ gnunet-gns-proxy-setup-ca | ||
| 1628 | @end example | ||
| 1629 | |||
| 1630 | @noindent | ||
| 1631 | This will create a personal certification authority for you and add this | ||
| 1632 | authority to the firefox and chrome database. The proxy will use the this | ||
| 1633 | CA certificate to generate @code{*.gnu} client certificates on the fly. | ||
| 1634 | |||
| 1635 | Note that the proxy uses libcurl. Make sure your version of libcurl uses | ||
| 1636 | GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled | ||
| 1637 | against OpenSSL. | ||
| 1638 | |||
| 1639 | You can check the configuration your libcurl was build with by | ||
| 1640 | running: | ||
| 1641 | |||
| 1642 | @example | ||
| 1643 | curl --version | ||
| 1644 | @end example | ||
| 1645 | |||
| 1646 | the output will look like this (without the linebreaks): | ||
| 1647 | |||
| 1648 | @example | ||
| 1649 | gnurl --version | ||
| 1650 | curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \ | ||
| 1651 | GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4 | ||
| 1652 | Release-Date: 2017-10-08 | ||
| 1653 | Protocols: http https | ||
| 1654 | Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \ | ||
| 1655 | TLS-SRP UnixSockets HTTPS-proxy | ||
| 1656 | @end example | ||
| 1657 | |||
| 1658 | @node Testing the GNS setup | ||
| 1659 | @subsubsection Testing the GNS setup | ||
| 1660 | |||
| 1661 | Now for testing purposes we can create some records in our zone to test | ||
| 1662 | the SSL functionality of the proxy: | ||
| 1663 | |||
| 1664 | @example | ||
| 1665 | $ gnunet-identity -C test | ||
| 1666 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ | ||
| 1667 | -t A -V 131.159.74.67 -z test | ||
| 1668 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ | ||
| 1669 | -t LEHO -V "gnunet.org" -z test | ||
| 1670 | @end example | ||
| 1671 | |||
| 1672 | @noindent | ||
| 1673 | At this point we can start the proxy. Simply execute | ||
| 1674 | |||
| 1675 | @example | ||
| 1676 | $ gnunet-gns-proxy | ||
| 1677 | @end example | ||
| 1678 | |||
| 1679 | @noindent | ||
| 1680 | Configure your browser to use this SOCKSv5 proxy on port 7777 and visit | ||
| 1681 | this link. | ||
| 1682 | If you use @command{Firefox} (or one of its derivatives/forks such as | ||
| 1683 | Icecat) you also have to go to @code{about:config} and set the key | ||
| 1684 | @code{network.proxy.socks_remote_dns} to @code{true}. | ||
| 1685 | |||
| 1686 | When you visit @code{https://homepage.test/}, you should get to the | ||
| 1687 | @code{https://gnunet.org/} frontpage and the browser (with the correctly | ||
| 1688 | configured proxy) should give you a valid SSL certificate for | ||
| 1689 | @code{homepage.gnu} and no warnings. It should look like this: | ||
| 1690 | |||
| 1691 | @c FIXME: Image does not exist, create it or save it from Drupal? | ||
| 1692 | @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} | ||
| 1693 | |||
| 1694 | |||
| 1695 | @node Configuring the GNUnet VPN | ||
| 1696 | @subsection Configuring the GNUnet VPN | ||
| 1697 | |||
| 1698 | @menu | ||
| 1699 | * IPv4 address for interface:: | ||
| 1700 | * IPv6 address for interface:: | ||
| 1701 | * Configuring the GNUnet VPN DNS:: | ||
| 1702 | * Configuring the GNUnet VPN Exit Service:: | ||
| 1703 | * IP Address of external DNS resolver:: | ||
| 1704 | * IPv4 address for Exit interface:: | ||
| 1705 | * IPv6 address for Exit interface:: | ||
| 1706 | @end menu | ||
| 1707 | |||
| 1708 | Before configuring the GNUnet VPN, please make sure that system-wide DNS | ||
| 1709 | interception is configured properly as described in the section on the | ||
| 1710 | GNUnet DNS setup. @pxref{Configuring the GNU Name System}, | ||
| 1711 | if you haven't done so already. | ||
| 1712 | |||
| 1713 | The default options for the GNUnet VPN are usually sufficient to use | ||
| 1714 | GNUnet as a Layer 2 for your Internet connection. | ||
| 1715 | However, what you always have to specify is which IP protocol you want | ||
| 1716 | to tunnel: IPv4, IPv6 or both. | ||
| 1717 | Furthermore, if you tunnel both, you most likely should also tunnel | ||
| 1718 | all of your DNS requests. | ||
| 1719 | You theoretically can tunnel "only" your DNS traffic, but that usually | ||
| 1720 | makes little sense. | ||
| 1721 | |||
| 1722 | The other options as shown on the gnunet-setup tool are: | ||
| 1723 | |||
| 1724 | @node IPv4 address for interface | ||
| 1725 | @subsubsection IPv4 address for interface | ||
| 1726 | |||
| 1727 | This is the IPv4 address the VPN interface will get. You should pick an | ||
| 1728 | 'private' IPv4 network that is not yet in use for you system. For example, | ||
| 1729 | if you use @code{10.0.0.1/255.255.0.0} already, you might use | ||
| 1730 | @code{10.1.0.1/255.255.0.0}. | ||
| 1731 | If you use @code{10.0.0.1/255.0.0.0} already, then you might use | ||
| 1732 | @code{192.168.0.1/255.255.0.0}. | ||
| 1733 | If your system is not in a private IP-network, using any of the above will | ||
| 1734 | work fine. | ||
| 1735 | You should try to make the mask of the address big enough | ||
| 1736 | (@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more | ||
| 1737 | mappings of remote IP Addresses into this range. | ||
| 1738 | However, even a @code{255.255.255.0} mask will suffice for most users. | ||
| 1739 | |||
| 1740 | @node IPv6 address for interface | ||
| 1741 | @subsubsection IPv6 address for interface | ||
| 1742 | |||
| 1743 | The IPv6 address the VPN interface will get. Here you can specify any | ||
| 1744 | non-link-local address (the address should not begin with @code{fe80:}). | ||
| 1745 | A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are | ||
| 1746 | currently not using would be a good choice. | ||
| 1747 | |||
| 1748 | @node Configuring the GNUnet VPN DNS | ||
| 1749 | @subsubsection Configuring the GNUnet VPN DNS | ||
| 1750 | |||
| 1751 | To resolve names for remote nodes, activate the DNS exit option. | ||
| 1752 | |||
| 1753 | @node Configuring the GNUnet VPN Exit Service | ||
| 1754 | @subsubsection Configuring the GNUnet VPN Exit Service | ||
| 1755 | |||
| 1756 | If you want to allow other users to share your Internet connection (yes, | ||
| 1757 | this may be dangerous, just as running a Tor exit node) or want to | ||
| 1758 | provide access to services on your host (this should be less dangerous, | ||
| 1759 | as long as those services are secure), you have to enable the GNUnet exit | ||
| 1760 | daemon. | ||
| 1761 | |||
| 1762 | You then get to specify which exit functions you want to provide. By | ||
| 1763 | enabling the exit daemon, you will always automatically provide exit | ||
| 1764 | functions for manually configured local services (this component of the | ||
| 1765 | system is under | ||
| 1766 | development and not documented further at this time). As for those | ||
| 1767 | services you explicitly specify the target IP address and port, there is | ||
| 1768 | no significant security risk in doing so. | ||
| 1769 | |||
| 1770 | Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet. | ||
| 1771 | Being a DNS exit is usually pretty harmless. However, enabling IPv4 or | ||
| 1772 | IPv6-exit without further precautions may enable adversaries to access | ||
| 1773 | your local network, send spam, attack other systems from your Internet | ||
| 1774 | connection and to other mischief that will appear to come from your | ||
| 1775 | machine. This may or may not get you into legal trouble. | ||
| 1776 | If you want to allow IPv4 or IPv6-exit functionality, you should strongly | ||
| 1777 | consider adding additional firewall rules manually to protect your local | ||
| 1778 | network and to restrict outgoing TCP traffic (i.e. by not allowing access | ||
| 1779 | to port 25). While we plan to improve exit-filtering in the future, | ||
| 1780 | you're currently on your own here. | ||
| 1781 | Essentially, be prepared for any kind of IP-traffic to exit the respective | ||
| 1782 | TUN interface (and GNUnet will enable IP-forwarding and NAT for the | ||
| 1783 | interface automatically). | ||
| 1784 | |||
| 1785 | Additional configuration options of the exit as shown by the gnunet-setup | ||
| 1786 | tool are: | ||
| 1787 | |||
| 1788 | @node IP Address of external DNS resolver | ||
| 1789 | @subsubsection IP Address of external DNS resolver | ||
| 1790 | |||
| 1791 | If DNS traffic is to exit your machine, it will be send to this DNS | ||
| 1792 | resolver. You can specify an IPv4 or IPv6 address. | ||
| 1793 | |||
| 1794 | @node IPv4 address for Exit interface | ||
| 1795 | @subsubsection IPv4 address for Exit interface | ||
| 1796 | |||
| 1797 | This is the IPv4 address the Interface will get. Make the mask of the | ||
| 1798 | address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more | ||
| 1799 | mappings of IP addresses into this range. As for the VPN interface, any | ||
| 1800 | unused, private IPv4 address range will do. | ||
| 1801 | |||
| 1802 | @node IPv6 address for Exit interface | ||
| 1803 | @subsubsection IPv6 address for Exit interface | ||
| 1804 | |||
| 1805 | The public IPv6 address the interface will get. If your kernel is not a | ||
| 1806 | very recent kernel and you are willing to manually enable IPv6-NAT, the | ||
| 1807 | IPv6 address you specify here must be a globally routed IPv6 address of | ||
| 1808 | your host. | ||
| 1809 | |||
| 1810 | Suppose your host has the address @code{2001:4ca0::1234/64}, then | ||
| 1811 | using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits, | ||
| 1812 | then change at least one bit in the range before the bitmask, in the | ||
| 1813 | example above we changed bit 111 from 0 to 1). | ||
| 1814 | |||
| 1815 | You may also have to configure your router to route traffic for the entire | ||
| 1816 | subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this | ||
| 1817 | should be automatic with IPv6, but obviously anything can be | ||
| 1818 | disabled). | ||
| 1819 | |||
| 1820 | @node Bandwidth Configuration | ||
| 1821 | @subsection Bandwidth Configuration | ||
| 1822 | |||
| 1823 | You can specify how many bandwidth GNUnet is allowed to use to receive | ||
| 1824 | and send data. This is important for users with limited bandwidth or | ||
| 1825 | traffic volume. | ||
| 1826 | |||
| 1827 | @node Configuring NAT | ||
| 1828 | @subsection Configuring NAT | ||
| 1829 | |||
| 1830 | Most hosts today do not have a normal global IP address but instead are | ||
| 1831 | behind a router performing Network Address Translation (NAT) which assigns | ||
| 1832 | each host in the local network a private IP address. | ||
| 1833 | As a result, these machines cannot trivially receive inbound connections | ||
| 1834 | from the Internet. GNUnet supports NAT traversal to enable these machines | ||
| 1835 | to receive incoming connections from other peers despite their | ||
| 1836 | limitations. | ||
| 1837 | |||
| 1838 | In an ideal world, you can press the "Attempt automatic configuration" | ||
| 1839 | button in gnunet-setup to automatically configure your peer correctly. | ||
| 1840 | Alternatively, your distribution might have already triggered this | ||
| 1841 | automatic configuration during the installation process. | ||
| 1842 | However, automatic configuration can fail to determine the optimal | ||
| 1843 | settings, resulting in your peer either not receiving as many connections | ||
| 1844 | as possible, or in the worst case it not connecting to the network at all. | ||
| 1845 | |||
| 1846 | To manually configure the peer, you need to know a few things about your | ||
| 1847 | network setup. First, determine if you are behind a NAT in the first | ||
| 1848 | place. | ||
| 1849 | This is always the case if your IP address starts with "10.*" or | ||
| 1850 | "192.168.*". Next, if you have control over your NAT router, you may | ||
| 1851 | choose to manually configure it to allow GNUnet traffic to your host. | ||
| 1852 | If you have configured your NAT to forward traffic on ports 2086 (and | ||
| 1853 | possibly 1080) to your host, you can check the "NAT ports have been opened | ||
| 1854 | manually" option, which corresponds to the "PUNCHED_NAT" option in the | ||
| 1855 | configuration file. If you did not punch your NAT box, it may still be | ||
| 1856 | configured to support UPnP, which allows GNUnet to automatically | ||
| 1857 | configure it. In that case, you need to install the "upnpc" command, | ||
| 1858 | enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal | ||
| 1859 | via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the | ||
| 1860 | configuration file). | ||
| 1861 | |||
| 1862 | Some NAT boxes can be traversed using the autonomous NAT traversal method. | ||
| 1863 | This requires certain GNUnet components to be installed with "SUID" | ||
| 1864 | privileges on your system (so if you're installing on a system you do | ||
| 1865 | not have administrative rights to, this will not work). | ||
| 1866 | If you installed as 'root', you can enable autonomous NAT traversal by | ||
| 1867 | checking the "Enable NAT traversal using ICMP method". | ||
| 1868 | The ICMP method requires a way to determine your NAT's external (global) | ||
| 1869 | IP address. This can be done using either UPnP, DynDNS, or by manual | ||
| 1870 | configuration. If you have a DynDNS name or know your external IP address, | ||
| 1871 | you should enter that name under "External (public) IPv4 address" (which | ||
| 1872 | corresponds to the "EXTERNAL_ADDRESS" option in the configuration file). | ||
| 1873 | If you leave the option empty, GNUnet will try to determine your external | ||
| 1874 | IP address automatically (which may fail, in which case autonomous | ||
| 1875 | NAT traversal will then not work). | ||
| 1876 | |||
| 1877 | Finally, if you yourself are not behind NAT but want to be able to | ||
| 1878 | connect to NATed peers using autonomous NAT traversal, you need to check | ||
| 1879 | the "Enable connecting to NATed peers using ICMP method" box. | ||
| 1880 | |||
| 1881 | |||
| 1882 | @node Peer configuration for distributions | ||
| 1883 | @subsection Peer configuration for distributions | ||
| 1884 | |||
| 1885 | The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be | ||
| 1886 | manually set to "/var/lib/gnunet/data/" as the default | ||
| 1887 | "~/.local/share/gnunet/" is probably not that appropriate in this case. | ||
| 1888 | Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to | ||
| 1889 | "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a | ||
| 1890 | distribution decide to override system defaults, all of these changes | ||
| 1891 | should be done in a custom @file{/etc/gnunet.conf} and not in the files | ||
| 1892 | in the @file{config.d/} directory. | ||
| 1893 | |||
| 1894 | Given the proposed access permissions, the "gnunet-setup" tool must be | ||
| 1895 | run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it | ||
| 1896 | modifies the system configuration). As always, gnunet-setup should be run | ||
| 1897 | after the GNUnet peer was stopped using "gnunet-arm -e". Distributions | ||
| 1898 | might want to include a wrapper for gnunet-setup that allows the | ||
| 1899 | desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account | ||
| 1900 | and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in | ||
| 1901 | sequence. | ||
| 1902 | |||
| 1903 | @node MOVED FROM USER Config Leftovers | ||
| 1904 | @section MOVED FROM USER Config Leftovers | ||
| 1905 | |||
| 1906 | This section describes how to start a GNUnet peer. It assumes that you | ||
| 1907 | have already compiled and installed GNUnet and its' dependencies. | ||
| 1908 | Before you start a GNUnet peer, you may want to create a configuration | ||
| 1909 | file using gnunet-setup (but you do not have to). | ||
| 1910 | Sane defaults should exist in your | ||
| 1911 | @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice | ||
| 1912 | you could simply start without any configuration. If you want to | ||
| 1913 | configure your peer later, you need to stop it before invoking the | ||
| 1914 | @code{gnunet-setup} tool to customize further and to test your | ||
| 1915 | configuration (@code{gnunet-setup} has build-in test functions). | ||
| 1916 | |||
| 1917 | The most important option you might have to still set by hand is in | ||
| 1918 | [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where | ||
| 1919 | GNUnet should store its data. | ||
| 1920 | It defaults to @code{$HOME/}, which again should work for most users. | ||
| 1921 | Make sure that the directory specified as GNUNET_HOME is writable to | ||
| 1922 | the user that you will use to run GNUnet (note that you can run frontends | ||
| 1923 | using other users, GNUNET_HOME must only be accessible to the user used to | ||
| 1924 | run the background processes). | ||
| 1925 | |||
| 1926 | You will also need to make one central decision: should all of GNUnet be | ||
| 1927 | run under your normal UID, or do you want distinguish between system-wide | ||
| 1928 | (user-independent) GNUnet services and personal GNUnet services. The | ||
| 1929 | multi-user setup is slightly more complicated, but also more secure and | ||
| 1930 | generally recommended. | ||
| 1931 | |||
| 1932 | @menu | ||
| 1933 | * The Single-User Setup:: | ||
| 1934 | * The Multi-User Setup:: | ||
| 1935 | * Killing GNUnet services:: | ||
| 1936 | * Access Control for GNUnet:: | ||
| 1937 | @end menu | ||
| 1938 | |||
| 1939 | @node The Single-User Setup | ||
| 1940 | @subsection The Single-User Setup | ||
| 1941 | |||
| 1942 | For the single-user setup, you do not need to do anything special and can | ||
| 1943 | just start the GNUnet background processes using @code{gnunet-arm}. | ||
| 1944 | By default, GNUnet looks in @file{~/.config/gnunet.conf} for a | ||
| 1945 | configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@ | ||
| 1946 | @code{$XDG_CONFIG_HOME} is defined). If your configuration lives | ||
| 1947 | elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet | ||
| 1948 | commands. | ||
| 1949 | |||
| 1950 | Assuming the configuration file is called @file{~/.config/gnunet.conf}, | ||
| 1951 | you start your peer using the @code{gnunet-arm} command (say as user | ||
| 1952 | @code{gnunet}) using: | ||
| 1953 | |||
| 1954 | @example | ||
| 1955 | gnunet-arm -c ~/.config/gnunet.conf -s | ||
| 1956 | @end example | ||
| 1957 | |||
| 1958 | @noindent | ||
| 1959 | The "-s" option here is for "start". The command should return almost | ||
| 1960 | instantly. If you want to stop GNUnet, you can use: | ||
| 1961 | |||
| 1962 | @example | ||
| 1963 | gnunet-arm -c ~/.config/gnunet.conf -e | ||
| 1964 | @end example | ||
| 1965 | |||
| 1966 | @noindent | ||
| 1967 | The "-e" option here is for "end". | ||
| 1968 | |||
| 1969 | Note that this will only start the basic peer, no actual applications | ||
| 1970 | will be available. | ||
| 1971 | If you want to start the file-sharing service, use (after starting | ||
| 1972 | GNUnet): | ||
| 1973 | |||
| 1974 | @example | ||
| 1975 | gnunet-arm -c ~/.config/gnunet.conf -i fs | ||
| 1976 | @end example | ||
| 1977 | |||
| 1978 | @noindent | ||
| 1979 | The "-i fs" option here is for "initialize" the "fs" (file-sharing) | ||
| 1980 | application. You can also selectively kill only file-sharing support using | ||
| 1981 | |||
| 1982 | @example | ||
| 1983 | gnunet-arm -c ~/.config/gnunet.conf -k fs | ||
| 1984 | @end example | ||
| 1985 | |||
| 1986 | @noindent | ||
| 1987 | Assuming that you want certain services (like file-sharing) to be always | ||
| 1988 | automatically started whenever you start GNUnet, you can activate them by | ||
| 1989 | setting "IMMEDIATE_START=YES" in the respective section of the configuration | ||
| 1990 | file (for example, "[fs]"). Then GNUnet with file-sharing support would | ||
| 1991 | be started whenever you@ enter: | ||
| 1992 | |||
| 1993 | @example | ||
| 1994 | gnunet-arm -c ~/.config/gnunet.conf -s | ||
| 1995 | @end example | ||
| 1996 | |||
| 1997 | @noindent | ||
| 1998 | Alternatively, you can combine the two options: | ||
| 1999 | |||
| 2000 | @example | ||
| 2001 | gnunet-arm -c ~/.config/gnunet.conf -s -i fs | ||
| 2002 | @end example | ||
| 2003 | |||
| 2004 | @noindent | ||
| 2005 | Using @code{gnunet-arm} is also the preferred method for initializing | ||
| 2006 | GNUnet from @code{init}. | ||
| 2007 | |||
| 2008 | Finally, you should edit your @code{crontab} (using the @code{crontab} | ||
| 2009 | command) and insert a line@ | ||
| 2010 | |||
| 2011 | @example | ||
| 2012 | @@reboot gnunet-arm -c ~/.config/gnunet.conf -s | ||
| 2013 | @end example | ||
| 2014 | |||
| 2015 | to automatically start your peer whenever your system boots. | ||
| 2016 | |||
| 2017 | @node The Multi-User Setup | ||
| 2018 | @subsection The Multi-User Setup | ||
| 2019 | |||
| 2020 | This requires you to create a user @code{gnunet} and an additional group | ||
| 2021 | @code{gnunetdns}, prior to running @code{make install} during | ||
| 2022 | installation. | ||
| 2023 | Then, you create a configuration file @file{/etc/gnunet.conf} which should | ||
| 2024 | contain the lines:@ | ||
| 2025 | |||
| 2026 | @example | ||
| 2027 | [arm] | ||
| 2028 | START_SYSTEM_SERVICES = YES | ||
| 2029 | START_USER_SERVICES = NO | ||
| 2030 | @end example | ||
| 2031 | |||
| 2032 | @noindent | ||
| 2033 | Then, perform the same steps to run GNUnet as in the per-user | ||
| 2034 | configuration, except as user @code{gnunet} (including the | ||
| 2035 | @code{crontab} installation). | ||
| 2036 | You may also want to run @code{gnunet-setup} to configure your peer | ||
| 2037 | (databases, etc.). | ||
| 2038 | Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you | ||
| 2039 | run @code{gnunet-setup} as user @code{gnunet}, you might need to change | ||
| 2040 | permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can | ||
| 2041 | write to the file (during setup). | ||
| 2042 | |||
| 2043 | Afterwards, you need to perform another setup step for each normal user | ||
| 2044 | account from which you want to access GNUnet. First, grant the normal user | ||
| 2045 | (@code{$USER}) permission to the group gnunet: | ||
| 2046 | |||
| 2047 | @example | ||
| 2048 | # adduser $USER gnunet | ||
| 2049 | @end example | ||
| 2050 | |||
| 2051 | @noindent | ||
| 2052 | Then, create a configuration file in @file{~/.config/gnunet.conf} for the | ||
| 2053 | $USER with the lines: | ||
| 2054 | |||
| 2055 | @example | ||
| 2056 | [arm] | ||
| 2057 | START_SYSTEM_SERVICES = NO | ||
| 2058 | START_USER_SERVICES = YES | ||
| 2059 | @end example | ||
| 2060 | |||
| 2061 | @noindent | ||
| 2062 | This will ensure that @code{gnunet-arm} when started by the normal user | ||
| 2063 | will only run services that are per-user, and otherwise rely on the | ||
| 2064 | system-wide services. | ||
| 2065 | Note that the normal user may run gnunet-setup, but the | ||
| 2066 | configuration would be ineffective as the system-wide services will use | ||
| 2067 | @file{/etc/gnunet.conf} and ignore options set by individual users. | ||
| 2068 | |||
| 2069 | Again, each user should then start the peer using | ||
| 2070 | @file{gnunet-arm -s} --- and strongly consider adding logic to start | ||
| 2071 | the peer automatically to their crontab. | ||
| 2072 | |||
| 2073 | Afterwards, you should see two (or more, if you have more than one USER) | ||
| 2074 | @code{gnunet-service-arm} processes running in your system. | ||
| 2075 | |||
| 2076 | @node Killing GNUnet services | ||
| 2077 | @subsection Killing GNUnet services | ||
| 2078 | |||
| 2079 | It is not necessary to stop GNUnet services explicitly when shutting | ||
| 2080 | down your computer. | ||
| 2081 | |||
| 2082 | It should be noted that manually killing "most" of the | ||
| 2083 | @code{gnunet-service} processes is generally not a successful method for | ||
| 2084 | stopping a peer (since @code{gnunet-service-arm} will instantly restart | ||
| 2085 | them). The best way to explicitly stop a peer is using | ||
| 2086 | @code{gnunet-arm -e}; note that the per-user services may need to be | ||
| 2087 | terminated before the system-wide services will terminate normally. | ||
| 2088 | |||
| 2089 | @node Access Control for GNUnet | ||
| 2090 | @subsection Access Control for GNUnet | ||
| 2091 | |||
| 2092 | This chapter documents how we plan to make access control work within the | ||
| 2093 | GNUnet system for a typical peer. It should be read as a best-practice | ||
| 2094 | installation guide for advanced users and builders of binary | ||
| 2095 | distributions. The recommendations in this guide apply to POSIX-systems | ||
| 2096 | with full support for UNIX domain sockets only. | ||
| 2097 | |||
| 2098 | Note that this is an advanced topic. The discussion presumes a very good | ||
| 2099 | understanding of users, groups and file permissions. Normal users on | ||
| 2100 | hosts with just a single user can just install GNUnet under their own | ||
| 2101 | account (and possibly allow the installer to use SUDO to grant additional | ||
| 2102 | permissions for special GNUnet tools that need additional rights). | ||
| 2103 | The discussion below largely applies to installations where multiple users | ||
| 2104 | share a system and to installations where the best possible security is | ||
| 2105 | paramount. | ||
| 2106 | |||
| 2107 | A typical GNUnet system consists of components that fall into four | ||
| 2108 | categories: | ||
| 2109 | |||
| 2110 | @table @asis | ||
| 2111 | |||
| 2112 | @item User interfaces | ||
| 2113 | User interfaces are not security sensitive and are supposed to be run and | ||
| 2114 | used by normal system users. | ||
| 2115 | The GTK GUIs and most command-line programs fall into this category. | ||
| 2116 | Some command-line tools (like gnunet-transport) should be excluded as they | ||
| 2117 | offer low-level access that normal users should not need. | ||
| 2118 | @item System services and support tools | ||
| 2119 | System services should always run and offer services that can then be | ||
| 2120 | accessed by the normal users. | ||
| 2121 | System services do not require special permissions, but as they are not | ||
| 2122 | specific to a particular user, they probably should not run as a | ||
| 2123 | particular user. Also, there should typically only be one GNUnet peer per | ||
| 2124 | host. System services include the gnunet-service and gnunet-daemon | ||
| 2125 | programs; support tools include command-line programs such as gnunet-arm. | ||
| 2126 | @item Privileged helpers | ||
| 2127 | Some GNUnet components require root rights to open raw sockets or perform | ||
| 2128 | other special operations. These gnunet-helper binaries are typically | ||
| 2129 | installed SUID and run from services or daemons. | ||
| 2130 | @item Critical services | ||
| 2131 | Some GNUnet services (such as the DNS service) can manipulate the service | ||
| 2132 | in deep and possibly highly security sensitive ways. For example, the DNS | ||
| 2133 | service can be used to intercept and alter any DNS query originating from | ||
| 2134 | the local machine. Access to the APIs of these critical services and their | ||
| 2135 | privileged helpers must be tightly controlled. | ||
| 2136 | @end table | ||
| 2137 | |||
| 2138 | @c FIXME: The titles of these chapters are too long in the index. | ||
| 2139 | |||
| 2140 | @menu | ||
| 2141 | * Recommendation - Disable access to services via TCP:: | ||
| 2142 | * Recommendation - Run most services as system user "gnunet":: | ||
| 2143 | * Recommendation - Control access to services using group "gnunet":: | ||
| 2144 | * Recommendation - Limit access to certain SUID binaries by group "gnunet":: | ||
| 2145 | * Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns":: | ||
| 2146 | * Differences between "make install" and these recommendations:: | ||
| 2147 | @end menu | ||
| 2148 | |||
| 2149 | @node Recommendation - Disable access to services via TCP | ||
| 2150 | @subsubsection Recommendation - Disable access to services via TCP | ||
| 2151 | |||
| 2152 | GNUnet services allow two types of access: via TCP socket or via UNIX | ||
| 2153 | domain socket. | ||
| 2154 | If the service is available via TCP, access control can only be | ||
| 2155 | implemented by restricting connections to a particular range of IP | ||
| 2156 | addresses. | ||
| 2157 | This is acceptable for non-critical services that are supposed to be | ||
| 2158 | available to all users on the local system or local network. | ||
| 2159 | However, as TCP is generally less efficient and it is rarely the case | ||
| 2160 | that a single GNUnet peer is supposed to serve an entire local network, | ||
| 2161 | the default configuration should disable TCP access to all GNUnet | ||
| 2162 | services on systems with support for UNIX domain sockets. | ||
| 2163 | As of GNUnet 0.9.2, configuration files with TCP access disabled should be | ||
| 2164 | generated by default. Users can re-enable TCP access to particular | ||
| 2165 | services simply by specifying a non-zero port number in the section of | ||
| 2166 | the respective service. | ||
| 2167 | |||
| 2168 | |||
| 2169 | @node Recommendation - Run most services as system user "gnunet" | ||
| 2170 | @subsubsection Recommendation - Run most services as system user "gnunet" | ||
| 2171 | |||
| 2172 | GNUnet's main services should be run as a separate user "gnunet" in a | ||
| 2173 | special group "gnunet". | ||
| 2174 | The user "gnunet" should start the peer using "gnunet-arm -s" during | ||
| 2175 | system startup. The home directory for this user should be | ||
| 2176 | @file{/var/lib/gnunet} and the configuration file should be | ||
| 2177 | @file{/etc/gnunet.conf}. | ||
| 2178 | Only the @code{gnunet} user should have the right to access | ||
| 2179 | @file{/var/lib/gnunet} (@emph{mode: 700}). | ||
| 2180 | |||
| 2181 | @node Recommendation - Control access to services using group "gnunet" | ||
| 2182 | @subsubsection Recommendation - Control access to services using group "gnunet" | ||
| 2183 | |||
| 2184 | Users that should be allowed to use the GNUnet peer should be added to the | ||
| 2185 | group "gnunet". Using GNUnet's access control mechanism for UNIX domain | ||
| 2186 | sockets, those services that are considered useful to ordinary users | ||
| 2187 | should be made available by setting "UNIX_MATCH_GID=YES" for those | ||
| 2188 | services. | ||
| 2189 | Again, as shipped, GNUnet provides reasonable defaults. | ||
| 2190 | Permissions to access the transport and core subsystems might additionally | ||
| 2191 | be granted without necessarily causing security concerns. | ||
| 2192 | Some services, such as DNS, must NOT be made accessible to the "gnunet" | ||
| 2193 | group (and should thus only be accessible to the "gnunet" user and | ||
| 2194 | services running with this UID). | ||
| 2195 | |||
| 2196 | @node Recommendation - Limit access to certain SUID binaries by group "gnunet" | ||
| 2197 | @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet" | ||
| 2198 | |||
| 2199 | Most of GNUnet's SUID binaries should be safe even if executed by normal | ||
| 2200 | users. However, it is possible to reduce the risk a little bit more by | ||
| 2201 | making these binaries owned by the group "gnunet" and restricting their | ||
| 2202 | execution to user of the group "gnunet" as well (4750). | ||
| 2203 | |||
| 2204 | @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | ||
| 2205 | @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | ||
| 2206 | |||
| 2207 | A special group "gnunetdns" should be created for controlling access to | ||
| 2208 | the "gnunet-helper-dns". | ||
| 2209 | The binary should then be owned by root and be in group "gnunetdns" and | ||
| 2210 | be installed SUID and only be group-executable (2750). | ||
| 2211 | @b{Note that the group "gnunetdns" should have no users in it at all, | ||
| 2212 | ever.} | ||
| 2213 | The "gnunet-service-dns" program should be executed by user "gnunet" (via | ||
| 2214 | gnunet-service-arm) with the binary owned by the user "root" and the group | ||
| 2215 | "gnunetdns" and be SGID (2700). This way, @strong{only} | ||
| 2216 | "gnunet-service-dns" can change its group to "gnunetdns" and execute the | ||
| 2217 | helper, and the helper can then run as root (as per SUID). | ||
| 2218 | Access to the API offered by "gnunet-service-dns" is in turn restricted | ||
| 2219 | to the user "gnunet" (not the group!), which means that only | ||
| 2220 | "benign" services can manipulate DNS queries using "gnunet-service-dns". | ||
| 2221 | |||
| 2222 | @node Differences between "make install" and these recommendations | ||
| 2223 | @subsubsection Differences between "make install" and these recommendations | ||
| 2224 | |||
| 2225 | The current build system does not set all permissions automatically based | ||
| 2226 | on the recommendations above. In particular, it does not use the group | ||
| 2227 | "gnunet" at all (so setting gnunet-helpers other than the | ||
| 2228 | gnunet-helper-dns to be owned by group "gnunet" must be done manually). | ||
| 2229 | Furthermore, 'make install' will silently fail to set the DNS binaries to | ||
| 2230 | be owned by group "gnunetdns" unless that group already exists (!). | ||
| 2231 | An alternative name for the "gnunetdns" group can be specified using the | ||
| 2232 | @code{--with-gnunetdns=GRPNAME} configure option. | ||
| 2233 | |||
diff --git a/doc/documentation/chapters/keyconcepts.texi b/doc/documentation/chapters/keyconcepts.texi deleted file mode 100644 index b4a60024c..000000000 --- a/doc/documentation/chapters/keyconcepts.texi +++ /dev/null | |||
| @@ -1,317 +0,0 @@ | |||
| 1 | |||
| 2 | @cindex Key Concepts | ||
| 3 | @node Key Concepts | ||
| 4 | @chapter Key Concepts | ||
| 5 | |||
| 6 | In this section, the fundamental concepts of GNUnet are explained. | ||
| 7 | @c FIXME: Use @uref{https://docs.gnunet.org/bib/, research papers} | ||
| 8 | @c once we have the new bibliography + subdomain setup. | ||
| 9 | Most of them are also described in our research papers. | ||
| 10 | First, some of the concepts used in the GNUnet framework are detailed. | ||
| 11 | The second part describes concepts specific to anonymous file-sharing. | ||
| 12 | |||
| 13 | @menu | ||
| 14 | * Authentication:: | ||
| 15 | * Accounting to Encourage Resource Sharing:: | ||
| 16 | * Confidentiality:: | ||
| 17 | * Anonymity:: | ||
| 18 | * Deniability:: | ||
| 19 | * Peer Identities:: | ||
| 20 | * Zones in the GNU Name System (GNS Zones):: | ||
| 21 | * Egos:: | ||
| 22 | @end menu | ||
| 23 | |||
| 24 | @cindex Authentication | ||
| 25 | @node Authentication | ||
| 26 | @section Authentication | ||
| 27 | |||
| 28 | Almost all peer-to-peer communications in GNUnet are between mutually | ||
| 29 | authenticated peers. The authentication works by using ECDHE, that is a | ||
| 30 | DH (Diffie---Hellman) key exchange using ephemeral elliptic curve | ||
| 31 | cryptography. The ephemeral ECC (Elliptic Curve Cryptography) keys are | ||
| 32 | signed using ECDSA (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}). | ||
| 33 | The shared secret from ECDHE is used to create a pair of session keys | ||
| 34 | @c FIXME: Long word for HKDF. More FIXMEs: Explain MITM etc. | ||
| 35 | (using HKDF) which are then used to encrypt the communication between the | ||
| 36 | two peers using both 256-bit AES (Advanced Encryption Standard) | ||
| 37 | and 256-bit Twofish (with independently derived secret keys). | ||
| 38 | As only the two participating hosts know the shared secret, this | ||
| 39 | authenticates each packet | ||
| 40 | without requiring signatures each time. GNUnet uses SHA-512 | ||
| 41 | (Secure Hash Algorithm) hash codes to verify the integrity of messages. | ||
| 42 | |||
| 43 | @c FIXME: A while back I got the feedback that I should try and integrate | ||
| 44 | @c explanation boxes in the long-run. So we could explain | ||
| 45 | @c "man-in-the-middle" and "man-in-the-middle attacks" and other words | ||
| 46 | @c which are not common knowledge. MITM is not common knowledge. To be | ||
| 47 | @c selfcontained, we should be able to explain words and concepts used in | ||
| 48 | @c a chapter or paragraph without hinting at Wikipedia and other online | ||
| 49 | @c sources which might not be available or accessible to everyone. | ||
| 50 | @c On the other hand we could write an introductionary chapter or book | ||
| 51 | @c that we could then reference in each chapter, which sound like it | ||
| 52 | @c could be more reusable. | ||
| 53 | In GNUnet, the identity of a host is its public key. For that reason, | ||
| 54 | man-in-the-middle attacks will not break the authentication or accounting | ||
| 55 | goals. Essentially, for GNUnet, the IP of the host has nothing to do with | ||
| 56 | the identity of the host. As the public key is the only thing that truly | ||
| 57 | matters, faking an IP, a port or any other property of the underlying | ||
| 58 | transport protocol is irrelevant. In fact, GNUnet peers can use | ||
| 59 | multiple IPs (IPv4 and IPv6) on multiple ports --- or even not use the | ||
| 60 | IP protocol at all (by running directly on layer 2). | ||
| 61 | @c FIXME: "IP protocol" feels wrong, but could be what people expect, as | ||
| 62 | @c IP is "the number" and "IP protocol" the protocol itself in general | ||
| 63 | @c knowledge? | ||
| 64 | |||
| 65 | @c NOTE: For consistency we will use @code{HELLO}s throughout this Manual. | ||
| 66 | GNUnet uses a special type of message to communicate a binding between | ||
| 67 | public (ECC) keys to their current network address. These messages are | ||
| 68 | commonly called @code{HELLO}s or @code{peer advertisements}. | ||
| 69 | They contain the public key of the peer and its current network | ||
| 70 | addresses for various transport services. | ||
| 71 | A transport service is a special kind of shared library that | ||
| 72 | provides (possibly unreliable, out-of-order) message delivery between | ||
| 73 | peers. | ||
| 74 | For the UDP and TCP transport services, a network address is an IP and a | ||
| 75 | port. | ||
| 76 | GNUnet can also use other transports (HTTP, HTTPS, WLAN, etc.) which use | ||
| 77 | various other forms of addresses. Note that any node can have many | ||
| 78 | different active transport services at the same time, | ||
| 79 | and each of these can have a different addresses. | ||
| 80 | Binding messages expire after at most a week (the timeout can be | ||
| 81 | shorter if the user configures the node appropriately). | ||
| 82 | This expiration ensures that the network will eventually get rid of | ||
| 83 | outdated advertisements. | ||
| 84 | |||
| 85 | For more information, refer to the following paper: | ||
| 86 | |||
| 87 | Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth. | ||
| 88 | A Transport Layer Abstraction for Peer-to-Peer Networks | ||
| 89 | Proceedings of the 3rd International Symposium on Cluster Computing | ||
| 90 | and the Grid (GRID 2003), 2003. | ||
| 91 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf, https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf}) | ||
| 92 | |||
| 93 | @cindex Accounting to Encourage Resource Sharing | ||
| 94 | @node Accounting to Encourage Resource Sharing | ||
| 95 | @section Accounting to Encourage Resource Sharing | ||
| 96 | |||
| 97 | Most distributed P2P networks suffer from a lack of defenses or | ||
| 98 | precautions against attacks in the form of freeloading. | ||
| 99 | While the intentions of an attacker and a freeloader are different, their | ||
| 100 | effect on the network is the same; they both render it useless. | ||
| 101 | Most simple attacks on networks such as @command{Gnutella} | ||
| 102 | involve flooding the network with traffic, particularly | ||
| 103 | with queries that are, in the worst case, multiplied by the network. | ||
| 104 | |||
| 105 | In order to ensure that freeloaders or attackers have a minimal impact | ||
| 106 | on the network, GNUnet's file-sharing implementation (@code{FS} tries | ||
| 107 | to distinguish good (contributing) nodes from malicious (freeloading) | ||
| 108 | nodes. In GNUnet, every file-sharing node keeps track of the behavior | ||
| 109 | of every other node it has been in contact with. Many requests | ||
| 110 | (depending on the application) are transmitted with a priority (or | ||
| 111 | importance) level. That priority is used to establish how important | ||
| 112 | the sender believes this request is. If a peer responds to an | ||
| 113 | important request, the recipient will increase its trust in the | ||
| 114 | responder: the responder contributed resources. If a peer is too busy | ||
| 115 | to answer all requests, it needs to prioritize. For that, peers do | ||
| 116 | not take the priorities of the requests received at face value. | ||
| 117 | First, they check how much they trust the sender, and depending on | ||
| 118 | that amount of trust they assign the request a (possibly lower) | ||
| 119 | effective priority. Then, they drop the requests with the lowest | ||
| 120 | effective priority to satisfy their resource constraints. This way, | ||
| 121 | GNUnet's economic model ensures that nodes that are not currently | ||
| 122 | considered to have a surplus in contributions will not be served if | ||
| 123 | the network load is high. | ||
| 124 | |||
| 125 | For more information, refer to the following paper: | ||
| 126 | Christian Grothoff. An Excess-Based Economic Model for Resource | ||
| 127 | Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003. | ||
| 128 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf}) | ||
| 129 | |||
| 130 | @cindex Confidentiality | ||
| 131 | @node Confidentiality | ||
| 132 | @section Confidentiality | ||
| 133 | |||
| 134 | Adversaries (malicious, bad actors) outside of GNUnet are not supposed | ||
| 135 | to know what kind of actions a peer is involved in. Only the specific | ||
| 136 | neighbor of a peer that is the corresponding sender or recipient of a | ||
| 137 | message may know its contents, and even then application protocols may | ||
| 138 | place further restrictions on that knowledge. In order to ensure | ||
| 139 | confidentiality, GNUnet uses link encryption, that is each message | ||
| 140 | exchanged between two peers is encrypted using a pair of keys only | ||
| 141 | known to these two peers. Encrypting traffic like this makes any kind | ||
| 142 | of traffic analysis much harder. Naturally, for some applications, it | ||
| 143 | may still be desirable if even neighbors cannot determine the concrete | ||
| 144 | contents of a message. In GNUnet, this problem is addressed by the | ||
| 145 | specific application-level protocols. See for example the following | ||
| 146 | sections @pxref{Anonymity}, @pxref{How file-sharing achieves Anonymity}, | ||
| 147 | and @pxref{Deniability}. | ||
| 148 | |||
| 149 | @cindex Anonymity | ||
| 150 | @node Anonymity | ||
| 151 | @section Anonymity | ||
| 152 | |||
| 153 | @menu | ||
| 154 | * How file-sharing achieves Anonymity:: | ||
| 155 | @end menu | ||
| 156 | |||
| 157 | Providing anonymity for users is the central goal for the anonymous | ||
| 158 | file-sharing application. Many other design decisions follow in the | ||
| 159 | footsteps of this requirement. | ||
| 160 | Anonymity is never absolute. While there are various | ||
| 161 | scientific metrics | ||
| 162 | (Claudia Díaz, Stefaan Seys, Joris Claessens, | ||
| 163 | and Bart Preneel. Towards measuring anonymity. | ||
| 164 | 2002. | ||
| 165 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf, https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf})) | ||
| 166 | that can help quantify the level of anonymity that a given mechanism | ||
| 167 | provides, there is no such thing as "complete anonymity". | ||
| 168 | GNUnet's file-sharing implementation allows users to select for each | ||
| 169 | operation (publish, search, download) the desired level of anonymity. | ||
| 170 | The metric used is the amount of cover traffic available to hide the | ||
| 171 | request. | ||
| 172 | While this metric is not as good as, for example, the theoretical metric | ||
| 173 | given in scientific metrics, | ||
| 174 | it is probably the best metric available to a peer with a purely local | ||
| 175 | view of the world that does not rely on unreliable external information. | ||
| 176 | The default anonymity level is @code{1}, which uses anonymous routing but | ||
| 177 | imposes no minimal requirements on cover traffic. It is possible | ||
| 178 | to forego anonymity when this is not required. The anonymity level of | ||
| 179 | @code{0} allows GNUnet to use more efficient, non-anonymous routing. | ||
| 180 | |||
| 181 | @cindex How file-sharing achieves Anonymity | ||
| 182 | @node How file-sharing achieves Anonymity | ||
| 183 | @subsection How file-sharing achieves Anonymity | ||
| 184 | |||
| 185 | Contrary to other designs, we do not believe that users achieve strong | ||
| 186 | anonymity just because their requests are obfuscated by a couple of | ||
| 187 | indirections. This is not sufficient if the adversary uses traffic | ||
| 188 | analysis. | ||
| 189 | The threat model used for anonymous file sharing in GNUnet assumes that | ||
| 190 | the adversary is quite powerful. | ||
| 191 | In particular, we assume that the adversary can see all the traffic on | ||
| 192 | the Internet. And while we assume that the adversary | ||
| 193 | can not break our encryption, we assume that the adversary has many | ||
| 194 | participating nodes in the network and that it can thus see many of the | ||
| 195 | node-to-node interactions since it controls some of the nodes. | ||
| 196 | |||
| 197 | The system tries to achieve anonymity based on the idea that users can be | ||
| 198 | anonymous if they can hide their actions in the traffic created by other | ||
| 199 | users. | ||
| 200 | Hiding actions in the traffic of other users requires participating in the | ||
| 201 | traffic, bringing back the traditional technique of using indirection and | ||
| 202 | source rewriting. Source rewriting is required to gain anonymity since | ||
| 203 | otherwise an adversary could tell if a message originated from a host by | ||
| 204 | looking at the source address. If all packets look like they originate | ||
| 205 | from one node, the adversary can not tell which ones originate from that | ||
| 206 | node and which ones were routed. | ||
| 207 | Note that in this mindset, any node can decide to break the | ||
| 208 | source-rewriting paradigm without violating the protocol, as this | ||
| 209 | only reduces the amount of traffic that a node can hide its own traffic | ||
| 210 | in. | ||
| 211 | |||
| 212 | If we want to hide our actions in the traffic of other nodes, we must make | ||
| 213 | our traffic indistinguishable from the traffic that we route for others. | ||
| 214 | As our queries must have us as the receiver of the reply | ||
| 215 | (otherwise they would be useless), we must put ourselves as the receiver | ||
| 216 | of replies that actually go to other hosts; in other words, we must | ||
| 217 | indirect replies. | ||
| 218 | Unlike other systems, in anonymous file-sharing as implemented on top of | ||
| 219 | GNUnet we do not have to indirect the replies if we don't think we need | ||
| 220 | more traffic to hide our own actions. | ||
| 221 | |||
| 222 | This increases the efficiency of the network as we can indirect less under | ||
| 223 | higher load. | ||
| 224 | Refer to the following paper for more: | ||
| 225 | Krista Bennett and Christian Grothoff. | ||
| 226 | GAP --- practical anonymous networking. In Proceedings of | ||
| 227 | Designing Privacy Enhancing Technologies, 2003. | ||
| 228 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf, https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf}) | ||
| 229 | |||
| 230 | @cindex Deniability | ||
| 231 | @node Deniability | ||
| 232 | @section Deniability | ||
| 233 | |||
| 234 | Even if the user that downloads data and the server that provides data are | ||
| 235 | anonymous, the intermediaries may still be targets. In particular, if the | ||
| 236 | intermediaries can find out which queries or which content they are | ||
| 237 | processing, a strong adversary could try to force them to censor | ||
| 238 | certain materials. | ||
| 239 | |||
| 240 | With the file-encoding used by GNUnet's anonymous file-sharing, this | ||
| 241 | problem does not arise. | ||
| 242 | The reason is that queries and replies are transmitted in | ||
| 243 | an encrypted format such that intermediaries cannot tell what the query | ||
| 244 | is for or what the content is about. Mind that this is not the same | ||
| 245 | encryption as the link-encryption between the nodes. GNUnet has | ||
| 246 | encryption on the network layer (link encryption, confidentiality, | ||
| 247 | authentication) and again on the application layer (provided | ||
| 248 | by @command{gnunet-publish}, @command{gnunet-download}, | ||
| 249 | @command{gnunet-search} and @command{gnunet-gtk}). | ||
| 250 | |||
| 251 | Refer to the following paper for more: | ||
| 252 | Christian Grothoff, Krista Grothoff, Tzvetan Horozov, | ||
| 253 | and Jussi T. Lindgren. | ||
| 254 | An Encoding for Censorship-Resistant Sharing. | ||
| 255 | 2009. | ||
| 256 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf}) | ||
| 257 | |||
| 258 | @cindex Peer Identities | ||
| 259 | @node Peer Identities | ||
| 260 | @section Peer Identities | ||
| 261 | |||
| 262 | Peer identities are used to identify peers in the network and are unique | ||
| 263 | for each peer. The identity for a peer is simply its public key, which is | ||
| 264 | generated along with a private key the peer is started for the first time. | ||
| 265 | While the identity is binary data, it is often expressed as ASCII string. | ||
| 266 | For example, the following is a peer identity as you might see it in | ||
| 267 | various places: | ||
| 268 | |||
| 269 | @example | ||
| 270 | UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0 | ||
| 271 | @end example | ||
| 272 | |||
| 273 | @noindent | ||
| 274 | You can find your peer identity by running @command{gnunet-peerinfo -s}. | ||
| 275 | |||
| 276 | @cindex Zones in the GNU Name System (GNS Zones) | ||
| 277 | @node Zones in the GNU Name System (GNS Zones) | ||
| 278 | @section Zones in the GNU Name System (GNS Zones) | ||
| 279 | |||
| 280 | @c FIXME: Explain or link to an explanation of the concept of public keys | ||
| 281 | @c and private keys. | ||
| 282 | @c FIXME: Rewrite for the latest GNS changes. | ||
| 283 | GNS (Matthias Wachs, Martin Schanzenbach, and Christian Grothoff. | ||
| 284 | A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name | ||
| 285 | System. In proceedings of 13th International Conference on Cryptology and | ||
| 286 | Network Security (CANS 2014). 2014. | ||
| 287 | @uref{https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf}) | ||
| 288 | zones are similar to those of DNS zones, but instead of a hierarchy of | ||
| 289 | authorities to governing their use, GNS zones are controlled by a private | ||
| 290 | key. | ||
| 291 | When you create a record in a DNS zone, that information is stored in your | ||
| 292 | nameserver. Anyone trying to resolve your domain then gets pointed | ||
| 293 | (hopefully) by the centralised authority to your nameserver. | ||
| 294 | Whereas GNS, being fully decentralized by design, stores that information | ||
| 295 | in DHT. The validity of the records is assured cryptographically, by | ||
| 296 | signing them with the private key of the respective zone. | ||
| 297 | |||
| 298 | Anyone trying to resolve records in a zone of your domain can then verify | ||
| 299 | the signature of the records they get from the DHT and be assured that | ||
| 300 | they are indeed from the respective zone. | ||
| 301 | To make this work, there is a 1:1 correspondence between zones and | ||
| 302 | their public-private key pairs. | ||
| 303 | So when we talk about the owner of a GNS zone, that's really the owner of | ||
| 304 | the private key. | ||
| 305 | And a user accessing a zone needs to somehow specify the corresponding | ||
| 306 | public key first. | ||
| 307 | |||
| 308 | @cindex Egos | ||
| 309 | @node Egos | ||
| 310 | @section Egos | ||
| 311 | |||
| 312 | @c what is the difference between peer identity and egos? It seems | ||
| 313 | @c like both are linked to public-private key pair. | ||
| 314 | Egos are your "identities" in GNUnet. Any user can assume multiple | ||
| 315 | identities, for example to separate their activities online. Egos can | ||
| 316 | correspond to "pseudonyms" or "real-world identities". Technically an | ||
| 317 | ego is first of all a key pair of a public- and private-key. | ||
diff --git a/doc/documentation/chapters/philosophy.texi b/doc/documentation/chapters/philosophy.texi deleted file mode 100644 index e57c20914..000000000 --- a/doc/documentation/chapters/philosophy.texi +++ /dev/null | |||
| @@ -1,81 +0,0 @@ | |||
| 1 | @cindex Philosophy | ||
| 2 | @node Philosophy | ||
| 3 | @chapter Philosophy | ||
| 4 | |||
| 5 | @c NOTE: We should probably re-use some of the images lynX created | ||
| 6 | @c for secushare, showing some of the relations and functionalities | ||
| 7 | @c of GNUnet. | ||
| 8 | The primary goal of the GNUnet project is to provide a reliable, open, | ||
| 9 | non-discriminating and censorship-resistant system for information | ||
| 10 | exchange. We value free speech above state interests and intellectual | ||
| 11 | monopoly. GNUnet's long-term goal is to serve as a development | ||
| 12 | platform for the next generation of Internet protocols. | ||
| 13 | |||
| 14 | GNUnet is an anarchistic network. Participants are encouraged to | ||
| 15 | contribute at least as much resources (storage, bandwidth) to the network | ||
| 16 | as they consume, so that their participation does not have a negative | ||
| 17 | impact on other users. | ||
| 18 | |||
| 19 | @menu | ||
| 20 | * Design Principles:: | ||
| 21 | * Privacy and Anonymity:: | ||
| 22 | * Practicality:: | ||
| 23 | @end menu | ||
| 24 | |||
| 25 | @cindex Design Principles | ||
| 26 | @node Design Principles | ||
| 27 | @section Design Principles | ||
| 28 | |||
| 29 | These are the GNUnet design principles, in order of importance: | ||
| 30 | |||
| 31 | @itemize | ||
| 32 | @item GNUnet must be implemented as | ||
| 33 | @uref{https://www.gnu.org/philosophy/free-sw.html, Free Software} --- | ||
| 34 | This means that you you have the four essential freedoms: to run | ||
| 35 | the program, to study and change the program in source code form, | ||
| 36 | to redistribute exact copies, and to distribute modified versions. | ||
| 37 | (@uref{https://www.gnu.org/philosophy/free-sw.html}). | ||
| 38 | @item GNUnet must minimize the amount of personally identifiable information exposed. | ||
| 39 | @item GNUnet must be fully distributed and resilient to external attacks and rogue participants. | ||
| 40 | @item GNUnet must be self-organizing and not depend on administrators or centralized infrastructure. | ||
| 41 | @item GNUnet must inform the user which other participants have to be trusted when establishing private communications. | ||
| 42 | @item GNUnet must be open and permit new peers to join. | ||
| 43 | @item GNUnet must support a diverse range of applications and devices. | ||
| 44 | @item GNUnet must use compartmentalization to protect sensitive information. | ||
| 45 | @item The GNUnet architecture must be resource efficient. | ||
| 46 | @item GNUnet must provide incentives for peers to contribute more resources than they consume. | ||
| 47 | @end itemize | ||
| 48 | |||
| 49 | |||
| 50 | @cindex Privacy and Anonymity | ||
| 51 | @node Privacy and Anonymity | ||
| 52 | @section Privacy and Anonymity | ||
| 53 | |||
| 54 | The GNUnet protocols minimize the leakage of personally identifiable | ||
| 55 | information of participants and do not allow adversaries to control, | ||
| 56 | track, monitor or censor users activities. The GNUnet protocols also | ||
| 57 | make it as hard as possible to disrupt operations by participating in | ||
| 58 | the network with malicious intent. | ||
| 59 | |||
| 60 | Analyzing participant's activities becomes more difficult as the | ||
| 61 | number of peers and applications that generate traffic on the network | ||
| 62 | grows, even if the additional traffic generated is not related to | ||
| 63 | anonymous communication. This is one of the reasons why GNUnet is | ||
| 64 | developed as a peer-to-peer framework where many applications share | ||
| 65 | the lower layers of an increasingly complex protocol stack. The GNUnet | ||
| 66 | architecture encourages many different forms of peer-to-peer | ||
| 67 | applications. | ||
| 68 | |||
| 69 | @cindex Practicality | ||
| 70 | @node Practicality | ||
| 71 | @section Practicality | ||
| 72 | |||
| 73 | Whereever possible GNUnet allows the peer to adjust its operations and | ||
| 74 | functionalities to specific use cases. A GNUnet peer running on a | ||
| 75 | mobile device with limited battery for example might choose not to | ||
| 76 | relay traffic for other participants. | ||
| 77 | |||
| 78 | For certain applications like file-sharing GNUnet allows participants | ||
| 79 | to trade degrees of anonymity in exchange for increased | ||
| 80 | efficiency. However, it is not possible for any user's efficiency | ||
| 81 | requirements to compromise the anonymity of any other user. | ||
diff --git a/doc/documentation/chapters/preface.texi b/doc/documentation/chapters/preface.texi deleted file mode 100644 index 386cefa6d..000000000 --- a/doc/documentation/chapters/preface.texi +++ /dev/null | |||
| @@ -1,173 +0,0 @@ | |||
| 1 | @node Preface | ||
| 2 | @chapter Preface | ||
| 3 | |||
| 4 | This collection of manuals describes how to use GNUnet, a framework | ||
| 5 | for secure peer-to-peer networking with the high-level goal to provide | ||
| 6 | a strong foundation Free Software for a global, distributed network | ||
| 7 | that provides security and privacy. GNUnet in that sense aims to | ||
| 8 | replace the current Internet protocol stack. Along with an | ||
| 9 | application for secure publication of files, it has grown to include | ||
| 10 | all kinds of basic applications for the foundation of a new Internet. | ||
| 11 | |||
| 12 | @menu | ||
| 13 | * About this book:: | ||
| 14 | * Contributing to this book:: | ||
| 15 | * Introduction:: | ||
| 16 | * Project governance:: | ||
| 17 | * Typography:: | ||
| 18 | @end menu | ||
| 19 | |||
| 20 | @node About this book | ||
| 21 | @section About this book | ||
| 22 | |||
| 23 | The books (described as ``book'' or ``books'' in the following) | ||
| 24 | bundled as the ``GNUnet Reference Manual'' are based on the historic | ||
| 25 | work of all contributors to GNUnet's documentation. It is our hope | ||
| 26 | that the content is described in a way that does not require any | ||
| 27 | academic background, although some concepts will require further | ||
| 28 | reading. | ||
| 29 | |||
| 30 | Our (long-term) goal with these books is to keep them self-contained. If | ||
| 31 | you see references to Wikipedia and other external sources (except for | ||
| 32 | our academic papers) it means that we are working on a solution to | ||
| 33 | describe the explanations found there which fits our use-case and licensing. | ||
| 34 | |||
| 35 | The first chapter (``Preface'') as well as the the second | ||
| 36 | chapter (``Philosophy'') give an introduction to GNUnet as a project, | ||
| 37 | what GNUnet tries to achieve. | ||
| 38 | |||
| 39 | @node Contributing to this book | ||
| 40 | @section Contributing to this book | ||
| 41 | |||
| 42 | The GNUnet Reference Manual is a collective work produced by various | ||
| 43 | people throughout the years. The version you are reading is derived | ||
| 44 | from many individual efforts hosted on our website. This was a failed | ||
| 45 | experiment, and with the conversion to Texinfo we hope to address this | ||
| 46 | in the longterm. Texinfo is the documentation language of the GNU project. | ||
| 47 | While it can be intimidating at first and look scary or complicated, | ||
| 48 | it is just another way to express text format instructions. We encourage | ||
| 49 | you to take this opportunity and learn about Texinfo, learn about GNUnet, | ||
| 50 | and one word at a time we will arrive at a book which explains GNUnet in | ||
| 51 | the least complicated way to you. Even when you don't want or can't learn | ||
| 52 | Texinfo, you can contribute. Send us an Email or join our IRC chat room | ||
| 53 | on freenode and talk with us about the documentation (the prefered way | ||
| 54 | to reach out is the mailinglist, since you can communicate with us | ||
| 55 | without waiting on someone in the chatroom). One way or another you | ||
| 56 | can help shape the understanding of GNUnet without the ability to read | ||
| 57 | and understand its sourcecode. | ||
| 58 | |||
| 59 | @node Introduction | ||
| 60 | @section Introduction | ||
| 61 | |||
| 62 | @c In less than 2 printed pages describe the history of GNUnet here, | ||
| 63 | @c what we have now and what's still missing (could be split into | ||
| 64 | @c subchapters). | ||
| 65 | |||
| 66 | GNUnet in its current version is the result of almost 20 years of work | ||
| 67 | from many contributors. So far, most contributions were made by | ||
| 68 | volunteers or people paid to do fundamental research. At this stage, | ||
| 69 | GNUnet remains an experimental system where | ||
| 70 | significant parts of the software lack a reasonable degree of | ||
| 71 | professionalism in its implementation. Furthermore, we are aware of a | ||
| 72 | significant number of existing bugs and critical design flaws, as some | ||
| 73 | unfortunate early design decisions remain to be rectified. There are | ||
| 74 | still known open problems; GNUnet remains an active research project. | ||
| 75 | |||
| 76 | The project was started in 2001 when some initial ideas for improving | ||
| 77 | Freenet's file-sharing turned out to be too radical to be easily | ||
| 78 | realized within the scope of the existing Freenet project. We lost | ||
| 79 | our first contributor on 11.9.2001 as the contributor realized that | ||
| 80 | privacy may help terrorists. The rest of the team concluded that it | ||
| 81 | was now even more important to fight for civil liberties. The first | ||
| 82 | release was called ``GNet'' -- already with the name GNUnet in mind, | ||
| 83 | but without the blessing of GNU we did not dare to call it GNUnet | ||
| 84 | immediately. A few months after the first release we contacted the | ||
| 85 | GNU project, happily agreed to their governance model and became an | ||
| 86 | official GNU package. | ||
| 87 | |||
| 88 | Within the first year, we created | ||
| 89 | @uref{https://gnu.org/s/libextractor, GNU libextractor}, a helper library | ||
| 90 | for meta data extraction which has been used by a few other projects | ||
| 91 | as well. 2003 saw the emergence of pluggable transports, the ability | ||
| 92 | for GNUnet to use different mechanisms for communication, starting | ||
| 93 | with TCP, UDP and SMTP (support for the latter was later dropped due | ||
| 94 | to a lack of maintenance). In 2005, the project first started to | ||
| 95 | evolve beyond the original file-sharing application with a first | ||
| 96 | simple P2P chat. In 2007, we created | ||
| 97 | @uref{https://gnu.org/s/libmicrohttpd, GNU libmicrohttpd} | ||
| 98 | to support a pluggable transport based on HTTP. In 2009, the | ||
| 99 | architecture was radically modularized into the multi-process system | ||
| 100 | that exists today. Coincidentally, the first version of the ARM | ||
| 101 | service (ARM: Automatic Restart Manager) | ||
| 102 | was implemented a day before systemd was announced. From 2009 | ||
| 103 | to 2014 work progressed rapidly thanks to a significant research grant | ||
| 104 | from the Deutsche Forschungsgesellschaft. This resulted in particular | ||
| 105 | in the creation of the R5N DHT, CADET, ATS and the GNU Name System. | ||
| 106 | In 2010, GNUnet was selected as the basis for the | ||
| 107 | @uref{https://secushare.org, secushare} online | ||
| 108 | social network, resulting in a significant growth of the core team. | ||
| 109 | In 2013, we launched @uref{https://taler.net, GNU Taler} to address | ||
| 110 | the challenge of convenient | ||
| 111 | and privacy-preserving online payments. In 2015, the | ||
| 112 | @c TODO: Maybe even markup for the E if it renders in most outputs. | ||
| 113 | @uref{https://pep.foundation/, pEp} (pretty Easy privacy) project | ||
| 114 | announced that they will use GNUnet as the technology for their | ||
| 115 | meta-data protection layer, ultimately resulting in GNUnet e.V. | ||
| 116 | entering into a formal long-term collaboration with the pEp | ||
| 117 | foundation. In 2016, Taler Systems SA, a first startup using GNUnet | ||
| 118 | technology, was founded with support from the community. | ||
| 119 | |||
| 120 | GNUnet is not merely a technical project, but also a political | ||
| 121 | mission: like the GNU project as a whole, we are writing software to | ||
| 122 | achieve political goals with a focus on the human right of | ||
| 123 | informational self-determination. Putting users in control of their | ||
| 124 | computing has been the core driver of the GNU project. With GNUnet we | ||
| 125 | are focusing on informational self-determination for collaborative | ||
| 126 | computing and communication over networks. | ||
| 127 | |||
| 128 | The Internet is shaped as much by code and protocols as it is by its | ||
| 129 | associated political processes (IETF, ICANN, IEEE, etc.). | ||
| 130 | Similarly its flaws are not limited to the protocol design. Thus, | ||
| 131 | technical excellence by itself will not suffice to create a better | ||
| 132 | network. We also need to build a community that is wise, humble and | ||
| 133 | has a sense of humor to achieve our goal to create a technical | ||
| 134 | foundation for a society we would like to live in. | ||
| 135 | |||
| 136 | |||
| 137 | @node Project governance | ||
| 138 | @section Project governance | ||
| 139 | |||
| 140 | GNUnet, like the GNU project and many other free software projects, | ||
| 141 | follows the governance model of a benevolent dictator. This means | ||
| 142 | that ultimately, the GNU project appoints the GNU maintainer and can | ||
| 143 | overrule decisions made by the GNUnet maintainer. Similarly, the | ||
| 144 | GNUnet maintainer can overrule any decisions made by individual | ||
| 145 | @c TODO: Should we mention if this is just about GNUnet? Other projects | ||
| 146 | @c TODO: in GNU seem to have rare issues (GCC, the 2018 documentation | ||
| 147 | @c TODO: discussion. | ||
| 148 | developers. Still, in practice neither has happened in the last 20 | ||
| 149 | years, and we hope to keep it that way. | ||
| 150 | |||
| 151 | @c TODO: Actually we are a Swiss association, or just a German association | ||
| 152 | @c TODO: with Swiss bylaws/Satzung? | ||
| 153 | @c TODO: Rewrite one of the 'GNUnet eV may also' sentences. | ||
| 154 | The GNUnet project is supported by GNUnet e.V., a German association | ||
| 155 | where any developer can become a member. GNUnet e.V. serves as a | ||
| 156 | legal entity to hold the copyrights to GNUnet. GNUnet e.V. may also | ||
| 157 | choose to pay for project resources, and can collect donations. | ||
| 158 | GNUnet e.V. may also choose to adjust the license of the | ||
| 159 | software (with the constraint that it has to remain free software). | ||
| 160 | In 2018 we switched from GPL3 to AGPL3, in practice these changes do | ||
| 161 | not happen very often. | ||
| 162 | |||
| 163 | |||
| 164 | @node Typography | ||
| 165 | @section Typography | ||
| 166 | |||
| 167 | When giving examples for commands, shell prompts are used to show if the | ||
| 168 | command should/can be issued as root, or if "normal" user privileges are | ||
| 169 | sufficient. We use a @code{#} for root's shell prompt, a | ||
| 170 | @code{%} for users' shell prompt, assuming they use the C-shell or tcsh | ||
| 171 | and a @code{$} for bourne shell and derivatives. | ||
| 172 | @c TODO: Really? Why the different prompts? Do we already have c-shell | ||
| 173 | @c TODO: examples? | ||
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi deleted file mode 100644 index 5aa3a62bf..000000000 --- a/doc/documentation/chapters/user.texi +++ /dev/null | |||
| @@ -1,2293 +0,0 @@ | |||
| 1 | @node Using GNUnet | ||
| 2 | @chapter Using GNUnet | ||
| 3 | @c %**end of header | ||
| 4 | |||
| 5 | This tutorial is supposed to give a first introduction for 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 | ||
| 10 | with the framework provided by GNUnet. | ||
| 11 | |||
| 12 | In short, this chapter of the ``GNUnet Reference Documentation'' will | ||
| 13 | show you how to use the various peer-to-peer applications of the | ||
| 14 | GNUnet system. | ||
| 15 | As GNUnet evolves, we will add new sections for the various | ||
| 16 | applications that are being created. | ||
| 17 | |||
| 18 | Comments on the content of this chapter, and extensions of it are | ||
| 19 | always welcome. | ||
| 20 | |||
| 21 | |||
| 22 | @menu | ||
| 23 | * Start and stop GNUnet:: | ||
| 24 | * First steps - Using the GNU Name System:: | ||
| 25 | * First steps - Using GNUnet Conversation:: | ||
| 26 | * First steps - Using the GNUnet VPN:: | ||
| 27 | * File-sharing:: | ||
| 28 | * The GNU Name System:: | ||
| 29 | * re@:claim Identity Provider:: | ||
| 30 | * Using the Virtual Public Network:: | ||
| 31 | @end menu | ||
| 32 | |||
| 33 | @node Start and stop GNUnet | ||
| 34 | @section Start and stop GNUnet | ||
| 35 | |||
| 36 | Previous to use any GNUnet-based application, one has to start a node: | ||
| 37 | |||
| 38 | @example | ||
| 39 | $ gnunet-arm -s -l gnunet.log | ||
| 40 | @end example | ||
| 41 | |||
| 42 | To stop GNUnet: | ||
| 43 | |||
| 44 | @example | ||
| 45 | $ gnunet-arm -e | ||
| 46 | @end example | ||
| 47 | |||
| 48 | @node First steps - Using the GNU Name System | ||
| 49 | @section First steps - Using the GNU Name System | ||
| 50 | @c %**end of header | ||
| 51 | |||
| 52 | @menu | ||
| 53 | * Preliminaries:: | ||
| 54 | * Managing Egos:: | ||
| 55 | * The GNS Tab:: | ||
| 56 | * Creating a Record:: | ||
| 57 | * Resolving GNS records:: | ||
| 58 | * Integration with Browsers:: | ||
| 59 | * Creating a Business Card:: | ||
| 60 | * Be Social:: | ||
| 61 | * Backup of Identities and Egos:: | ||
| 62 | * Revocation:: | ||
| 63 | * What's Next?:: | ||
| 64 | @end menu | ||
| 65 | |||
| 66 | @node Preliminaries | ||
| 67 | @subsection Preliminaries | ||
| 68 | @c %**end of header | ||
| 69 | |||
| 70 | ``.pin'' is a default zone which points to a zone managed by gnunet.org. | ||
| 71 | Use @code{gnunet-config -s gns} to view the GNS configuration, including | ||
| 72 | all configured zones that are operated by other users. The respective | ||
| 73 | configuration entry names start with a ``.'', i.e. ``.pin''. | ||
| 74 | |||
| 75 | You can configure any number of top-level domains, and point them to | ||
| 76 | the respective zones of your friends! For this, simply obtain the | ||
| 77 | respective public key (you will learn how below) and extend the | ||
| 78 | configuration: | ||
| 79 | |||
| 80 | @example | ||
| 81 | $ gnunet-config -s gns -n .myfriend -V PUBLIC_KEY | ||
| 82 | @end example | ||
| 83 | |||
| 84 | @node Managing Egos | ||
| 85 | @subsection Managing Egos | ||
| 86 | |||
| 87 | In GNUnet, identity management is about managing egos. Egos can | ||
| 88 | correspond to pseudonyms or real-world identities. If you value your | ||
| 89 | privacy, you are encouraged to use separate egos for separate | ||
| 90 | activities. | ||
| 91 | |||
| 92 | Technically, an ego is first of all a public-private key pair, and | ||
| 93 | thus egos also always correspond to a GNS zone. Egos are managed by | ||
| 94 | the IDENTITY service. Note that this service has nothing to do with | ||
| 95 | the peer identity. The IDENTITY service essentially stores the | ||
| 96 | private keys under human-readable names, and keeps a mapping of which | ||
| 97 | private key should be used for particular important system functions. | ||
| 98 | The existing identities can be listed using the command | ||
| 99 | @command{gnunet-identity -d} | ||
| 100 | |||
| 101 | @example | ||
| 102 | gnu - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50 | ||
| 103 | rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30 | ||
| 104 | @end example | ||
| 105 | |||
| 106 | |||
| 107 | @node The GNS Tab | ||
| 108 | @subsection The GNS Tab | ||
| 109 | @c %**end of header | ||
| 110 | |||
| 111 | Maintaing your zones is through the NAMESTORE service and is discussed | ||
| 112 | here. You can manage your zone using @command{gnunet-identity} and | ||
| 113 | @command{gnunet-namestore}, or most conveniently using | ||
| 114 | @command{gnunet-namestore-gtk}. | ||
| 115 | |||
| 116 | We will use the GTK+ interface in this introduction. Please start | ||
| 117 | @command{gnunet-gkt} and switch to the GNS tab, which is the tab in | ||
| 118 | the middle with the letters "GNS" connected by a graph. | ||
| 119 | |||
| 120 | Next to the ``Add'' button there is a field where you can enter the | ||
| 121 | label (pseudonym in IDENTITY subsystem speak) of a zone you would like | ||
| 122 | to create. Pushing the ``Add'' button will create the zone. | ||
| 123 | Afterwards, you can change the label in the combo box below at any | ||
| 124 | time. The label will be the top-level domain that the GNU Name System | ||
| 125 | will resolve using your zone. For the label, you should pick | ||
| 126 | a name by which you would like to | ||
| 127 | be known by your friends (or colleagues). You should pick a label that | ||
| 128 | is reasonably unique within your social group. Be aware that | ||
| 129 | the label will be published together with every record in that zone. | ||
| 130 | |||
| 131 | Once you have created a first zone, you should see a QR code for the | ||
| 132 | zone on the right. Next to it is a "Copy" button to copy the public | ||
| 133 | key string to the clipboard. You can also save the QR code image to | ||
| 134 | disk. | ||
| 135 | |||
| 136 | Furthermore, you now can see the bottom part of the dialog. The | ||
| 137 | bottom of the window contains the existing entries in the selected zone. | ||
| 138 | |||
| 139 | @node Creating a Record | ||
| 140 | @subsection Creating a Record | ||
| 141 | @c %**end of header | ||
| 142 | |||
| 143 | We will begin by creating a simple record in your master zone. | ||
| 144 | To do this, click on the text "<new name>" in the table. The field is | ||
| 145 | editable, allowing you to enter a fresh label. Labels are restricted | ||
| 146 | to 63 characters and must not contain dots. For now, simply enter | ||
| 147 | "test", then press ENTER to confirm. This will create a new (empty) | ||
| 148 | record group under the label "test". Now click on "<new record>" next | ||
| 149 | to the new label "test". In the drop-down menu, select "A" and push | ||
| 150 | ENTER to confirm. Afterwards, a new dialog will pop up, asking to enter | ||
| 151 | details for the "A" record. | ||
| 152 | |||
| 153 | "A" records are used in the @dfn{Domain Name System} (DNS) to specify | ||
| 154 | IPv4 addresses. An IPv4 address is a number that is used to identify | ||
| 155 | and address a computer on the Internet (version 4). Please enter | ||
| 156 | "217.92.15.146" in the dialog below "Destination IPv4 Address" and | ||
| 157 | select "Record is public". Do not change any of the other options. | ||
| 158 | Note that as you enter a (well-formed) IPv4 address, the "Save" | ||
| 159 | button in the bottom right corner becomes sensitive. In general, buttons | ||
| 160 | in dialogs are often insensitive as long as the contents of the dialog | ||
| 161 | are incorrect. | ||
| 162 | |||
| 163 | Once finished, press the "Save" button. Back in the main dialog, select | ||
| 164 | the tiny triangle left of the "test" label. By doing so, you get to see | ||
| 165 | all of the records under "test". Note that you can right-click a record | ||
| 166 | to edit it later. | ||
| 167 | |||
| 168 | |||
| 169 | @node Resolving GNS records | ||
| 170 | @subsection Resolving GNS records | ||
| 171 | @c %**end of header | ||
| 172 | |||
| 173 | Next, you should try resolving your own GNS records. The method we | ||
| 174 | found to be the most uncomplicated is to do this by explicitly | ||
| 175 | resolving using @code{gnunet-gns}. For this exercise, we will assume | ||
| 176 | that you used the string ``gnu'' for the pseudonym (or label) of your | ||
| 177 | GNS zone. If you used something else, replace ``.gnu'' with your real | ||
| 178 | pseudonym in the examples below. | ||
| 179 | |||
| 180 | In the shell, type: | ||
| 181 | |||
| 182 | @example | ||
| 183 | $ gnunet-gns -u test.gnu # what follows is the reply | ||
| 184 | test.gnu: | ||
| 185 | Got `A' record: 217.92.15.146 | ||
| 186 | @end example | ||
| 187 | |||
| 188 | @noindent | ||
| 189 | That shows that resolution works, once GNS is integrated with | ||
| 190 | the application. | ||
| 191 | |||
| 192 | @node Integration with Browsers | ||
| 193 | @subsection Integration with Browsers | ||
| 194 | @c %**end of header | ||
| 195 | |||
| 196 | While we recommend integrating GNS using the NSS module in the | ||
| 197 | GNU libc Name Service Switch, you can also integrate GNS | ||
| 198 | directly with your browser via the @code{gnunet-gns-proxy}. | ||
| 199 | This method can have the advantage that the proxy can validate | ||
| 200 | TLS/X.509 records and thus strengthen web security; however, the proxy | ||
| 201 | is still a bit brittle, so expect subtle failures. We have had reasonable | ||
| 202 | success with Chromium, and various frustrations with Firefox in this area | ||
| 203 | recently. | ||
| 204 | |||
| 205 | The first step is to start the proxy. As the proxy is (usually) | ||
| 206 | not started by default, this is done as a unprivileged user | ||
| 207 | using @command{gnunet-arm -i gns-proxy}. Use @command{gnunet-arm -I} | ||
| 208 | as a unprivileged user to check that the proxy was actually | ||
| 209 | started. (The most common error for why the proxy may fail to start | ||
| 210 | is that you did not run @command{gnunet-gns-proxy-setup-ca} during | ||
| 211 | installation.) The proxy is a SOCKS5 proxy running (by default) | ||
| 212 | on port 7777. Thus, you need to now configure your browser to use | ||
| 213 | this proxy. With Chromium, you can do this by starting the browser | ||
| 214 | as a unprivileged user using | ||
| 215 | @command{chromium --proxy-server="socks5://localhost:7777"} | ||
| 216 | For @command{Firefox} (or @command{Icecat}), select "Edit-Preferences" | ||
| 217 | in the menu, and then select the "Advanced" tab in the dialog | ||
| 218 | and then "Network": | ||
| 219 | |||
| 220 | Here, select "Settings..." to open the proxy settings dialog. | ||
| 221 | Select "Manual proxy configuration" and enter @code{localhost} | ||
| 222 | with port 7777 under SOCKS Host. Furthermore, set the | ||
| 223 | checkbox ``Proxy DNS when using SOCKS v5'' at the bottom of | ||
| 224 | the dialog. Finally, push "OK". | ||
| 225 | |||
| 226 | You must also go to about:config and change the | ||
| 227 | @code{browser.fixup.alternate.enabled} option to @code{false}, | ||
| 228 | otherwise the browser will autoblunder an address like | ||
| 229 | @code{@uref{http://www.gnu/, www.gnu}} to | ||
| 230 | @code{@uref{http://www.gnu.com/, www.gnu.com}}. If you want | ||
| 231 | to resolve @@ in your own TLDs, you must additionally | ||
| 232 | set @code{browser.fixup.dns_first_use_for_single_words} to @code{true}. | ||
| 233 | |||
| 234 | After configuring your browser, you might want to first confirm that it | ||
| 235 | continues to work as before. (The proxy is still experimental and if you | ||
| 236 | experience "odd" failures with some webpages, you might want to disable | ||
| 237 | it again temporarily.) Next, test if things work by typing | ||
| 238 | "@uref{http://test.gnu/}" into the URL bar of your browser. | ||
| 239 | This currently fails with (my version of) Firefox as Firefox is | ||
| 240 | super-smart and tries to resolve "@uref{http://www.test.gnu/}" instead of | ||
| 241 | "@uref{test.gnu}". Chromium can be convinced to comply if you explicitly | ||
| 242 | include the "http://" prefix --- otherwise a Google search might be | ||
| 243 | attempted, which is not what you want. If successful, you should | ||
| 244 | see a simple website. | ||
| 245 | |||
| 246 | Note that while you can use GNS to access ordinary websites, this is | ||
| 247 | more an experimental feature and not really our primary goal at this | ||
| 248 | time. Still, it is a possible use-case and we welcome help with testing | ||
| 249 | and development. | ||
| 250 | |||
| 251 | @pindex gnunet-bcd | ||
| 252 | @node Creating a Business Card | ||
| 253 | @subsection Creating a Business Card | ||
| 254 | @c FIXME: Which parts of texlive are needed? Some systems offer a modular | ||
| 255 | @c texlive (smaller size). | ||
| 256 | |||
| 257 | Before we can really use GNS, you should create a business card. | ||
| 258 | Note that this requires having @command{LaTeX} installed on your system. | ||
| 259 | If you are using a Debian GNU/Linux based operating system, the | ||
| 260 | following command should install the required components. | ||
| 261 | Keep in mind that this @b{requires 3GB} of downloaded data and possibly | ||
| 262 | @b{even more} when unpacked. On a GNU Guix based system texlive 2017 has | ||
| 263 | returns a DAG size of 5032.4 MiB. | ||
| 264 | @b{We welcome any help in identifying the required components of the | ||
| 265 | TexLive Distribution. This way we could just state the required components | ||
| 266 | without pulling in the full distribution of TexLive.} | ||
| 267 | |||
| 268 | @example | ||
| 269 | apt-get install texlive-full | ||
| 270 | @end example | ||
| 271 | |||
| 272 | @noindent | ||
| 273 | Start creating a business card by clicking the "Copy" button | ||
| 274 | in @command{gnunet-gtk}'s GNS tab. Next, you should start | ||
| 275 | the @command{gnunet-bcd} program (in the terminal, on the command-line). | ||
| 276 | You do not need to pass any options, and please be not surprised if | ||
| 277 | there is no output: | ||
| 278 | |||
| 279 | @example | ||
| 280 | $ gnunet-bcd # seems to hang... | ||
| 281 | @end example | ||
| 282 | |||
| 283 | @noindent | ||
| 284 | Then, start a browser and point it to @uref{http://localhost:8888/} | ||
| 285 | where @code{gnunet-bcd} is running a Web server! | ||
| 286 | |||
| 287 | First, you might want to fill in the "GNS Public Key" field by | ||
| 288 | right-clicking and selecting "Paste", filling in the public key | ||
| 289 | from the copy you made in @command{gnunet-gtk}. | ||
| 290 | Then, fill in all of the other fields, including your @b{GNS NICKname}. | ||
| 291 | Adding a GPG fingerprint is optional. | ||
| 292 | Once finished, click "Submit Query". | ||
| 293 | If your @code{LaTeX} installation is incomplete, the result will be | ||
| 294 | disappointing. | ||
| 295 | Otherwise, you should get a PDF containing fancy 5x2 double-sided | ||
| 296 | translated business cards with a QR code containing your public key | ||
| 297 | and a GNUnet logo. | ||
| 298 | We'll explain how to use those a bit later. | ||
| 299 | You can now go back to the shell running @code{gnunet-bcd} and press | ||
| 300 | @b{CTRL-C} to shut down the Web server. | ||
| 301 | |||
| 302 | |||
| 303 | @node Be Social | ||
| 304 | @subsection Be Social | ||
| 305 | @c %**end of header | ||
| 306 | |||
| 307 | Next, you should print out your business card and be social. | ||
| 308 | Find a friend, help them install GNUnet and exchange business cards with | ||
| 309 | them. Or, if you're a desperate loner, you might try the next step with | ||
| 310 | your own card. Still, it'll be hard to have a conversation with | ||
| 311 | yourself later, so it would be better if you could find a friend. | ||
| 312 | You might also want a camera attached to your computer, so | ||
| 313 | you might need a trip to the store together. | ||
| 314 | |||
| 315 | Before we get started, we need to tell @code{gnunet-qr} which zone | ||
| 316 | it should import new records into. For this, run: | ||
| 317 | |||
| 318 | @pindex gnunet-identity | ||
| 319 | @example | ||
| 320 | $ gnunet-identity -s namestore -e NAME | ||
| 321 | @end example | ||
| 322 | where NAME is the name of the zone you want to import records | ||
| 323 | into. In our running example, this would be ``gnu''. | ||
| 324 | |||
| 325 | @pindex gnunet-qr | ||
| 326 | Henceforth, for every business card you collect, simply run: | ||
| 327 | @example | ||
| 328 | $ gnunet-qr | ||
| 329 | @end example | ||
| 330 | |||
| 331 | @noindent | ||
| 332 | to open a window showing whatever your camera points at. | ||
| 333 | Hold up your friend's business card and tilt it until | ||
| 334 | the QR code is recognized. At that point, the window should | ||
| 335 | automatically close. At that point, your friend's NICKname and their | ||
| 336 | public key should have been automatically imported into your zone. | ||
| 337 | |||
| 338 | Assuming both of your peers are properly integrated in the | ||
| 339 | GNUnet network at this time, you should thus be able to | ||
| 340 | resolve your friends names. Suppose your friend's nickname | ||
| 341 | is "Bob". Then, type | ||
| 342 | |||
| 343 | @pindex gnunet-gns | ||
| 344 | @example | ||
| 345 | $ gnunet-gns -u test.bob.gnu | ||
| 346 | @end example | ||
| 347 | |||
| 348 | @noindent | ||
| 349 | to check if your friend was as good at following instructions | ||
| 350 | as you were. | ||
| 351 | |||
| 352 | |||
| 353 | @node Backup of Identities and Egos | ||
| 354 | @subsection Backup of Identities and Egos | ||
| 355 | |||
| 356 | |||
| 357 | One should always backup their files, especially in these SSD days (our | ||
| 358 | team has suffered 3 SSD crashes over a span of 2 weeks). Backing up peer | ||
| 359 | identity and zones is achieved by copying the following files: | ||
| 360 | |||
| 361 | The peer identity file can be found | ||
| 362 | in @file{~/.local/share/gnunet/private_key.ecc} | ||
| 363 | |||
| 364 | The private keys of your egos are stored in the | ||
| 365 | directory @file{~/.local/share/gnunet/identity/egos/}. | ||
| 366 | They are stored in files whose filenames correspond to the zones' | ||
| 367 | ego names. These are probably the most important files you want | ||
| 368 | to backup from a GNUnet installation. | ||
| 369 | |||
| 370 | Note: All these files contain cryptographic keys and they are | ||
| 371 | stored without any encryption. So it is advisable to backup | ||
| 372 | encrypted copies of them. | ||
| 373 | |||
| 374 | |||
| 375 | @node Revocation | ||
| 376 | @subsection Revocation | ||
| 377 | |||
| 378 | Now, in the situation of an attacker gaining access to the private key of | ||
| 379 | one of your egos, the attacker can create records in the respective | ||
| 380 | GNS zone | ||
| 381 | and publish them as if you published them. Anyone resolving your | ||
| 382 | domain will get these new records and when they verify they seem | ||
| 383 | authentic because the attacker has signed them with your key. | ||
| 384 | |||
| 385 | To address this potential security issue, you can pre-compute | ||
| 386 | a revocation certificate corresponding to your ego. This certificate, | ||
| 387 | when published on the P2P network, flags your private key as invalid, | ||
| 388 | and all further resolutions or other checks involving the key will fail. | ||
| 389 | |||
| 390 | @pindex gnunet-revocation | ||
| 391 | A revocation certificate is thus a useful tool when things go out of | ||
| 392 | control, but at the same time it should be stored securely. | ||
| 393 | Generation of the revocation certificate for a zone can be done through | ||
| 394 | @command{gnunet-revocation}. For example, the following command (as | ||
| 395 | unprivileged user) generates a revocation file | ||
| 396 | @file{revocation.dat} for the zone @code{zone1}: | ||
| 397 | @command{gnunet-revocation -f revocation.dat -R zone1} | ||
| 398 | |||
| 399 | The above command only pre-computes a revocation certificate. It does | ||
| 400 | not revoke the given zone. Pre-computing a revocation certificate | ||
| 401 | involves computing a proof-of-work and hence may take up to 4 to 5 days | ||
| 402 | on a modern processor. Note that you can abort and resume the | ||
| 403 | calculation at any time. Also, even if you did not finish the | ||
| 404 | calculation, the resulting file will contain the signature, which is | ||
| 405 | sufficient to complete the revocation process even without access to | ||
| 406 | the private key. So instead of waiting for a few days, you can just | ||
| 407 | abort with CTRL-C, backup the revocation certificate and run the | ||
| 408 | calculation only if your key actually was compromised. This has the | ||
| 409 | disadvantage of revocation taking longer after the incident, but | ||
| 410 | the advantage of saving a significant amount of energy. So unless | ||
| 411 | you believe that a key compromise will need a rapid response, we | ||
| 412 | urge you to wait with generating the revocation certificate. | ||
| 413 | Also, the calculation is deliberately expensive, to deter people from | ||
| 414 | doing this just for fun (as the actual revocation operation is expensive | ||
| 415 | for the network, not for the peer performing the revocation). | ||
| 416 | |||
| 417 | |||
| 418 | @c FIXME: The Manual should give away the command using an example that is | ||
| 419 | @c very likely to never exist. | ||
| 420 | To avoid TL;DR ones from accidentally revocating their zones, we are not | ||
| 421 | giving away the command, but it is uncomplicated: the actual revocation is | ||
| 422 | performed by using the @command{-p} option of @command{gnunet-revocation}. | ||
| 423 | |||
| 424 | |||
| 425 | @node What's Next? | ||
| 426 | @subsection What's Next? | ||
| 427 | @c %**end of header | ||
| 428 | |||
| 429 | This may seem not like much of an application yet, but you have | ||
| 430 | just been one of the first to perform a decentralized secure name | ||
| 431 | lookup (where nobody could have altered the value supplied by your | ||
| 432 | friend) in a privacy-preserving manner (your query on the network | ||
| 433 | and the corresponding response were always encrypted). So what | ||
| 434 | can you really do with this? Well, to start with, you can publish your | ||
| 435 | GnuPG fingerprint in GNS as a "CERT" record and replace the public | ||
| 436 | web-of-trust with its complicated trust model with explicit names | ||
| 437 | and privacy-preserving resolution. Also, you should read the next | ||
| 438 | chapter of the tutorial and learn how to use GNS to have a | ||
| 439 | private conversation with your friend. Finally, help us | ||
| 440 | with the next GNUnet release for even more applications | ||
| 441 | using this new public key infrastructure. | ||
| 442 | |||
| 443 | @pindex gnunet-conservation-gtk | ||
| 444 | @node First steps - Using GNUnet Conversation | ||
| 445 | @section First steps - Using GNUnet Conversation | ||
| 446 | @c %**end of header | ||
| 447 | |||
| 448 | First, you should launch the graphical user interface. You can do | ||
| 449 | this from the command-line by typing | ||
| 450 | |||
| 451 | @example | ||
| 452 | $ gnunet-conversation-gtk | ||
| 453 | @end example | ||
| 454 | |||
| 455 | @menu | ||
| 456 | * Testing your Audio Equipment:: | ||
| 457 | * GNS Zones:: | ||
| 458 | @end menu | ||
| 459 | |||
| 460 | @node Testing your Audio Equipment | ||
| 461 | @subsection Testing your Audio Equipment | ||
| 462 | @c %**end of header | ||
| 463 | |||
| 464 | First, you should use @code{gnunet-conversation-test} to check that your | ||
| 465 | microphone and speaker are working correctly. You will be prompted to | ||
| 466 | speak for 5 seconds, and then those 5 seconds will be replayed to you. | ||
| 467 | The network is not involved in this test. If it fails, you should run | ||
| 468 | your pulse audio configuration tool to check that microphone and | ||
| 469 | speaker are not muted and, if you have multiple input/output devices, | ||
| 470 | that the correct device is being associated with GNUnet's audio tools. | ||
| 471 | |||
| 472 | @node GNS Zones | ||
| 473 | @subsection GNS Zones | ||
| 474 | @c %**end of header | ||
| 475 | |||
| 476 | @code{gnunet-conversation} uses GNS for addressing. This means that | ||
| 477 | you need to have a GNS zone created before using it. Information | ||
| 478 | about how to create GNS zones can be found here. | ||
| 479 | |||
| 480 | |||
| 481 | @menu | ||
| 482 | * Picking an Identity:: | ||
| 483 | * Calling somebody:: | ||
| 484 | @end menu | ||
| 485 | |||
| 486 | @node Picking an Identity | ||
| 487 | @subsubsection Picking an Identity | ||
| 488 | @c %**end of header | ||
| 489 | |||
| 490 | To make a call with @code{gnunet-conversation}, you first | ||
| 491 | need to choose an identity. This identity is both the caller ID | ||
| 492 | that will show up when you call somebody else, as well as the | ||
| 493 | GNS zone that will be used to resolve names of users that you | ||
| 494 | are calling. Run | ||
| 495 | |||
| 496 | @pindex gnunet-conversation | ||
| 497 | @example | ||
| 498 | gnunet-conversation -e zone-name | ||
| 499 | @end example | ||
| 500 | |||
| 501 | @noindent | ||
| 502 | to start the command-line tool. You will see a message saying | ||
| 503 | that your phone is now "active on line 0". You can connect | ||
| 504 | multiple phones on different lines at the same peer. For the | ||
| 505 | first phone, the line zero is of course a fine choice. | ||
| 506 | |||
| 507 | Next, you should type in @command{/help} for a list of | ||
| 508 | available commands. We will explain the important ones | ||
| 509 | during this tutorial. First, you will need to type in | ||
| 510 | @command{/address} to determine the address of your | ||
| 511 | phone. The result should look something like this: | ||
| 512 | |||
| 513 | @example | ||
| 514 | /address | ||
| 515 | 0-PD67SGHF3E0447TU9HADIVU9OM7V4QHTOG0EBU69TFRI2LG63DR0 | ||
| 516 | @end example | ||
| 517 | |||
| 518 | @noindent | ||
| 519 | Here, the "0" is your phone line, and what follows | ||
| 520 | after the hyphen is your peer's identity. This information will | ||
| 521 | need to be placed in a PHONE record of | ||
| 522 | your GNS master-zone so that other users can call you. | ||
| 523 | |||
| 524 | Start @code{gnunet-namestore-gtk} now (possibly from another | ||
| 525 | shell) and create an entry home-phone in your master zone. | ||
| 526 | For the record type, select PHONE. You should then see the | ||
| 527 | PHONE dialog: | ||
| 528 | |||
| 529 | @c image here | ||
| 530 | |||
| 531 | Note: Do not choose the expiry time to be 'Never'. If you | ||
| 532 | do that, you assert that this record will never change and | ||
| 533 | can be cached indefinitely by the DHT and the peers which | ||
| 534 | resolve this record. A reasonable period is 1 year. | ||
| 535 | |||
| 536 | Enter your peer identity under Peer and leave the line | ||
| 537 | at zero. Select the first option to make the record public. | ||
| 538 | If you entered your peer identity incorrectly, | ||
| 539 | the "Save" button will not work; you might want to use | ||
| 540 | copy-and-paste instead of typing in the peer identity | ||
| 541 | manually. Save the record. | ||
| 542 | |||
| 543 | @node Calling somebody | ||
| 544 | @subsubsection Calling somebody | ||
| 545 | @c %**end of header | ||
| 546 | |||
| 547 | Now you can call a buddy. Obviously, your buddy will have to have GNUnet | ||
| 548 | installed and must have performed the same steps. Also, you must have | ||
| 549 | your buddy in your GNS master zone, for example by having imported | ||
| 550 | your buddy's public key using @code{gnunet-qr}. Suppose your buddy | ||
| 551 | is in your zone as @code{buddy.mytld} and they also created their | ||
| 552 | phone using a label "home-phone". Then you can initiate a call using: | ||
| 553 | |||
| 554 | @example | ||
| 555 | /call home-phone.buddy.mytld | ||
| 556 | @end example | ||
| 557 | |||
| 558 | It may take some time for GNUnet to resolve the name and to establish | ||
| 559 | a link. If your buddy has your public key in their master zone, they | ||
| 560 | should see an incoming call with your name. If your public key is not | ||
| 561 | in their master zone, they will just see the public key as the caller ID. | ||
| 562 | |||
| 563 | Your buddy then can answer the call using the "/accept" command. After | ||
| 564 | that, (encrypted) voice data should be relayed between your two peers. | ||
| 565 | Either of you can end the call using @command{/cancel}. You can exit | ||
| 566 | @code{gnunet-conversation} using @command{/quit}. | ||
| 567 | |||
| 568 | |||
| 569 | @node First steps - Using the GNUnet VPN | ||
| 570 | @section First steps - Using the GNUnet VPN | ||
| 571 | @c %**end of header | ||
| 572 | |||
| 573 | |||
| 574 | @menu | ||
| 575 | * VPN Preliminaries:: | ||
| 576 | * GNUnet-Exit configuration:: | ||
| 577 | * GNS configuration:: | ||
| 578 | * Accessing the service:: | ||
| 579 | * Using a Browser:: | ||
| 580 | @end menu | ||
| 581 | |||
| 582 | @node VPN Preliminaries | ||
| 583 | @subsection VPN Preliminaries | ||
| 584 | @c %**end of header | ||
| 585 | |||
| 586 | To test the GNUnet VPN, we should first run a web server. | ||
| 587 | The easiest way to do this is to just start @code{gnunet-bcd}, | ||
| 588 | which will run a webserver on port @code{8888} by default. | ||
| 589 | Naturally, you can run some other HTTP server for our little tutorial. | ||
| 590 | |||
| 591 | If you have not done this, you should also configure your | ||
| 592 | Name System Service switch to use GNS. In your @code{/etc/nsswitch.conf} | ||
| 593 | you should fine a line like this: | ||
| 594 | |||
| 595 | @example | ||
| 596 | hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 | ||
| 597 | @end example | ||
| 598 | |||
| 599 | @noindent | ||
| 600 | The exact details may differ a bit, which is fine. Add the text | ||
| 601 | @code{gns [NOTFOUND=return]} after @code{files}: | ||
| 602 | |||
| 603 | @example | ||
| 604 | hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 | ||
| 605 | @end example | ||
| 606 | |||
| 607 | @c TODO: outdated section, we no longer install this as part of the | ||
| 608 | @c TODO: standard installation procedure and should point out the manual | ||
| 609 | @c TODO: steps required to make it useful. | ||
| 610 | @noindent | ||
| 611 | You might want to make sure that @code{/lib/libnss_gns.so.2} exists on | ||
| 612 | your system, it should have been created during the installation. | ||
| 613 | If not, re-run | ||
| 614 | |||
| 615 | @example | ||
| 616 | $ configure --with-nssdir=/lib | ||
| 617 | $ cd src/gns/nss; sudo make install | ||
| 618 | @end example | ||
| 619 | |||
| 620 | @noindent | ||
| 621 | to install the NSS plugins in the proper location. | ||
| 622 | |||
| 623 | @node GNUnet-Exit configuration | ||
| 624 | @subsection GNUnet-Exit configuration | ||
| 625 | @c %**end of header | ||
| 626 | |||
| 627 | Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and | ||
| 628 | run @command{gnunet-setup}. In @command{gnunet-setup}, make sure to | ||
| 629 | activate the @strong{EXIT} and @strong{GNS} services in the General tab. | ||
| 630 | Then select the Exit tab. Most of the defaults should be fine (but | ||
| 631 | you should check against the screenshot that they have not been modified). | ||
| 632 | In the bottom area, enter @code{bcd} under Identifier and change the | ||
| 633 | Destination to @code{169.254.86.1:8888} (if your server runs on a port | ||
| 634 | other than 8888, change the 8888 port accordingly). | ||
| 635 | |||
| 636 | Now exit @command{gnunet-setup} and restart your peer | ||
| 637 | (@command{gnunet-arm -s}). | ||
| 638 | |||
| 639 | @node GNS configuration | ||
| 640 | @subsection GNS configuration | ||
| 641 | @c %**end of header | ||
| 642 | |||
| 643 | Now, using your normal user (not the @code{gnunet} system user), run | ||
| 644 | @command{gnunet-gtk}. Select the GNS icon and add a new label www in your | ||
| 645 | master zone. For the record type, select @code{VPN}. You should then | ||
| 646 | see the VPN dialog: | ||
| 647 | |||
| 648 | @c insert image | ||
| 649 | |||
| 650 | Under peer, you need to supply the peer identity of your own peer. You can | ||
| 651 | obtain the respective string by running @command{gnunet-peerinfo -sq} | ||
| 652 | as the @code{gnunet} user. For the Identifier, you need to supply the same | ||
| 653 | identifier that we used in the Exit setup earlier, so here supply "bcd". | ||
| 654 | If you want others to be able to use the service, you should probably make | ||
| 655 | the record public. For non-public services, you should use a passphrase | ||
| 656 | instead of the string "bcd". Save the record and | ||
| 657 | exit @command{gnunet-gtk}. | ||
| 658 | |||
| 659 | @node Accessing the service | ||
| 660 | @subsection Accessing the service | ||
| 661 | @c %**end of header | ||
| 662 | |||
| 663 | You should now be able to access your webserver. Type in: | ||
| 664 | |||
| 665 | @example | ||
| 666 | $ wget http://www.gnu/ | ||
| 667 | @end example | ||
| 668 | |||
| 669 | @noindent | ||
| 670 | The request will resolve to the VPN record, telling the GNS resolver | ||
| 671 | to route it via the GNUnet VPN. The GNS resolver will ask the | ||
| 672 | GNUnet VPN for an IPv4 address to return to the application. The | ||
| 673 | VPN service will use the VPN information supplied by GNS to create | ||
| 674 | a tunnel (via GNUnet's MESH service) to the EXIT peer. | ||
| 675 | At the EXIT, the name "bcd" and destination port (80) will be mapped | ||
| 676 | to the specified destination IP and port. While all this is currently | ||
| 677 | happening on just the local machine, it should also work with other | ||
| 678 | peers --- naturally, they will need a way to access your GNS zone | ||
| 679 | first, for example by learning your public key from a QR code on | ||
| 680 | your business card. | ||
| 681 | |||
| 682 | @node Using a Browser | ||
| 683 | @subsection Using a Browser | ||
| 684 | @c %**end of header | ||
| 685 | |||
| 686 | Sadly, modern browsers tend to bypass the Name Services Switch and | ||
| 687 | attempt DNS resolution directly. You can either run | ||
| 688 | a @code{gnunet-dns2gns} DNS proxy, or point the browsers to an | ||
| 689 | HTTP proxy. When we tried it, Iceweasel did not like to connect to | ||
| 690 | the socks proxy for @code{.gnu} TLDs, even if we disabled its | ||
| 691 | autoblunder of changing @code{.gnu} to ".gnu.com". Still, | ||
| 692 | using the HTTP proxy with Chrome does work. | ||
| 693 | |||
| 694 | @node File-sharing | ||
| 695 | @section File-sharing | ||
| 696 | @c %**end of header | ||
| 697 | |||
| 698 | This chapter documents the GNUnet file-sharing application. The original | ||
| 699 | file-sharing implementation for GNUnet was designed to provide | ||
| 700 | @strong{anonymous} file-sharing. However, over time, we have also added | ||
| 701 | support for non-anonymous file-sharing (which can provide better | ||
| 702 | performance). Anonymous and non-anonymous file-sharing are quite | ||
| 703 | integrated in GNUnet and, except for routing, share most of the concepts | ||
| 704 | and implementation. There are three primary file-sharing operations: | ||
| 705 | publishing, searching and downloading. For each of these operations, | ||
| 706 | the user specifies an @strong{anonymity level}. If both the publisher and | ||
| 707 | the searcher/downloader specify "no anonymity", non-anonymous | ||
| 708 | file-sharing is used. If either user specifies some desired degree | ||
| 709 | of anonymity, anonymous file-sharing will be used. | ||
| 710 | |||
| 711 | After a short introduction, we will first look at the various concepts | ||
| 712 | in GNUnet's file-sharing implementation. Then, we will discuss | ||
| 713 | specifics as to how they impact users that publish, search or download | ||
| 714 | files. | ||
| 715 | |||
| 716 | |||
| 717 | @menu | ||
| 718 | * fs-Searching:: | ||
| 719 | * fs-Downloading:: | ||
| 720 | * fs-Publishing:: | ||
| 721 | * fs-Concepts:: | ||
| 722 | * Namespace Management:: | ||
| 723 | * File-Sharing URIs:: | ||
| 724 | * GTK User Interface:: | ||
| 725 | @end menu | ||
| 726 | |||
| 727 | @node fs-Searching | ||
| 728 | @subsection Searching | ||
| 729 | @c %**end of header | ||
| 730 | |||
| 731 | The command @command{gnunet-search} can be used to search | ||
| 732 | for content on GNUnet. The format is: | ||
| 733 | |||
| 734 | @example | ||
| 735 | $ gnunet-search [-t TIMEOUT] KEYWORD | ||
| 736 | @end example | ||
| 737 | |||
| 738 | @noindent | ||
| 739 | The @command{-t} option specifies that the query should timeout after | ||
| 740 | approximately TIMEOUT seconds. A value of zero (``0'') is interpreted | ||
| 741 | as @emph{no timeout}, which is the default. In this case, | ||
| 742 | @command{gnunet-search} will never terminate (unless you press | ||
| 743 | @command{CTRL-C}). | ||
| 744 | |||
| 745 | If multiple words are passed as keywords, they will all be | ||
| 746 | considered optional. Prefix keywords with a "+" to make them mandatory. | ||
| 747 | |||
| 748 | Note that searching using | ||
| 749 | |||
| 750 | @example | ||
| 751 | $ gnunet-search Das Kapital | ||
| 752 | @end example | ||
| 753 | |||
| 754 | @noindent | ||
| 755 | is not the same as searching for | ||
| 756 | |||
| 757 | @example | ||
| 758 | $ gnunet-search "Das Kapital" | ||
| 759 | @end example | ||
| 760 | |||
| 761 | @noindent | ||
| 762 | as the first will match files shared under the keywords | ||
| 763 | "Das" or "Kapital" whereas the second will match files | ||
| 764 | shared under the keyword "Das Kapital". | ||
| 765 | |||
| 766 | Search results are printed by @command{gnunet-search} like this: | ||
| 767 | |||
| 768 | @c it will be better the avoid the ellipsis altogether because I don't | ||
| 769 | @c understand the explanation below that | ||
| 770 | @c ng0: who is ``I'' and what was the complete sentence? | ||
| 771 | @example | ||
| 772 | #15: | ||
| 773 | gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 | ||
| 774 | |||
| 775 | @end example | ||
| 776 | |||
| 777 | @noindent | ||
| 778 | The whole line is the command you would have to enter to download | ||
| 779 | the file. The first argument passed to @code{-o} is the suggested | ||
| 780 | filename (you may change it to whatever you like). | ||
| 781 | It is followed by the key for decrypting the file, the query for | ||
| 782 | searching the file, a checksum (in hexadecimal) finally the size of | ||
| 783 | the file in bytes. | ||
| 784 | |||
| 785 | @node fs-Downloading | ||
| 786 | @subsection Downloading | ||
| 787 | @c %**end of header | ||
| 788 | |||
| 789 | In order to download a file, you need the whole line returned by | ||
| 790 | @command{gnunet-search}. | ||
| 791 | You can then use the tool @command{gnunet-download} to obtain the file: | ||
| 792 | |||
| 793 | @example | ||
| 794 | $ gnunet-download -o <FILENAME> <GNUNET-URL> | ||
| 795 | @end example | ||
| 796 | |||
| 797 | @noindent | ||
| 798 | FILENAME specifies the name of the file where GNUnet is supposed | ||
| 799 | to write the result. Existing files are overwritten. If the | ||
| 800 | existing file contains blocks that are identical to the | ||
| 801 | desired download, those blocks will not be downloaded again | ||
| 802 | (automatic resume). | ||
| 803 | |||
| 804 | If you want to download the GPL from the previous example, | ||
| 805 | you do the following: | ||
| 806 | |||
| 807 | @example | ||
| 808 | $ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 | ||
| 809 | @end example | ||
| 810 | |||
| 811 | @noindent | ||
| 812 | If you ever have to abort a download, you can continue it at any time by | ||
| 813 | re-issuing @command{gnunet-download} with the same filename. | ||
| 814 | In that case, GNUnet will @strong{not} download blocks again that are | ||
| 815 | already present. | ||
| 816 | |||
| 817 | GNUnet's file-encoding mechanism will ensure file integrity, even if the | ||
| 818 | existing file was not downloaded from GNUnet in the first place. | ||
| 819 | |||
| 820 | You may want to use the @command{-V} switch to turn on verbose | ||
| 821 | reporting. In this case, @command{gnunet-download} will print the | ||
| 822 | current number of bytes downloaded whenever new data was received. | ||
| 823 | |||
| 824 | @node fs-Publishing | ||
| 825 | @subsection Publishing | ||
| 826 | @c %**end of header | ||
| 827 | |||
| 828 | The command @command{gnunet-publish} can be used to add content | ||
| 829 | to the network. The basic format of the command is | ||
| 830 | |||
| 831 | @example | ||
| 832 | $ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME | ||
| 833 | @end example | ||
| 834 | |||
| 835 | For example | ||
| 836 | @example | ||
| 837 | $ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING | ||
| 838 | @end example | ||
| 839 | |||
| 840 | @menu | ||
| 841 | * Important command-line options:: | ||
| 842 | * Indexing vs. Inserting:: | ||
| 843 | @end menu | ||
| 844 | |||
| 845 | @node Important command-line options | ||
| 846 | @subsubsection Important command-line options | ||
| 847 | @c %**end of header | ||
| 848 | |||
| 849 | The option @code{-k} is used to specify keywords for the file that | ||
| 850 | should be inserted. You can supply any number of keywords, | ||
| 851 | and each of the keywords will be sufficient to locate and | ||
| 852 | retrieve the file. Please note that you must use the @code{-k} option | ||
| 853 | more than once -- one for each expression you use as a keyword for | ||
| 854 | the filename. | ||
| 855 | |||
| 856 | The -m option is used to specify meta-data, such as descriptions. | ||
| 857 | You can use -m multiple times. The TYPE passed must be from the | ||
| 858 | list of meta-data types known to libextractor. You can obtain this | ||
| 859 | list by running @command{extract -L}. Use quotes around the entire | ||
| 860 | meta-data argument if the value contains spaces. The meta-data | ||
| 861 | is displayed to other users when they select which files to | ||
| 862 | download. The meta-data and the keywords are optional and | ||
| 863 | may be inferred using @code{GNU libextractor}. | ||
| 864 | |||
| 865 | @command{gnunet-publish} has a few additional options to handle | ||
| 866 | namespaces and directories. Refer to the man-page for details: | ||
| 867 | |||
| 868 | @example | ||
| 869 | man gnunet-publish | ||
| 870 | @end example | ||
| 871 | |||
| 872 | @node Indexing vs. Inserting | ||
| 873 | @subsubsection Indexing vs Inserting | ||
| 874 | @c %**end of header | ||
| 875 | |||
| 876 | By default, GNUnet indexes a file instead of making a full copy. | ||
| 877 | This is much more efficient, but requires the file to stay unaltered | ||
| 878 | at the location where it was when it was indexed. If you intend to move, | ||
| 879 | delete or alter a file, consider using the option @code{-n} which will | ||
| 880 | force GNUnet to make a copy of the file in the database. | ||
| 881 | |||
| 882 | Since it is much less efficient, this is strongly discouraged for large | ||
| 883 | files. When GNUnet indexes a file (default), GNUnet does @strong{not} | ||
| 884 | create an additional encrypted copy of the file but just computes a | ||
| 885 | summary (or index) of the file. That summary is approximately two percent | ||
| 886 | of the size of the original file and is stored in GNUnet's database. | ||
| 887 | Whenever a request for a part of an indexed file reaches GNUnet, | ||
| 888 | this part is encrypted on-demand and send out. This way, there is no | ||
| 889 | need for an additional encrypted copy of the file to stay anywhere | ||
| 890 | on the drive. This is different from other systems, such as Freenet, | ||
| 891 | where each file that is put online must be in Freenet's database in | ||
| 892 | encrypted format, doubling the space requirements if the user wants | ||
| 893 | to preserve a directly accessible copy in plaintext. | ||
| 894 | |||
| 895 | Thus indexing should be used for all files where the user will keep | ||
| 896 | using this file (at the location given to gnunet-publish) and does | ||
| 897 | not want to retrieve it back from GNUnet each time. If you want to | ||
| 898 | remove a file that you have indexed from the local peer, use the tool | ||
| 899 | @command{gnunet-unindex} to un-index the file. | ||
| 900 | |||
| 901 | The option @code{-n} may be used if the user fears that the file might | ||
| 902 | be found on their drive (assuming the computer comes under the control | ||
| 903 | of an adversary). When used with the @code{-n} flag, the user has a | ||
| 904 | much better chance of denying knowledge of the existence of the file, | ||
| 905 | even if it is still (encrypted) on the drive and the adversary is | ||
| 906 | able to crack the encryption (e.g. by guessing the keyword. | ||
| 907 | |||
| 908 | @node fs-Concepts | ||
| 909 | @subsection Concepts | ||
| 910 | @c %**end of header | ||
| 911 | |||
| 912 | For better results with filesharing it is useful to understand the | ||
| 913 | following concepts. | ||
| 914 | In addition to anonymous routing GNUnet attempts to give users a better | ||
| 915 | experience in searching for content. GNUnet uses cryptography to safely | ||
| 916 | break content into smaller pieces that can be obtained from different | ||
| 917 | sources without allowing participants to corrupt files. GNUnet makes it | ||
| 918 | difficult for an adversary to send back bogus search results. GNUnet | ||
| 919 | enables content providers to group related content and to establish a | ||
| 920 | reputation. Furthermore, GNUnet allows updates to certain content to be | ||
| 921 | made available. This section is supposed to introduce users to the | ||
| 922 | concepts that are used to achieve these goals. | ||
| 923 | |||
| 924 | |||
| 925 | @menu | ||
| 926 | * Files:: | ||
| 927 | * Keywords:: | ||
| 928 | * Directories:: | ||
| 929 | * Pseudonyms:: | ||
| 930 | * Namespaces:: | ||
| 931 | * Advertisements:: | ||
| 932 | * Anonymity level:: | ||
| 933 | * Content Priority:: | ||
| 934 | * Replication:: | ||
| 935 | @end menu | ||
| 936 | |||
| 937 | @node Files | ||
| 938 | @subsubsection Files | ||
| 939 | @c %**end of header | ||
| 940 | |||
| 941 | A file in GNUnet is just a sequence of bytes. Any file-format is allowed | ||
| 942 | and the maximum file size is theoretically @math{2^64 - 1} bytes, except | ||
| 943 | that it would take an impractical amount of time to share such a file. | ||
| 944 | GNUnet itself never interprets the contents of shared files, except when | ||
| 945 | using GNU libextractor to obtain keywords. | ||
| 946 | |||
| 947 | @node Keywords | ||
| 948 | @subsubsection Keywords | ||
| 949 | @c %**end of header | ||
| 950 | |||
| 951 | Keywords are the most simple mechanism to find files on GNUnet. | ||
| 952 | Keywords are @strong{case-sensitive} and the search string | ||
| 953 | must always match @strong{exactly} the keyword used by the | ||
| 954 | person providing the file. Keywords are never transmitted in | ||
| 955 | plaintext. The only way for an adversary to determine the keyword | ||
| 956 | that you used to search is to guess it (which then allows the | ||
| 957 | adversary to produce the same search request). Since providing | ||
| 958 | keywords by hand for each shared file is tedious, GNUnet uses | ||
| 959 | GNU libextractor to help automate this process. Starting a | ||
| 960 | keyword search on a slow machine can take a little while since | ||
| 961 | the keyword search involves computing a fresh RSA key to formulate the | ||
| 962 | request. | ||
| 963 | |||
| 964 | @node Directories | ||
| 965 | @subsubsection Directories | ||
| 966 | @c %**end of header | ||
| 967 | |||
| 968 | A directory in GNUnet is a list of file identifiers with meta data. | ||
| 969 | The file identifiers provide sufficient information about the files | ||
| 970 | to allow downloading the contents. Once a directory has been created, | ||
| 971 | it cannot be changed since it is treated just like an ordinary file | ||
| 972 | by the network. Small files (of a few kilobytes) can be inlined in | ||
| 973 | the directory, so that a separate download becomes unnecessary. | ||
| 974 | |||
| 975 | Directories are shared just like ordinary files. If you download a | ||
| 976 | directory with @command{gnunet-download}, you can use | ||
| 977 | @command{gnunet-directory} to list its contents. The canonical | ||
| 978 | extension for GNUnet directories when stored as files in your | ||
| 979 | local file-system is ".gnd". The contents of a directory are URIs and | ||
| 980 | meta data. | ||
| 981 | The URIs contain all the information required by | ||
| 982 | @command{gnunet-download} to retrieve the file. The meta data | ||
| 983 | typically includes the mime-type, description, a filename and | ||
| 984 | other meta information, and possibly even the full original file | ||
| 985 | (if it was small). | ||
| 986 | |||
| 987 | @node Pseudonyms | ||
| 988 | @subsubsection Pseudonyms | ||
| 989 | @c %**end of header | ||
| 990 | |||
| 991 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 992 | @b{to be rewritten for version 0.10!} | ||
| 993 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
| 994 | |||
| 995 | Pseudonyms in GNUnet are essentially public-private (RSA) key pairs | ||
| 996 | that allow a GNUnet user to maintain an identity (which may or may not | ||
| 997 | be detached from their real-life identity). GNUnet's pseudonyms are not | ||
| 998 | file-sharing specific --- and they will likely be used by many GNUnet | ||
| 999 | applications where a user identity is required. | ||
| 1000 | |||
| 1001 | Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple | ||
| 1002 | pseudonyms for a single user, and users could (theoretically) share the | ||
| 1003 | private pseudonym keys (currently only out-of-band by knowing which files | ||
| 1004 | to copy around). | ||
| 1005 | |||
| 1006 | @node Namespaces | ||
| 1007 | @subsubsection Namespaces | ||
| 1008 | @c %**end of header | ||
| 1009 | |||
| 1010 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 1011 | @b{to be rewritten for version 0.10!} | ||
| 1012 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
| 1013 | |||
| 1014 | A namespace is a set of files that were signed by the same pseudonym. | ||
| 1015 | Files (or directories) that have been signed and placed into a namespace | ||
| 1016 | can be updated. Updates are identified as authentic if the same secret | ||
| 1017 | key was used to sign the update. Namespaces are also useful to establish | ||
| 1018 | a reputation, since all of the content in the namespace comes from the | ||
| 1019 | same entity (which does not have to be the same person). | ||
| 1020 | |||
| 1021 | @node Advertisements | ||
| 1022 | @subsubsection Advertisements | ||
| 1023 | @c %**end of header | ||
| 1024 | |||
| 1025 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 1026 | @b{to be rewritten for version 0.10!} | ||
| 1027 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
| 1028 | |||
| 1029 | Advertisements are used to notify other users about the existence of a | ||
| 1030 | namespace. Advertisements are propagated using the normal keyword search. | ||
| 1031 | When an advertisement is received (in response to a search), the namespace | ||
| 1032 | is added to the list of namespaces available in the namespace-search | ||
| 1033 | dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a | ||
| 1034 | namespace is created, an appropriate advertisement can be generated. | ||
| 1035 | The default keyword for the advertising of namespaces is "namespace". | ||
| 1036 | |||
| 1037 | Note that GNUnet differentiates between your pseudonyms (the identities | ||
| 1038 | that you control) and namespaces. If you create a pseudonym, you will | ||
| 1039 | not automatically see the respective namespace. You first have to create | ||
| 1040 | an advertisement for the namespace and find it using keyword | ||
| 1041 | search --- even for your own namespaces. The @command{gnunet-identity} | ||
| 1042 | tool is currently responsible for both managing pseudonyms and namespaces. | ||
| 1043 | This will likely change in the future to reduce the potential for | ||
| 1044 | confusion. | ||
| 1045 | |||
| 1046 | @node Anonymity level | ||
| 1047 | @subsubsection Anonymity level | ||
| 1048 | @c %**end of header | ||
| 1049 | |||
| 1050 | The anonymity level determines how hard it should be for an adversary to | ||
| 1051 | determine the identity of the publisher or the searcher/downloader. An | ||
| 1052 | anonymity level of zero means that anonymity is not required. The default | ||
| 1053 | anonymity level of "1" means that anonymous routing is desired, but no | ||
| 1054 | particular amount of cover traffic is necessary. A powerful adversary | ||
| 1055 | might thus still be able to deduce the origin of the traffic using | ||
| 1056 | traffic analysis. Specifying higher anonymity levels increases the | ||
| 1057 | amount of cover traffic required. While this offers better privacy, | ||
| 1058 | it can also significantly hurt performance. | ||
| 1059 | |||
| 1060 | @node Content Priority | ||
| 1061 | @subsubsection Content Priority | ||
| 1062 | @c %**end of header | ||
| 1063 | |||
| 1064 | Depending on the peer's configuration, GNUnet peers migrate content | ||
| 1065 | between peers. Content in this sense are individual blocks of a file, | ||
| 1066 | not necessarily entire files. When peers run out of space (due to | ||
| 1067 | local publishing operations or due to migration of content from other | ||
| 1068 | peers), blocks sometimes need to be discarded. GNUnet first always | ||
| 1069 | discards expired blocks (typically, blocks are published with an | ||
| 1070 | expiration of about two years in the future; this is another option). | ||
| 1071 | If there is still not enough space, GNUnet discards the blocks with the | ||
| 1072 | lowest priority. The priority of a block is decided by its popularity | ||
| 1073 | (in terms of requests from peers we trust) and, in case of blocks | ||
| 1074 | published locally, the base-priority that was specified by the user | ||
| 1075 | when the block was published initially. | ||
| 1076 | |||
| 1077 | @node Replication | ||
| 1078 | @subsubsection Replication | ||
| 1079 | @c %**end of header | ||
| 1080 | |||
| 1081 | When peers migrate content to other systems, the replication level | ||
| 1082 | of a block is used to decide which blocks need to be migrated most | ||
| 1083 | urgently. GNUnet will always push the block with the highest | ||
| 1084 | replication level into the network, and then decrement the replication | ||
| 1085 | level by one. If all blocks reach replication level zero, the | ||
| 1086 | selection is simply random. | ||
| 1087 | |||
| 1088 | |||
| 1089 | @node Namespace Management | ||
| 1090 | @subsection Namespace Management | ||
| 1091 | @c %**end of header | ||
| 1092 | |||
| 1093 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 1094 | @b{to be rewritten for version 0.10!} | ||
| 1095 | |||
| 1096 | The @code{gnunet-identity} tool can be used to create pseudonyms and | ||
| 1097 | to advertise namespaces. By default, @code{gnunet-identity -D} simply | ||
| 1098 | lists all locally available pseudonyms. | ||
| 1099 | |||
| 1100 | |||
| 1101 | @menu | ||
| 1102 | * Creating Pseudonyms:: | ||
| 1103 | * Deleting Pseudonyms:: | ||
| 1104 | * Advertising namespaces:: | ||
| 1105 | * Namespace names:: | ||
| 1106 | * Namespace root:: | ||
| 1107 | @end menu | ||
| 1108 | |||
| 1109 | @node Creating Pseudonyms | ||
| 1110 | @subsubsection Creating Pseudonyms | ||
| 1111 | @c %**end of header | ||
| 1112 | |||
| 1113 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 1114 | @b{to be rewritten for version 0.10!} | ||
| 1115 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
| 1116 | |||
| 1117 | With the @command{-C NICK} option it can also be used to | ||
| 1118 | create a new pseudonym. A pseudonym is the virtual identity | ||
| 1119 | of the entity in control of a namespace. Anyone can create | ||
| 1120 | any number of pseudonyms. Note that creating a pseudonym can | ||
| 1121 | take a few minutes depending on the performance of the machine | ||
| 1122 | used. | ||
| 1123 | |||
| 1124 | @node Deleting Pseudonyms | ||
| 1125 | @subsubsection Deleting Pseudonyms | ||
| 1126 | @c %**end of header | ||
| 1127 | |||
| 1128 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 1129 | @b{to be rewritten for version 0.10!} | ||
| 1130 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
| 1131 | |||
| 1132 | With the @command{-D NICK} option pseudonyms can be deleted. | ||
| 1133 | Once the pseudonym has been deleted it is impossible to add | ||
| 1134 | content to the corresponding namespace. Deleting the | ||
| 1135 | pseudonym does not make the namespace or any content in it | ||
| 1136 | unavailable. | ||
| 1137 | |||
| 1138 | @node Advertising namespaces | ||
| 1139 | @subsubsection Advertising namespaces | ||
| 1140 | @c %**end of header | ||
| 1141 | |||
| 1142 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 1143 | @b{to be rewritten for version 0.10!} | ||
| 1144 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
| 1145 | |||
| 1146 | Each namespace is associated with meta-data that describes | ||
| 1147 | the namespace. This meta-data is provided by the user at | ||
| 1148 | the time that the namespace is advertised. Advertisements | ||
| 1149 | are published under keywords so that they can be found using | ||
| 1150 | normal keyword-searches. This way, users can learn about new | ||
| 1151 | namespaces without relying on out-of-band communication or directories. | ||
| 1152 | A suggested keyword to use for all namespaces is simply "namespace". | ||
| 1153 | When a keyword-search finds a namespace advertisement, | ||
| 1154 | it is automatically stored in a local list of known namespaces. | ||
| 1155 | Users can then associate a rank with the namespace to remember | ||
| 1156 | the quality of the content found in it. | ||
| 1157 | |||
| 1158 | @node Namespace names | ||
| 1159 | @subsubsection Namespace names | ||
| 1160 | @c %**end of header | ||
| 1161 | |||
| 1162 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 1163 | @b{to be rewritten for version 0.10!} | ||
| 1164 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
| 1165 | |||
| 1166 | While the namespace is uniquely identified by its ID, another way | ||
| 1167 | to refer to the namespace is to use the NICKNAME. | ||
| 1168 | The NICKNAME can be freely chosen by the creator of the namespace and | ||
| 1169 | hence conflicts are possible. If a GNUnet client learns about more | ||
| 1170 | than one namespace using the same NICKNAME, the ID is appended | ||
| 1171 | to the NICKNAME to get a unique identifier. | ||
| 1172 | |||
| 1173 | @node Namespace root | ||
| 1174 | @subsubsection Namespace root | ||
| 1175 | @c %**end of header | ||
| 1176 | |||
| 1177 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 1178 | @b{to be rewritten for version 0.10!} | ||
| 1179 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
| 1180 | |||
| 1181 | An item of particular interest in the namespace advertisement is | ||
| 1182 | the ROOT. The ROOT is the identifier of a designated entry in the | ||
| 1183 | namespace. The idea is that the ROOT can be used to advertise an | ||
| 1184 | entry point to the content of the namespace. | ||
| 1185 | |||
| 1186 | @node File-Sharing URIs | ||
| 1187 | @subsection File-Sharing URIs | ||
| 1188 | @c %**end of header | ||
| 1189 | |||
| 1190 | GNUnet (currently) uses four different types of URIs for | ||
| 1191 | file-sharing. They all begin with "gnunet://fs/". | ||
| 1192 | This section describes the four different URI types in detail. | ||
| 1193 | |||
| 1194 | For FS URIs empty KEYWORDs are not allowed. Quotes are allowed to | ||
| 1195 | denote whitespace between words. Keywords must contain a balanced | ||
| 1196 | number of double quotes. Doubles quotes can not be used in the actual | ||
| 1197 | keywords. This means that the the string '""foo bar""' will be turned | ||
| 1198 | into two OR-ed keywords 'foo' and 'bar', not into '"foo bar"'. | ||
| 1199 | |||
| 1200 | @menu | ||
| 1201 | * Encoding of hash values in URIs:: | ||
| 1202 | * Content Hash Key (chk):: | ||
| 1203 | * Location identifiers (loc):: | ||
| 1204 | * Keyword queries (ksk):: | ||
| 1205 | * Namespace content (sks):: | ||
| 1206 | @end menu | ||
| 1207 | |||
| 1208 | @node Encoding of hash values in URIs | ||
| 1209 | @subsubsection Encoding of hash values in URIs | ||
| 1210 | @c %**end of header | ||
| 1211 | |||
| 1212 | Most URIs include some hash values. Hashes are encoded using | ||
| 1213 | base32hex (RFC 2938). | ||
| 1214 | |||
| 1215 | @cindex chk-uri | ||
| 1216 | @node Content Hash Key (chk) | ||
| 1217 | @subsubsection Content Hash Key (chk) | ||
| 1218 | @c %**end of header | ||
| 1219 | |||
| 1220 | A chk-URI is used to (uniquely) identify a file or directory | ||
| 1221 | and to allow peers to download the file. Files are stored in | ||
| 1222 | GNUnet as a tree of encrypted blocks. | ||
| 1223 | The chk-URI thus contains the information to download and decrypt | ||
| 1224 | those blocks. A chk-URI has the format | ||
| 1225 | "gnunet://fs/chk/KEYHASH.QUERYHASH.SIZE". Here, "SIZE" | ||
| 1226 | is the size of the file (which allows a peer to determine the | ||
| 1227 | shape of the tree), KEYHASH is the key used to decrypt the file | ||
| 1228 | (also the hash of the plaintext of the top block) and QUERYHASH | ||
| 1229 | is the query used to request the top-level block (also the hash | ||
| 1230 | of the encrypted block). | ||
| 1231 | |||
| 1232 | @cindex loc-uri | ||
| 1233 | @node Location identifiers (loc) | ||
| 1234 | @subsubsection Location identifiers (loc) | ||
| 1235 | @c %**end of header | ||
| 1236 | |||
| 1237 | For non-anonymous file-sharing, loc-URIs are used to specify which | ||
| 1238 | peer is offering the data (in addition to specifying all of the | ||
| 1239 | data from a chk-URI). Location identifiers include a digital | ||
| 1240 | signature of the peer to affirm that the peer is truly the | ||
| 1241 | origin of the data. The format is | ||
| 1242 | "gnunet://fs/loc/KEYHASH.QUERYHASH.SIZE.PEER.SIG.EXPTIME". | ||
| 1243 | Here, "PEER" is the public key of the peer (in GNUnet format in | ||
| 1244 | base32hex), SIG is the RSA signature (in GNUnet format in | ||
| 1245 | base32hex) and EXPTIME specifies when the signature expires | ||
| 1246 | (in milliseconds after 1970). | ||
| 1247 | |||
| 1248 | @cindex ksk-uri | ||
| 1249 | @node Keyword queries (ksk) | ||
| 1250 | @subsubsection Keyword queries (ksk) | ||
| 1251 | @c %**end of header | ||
| 1252 | |||
| 1253 | A keyword-URI is used to specify that the desired operation | ||
| 1254 | is the search using a particular keyword. The format is simply | ||
| 1255 | "gnunet://fs/ksk/KEYWORD". Non-ASCII characters can be specified | ||
| 1256 | using the typical URI-encoding (using hex values) from HTTP. | ||
| 1257 | "+" can be used to specify multiple keywords (which are then | ||
| 1258 | logically "OR"-ed in the search, results matching both keywords | ||
| 1259 | are given a higher rank): "gnunet://fs/ksk/KEYWORD1+KEYWORD2". | ||
| 1260 | ksk-URIs must not begin or end with the plus ('+') character. | ||
| 1261 | Furthermore they must not contain '++'. | ||
| 1262 | |||
| 1263 | @cindex sks-uri | ||
| 1264 | @node Namespace content (sks) | ||
| 1265 | @subsubsection Namespace content (sks) | ||
| 1266 | @c %**end of header | ||
| 1267 | |||
| 1268 | @b{Please note that the text in this subsection is outdated and needs} | ||
| 1269 | @b{to be rewritten for version 0.10!} | ||
| 1270 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
| 1271 | |||
| 1272 | Namespaces are sets of files that have been approved by some (usually | ||
| 1273 | pseudonymous) user --- typically by that user publishing all of the | ||
| 1274 | files together. A file can be in many namespaces. A file is in a | ||
| 1275 | namespace if the owner of the ego (aka the namespace's private key) | ||
| 1276 | signs the CHK of the file cryptographically. An SKS-URI is used to | ||
| 1277 | search a namespace. The result is a block containing meta data, | ||
| 1278 | the CHK and the namespace owner's signature. The format of a sks-URI | ||
| 1279 | is "gnunet://fs/sks/NAMESPACE/IDENTIFIER". Here, "NAMESPACE" | ||
| 1280 | is the public key for the namespace. "IDENTIFIER" is a freely | ||
| 1281 | chosen keyword (or password!). A commonly used identifier is | ||
| 1282 | "root" which by convention refers to some kind of index or other | ||
| 1283 | entry point into the namespace. | ||
| 1284 | |||
| 1285 | @node GTK User Interface | ||
| 1286 | @subsection GTK User Interface | ||
| 1287 | This chapter describes first steps for file-sharing with GNUnet. | ||
| 1288 | To start, you should launch @command{gnunet-fs-gtk}. | ||
| 1289 | |||
| 1290 | As we want to be sure that the network contains the data that we are | ||
| 1291 | looking for for testing, we need to begin by publishing a file. | ||
| 1292 | |||
| 1293 | @menu | ||
| 1294 | * gtk-Publishing:: | ||
| 1295 | * gtk-Searching:: | ||
| 1296 | * gtk-Downloading:: | ||
| 1297 | @end menu | ||
| 1298 | |||
| 1299 | @node gtk-Publishing | ||
| 1300 | @subsubsection Publishing | ||
| 1301 | @c %**end of header | ||
| 1302 | |||
| 1303 | To publish a file, select "File Sharing" in the menu bar just below the | ||
| 1304 | "Statistics" icon, and then select "Publish" from the menu. | ||
| 1305 | |||
| 1306 | Afterwards, the following publishing dialog will appear: | ||
| 1307 | |||
| 1308 | @c Add image here | ||
| 1309 | |||
| 1310 | In this dialog, select the "Add File" button. This will open a | ||
| 1311 | file selection dialog: | ||
| 1312 | |||
| 1313 | @c Add image here | ||
| 1314 | |||
| 1315 | Now, you should select a file from your computer to be published on | ||
| 1316 | GNUnet. To see more of GNUnet's features later, you should pick a | ||
| 1317 | PNG or JPEG file this time. You can leave all of the other options | ||
| 1318 | in the dialog unchanged. Confirm your selection by pressing the "OK" | ||
| 1319 | button in the bottom right corner. Now, you will briefly see a | ||
| 1320 | "Messages..." dialog pop up, but most likely it will be too short for | ||
| 1321 | you to really read anything. That dialog is showing you progress | ||
| 1322 | information as GNUnet takes a first look at the selected file(s). | ||
| 1323 | For a normal image, this is virtually instant, but if you later | ||
| 1324 | import a larger directory you might be interested in the progress dialog | ||
| 1325 | and potential errors that might be encountered during processing. | ||
| 1326 | After the progress dialog automatically disappears, your file | ||
| 1327 | should now appear in the publishing dialog: | ||
| 1328 | |||
| 1329 | @c Add image here | ||
| 1330 | |||
| 1331 | Now, select the file (by clicking on the file name) and then click | ||
| 1332 | the "Edit" button. This will open the editing dialog: | ||
| 1333 | |||
| 1334 | @c Add image here | ||
| 1335 | |||
| 1336 | In this dialog, you can see many details about your file. In the | ||
| 1337 | top left area, you can see meta data extracted about the file, | ||
| 1338 | such as the original filename, the mimetype and the size of the image. | ||
| 1339 | In the top right, you should see a preview for the image | ||
| 1340 | (if GNU libextractor was installed correctly with the | ||
| 1341 | respective plugins). Note that if you do not see a preview, this | ||
| 1342 | is not a disaster, but you might still want to install more of | ||
| 1343 | GNU libextractor in the future. In the bottom left, the dialog contains | ||
| 1344 | a list of keywords. These are the keywords under which the file will be | ||
| 1345 | made available. The initial list will be based on the extracted meta data. | ||
| 1346 | Additional publishing options are in the right bottom corner. We will | ||
| 1347 | now add an additional keyword to the list of keywords. This is done by | ||
| 1348 | entering the keyword above the keyword list between the label "Keyword" | ||
| 1349 | and the "Add keyword" button. Enter "test" and select "Add keyword". | ||
| 1350 | Note that the keyword will appear at the bottom of the existing keyword | ||
| 1351 | list, so you might have to scroll down to see it. Afterwards, push the | ||
| 1352 | "OK" button at the bottom right of the dialog. | ||
| 1353 | |||
| 1354 | You should now be back at the "Publish content on GNUnet" dialog. Select | ||
| 1355 | "Execute" in the bottom right to close the dialog and publish your file | ||
| 1356 | on GNUnet! Afterwards, you should see the main dialog with a new area | ||
| 1357 | showing the list of published files (or ongoing publishing operations | ||
| 1358 | with progress indicators): | ||
| 1359 | |||
| 1360 | @c Add image here | ||
| 1361 | |||
| 1362 | @node gtk-Searching | ||
| 1363 | @subsubsection Searching | ||
| 1364 | @c %**end of header | ||
| 1365 | |||
| 1366 | Below the menu bar, there are four entry widges labeled "Namespace", | ||
| 1367 | "Keywords", "Anonymity" and "Mime-type" (from left to right). These | ||
| 1368 | widgets are used to control searching for files in GNUnet. Between the | ||
| 1369 | "Keywords" and "Anonymity" widgets, there is also a big "Search" button, | ||
| 1370 | which is used to initiate the search. We will ignore the "Namespace", | ||
| 1371 | "Anonymity" and "Mime-type" options in this tutorial, please leave them | ||
| 1372 | empty. Instead, simply enter "test" under "Keywords" and press "Search". | ||
| 1373 | Afterwards, you should immediately see a new tab labeled after your | ||
| 1374 | search term, followed by the (current) number of search | ||
| 1375 | results --- "(15)" in our screenshot. Note that your results may | ||
| 1376 | vary depending on what other users may have shared and how your | ||
| 1377 | peer is connected. | ||
| 1378 | |||
| 1379 | You can now select one of the search results. Once you do this, | ||
| 1380 | additional information about the result should be displayed on the | ||
| 1381 | right. If available, a preview image should appear on the top right. | ||
| 1382 | Meta data describing the file will be listed at the bottom right. | ||
| 1383 | |||
| 1384 | Once a file is selected, at the bottom of the search result list | ||
| 1385 | a little area for downloading appears. | ||
| 1386 | |||
| 1387 | @node gtk-Downloading | ||
| 1388 | @subsubsection Downloading | ||
| 1389 | @c %**end of header | ||
| 1390 | |||
| 1391 | In the downloading area, you can select the target directory (default is | ||
| 1392 | "Downloads") and specify the desired filename (by default the filename it | ||
| 1393 | taken from the meta data of the published file). Additionally, you can | ||
| 1394 | specify if the download should be anonymous and (for directories) if | ||
| 1395 | the download should be recursive. In most cases, you can simply start | ||
| 1396 | the download with the "Download!" button. | ||
| 1397 | |||
| 1398 | Once you selected download, the progress of the download will be | ||
| 1399 | displayed with the search result. You may need to resize the result | ||
| 1400 | list or scroll to the right. The "Status" column shows the current | ||
| 1401 | status of the download, and "Progress" how much has been completed. | ||
| 1402 | When you close the search tab (by clicking on the "X" button next to | ||
| 1403 | the "test" label), ongoing and completed downloads are not aborted | ||
| 1404 | but moved to a special "*" tab. | ||
| 1405 | |||
| 1406 | You can remove completed downloads from the "*" tab by clicking the | ||
| 1407 | cleanup button next to the "*". You can also abort downloads by right | ||
| 1408 | clicking on the respective download and selecting "Abort download" | ||
| 1409 | from the menu. | ||
| 1410 | |||
| 1411 | That's it, you now know the basics for file-sharing with GNUnet! | ||
| 1412 | |||
| 1413 | |||
| 1414 | @node The GNU Name System | ||
| 1415 | @section The GNU Name System | ||
| 1416 | @c %**end of header | ||
| 1417 | |||
| 1418 | |||
| 1419 | The GNU Name System (GNS) is secure and decentralized naming system. | ||
| 1420 | It allows its users to resolve and register names within the @code{.gnu} | ||
| 1421 | @dfn{top-level domain} (TLD). | ||
| 1422 | |||
| 1423 | GNS is designed to provide: | ||
| 1424 | @itemize @bullet | ||
| 1425 | @item Censorship resistance | ||
| 1426 | @item Query privacy | ||
| 1427 | @item Secure name resolution | ||
| 1428 | @item Compatibility with DNS | ||
| 1429 | @end itemize | ||
| 1430 | |||
| 1431 | For the initial configuration and population of your | ||
| 1432 | GNS installation, please follow the GNS setup instructions. | ||
| 1433 | The remainder of this chapter will provide some background on GNS | ||
| 1434 | and then describe how to use GNS in more detail. | ||
| 1435 | |||
| 1436 | Unlike DNS, GNS does not rely on central root zones or authorities. | ||
| 1437 | Instead any user administers their own root and can can create arbitrary | ||
| 1438 | name value mappings. Furthermore users can delegate resolution to other | ||
| 1439 | users' zones just like DNS NS records do. Zones are uniquely identified | ||
| 1440 | via public keys and resource records are signed using the corresponding | ||
| 1441 | public key. Delegation to another user's zone is done using special PKEY | ||
| 1442 | records and petnames. A petname is a name that can be freely chosen by | ||
| 1443 | the user. This results in non-unique name-value mappings as | ||
| 1444 | @code{@uref{http://www.bob.gnu/, www.bob.gnu}} to one user might be | ||
| 1445 | @code{@uref{http://www.friend.gnu/, www.friend.gnu}} for someone else. | ||
| 1446 | |||
| 1447 | |||
| 1448 | @menu | ||
| 1449 | * Creating a Zone:: | ||
| 1450 | * Maintaining your own Zones:: | ||
| 1451 | * Obtaining your Zone Key:: | ||
| 1452 | * Adding Links to Other Zones:: | ||
| 1453 | * Using Public Keys as Top Level Domains:: | ||
| 1454 | * Resource Records in GNS:: | ||
| 1455 | * Synchronizing with legacy DNS:: | ||
| 1456 | @end menu | ||
| 1457 | |||
| 1458 | |||
| 1459 | @node Creating a Zone | ||
| 1460 | @subsection Creating a Zone | ||
| 1461 | |||
| 1462 | To use GNS, you probably should create at least one zone of your own. | ||
| 1463 | You can create any number of zones using the gnunet-identity tool | ||
| 1464 | using: | ||
| 1465 | |||
| 1466 | @example | ||
| 1467 | $ gnunet-identity -C "myzone" | ||
| 1468 | @end example | ||
| 1469 | |||
| 1470 | Henceforth, on your system you control the TLD ``myzone''. | ||
| 1471 | |||
| 1472 | All of your zones can be listed (displayed) using the | ||
| 1473 | @command{gnunet-identity} command line tool as well: | ||
| 1474 | |||
| 1475 | @example | ||
| 1476 | $ gnunet-identity -d | ||
| 1477 | @end example | ||
| 1478 | |||
| 1479 | @node Maintaining your own Zones | ||
| 1480 | @subsection Maintaining your own Zones | ||
| 1481 | |||
| 1482 | @noindent | ||
| 1483 | Now you can add (or edit, or remove) records in your GNS zone using the | ||
| 1484 | @command{gnunet-namestore-gtk} GUI or using the @command{gnunet-namestore} | ||
| 1485 | command-line tool. | ||
| 1486 | In either case, your records will be stored in an SQL database under | ||
| 1487 | control of the @command{gnunet-service-namestore}. | ||
| 1488 | Note that if multiple users use one peer, the namestore database will | ||
| 1489 | include the combined records of all users. | ||
| 1490 | However, users will not be able to see each other's records | ||
| 1491 | if they are marked as private. | ||
| 1492 | |||
| 1493 | To provide a short example for editing your own zone, suppose you | ||
| 1494 | have your own web server with the IP @code{1.2.3.4}. Then you can put an | ||
| 1495 | @code{A} record (@code{A} records in DNS are for IPv4 IP addresses) | ||
| 1496 | into your local zone ``myzone'' using the command: | ||
| 1497 | |||
| 1498 | @example | ||
| 1499 | $ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e never | ||
| 1500 | @end example | ||
| 1501 | |||
| 1502 | @noindent | ||
| 1503 | Afterwards, you will be able to access your webpage under "www.myzone" | ||
| 1504 | (assuming your webserver does not use virtual hosting, if it does, | ||
| 1505 | please read up on setting up the GNS proxy). | ||
| 1506 | |||
| 1507 | Similar commands will work for other types of DNS and GNS records, | ||
| 1508 | the syntax largely depending on the type of the record. | ||
| 1509 | Naturally, most users may find editing the zones using the | ||
| 1510 | @command{gnunet-namestore-gtk} GUI to be easier. | ||
| 1511 | |||
| 1512 | @node Obtaining your Zone Key | ||
| 1513 | @subsection Obtaining your Zone Key | ||
| 1514 | |||
| 1515 | Each zone in GNS has a public-private key. Usually, gnunet-namestore and | ||
| 1516 | gnunet-setup will access your private key as necessary, so you do not | ||
| 1517 | have to worry about those. What is important is your public key | ||
| 1518 | (or rather, the hash of your public key), as you will likely want to | ||
| 1519 | give it to others so that they can securely link to you. | ||
| 1520 | |||
| 1521 | You can usually get the hash of your public key using | ||
| 1522 | |||
| 1523 | @example | ||
| 1524 | $ gnunet-identity -d $options | grep myzone | awk '@{print $3@}' | ||
| 1525 | @end example | ||
| 1526 | |||
| 1527 | @noindent | ||
| 1528 | For example, the output might be something like: | ||
| 1529 | |||
| 1530 | @example | ||
| 1531 | DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0 | ||
| 1532 | @end example | ||
| 1533 | |||
| 1534 | @noindent | ||
| 1535 | Alternatively, you can obtain a QR code with your zone key AND your | ||
| 1536 | pseudonym from gnunet-namestore-gtk. The QR code is displayed in the | ||
| 1537 | main window and can be stored to disk using the ``Save as'' button | ||
| 1538 | next to the image. | ||
| 1539 | |||
| 1540 | @node Adding Links to Other Zones | ||
| 1541 | @subsection Adding Links to Other Zones | ||
| 1542 | |||
| 1543 | |||
| 1544 | A central operation in GNS is the ability to securely delegate to | ||
| 1545 | other zones. Basically, by adding a delegation you make all of the | ||
| 1546 | names from the other zone available to yourself. This section | ||
| 1547 | describes how to create delegations. | ||
| 1548 | |||
| 1549 | Suppose you have a friend who you call 'bob' who also uses GNS. | ||
| 1550 | You can then delegate resolution of names to Bob's zone by adding | ||
| 1551 | a PKEY record to their local zone: | ||
| 1552 | |||
| 1553 | @example | ||
| 1554 | $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never -Z myzone | ||
| 1555 | @end example | ||
| 1556 | |||
| 1557 | @noindent | ||
| 1558 | Note that ``XXXX'' in the command above must be replaced with the hash | ||
| 1559 | of Bob's public key (the output your friend obtained using the | ||
| 1560 | @command{gnunet-identity} command from the previous section and told | ||
| 1561 | you, for example by giving you a business card containing this | ||
| 1562 | information as a QR code). | ||
| 1563 | |||
| 1564 | Assuming Bob has an ``A'' record for their website under the name of | ||
| 1565 | ``www'' in his zone, you can then access Bob's website under | ||
| 1566 | ``www.bob.myzone'' --- as well as any (public) GNS record that Bob has | ||
| 1567 | in their zone by replacing www with the respective name of the | ||
| 1568 | record in Bob's zone. | ||
| 1569 | |||
| 1570 | @c themselves? themself? | ||
| 1571 | Furthermore, if Bob has themselves a (public) delegation to Carol's | ||
| 1572 | zone under "carol", you can access Carol's records under | ||
| 1573 | ``NAME.carol.bob.myzone'' (where ``NAME'' is the name of Carol's | ||
| 1574 | record you want to access). | ||
| 1575 | |||
| 1576 | |||
| 1577 | @node Using Public Keys as Top Level Domains | ||
| 1578 | @subsection Using Public Keys as Top Level Domains | ||
| 1579 | |||
| 1580 | |||
| 1581 | GNS also assumes responsibility for any name that uses in a | ||
| 1582 | well-formed public key for the TLD. Names ending this way are then | ||
| 1583 | resolved by querying the respective zone. Such public key TLDs are | ||
| 1584 | expected to be used under rare circumstances where globally unique | ||
| 1585 | names are required, and for integration with legacy systems. | ||
| 1586 | |||
| 1587 | @node Resource Records in GNS | ||
| 1588 | @subsection Resource Records in GNS | ||
| 1589 | |||
| 1590 | |||
| 1591 | GNS supports the majority of the DNS records as defined in | ||
| 1592 | @uref{http://www.ietf.org/rfc/rfc1035.txt, RFC 1035}. Additionally, | ||
| 1593 | GNS defines some new record types the are unique to the GNS system. | ||
| 1594 | For example, GNS-specific resource records are used to give petnames | ||
| 1595 | for zone delegation, revoke zone keys and provide some compatibility | ||
| 1596 | features. | ||
| 1597 | |||
| 1598 | For some DNS records, GNS does extended processing to increase their | ||
| 1599 | usefulness in GNS. In particular, GNS introduces special names | ||
| 1600 | referred to as "zone relative names". Zone relative names are allowed | ||
| 1601 | in some resource record types (for example, in NS and CNAME records) | ||
| 1602 | and can also be used in links on webpages. Zone relative names end | ||
| 1603 | in ".+" which indicates that the name needs to be resolved relative | ||
| 1604 | to the current authoritative zone. The extended processing of those | ||
| 1605 | names will expand the ".+" with the correct delegation chain to the | ||
| 1606 | authoritative zone (replacing ".+" with the name of the location | ||
| 1607 | where the name was encountered) and hence generate a | ||
| 1608 | valid GNS name. | ||
| 1609 | |||
| 1610 | GNS currently supports the following record types: | ||
| 1611 | |||
| 1612 | @menu | ||
| 1613 | * NICK:: | ||
| 1614 | * PKEY:: | ||
| 1615 | * BOX:: | ||
| 1616 | * LEHO:: | ||
| 1617 | * VPN:: | ||
| 1618 | * A AAAA and TXT:: | ||
| 1619 | * CNAME:: | ||
| 1620 | * GNS2DNS:: | ||
| 1621 | * SOA SRV PTR and MX:: | ||
| 1622 | * PLACE:: | ||
| 1623 | * PHONE:: | ||
| 1624 | * ID ATTR:: | ||
| 1625 | * ID TOKEN:: | ||
| 1626 | * ID TOKEN METADATA:: | ||
| 1627 | * CREDENTIAL:: | ||
| 1628 | * POLICY:: | ||
| 1629 | * ATTRIBUTE:: | ||
| 1630 | * ABE KEY:: | ||
| 1631 | * ABE MASTER:: | ||
| 1632 | * RECLAIM OIDC CLIENT:: | ||
| 1633 | * RECLAIM OIDC REDIRECT:: | ||
| 1634 | @end menu | ||
| 1635 | |||
| 1636 | @node NICK | ||
| 1637 | @subsubsection NICK | ||
| 1638 | |||
| 1639 | A NICK record is used to give a zone a name. With a NICK record, you | ||
| 1640 | can essentially specify how you would like to be called. GNS expects | ||
| 1641 | this record under the empty label ``@@'' in the zone's database | ||
| 1642 | (NAMESTORE); however, it will then automatically be copied into each | ||
| 1643 | record set, so that clients never need to do a separate lookup to | ||
| 1644 | discover the NICK record. Also, users do not usually have to worry | ||
| 1645 | about setting the NICK record: it is automatically set to the local | ||
| 1646 | name of the TLD. | ||
| 1647 | |||
| 1648 | @b{Example}@ | ||
| 1649 | |||
| 1650 | @example | ||
| 1651 | Name: @@; RRType: NICK; Value: bob | ||
| 1652 | @end example | ||
| 1653 | |||
| 1654 | @noindent | ||
| 1655 | This record in Bob's zone will tell other users that this zone wants | ||
| 1656 | to be referred to as 'bob'. Note that nobody is obliged to call Bob's | ||
| 1657 | zone 'bob' in their own zones. It can be seen as a | ||
| 1658 | recommendation ("Please call this zone 'bob'"). | ||
| 1659 | |||
| 1660 | @node PKEY | ||
| 1661 | @subsubsection PKEY | ||
| 1662 | |||
| 1663 | PKEY records are used to add delegation to other users' zones and | ||
| 1664 | give those zones a petname. | ||
| 1665 | |||
| 1666 | @b{Example}@ | ||
| 1667 | |||
| 1668 | Let Bob's zone be identified by the hash "ABC012". Bob is your friend | ||
| 1669 | so you want to give them the petname "friend". Then you add the | ||
| 1670 | following record to your zone: | ||
| 1671 | |||
| 1672 | @example | ||
| 1673 | Name: friend; RRType: PKEY; Value: ABC012; | ||
| 1674 | @end example | ||
| 1675 | |||
| 1676 | @noindent | ||
| 1677 | This will allow you to resolve records in bob's zone | ||
| 1678 | under "*.friend.gnu". | ||
| 1679 | |||
| 1680 | @node BOX | ||
| 1681 | @subsubsection BOX | ||
| 1682 | |||
| 1683 | BOX records are there to integrate information from TLSA or | ||
| 1684 | SRV records under the main label. In DNS, TLSA and SRV records | ||
| 1685 | use special names of the form @code{_port._proto.(label.)*tld} to | ||
| 1686 | indicate the port number and protocol (i.e. tcp or udp) for which | ||
| 1687 | the TLSA or SRV record is valid. This causes various problems, and | ||
| 1688 | is elegantly solved in GNS by integrating the protocol and port | ||
| 1689 | numbers together with the respective value into a "BOX" record. | ||
| 1690 | Note that in the GUI, you do not get to edit BOX records directly | ||
| 1691 | right now --- the GUI will provide the illusion of directly | ||
| 1692 | editing the TLSA and SRV records, even though they internally | ||
| 1693 | are BOXed up. | ||
| 1694 | |||
| 1695 | @node LEHO | ||
| 1696 | @subsubsection LEHO | ||
| 1697 | |||
| 1698 | The LEgacy HOstname of a server. Some webservers expect a specific | ||
| 1699 | hostname to provide a service (virtiual hosting). Also SSL | ||
| 1700 | certificates usually contain DNS names. To provide the expected | ||
| 1701 | legacy DNS name for a server, the LEHO record can be used. | ||
| 1702 | To mitigate the just mentioned issues the GNS proxy has to be used. | ||
| 1703 | The GNS proxy will use the LEHO information to apply the necessary | ||
| 1704 | transformations. | ||
| 1705 | |||
| 1706 | @node VPN | ||
| 1707 | @subsubsection VPN | ||
| 1708 | |||
| 1709 | GNS allows easy access to services provided by the GNUnet Virtual Public | ||
| 1710 | Network. When the GNS resolver encounters a VPN record it will contact | ||
| 1711 | the VPN service to try and allocate an IPv4/v6 address (if the queries | ||
| 1712 | record type is an IP address) that can be used to contact the service. | ||
| 1713 | |||
| 1714 | @b{Example}@ | ||
| 1715 | |||
| 1716 | I want to provide access to the VPN service "web.gnu." on port 80 on peer | ||
| 1717 | ABC012:@ | ||
| 1718 | Name: www; RRType: VPN; Value: 80 ABC012 web.gnu. | ||
| 1719 | |||
| 1720 | The peer ABC012 is configured to provide an exit point for the service | ||
| 1721 | "web.gnu." on port 80 to it's server running locally on port 8080 by | ||
| 1722 | having the following lines in the @file{gnunet.conf} configuration file: | ||
| 1723 | |||
| 1724 | @example | ||
| 1725 | [web.gnunet.] | ||
| 1726 | TCP_REDIRECTS = 80:localhost4:8080 | ||
| 1727 | @end example | ||
| 1728 | |||
| 1729 | @node A AAAA and TXT | ||
| 1730 | @subsubsection A AAAA and TXT | ||
| 1731 | |||
| 1732 | Those records work in exactly the same fashion as in traditional DNS. | ||
| 1733 | |||
| 1734 | @node CNAME | ||
| 1735 | @subsubsection CNAME | ||
| 1736 | |||
| 1737 | As specified in RFC 1035 whenever a CNAME is encountered the query | ||
| 1738 | needs to be restarted with the specified name. In GNS a CNAME | ||
| 1739 | can either be: | ||
| 1740 | |||
| 1741 | @itemize @bullet | ||
| 1742 | @item A zone relative name, | ||
| 1743 | @item A zkey name or | ||
| 1744 | @item A DNS name (in which case resolution will continue outside | ||
| 1745 | of GNS with the systems DNS resolver) | ||
| 1746 | @end itemize | ||
| 1747 | |||
| 1748 | @node GNS2DNS | ||
| 1749 | @subsubsection GNS2DNS | ||
| 1750 | |||
| 1751 | GNS can delegate authority to a legacy DNS zone. For this, the | ||
| 1752 | name of the DNS nameserver and the name of the DNS zone are | ||
| 1753 | specified in a GNS2DNS record. | ||
| 1754 | |||
| 1755 | @b{Example} | ||
| 1756 | |||
| 1757 | @example | ||
| 1758 | Name: pet; RRType: GNS2DNS; Value: gnunet.org@@a.ns.joker.com | ||
| 1759 | @end example | ||
| 1760 | |||
| 1761 | @noindent | ||
| 1762 | Any query to @code{pet.gnu} will then be delegated to the DNS server at | ||
| 1763 | @code{a.ns.joker.com}. For example, | ||
| 1764 | @code{@uref{http://www.pet.gnu/, www.pet.gnu}} will result in a DNS query | ||
| 1765 | for @code{@uref{http://www.gnunet.org/, www.gnunet.org}} to the server | ||
| 1766 | at @code{a.ns.joker.com}. Delegation to DNS via NS records in GNS can | ||
| 1767 | be useful if you do not want to start resolution in the DNS root zone | ||
| 1768 | (due to issues such as censorship or availability). | ||
| 1769 | |||
| 1770 | Note that you would typically want to use a relative name for the | ||
| 1771 | nameserver, i.e. | ||
| 1772 | |||
| 1773 | @example | ||
| 1774 | Name: pet; RRType: GNS2DNS; Value: gnunet.org@@ns-joker.+@ | ||
| 1775 | Name: ns-joker; RRType: A; Value: 184.172.157.218 | ||
| 1776 | @end example | ||
| 1777 | |||
| 1778 | @noindent | ||
| 1779 | This way, you can avoid involving the DNS hierarchy in the resolution of | ||
| 1780 | @code{a.ns.joker.com}. In the example above, the problem may not be | ||
| 1781 | obvious as the nameserver for "gnunet.org" is in the ".com" zone. | ||
| 1782 | However, imagine the nameserver was "ns.gnunet.org". In this case, | ||
| 1783 | delegating to "ns.gnunet.org" would mean that despite using GNS, | ||
| 1784 | censorship in the DNS ".org" zone would still be effective. | ||
| 1785 | |||
| 1786 | @node SOA SRV PTR and MX | ||
| 1787 | @subsubsection SOA SRV PTR and MX | ||
| 1788 | |||
| 1789 | The domain names in those records can, again, be either | ||
| 1790 | |||
| 1791 | @itemize @bullet | ||
| 1792 | @item A zone relative name, | ||
| 1793 | @item A zkey name or | ||
| 1794 | @item A DNS name | ||
| 1795 | @end itemize | ||
| 1796 | |||
| 1797 | The resolver will expand the zone relative name if possible. | ||
| 1798 | Note that when using MX records within GNS, the target mail | ||
| 1799 | server might still refuse to accept e-mails to the resulting | ||
| 1800 | domain as the name might not match. GNS-enabled mail clients | ||
| 1801 | should use the ZKEY zone as the destination hostname and | ||
| 1802 | GNS-enabled mail servers should be configured to accept | ||
| 1803 | e-mails to the ZKEY-zones of all local users. | ||
| 1804 | |||
| 1805 | @node PLACE | ||
| 1806 | @subsubsection PLACE | ||
| 1807 | |||
| 1808 | Record type for a social place. | ||
| 1809 | |||
| 1810 | @node PHONE | ||
| 1811 | @subsubsection PHONE | ||
| 1812 | |||
| 1813 | Record type for a phone (of CONVERSATION). | ||
| 1814 | |||
| 1815 | @node ID ATTR | ||
| 1816 | @subsubsection ID ATTR | ||
| 1817 | |||
| 1818 | Record type for identity attributes (of IDENTITY). | ||
| 1819 | |||
| 1820 | @node ID TOKEN | ||
| 1821 | @subsubsection ID TOKEN | ||
| 1822 | |||
| 1823 | Record type for an identity token (of IDENTITY-TOKEN). | ||
| 1824 | |||
| 1825 | @node ID TOKEN METADATA | ||
| 1826 | @subsubsection ID TOKEN METADATA | ||
| 1827 | |||
| 1828 | Record type for the private metadata of an identity token (of IDENTITY-TOKEN). | ||
| 1829 | |||
| 1830 | @node CREDENTIAL | ||
| 1831 | @subsubsection CREDENTIAL | ||
| 1832 | |||
| 1833 | Record type for credential. | ||
| 1834 | |||
| 1835 | @node POLICY | ||
| 1836 | @subsubsection POLICY | ||
| 1837 | |||
| 1838 | Record type for policies. | ||
| 1839 | |||
| 1840 | @node ATTRIBUTE | ||
| 1841 | @subsubsection ATTRIBUTE | ||
| 1842 | |||
| 1843 | Record type for reverse lookups. | ||
| 1844 | |||
| 1845 | @node ABE KEY | ||
| 1846 | @subsubsection ABE KEY | ||
| 1847 | |||
| 1848 | Record type for ABE records. | ||
| 1849 | |||
| 1850 | @node ABE MASTER | ||
| 1851 | @subsubsection ABE MASTER | ||
| 1852 | |||
| 1853 | Record type for ABE master keys. | ||
| 1854 | |||
| 1855 | @node RECLAIM OIDC CLIENT | ||
| 1856 | @subsubsection RECLAIM OIDC CLIENT | ||
| 1857 | |||
| 1858 | Record type for reclaim OIDC clients. | ||
| 1859 | |||
| 1860 | @node RECLAIM OIDC REDIRECT | ||
| 1861 | @subsubsection RECLAIM OIDC REDIRECT | ||
| 1862 | |||
| 1863 | Record type for reclaim OIDC redirect URIs. | ||
| 1864 | |||
| 1865 | @node Synchronizing with legacy DNS | ||
| 1866 | @subsection Synchronizing with legacy DNS | ||
| 1867 | |||
| 1868 | If you want to support GNS but the master database for a zone | ||
| 1869 | is only available and maintained in DNS, GNUnet includes the | ||
| 1870 | @command{gnunet-zoneimport} tool to monitor a DNS zone and | ||
| 1871 | automatically import records into GNS. Today, the tool does | ||
| 1872 | not yet support DNS AF(X)R, as we initially used it on the | ||
| 1873 | ``.fr'' zone which does not allow us to perform a DNS zone | ||
| 1874 | transfer. Instead, @command{gnunet-zoneimport} reads a list | ||
| 1875 | of DNS domain names from @code{stdin}, issues DNS queries for | ||
| 1876 | each, converts the obtained records (if possible) and stores | ||
| 1877 | the result in the namestore. | ||
| 1878 | |||
| 1879 | @image{images/gns,6in,, picture of DNS-GNS data flow} | ||
| 1880 | |||
| 1881 | The zonemaster service then takes the records from the namestore, | ||
| 1882 | publishes them into the DHT which makes the result available to the | ||
| 1883 | GNS resolver. In the GNS configuration, non-local zones can be | ||
| 1884 | configured to be intercepted by specifying ``.tld = PUBLICKEY'' in the | ||
| 1885 | configuration file in the ``[gns]'' section. | ||
| 1886 | |||
| 1887 | Note that the namestore by default also populates the namecache. | ||
| 1888 | This pre-population is cryptographically expensive. Thus, on | ||
| 1889 | systems that only serve to import a large (millions of records) | ||
| 1890 | DNS zone and that do not have a local gns service in use, it | ||
| 1891 | is thus advisable to disable the namecache by setting the | ||
| 1892 | option ``DISABLE'' to ``YES'' in section ``[namecache]''. | ||
| 1893 | |||
| 1894 | |||
| 1895 | @node re@:claim Identity Provider | ||
| 1896 | @section re@:claim Identity Provider | ||
| 1897 | |||
| 1898 | The re:claim Identity Provider (IdP) is a decentralized IdP service. | ||
| 1899 | It allows its users to manage and authorize third parties to access their identity attributes such as email or shipping addresses. | ||
| 1900 | |||
| 1901 | It basically mimics the concepts of centralized IdPs, such as those offered by Google or Facebook. | ||
| 1902 | Like other IdPs, re:claim features an (optional) OpenID-Connect 1.0-compliant protocol layer that can be used for websites to integrate re:claim as an Identity Provider with little effort. | ||
| 1903 | |||
| 1904 | @menu | ||
| 1905 | * Managing Attributes:: | ||
| 1906 | * Sharing Attributes with Third Parties:: | ||
| 1907 | * Revoking Authorizations of Third Parties:: | ||
| 1908 | * Using the OpenID-Connect IdP:: | ||
| 1909 | @end menu | ||
| 1910 | |||
| 1911 | @node Managing Attributes | ||
| 1912 | @subsection Managing Attributes | ||
| 1913 | |||
| 1914 | Before adding attributes to an identity, you must first create an ego: | ||
| 1915 | |||
| 1916 | @example | ||
| 1917 | $ gnunet-identity -C "username" | ||
| 1918 | @end example | ||
| 1919 | |||
| 1920 | Henceforth, you can manage a new user profile of the user ``username''. | ||
| 1921 | |||
| 1922 | To add an email address to your user profile, simply use the @command{gnunet-reclaim} command line tool:: | ||
| 1923 | |||
| 1924 | @example | ||
| 1925 | $ gnunet-reclaim -e "username" -a "email" -V "username@@example.gnunet" | ||
| 1926 | @end example | ||
| 1927 | |||
| 1928 | All of your attributes can be listed using the @command{gnunet-reclaim} | ||
| 1929 | command line tool as well: | ||
| 1930 | |||
| 1931 | @example | ||
| 1932 | $ gnunet-reclaim -e "username" -D | ||
| 1933 | @end example | ||
| 1934 | |||
| 1935 | Currently, and by default, attribute values are interpreted as plain text. | ||
| 1936 | In the future there might be more value types such as X.509 certificate credentials. | ||
| 1937 | |||
| 1938 | @node Sharing Attributes with Third Parties | ||
| 1939 | @subsection Sharing Attributes with Third Parties | ||
| 1940 | |||
| 1941 | If you want to allow a third party such as a website or friend to access to your attributes (or a subset thereof) execute: | ||
| 1942 | |||
| 1943 | @example | ||
| 1944 | $ gnunet-reclaim -e "username" -r "PKEY" -i "attribute1,attribute2,..." | ||
| 1945 | @end example | ||
| 1946 | |||
| 1947 | Where "PKEY" is the public key of the third party and "attribute1,attribute2,..." is a comma-separated list of attribute names, such as "email", that you want to share. | ||
| 1948 | |||
| 1949 | The command will return a "ticket" string. | ||
| 1950 | You must give this "ticket" to the requesting third party. | ||
| 1951 | |||
| 1952 | The third party can then retrieve your shared identity attributes using: | ||
| 1953 | |||
| 1954 | @example | ||
| 1955 | $ gnunet-reclaim -e "friend" -C "ticket" | ||
| 1956 | @end example | ||
| 1957 | |||
| 1958 | This will retrieve and list the shared identity attributes. | ||
| 1959 | The above command will also work if the user "username" is currently offline since the attributes are retrieved from GNS. | ||
| 1960 | Further, the "ticket" can be re-used later to retrieve up-to-date attributes in case "username" has changed the value(s). For instance, becasue his email address changed. | ||
| 1961 | |||
| 1962 | To list all given authorizations (tickets) you can execute: | ||
| 1963 | @example | ||
| 1964 | $ gnunet-reclaim -e "friend" -T (TODO there is only a REST API for this ATM) | ||
| 1965 | @end example | ||
| 1966 | |||
| 1967 | |||
| 1968 | @node Revoking Authorizations of Third Parties | ||
| 1969 | @subsection Revoking Authorizations of Third Parties | ||
| 1970 | |||
| 1971 | If you want to revoke the access of a third party to your attributes you can execute: | ||
| 1972 | |||
| 1973 | @example | ||
| 1974 | $ gnunet-reclaim -e "username" -R "ticket" | ||
| 1975 | @end example | ||
| 1976 | |||
| 1977 | This will prevent the third party from accessing the attribute in the future. | ||
| 1978 | Please note that if the third party has previously accessed the attribute, there is not way in which the system could have prevented the thiry party from storing the data. | ||
| 1979 | As such, only access to updated data in the future can be revoked. | ||
| 1980 | This behaviour is _exactly the same_ as with other IdPs. | ||
| 1981 | |||
| 1982 | @node Using the OpenID-Connect IdP | ||
| 1983 | @subsection Using the OpenID-Connect IdP | ||
| 1984 | |||
| 1985 | @menu | ||
| 1986 | * Setting up reclaim.io:: | ||
| 1987 | * For Users:: | ||
| 1988 | * For Service Providers:: | ||
| 1989 | @end menu | ||
| 1990 | |||
| 1991 | |||
| 1992 | @node Setting up reclaim.io | ||
| 1993 | @subsubsection Setting up reclaim.io | ||
| 1994 | |||
| 1995 | @example | ||
| 1996 | $ gnunet-identity -C id | ||
| 1997 | $ openssl genrsa -des3 -passout pass:xxxx -out server.pass.key 2048 | ||
| 1998 | $ openssl rsa -passin pass:xxxx -in server.pass.key -out /etc/reclaim/reclaim.id.key | ||
| 1999 | $ rm server.pass.key | ||
| 2000 | $ openssl req -new -key /etc/reclaim/reclaim.id.key -out server.csr \ | ||
| 2001 | -subj "/CN=reclaim.id.local" | ||
| 2002 | $ openssl x509 -req -days 365 -in server.csr -signkey /etc/reclaim/reclaim.id.key -out /etc/reclaim/reclaim.id.crt | ||
| 2003 | $ openssl x509 -in /etc/reclaim/reclaim.id.crt -out /etc/reclaim/reclaim.id.der -outform DER | ||
| 2004 | $ HEXCERT=`xxd -p /etc/reclaim/reclaim.id.der | tr -d '\n'` | ||
| 2005 | $ BOXVALUE="6 443 52 3 0 0 $HEXCERT" | ||
| 2006 | $ gnunet-namestore -z id -a -n reclaim -t A -V "127.0.0.1" -e 1d -p | ||
| 2007 | $ gnunet-namestore -z id -a -n reclaim -t LEHO -V "reclaim.id.local" -e 1d -p | ||
| 2008 | $ gnunet-namestore -z id -a -n reclaim -t BOX -V "$BOXVALUE" -e 1d -p | ||
| 2009 | @end example | ||
| 2010 | |||
| 2011 | NGINX setup: | ||
| 2012 | @example | ||
| 2013 | server @{ | ||
| 2014 | listen 443; | ||
| 2015 | server_name reclaim.id.local; | ||
| 2016 | ssl on; | ||
| 2017 | ssl_certificate /etc/reclaim/reclaim.id.crt; | ||
| 2018 | ssl_certificate_key /etc/reclaim/reclaim.id.key; | ||
| 2019 | ssl_session_timeout 30m; | ||
| 2020 | ssl_protocols TLSv1 TLSv1.1 TLSv1.2; | ||
| 2021 | ssl_session_cache shared:SSL:10m; | ||
| 2022 | |||
| 2023 | location /api @{ | ||
| 2024 | rewrite /api/(.*) /$1 break; | ||
| 2025 | proxy_pass http://127.0.0.1:7776; | ||
| 2026 | @} | ||
| 2027 | @} | ||
| 2028 | @end example | ||
| 2029 | |||
| 2030 | This will expose the REST API of GNUnet at https://reclaim.id/api. | ||
| 2031 | |||
| 2032 | @node For Users | ||
| 2033 | @subsubsection For Users | ||
| 2034 | |||
| 2035 | To use the OpenID Connect Identity Provider as an end user, you must first intall the User Interface from TODOINSERTURLHERE. | ||
| 2036 | |||
| 2037 | Start the user interface using: | ||
| 2038 | |||
| 2039 | @example | ||
| 2040 | $ yarn run build --prod | ||
| 2041 | @end example | ||
| 2042 | |||
| 2043 | Now setup a webserver to serve the compiled website under "dist/". | ||
| 2044 | |||
| 2045 | Now we can add the user interfce to our NGINX configuraiton: | ||
| 2046 | |||
| 2047 | @example | ||
| 2048 | server @{ | ||
| 2049 | ... | ||
| 2050 | location / @{ | ||
| 2051 | proxy_pass http://<whereever you serve the UI>; | ||
| 2052 | @} | ||
| 2053 | @} | ||
| 2054 | @end example | ||
| 2055 | |||
| 2056 | You can thest your setup by accessing https://reclaim.id in your browser through the GNS proxy. | ||
| 2057 | |||
| 2058 | @node For Service Providers | ||
| 2059 | @subsubsection For Service Providers | ||
| 2060 | |||
| 2061 | To setup an OpenID Connect client, it must first be registered. | ||
| 2062 | In reclaim, client registration is done by creating a client identity and adding the redirect URI and client description into its namespace: | ||
| 2063 | |||
| 2064 | @example | ||
| 2065 | $ gnunet-identity -C <rp_name> | ||
| 2066 | $ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p | ||
| 2067 | $ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p | ||
| 2068 | @end example | ||
| 2069 | |||
| 2070 | You can now use the OpenID Connect REST endpoints exposed by reclaim. | ||
| 2071 | |||
| 2072 | To request authorization from a user, your webapplication should initiate the OpenID Connect Authorization Flow like this: | ||
| 2073 | @example | ||
| 2074 | $ https://reclaim.id/openid/authorize?redirect_uri=<redirect_uri>&client_id=<RP_PKEY>&response_type=code&nonce=1234&scope=attribute1 attribute2 ... | ||
| 2075 | @end example | ||
| 2076 | |||
| 2077 | You should choose a random number for the nonce parameter. The RP_KEY is the public key corresponding to the <rp_name> identity. | ||
| 2078 | |||
| 2079 | The redirect URI is the URI that you expect the user to return to within the OpenID Connect authorization code flow. | ||
| 2080 | |||
| 2081 | When the user returns to your redirect URI, you can exchange it for an access token at the OpenID Token endpoint. | ||
| 2082 | The authentication at the token endpoint is performed using the configured password (PSW) in the reclaim configuration (reclaim.conf). To set it execute: | ||
| 2083 | |||
| 2084 | @example | ||
| 2085 | $ gnunet-config -s reclaim-rest-plugin -o PSW -V <secret> | ||
| 2086 | @end example | ||
| 2087 | |||
| 2088 | To retrieve the access token, you can access the token endpoint through the proxy like this: | ||
| 2089 | |||
| 2090 | @example | ||
| 2091 | $ curl --socks5-hostname 127.0.0.1:7777 \ | ||
| 2092 | -X POST \ | ||
| 2093 | https://reclaim.id/openid/token?grant_type=authorization_code&redirect_uri=<redirect_uri>&code=<code> \ | ||
| 2094 | -u <RP_KEY>:<secret> | ||
| 2095 | @end example | ||
| 2096 | |||
| 2097 | If successful, this will return a JSON object containing an ID Token and Access Token. | ||
| 2098 | The Access Token can be used to access the OpenID Connect userinfo endpoint: | ||
| 2099 | |||
| 2100 | @example | ||
| 2101 | $ curl --socks5-hostname 127.0.0.1:7777 \ | ||
| 2102 | -X POST \ | ||
| 2103 | https://reclaim.id/openid/userinfo\ | ||
| 2104 | -H 'Authorization: Bearer <access_token>' | ||
| 2105 | @end example | ||
| 2106 | |||
| 2107 | |||
| 2108 | |||
| 2109 | @node Using the Virtual Public Network | ||
| 2110 | @section Using the Virtual Public Network | ||
| 2111 | |||
| 2112 | @menu | ||
| 2113 | * Setting up an Exit node:: | ||
| 2114 | * Fedora and the Firewall:: | ||
| 2115 | * Setting up VPN node for protocol translation and tunneling:: | ||
| 2116 | @end menu | ||
| 2117 | |||
| 2118 | Using the GNUnet Virtual Public Network (VPN) application you can | ||
| 2119 | tunnel IP traffic over GNUnet. Moreover, the VPN comes | ||
| 2120 | with built-in protocol translation and DNS-ALG support, enabling | ||
| 2121 | IPv4-to-IPv6 protocol translation (in both directions). | ||
| 2122 | This chapter documents how to use the GNUnet VPN. | ||
| 2123 | |||
| 2124 | The first thing to note about the GNUnet VPN is that it is a public | ||
| 2125 | network. All participating peers can participate and there is no | ||
| 2126 | secret key to control access. So unlike common virtual private | ||
| 2127 | networks, the GNUnet VPN is not useful as a means to provide a | ||
| 2128 | "private" network abstraction over the Internet. The GNUnet VPN | ||
| 2129 | is a virtual network in the sense that it is an overlay over the | ||
| 2130 | Internet, using its own routing mechanisms and can also use an | ||
| 2131 | internal addressing scheme. The GNUnet VPN is an Internet | ||
| 2132 | underlay --- TCP/IP applications run on top of it. | ||
| 2133 | |||
| 2134 | The VPN is currently only supported on GNU/Linux systems. | ||
| 2135 | Support for operating systems that support TUN (such as FreeBSD) | ||
| 2136 | should be easy to add (or might not even require any coding at | ||
| 2137 | all --- we just did not test this so far). Support for other | ||
| 2138 | operating systems would require re-writing the code to create virtual | ||
| 2139 | network interfaces and to intercept DNS requests. | ||
| 2140 | |||
| 2141 | The VPN does not provide good anonymity. While requests are routed | ||
| 2142 | over the GNUnet network, other peers can directly see the source | ||
| 2143 | and destination of each (encapsulated) IP packet. Finally, if you | ||
| 2144 | use the VPN to access Internet services, the peer sending the | ||
| 2145 | request to the Internet will be able to observe and even alter | ||
| 2146 | the IP traffic. We will discuss additional security implications | ||
| 2147 | of using the VPN later in this chapter. | ||
| 2148 | |||
| 2149 | @node Setting up an Exit node | ||
| 2150 | @subsection Setting up an Exit node | ||
| 2151 | |||
| 2152 | Any useful operation with the VPN requires the existence of an exit | ||
| 2153 | node in the GNUnet Peer-to-Peer network. Exit functionality can only | ||
| 2154 | be enabled on peers that have regular Internet access. If you want | ||
| 2155 | to play around with the VPN or support the network, we encourage | ||
| 2156 | you to setup exit nodes. This chapter documents how to setup an | ||
| 2157 | exit node. | ||
| 2158 | |||
| 2159 | There are four types of exit functions an exit node can provide, | ||
| 2160 | and using the GNUnet VPN to access the Internet will only work | ||
| 2161 | nicely if the first three types are provided somewhere in | ||
| 2162 | the network. The four exit functions are: | ||
| 2163 | |||
| 2164 | @itemize @bullet | ||
| 2165 | @item DNS: allow other peers to use your DNS resolver | ||
| 2166 | @item IPv4: allow other peers to access your IPv4 Internet connection | ||
| 2167 | @item IPv6: allow other peers to access your IPv6 Internet connection | ||
| 2168 | @item Local service: allow other peers to access a specific TCP or | ||
| 2169 | UDP service your peer is providing | ||
| 2170 | @end itemize | ||
| 2171 | |||
| 2172 | By enabling "exit" in gnunet-setup and checking the respective boxes | ||
| 2173 | in the "exit" tab, you can easily choose which of the above exit | ||
| 2174 | functions you want to support. | ||
| 2175 | |||
| 2176 | Note, however, that by supporting the first three functions you will | ||
| 2177 | allow arbitrary other GNUnet users to access the Internet via your | ||
| 2178 | system. This is somewhat similar to running a Tor exit node. The | ||
| 2179 | Torproject has a nice article about what to consider if you want | ||
| 2180 | to do this here. We believe that generally running a DNS exit node | ||
| 2181 | is completely harmless. | ||
| 2182 | |||
| 2183 | The exit node configuration does currently not allow you to restrict the | ||
| 2184 | Internet traffic that leaves your system. In particular, you cannot | ||
| 2185 | exclude SMTP traffic (or block port 25) or limit to HTTP traffic using | ||
| 2186 | the GNUnet configuration. However, you can use your host firewall to | ||
| 2187 | restrict outbound connections from the virtual tunnel interface. This | ||
| 2188 | is highly recommended. In the future, we plan to offer a wider range | ||
| 2189 | of configuration options for exit nodes. | ||
| 2190 | |||
| 2191 | Note that by running an exit node GNUnet will configure your kernel | ||
| 2192 | to perform IP-forwarding (for IPv6) and NAT (for IPv4) so that the | ||
| 2193 | traffic from the virtual interface can be routed to the Internet. | ||
| 2194 | In order to provide an IPv6-exit, you need to have a subnet routed | ||
| 2195 | to your host's external network interface and assign a subrange of | ||
| 2196 | that subnet to the GNUnet exit's TUN interface. | ||
| 2197 | |||
| 2198 | When running a local service, you should make sure that the local | ||
| 2199 | service is (also) bound to the IP address of your EXIT interface | ||
| 2200 | (i.e. 169.254.86.1). It will NOT work if your local service is | ||
| 2201 | just bound to loopback. You may also want to create a "VPN" record | ||
| 2202 | in your zone of the GNU Name System to make it easy for others to | ||
| 2203 | access your service via a name instead of just the full service | ||
| 2204 | descriptor. Note that the identifier you assign the service can | ||
| 2205 | serve as a passphrase or shared secret, clients connecting to the | ||
| 2206 | service must somehow learn the service's name. VPN records in the | ||
| 2207 | GNU Name System can make this easier. | ||
| 2208 | |||
| 2209 | @node Fedora and the Firewall | ||
| 2210 | @subsection Fedora and the Firewall | ||
| 2211 | |||
| 2212 | |||
| 2213 | When using an exit node on Fedora 15, the standard firewall can | ||
| 2214 | create trouble even when not really exiting the local system! | ||
| 2215 | For IPv4, the standard rules seem fine. However, for IPv6 the | ||
| 2216 | standard rules prohibit traffic from the network range of the | ||
| 2217 | virtual interface created by the exit daemon to the local IPv6 | ||
| 2218 | address of the same interface (which is essentially loopback | ||
| 2219 | traffic, so you might suspect that a standard firewall would | ||
| 2220 | leave this traffic alone). However, as somehow for IPv6 the | ||
| 2221 | traffic is not recognized as originating from the local | ||
| 2222 | system (and as the connection is not already "established"), | ||
| 2223 | the firewall drops the traffic. You should still get ICMPv6 | ||
| 2224 | packets back, but that's obviously not very useful. | ||
| 2225 | |||
| 2226 | Possible ways to fix this include disabling the firewall (do you | ||
| 2227 | have a good reason for having it on?) or disabling the firewall | ||
| 2228 | at least for the GNUnet exit interface (or the respective | ||
| 2229 | IPv4/IPv6 address range). The best way to diagnose these kinds | ||
| 2230 | of problems in general involves setting the firewall to REJECT | ||
| 2231 | instead of DROP and to watch the traffic using wireshark | ||
| 2232 | (or tcpdump) to see if ICMP messages are generated when running | ||
| 2233 | some tests that should work. | ||
| 2234 | |||
| 2235 | @node Setting up VPN node for protocol translation and tunneling | ||
| 2236 | @subsection Setting up VPN node for protocol translation and tunneling | ||
| 2237 | |||
| 2238 | |||
| 2239 | The GNUnet VPN/PT subsystem enables you to tunnel IP traffic over the | ||
| 2240 | VPN to an exit node, from where it can then be forwarded to the | ||
| 2241 | Internet. This section documents how to setup VPN/PT on a node. | ||
| 2242 | Note that you can enable both the VPN and an exit on the same peer. | ||
| 2243 | In this case, IP traffic from your system may enter your peer's VPN | ||
| 2244 | and leave your peer's exit. This can be useful as a means to do | ||
| 2245 | protocol translation. For example, you might have an application that | ||
| 2246 | supports only IPv4 but needs to access an IPv6-only site. In this case, | ||
| 2247 | GNUnet would perform 4to6 protocol translation between the VPN (IPv4) | ||
| 2248 | and the Exit (IPv6). Similarly, 6to4 protocol translation is also | ||
| 2249 | possible. However, the primary use for GNUnet would be to access | ||
| 2250 | an Internet service running with an IP version that is not supported | ||
| 2251 | by your ISP. In this case, your IP traffic would be routed via GNUnet | ||
| 2252 | to a peer that has access to the Internet with the desired IP version. | ||
| 2253 | |||
| 2254 | Setting up an entry node into the GNUnet VPN primarily requires you | ||
| 2255 | to enable the "VPN/PT" option in "gnunet-setup". This will launch the | ||
| 2256 | "gnunet-service-vpn", "gnunet-service-dns" and "gnunet-daemon-pt" | ||
| 2257 | processes. The "gnunet-service-vpn" will create a virtual interface | ||
| 2258 | which will be used as the target for your IP traffic that enters the | ||
| 2259 | VPN. Additionally, a second virtual interface will be created by | ||
| 2260 | the "gnunet-service-dns" for your DNS traffic. You will then need to | ||
| 2261 | specify which traffic you want to tunnel over GNUnet. If your ISP only | ||
| 2262 | provides you with IPv4 or IPv6-access, you may choose to tunnel the | ||
| 2263 | other IP protocol over the GNUnet VPN. If you do not have an ISP | ||
| 2264 | (and are connected to other GNUnet peers via WLAN), you can also | ||
| 2265 | choose to tunnel all IP traffic over GNUnet. This might also provide | ||
| 2266 | you with some anonymity. After you enable the respective options | ||
| 2267 | and restart your peer, your Internet traffic should be tunneled | ||
| 2268 | over the GNUnet VPN. | ||
| 2269 | |||
| 2270 | The GNUnet VPN uses DNS-ALG to hijack your IP traffic. Whenever an | ||
| 2271 | application resolves a hostname (i.e. 'gnunet.org'), the | ||
| 2272 | "gnunet-daemon-pt" will instruct the "gnunet-service-dns" to intercept | ||
| 2273 | the request (possibly route it over GNUnet as well) and replace the | ||
| 2274 | normal answer with an IP in the range of the VPN's interface. | ||
| 2275 | "gnunet-daemon-pt" will then tell "gnunet-service-vpn" to forward all | ||
| 2276 | traffic it receives on the TUN interface via the VPN to the original | ||
| 2277 | destination. | ||
| 2278 | |||
| 2279 | For applications that do not use DNS, you can also manually create | ||
| 2280 | such a mapping using the gnunet-vpn command-line tool. Here, you | ||
| 2281 | specify the desired address family of the result (i.e. "-4"), and the | ||
| 2282 | intended target IP on the Internet ("-i 131.159.74.67") and | ||
| 2283 | "gnunet-vpn" will tell you which IP address in the range of your | ||
| 2284 | VPN tunnel was mapped. | ||
| 2285 | |||
| 2286 | @command{gnunet-vpn} can also be used to access "internal" services | ||
| 2287 | offered by GNUnet nodes. So if you happen to know a peer and a | ||
| 2288 | service offered by that peer, you can create an IP tunnel to | ||
| 2289 | that peer by specifying the peer's identity, service name and | ||
| 2290 | protocol (--tcp or --udp) and you will again receive an IP address | ||
| 2291 | that will terminate at the respective peer's service. | ||
| 2292 | |||
| 2293 | |||
diff --git a/doc/documentation/chapters/vocabulary.texi b/doc/documentation/chapters/vocabulary.texi deleted file mode 100644 index 0ee472b95..000000000 --- a/doc/documentation/chapters/vocabulary.texi +++ /dev/null | |||
| @@ -1,72 +0,0 @@ | |||
| 1 | @node Vocabulary | ||
| 2 | @chapter Vocabulary | ||
| 3 | |||
| 4 | @menu | ||
| 5 | * Definitions abbreviations and acronyms:: | ||
| 6 | * Words and characters:: | ||
| 7 | * Technical Assumptions:: | ||
| 8 | @end menu | ||
| 9 | |||
| 10 | Throughout this Reference Manual we will use certain words and characters | ||
| 11 | which are listed in this introductionary chapter. | ||
| 12 | |||
| 13 | @node Definitions abbreviations and acronyms | ||
| 14 | @section Definitions abbreviations and acronyms | ||
| 15 | |||
| 16 | @menu | ||
| 17 | * Definitions:: | ||
| 18 | @end menu | ||
| 19 | |||
| 20 | @node Definitions | ||
| 21 | @subsection Definitions | ||
| 22 | |||
| 23 | Throughout this Reference Manual, the following terms and definitions | ||
| 24 | apply. | ||
| 25 | |||
| 26 | @node Words and characters | ||
| 27 | @section Words and characters | ||
| 28 | |||
| 29 | @enumerate | ||
| 30 | @item | ||
| 31 | In chapter Installation Handbook, | ||
| 32 | ``@command{#}'' in example code blocks describes commands executed as root | ||
| 33 | |||
| 34 | @example | ||
| 35 | # echo "I am root" | ||
| 36 | I am root | ||
| 37 | @end example | ||
| 38 | |||
| 39 | @item | ||
| 40 | However, in the chapter GNUnet C Tutorial | ||
| 41 | ``@command{#}'' in example code blocks describes commands, ie comments. | ||
| 42 | |||
| 43 | @example | ||
| 44 | # Do the foobar thing: | ||
| 45 | $ make foobar | ||
| 46 | @end example | ||
| 47 | |||
| 48 | @item | ||
| 49 | Dollarsign ``@command{$}'' in example code blocks describes commands you | ||
| 50 | execute as unprivileged users. | ||
| 51 | |||
| 52 | @example | ||
| 53 | $ cd foo; ./configure --example-switch | ||
| 54 | @end example | ||
| 55 | |||
| 56 | @item | ||
| 57 | Backslash ``@command{\}'' describes linebreaks. | ||
| 58 | |||
| 59 | @example | ||
| 60 | ./configure --foo --bar --baz \ | ||
| 61 | --short-loop | ||
| 62 | @end example | ||
| 63 | |||
| 64 | ...expands to @code{./configure --foo --bar --baz --short-loop} | ||
| 65 | |||
| 66 | @end enumerate | ||
| 67 | |||
| 68 | @node Technical Assumptions | ||
| 69 | @section Technical Assumptions | ||
| 70 | |||
| 71 | @c Is it really assuming Bash (ie Bash extensions of POSIX being used)? | ||
| 72 | The shell on GNU systems is assumed to be Bash. | ||
diff --git a/doc/documentation/docstyle.css b/doc/documentation/docstyle.css deleted file mode 100644 index 8719248d0..000000000 --- a/doc/documentation/docstyle.css +++ /dev/null | |||
| @@ -1,76 +0,0 @@ | |||
| 1 | html, body { | ||
| 2 | font-size: 1em; | ||
| 3 | text-align: left; | ||
| 4 | text-decoration: none; | ||
| 5 | } | ||
| 6 | html { background-color: #e7e7e7; } | ||
| 7 | |||
| 8 | body { | ||
| 9 | max-width: 74.92em; | ||
| 10 | margin: 0 auto; | ||
| 11 | padding: .5em 1em 1em 1em; | ||
| 12 | background-color: white; | ||
| 13 | border: .1em solid #c0c0c0; | ||
| 14 | } | ||
| 15 | |||
| 16 | h1, h2, h3, h4 { color: #333; } | ||
| 17 | h5, h6, dt { color: #222; } | ||
| 18 | |||
| 19 | |||
| 20 | a h3 { | ||
| 21 | color: #005090; | ||
| 22 | } | ||
| 23 | |||
| 24 | a[href] { color: #005090; } | ||
| 25 | a[href]:visited { color: #100070; } | ||
| 26 | a[href]:active, a[href]:hover { | ||
| 27 | color: #100070; | ||
| 28 | text-decoration: none; | ||
| 29 | } | ||
| 30 | |||
| 31 | .linkrow { | ||
| 32 | margin: 3em 0; | ||
| 33 | } | ||
| 34 | |||
| 35 | .linkrow { | ||
| 36 | text-align: center; | ||
| 37 | } | ||
| 38 | |||
| 39 | div.example { padding: .8em 1.2em .4em; } | ||
| 40 | pre.example { padding: .8em 1.2em; } | ||
| 41 | div.example, pre.example { | ||
| 42 | margin: 1em 0 1em 3% ; | ||
| 43 | -webkit-border-radius: .3em; | ||
| 44 | -moz-border-radius: .3em; | ||
| 45 | border-radius: .3em; | ||
| 46 | border: 1px solid #d4cbb6; | ||
| 47 | background-color: #f2efe4; | ||
| 48 | } | ||
| 49 | div.example > pre.example { | ||
| 50 | padding: 0 0 .4em; | ||
| 51 | margin: 0; | ||
| 52 | border: none; | ||
| 53 | } | ||
| 54 | |||
| 55 | |||
| 56 | /* This makes the very long tables of contents in Gnulib and other | ||
| 57 | manuals easier to read. */ | ||
| 58 | .contents ul, .shortcontents ul { font-weight: bold; } | ||
| 59 | .contents ul ul, .shortcontents ul ul { font-weight: normal; } | ||
| 60 | .contents ul { list-style: none; } | ||
| 61 | |||
| 62 | /* For colored navigation bars (Emacs manual): make the bar extend | ||
| 63 | across the whole width of the page and give it a decent height. */ | ||
| 64 | .header, .node { margin: 0 -1em; padding: 0 1em; } | ||
| 65 | .header p, .node p { line-height: 2em; } | ||
| 66 | |||
| 67 | /* For navigation links */ | ||
| 68 | .node a, .header a { display: inline-block; line-height: 2em; } | ||
| 69 | .node a:hover, .header a:hover { background: #f2efe4; } | ||
| 70 | |||
| 71 | table.cartouche { | ||
| 72 | border-collapse: collapse; | ||
| 73 | border-color: darkred; | ||
| 74 | border-style: solid; | ||
| 75 | border-width: 3px; | ||
| 76 | } | ||
diff --git a/doc/documentation/fdl-1.3.texi b/doc/documentation/fdl-1.3.texi deleted file mode 100644 index cb71f05a1..000000000 --- a/doc/documentation/fdl-1.3.texi +++ /dev/null | |||
| @@ -1,505 +0,0 @@ | |||
| 1 | @c The GNU Free Documentation License. | ||
| 2 | @center Version 1.3, 3 November 2008 | ||
| 3 | |||
| 4 | @c This file is intended to be included within another document, | ||
| 5 | @c hence no sectioning command or @node. | ||
| 6 | |||
| 7 | @display | ||
| 8 | Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. | ||
| 9 | @uref{http://fsf.org/} | ||
| 10 | |||
| 11 | Everyone is permitted to copy and distribute verbatim copies | ||
| 12 | of this license document, but changing it is not allowed. | ||
| 13 | @end display | ||
| 14 | |||
| 15 | @enumerate 0 | ||
| 16 | @item | ||
| 17 | PREAMBLE | ||
| 18 | |||
| 19 | The purpose of this License is to make a manual, textbook, or other | ||
| 20 | functional and useful document @dfn{free} in the sense of freedom: to | ||
| 21 | assure everyone the effective freedom to copy and redistribute it, | ||
| 22 | with or without modifying it, either commercially or noncommercially. | ||
| 23 | Secondarily, this License preserves for the author and publisher a way | ||
| 24 | to get credit for their work, while not being considered responsible | ||
| 25 | for modifications made by others. | ||
| 26 | |||
| 27 | This License is a kind of ``copyleft'', which means that derivative | ||
| 28 | works of the document must themselves be free in the same sense. It | ||
| 29 | complements the GNU General Public License, which is a copyleft | ||
| 30 | license designed for free software. | ||
| 31 | |||
| 32 | We have designed this License in order to use it for manuals for free | ||
| 33 | software, because free software needs free documentation: a free | ||
| 34 | program should come with manuals providing the same freedoms that the | ||
| 35 | software does. But this License is not limited to software manuals; | ||
| 36 | it can be used for any textual work, regardless of subject matter or | ||
| 37 | whether it is published as a printed book. We recommend this License | ||
| 38 | principally for works whose purpose is instruction or reference. | ||
| 39 | |||
| 40 | @item | ||
| 41 | APPLICABILITY AND DEFINITIONS | ||
| 42 | |||
| 43 | This License applies to any manual or other work, in any medium, that | ||
| 44 | contains a notice placed by the copyright holder saying it can be | ||
| 45 | distributed under the terms of this License. Such a notice grants a | ||
| 46 | world-wide, royalty-free license, unlimited in duration, to use that | ||
| 47 | work under the conditions stated herein. The ``Document'', below, | ||
| 48 | refers to any such manual or work. Any member of the public is a | ||
| 49 | licensee, and is addressed as ``you''. You accept the license if you | ||
| 50 | copy, modify or distribute the work in a way requiring permission | ||
| 51 | under copyright law. | ||
| 52 | |||
| 53 | A ``Modified Version'' of the Document means any work containing the | ||
| 54 | Document or a portion of it, either copied verbatim, or with | ||
| 55 | modifications and/or translated into another language. | ||
| 56 | |||
| 57 | A ``Secondary Section'' is a named appendix or a front-matter section | ||
| 58 | of the Document that deals exclusively with the relationship of the | ||
| 59 | publishers or authors of the Document to the Document's overall | ||
| 60 | subject (or to related matters) and contains nothing that could fall | ||
| 61 | directly within that overall subject. (Thus, if the Document is in | ||
| 62 | part a textbook of mathematics, a Secondary Section may not explain | ||
| 63 | any mathematics.) The relationship could be a matter of historical | ||
| 64 | connection with the subject or with related matters, or of legal, | ||
| 65 | commercial, philosophical, ethical or political position regarding | ||
| 66 | them. | ||
| 67 | |||
| 68 | The ``Invariant Sections'' are certain Secondary Sections whose titles | ||
| 69 | are designated, as being those of Invariant Sections, in the notice | ||
| 70 | that says that the Document is released under this License. If a | ||
| 71 | section does not fit the above definition of Secondary then it is not | ||
| 72 | allowed to be designated as Invariant. The Document may contain zero | ||
| 73 | Invariant Sections. If the Document does not identify any Invariant | ||
| 74 | Sections then there are none. | ||
| 75 | |||
| 76 | The ``Cover Texts'' are certain short passages of text that are listed, | ||
| 77 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that | ||
| 78 | the Document is released under this License. A Front-Cover Text may | ||
| 79 | be at most 5 words, and a Back-Cover Text may be at most 25 words. | ||
| 80 | |||
| 81 | A ``Transparent'' copy of the Document means a machine-readable copy, | ||
| 82 | represented in a format whose specification is available to the | ||
| 83 | general public, that is suitable for revising the document | ||
| 84 | straightforwardly with generic text editors or (for images composed of | ||
| 85 | pixels) generic paint programs or (for drawings) some widely available | ||
| 86 | drawing editor, and that is suitable for input to text formatters or | ||
| 87 | for automatic translation to a variety of formats suitable for input | ||
| 88 | to text formatters. A copy made in an otherwise Transparent file | ||
| 89 | format whose markup, or absence of markup, has been arranged to thwart | ||
| 90 | or discourage subsequent modification by readers is not Transparent. | ||
| 91 | An image format is not Transparent if used for any substantial amount | ||
| 92 | of text. A copy that is not ``Transparent'' is called ``Opaque''. | ||
| 93 | |||
| 94 | Examples of suitable formats for Transparent copies include plain | ||
| 95 | ASCII without markup, Texinfo input format, La@TeX{} input | ||
| 96 | format, SGML or XML using a publicly available | ||
| 97 | DTD, and standard-conforming simple HTML, | ||
| 98 | PostScript or PDF designed for human modification. Examples | ||
| 99 | of transparent image formats include PNG, XCF and | ||
| 100 | JPG. Opaque formats include proprietary formats that can be | ||
| 101 | read and edited only by proprietary word processors, SGML or | ||
| 102 | XML for which the DTD and/or processing tools are | ||
| 103 | not generally available, and the machine-generated HTML, | ||
| 104 | PostScript or PDF produced by some word processors for | ||
| 105 | output purposes only. | ||
| 106 | |||
| 107 | The ``Title Page'' means, for a printed book, the title page itself, | ||
| 108 | plus such following pages as are needed to hold, legibly, the material | ||
| 109 | this License requires to appear in the title page. For works in | ||
| 110 | formats which do not have any title page as such, ``Title Page'' means | ||
| 111 | the text near the most prominent appearance of the work's title, | ||
| 112 | preceding the beginning of the body of the text. | ||
| 113 | |||
| 114 | The ``publisher'' means any person or entity that distributes copies | ||
| 115 | of the Document to the public. | ||
| 116 | |||
| 117 | A section ``Entitled XYZ'' means a named subunit of the Document whose | ||
| 118 | title either is precisely XYZ or contains XYZ in parentheses following | ||
| 119 | text that translates XYZ in another language. (Here XYZ stands for a | ||
| 120 | specific section name mentioned below, such as ``Acknowledgements'', | ||
| 121 | ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' | ||
| 122 | of such a section when you modify the Document means that it remains a | ||
| 123 | section ``Entitled XYZ'' according to this definition. | ||
| 124 | |||
| 125 | The Document may include Warranty Disclaimers next to the notice which | ||
| 126 | states that this License applies to the Document. These Warranty | ||
| 127 | Disclaimers are considered to be included by reference in this | ||
| 128 | License, but only as regards disclaiming warranties: any other | ||
| 129 | implication that these Warranty Disclaimers may have is void and has | ||
| 130 | no effect on the meaning of this License. | ||
| 131 | |||
| 132 | @item | ||
| 133 | VERBATIM COPYING | ||
| 134 | |||
| 135 | You may copy and distribute the Document in any medium, either | ||
| 136 | commercially or noncommercially, provided that this License, the | ||
| 137 | copyright notices, and the license notice saying this License applies | ||
| 138 | to the Document are reproduced in all copies, and that you add no other | ||
| 139 | conditions whatsoever to those of this License. You may not use | ||
| 140 | technical measures to obstruct or control the reading or further | ||
| 141 | copying of the copies you make or distribute. However, you may accept | ||
| 142 | compensation in exchange for copies. If you distribute a large enough | ||
| 143 | number of copies you must also follow the conditions in section 3. | ||
| 144 | |||
| 145 | You may also lend copies, under the same conditions stated above, and | ||
| 146 | you may publicly display copies. | ||
| 147 | |||
| 148 | @item | ||
| 149 | COPYING IN QUANTITY | ||
| 150 | |||
| 151 | If you publish printed copies (or copies in media that commonly have | ||
| 152 | printed covers) of the Document, numbering more than 100, and the | ||
| 153 | Document's license notice requires Cover Texts, you must enclose the | ||
| 154 | copies in covers that carry, clearly and legibly, all these Cover | ||
| 155 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | ||
| 156 | the back cover. Both covers must also clearly and legibly identify | ||
| 157 | you as the publisher of these copies. The front cover must present | ||
| 158 | the full title with all words of the title equally prominent and | ||
| 159 | visible. You may add other material on the covers in addition. | ||
| 160 | Copying with changes limited to the covers, as long as they preserve | ||
| 161 | the title of the Document and satisfy these conditions, can be treated | ||
| 162 | as verbatim copying in other respects. | ||
| 163 | |||
| 164 | If the required texts for either cover are too voluminous to fit | ||
| 165 | legibly, you should put the first ones listed (as many as fit | ||
| 166 | reasonably) on the actual cover, and continue the rest onto adjacent | ||
| 167 | pages. | ||
| 168 | |||
| 169 | If you publish or distribute Opaque copies of the Document numbering | ||
| 170 | more than 100, you must either include a machine-readable Transparent | ||
| 171 | copy along with each Opaque copy, or state in or with each Opaque copy | ||
| 172 | a computer-network location from which the general network-using | ||
| 173 | public has access to download using public-standard network protocols | ||
| 174 | a complete Transparent copy of the Document, free of added material. | ||
| 175 | If you use the latter option, you must take reasonably prudent steps, | ||
| 176 | when you begin distribution of Opaque copies in quantity, to ensure | ||
| 177 | that this Transparent copy will remain thus accessible at the stated | ||
| 178 | location until at least one year after the last time you distribute an | ||
| 179 | Opaque copy (directly or through your agents or retailers) of that | ||
| 180 | edition to the public. | ||
| 181 | |||
| 182 | It is requested, but not required, that you contact the authors of the | ||
| 183 | Document well before redistributing any large number of copies, to give | ||
| 184 | them a chance to provide you with an updated version of the Document. | ||
| 185 | |||
| 186 | @item | ||
| 187 | MODIFICATIONS | ||
| 188 | |||
| 189 | You may copy and distribute a Modified Version of the Document under | ||
| 190 | the conditions of sections 2 and 3 above, provided that you release | ||
| 191 | the Modified Version under precisely this License, with the Modified | ||
| 192 | Version filling the role of the Document, thus licensing distribution | ||
| 193 | and modification of the Modified Version to whoever possesses a copy | ||
| 194 | of it. In addition, you must do these things in the Modified Version: | ||
| 195 | |||
| 196 | @enumerate A | ||
| 197 | @item | ||
| 198 | Use in the Title Page (and on the covers, if any) a title distinct | ||
| 199 | from that of the Document, and from those of previous versions | ||
| 200 | (which should, if there were any, be listed in the History section | ||
| 201 | of the Document). You may use the same title as a previous version | ||
| 202 | if the original publisher of that version gives permission. | ||
| 203 | |||
| 204 | @item | ||
| 205 | List on the Title Page, as authors, one or more persons or entities | ||
| 206 | responsible for authorship of the modifications in the Modified | ||
| 207 | Version, together with at least five of the principal authors of the | ||
| 208 | Document (all of its principal authors, if it has fewer than five), | ||
| 209 | unless they release you from this requirement. | ||
| 210 | |||
| 211 | @item | ||
| 212 | State on the Title page the name of the publisher of the | ||
| 213 | Modified Version, as the publisher. | ||
| 214 | |||
| 215 | @item | ||
| 216 | Preserve all the copyright notices of the Document. | ||
| 217 | |||
| 218 | @item | ||
| 219 | Add an appropriate copyright notice for your modifications | ||
| 220 | adjacent to the other copyright notices. | ||
| 221 | |||
| 222 | @item | ||
| 223 | Include, immediately after the copyright notices, a license notice | ||
| 224 | giving the public permission to use the Modified Version under the | ||
| 225 | terms of this License, in the form shown in the Addendum below. | ||
| 226 | |||
| 227 | @item | ||
| 228 | Preserve in that license notice the full lists of Invariant Sections | ||
| 229 | and required Cover Texts given in the Document's license notice. | ||
| 230 | |||
| 231 | @item | ||
| 232 | Include an unaltered copy of this License. | ||
| 233 | |||
| 234 | @item | ||
| 235 | Preserve the section Entitled ``History'', Preserve its Title, and add | ||
| 236 | to it an item stating at least the title, year, new authors, and | ||
| 237 | publisher of the Modified Version as given on the Title Page. If | ||
| 238 | there is no section Entitled ``History'' in the Document, create one | ||
| 239 | stating the title, year, authors, and publisher of the Document as | ||
| 240 | given on its Title Page, then add an item describing the Modified | ||
| 241 | Version as stated in the previous sentence. | ||
| 242 | |||
| 243 | @item | ||
| 244 | Preserve the network location, if any, given in the Document for | ||
| 245 | public access to a Transparent copy of the Document, and likewise | ||
| 246 | the network locations given in the Document for previous versions | ||
| 247 | it was based on. These may be placed in the ``History'' section. | ||
| 248 | You may omit a network location for a work that was published at | ||
| 249 | least four years before the Document itself, or if the original | ||
| 250 | publisher of the version it refers to gives permission. | ||
| 251 | |||
| 252 | @item | ||
| 253 | For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve | ||
| 254 | the Title of the section, and preserve in the section all the | ||
| 255 | substance and tone of each of the contributor acknowledgements and/or | ||
| 256 | dedications given therein. | ||
| 257 | |||
| 258 | @item | ||
| 259 | Preserve all the Invariant Sections of the Document, | ||
| 260 | unaltered in their text and in their titles. Section numbers | ||
| 261 | or the equivalent are not considered part of the section titles. | ||
| 262 | |||
| 263 | @item | ||
| 264 | Delete any section Entitled ``Endorsements''. Such a section | ||
| 265 | may not be included in the Modified Version. | ||
| 266 | |||
| 267 | @item | ||
| 268 | Do not retitle any existing section to be Entitled ``Endorsements'' or | ||
| 269 | to conflict in title with any Invariant Section. | ||
| 270 | |||
| 271 | @item | ||
| 272 | Preserve any Warranty Disclaimers. | ||
| 273 | @end enumerate | ||
| 274 | |||
| 275 | If the Modified Version includes new front-matter sections or | ||
| 276 | appendices that qualify as Secondary Sections and contain no material | ||
| 277 | copied from the Document, you may at your option designate some or all | ||
| 278 | of these sections as invariant. To do this, add their titles to the | ||
| 279 | list of Invariant Sections in the Modified Version's license notice. | ||
| 280 | These titles must be distinct from any other section titles. | ||
| 281 | |||
| 282 | You may add a section Entitled ``Endorsements'', provided it contains | ||
| 283 | nothing but endorsements of your Modified Version by various | ||
| 284 | parties---for example, statements of peer review or that the text has | ||
| 285 | been approved by an organization as the authoritative definition of a | ||
| 286 | standard. | ||
| 287 | |||
| 288 | You may add a passage of up to five words as a Front-Cover Text, and a | ||
| 289 | passage of up to 25 words as a Back-Cover Text, to the end of the list | ||
| 290 | of Cover Texts in the Modified Version. Only one passage of | ||
| 291 | Front-Cover Text and one of Back-Cover Text may be added by (or | ||
| 292 | through arrangements made by) any one entity. If the Document already | ||
| 293 | includes a cover text for the same cover, previously added by you or | ||
| 294 | by arrangement made by the same entity you are acting on behalf of, | ||
| 295 | you may not add another; but you may replace the old one, on explicit | ||
| 296 | permission from the previous publisher that added the old one. | ||
| 297 | |||
| 298 | The author(s) and publisher(s) of the Document do not by this License | ||
| 299 | give permission to use their names for publicity for or to assert or | ||
| 300 | imply endorsement of any Modified Version. | ||
| 301 | |||
| 302 | @item | ||
| 303 | COMBINING DOCUMENTS | ||
| 304 | |||
| 305 | You may combine the Document with other documents released under this | ||
| 306 | License, under the terms defined in section 4 above for modified | ||
| 307 | versions, provided that you include in the combination all of the | ||
| 308 | Invariant Sections of all of the original documents, unmodified, and | ||
| 309 | list them all as Invariant Sections of your combined work in its | ||
| 310 | license notice, and that you preserve all their Warranty Disclaimers. | ||
| 311 | |||
| 312 | The combined work need only contain one copy of this License, and | ||
| 313 | multiple identical Invariant Sections may be replaced with a single | ||
| 314 | copy. If there are multiple Invariant Sections with the same name but | ||
| 315 | different contents, make the title of each such section unique by | ||
| 316 | adding at the end of it, in parentheses, the name of the original | ||
| 317 | author or publisher of that section if known, or else a unique number. | ||
| 318 | Make the same adjustment to the section titles in the list of | ||
| 319 | Invariant Sections in the license notice of the combined work. | ||
| 320 | |||
| 321 | In the combination, you must combine any sections Entitled ``History'' | ||
| 322 | in the various original documents, forming one section Entitled | ||
| 323 | ``History''; likewise combine any sections Entitled ``Acknowledgements'', | ||
| 324 | and any sections Entitled ``Dedications''. You must delete all | ||
| 325 | sections Entitled ``Endorsements.'' | ||
| 326 | |||
| 327 | @item | ||
| 328 | COLLECTIONS OF DOCUMENTS | ||
| 329 | |||
| 330 | You may make a collection consisting of the Document and other documents | ||
| 331 | released under this License, and replace the individual copies of this | ||
| 332 | License in the various documents with a single copy that is included in | ||
| 333 | the collection, provided that you follow the rules of this License for | ||
| 334 | verbatim copying of each of the documents in all other respects. | ||
| 335 | |||
| 336 | You may extract a single document from such a collection, and distribute | ||
| 337 | it individually under this License, provided you insert a copy of this | ||
| 338 | License into the extracted document, and follow this License in all | ||
| 339 | other respects regarding verbatim copying of that document. | ||
| 340 | |||
| 341 | @item | ||
| 342 | AGGREGATION WITH INDEPENDENT WORKS | ||
| 343 | |||
| 344 | A compilation of the Document or its derivatives with other separate | ||
| 345 | and independent documents or works, in or on a volume of a storage or | ||
| 346 | distribution medium, is called an ``aggregate'' if the copyright | ||
| 347 | resulting from the compilation is not used to limit the legal rights | ||
| 348 | of the compilation's users beyond what the individual works permit. | ||
| 349 | When the Document is included in an aggregate, this License does not | ||
| 350 | apply to the other works in the aggregate which are not themselves | ||
| 351 | derivative works of the Document. | ||
| 352 | |||
| 353 | If the Cover Text requirement of section 3 is applicable to these | ||
| 354 | copies of the Document, then if the Document is less than one half of | ||
| 355 | the entire aggregate, the Document's Cover Texts may be placed on | ||
| 356 | covers that bracket the Document within the aggregate, or the | ||
| 357 | electronic equivalent of covers if the Document is in electronic form. | ||
| 358 | Otherwise they must appear on printed covers that bracket the whole | ||
| 359 | aggregate. | ||
| 360 | |||
| 361 | @item | ||
| 362 | TRANSLATION | ||
| 363 | |||
| 364 | Translation is considered a kind of modification, so you may | ||
| 365 | distribute translations of the Document under the terms of section 4. | ||
| 366 | Replacing Invariant Sections with translations requires special | ||
| 367 | permission from their copyright holders, but you may include | ||
| 368 | translations of some or all Invariant Sections in addition to the | ||
| 369 | original versions of these Invariant Sections. You may include a | ||
| 370 | translation of this License, and all the license notices in the | ||
| 371 | Document, and any Warranty Disclaimers, provided that you also include | ||
| 372 | the original English version of this License and the original versions | ||
| 373 | of those notices and disclaimers. In case of a disagreement between | ||
| 374 | the translation and the original version of this License or a notice | ||
| 375 | or disclaimer, the original version will prevail. | ||
| 376 | |||
| 377 | If a section in the Document is Entitled ``Acknowledgements'', | ||
| 378 | ``Dedications'', or ``History'', the requirement (section 4) to Preserve | ||
| 379 | its Title (section 1) will typically require changing the actual | ||
| 380 | title. | ||
| 381 | |||
| 382 | @item | ||
| 383 | TERMINATION | ||
| 384 | |||
| 385 | You may not copy, modify, sublicense, or distribute the Document | ||
| 386 | except as expressly provided under this License. Any attempt | ||
| 387 | otherwise to copy, modify, sublicense, or distribute it is void, and | ||
| 388 | will automatically terminate your rights under this License. | ||
| 389 | |||
| 390 | However, if you cease all violation of this License, then your license | ||
| 391 | from a particular copyright holder is reinstated (a) provisionally, | ||
| 392 | unless and until the copyright holder explicitly and finally | ||
| 393 | terminates your license, and (b) permanently, if the copyright holder | ||
| 394 | fails to notify you of the violation by some reasonable means prior to | ||
| 395 | 60 days after the cessation. | ||
| 396 | |||
| 397 | Moreover, your license from a particular copyright holder is | ||
| 398 | reinstated permanently if the copyright holder notifies you of the | ||
| 399 | violation by some reasonable means, this is the first time you have | ||
| 400 | received notice of violation of this License (for any work) from that | ||
| 401 | copyright holder, and you cure the violation prior to 30 days after | ||
| 402 | your receipt of the notice. | ||
| 403 | |||
| 404 | Termination of your rights under this section does not terminate the | ||
| 405 | licenses of parties who have received copies or rights from you under | ||
| 406 | this License. If your rights have been terminated and not permanently | ||
| 407 | reinstated, receipt of a copy of some or all of the same material does | ||
| 408 | not give you any rights to use it. | ||
| 409 | |||
| 410 | @item | ||
| 411 | FUTURE REVISIONS OF THIS LICENSE | ||
| 412 | |||
| 413 | The Free Software Foundation may publish new, revised versions | ||
| 414 | of the GNU Free Documentation License from time to time. Such new | ||
| 415 | versions will be similar in spirit to the present version, but may | ||
| 416 | differ in detail to address new problems or concerns. See | ||
| 417 | @uref{http://www.gnu.org/copyleft/}. | ||
| 418 | |||
| 419 | Each version of the License is given a distinguishing version number. | ||
| 420 | If the Document specifies that a particular numbered version of this | ||
| 421 | License ``or any later version'' applies to it, you have the option of | ||
| 422 | following the terms and conditions either of that specified version or | ||
| 423 | of any later version that has been published (not as a draft) by the | ||
| 424 | Free Software Foundation. If the Document does not specify a version | ||
| 425 | number of this License, you may choose any version ever published (not | ||
| 426 | as a draft) by the Free Software Foundation. If the Document | ||
| 427 | specifies that a proxy can decide which future versions of this | ||
| 428 | License can be used, that proxy's public statement of acceptance of a | ||
| 429 | version permanently authorizes you to choose that version for the | ||
| 430 | Document. | ||
| 431 | |||
| 432 | @item | ||
| 433 | RELICENSING | ||
| 434 | |||
| 435 | ``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any | ||
| 436 | World Wide Web server that publishes copyrightable works and also | ||
| 437 | provides prominent facilities for anybody to edit those works. A | ||
| 438 | public wiki that anybody can edit is an example of such a server. A | ||
| 439 | ``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the | ||
| 440 | site means any set of copyrightable works thus published on the MMC | ||
| 441 | site. | ||
| 442 | |||
| 443 | ``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 | ||
| 444 | license published by Creative Commons Corporation, a not-for-profit | ||
| 445 | corporation with a principal place of business in San Francisco, | ||
| 446 | California, as well as future copyleft versions of that license | ||
| 447 | published by that same organization. | ||
| 448 | |||
| 449 | ``Incorporate'' means to publish or republish a Document, in whole or | ||
| 450 | in part, as part of another Document. | ||
| 451 | |||
| 452 | An MMC is ``eligible for relicensing'' if it is licensed under this | ||
| 453 | License, and if all works that were first published under this License | ||
| 454 | somewhere other than this MMC, and subsequently incorporated in whole | ||
| 455 | or in part into the MMC, (1) had no cover texts or invariant sections, | ||
| 456 | and (2) were thus incorporated prior to November 1, 2008. | ||
| 457 | |||
| 458 | The operator of an MMC Site may republish an MMC contained in the site | ||
| 459 | under CC-BY-SA on the same site at any time before August 1, 2009, | ||
| 460 | provided the MMC is eligible for relicensing. | ||
| 461 | |||
| 462 | @end enumerate | ||
| 463 | |||
| 464 | @page | ||
| 465 | @heading ADDENDUM: How to use this License for your documents | ||
| 466 | |||
| 467 | To use this License in a document you have written, include a copy of | ||
| 468 | the License in the document and put the following copyright and | ||
| 469 | license notices just after the title page: | ||
| 470 | |||
| 471 | @smallexample | ||
| 472 | @group | ||
| 473 | Copyright (C) @var{year} @var{your name}. | ||
| 474 | Permission is granted to copy, distribute and/or modify this document | ||
| 475 | under the terms of the GNU Free Documentation License, Version 1.3 | ||
| 476 | or any later version published by the Free Software Foundation; | ||
| 477 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover | ||
| 478 | Texts. A copy of the license is included in the section entitled ``GNU | ||
| 479 | Free Documentation License''. | ||
| 480 | @end group | ||
| 481 | @end smallexample | ||
| 482 | |||
| 483 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, | ||
| 484 | replace the ``with@dots{}Texts.''@: line with this: | ||
| 485 | |||
| 486 | @smallexample | ||
| 487 | @group | ||
| 488 | with the Invariant Sections being @var{list their titles}, with | ||
| 489 | the Front-Cover Texts being @var{list}, and with the Back-Cover Texts | ||
| 490 | being @var{list}. | ||
| 491 | @end group | ||
| 492 | @end smallexample | ||
| 493 | |||
| 494 | If you have Invariant Sections without Cover Texts, or some other | ||
| 495 | combination of the three, merge those two alternatives to suit the | ||
| 496 | situation. | ||
| 497 | |||
| 498 | If your document contains nontrivial examples of program code, we | ||
| 499 | recommend releasing these examples in parallel under your choice of | ||
| 500 | free software license, such as the GNU General Public License, | ||
| 501 | to permit their use in free software. | ||
| 502 | |||
| 503 | @c Local Variables: | ||
| 504 | @c ispell-local-pdict: "ispell-dict" | ||
| 505 | @c End: | ||
diff --git a/doc/documentation/gendocs.sh b/doc/documentation/gendocs.sh deleted file mode 100755 index 3b71b36a2..000000000 --- a/doc/documentation/gendocs.sh +++ /dev/null | |||
| @@ -1,504 +0,0 @@ | |||
| 1 | #!/bin/sh -e | ||
| 2 | # gendocs.sh -- generate a GNU manual in many formats. This script is | ||
| 3 | # mentioned in maintain.texi. See the help message below for usage details. | ||
| 4 | |||
| 5 | scriptversion=2016-12-31.18 | ||
| 6 | |||
| 7 | # Copyright 2003-2017 Free Software Foundation, Inc. | ||
| 8 | # | ||
| 9 | # This program is free software: you can redistribute it and/or modify | ||
| 10 | # it under the terms of the GNU General Public License as published by | ||
| 11 | # the Free Software Foundation; either version 3 of the License, or | ||
| 12 | # (at your option) any later version. | ||
| 13 | # | ||
| 14 | # This program is distributed in the hope that it will be useful, | ||
| 15 | # but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 16 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
| 17 | # GNU General Public License for more details. | ||
| 18 | # | ||
| 19 | # You should have received a copy of the GNU General Public License | ||
| 20 | # along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
| 21 | # | ||
| 22 | # Original author: Mohit Agarwal. | ||
| 23 | # Send bug reports and any other correspondence to bug-gnulib@gnu.org. | ||
| 24 | # | ||
| 25 | # The latest version of this script, and the companion template, is | ||
| 26 | # available from the Gnulib repository: | ||
| 27 | # | ||
| 28 | # http://git.savannah.gnu.org/cgit/gnulib.git/tree/build-aux/gendocs.sh | ||
| 29 | # http://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/gendocs_template | ||
| 30 | |||
| 31 | # TODO: | ||
| 32 | # - image importing was only implemented for HTML generated by | ||
| 33 | # makeinfo. But it should be simple enough to adjust. | ||
| 34 | # - images are not imported in the source tarball. All the needed | ||
| 35 | # formats (PDF, PNG, etc.) should be included. | ||
| 36 | |||
| 37 | prog=`basename "$0"` | ||
| 38 | srcdir=`pwd` | ||
| 39 | |||
| 40 | scripturl="http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/gendocs.sh" | ||
| 41 | templateurl="http://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/gendocs_template" | ||
| 42 | |||
| 43 | : ${SETLANG="env LANG= LC_MESSAGES= LC_ALL= LANGUAGE="} | ||
| 44 | : ${MAKEINFO="makeinfo"} | ||
| 45 | : ${TEXI2DVI="texi2dvi"} | ||
| 46 | : ${DOCBOOK2HTML="docbook2html"} | ||
| 47 | : ${DOCBOOK2PDF="docbook2pdf"} | ||
| 48 | : ${DOCBOOK2TXT="docbook2txt"} | ||
| 49 | : ${GENDOCS_TEMPLATE_DIR="."} | ||
| 50 | : ${PERL='perl'} | ||
| 51 | : ${TEXI2HTML="texi2html"} | ||
| 52 | unset CDPATH | ||
| 53 | unset use_texi2html | ||
| 54 | |||
| 55 | MANUAL_TITLE= | ||
| 56 | PACKAGE= | ||
| 57 | EMAIL=webmasters@gnu.org # please override with --email | ||
| 58 | commonarg= # passed to all makeinfo/texi2html invcations. | ||
| 59 | dirargs= # passed to all tools (-I dir). | ||
| 60 | dirs= # -I directories. | ||
| 61 | htmlarg="--css-ref=/software/gnulib/manual.css -c TOP_NODE_UP_URL=/manual" | ||
| 62 | infoarg=--no-split | ||
| 63 | generate_ascii=true | ||
| 64 | generate_html=true | ||
| 65 | generate_info=true | ||
| 66 | generate_tex=true | ||
| 67 | outdir=manual | ||
| 68 | source_extra= | ||
| 69 | split=node | ||
| 70 | srcfile= | ||
| 71 | texarg="-t @finalout" | ||
| 72 | |||
| 73 | version="gendocs.sh $scriptversion | ||
| 74 | |||
| 75 | Copyright 2017 Free Software Foundation, Inc. | ||
| 76 | There is NO warranty. You may redistribute this software | ||
| 77 | under the terms of the GNU General Public License. | ||
| 78 | For more information about these matters, see the files named COPYING." | ||
| 79 | |||
| 80 | usage="Usage: $prog [OPTION]... PACKAGE MANUAL-TITLE | ||
| 81 | |||
| 82 | Generate output in various formats from PACKAGE.texinfo (or .texi or | ||
| 83 | .txi) source. See the GNU Maintainers document for a more extensive | ||
| 84 | discussion: | ||
| 85 | http://www.gnu.org/prep/maintain_toc.html | ||
| 86 | |||
| 87 | Options: | ||
| 88 | --email ADR use ADR as contact in generated web pages; always give this. | ||
| 89 | |||
| 90 | -s SRCFILE read Texinfo from SRCFILE, instead of PACKAGE.{texinfo|texi|txi} | ||
| 91 | -o OUTDIR write files into OUTDIR, instead of manual/. | ||
| 92 | -I DIR append DIR to the Texinfo search path. | ||
| 93 | --common ARG pass ARG in all invocations. | ||
| 94 | --html ARG pass ARG to makeinfo or texi2html for HTML targets, | ||
| 95 | instead of '$htmlarg'. | ||
| 96 | --info ARG pass ARG to makeinfo for Info, instead of --no-split. | ||
| 97 | --no-ascii skip generating the plain text output. | ||
| 98 | --no-html skip generating the html output. | ||
| 99 | --no-info skip generating the info output. | ||
| 100 | --no-tex skip generating the dvi and pdf output. | ||
| 101 | --source ARG include ARG in tar archive of sources. | ||
| 102 | --split HOW make split HTML by node, section, chapter; default node. | ||
| 103 | --tex ARG pass ARG to texi2dvi for DVI and PDF, instead of -t @finalout. | ||
| 104 | |||
| 105 | --texi2html use texi2html to make HTML target, with all split versions. | ||
| 106 | --docbook convert through DocBook too (xml, txt, html, pdf). | ||
| 107 | |||
| 108 | --help display this help and exit successfully. | ||
| 109 | --version display version information and exit successfully. | ||
| 110 | |||
| 111 | Simple example: $prog --email bug-gnu-emacs@gnu.org emacs \"GNU Emacs Manual\" | ||
| 112 | |||
| 113 | Typical sequence: | ||
| 114 | cd PACKAGESOURCE/doc | ||
| 115 | wget \"$scripturl\" | ||
| 116 | wget \"$templateurl\" | ||
| 117 | $prog --email BUGLIST MANUAL \"GNU MANUAL - One-line description\" | ||
| 118 | |||
| 119 | Output will be in a new subdirectory \"manual\" (by default; | ||
| 120 | use -o OUTDIR to override). Move all the new files into your web CVS | ||
| 121 | tree, as explained in the Web Pages node of maintain.texi. | ||
| 122 | |||
| 123 | Please use the --email ADDRESS option so your own bug-reporting | ||
| 124 | address will be used in the generated HTML pages. | ||
| 125 | |||
| 126 | MANUAL-TITLE is included as part of the HTML <title> of the overall | ||
| 127 | manual/index.html file. It should include the name of the package being | ||
| 128 | documented. manual/index.html is created by substitution from the file | ||
| 129 | $GENDOCS_TEMPLATE_DIR/gendocs_template. (Feel free to modify the | ||
| 130 | generic template for your own purposes.) | ||
| 131 | |||
| 132 | If you have several manuals, you'll need to run this script several | ||
| 133 | times with different MANUAL values, specifying a different output | ||
| 134 | directory with -o each time. Then write (by hand) an overall index.html | ||
| 135 | with links to them all. | ||
| 136 | |||
| 137 | If a manual's Texinfo sources are spread across several directories, | ||
| 138 | first copy or symlink all Texinfo sources into a single directory. | ||
| 139 | (Part of the script's work is to make a tar.gz of the sources.) | ||
| 140 | |||
| 141 | As implied above, by default monolithic Info files are generated. | ||
| 142 | If you want split Info, or other Info options, use --info to override. | ||
| 143 | |||
| 144 | You can set the environment variables MAKEINFO, TEXI2DVI, TEXI2HTML, | ||
| 145 | and PERL to control the programs that get executed, and | ||
| 146 | GENDOCS_TEMPLATE_DIR to control where the gendocs_template file is | ||
| 147 | looked for. With --docbook, the environment variables DOCBOOK2HTML, | ||
| 148 | DOCBOOK2PDF, and DOCBOOK2TXT are also consulted. | ||
| 149 | |||
| 150 | By default, makeinfo and texi2dvi are run in the default (English) | ||
| 151 | locale, since that's the language of most Texinfo manuals. If you | ||
| 152 | happen to have a non-English manual and non-English web site, see the | ||
| 153 | SETLANG setting in the source. | ||
| 154 | |||
| 155 | Email bug reports or enhancement requests to bug-gnulib@gnu.org. | ||
| 156 | " | ||
| 157 | |||
| 158 | while test $# -gt 0; do | ||
| 159 | case $1 in | ||
| 160 | -s) shift; srcfile=$1;; | ||
| 161 | -o) shift; outdir=$1;; | ||
| 162 | -I) shift; dirargs="$dirargs -I '$1'"; dirs="$dirs $1";; | ||
| 163 | --common) shift; commonarg=$1;; | ||
| 164 | --docbook) docbook=yes;; | ||
| 165 | --email) shift; EMAIL=$1;; | ||
| 166 | --html) shift; htmlarg=$1;; | ||
| 167 | --info) shift; infoarg=$1;; | ||
| 168 | --no-ascii) generate_ascii=false;; | ||
| 169 | --no-html) generate_ascii=false;; | ||
| 170 | --no-info) generate_info=false;; | ||
| 171 | --no-tex) generate_tex=false;; | ||
| 172 | --source) shift; source_extra=$1;; | ||
| 173 | --split) shift; split=$1;; | ||
| 174 | --tex) shift; texarg=$1;; | ||
| 175 | --texi2html) use_texi2html=1;; | ||
| 176 | |||
| 177 | --help) echo "$usage"; exit 0;; | ||
| 178 | --version) echo "$version"; exit 0;; | ||
| 179 | -*) | ||
| 180 | echo "$0: Unknown option \`$1'." >&2 | ||
| 181 | echo "$0: Try \`--help' for more information." >&2 | ||
| 182 | exit 1;; | ||
| 183 | *) | ||
| 184 | if test -z "$PACKAGE"; then | ||
| 185 | PACKAGE=$1 | ||
| 186 | elif test -z "$MANUAL_TITLE"; then | ||
| 187 | MANUAL_TITLE=$1 | ||
| 188 | else | ||
| 189 | echo "$0: extra non-option argument \`$1'." >&2 | ||
| 190 | exit 1 | ||
| 191 | fi;; | ||
| 192 | esac | ||
| 193 | shift | ||
| 194 | done | ||
| 195 | |||
| 196 | # makeinfo uses the dirargs, but texi2dvi doesn't. | ||
| 197 | commonarg=" $dirargs $commonarg" | ||
| 198 | |||
| 199 | # For most of the following, the base name is just $PACKAGE | ||
| 200 | base=$PACKAGE | ||
| 201 | |||
| 202 | if test -n "$srcfile"; then | ||
| 203 | # but here, we use the basename of $srcfile | ||
| 204 | base=`basename "$srcfile"` | ||
| 205 | case $base in | ||
| 206 | *.txi|*.texi|*.texinfo) base=`echo "$base"|sed 's/\.[texinfo]*$//'`;; | ||
| 207 | esac | ||
| 208 | PACKAGE=$base | ||
| 209 | elif test -s "$srcdir/$PACKAGE.texinfo"; then | ||
| 210 | srcfile=$srcdir/$PACKAGE.texinfo | ||
| 211 | elif test -s "$srcdir/$PACKAGE.texi"; then | ||
| 212 | srcfile=$srcdir/$PACKAGE.texi | ||
| 213 | elif test -s "$srcdir/$PACKAGE.txi"; then | ||
| 214 | srcfile=$srcdir/$PACKAGE.txi | ||
| 215 | else | ||
| 216 | echo "$0: cannot find .texinfo or .texi or .txi for $PACKAGE in $srcdir." >&2 | ||
| 217 | exit 1 | ||
| 218 | fi | ||
| 219 | |||
| 220 | if test ! -r $GENDOCS_TEMPLATE_DIR/gendocs_template; then | ||
| 221 | echo "$0: cannot read $GENDOCS_TEMPLATE_DIR/gendocs_template." >&2 | ||
| 222 | echo "$0: it is available from $templateurl." >&2 | ||
| 223 | exit 1 | ||
| 224 | fi | ||
| 225 | |||
| 226 | # Function to return size of $1 in something resembling kilobytes. | ||
| 227 | calcsize() | ||
| 228 | { | ||
| 229 | size=`ls -ksl $1 | awk '{print $1}'` | ||
| 230 | echo $size | ||
| 231 | } | ||
| 232 | |||
| 233 | # copy_images OUTDIR HTML-FILE... | ||
| 234 | # ------------------------------- | ||
| 235 | # Copy all the images needed by the HTML-FILEs into OUTDIR. | ||
| 236 | # Look for them in . and the -I directories; this is simpler than what | ||
| 237 | # makeinfo supports with -I, but hopefully it will suffice. | ||
| 238 | copy_images() | ||
| 239 | { | ||
| 240 | local odir | ||
| 241 | odir=$1 | ||
| 242 | shift | ||
| 243 | $PERL -n -e " | ||
| 244 | BEGIN { | ||
| 245 | \$me = '$prog'; | ||
| 246 | \$odir = '$odir'; | ||
| 247 | @dirs = qw(. $dirs); | ||
| 248 | } | ||
| 249 | " -e ' | ||
| 250 | /<img src="(.*?)"/g && ++$need{$1}; | ||
| 251 | |||
| 252 | END { | ||
| 253 | #print "$me: @{[keys %need]}\n"; # for debugging, show images found. | ||
| 254 | FILE: for my $f (keys %need) { | ||
| 255 | for my $d (@dirs) { | ||
| 256 | if (-f "$d/$f") { | ||
| 257 | use File::Basename; | ||
| 258 | my $dest = dirname ("$odir/$f"); | ||
| 259 | # | ||
| 260 | use File::Path; | ||
| 261 | -d $dest || mkpath ($dest) | ||
| 262 | || die "$me: cannot mkdir $dest: $!\n"; | ||
| 263 | # | ||
| 264 | use File::Copy; | ||
| 265 | copy ("$d/$f", $dest) | ||
| 266 | || die "$me: cannot copy $d/$f to $dest: $!\n"; | ||
| 267 | next FILE; | ||
| 268 | } | ||
| 269 | } | ||
| 270 | die "$me: $ARGV: cannot find image $f\n"; | ||
| 271 | } | ||
| 272 | } | ||
| 273 | ' -- "$@" || exit 1 | ||
| 274 | } | ||
| 275 | |||
| 276 | case $outdir in | ||
| 277 | /*) abs_outdir=$outdir;; | ||
| 278 | *) abs_outdir=$srcdir/$outdir;; | ||
| 279 | esac | ||
| 280 | |||
| 281 | echo "Making output for $srcfile" | ||
| 282 | echo " in `pwd`" | ||
| 283 | mkdir -p "$outdir/" | ||
| 284 | |||
| 285 | # | ||
| 286 | if $generate_info; then | ||
| 287 | cmd="$SETLANG $MAKEINFO -o $PACKAGE.info $commonarg $infoarg \"$srcfile\"" | ||
| 288 | echo "Generating info... ($cmd)" | ||
| 289 | rm -f $PACKAGE.info* # get rid of any strays | ||
| 290 | eval "$cmd" | ||
| 291 | tar czf "$outdir/$PACKAGE.info.tar.gz" $PACKAGE.info* | ||
| 292 | ls -l "$outdir/$PACKAGE.info.tar.gz" | ||
| 293 | info_tgz_size=`calcsize "$outdir/$PACKAGE.info.tar.gz"` | ||
| 294 | # do not mv the info files, there's no point in having them available | ||
| 295 | # separately on the web. | ||
| 296 | fi # end info | ||
| 297 | |||
| 298 | # | ||
| 299 | if $generate_tex; then | ||
| 300 | cmd="$SETLANG $TEXI2DVI $dirargs $texarg \"$srcfile\"" | ||
| 301 | printf "\nGenerating dvi... ($cmd)\n" | ||
| 302 | eval "$cmd" | ||
| 303 | # compress/finish dvi: | ||
| 304 | gzip -f -9 $PACKAGE.dvi | ||
| 305 | dvi_gz_size=`calcsize $PACKAGE.dvi.gz` | ||
| 306 | mv $PACKAGE.dvi.gz "$outdir/" | ||
| 307 | ls -l "$outdir/$PACKAGE.dvi.gz" | ||
| 308 | |||
| 309 | cmd="$SETLANG $TEXI2DVI --pdf $dirargs $texarg \"$srcfile\"" | ||
| 310 | printf "\nGenerating pdf... ($cmd)\n" | ||
| 311 | eval "$cmd" | ||
| 312 | pdf_size=`calcsize $PACKAGE.pdf` | ||
| 313 | mv $PACKAGE.pdf "$outdir/" | ||
| 314 | ls -l "$outdir/$PACKAGE.pdf" | ||
| 315 | fi # end tex (dvi + pdf) | ||
| 316 | |||
| 317 | # | ||
| 318 | if $generate_ascii; then | ||
| 319 | opt="-o $PACKAGE.txt --no-split --no-headers $commonarg" | ||
| 320 | cmd="$SETLANG $MAKEINFO $opt \"$srcfile\"" | ||
| 321 | printf "\nGenerating ascii... ($cmd)\n" | ||
| 322 | eval "$cmd" | ||
| 323 | ascii_size=`calcsize $PACKAGE.txt` | ||
| 324 | gzip -f -9 -c $PACKAGE.txt >"$outdir/$PACKAGE.txt.gz" | ||
| 325 | ascii_gz_size=`calcsize "$outdir/$PACKAGE.txt.gz"` | ||
| 326 | mv $PACKAGE.txt "$outdir/" | ||
| 327 | ls -l "$outdir/$PACKAGE.txt" "$outdir/$PACKAGE.txt.gz" | ||
| 328 | fi | ||
| 329 | |||
| 330 | # | ||
| 331 | |||
| 332 | if $generate_html; then | ||
| 333 | # Split HTML at level $1. Used for texi2html. | ||
| 334 | html_split() | ||
| 335 | { | ||
| 336 | opt="--split=$1 --node-files $commonarg $htmlarg" | ||
| 337 | cmd="$SETLANG $TEXI2HTML --output $PACKAGE.html $opt \"$srcfile\"" | ||
| 338 | printf "\nGenerating html by $1... ($cmd)\n" | ||
| 339 | eval "$cmd" | ||
| 340 | split_html_dir=$PACKAGE.html | ||
| 341 | ( | ||
| 342 | cd ${split_html_dir} || exit 1 | ||
| 343 | ln -sf ${PACKAGE}.html index.html | ||
| 344 | tar -czf "$abs_outdir/${PACKAGE}.html_$1.tar.gz" -- *.html | ||
| 345 | ) | ||
| 346 | eval html_$1_tgz_size=`calcsize "$outdir/${PACKAGE}.html_$1.tar.gz"` | ||
| 347 | rm -f "$outdir"/html_$1/*.html | ||
| 348 | mkdir -p "$outdir/html_$1/" | ||
| 349 | mv ${split_html_dir}/*.html "$outdir/html_$1/" | ||
| 350 | rmdir ${split_html_dir} | ||
| 351 | } | ||
| 352 | |||
| 353 | if test -z "$use_texi2html"; then | ||
| 354 | opt="--no-split --html -o $PACKAGE.html $commonarg $htmlarg" | ||
| 355 | cmd="$SETLANG $MAKEINFO $opt \"$srcfile\"" | ||
| 356 | printf "\nGenerating monolithic html... ($cmd)\n" | ||
| 357 | rm -rf $PACKAGE.html # in case a directory is left over | ||
| 358 | eval "$cmd" | ||
| 359 | html_mono_size=`calcsize $PACKAGE.html` | ||
| 360 | gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz" | ||
| 361 | html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"` | ||
| 362 | copy_images "$outdir/" $PACKAGE.html | ||
| 363 | mv $PACKAGE.html "$outdir/" | ||
| 364 | ls -l "$outdir/$PACKAGE.html" "$outdir/$PACKAGE.html.gz" | ||
| 365 | |||
| 366 | # Before Texinfo 5.0, makeinfo did not accept a --split=HOW option, | ||
| 367 | # it just always split by node. So if we're splitting by node anyway, | ||
| 368 | # leave it out. | ||
| 369 | if test "x$split" = xnode; then | ||
| 370 | split_arg= | ||
| 371 | else | ||
| 372 | split_arg=--split=$split | ||
| 373 | fi | ||
| 374 | # | ||
| 375 | opt="--html -o $PACKAGE.html $split_arg $commonarg $htmlarg" | ||
| 376 | cmd="$SETLANG $MAKEINFO $opt \"$srcfile\"" | ||
| 377 | printf "\nGenerating html by $split... ($cmd)\n" | ||
| 378 | eval "$cmd" | ||
| 379 | split_html_dir=$PACKAGE.html | ||
| 380 | copy_images $split_html_dir/ $split_html_dir/*.html | ||
| 381 | ( | ||
| 382 | cd $split_html_dir || exit 1 | ||
| 383 | tar -czf "$abs_outdir/$PACKAGE.html_$split.tar.gz" -- * | ||
| 384 | ) | ||
| 385 | eval \ | ||
| 386 | html_${split}_tgz_size=`calcsize "$outdir/$PACKAGE.html_$split.tar.gz"` | ||
| 387 | rm -rf "$outdir/html_$split/" | ||
| 388 | mv $split_html_dir "$outdir/html_$split/" | ||
| 389 | du -s "$outdir/html_$split/" | ||
| 390 | ls -l "$outdir/$PACKAGE.html_$split.tar.gz" | ||
| 391 | |||
| 392 | else # use texi2html: | ||
| 393 | opt="--output $PACKAGE.html $commonarg $htmlarg" | ||
| 394 | cmd="$SETLANG $TEXI2HTML $opt \"$srcfile\"" | ||
| 395 | printf "\nGenerating monolithic html with texi2html... ($cmd)\n" | ||
| 396 | rm -rf $PACKAGE.html # in case a directory is left over | ||
| 397 | eval "$cmd" | ||
| 398 | html_mono_size=`calcsize $PACKAGE.html` | ||
| 399 | gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz" | ||
| 400 | html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"` | ||
| 401 | mv $PACKAGE.html "$outdir/" | ||
| 402 | |||
| 403 | html_split node | ||
| 404 | html_split chapter | ||
| 405 | html_split section | ||
| 406 | fi | ||
| 407 | fi # end html | ||
| 408 | |||
| 409 | # | ||
| 410 | printf "\nMaking .tar.gz for sources...\n" | ||
| 411 | d=`dirname $srcfile` | ||
| 412 | ( | ||
| 413 | cd "$d" | ||
| 414 | srcfiles=`ls -d *.texinfo *.texi *.txi *.eps $source_extra 2>/dev/null` || true | ||
| 415 | tar czfh "$abs_outdir/$PACKAGE.texi.tar.gz" $srcfiles | ||
| 416 | ls -l "$abs_outdir/$PACKAGE.texi.tar.gz" | ||
| 417 | ) | ||
| 418 | texi_tgz_size=`calcsize "$outdir/$PACKAGE.texi.tar.gz"` | ||
| 419 | |||
| 420 | # | ||
| 421 | # Do everything again through docbook. | ||
| 422 | if test -n "$docbook"; then | ||
| 423 | opt="-o - --docbook $commonarg" | ||
| 424 | cmd="$SETLANG $MAKEINFO $opt \"$srcfile\" >${srcdir}/$PACKAGE-db.xml" | ||
| 425 | printf "\nGenerating docbook XML... ($cmd)\n" | ||
| 426 | eval "$cmd" | ||
| 427 | docbook_xml_size=`calcsize $PACKAGE-db.xml` | ||
| 428 | gzip -f -9 -c $PACKAGE-db.xml >"$outdir/$PACKAGE-db.xml.gz" | ||
| 429 | docbook_xml_gz_size=`calcsize "$outdir/$PACKAGE-db.xml.gz"` | ||
| 430 | mv $PACKAGE-db.xml "$outdir/" | ||
| 431 | |||
| 432 | split_html_db_dir=html_node_db | ||
| 433 | opt="$commonarg -o $split_html_db_dir" | ||
| 434 | cmd="$DOCBOOK2HTML $opt \"${outdir}/$PACKAGE-db.xml\"" | ||
| 435 | printf "\nGenerating docbook HTML... ($cmd)\n" | ||
| 436 | eval "$cmd" | ||
| 437 | ( | ||
| 438 | cd ${split_html_db_dir} || exit 1 | ||
| 439 | tar -czf "$abs_outdir/${PACKAGE}.html_node_db.tar.gz" -- *.html | ||
| 440 | ) | ||
| 441 | html_node_db_tgz_size=`calcsize "$outdir/${PACKAGE}.html_node_db.tar.gz"` | ||
| 442 | rm -f "$outdir"/html_node_db/*.html | ||
| 443 | mkdir -p "$outdir/html_node_db" | ||
| 444 | mv ${split_html_db_dir}/*.html "$outdir/html_node_db/" | ||
| 445 | rmdir ${split_html_db_dir} | ||
| 446 | |||
| 447 | cmd="$DOCBOOK2TXT \"${outdir}/$PACKAGE-db.xml\"" | ||
| 448 | printf "\nGenerating docbook ASCII... ($cmd)\n" | ||
| 449 | eval "$cmd" | ||
| 450 | docbook_ascii_size=`calcsize $PACKAGE-db.txt` | ||
| 451 | mv $PACKAGE-db.txt "$outdir/" | ||
| 452 | |||
| 453 | cmd="$DOCBOOK2PDF \"${outdir}/$PACKAGE-db.xml\"" | ||
| 454 | printf "\nGenerating docbook PDF... ($cmd)\n" | ||
| 455 | eval "$cmd" | ||
| 456 | docbook_pdf_size=`calcsize $PACKAGE-db.pdf` | ||
| 457 | mv $PACKAGE-db.pdf "$outdir/" | ||
| 458 | fi | ||
| 459 | |||
| 460 | # | ||
| 461 | printf "\nMaking index.html for $PACKAGE...\n" | ||
| 462 | if test -z "$use_texi2html"; then | ||
| 463 | CONDS="/%%IF *HTML_SECTION%%/,/%%ENDIF *HTML_SECTION%%/d;\ | ||
| 464 | /%%IF *HTML_CHAPTER%%/,/%%ENDIF *HTML_CHAPTER%%/d" | ||
| 465 | else | ||
| 466 | # should take account of --split here. | ||
| 467 | CONDS="/%%ENDIF.*%%/d;/%%IF *HTML_SECTION%%/d;/%%IF *HTML_CHAPTER%%/d" | ||
| 468 | fi | ||
| 469 | |||
| 470 | curdate=`$SETLANG date '+%B %d, %Y'` | ||
| 471 | sed \ | ||
| 472 | -e "s!%%TITLE%%!$MANUAL_TITLE!g" \ | ||
| 473 | -e "s!%%EMAIL%%!$EMAIL!g" \ | ||
| 474 | -e "s!%%PACKAGE%%!$PACKAGE!g" \ | ||
| 475 | -e "s!%%DATE%%!$curdate!g" \ | ||
| 476 | -e "s!%%HTML_MONO_SIZE%%!$html_mono_size!g" \ | ||
| 477 | -e "s!%%HTML_MONO_GZ_SIZE%%!$html_mono_gz_size!g" \ | ||
| 478 | -e "s!%%HTML_NODE_TGZ_SIZE%%!$html_node_tgz_size!g" \ | ||
| 479 | -e "s!%%HTML_SECTION_TGZ_SIZE%%!$html_section_tgz_size!g" \ | ||
| 480 | -e "s!%%HTML_CHAPTER_TGZ_SIZE%%!$html_chapter_tgz_size!g" \ | ||
| 481 | -e "s!%%INFO_TGZ_SIZE%%!$info_tgz_size!g" \ | ||
| 482 | -e "s!%%DVI_GZ_SIZE%%!$dvi_gz_size!g" \ | ||
| 483 | -e "s!%%PDF_SIZE%%!$pdf_size!g" \ | ||
| 484 | -e "s!%%ASCII_SIZE%%!$ascii_size!g" \ | ||
| 485 | -e "s!%%ASCII_GZ_SIZE%%!$ascii_gz_size!g" \ | ||
| 486 | -e "s!%%TEXI_TGZ_SIZE%%!$texi_tgz_size!g" \ | ||
| 487 | -e "s!%%DOCBOOK_HTML_NODE_TGZ_SIZE%%!$html_node_db_tgz_size!g" \ | ||
| 488 | -e "s!%%DOCBOOK_ASCII_SIZE%%!$docbook_ascii_size!g" \ | ||
| 489 | -e "s!%%DOCBOOK_PDF_SIZE%%!$docbook_pdf_size!g" \ | ||
| 490 | -e "s!%%DOCBOOK_XML_SIZE%%!$docbook_xml_size!g" \ | ||
| 491 | -e "s!%%DOCBOOK_XML_GZ_SIZE%%!$docbook_xml_gz_size!g" \ | ||
| 492 | -e "s,%%SCRIPTURL%%,$scripturl,g" \ | ||
| 493 | -e "s!%%SCRIPTNAME%%!$prog!g" \ | ||
| 494 | -e "$CONDS" \ | ||
| 495 | $GENDOCS_TEMPLATE_DIR/gendocs_template >"$outdir/index.html" | ||
| 496 | |||
| 497 | echo "Done, see $outdir/ subdirectory for new files." | ||
| 498 | |||
| 499 | # Local variables: | ||
| 500 | # eval: (add-hook 'write-file-hooks 'time-stamp) | ||
| 501 | # time-stamp-start: "scriptversion=" | ||
| 502 | # time-stamp-format: "%:y-%02m-%02d.%02H" | ||
| 503 | # time-stamp-end: "$" | ||
| 504 | # End: | ||
diff --git a/doc/documentation/gendocs_template b/doc/documentation/gendocs_template deleted file mode 100644 index 178f6cb4c..000000000 --- a/doc/documentation/gendocs_template +++ /dev/null | |||
| @@ -1,91 +0,0 @@ | |||
| 1 | <!--#include virtual="/server/header.html" --> | ||
| 2 | <!-- Parent-Version: 1.77 --> | ||
| 3 | <title>%%TITLE%% - GNU Project - Free Software Foundation</title> | ||
| 4 | <!--#include virtual="/server/banner.html" --> | ||
| 5 | <h2>%%TITLE%%</h2> | ||
| 6 | |||
| 7 | <address>Free Software Foundation</address> | ||
| 8 | <address>last updated %%DATE%%</address> | ||
| 9 | |||
| 10 | <p>This manual (%%PACKAGE%%) is available in the following formats:</p> | ||
| 11 | |||
| 12 | <ul> | ||
| 13 | <li><a href="%%PACKAGE%%.html">HTML | ||
| 14 | (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li> | ||
| 15 | <li><a href="html_node/index.html">HTML</a> - with one web page per | ||
| 16 | node.</li> | ||
| 17 | %%IF HTML_SECTION%% | ||
| 18 | <li><a href="html_section/index.html">HTML</a> - with one web page per | ||
| 19 | section.</li> | ||
| 20 | %%ENDIF HTML_SECTION%% | ||
| 21 | %%IF HTML_CHAPTER%% | ||
| 22 | <li><a href="html_chapter/index.html">HTML</a> - with one web page per | ||
| 23 | chapter.</li> | ||
| 24 | %%ENDIF HTML_CHAPTER%% | ||
| 25 | <li><a href="%%PACKAGE%%.html.gz">HTML compressed | ||
| 26 | (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on | ||
| 27 | one web page.</li> | ||
| 28 | <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed | ||
| 29 | (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> - | ||
| 30 | with one web page per node.</li> | ||
| 31 | %%IF HTML_SECTION%% | ||
| 32 | <li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed | ||
| 33 | (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> - | ||
| 34 | with one web page per section.</li> | ||
| 35 | %%ENDIF HTML_SECTION%% | ||
| 36 | %%IF HTML_CHAPTER%% | ||
| 37 | <li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed | ||
| 38 | (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> - | ||
| 39 | with one web page per chapter.</li> | ||
| 40 | %%ENDIF HTML_CHAPTER%% | ||
| 41 | <li><a href="%%PACKAGE%%.info.tar.gz">Info document | ||
| 42 | (%%INFO_TGZ_SIZE%%K bytes gzipped tar file)</a>.</li> | ||
| 43 | <li><a href="%%PACKAGE%%.txt">ASCII text | ||
| 44 | (%%ASCII_SIZE%%K bytes)</a>.</li> | ||
| 45 | <li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed | ||
| 46 | (%%ASCII_GZ_SIZE%%K bytes gzipped)</a>.</li> | ||
| 47 | <li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file | ||
| 48 | (%%DVI_GZ_SIZE%%K bytes gzipped)</a>.</li> | ||
| 49 | <li><a href="%%PACKAGE%%.pdf">PDF file | ||
| 50 | (%%PDF_SIZE%%K bytes)</a>.</li> | ||
| 51 | <li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source | ||
| 52 | (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li> | ||
| 53 | </ul> | ||
| 54 | |||
| 55 | <p>You can <a href="http://shop.fsf.org/">buy printed copies of | ||
| 56 | some manuals</a> (among other items) from the Free Software Foundation; | ||
| 57 | this helps support FSF activities.</p> | ||
| 58 | |||
| 59 | <p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%% | ||
| 60 | script</a>.)</p> | ||
| 61 | |||
| 62 | <!-- If needed, change the copyright block at the bottom. In general, | ||
| 63 | all pages on the GNU web server should have the section about | ||
| 64 | verbatim copying. Please do NOT remove this without talking | ||
| 65 | with the webmasters first. | ||
| 66 | Please make sure the copyright date is consistent with the document | ||
| 67 | and that it is like this: "2001, 2002", not this: "2001-2002". --> | ||
| 68 | </div><!-- for id="content", starts in the include above --> | ||
| 69 | <!--#include virtual="/server/footer.html" --> | ||
| 70 | <div id="footer"> | ||
| 71 | <div class="unprintable"> | ||
| 72 | |||
| 73 | <p>Please send general FSF & GNU inquiries to | ||
| 74 | <a href="mailto:gnu@gnu.org"><gnu@gnu.org></a>. | ||
| 75 | There are also <a href="/contact/">other ways to contact</a> | ||
| 76 | the FSF. Broken links and other corrections or suggestions can be sent | ||
| 77 | to <a href="mailto:%%EMAIL%%"><%%EMAIL%%></a>.</p> | ||
| 78 | </div> | ||
| 79 | |||
| 80 | <p>Copyright © 2017 Free Software Foundation, Inc.</p> | ||
| 81 | |||
| 82 | <p>This page is licensed under a <a rel="license" | ||
| 83 | href="http://creativecommons.org/licenses/by-nd/3.0/us/">Creative | ||
| 84 | Commons Attribution-NoDerivs 3.0 United States License</a>.</p> | ||
| 85 | |||
| 86 | <!--#include virtual="/server/bottom-notes.html" --> | ||
| 87 | |||
| 88 | </div> | ||
| 89 | </div> | ||
| 90 | </body> | ||
| 91 | </html> | ||
diff --git a/doc/documentation/gendocs_template_min b/doc/documentation/gendocs_template_min deleted file mode 100644 index 112fa3bfb..000000000 --- a/doc/documentation/gendocs_template_min +++ /dev/null | |||
| @@ -1,93 +0,0 @@ | |||
| 1 | <?xml version="1.0" encoding="utf-8" ?> | ||
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
| 3 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
| 4 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> | ||
| 5 | |||
| 6 | <head> | ||
| 7 | <title>%%TITLE%% - GNU Project - Free Software Foundation</title> | ||
| 8 | <meta http-equiv="content-type" content='text/html; charset=utf-8' /> | ||
| 9 | <link rel="stylesheet" type="text/css" href="/gnu.css" /> | ||
| 10 | </head> | ||
| 11 | |||
| 12 | <body> | ||
| 13 | |||
| 14 | <h3>%%TITLE%%</h3> | ||
| 15 | |||
| 16 | <address>Free Software Foundation</address> | ||
| 17 | <address>last updated %%DATE%%</address> | ||
| 18 | <p> | ||
| 19 | <a href="/graphics/gnu-head.jpg"> | ||
| 20 | <img src="/graphics/gnu-head-sm.jpg" | ||
| 21 | alt=" [image of the head of a GNU] " width="129" height="122"/> | ||
| 22 | </a> | ||
| 23 | </p> | ||
| 24 | <hr /> | ||
| 25 | |||
| 26 | <p>This manual (%%PACKAGE%%) is available in the following formats:</p> | ||
| 27 | |||
| 28 | <ul> | ||
| 29 | <li><a href="%%PACKAGE%%.html">HTML | ||
| 30 | (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li> | ||
| 31 | <li><a href="html_node/index.html">HTML</a> - with one web page per | ||
| 32 | node.</li> | ||
| 33 | %%IF HTML_SECTION%% | ||
| 34 | <li><a href="html_section/index.html">HTML</a> - with one web page per | ||
| 35 | section.</li> | ||
| 36 | %%ENDIF HTML_SECTION%% | ||
| 37 | %%IF HTML_CHAPTER%% | ||
| 38 | <li><a href="html_chapter/index.html">HTML</a> - with one web page per | ||
| 39 | chapter.</li> | ||
| 40 | %%ENDIF HTML_CHAPTER%% | ||
| 41 | <li><a href="%%PACKAGE%%.html.gz">HTML compressed | ||
| 42 | (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on | ||
| 43 | one web page.</li> | ||
| 44 | <li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed | ||
| 45 | (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> - | ||
| 46 | with one web page per node.</li> | ||
| 47 | %%IF HTML_SECTION%% | ||
| 48 | <li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed | ||
| 49 | (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> - | ||
| 50 | with one web page per section.</li> | ||
| 51 | %%ENDIF HTML_SECTION%% | ||
| 52 | %%IF HTML_CHAPTER%% | ||
| 53 | <li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed | ||
| 54 | (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> - | ||
| 55 | with one web page per chapter.</li> | ||
| 56 | %%ENDIF HTML_CHAPTER%% | ||
| 57 | <li><a href="%%PACKAGE%%.info.tar.gz">Info document | ||
| 58 | (%%INFO_TGZ_SIZE%%K bytes gzipped tar file)</a>.</li> | ||
| 59 | <li><a href="%%PACKAGE%%.txt">ASCII text | ||
| 60 | (%%ASCII_SIZE%%K bytes)</a>.</li> | ||
| 61 | <li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed | ||
| 62 | (%%ASCII_GZ_SIZE%%K bytes gzipped)</a>.</li> | ||
| 63 | <li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file | ||
| 64 | (%%DVI_GZ_SIZE%%K bytes gzipped)</a>.</li> | ||
| 65 | <li><a href="%%PACKAGE%%.pdf">PDF file | ||
| 66 | (%%PDF_SIZE%%K bytes)</a>.</li> | ||
| 67 | <li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source | ||
| 68 | (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li> | ||
| 69 | </ul> | ||
| 70 | |||
| 71 | <p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%% | ||
| 72 | script</a>.)</p> | ||
| 73 | |||
| 74 | <div id="footer" class="copyright"> | ||
| 75 | |||
| 76 | <p>Please send general FSF & GNU inquiries to | ||
| 77 | <a href="mailto:gnu@gnu.org"><gnu@gnu.org></a>. | ||
| 78 | There are also <a href="/contact/">other ways to contact</a> | ||
| 79 | the FSF. Broken links and other corrections or suggestions can be sent | ||
| 80 | to <a href="mailto:%%EMAIL%%"><%%EMAIL%%></a>.</p> | ||
| 81 | </div> | ||
| 82 | |||
| 83 | <p>Copyright © 2017 Free Software Foundation, Inc.</p> | ||
| 84 | |||
| 85 | <p>This page is licensed under a <a rel="license" | ||
| 86 | href="http://creativecommons.org/licenses/by-nd/3.0/us/">Creative | ||
| 87 | Commons Attribution-NoDerivs 3.0 United States License</a>.</p> | ||
| 88 | |||
| 89 | <!--#include virtual="/server/bottom-notes.html" --> | ||
| 90 | |||
| 91 | </div> | ||
| 92 | </body> | ||
| 93 | </html> | ||
diff --git a/doc/documentation/gnunet-c-tutorial.texi b/doc/documentation/gnunet-c-tutorial.texi deleted file mode 100644 index b3bcdf18a..000000000 --- a/doc/documentation/gnunet-c-tutorial.texi +++ /dev/null | |||
| @@ -1,1559 +0,0 @@ | |||
| 1 | \input texinfo | ||
| 2 | @c %**start of header | ||
| 3 | @setfilename gnunet-c-tutorial.info | ||
| 4 | @documentencoding UTF-8 | ||
| 5 | @settitle GNUnet C Tutorial | ||
| 6 | @c @exampleindent 2 | ||
| 7 | @c %**end of header | ||
| 8 | |||
| 9 | @include version.texi | ||
| 10 | |||
| 11 | @copying | ||
| 12 | Copyright @copyright{} 2001-2018 GNUnet e.V. | ||
| 13 | |||
| 14 | Permission is granted to copy, distribute and/or modify this document | ||
| 15 | under the terms of the GNU Free Documentation License, Version 1.3 or | ||
| 16 | any later version published by the Free Software Foundation; with no | ||
| 17 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A | ||
| 18 | copy of the license is included in the section entitled ``GNU Free | ||
| 19 | Documentation License''. | ||
| 20 | |||
| 21 | A copy of the license is also available from the Free Software | ||
| 22 | Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}. | ||
| 23 | |||
| 24 | Alternately, this document is also available under the General | ||
| 25 | Public License, version 3 or later, as published by the Free Software | ||
| 26 | Foundation. A copy of the license is included in the section entitled | ||
| 27 | ``GNU General Public License''. | ||
| 28 | |||
| 29 | A copy of the license is also available from the Free Software | ||
| 30 | Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. | ||
| 31 | @end copying | ||
| 32 | |||
| 33 | @dircategory Tutorial | ||
| 34 | @direntry | ||
| 35 | * GNUnet-C-Tutorial: (gnunet-c-tutorial). C Tutorial for GNunet | ||
| 36 | @end direntry | ||
| 37 | |||
| 38 | |||
| 39 | @titlepage | ||
| 40 | @title GNUnet C Tutorial | ||
| 41 | @subtitle A Tutorial for GNUnet @value{VERSION} (C version) | ||
| 42 | @author The GNUnet Developers | ||
| 43 | |||
| 44 | @page | ||
| 45 | @vskip 0pt plus 1filll | ||
| 46 | |||
| 47 | @insertcopying | ||
| 48 | @end titlepage | ||
| 49 | |||
| 50 | @contents | ||
| 51 | |||
| 52 | @c **** TODO | ||
| 53 | @c 1. Update content? | ||
| 54 | @c 2. Either reference main documentation or | ||
| 55 | @c 3. Merge this into main documentation | ||
| 56 | |||
| 57 | @node Top | ||
| 58 | @top Introduction | ||
| 59 | |||
| 60 | This tutorials explains how to install GNUnet on a | ||
| 61 | GNU/Linux system and gives an introduction on how | ||
| 62 | GNUnet can be used to develop a Peer-to-Peer application. | ||
| 63 | Detailed installation instructions for | ||
| 64 | various operating systems and a detailed list of all | ||
| 65 | dependencies can be found on our website at | ||
| 66 | @uref{https://gnunet.org/installation} and in our | ||
| 67 | Reference Documentation (GNUnet Handbook). | ||
| 68 | |||
| 69 | Please read this tutorial carefully since every single step is | ||
| 70 | important, and do not hesitate to contact the GNUnet team if you have | ||
| 71 | any questions or problems! Visit this link in your webbrowser to learn | ||
| 72 | how to contact the GNUnet team: | ||
| 73 | @uref{https://gnunet.org/contact_information} | ||
| 74 | |||
| 75 | @menu | ||
| 76 | |||
| 77 | * Installing GNUnet:: Installing GNUnet | ||
| 78 | * Introduction to GNUnet Architecture:: Introduction to GNUnet Architecture | ||
| 79 | * First Steps with GNUnet:: First Steps with GNUnet | ||
| 80 | * Developing Applications:: Developing Applications | ||
| 81 | |||
| 82 | @detailmenu | ||
| 83 | --- The Detailed Node Listing --- | ||
| 84 | |||
| 85 | Installing GNUnet | ||
| 86 | |||
| 87 | * Obtaining a stable version:: | ||
| 88 | * Installing Build Tool Chain and Dependencies:: | ||
| 89 | * Obtaining the latest version from Git:: | ||
| 90 | * Compiling and Installing GNUnet:: | ||
| 91 | * Common Issues - Check your GNUnet installation:: | ||
| 92 | |||
| 93 | Introduction to GNUnet Architecture | ||
| 94 | |||
| 95 | First Steps with GNUnet | ||
| 96 | |||
| 97 | * Configure your peer:: | ||
| 98 | * Start a peer:: | ||
| 99 | * Monitor a peer:: | ||
| 100 | * Starting Two Peers by Hand:: | ||
| 101 | * Starting Peers Using the Testbed Service:: | ||
| 102 | |||
| 103 | Developing Applications | ||
| 104 | |||
| 105 | * gnunet-ext:: | ||
| 106 | * Adapting the Template:: | ||
| 107 | * Writing a Client Application:: | ||
| 108 | * Writing a Service:: | ||
| 109 | * Interacting directly with other Peers using the CORE Service:: | ||
| 110 | * Storing peer-specific data using the PEERSTORE service:: | ||
| 111 | * Using the DHT:: | ||
| 112 | * Debugging with gnunet-arm:: | ||
| 113 | |||
| 114 | @end detailmenu | ||
| 115 | @end menu | ||
| 116 | |||
| 117 | @node Installing GNUnet | ||
| 118 | @chapter Installing GNUnet | ||
| 119 | |||
| 120 | First of all you have to install a current version of GNUnet. | ||
| 121 | You can download a tarball of a stable version from GNU FTP mirrors | ||
| 122 | or obtain the latest development version from our Git repository. | ||
| 123 | |||
| 124 | Most of the time you should prefer to download the stable version | ||
| 125 | since with the latest development version things can be broken, | ||
| 126 | functionality can be changed or tests can fail. You should only use | ||
| 127 | the development version if you know that you require a certain | ||
| 128 | feature or a certain issue has been fixed since the last release. | ||
| 129 | |||
| 130 | @menu | ||
| 131 | * Obtaining a stable version:: | ||
| 132 | * Installing Build Tool Chain and Dependencies:: | ||
| 133 | * Obtaining the latest version from Git:: | ||
| 134 | * Compiling and Installing GNUnet:: | ||
| 135 | * Common Issues - Check your GNUnet installation:: | ||
| 136 | @end menu | ||
| 137 | |||
| 138 | @node Obtaining a stable version | ||
| 139 | @section Obtaining a stable version | ||
| 140 | |||
| 141 | Download the tarball from | ||
| 142 | @indicateurl{https://ftp.gnu.org/gnu/gnunet/gnunet-@value{VERSION}.tar.gz}. | ||
| 143 | |||
| 144 | Make sure to download the associated @file{.sig} file and to verify the | ||
| 145 | authenticity of the tarball against it, like this: | ||
| 146 | |||
| 147 | @example | ||
| 148 | $ wget https://ftp.gnu.org/gnu/gnunet/gnunet-@value{VERSION}.tar.gz.sig | ||
| 149 | $ gpg --verify-files gnunet-@value{VERSION}.tar.gz.sig | ||
| 150 | @end example | ||
| 151 | |||
| 152 | @noindent | ||
| 153 | If this command fails because you do not have the required public key, | ||
| 154 | then you need to run the following command to import it: | ||
| 155 | |||
| 156 | @example | ||
| 157 | $ gpg --keyserver keys.gnupg.net --recv-keys 48426C7E | ||
| 158 | @end example | ||
| 159 | |||
| 160 | @noindent | ||
| 161 | and rerun the @code{gpg --verify-files} command. | ||
| 162 | |||
| 163 | @b{Note:}@ | ||
| 164 | @b{The pub key to sign the 0.10.1 release has been | ||
| 165 | revoked}. You will get an error message stating that | ||
| 166 | @b{there is no known public key or that it has been revoked}. | ||
| 167 | The next release of GNUnet will have a valid signature | ||
| 168 | again. We are sorry for the inconvenience this causes. | ||
| 169 | Another possible source you could use is our | ||
| 170 | "gnunet" git repository which, since the change from SVN to git in 2016, | ||
| 171 | has mandatory signed commits by every developer. | ||
| 172 | |||
| 173 | After verifying the signature you can extract the tarball. | ||
| 174 | The resulting directory will be renamed to @file{gnunet}, which we will | ||
| 175 | be using in the remainder of this document to refer to the | ||
| 176 | root of the source directory. | ||
| 177 | |||
| 178 | @example | ||
| 179 | $ tar xvzf gnunet-@value{VERSION}.tar.gz | ||
| 180 | $ mv gnunet-@value{VERSION} gnunet | ||
| 181 | @end example | ||
| 182 | |||
| 183 | @c FIXME: This can be irritating for the reader - First we say git should | ||
| 184 | @c be avoid unless it is really required, and then we write this | ||
| 185 | @c paragraph: | ||
| 186 | @noindent | ||
| 187 | However, please note that stable versions can be very outdated. | ||
| 188 | As a developer you are @b{strongly} encouraged to use the version | ||
| 189 | from @uref{https://gnunet.org/git/, git}. | ||
| 190 | |||
| 191 | @node Installing Build Tool Chain and Dependencies | ||
| 192 | @section Installing Build Tool Chain and Dependencies | ||
| 193 | |||
| 194 | To successfully compile GNUnet, you need the tools to build GNUnet and | ||
| 195 | the required dependencies. Please take a look at the | ||
| 196 | GNUnet Reference Documentation | ||
| 197 | (@pxref{Dependencies, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation}) | ||
| 198 | for a list of required dependencies and | ||
| 199 | (@pxref{Generic installation instructions, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation}) | ||
| 200 | read its Installation chapter for specific instructions for | ||
| 201 | your Operating System. | ||
| 202 | Please check the notes at the end of the configure process about | ||
| 203 | required dependencies. | ||
| 204 | |||
| 205 | For GNUnet bootstrapping support and the HTTP(S) plugin you should | ||
| 206 | install @uref{https://gnunet.org/gnurl, libgnurl}. | ||
| 207 | For the filesharing service you should install at least one of the | ||
| 208 | datastore backends (MySQL, SQlite and PostgreSQL are supported). | ||
| 209 | |||
| 210 | @node Obtaining the latest version from Git | ||
| 211 | @section Obtaining the latest version from Git | ||
| 212 | |||
| 213 | The latest development version can be obtained from our Git repository. | ||
| 214 | To get the code you need to have @code{Git} installed. Usually your | ||
| 215 | Operating System package manager should provide a suitable distribution | ||
| 216 | of git (otherwise check out Guix or Nix). If you are using an Operating | ||
| 217 | System based on Debian's apt: | ||
| 218 | |||
| 219 | @example | ||
| 220 | $ sudo apt-get install git | ||
| 221 | @end example | ||
| 222 | |||
| 223 | This is required for obtaining the repository, which is achieved with | ||
| 224 | the following command: | ||
| 225 | |||
| 226 | @example | ||
| 227 | $ git clone https://gnunet.org/git/gnunet | ||
| 228 | @end example | ||
| 229 | |||
| 230 | @noindent | ||
| 231 | After cloning the repository, you have to execute the @file{bootstrap} | ||
| 232 | script in the new directory: | ||
| 233 | |||
| 234 | @example | ||
| 235 | $ cd gnunet | ||
| 236 | $ ./bootstrap | ||
| 237 | @end example | ||
| 238 | |||
| 239 | @noindent | ||
| 240 | The remainder of this tutorial will assume that you have the | ||
| 241 | Git branch ``master'' checked out. | ||
| 242 | |||
| 243 | @node Compiling and Installing GNUnet | ||
| 244 | @section Compiling and Installing GNUnet | ||
| 245 | |||
| 246 | Note: This section is a duplication of the more in depth | ||
| 247 | @pxref{GNUnet Installation Handbook, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation}. | ||
| 248 | |||
| 249 | First, you need to install libgnupgerror @geq{} 1.27 and | ||
| 250 | libgcrypt @geq{} 1.7.6: | ||
| 251 | |||
| 252 | @example | ||
| 253 | $ export GNUPGFTP="https://www.gnupg.org/ftp/gcrypt" | ||
| 254 | $ wget $GNUPGFTP/libgpg-error/libgpg-error-1.27.tar.bz2 | ||
| 255 | $ tar xf libgpg-error-1.27.tar.bz2 | ||
| 256 | $ cd libgpg-error-1.27 | ||
| 257 | $ ./configure | ||
| 258 | $ make | ||
| 259 | $ sudo make install | ||
| 260 | $ cd .. | ||
| 261 | @end example | ||
| 262 | |||
| 263 | @example | ||
| 264 | $ export GNUPGFTP="https://www.gnupg.org/ftp/gcrypt" | ||
| 265 | $ wget $GNUPGFTP/libgcrypt/libgcrypt-1.7.6.tar.bz2 | ||
| 266 | $ tar xf libgcrypt-1.7.6.tar.bz2 | ||
| 267 | $ cd libgcrypt-1.7.6 | ||
| 268 | $ ./configure | ||
| 269 | $ make | ||
| 270 | $ sudo make install | ||
| 271 | $ cd .. | ||
| 272 | @end example | ||
| 273 | |||
| 274 | @menu | ||
| 275 | * Installation:: | ||
| 276 | @end menu | ||
| 277 | |||
| 278 | @node Installation | ||
| 279 | @subsection Installation | ||
| 280 | Assuming all dependencies are installed, the following commands will | ||
| 281 | compile and install GNUnet in your home directory. You can specify the | ||
| 282 | directory where GNUnet will be installed by changing the | ||
| 283 | @code{--prefix} value when calling @command{./configure}. If | ||
| 284 | you do not specifiy a prefix, GNUnet is installed in the directory | ||
| 285 | @file{/usr/local}. When developing new applications you may want | ||
| 286 | to enable verbose logging by adding @code{--enable-logging=verbose}: | ||
| 287 | |||
| 288 | @example | ||
| 289 | $ export PREFIX=$HOME | ||
| 290 | $ ./configure --prefix=$PREFIX --enable-logging | ||
| 291 | $ make | ||
| 292 | $ make install | ||
| 293 | @end example | ||
| 294 | |||
| 295 | @noindent | ||
| 296 | After installing GNUnet you have to add your GNUnet installation | ||
| 297 | to your path environmental variable. In addition you have to | ||
| 298 | create the @file{.config} directory in your home directory | ||
| 299 | (unless it already exists) where GNUnet stores its data and an | ||
| 300 | empty GNUnet configuration file: | ||
| 301 | |||
| 302 | @example | ||
| 303 | $ export PATH=$PATH:$PREFIX/bin | ||
| 304 | $ echo export PATH=$PREFIX/bin:\\$PATH >> ~/.bashrc | ||
| 305 | $ mkdir ~/.config/ | ||
| 306 | $ touch ~/.config/gnunet.conf | ||
| 307 | @end example | ||
| 308 | |||
| 309 | @node Common Issues - Check your GNUnet installation | ||
| 310 | @section Common Issues - Check your GNUnet installation | ||
| 311 | |||
| 312 | You should check your installation to ensure that installing GNUnet | ||
| 313 | was successful up to this point. You should be able to access GNUnet's | ||
| 314 | binaries and run GNUnet's self check. | ||
| 315 | |||
| 316 | @example | ||
| 317 | $ which gnunet-arm | ||
| 318 | $PREFIX/bin/gnunet-arm | ||
| 319 | @end example | ||
| 320 | |||
| 321 | @noindent | ||
| 322 | should return $PREFIX/bin/gnunet-arm (where $PREFIX is the location | ||
| 323 | you have set earlier). It should be located in your | ||
| 324 | GNUnet installation and the output should not be empty. | ||
| 325 | |||
| 326 | If you see an output like: | ||
| 327 | |||
| 328 | @example | ||
| 329 | $ which gnunet-arm | ||
| 330 | @end example | ||
| 331 | |||
| 332 | @noindent | ||
| 333 | check your PATH variable to ensure GNUnet's @file{bin} directory is | ||
| 334 | included. | ||
| 335 | |||
| 336 | GNUnet provides tests for all of its subcomponents. Assuming you have | ||
| 337 | successfully built GNUnet, run | ||
| 338 | |||
| 339 | @example | ||
| 340 | $ cd gnunet | ||
| 341 | $ make check | ||
| 342 | @end example | ||
| 343 | |||
| 344 | @noindent | ||
| 345 | to execute tests for all components. @command{make check} traverses all | ||
| 346 | subdirectories in @file{src}. For every subdirectory you should | ||
| 347 | get a message like this: | ||
| 348 | |||
| 349 | @example | ||
| 350 | make[2]: Entering directory `/home/$USER/gnunet/contrib' | ||
| 351 | PASS: test_gnunet_prefix | ||
| 352 | ============= | ||
| 353 | 1 test passed | ||
| 354 | ============= | ||
| 355 | @end example | ||
| 356 | |||
| 357 | @node Introduction to GNUnet Architecture | ||
| 358 | @chapter Introduction to GNUnet Architecture | ||
| 359 | |||
| 360 | GNUnet is organized in layers and services. Each service is composed of a | ||
| 361 | main service implementation and a client library for other programs to use | ||
| 362 | the service's functionality, described by an API. | ||
| 363 | @c This approach is shown in | ||
| 364 | @c FIXME: enable this once the commented block below works: | ||
| 365 | @c figure~\ref fig:service. | ||
| 366 | Some services provide an additional command line tool to enable the user | ||
| 367 | to interact with the service. | ||
| 368 | |||
| 369 | Very often it is other GNUnet services that will use these APIs to build | ||
| 370 | the higher layers of GNUnet on top of the lower ones. Each layer expands | ||
| 371 | or extends the functionality of the service below (for instance, to build | ||
| 372 | a mesh on top of a DHT). | ||
| 373 | @c FXIME: See comment above. | ||
| 374 | @c See figure ~\ref fig:interaction for an illustration of this approach. | ||
| 375 | |||
| 376 | @c ** @image filename[, width[, height[, alttext[, extension]]]] | ||
| 377 | @c FIXME: Texlive (?) 20112 makes the assumption that this means | ||
| 378 | @c 'images/OBJECTNAME.txt' but later versions of it (2017) use this | ||
| 379 | @c syntax as described below. | ||
| 380 | @c TODO: Checkout the makedoc script Guile uses. | ||
| 381 | |||
| 382 | @c FIXME!!! | ||
| 383 | @c @image{images/gnunet-tutorial-service,,5in,Service with API and network protocol,.png} | ||
| 384 | @c @image{images/gnunet-tutorial-system,,5in,The layered system architecture of GNUnet,.png} | ||
| 385 | |||
| 386 | @c \begin{figure}[!h] | ||
| 387 | @c \begin{center} | ||
| 388 | @c % \begin{subfigure} | ||
| 389 | @c \begin{subfigure}[b]{0.3\textwidth} | ||
| 390 | @c \centering | ||
| 391 | @c \includegraphics[width=\textwidth]{figs/Service.pdf} | ||
| 392 | @c \caption{Service with API and network protocol} | ||
| 393 | @c \label{fig:service} | ||
| 394 | @c \end{subfigure} | ||
| 395 | @c ~~~~~~~~~~ | ||
| 396 | @c \begin{subfigure}[b]{0.3\textwidth} | ||
| 397 | @c \centering | ||
| 398 | @c \includegraphics[width=\textwidth]{figs/System.pdf} | ||
| 399 | @c \caption{Service interaction} | ||
| 400 | @c \label{fig:interaction} | ||
| 401 | @c \end{subfigure} | ||
| 402 | @c \end{center} | ||
| 403 | @c \caption{GNUnet's layered system architecture} | ||
| 404 | @c \end{figure} | ||
| 405 | |||
| 406 | The main service implementation runs as a standalone process in the | ||
| 407 | Operating System and the client code runs as part of the client program, | ||
| 408 | so crashes of a client do not affect the service process or other clients. | ||
| 409 | The service and the clients communicate via a message protocol to be | ||
| 410 | defined and implemented by the programmer. | ||
| 411 | |||
| 412 | @node First Steps with GNUnet | ||
| 413 | @chapter First Steps with GNUnet | ||
| 414 | |||
| 415 | @menu | ||
| 416 | * Configure your peer:: | ||
| 417 | * Start a peer:: | ||
| 418 | * Monitor a peer:: | ||
| 419 | * Starting Two Peers by Hand:: | ||
| 420 | * Starting Peers Using the Testbed Service:: | ||
| 421 | @end menu | ||
| 422 | |||
| 423 | @node Configure your peer | ||
| 424 | @section Configure your peer | ||
| 425 | |||
| 426 | First of all we need to configure your peer. Each peer is started with | ||
| 427 | a configuration containing settings for GNUnet itself and its services. | ||
| 428 | This configuration is based on the default configuration shipped with | ||
| 429 | GNUnet and can be modified. The default configuration is located in the | ||
| 430 | @file{$PREFIX/share/gnunet/config.d} directory. When starting a peer, you | ||
| 431 | can specify a customized configuration using the the @command{-c} command | ||
| 432 | line switch when starting the ARM service and all other services. When | ||
| 433 | using a modified configuration the default values are loaded and only | ||
| 434 | values specified in the configuration file will replace the default | ||
| 435 | values. | ||
| 436 | |||
| 437 | Since we want to start additional peers later, we need some modifications | ||
| 438 | from the default configuration. We need to create a separate service | ||
| 439 | home and a file containing our modifications for this peer: | ||
| 440 | |||
| 441 | @example | ||
| 442 | $ mkdir ~/gnunet1/ | ||
| 443 | $ touch peer1.conf | ||
| 444 | @end example | ||
| 445 | |||
| 446 | @noindent | ||
| 447 | Now add the following lines to @file{peer1.conf} to use this directory. | ||
| 448 | For simplified usage we want to prevent the peer to connect to the GNUnet | ||
| 449 | network since this could lead to confusing output. This modifications | ||
| 450 | will replace the default settings: | ||
| 451 | |||
| 452 | @example | ||
| 453 | [PATHS] | ||
| 454 | # Use this directory to store GNUnet data | ||
| 455 | GNUNET_HOME = ~/gnunet1/ | ||
| 456 | [hostlist] | ||
| 457 | # prevent bootstrapping | ||
| 458 | SERVERS = | ||
| 459 | @end example | ||
| 460 | |||
| 461 | @node Start a peer | ||
| 462 | @section Start a peer | ||
| 463 | Each GNUnet instance (called peer) has an identity (peer ID) based on a | ||
| 464 | cryptographic public private key pair. The peer ID is the printable hash | ||
| 465 | of the public key. | ||
| 466 | |||
| 467 | GNUnet services are controlled by a master service, the so called | ||
| 468 | @dfn{Automatic Restart Manager} (ARM). ARM starts, stops and even | ||
| 469 | restarts services automatically or on demand when a client connects. | ||
| 470 | You interact with the ARM service using the @command{gnunet-arm} tool. | ||
| 471 | GNUnet can then be started with @command{gnunet-arm -s} and stopped with | ||
| 472 | @command{gnunet-arm -e}. An additional service not automatically started | ||
| 473 | can be started using @command{gnunet-arm -i <service name>} and stopped | ||
| 474 | using @command{gnunet-arm -k <servicename>}. | ||
| 475 | |||
| 476 | Once you have started your peer, you can use many other GNUnet commands | ||
| 477 | to interact with it. For example, you can run: | ||
| 478 | |||
| 479 | @example | ||
| 480 | $ gnunet-peerinfo -s | ||
| 481 | @end example | ||
| 482 | |||
| 483 | @noindent | ||
| 484 | to obtain the public key of your peer. | ||
| 485 | |||
| 486 | You should see an output containing the peer ID similar to: | ||
| 487 | |||
| 488 | @example | ||
| 489 | I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'. | ||
| 490 | @end example | ||
| 491 | |||
| 492 | @node Monitor a peer | ||
| 493 | @section Monitor a peer | ||
| 494 | |||
| 495 | In this section, we will monitor the behaviour of our peer's DHT | ||
| 496 | service with respect to a specific key. First we will start | ||
| 497 | GNUnet and then start the DHT service and use the DHT monitor tool | ||
| 498 | to monitor the PUT and GET commands we issue ussing the | ||
| 499 | @command{gnunet-dht-put} and @command{gnunet-dht-get} commands. | ||
| 500 | Using the ``monitor'' line given below, you can observe the behavior | ||
| 501 | of your own peer's DHT with respect to the specified KEY: | ||
| 502 | |||
| 503 | @example | ||
| 504 | # start gnunet with all default services: | ||
| 505 | $ gnunet-arm -c ~/peer1.conf -s | ||
| 506 | # start DHT service: | ||
| 507 | $ gnunet-arm -c ~/peer1.conf -i dht | ||
| 508 | $ cd ~/gnunet/src/dht; | ||
| 509 | $ ./gnunet-dht-monitor -c ~/peer1.conf -k KEY | ||
| 510 | @end example | ||
| 511 | |||
| 512 | @noindent | ||
| 513 | Now open a separate terminal and change again to | ||
| 514 | the @file{gnunet/src/dht} directory: | ||
| 515 | |||
| 516 | @example | ||
| 517 | $ cd ~/gnunet/src/dht | ||
| 518 | # put VALUE under KEY in the DHT: | ||
| 519 | $ ./gnunet-dht-put -c ~/peer1.conf -k KEY -d VALUE | ||
| 520 | # get key KEY from the DHT: | ||
| 521 | $ ./gnunet/src/dht/gnunet-dht-get -c ~/peer1.conf -k KEY | ||
| 522 | # print statistics about current GNUnet state: | ||
| 523 | $ gnunet-statistics -c ~/peer1.conf | ||
| 524 | # print statistics about DHT service: | ||
| 525 | $ gnunet-statistics -c ~/peer1.conf -s dht | ||
| 526 | @end example | ||
| 527 | |||
| 528 | @node Starting Two Peers by Hand | ||
| 529 | @section Starting Two Peers by Hand | ||
| 530 | |||
| 531 | This section describes how to start two peers on the same machine by hand. | ||
| 532 | The process is rather painful, but the description is somewhat | ||
| 533 | instructive. In practice, you might prefer the automated method | ||
| 534 | (@pxref{Starting Peers Using the Testbed Service}). | ||
| 535 | |||
| 536 | @menu | ||
| 537 | * Setup a second peer:: | ||
| 538 | * Start the second peer and connect the peers:: | ||
| 539 | * How to connect manually:: | ||
| 540 | @end menu | ||
| 541 | |||
| 542 | @node Setup a second peer | ||
| 543 | @subsection Setup a second peer | ||
| 544 | We will now start a second peer on your machine. | ||
| 545 | For the second peer, you will need to manually create a modified | ||
| 546 | configuration file to avoid conflicts with ports and directories. | ||
| 547 | A peers configuration file is by default located | ||
| 548 | in @file{~/.gnunet/gnunet.conf}. This file is typically very short | ||
| 549 | or even empty as only the differences to the defaults need to be | ||
| 550 | specified. The defaults are located in many files in the | ||
| 551 | @file{$PREFIX/share/gnunet/config.d} directory. | ||
| 552 | |||
| 553 | To configure the second peer, use the files | ||
| 554 | @file{$PREFIX/share/gnunet/config.d} as a template for your main | ||
| 555 | configuration file: | ||
| 556 | |||
| 557 | @example | ||
| 558 | $ cat $PREFIX/share/gnunet/config.d/*.conf > peer2.conf | ||
| 559 | @end example | ||
| 560 | |||
| 561 | @noindent | ||
| 562 | Now you have to edit @file{peer2.conf} and change: | ||
| 563 | |||
| 564 | @itemize | ||
| 565 | @item @code{GNUNET\_TEST\_HOME} under @code{PATHS} | ||
| 566 | @item Every (uncommented) value for ``@code{PORT}'' (add 10000) in any | ||
| 567 | section (the option may be commented out if @code{PORT} is | ||
| 568 | prefixed by "\#", in this case, UNIX domain sockets are used | ||
| 569 | and the PORT option does not need to be touched) | ||
| 570 | @item Every value for ``@code{UNIXPATH}'' in any section | ||
| 571 | (e.g. by adding a "-p2" suffix) | ||
| 572 | @end itemize | ||
| 573 | |||
| 574 | to a fresh, unique value. Make sure that the PORT numbers stay | ||
| 575 | below 65536. From now on, whenever you interact with the second peer, | ||
| 576 | you need to specify @command{-c peer2.conf} as an additional | ||
| 577 | command line argument. | ||
| 578 | |||
| 579 | Now, generate the 2nd peer's private key: | ||
| 580 | |||
| 581 | @example | ||
| 582 | $ gnunet-peerinfo -s -c peer2.conf | ||
| 583 | @end example | ||
| 584 | |||
| 585 | @noindent | ||
| 586 | This may take a while, generate entropy using your keyboard or mouse | ||
| 587 | as needed. Also, make sure the output is different from the | ||
| 588 | gnunet-peerinfo output for the first peer (otherwise you made an | ||
| 589 | error in the configuration). | ||
| 590 | |||
| 591 | @node Start the second peer and connect the peers | ||
| 592 | @subsection Start the second peer and connect the peers | ||
| 593 | |||
| 594 | Then, you can start a second peer using: | ||
| 595 | |||
| 596 | @example | ||
| 597 | $ gnunet-arm -c peer2.conf -s | ||
| 598 | $ gnunet-arm -c peer2.conf -i dht | ||
| 599 | $ ~/gnunet/src/dht/gnunet-dht-put -c peer2.conf -k KEY -d VALUE | ||
| 600 | $ ~/gnunet/src/dht/gnunet-dht-get -c peer2.conf -k KEY | ||
| 601 | @end example | ||
| 602 | |||
| 603 | If you want the two peers to connect, you have multiple options: | ||
| 604 | |||
| 605 | @itemize | ||
| 606 | @item UDP neighbour discovery (automatic) | ||
| 607 | @item Setup a bootstrap server | ||
| 608 | @item Connect manually | ||
| 609 | @end itemize | ||
| 610 | |||
| 611 | To setup peer 1 as bootstrapping server change the configuration of | ||
| 612 | the first one to be a hostlist server by adding the following lines to | ||
| 613 | @file{peer1.conf} to enable bootstrapping server: | ||
| 614 | |||
| 615 | @example | ||
| 616 | [hostlist] | ||
| 617 | OPTIONS = -p | ||
| 618 | @end example | ||
| 619 | |||
| 620 | @noindent | ||
| 621 | Then change @file{peer2.conf} and replace the ``@code{SERVERS}'' | ||
| 622 | line in the ``@code{[hostlist]}'' section with | ||
| 623 | ``@code{http://localhost:8080/}''. Restart both peers using: | ||
| 624 | |||
| 625 | @example | ||
| 626 | # stop first peer | ||
| 627 | $ gnunet-arm -c peer1.conf -e | ||
| 628 | # start first peer | ||
| 629 | $ gnunet-arm -c peer1.conf -s | ||
| 630 | # start second peer | ||
| 631 | $ gnunet-arm -c peer2.conf -s | ||
| 632 | @end example | ||
| 633 | |||
| 634 | @noindent | ||
| 635 | Note that if you start your peers without changing these settings, they | ||
| 636 | will use the ``global'' hostlist servers of the GNUnet P2P network and | ||
| 637 | likely connect to those peers. At that point, debugging might become | ||
| 638 | tricky as you're going to be connected to many more peers and would | ||
| 639 | likely observe traffic and behaviors that are not explicitly controlled | ||
| 640 | by you. | ||
| 641 | |||
| 642 | @node How to connect manually | ||
| 643 | @subsection How to connect manually | ||
| 644 | |||
| 645 | If you want to use the @code{peerinfo} tool to connect your | ||
| 646 | peers, you should: | ||
| 647 | |||
| 648 | @itemize | ||
| 649 | @item Set @code{IMMEDIATE_START = NO} in section @code{hostlist} | ||
| 650 | (to not connect to the global GNUnet) | ||
| 651 | @item Start both peers running @command{gnunet-arm -c peer1.conf -s} | ||
| 652 | and @command{gnunet-arm -c peer2.conf -s} | ||
| 653 | @item Get @code{HELLO} message of the first peer running | ||
| 654 | @command{gnunet-peerinfo -c peer1.conf -g} | ||
| 655 | @item Give the output to the second peer by running | ||
| 656 | @command{gnunet-peerinfo -c peer2.conf -p '<output>'} | ||
| 657 | @end itemize | ||
| 658 | |||
| 659 | Check that they are connected using @command{gnunet-core -c peer1.conf}, | ||
| 660 | which should give you the other peer's peer identity: | ||
| 661 | |||
| 662 | @example | ||
| 663 | $ gnunet-core -c peer1.conf | ||
| 664 | Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG' | ||
| 665 | @end example | ||
| 666 | |||
| 667 | @node Starting Peers Using the Testbed Service | ||
| 668 | @section Starting Peers Using the Testbed Service | ||
| 669 | @c \label{sec:testbed} | ||
| 670 | |||
| 671 | GNUnet's testbed service is used for testing scenarios where | ||
| 672 | a number of peers are to be started. The testbed can manage peers | ||
| 673 | on a single host or on multiple hosts in a distributed fashion. | ||
| 674 | On a single affordable computer, it should be possible to run | ||
| 675 | around tens of peers without drastically increasing the load on the | ||
| 676 | system. | ||
| 677 | |||
| 678 | The testbed service can be access through its API | ||
| 679 | @file{include/gnunet\_testbed\_service.h}. The API provides many | ||
| 680 | routines for managing a group of peers. It also provides a helper | ||
| 681 | function @code{GNUNET\_TESTBED\_test\_run()} to quickly setup a | ||
| 682 | minimalistic testing environment on a single host. | ||
| 683 | |||
| 684 | This function takes a configuration file which will be used as a | ||
| 685 | template configuration for the peers. The testbed takes care of | ||
| 686 | modifying relevant options in the peers' configuration such as | ||
| 687 | @code{SERVICEHOME}, @code{PORT}, @code{UNIXPATH} to unique values | ||
| 688 | so that peers run without running into conflicts. It also checks | ||
| 689 | and assigns the ports in configurations only if they are free. | ||
| 690 | |||
| 691 | Additionally, the testbed service also reads its options from the | ||
| 692 | same configuration file. Various available options and details | ||
| 693 | about them can be found in the testbed default configuration file | ||
| 694 | @file{src/testbed/testbed.conf}. | ||
| 695 | |||
| 696 | With the testbed API, a sample test case can be structured as follows: | ||
| 697 | |||
| 698 | @example | ||
| 699 | @verbatiminclude testbed_test.c | ||
| 700 | @end example | ||
| 701 | |||
| 702 | @noindent | ||
| 703 | The source code for the above listing can be found at | ||
| 704 | @uref{https://gnunet.org/git/gnunet.git/tree/doc/ | ||
| 705 | documentation/testbed_test.c} | ||
| 706 | or in the @file{doc/documentation/} folder of your repository check-out. | ||
| 707 | After installing GNUnet, the above source code can be compiled as: | ||
| 708 | |||
| 709 | @example | ||
| 710 | $ export CPPFLAGS="-I/path/to/gnunet/headers" | ||
| 711 | $ export LDFLAGS="-L/path/to/gnunet/libraries" | ||
| 712 | $ gcc $CPPFLAGS $LDFLAGS -o testbed-test testbed_test.c \ | ||
| 713 | -lgnunettestbed -lgnunetdht -lgnunetutil | ||
| 714 | # Generate (empty) configuration | ||
| 715 | $ touch template.conf | ||
| 716 | # run it (press CTRL-C to stop) | ||
| 717 | $ ./testbed-test | ||
| 718 | @end example | ||
| 719 | |||
| 720 | @noindent | ||
| 721 | The @code{CPPFLAGS} and @code{LDFLAGS} are necessary if GNUnet | ||
| 722 | is installed into a different directory other than @file{/usr/local}. | ||
| 723 | |||
| 724 | All of testbed API's peer management functions treat management | ||
| 725 | actions as operations and return operation handles. It is expected | ||
| 726 | that the operations begin immediately, but they may get delayed (to | ||
| 727 | balance out load on the system). The program using the API then has | ||
| 728 | to take care of marking the operation as ``done'' so that its | ||
| 729 | associated resources can be freed immediately and other waiting | ||
| 730 | operations can be executed. Operations will be canceled if they are | ||
| 731 | marked as ``done'' before their completion. | ||
| 732 | |||
| 733 | An operation is treated as completed when it succeeds or fails. | ||
| 734 | Completion of an operation is either conveyed as events through | ||
| 735 | @dfn{controller event callback} or through respective | ||
| 736 | @dfn{operation completion callbacks}. | ||
| 737 | In functions which support completion notification | ||
| 738 | through both controller event callback and operation | ||
| 739 | completion callback, first the controller event callback will be | ||
| 740 | called. If the operation is not marked as done in that callback | ||
| 741 | or if the callback is given as NULL when creating the operation, | ||
| 742 | the operation completion callback will be called. The API | ||
| 743 | documentation shows which event are to be expected in the | ||
| 744 | controller event notifications. It also documents any exceptional | ||
| 745 | behaviour. | ||
| 746 | |||
| 747 | Once the peers are started, test cases often need to connect | ||
| 748 | some of the peers' services. Normally, opening a connect to | ||
| 749 | a peer's service requires the peer's configuration. While using | ||
| 750 | testbed, the testbed automatically generates per-peer configuration. | ||
| 751 | Accessing those configurations directly through file system is | ||
| 752 | discouraged as their locations are dynamically created and will be | ||
| 753 | different among various runs of testbed. To make access to these | ||
| 754 | configurations easy, testbed API provides the function | ||
| 755 | @code{GNUNET\_TESTBED\_service\_connect()}. This function fetches | ||
| 756 | the configuration of a given peer and calls the @dfn{Connect Adapter}. | ||
| 757 | In the example code, it is the @code{dht\_ca}. A connect adapter is | ||
| 758 | expected to open the connection to the needed service by using the | ||
| 759 | provided configuration and return the created service connection handle. | ||
| 760 | Successful connection to the needed service is signaled through | ||
| 761 | @code{service\_connect\_comp\_cb}. | ||
| 762 | |||
| 763 | A dual to connect adapter is the @dfn{Disconnect Adapter}. This callback | ||
| 764 | is called after the connect adapter has been called when the operation | ||
| 765 | from @code{GNUNET\_TESTBED\_service\_connect()} is marked as ``done''. | ||
| 766 | It has to disconnect from the service with the provided service | ||
| 767 | handle (@code{op\_result}). | ||
| 768 | |||
| 769 | Exercise: Find out how many peers you can run on your system. | ||
| 770 | |||
| 771 | Exercise: Find out how to create a 2D torus topology by changing the | ||
| 772 | options in the configuration file. | ||
| 773 | @xref{Supported Topologies, The GNUnet Reference Documentation ,, gnunet, The GNUnet Reference Documentation}, | ||
| 774 | then use the DHT API to store and retrieve values in the network. | ||
| 775 | |||
| 776 | @node Developing Applications | ||
| 777 | @chapter Developing Applications | ||
| 778 | |||
| 779 | @menu | ||
| 780 | * gnunet-ext:: | ||
| 781 | * Adapting the Template:: | ||
| 782 | * Writing a Client Application:: | ||
| 783 | * Writing a Service:: | ||
| 784 | * Interacting directly with other Peers using the CORE Service:: | ||
| 785 | * Storing peer-specific data using the PEERSTORE service:: | ||
| 786 | * Using the DHT:: | ||
| 787 | * Debugging with gnunet-arm:: | ||
| 788 | @end menu | ||
| 789 | |||
| 790 | @node gnunet-ext | ||
| 791 | @section gnunet-ext | ||
| 792 | To develop a new peer-to-peer application or to extend GNUnet we provide | ||
| 793 | a template build system for writing GNUnet extensions in C. It can be | ||
| 794 | obtained as follows: | ||
| 795 | |||
| 796 | @example | ||
| 797 | $ git clone https://gnunet.org/git/gnunet-ext | ||
| 798 | $ cd gnunet-ext/ | ||
| 799 | $ ./bootstrap | ||
| 800 | $ ./configure --prefix=$PREFIX --with-gnunet=$PREFIX | ||
| 801 | $ make | ||
| 802 | $ make install | ||
| 803 | $ make check | ||
| 804 | @end example | ||
| 805 | |||
| 806 | @noindent | ||
| 807 | The GNUnet ext template includes examples and a working buildsystem | ||
| 808 | for a new GNUnet service. A common GNUnet service consists of the | ||
| 809 | following parts which will be discussed in detail in the remainder | ||
| 810 | of this document. The functionality of a GNUnet service is implemented in: | ||
| 811 | |||
| 812 | @itemize | ||
| 813 | @item the GNUnet service (gnunet-ext/src/ext/gnunet-service-ext.c) | ||
| 814 | @item the client API (gnunet-ext/src/ext/ext_api.c) | ||
| 815 | @item the client application using the service API | ||
| 816 | (gnunet-ext/src/ext/gnunet-ext.c) | ||
| 817 | @end itemize | ||
| 818 | |||
| 819 | The interfaces for these entities are defined in: | ||
| 820 | |||
| 821 | @itemize | ||
| 822 | @item client API interface (gnunet-ext/src/ext/ext.h) | ||
| 823 | @item the service interface (gnunet-ext/src/include/gnunet_service_SERVICE.h) | ||
| 824 | @item the P2P protocol (gnunet-ext/src/include/gnunet_protocols_ext.h) | ||
| 825 | @end itemize | ||
| 826 | |||
| 827 | |||
| 828 | In addition the ext systems provides: | ||
| 829 | |||
| 830 | @itemize | ||
| 831 | @item a test testing the API (gnunet-ext/src/ext/test_ext_api.c) | ||
| 832 | @item a configuration template for the service | ||
| 833 | (gnunet-ext/src/ext/ext.conf.in) | ||
| 834 | @end itemize | ||
| 835 | |||
| 836 | @node Adapting the Template | ||
| 837 | @section Adapting the Template | ||
| 838 | |||
| 839 | The first step for writing any extension with a new service is to | ||
| 840 | ensure that the @file{ext.conf.in} file contains entries for the | ||
| 841 | @code{UNIXPATH}, @code{PORT} and @code{BINARY} for the service in a | ||
| 842 | section named after the service. | ||
| 843 | |||
| 844 | If you want to adapt the template rename the @file{ext.conf.in} to | ||
| 845 | match your services name, you have to modify the @code{AC\_OUTPUT} | ||
| 846 | section in @file{configure.ac} in the @file{gnunet-ext} root. | ||
| 847 | |||
| 848 | @node Writing a Client Application | ||
| 849 | @section Writing a Client Application | ||
| 850 | |||
| 851 | When writing any client application (for example, a command-line | ||
| 852 | tool), the basic structure is to start with the | ||
| 853 | @code{GNUNET\_PROGRAM\_run} function. This function will parse | ||
| 854 | command-line options, setup the scheduler and then invoke the | ||
| 855 | @code{run} function (with the remaining non-option arguments) | ||
| 856 | and a handle to the parsed configuration (and the configuration | ||
| 857 | file name that was used, which is typically not needed): | ||
| 858 | |||
| 859 | @example | ||
| 860 | @verbatiminclude tutorial-examples/001.c | ||
| 861 | @end example | ||
| 862 | |||
| 863 | @menu | ||
| 864 | * Handling command-line options:: | ||
| 865 | * Writing a Client Library:: | ||
| 866 | * Writing a user interface:: | ||
| 867 | @end menu | ||
| 868 | |||
| 869 | @node Handling command-line options | ||
| 870 | @subsection Handling command-line options | ||
| 871 | |||
| 872 | Options can then be added easily by adding global variables and | ||
| 873 | expanding the @code{options} array. For example, the following would | ||
| 874 | add a string-option and a binary flag (defaulting to @code{NULL} and | ||
| 875 | @code{GNUNET\_NO} respectively): | ||
| 876 | |||
| 877 | @example | ||
| 878 | @verbatiminclude tutorial-examples/002.c | ||
| 879 | @end example | ||
| 880 | |||
| 881 | Issues such as displaying some helpful text describing options using | ||
| 882 | the @code{--help} argument and error handling are taken care of when | ||
| 883 | using this approach. Other @code{GNUNET\_GETOPT\_}-functions can be used | ||
| 884 | to obtain integer value options, increment counters, etc. You can | ||
| 885 | even write custom option parsers for special circumstances not covered | ||
| 886 | by the available handlers. To check if an argument was specified by the | ||
| 887 | user you initialize the variable with a specific value (e.g. NULL for | ||
| 888 | a string and GNUNET\_SYSERR for a integer) and check after parsing | ||
| 889 | happened if the values were modified. | ||
| 890 | |||
| 891 | Inside the @code{run} method, the program would perform the | ||
| 892 | application-specific logic, which typically involves initializing and | ||
| 893 | using some client library to interact with the service. The client | ||
| 894 | library is supposed to implement the IPC whereas the service provides | ||
| 895 | more persistent P2P functions. | ||
| 896 | |||
| 897 | Exercise: Add a few command-line options and print them inside | ||
| 898 | of @code{run}. What happens if the user gives invalid arguments? | ||
| 899 | |||
| 900 | @node Writing a Client Library | ||
| 901 | @subsection Writing a Client Library | ||
| 902 | |||
| 903 | The first and most important step in writing a client library is to | ||
| 904 | decide on an API for the library. Typical API calls include | ||
| 905 | connecting to the service, performing application-specific requests | ||
| 906 | and cleaning up. Many examples for such service APIs can be found | ||
| 907 | in the @file{gnunet/src/include/gnunet\_*\_service.h} files. | ||
| 908 | |||
| 909 | Then, a client-service protocol needs to be designed. This typically | ||
| 910 | involves defining various message formats in a header that will be | ||
| 911 | included by both the service and the client library (but is otherwise | ||
| 912 | not shared and hence located within the service's directory and not | ||
| 913 | installed by @command{make install}). Each message must start with a | ||
| 914 | @code{struct GNUNET\_MessageHeader} and must be shorter than 64k. By | ||
| 915 | convention, all fields in IPC (and P2P) messages must be in big-endian | ||
| 916 | format (and thus should be read using @code{ntohl} and similar | ||
| 917 | functions and written using @code{htonl} and similar functions). | ||
| 918 | Unique message types must be defined for each message struct in the | ||
| 919 | @file{gnunet\_protocols.h} header (or an extension-specific include | ||
| 920 | file). | ||
| 921 | |||
| 922 | @menu | ||
| 923 | * Connecting to the Service:: | ||
| 924 | * Sending messages:: | ||
| 925 | * Receiving Replies from the Service:: | ||
| 926 | @end menu | ||
| 927 | |||
| 928 | @node Connecting to the Service | ||
| 929 | @subsubsection Connecting to the Service | ||
| 930 | |||
| 931 | Before a client library can implement the application-specific protocol | ||
| 932 | with the service, a connection must be created: | ||
| 933 | |||
| 934 | @example | ||
| 935 | @verbatiminclude tutorial-examples/003.c | ||
| 936 | @end example | ||
| 937 | |||
| 938 | @noindent | ||
| 939 | As a result a @code{GNUNET\_MQ\_Handle} is returned | ||
| 940 | which can to used henceforth to transmit messages to the service. | ||
| 941 | The complete MQ API can be found in @file{gnunet\_mq\_lib.h}. | ||
| 942 | The @code{hanlders} array in the example above is incomplete. | ||
| 943 | Here is where you will define which messages you expect to | ||
| 944 | receive from the service, and which functions handle them. | ||
| 945 | The @code{error\_cb} is a function that is to be called whenever | ||
| 946 | there are errors communicating with the service. | ||
| 947 | |||
| 948 | @node Sending messages | ||
| 949 | @subsubsection Sending messages | ||
| 950 | |||
| 951 | In GNUnet, messages are always sent beginning with a | ||
| 952 | @code{struct GNUNET\_MessageHeader} in big endian format. | ||
| 953 | This header defines the size and the type of the | ||
| 954 | message, the payload follows after this header. | ||
| 955 | |||
| 956 | @example | ||
| 957 | @verbatiminclude tutorial-examples/004.c | ||
| 958 | @end example | ||
| 959 | |||
| 960 | @noindent | ||
| 961 | Existing message types are defined in @file{gnunet\_protocols.h}. | ||
| 962 | A common way to create a message is with an envelope: | ||
| 963 | |||
| 964 | @example | ||
| 965 | @verbatiminclude tutorial-examples/005.c | ||
| 966 | @end example | ||
| 967 | |||
| 968 | @noindent | ||
| 969 | Exercise: Define a message struct that includes a 32-bit | ||
| 970 | unsigned integer in addition to the standard GNUnet MessageHeader. | ||
| 971 | Add a C struct and define a fresh protocol number for your message. | ||
| 972 | Protocol numbers in gnunet-ext are defined | ||
| 973 | in @file{gnunet-ext/src/include/gnunet_protocols_ext.h} | ||
| 974 | |||
| 975 | Exercise: Find out how you can determine the number of messages | ||
| 976 | in a message queue. | ||
| 977 | |||
| 978 | Exercise: Find out how you can determine when a message you | ||
| 979 | have queued was actually transmitted. | ||
| 980 | |||
| 981 | Exercise: Define a helper function to transmit a 32-bit | ||
| 982 | unsigned integer (as payload) to a service using some given client | ||
| 983 | handle. | ||
| 984 | |||
| 985 | @node Receiving Replies from the Service | ||
| 986 | @subsubsection Receiving Replies from the Service | ||
| 987 | |||
| 988 | Clients can receive messages from the service using the handlers | ||
| 989 | specified in the @code{handlers} array we specified when connecting | ||
| 990 | to the service. Entries in the the array are usually created using | ||
| 991 | one of two macros, depending on whether the message is fixed size | ||
| 992 | or variable size. Variable size messages are managed using two | ||
| 993 | callbacks, one to check that the message is well-formed, the other | ||
| 994 | to actually process the message. Fixed size messages are fully | ||
| 995 | checked by the MQ-logic, and thus only need to provide the handler | ||
| 996 | to process the message. Note that the prefixes @code{check\_} | ||
| 997 | and @code{handle\_} are mandatory. | ||
| 998 | |||
| 999 | @example | ||
| 1000 | @verbatiminclude tutorial-examples/006.c | ||
| 1001 | @end example | ||
| 1002 | |||
| 1003 | @noindent | ||
| 1004 | Exercise: Expand your helper function to receive a response message | ||
| 1005 | (for example, containing just the @code{struct GNUnet MessageHeader} | ||
| 1006 | without any payload). Upon receiving the service's response, you | ||
| 1007 | should call a callback provided to your helper function's API. | ||
| 1008 | |||
| 1009 | Exercise: Figure out where you can pass values to the | ||
| 1010 | closures (@code{cls}). | ||
| 1011 | |||
| 1012 | @node Writing a user interface | ||
| 1013 | @subsection Writing a user interface | ||
| 1014 | |||
| 1015 | Given a client library, all it takes to access a service now is to | ||
| 1016 | combine calls to the client library with parsing command-line | ||
| 1017 | options. | ||
| 1018 | |||
| 1019 | Exercise: Call your client API from your @code{run()} method in your | ||
| 1020 | client application to send a request to the service. For example, | ||
| 1021 | send a 32-bit integer value based on a number given at the | ||
| 1022 | command-line to the service. | ||
| 1023 | |||
| 1024 | @node Writing a Service | ||
| 1025 | @section Writing a Service | ||
| 1026 | |||
| 1027 | Before you can test the client you've written so far, you'll | ||
| 1028 | need to also implement the corresponding service. | ||
| 1029 | |||
| 1030 | @menu | ||
| 1031 | * Code Placement:: | ||
| 1032 | * Starting a Service:: | ||
| 1033 | @end menu | ||
| 1034 | |||
| 1035 | @node Code Placement | ||
| 1036 | @subsection Code Placement | ||
| 1037 | |||
| 1038 | New services are placed in their own subdirectory under | ||
| 1039 | @file{gnunet/src}. This subdirectory should contain the API | ||
| 1040 | implementation file @file{SERVICE\_api.c}, the description of | ||
| 1041 | the client-service protocol @file{SERVICE.h} and P2P protocol | ||
| 1042 | @file{SERVICE\_protocol.h}, the implementation of the service itself | ||
| 1043 | @file{gnunet-service-SERVICE.h} and several files for tests, | ||
| 1044 | including test code and configuration files. | ||
| 1045 | |||
| 1046 | @node Starting a Service | ||
| 1047 | @subsection Starting a Service | ||
| 1048 | |||
| 1049 | The key API definition for creating a service is the | ||
| 1050 | @code{GNUNET\_SERVICE\_MAIN} macro: | ||
| 1051 | |||
| 1052 | @example | ||
| 1053 | @verbatiminclude tutorial-examples/007.c | ||
| 1054 | @end example | ||
| 1055 | |||
| 1056 | @noindent | ||
| 1057 | In addition to the service name and flags, the macro takes three | ||
| 1058 | functions, typically called @code{run}, @code{client\_connect\_cb} and | ||
| 1059 | @code{client\_disconnect\_cb} as well as an array of message handlers | ||
| 1060 | that will be called for incoming messages from clients. | ||
| 1061 | |||
| 1062 | A minimal version of the three central service funtions would look | ||
| 1063 | like this: | ||
| 1064 | |||
| 1065 | @example | ||
| 1066 | @verbatiminclude tutorial-examples/008.c | ||
| 1067 | @end example | ||
| 1068 | |||
| 1069 | @noindent | ||
| 1070 | Exercise: Write a stub service that processes no messages at all | ||
| 1071 | in your code. Create a default configuration for it, integrate it | ||
| 1072 | with the build system and start the service from | ||
| 1073 | @command{gnunet-service-arm} using @command{gnunet-arm -i NAME}. | ||
| 1074 | |||
| 1075 | Exercise: Figure out how to set the closure (@code{cls}) for handlers | ||
| 1076 | of a service. | ||
| 1077 | |||
| 1078 | Exercise: Figure out how to send messages from the service back to the | ||
| 1079 | client. | ||
| 1080 | |||
| 1081 | Each handler function in the service @b{must} eventually (possibly in some | ||
| 1082 | asynchronous continuation) call | ||
| 1083 | @code{GNUNET\_SERVICE\_client\_continue()}. Only after this call | ||
| 1084 | additional messages from the same client may | ||
| 1085 | be processed. This way, the service can throttle processing messages | ||
| 1086 | from the same client. | ||
| 1087 | |||
| 1088 | Exercise: Change the service to ``handle'' the message from your | ||
| 1089 | client (for now, by printing a message). What happens if you | ||
| 1090 | forget to call @code{GNUNET\_SERVICE\_client\_continue()}? | ||
| 1091 | |||
| 1092 | @node Interacting directly with other Peers using the CORE Service | ||
| 1093 | @section Interacting directly with other Peers using the CORE Service | ||
| 1094 | |||
| 1095 | FIXME: This section still needs to be updated to the lastest API! | ||
| 1096 | |||
| 1097 | One of the most important services in GNUnet is the @code{CORE} service | ||
| 1098 | managing connections between peers and handling encryption between peers. | ||
| 1099 | |||
| 1100 | One of the first things any service that extends the P2P protocol | ||
| 1101 | typically does is connect to the @code{CORE} service using: | ||
| 1102 | |||
| 1103 | @example | ||
| 1104 | @verbatiminclude tutorial-examples/009.c | ||
| 1105 | @end example | ||
| 1106 | |||
| 1107 | @menu | ||
| 1108 | * New P2P connections:: | ||
| 1109 | * Receiving P2P Messages:: | ||
| 1110 | * Sending P2P Messages:: | ||
| 1111 | * End of P2P connections:: | ||
| 1112 | @end menu | ||
| 1113 | |||
| 1114 | @node New P2P connections | ||
| 1115 | @subsection New P2P connections | ||
| 1116 | |||
| 1117 | Before any traffic with a different peer can be exchanged, the peer must | ||
| 1118 | be known to the service. This is notified by the @code{CORE} | ||
| 1119 | @code{connects} callback, which communicates the identity of the new | ||
| 1120 | peer to the service: | ||
| 1121 | |||
| 1122 | @example | ||
| 1123 | @verbatiminclude tutorial-examples/010.c | ||
| 1124 | @end example | ||
| 1125 | |||
| 1126 | @noindent | ||
| 1127 | Note that whatever you return from @code{connects} is given as the | ||
| 1128 | @code{cls} argument to the message handlers for messages from | ||
| 1129 | the respective peer. | ||
| 1130 | |||
| 1131 | Exercise: Create a service that connects to the @code{CORE}. Then | ||
| 1132 | start (and connect) two peers and print a message once your connect | ||
| 1133 | callback is invoked. | ||
| 1134 | |||
| 1135 | @node Receiving P2P Messages | ||
| 1136 | @subsection Receiving P2P Messages | ||
| 1137 | |||
| 1138 | To receive messages from @code{CORE}, you pass the desired | ||
| 1139 | @code{handlers} to the @code{GNUNET\_CORE\_connect()} function, | ||
| 1140 | just as we showed for services. | ||
| 1141 | |||
| 1142 | It is your responsibility to process messages fast enough or | ||
| 1143 | to implement flow control. If an application does not process | ||
| 1144 | CORE messages fast enough, CORE will randomly drop messages | ||
| 1145 | to not keep a very long queue in memory. | ||
| 1146 | |||
| 1147 | Exercise: Start one peer with a new service that has a message | ||
| 1148 | handler and start a second peer that only has your ``old'' service | ||
| 1149 | without message handlers. Which ``connect'' handlers are invoked when | ||
| 1150 | the two peers are connected? Why? | ||
| 1151 | |||
| 1152 | @node Sending P2P Messages | ||
| 1153 | @subsection Sending P2P Messages | ||
| 1154 | |||
| 1155 | You can transmit messages to other peers using the @code{mq} you were | ||
| 1156 | given during the @code{connect} callback. Note that the @code{mq} | ||
| 1157 | automatically is released upon @code{disconnect} and that you must | ||
| 1158 | not use it afterwards. | ||
| 1159 | |||
| 1160 | It is your responsibility to not over-fill the message queue, GNUnet | ||
| 1161 | will send the messages roughly in the order given as soon as possible. | ||
| 1162 | |||
| 1163 | Exercise: Write a service that upon connect sends messages as | ||
| 1164 | fast as possible to the other peer (the other peer should run a | ||
| 1165 | service that ``processes'' those messages). How fast is the | ||
| 1166 | transmission? Count using the STATISTICS service on both ends. Are | ||
| 1167 | messages lost? How can you transmit messages faster? What happens if | ||
| 1168 | you stop the peer that is receiving your messages? | ||
| 1169 | |||
| 1170 | @node End of P2P connections | ||
| 1171 | @subsection End of P2P connections | ||
| 1172 | |||
| 1173 | If a message handler returns @code{GNUNET\_SYSERR}, the remote | ||
| 1174 | peer shuts down or there is an unrecoverable network | ||
| 1175 | disconnection, CORE notifies the service that the peer disconnected. | ||
| 1176 | After this notification no more messages will be received from the | ||
| 1177 | peer and the service is no longer allowed to send messages to the peer. | ||
| 1178 | The disconnect callback looks like the following: | ||
| 1179 | |||
| 1180 | @example | ||
| 1181 | @verbatiminclude tutorial-examples/011.c | ||
| 1182 | @end example | ||
| 1183 | |||
| 1184 | @noindent | ||
| 1185 | Exercise: Fix your service to handle peer disconnects. | ||
| 1186 | |||
| 1187 | @node Storing peer-specific data using the PEERSTORE service | ||
| 1188 | @section Storing peer-specific data using the PEERSTORE service | ||
| 1189 | |||
| 1190 | GNUnet's PEERSTORE service offers a persistorage for arbitrary | ||
| 1191 | peer-specific data. Other GNUnet services can use the PEERSTORE | ||
| 1192 | to store, retrieve and monitor data records. Each data record | ||
| 1193 | stored with PEERSTORE contains the following fields: | ||
| 1194 | |||
| 1195 | @itemize | ||
| 1196 | @item subsystem: Name of the subsystem responsible for the record. | ||
| 1197 | @item peerid: Identity of the peer this record is related to. | ||
| 1198 | @item key: a key string identifying the record. | ||
| 1199 | @item value: binary record value. | ||
| 1200 | @item expiry: record expiry date. | ||
| 1201 | @end itemize | ||
| 1202 | |||
| 1203 | The first step is to start a connection to the PEERSTORE service: | ||
| 1204 | @example | ||
| 1205 | @verbatiminclude tutorial-examples/012.c | ||
| 1206 | @end example | ||
| 1207 | |||
| 1208 | The service handle @code{peerstore_handle} will be needed for | ||
| 1209 | all subsequent PEERSTORE operations. | ||
| 1210 | |||
| 1211 | @menu | ||
| 1212 | * Storing records:: | ||
| 1213 | * Retrieving records:: | ||
| 1214 | * Monitoring records:: | ||
| 1215 | * Disconnecting from PEERSTORE:: | ||
| 1216 | @end menu | ||
| 1217 | |||
| 1218 | @node Storing records | ||
| 1219 | @subsection Storing records | ||
| 1220 | |||
| 1221 | To store a new record, use the following function: | ||
| 1222 | |||
| 1223 | @example | ||
| 1224 | @verbatiminclude tutorial-examples/013.c | ||
| 1225 | @end example | ||
| 1226 | |||
| 1227 | @noindent | ||
| 1228 | The @code{options} parameter can either be | ||
| 1229 | @code{GNUNET_PEERSTORE_STOREOPTION_MULTIPLE} which means that multiple | ||
| 1230 | values can be stored under the same key combination | ||
| 1231 | (subsystem, peerid, key), or @code{GNUNET_PEERSTORE_STOREOPTION_REPLACE} | ||
| 1232 | which means that PEERSTORE will replace any existing values under the | ||
| 1233 | given key combination (subsystem, peerid, key) with the new given value. | ||
| 1234 | |||
| 1235 | The continuation function @code{cont} will be called after the store | ||
| 1236 | request is successfully sent to the PEERSTORE service. This does not | ||
| 1237 | guarantee that the record is successfully stored, only that it was | ||
| 1238 | received by the service. | ||
| 1239 | |||
| 1240 | The @code{GNUNET_PEERSTORE_store} function returns a handle to the store | ||
| 1241 | operation. This handle can be used to cancel the store operation only | ||
| 1242 | before the continuation function is called: | ||
| 1243 | |||
| 1244 | @example | ||
| 1245 | @verbatiminclude tutorial-examples/013.1.c | ||
| 1246 | @end example | ||
| 1247 | |||
| 1248 | @node Retrieving records | ||
| 1249 | @subsection Retrieving records | ||
| 1250 | |||
| 1251 | To retrieve stored records, use the following function: | ||
| 1252 | |||
| 1253 | @example | ||
| 1254 | @verbatiminclude tutorial-examples/014.c | ||
| 1255 | @end example | ||
| 1256 | |||
| 1257 | @noindent | ||
| 1258 | The values of @code{peer} and @code{key} can be @code{NULL}. This | ||
| 1259 | allows the iteration over values stored under any of the following | ||
| 1260 | key combinations: | ||
| 1261 | |||
| 1262 | @itemize | ||
| 1263 | @item (subsystem) | ||
| 1264 | @item (subsystem, peerid) | ||
| 1265 | @item (subsystem, key) | ||
| 1266 | @item (subsystem, peerid, key) | ||
| 1267 | @end itemize | ||
| 1268 | |||
| 1269 | The @code{callback} function will be called once with each retrieved | ||
| 1270 | record and once more with a @code{NULL} record to signal the end of | ||
| 1271 | results. | ||
| 1272 | |||
| 1273 | The @code{GNUNET_PEERSTORE_iterate} function returns a handle to the | ||
| 1274 | iterate operation. This handle can be used to cancel the iterate | ||
| 1275 | operation only before the callback function is called with a | ||
| 1276 | @code{NULL} record. | ||
| 1277 | |||
| 1278 | @node Monitoring records | ||
| 1279 | @subsection Monitoring records | ||
| 1280 | |||
| 1281 | PEERSTORE offers the functionality of monitoring for new records | ||
| 1282 | stored under a specific key combination (subsystem, peerid, key). | ||
| 1283 | To start the monitoring, use the following function: | ||
| 1284 | |||
| 1285 | @example | ||
| 1286 | @verbatiminclude tutorial-examples/015.c | ||
| 1287 | @end example | ||
| 1288 | |||
| 1289 | @noindent | ||
| 1290 | Whenever a new record is stored under the given key combination, | ||
| 1291 | the @code{callback} function will be called with this new | ||
| 1292 | record. This will continue until the connection to the PEERSTORE | ||
| 1293 | service is broken or the watch operation is canceled: | ||
| 1294 | |||
| 1295 | @example | ||
| 1296 | @verbatiminclude tutorial-examples/016.c | ||
| 1297 | @end example | ||
| 1298 | |||
| 1299 | @node Disconnecting from PEERSTORE | ||
| 1300 | @subsection Disconnecting from PEERSTORE | ||
| 1301 | |||
| 1302 | When the connection to the PEERSTORE service is no longer needed, | ||
| 1303 | disconnect using the following function: | ||
| 1304 | |||
| 1305 | @example | ||
| 1306 | @verbatiminclude tutorial-examples/017.c | ||
| 1307 | @end example | ||
| 1308 | |||
| 1309 | @noindent | ||
| 1310 | If the @code{sync_first} flag is set to @code{GNUNET_YES}, | ||
| 1311 | the API will delay the disconnection until all store requests | ||
| 1312 | are received by the PEERSTORE service. Otherwise, it will | ||
| 1313 | disconnect immediately. | ||
| 1314 | |||
| 1315 | @node Using the DHT | ||
| 1316 | @section Using the DHT | ||
| 1317 | |||
| 1318 | The DHT allows to store data so other peers in the P2P network can | ||
| 1319 | access it and retrieve data stored by any peers in the network. | ||
| 1320 | This section will explain how to use the DHT. Of course, the first | ||
| 1321 | thing to do is to connect to the DHT service: | ||
| 1322 | |||
| 1323 | @example | ||
| 1324 | @verbatiminclude tutorial-examples/018.c | ||
| 1325 | @end example | ||
| 1326 | |||
| 1327 | @noindent | ||
| 1328 | The second parameter indicates how many requests in parallel to expect. | ||
| 1329 | It is not a hard limit, but a good approximation will make the DHT more | ||
| 1330 | efficient. | ||
| 1331 | |||
| 1332 | @menu | ||
| 1333 | * Storing data in the DHT:: | ||
| 1334 | * Obtaining data from the DHT:: | ||
| 1335 | * Implementing a block plugin:: | ||
| 1336 | * Monitoring the DHT:: | ||
| 1337 | @end menu | ||
| 1338 | |||
| 1339 | @node Storing data in the DHT | ||
| 1340 | @subsection Storing data in the DHT | ||
| 1341 | Since the DHT is a dynamic environment (peers join and leave frequently) | ||
| 1342 | the data that we put in the DHT does not stay there indefinitely. It is | ||
| 1343 | important to ``refresh'' the data periodically by simply storing it | ||
| 1344 | again, in order to make sure other peers can access it. | ||
| 1345 | |||
| 1346 | The put API call offers a callback to signal that the PUT request has been | ||
| 1347 | sent. This does not guarantee that the data is accessible to others peers, | ||
| 1348 | or even that is has been stored, only that the service has requested to | ||
| 1349 | a neighboring peer the retransmission of the PUT request towards its final | ||
| 1350 | destination. Currently there is no feedback about whether or not the data | ||
| 1351 | has been sucessfully stored or where it has been stored. In order to | ||
| 1352 | improve the availablilty of the data and to compensate for possible | ||
| 1353 | errors, peers leaving and other unfavorable events, just make several | ||
| 1354 | PUT requests! | ||
| 1355 | |||
| 1356 | @example | ||
| 1357 | @verbatiminclude tutorial-examples/019.c | ||
| 1358 | @end example | ||
| 1359 | |||
| 1360 | @noindent | ||
| 1361 | Exercise: Store a value in the DHT periodically to make sure it | ||
| 1362 | is available over time. You might consider using the function | ||
| 1363 | @code{GNUNET\_SCHEDULER\_add\_delayed} and call | ||
| 1364 | @code{GNUNET\_DHT\_put} from inside a helper function. | ||
| 1365 | |||
| 1366 | @node Obtaining data from the DHT | ||
| 1367 | @subsection Obtaining data from the DHT | ||
| 1368 | |||
| 1369 | As we saw in the previous example, the DHT works in an asynchronous mode. | ||
| 1370 | Each request to the DHT is executed ``in the background'' and the API | ||
| 1371 | calls return immediately. In order to receive results from the DHT, the | ||
| 1372 | API provides a callback. Once started, the request runs in the service, | ||
| 1373 | the service will try to get as many results as possible (filtering out | ||
| 1374 | duplicates) until the timeout expires or we explicitly stop the request. | ||
| 1375 | It is possible to give a ``forever'' timeout with | ||
| 1376 | @code{GNUNET\_TIME\_UNIT\_FOREVER\_REL}. | ||
| 1377 | |||
| 1378 | If we give a route option @code{GNUNET\_DHT\_RO\_RECORD\_ROUTE} | ||
| 1379 | the callback will get a list of all the peers the data has travelled, | ||
| 1380 | both on the PUT path and on the GET path. | ||
| 1381 | |||
| 1382 | @example | ||
| 1383 | @verbatiminclude tutorial-examples/020.c | ||
| 1384 | @end example | ||
| 1385 | |||
| 1386 | @noindent | ||
| 1387 | Exercise: Store a value in the DHT and after a while retrieve it. | ||
| 1388 | Show the IDs of all the peers the requests have gone through. | ||
| 1389 | In order to convert a peer ID to a string, use the function | ||
| 1390 | @code{GNUNET\_i2s}. Pay attention to the route option parameters | ||
| 1391 | in both calls! | ||
| 1392 | |||
| 1393 | @node Implementing a block plugin | ||
| 1394 | @subsection Implementing a block plugin | ||
| 1395 | |||
| 1396 | In order to store data in the DHT, it is necessary to provide a block | ||
| 1397 | plugin. The DHT uses the block plugin to ensure that only well-formed | ||
| 1398 | requests and replies are transmitted over the network. | ||
| 1399 | |||
| 1400 | The block plugin should be put in a file @file{plugin\_block\_SERVICE.c} | ||
| 1401 | in the service's respective directory. The | ||
| 1402 | mandatory functions that need to be implemented for a block plugin are | ||
| 1403 | described in the following sections. | ||
| 1404 | |||
| 1405 | @menu | ||
| 1406 | * Validating requests and replies:: | ||
| 1407 | * Deriving a key from a reply:: | ||
| 1408 | * Initialization of the plugin:: | ||
| 1409 | * Shutdown of the plugin:: | ||
| 1410 | * Integration of the plugin with the build system:: | ||
| 1411 | @end menu | ||
| 1412 | |||
| 1413 | @node Validating requests and replies | ||
| 1414 | @subsubsection Validating requests and replies | ||
| 1415 | |||
| 1416 | The evaluate function should validate a reply or a request. It returns | ||
| 1417 | a @code{GNUNET\_BLOCK\_EvaluationResult}, which is an enumeration. All | ||
| 1418 | possible answers are in @file{gnunet\_block\_lib.h}. The function will | ||
| 1419 | be called with a @code{reply\_block} argument of @code{NULL} for | ||
| 1420 | requests. Note that depending on how @code{evaluate} is called, only | ||
| 1421 | some of the possible return values are valid. The specific meaning of | ||
| 1422 | the @code{xquery} argument is application-specific. Applications that | ||
| 1423 | do not use an extended query should check that the @code{xquery\_size} | ||
| 1424 | is zero. The block group is typically used to filter duplicate | ||
| 1425 | replies. | ||
| 1426 | |||
| 1427 | @example | ||
| 1428 | @verbatiminclude tutorial-examples/021.c | ||
| 1429 | @end example | ||
| 1430 | |||
| 1431 | @noindent | ||
| 1432 | Note that it is mandatory to detect duplicate replies in this function | ||
| 1433 | and return the respective status code. Duplicate detection is | ||
| 1434 | typically done using the Bloom filter block group provided by | ||
| 1435 | @file{libgnunetblockgroup.so}. Failure to do so may cause replies to | ||
| 1436 | circle in the network. | ||
| 1437 | |||
| 1438 | @node Deriving a key from a reply | ||
| 1439 | @subsubsection Deriving a key from a reply | ||
| 1440 | |||
| 1441 | The DHT can operate more efficiently if it is possible to derive a key | ||
| 1442 | from the value of the corresponding block. The @code{get\_key} | ||
| 1443 | function is used to obtain the key of a block --- for example, by | ||
| 1444 | means of hashing. If deriving the key is not possible, the function | ||
| 1445 | should simply return @code{GNUNET\_SYSERR} (the DHT will still work | ||
| 1446 | just fine with such blocks). | ||
| 1447 | |||
| 1448 | @example | ||
| 1449 | @verbatiminclude tutorial-examples/022.c | ||
| 1450 | @end example | ||
| 1451 | |||
| 1452 | @node Initialization of the plugin | ||
| 1453 | @subsubsection Initialization of the plugin | ||
| 1454 | |||
| 1455 | The plugin is realized as a shared C library. The library must export | ||
| 1456 | an initialization function which should initialize the plugin. The | ||
| 1457 | initialization function specifies what block types the plugin cares | ||
| 1458 | about and returns a struct with the functions that are to be used for | ||
| 1459 | validation and obtaining keys (the ones just defined above). | ||
| 1460 | |||
| 1461 | @example | ||
| 1462 | @verbatiminclude tutorial-examples/023.c | ||
| 1463 | @end example | ||
| 1464 | |||
| 1465 | @node Shutdown of the plugin | ||
| 1466 | @subsubsection Shutdown of the plugin | ||
| 1467 | |||
| 1468 | Following GNUnet's general plugin API concept, the plugin must | ||
| 1469 | export a second function for cleaning up. It usually does very | ||
| 1470 | little. | ||
| 1471 | |||
| 1472 | @example | ||
| 1473 | @verbatiminclude tutorial-examples/024.c | ||
| 1474 | @end example | ||
| 1475 | |||
| 1476 | @node Integration of the plugin with the build system | ||
| 1477 | @subsubsection Integration of the plugin with the build system | ||
| 1478 | |||
| 1479 | In order to compile the plugin, the @file{Makefile.am} file for the | ||
| 1480 | service SERVICE should contain a rule similar to this: | ||
| 1481 | @c Actually this is a Makefile not C. But the whole structure of examples | ||
| 1482 | @c must be improved. | ||
| 1483 | |||
| 1484 | @example | ||
| 1485 | @verbatiminclude tutorial-examples/025.Makefile.am | ||
| 1486 | @end example | ||
| 1487 | |||
| 1488 | @noindent | ||
| 1489 | Exercise: Write a block plugin that accepts all queries | ||
| 1490 | and all replies but prints information about queries and replies | ||
| 1491 | when the respective validation hooks are called. | ||
| 1492 | |||
| 1493 | @node Monitoring the DHT | ||
| 1494 | @subsection Monitoring the DHT | ||
| 1495 | |||
| 1496 | It is possible to monitor the functioning of the local | ||
| 1497 | DHT service. When monitoring the DHT, the service will | ||
| 1498 | alert the monitoring program of any events, both started | ||
| 1499 | locally or received for routing from another peer. | ||
| 1500 | The are three different types of events possible: a | ||
| 1501 | GET request, a PUT request or a response (a reply to a GET). | ||
| 1502 | |||
| 1503 | Since the different events have different associated data, | ||
| 1504 | the API gets 3 different callbacks (one for each message type) | ||
| 1505 | and optional type and key parameters, to allow for filtering of | ||
| 1506 | messages. When an event happens, the appropiate callback is | ||
| 1507 | called with all the information about the event. | ||
| 1508 | |||
| 1509 | @example | ||
| 1510 | @verbatiminclude tutorial-examples/026.c | ||
| 1511 | @end example | ||
| 1512 | |||
| 1513 | @node Debugging with gnunet-arm | ||
| 1514 | @section Debugging with gnunet-arm | ||
| 1515 | |||
| 1516 | Even if services are managed by @command{gnunet-arm}, you can | ||
| 1517 | start them with @command{gdb} or @command{valgrind}. For | ||
| 1518 | example, you could add the following lines to your | ||
| 1519 | configuration file to start the DHT service in a @command{gdb} | ||
| 1520 | session in a fresh @command{xterm}: | ||
| 1521 | |||
| 1522 | @example | ||
| 1523 | [dht] | ||
| 1524 | PREFIX=xterm -e gdb --args | ||
| 1525 | @end example | ||
| 1526 | |||
| 1527 | @noindent | ||
| 1528 | Alternatively, you can stop a service that was started via | ||
| 1529 | ARM and run it manually: | ||
| 1530 | |||
| 1531 | @example | ||
| 1532 | $ gnunet-arm -k dht | ||
| 1533 | $ gdb --args gnunet-service-dht -L DEBUG | ||
| 1534 | $ valgrind gnunet-service-dht -L DEBUG | ||
| 1535 | @end example | ||
| 1536 | |||
| 1537 | @noindent | ||
| 1538 | Assuming other services are well-written, they will automatically | ||
| 1539 | re-integrate the restarted service with the peer. | ||
| 1540 | |||
| 1541 | GNUnet provides a powerful logging mechanism providing log | ||
| 1542 | levels @code{ERROR}, @code{WARNING}, @code{INFO} and @code{DEBUG}. | ||
| 1543 | The current log level is configured using the @code{$GNUNET_FORCE_LOG} | ||
| 1544 | environmental variable. The @code{DEBUG} level is only available if | ||
| 1545 | @command{--enable-logging=verbose} was used when running | ||
| 1546 | @command{configure}. More details about logging can be found under | ||
| 1547 | @uref{https://gnunet.org/logging}. | ||
| 1548 | |||
| 1549 | You should also probably enable the creation of core files, by setting | ||
| 1550 | @code{ulimit}, and echo'ing @code{1} into | ||
| 1551 | @file{/proc/sys/kernel/core\_uses\_pid}. Then you can investigate the | ||
| 1552 | core dumps with @command{gdb}, which is often the fastest method to | ||
| 1553 | find simple errors. | ||
| 1554 | |||
| 1555 | Exercise: Add a memory leak to your service and obtain a trace | ||
| 1556 | pointing to the leak using @command{valgrind} while running the service | ||
| 1557 | from @command{gnunet-service-arm}. | ||
| 1558 | |||
| 1559 | @bye | ||
diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi deleted file mode 100644 index 05522d7d0..000000000 --- a/doc/documentation/gnunet.texi +++ /dev/null | |||
| @@ -1,247 +0,0 @@ | |||
| 1 | \input texinfo | ||
| 2 | @c -*-texinfo-*- | ||
| 3 | @setfilename gnunet.info | ||
| 4 | @documentencoding UTF-8 | ||
| 5 | @settitle GNUnet Reference Manual | ||
| 6 | @c @exampleindent 2 | ||
| 7 | |||
| 8 | @c Set Versions which might be used in more than one place: | ||
| 9 | @set GNUFTP-URL https://ftp.gnu.org/gnu/gnunet | ||
| 10 | @set PYPI-URL https://pypi.python.org/packages/source | ||
| 11 | @set GNURL-VERSION-CURRENT 7.55.1 | ||
| 12 | @set GNUNET-DIST-URL https://gnunet.org/sites/default/files/ | ||
| 13 | @include version.texi | ||
| 14 | @c @set OPENPGP-SIGNING-KEY-ID | ||
| 15 | |||
| 16 | @copying | ||
| 17 | Copyright @copyright{} 2001-2018 GNUnet e.V. | ||
| 18 | |||
| 19 | Permission is granted to copy, distribute and/or modify this document | ||
| 20 | under the terms of the GNU Free Documentation License, Version 1.3 or | ||
| 21 | any later version published by the Free Software Foundation; with no | ||
| 22 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A | ||
| 23 | copy of the license is included in the section entitled ``GNU Free | ||
| 24 | Documentation License''. | ||
| 25 | |||
| 26 | A copy of the license is also available from the Free Software | ||
| 27 | Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}. | ||
| 28 | |||
| 29 | Alternately, this document is also available under the General | ||
| 30 | Public License, version 3 or later, as published by the Free Software | ||
| 31 | Foundation. A copy of the license is included in the section entitled | ||
| 32 | ``GNU General Public License''. | ||
| 33 | |||
| 34 | A copy of the license is also available from the Free Software | ||
| 35 | Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. | ||
| 36 | @end copying | ||
| 37 | |||
| 38 | @c TODO: Improve this and improve https://directory.fsf.org/wiki/Gnunet | ||
| 39 | @c NOTE FOR TRANSLATORS: Due to en.wikipedia.org being the wikipedia | ||
| 40 | @c which is more up to date than others, refrain | ||
| 41 | @c from using localized wikipedia unless you are | ||
| 42 | @c sure the articles content is good enough. For | ||
| 43 | @c example the german wikipedia entry for GNUnet | ||
| 44 | @c is in a terrible shape, but the en.wikipedia.org | ||
| 45 | @c entry is still acceptable (although in need of | ||
| 46 | @c updates). | ||
| 47 | |||
| 48 | @dircategory Networking | ||
| 49 | @direntry | ||
| 50 | * GNUnet: (gnunet). Framework for secure peer-to-peer networking | ||
| 51 | @end direntry | ||
| 52 | |||
| 53 | @titlepage | ||
| 54 | @title GNUnet Reference Manual | ||
| 55 | @subtitle Installing, configuring, using and contributing to GNUnet | ||
| 56 | @author The GNUnet Developers | ||
| 57 | |||
| 58 | @page | ||
| 59 | @vskip 0pt plus 1filll | ||
| 60 | Edition @value{EDITION} @* | ||
| 61 | |||
| 62 | @insertcopying | ||
| 63 | @end titlepage | ||
| 64 | |||
| 65 | @summarycontents | ||
| 66 | @contents | ||
| 67 | |||
| 68 | @node Top | ||
| 69 | @top Introduction | ||
| 70 | |||
| 71 | This document is the Reference Manual for GNUnet version @value{VERSION}. | ||
| 72 | |||
| 73 | @menu | ||
| 74 | |||
| 75 | * Preface:: Chapter 0 | ||
| 76 | * Philosophy:: About GNUnet | ||
| 77 | * Key Concepts:: Key concepts of GNUnet | ||
| 78 | @c * Vocabulary:: Vocabulary | ||
| 79 | * Installing GNUnet:: Installing GNUnet | ||
| 80 | * Using GNUnet:: Using GNUnet | ||
| 81 | @c * Configuration Handbook:: Configuring GNUnet | ||
| 82 | * GNUnet Contributors Handbook:: Contributing to GNUnet | ||
| 83 | * GNUnet Developer Handbook:: Developing GNUnet | ||
| 84 | * GNU Free Documentation License:: The license of this manual | ||
| 85 | * GNU General Public License:: | ||
| 86 | * GNU Affero General Public License:: | ||
| 87 | * Concept Index:: Concepts | ||
| 88 | * Programming Index:: Data types, functions, and variables | ||
| 89 | |||
| 90 | @detailmenu | ||
| 91 | --- The Detailed Node Listing --- | ||
| 92 | |||
| 93 | Preface | ||
| 94 | |||
| 95 | * About this book | ||
| 96 | * Contributing to this book | ||
| 97 | * Introduction | ||
| 98 | * Typography:: | ||
| 99 | |||
| 100 | Philosophy | ||
| 101 | |||
| 102 | * Design Principles:: | ||
| 103 | * Privacy and Anonymity:: | ||
| 104 | * Practicality:: | ||
| 105 | |||
| 106 | Key Concepts | ||
| 107 | |||
| 108 | * Authentication:: | ||
| 109 | * Accounting to Encourage Resource Sharing:: | ||
| 110 | * Confidentiality:: | ||
| 111 | * Anonymity:: | ||
| 112 | * Deniability:: | ||
| 113 | * Peer Identities:: | ||
| 114 | * Zones in the GNU Name System (GNS Zones):: | ||
| 115 | * Egos:: | ||
| 116 | * Backup of Identities and Egos:: | ||
| 117 | * Revocation:: | ||
| 118 | |||
| 119 | Installing GNUnet | ||
| 120 | * Installing dependencies:: | ||
| 121 | * Getting the Source Code:: | ||
| 122 | * Create @code{gnunet} user and group:: | ||
| 123 | * Preparing and Compiling the Source Code:: | ||
| 124 | * Installation:: | ||
| 125 | * MOVED FROM USER Checking the Installation:: | ||
| 126 | * MOVED FROM USER The graphical configuration interface:: | ||
| 127 | * MOVED FROM USER Config Leftovers:: | ||
| 128 | |||
| 129 | Using GNUnet | ||
| 130 | |||
| 131 | * Start and stop GNUnet:: | ||
| 132 | * First steps - Using the GNU Name System:: | ||
| 133 | * First steps - Using GNUnet Conversation:: | ||
| 134 | * First steps - Using the GNUnet VPN:: | ||
| 135 | * File-sharing:: | ||
| 136 | * The GNU Name System:: | ||
| 137 | * Using the Virtual Public Network:: | ||
| 138 | |||
| 139 | GNUnet Contributors Handbook | ||
| 140 | |||
| 141 | * Contributing to GNUnet:: | ||
| 142 | * Licenses of contributions:: | ||
| 143 | * Copyright Assignment:: | ||
| 144 | * Contributing to the Reference Manual:: | ||
| 145 | * Contributing testcases:: | ||
| 146 | |||
| 147 | GNUnet Developer Handbook | ||
| 148 | |||
| 149 | * Developer Introduction:: | ||
| 150 | * Internal dependencies:: | ||
| 151 | * Code overview:: | ||
| 152 | * System Architecture:: | ||
| 153 | * Subsystem stability:: | ||
| 154 | * Naming conventions and coding style guide:: | ||
| 155 | * Build-system:: | ||
| 156 | * Developing extensions for GNUnet using the gnunet-ext template:: | ||
| 157 | * Writing testcases:: | ||
| 158 | * Building GNUnet and its dependencies:: | ||
| 159 | * TESTING library:: | ||
| 160 | * Performance regression analysis with Gauger:: | ||
| 161 | * TESTBED Subsystem:: | ||
| 162 | * libgnunetutil:: | ||
| 163 | * Automatic Restart Manager (ARM):: | ||
| 164 | * TRANSPORT Subsystem:: | ||
| 165 | * NAT library:: | ||
| 166 | * Distance-Vector plugin:: | ||
| 167 | * SMTP plugin:: | ||
| 168 | * Bluetooth plugin:: | ||
| 169 | * WLAN plugin:: | ||
| 170 | * ATS Subsystem:: | ||
| 171 | * CORE Subsystem:: | ||
| 172 | * CADET Subsystem:: | ||
| 173 | * NSE Subsystem:: | ||
| 174 | * HOSTLIST Subsystem:: | ||
| 175 | * IDENTITY Subsystem:: | ||
| 176 | * NAMESTORE Subsystem:: | ||
| 177 | * PEERINFO Subsystem:: | ||
| 178 | * PEERSTORE Subsystem:: | ||
| 179 | * SET Subsystem:: | ||
| 180 | * STATISTICS Subsystem:: | ||
| 181 | * Distributed Hash Table (DHT):: | ||
| 182 | * GNU Name System (GNS):: | ||
| 183 | * GNS Namecache:: | ||
| 184 | * REVOCATION Subsystem:: | ||
| 185 | * File-sharing (FS) Subsystem:: | ||
| 186 | * REGEX Subsystem:: | ||
| 187 | |||
| 188 | @end detailmenu | ||
| 189 | @end menu | ||
| 190 | |||
| 191 | @c ********************************************************************* | ||
| 192 | @include chapters/preface.texi | ||
| 193 | @c ********************************************************************* | ||
| 194 | |||
| 195 | @c ********************************************************************* | ||
| 196 | @include chapters/philosophy.texi | ||
| 197 | @c ********************************************************************* | ||
| 198 | |||
| 199 | @c ********************************************************************* | ||
| 200 | @include chapters/keyconcepts.texi | ||
| 201 | @c ********************************************************************* | ||
| 202 | |||
| 203 | @c ********************************************************************* | ||
| 204 | @include chapters/installation.texi | ||
| 205 | @c ********************************************************************* | ||
| 206 | |||
| 207 | @c ********************************************************************* | ||
| 208 | @include chapters/user.texi | ||
| 209 | @c ********************************************************************* | ||
| 210 | |||
| 211 | @include chapters/contributing.texi | ||
| 212 | |||
| 213 | @c ********************************************************************* | ||
| 214 | @include chapters/developer.texi | ||
| 215 | @c ********************************************************************* | ||
| 216 | |||
| 217 | @c ********************************************************************* | ||
| 218 | @node GNU Free Documentation License | ||
| 219 | @appendix GNU Free Documentation License | ||
| 220 | @cindex license, GNU Free Documentation License | ||
| 221 | @include fdl-1.3.texi | ||
| 222 | |||
| 223 | @c ********************************************************************* | ||
| 224 | @node GNU General Public License | ||
| 225 | @appendix GNU General Public License | ||
| 226 | @cindex license, GNU General Public License | ||
| 227 | @include gpl-3.0.texi | ||
| 228 | |||
| 229 | @c ********************************************************************* | ||
| 230 | @node GNU Affero General Public License | ||
| 231 | @appendix GNU Affero General Public License | ||
| 232 | @cindex license, GNU Affero General Public License | ||
| 233 | @include agpl-3.0.texi | ||
| 234 | |||
| 235 | @c ********************************************************************* | ||
| 236 | @node Concept Index | ||
| 237 | @unnumbered Concept Index | ||
| 238 | @printindex cp | ||
| 239 | |||
| 240 | @node Programming Index | ||
| 241 | @unnumbered Programming Index | ||
| 242 | @syncodeindex tp fn | ||
| 243 | @syncodeindex vr fn | ||
| 244 | @syncodeindex pg fn | ||
| 245 | @printindex fn | ||
| 246 | |||
| 247 | @bye | ||
diff --git a/doc/documentation/gpl-3.0.texi b/doc/documentation/gpl-3.0.texi deleted file mode 100644 index 0e2e212ac..000000000 --- a/doc/documentation/gpl-3.0.texi +++ /dev/null | |||
| @@ -1,717 +0,0 @@ | |||
| 1 | @c The GNU General Public License. | ||
| 2 | @center Version 3, 29 June 2007 | ||
| 3 | |||
| 4 | @c This file is intended to be included within another document, | ||
| 5 | @c hence no sectioning command or @node. | ||
| 6 | |||
| 7 | @display | ||
| 8 | Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} | ||
| 9 | |||
| 10 | Everyone is permitted to copy and distribute verbatim copies of this | ||
| 11 | license document, but changing it is not allowed. | ||
| 12 | @end display | ||
| 13 | |||
| 14 | @heading Preamble | ||
| 15 | |||
| 16 | The GNU General Public License is a free, copyleft license for | ||
| 17 | software and other kinds of works. | ||
| 18 | |||
| 19 | The licenses for most software and other practical works are designed | ||
| 20 | to take away your freedom to share and change the works. By contrast, | ||
| 21 | the GNU General Public License is intended to guarantee your freedom | ||
| 22 | to share and change all versions of a program---to make sure it remains | ||
| 23 | free software for all its users. We, the Free Software Foundation, | ||
| 24 | use the GNU General Public License for most of our software; it | ||
| 25 | applies also to any other work released this way by its authors. You | ||
| 26 | can apply it to your programs, too. | ||
| 27 | |||
| 28 | When we speak of free software, we are referring to freedom, not | ||
| 29 | price. Our General Public Licenses are designed to make sure that you | ||
| 30 | have the freedom to distribute copies of free software (and charge for | ||
| 31 | them if you wish), that you receive source code or can get it if you | ||
| 32 | want it, that you can change the software or use pieces of it in new | ||
| 33 | free programs, and that you know you can do these things. | ||
| 34 | |||
| 35 | To protect your rights, we need to prevent others from denying you | ||
| 36 | these rights or asking you to surrender the rights. Therefore, you | ||
| 37 | have certain responsibilities if you distribute copies of the | ||
| 38 | software, or if you modify it: responsibilities to respect the freedom | ||
| 39 | of others. | ||
| 40 | |||
| 41 | For example, if you distribute copies of such a program, whether | ||
| 42 | gratis or for a fee, you must pass on to the recipients the same | ||
| 43 | freedoms that you received. You must make sure that they, too, | ||
| 44 | receive or can get the source code. And you must show them these | ||
| 45 | terms so they know their rights. | ||
| 46 | |||
| 47 | Developers that use the GNU GPL protect your rights with two steps: | ||
| 48 | (1) assert copyright on the software, and (2) offer you this License | ||
| 49 | giving you legal permission to copy, distribute and/or modify it. | ||
| 50 | |||
| 51 | For the developers' and authors' protection, the GPL clearly explains | ||
| 52 | that there is no warranty for this free software. For both users' and | ||
| 53 | authors' sake, the GPL requires that modified versions be marked as | ||
| 54 | changed, so that their problems will not be attributed erroneously to | ||
| 55 | authors of previous versions. | ||
| 56 | |||
| 57 | Some devices are designed to deny users access to install or run | ||
| 58 | modified versions of the software inside them, although the | ||
| 59 | manufacturer can do so. This is fundamentally incompatible with the | ||
| 60 | aim of protecting users' freedom to change the software. The | ||
| 61 | systematic pattern of such abuse occurs in the area of products for | ||
| 62 | individuals to use, which is precisely where it is most unacceptable. | ||
| 63 | Therefore, we have designed this version of the GPL to prohibit the | ||
| 64 | practice for those products. If such problems arise substantially in | ||
| 65 | other domains, we stand ready to extend this provision to those | ||
| 66 | domains in future versions of the GPL, as needed to protect the | ||
| 67 | freedom of users. | ||
| 68 | |||
| 69 | Finally, every program is threatened constantly by software patents. | ||
| 70 | States should not allow patents to restrict development and use of | ||
| 71 | software on general-purpose computers, but in those that do, we wish | ||
| 72 | to avoid the special danger that patents applied to a free program | ||
| 73 | could make it effectively proprietary. To prevent this, the GPL | ||
| 74 | assures that patents cannot be used to render the program non-free. | ||
| 75 | |||
| 76 | The precise terms and conditions for copying, distribution and | ||
| 77 | modification follow. | ||
| 78 | |||
| 79 | @heading TERMS AND CONDITIONS | ||
| 80 | |||
| 81 | @enumerate 0 | ||
| 82 | @item Definitions. | ||
| 83 | |||
| 84 | ``This License'' refers to version 3 of the GNU General Public License. | ||
| 85 | |||
| 86 | ``Copyright'' also means copyright-like laws that apply to other kinds | ||
| 87 | of works, such as semiconductor masks. | ||
| 88 | |||
| 89 | ``The Program'' refers to any copyrightable work licensed under this | ||
| 90 | License. Each licensee is addressed as ``you''. ``Licensees'' and | ||
| 91 | ``recipients'' may be individuals or organizations. | ||
| 92 | |||
| 93 | To ``modify'' a work means to copy from or adapt all or part of the work | ||
| 94 | in a fashion requiring copyright permission, other than the making of | ||
| 95 | an exact copy. The resulting work is called a ``modified version'' of | ||
| 96 | the earlier work or a work ``based on'' the earlier work. | ||
| 97 | |||
| 98 | A ``covered work'' means either the unmodified Program or a work based | ||
| 99 | on the Program. | ||
| 100 | |||
| 101 | To ``propagate'' a work means to do anything with it that, without | ||
| 102 | permission, would make you directly or secondarily liable for | ||
| 103 | infringement under applicable copyright law, except executing it on a | ||
| 104 | computer or modifying a private copy. Propagation includes copying, | ||
| 105 | distribution (with or without modification), making available to the | ||
| 106 | public, and in some countries other activities as well. | ||
| 107 | |||
| 108 | To ``convey'' a work means any kind of propagation that enables other | ||
| 109 | parties to make or receive copies. Mere interaction with a user | ||
| 110 | through a computer network, with no transfer of a copy, is not | ||
| 111 | conveying. | ||
| 112 | |||
| 113 | An interactive user interface displays ``Appropriate Legal Notices'' to | ||
| 114 | the extent that it includes a convenient and prominently visible | ||
| 115 | feature that (1) displays an appropriate copyright notice, and (2) | ||
| 116 | tells the user that there is no warranty for the work (except to the | ||
| 117 | extent that warranties are provided), that licensees may convey the | ||
| 118 | work under this License, and how to view a copy of this License. If | ||
| 119 | the interface presents a list of user commands or options, such as a | ||
| 120 | menu, a prominent item in the list meets this criterion. | ||
| 121 | |||
| 122 | @item Source Code. | ||
| 123 | |||
| 124 | The ``source code'' for a work means the preferred form of the work for | ||
| 125 | making modifications to it. ``Object code'' means any non-source form | ||
| 126 | of a work. | ||
| 127 | |||
| 128 | A ``Standard Interface'' means an interface that either is an official | ||
| 129 | standard defined by a recognized standards body, or, in the case of | ||
| 130 | interfaces specified for a particular programming language, one that | ||
| 131 | is widely used among developers working in that language. | ||
| 132 | |||
| 133 | The ``System Libraries'' of an executable work include anything, other | ||
| 134 | than the work as a whole, that (a) is included in the normal form of | ||
| 135 | packaging a Major Component, but which is not part of that Major | ||
| 136 | Component, and (b) serves only to enable use of the work with that | ||
| 137 | Major Component, or to implement a Standard Interface for which an | ||
| 138 | implementation is available to the public in source code form. A | ||
| 139 | ``Major Component'', in this context, means a major essential component | ||
| 140 | (kernel, window system, and so on) of the specific operating system | ||
| 141 | (if any) on which the executable work runs, or a compiler used to | ||
| 142 | produce the work, or an object code interpreter used to run it. | ||
| 143 | |||
| 144 | The ``Corresponding Source'' for a work in object code form means all | ||
| 145 | the source code needed to generate, install, and (for an executable | ||
| 146 | work) run the object code and to modify the work, including scripts to | ||
| 147 | control those activities. However, it does not include the work's | ||
| 148 | System Libraries, or general-purpose tools or generally available free | ||
| 149 | programs which are used unmodified in performing those activities but | ||
| 150 | which are not part of the work. For example, Corresponding Source | ||
| 151 | includes interface definition files associated with source files for | ||
| 152 | the work, and the source code for shared libraries and dynamically | ||
| 153 | linked subprograms that the work is specifically designed to require, | ||
| 154 | such as by intimate data communication or control flow between those | ||
| 155 | subprograms and other parts of the work. | ||
| 156 | |||
| 157 | The Corresponding Source need not include anything that users can | ||
| 158 | regenerate automatically from other parts of the Corresponding Source. | ||
| 159 | |||
| 160 | The Corresponding Source for a work in source code form is that same | ||
| 161 | work. | ||
| 162 | |||
| 163 | @item Basic Permissions. | ||
| 164 | |||
| 165 | All rights granted under this License are granted for the term of | ||
| 166 | copyright on the Program, and are irrevocable provided the stated | ||
| 167 | conditions are met. This License explicitly affirms your unlimited | ||
| 168 | permission to run the unmodified Program. The output from running a | ||
| 169 | covered work is covered by this License only if the output, given its | ||
| 170 | content, constitutes a covered work. This License acknowledges your | ||
| 171 | rights of fair use or other equivalent, as provided by copyright law. | ||
| 172 | |||
| 173 | You may make, run and propagate covered works that you do not convey, | ||
| 174 | without conditions so long as your license otherwise remains in force. | ||
| 175 | You may convey covered works to others for the sole purpose of having | ||
| 176 | them make modifications exclusively for you, or provide you with | ||
| 177 | facilities for running those works, provided that you comply with the | ||
| 178 | terms of this License in conveying all material for which you do not | ||
| 179 | control copyright. Those thus making or running the covered works for | ||
| 180 | you must do so exclusively on your behalf, under your direction and | ||
| 181 | control, on terms that prohibit them from making any copies of your | ||
| 182 | copyrighted material outside their relationship with you. | ||
| 183 | |||
| 184 | Conveying under any other circumstances is permitted solely under the | ||
| 185 | conditions stated below. Sublicensing is not allowed; section 10 | ||
| 186 | makes it unnecessary. | ||
| 187 | |||
| 188 | @item Protecting Users' Legal Rights From Anti-Circumvention Law. | ||
| 189 | |||
| 190 | No covered work shall be deemed part of an effective technological | ||
| 191 | measure under any applicable law fulfilling obligations under article | ||
| 192 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or | ||
| 193 | similar laws prohibiting or restricting circumvention of such | ||
| 194 | measures. | ||
| 195 | |||
| 196 | When you convey a covered work, you waive any legal power to forbid | ||
| 197 | circumvention of technological measures to the extent such | ||
| 198 | circumvention is effected by exercising rights under this License with | ||
| 199 | respect to the covered work, and you disclaim any intention to limit | ||
| 200 | operation or modification of the work as a means of enforcing, against | ||
| 201 | the work's users, your or third parties' legal rights to forbid | ||
| 202 | circumvention of technological measures. | ||
| 203 | |||
| 204 | @item Conveying Verbatim Copies. | ||
| 205 | |||
| 206 | You may convey verbatim copies of the Program's source code as you | ||
| 207 | receive it, in any medium, provided that you conspicuously and | ||
| 208 | appropriately publish on each copy an appropriate copyright notice; | ||
| 209 | keep intact all notices stating that this License and any | ||
| 210 | non-permissive terms added in accord with section 7 apply to the code; | ||
| 211 | keep intact all notices of the absence of any warranty; and give all | ||
| 212 | recipients a copy of this License along with the Program. | ||
| 213 | |||
| 214 | You may charge any price or no price for each copy that you convey, | ||
| 215 | and you may offer support or warranty protection for a fee. | ||
| 216 | |||
| 217 | @item Conveying Modified Source Versions. | ||
| 218 | |||
| 219 | You may convey a work based on the Program, or the modifications to | ||
| 220 | produce it from the Program, in the form of source code under the | ||
| 221 | terms of section 4, provided that you also meet all of these | ||
| 222 | conditions: | ||
| 223 | |||
| 224 | @enumerate a | ||
| 225 | @item | ||
| 226 | The work must carry prominent notices stating that you modified it, | ||
| 227 | and giving a relevant date. | ||
| 228 | |||
| 229 | @item | ||
| 230 | The work must carry prominent notices stating that it is released | ||
| 231 | under this License and any conditions added under section 7. This | ||
| 232 | requirement modifies the requirement in section 4 to ``keep intact all | ||
| 233 | notices''. | ||
| 234 | |||
| 235 | @item | ||
| 236 | You must license the entire work, as a whole, under this License to | ||
| 237 | anyone who comes into possession of a copy. This License will | ||
| 238 | therefore apply, along with any applicable section 7 additional terms, | ||
| 239 | to the whole of the work, and all its parts, regardless of how they | ||
| 240 | are packaged. This License gives no permission to license the work in | ||
| 241 | any other way, but it does not invalidate such permission if you have | ||
| 242 | separately received it. | ||
| 243 | |||
| 244 | @item | ||
| 245 | If the work has interactive user interfaces, each must display | ||
| 246 | Appropriate Legal Notices; however, if the Program has interactive | ||
| 247 | interfaces that do not display Appropriate Legal Notices, your work | ||
| 248 | need not make them do so. | ||
| 249 | @end enumerate | ||
| 250 | |||
| 251 | A compilation of a covered work with other separate and independent | ||
| 252 | works, which are not by their nature extensions of the covered work, | ||
| 253 | and which are not combined with it such as to form a larger program, | ||
| 254 | in or on a volume of a storage or distribution medium, is called an | ||
| 255 | ``aggregate'' if the compilation and its resulting copyright are not | ||
| 256 | used to limit the access or legal rights of the compilation's users | ||
| 257 | beyond what the individual works permit. Inclusion of a covered work | ||
| 258 | in an aggregate does not cause this License to apply to the other | ||
| 259 | parts of the aggregate. | ||
| 260 | |||
| 261 | @item Conveying Non-Source Forms. | ||
| 262 | |||
| 263 | You may convey a covered work in object code form under the terms of | ||
| 264 | sections 4 and 5, provided that you also convey the machine-readable | ||
| 265 | Corresponding Source under the terms of this License, in one of these | ||
| 266 | ways: | ||
| 267 | |||
| 268 | @enumerate a | ||
| 269 | @item | ||
| 270 | Convey the object code in, or embodied in, a physical product | ||
| 271 | (including a physical distribution medium), accompanied by the | ||
| 272 | Corresponding Source fixed on a durable physical medium customarily | ||
| 273 | used for software interchange. | ||
| 274 | |||
| 275 | @item | ||
| 276 | Convey the object code in, or embodied in, a physical product | ||
| 277 | (including a physical distribution medium), accompanied by a written | ||
| 278 | offer, valid for at least three years and valid for as long as you | ||
| 279 | offer spare parts or customer support for that product model, to give | ||
| 280 | anyone who possesses the object code either (1) a copy of the | ||
| 281 | Corresponding Source for all the software in the product that is | ||
| 282 | covered by this License, on a durable physical medium customarily used | ||
| 283 | for software interchange, for a price no more than your reasonable | ||
| 284 | cost of physically performing this conveying of source, or (2) access | ||
| 285 | to copy the Corresponding Source from a network server at no charge. | ||
| 286 | |||
| 287 | @item | ||
| 288 | Convey individual copies of the object code with a copy of the written | ||
| 289 | offer to provide the Corresponding Source. This alternative is | ||
| 290 | allowed only occasionally and noncommercially, and only if you | ||
| 291 | received the object code with such an offer, in accord with subsection | ||
| 292 | 6b. | ||
| 293 | |||
| 294 | @item | ||
| 295 | Convey the object code by offering access from a designated place | ||
| 296 | (gratis or for a charge), and offer equivalent access to the | ||
| 297 | Corresponding Source in the same way through the same place at no | ||
| 298 | further charge. You need not require recipients to copy the | ||
| 299 | Corresponding Source along with the object code. If the place to copy | ||
| 300 | the object code is a network server, the Corresponding Source may be | ||
| 301 | on a different server (operated by you or a third party) that supports | ||
| 302 | equivalent copying facilities, provided you maintain clear directions | ||
| 303 | next to the object code saying where to find the Corresponding Source. | ||
| 304 | Regardless of what server hosts the Corresponding Source, you remain | ||
| 305 | obligated to ensure that it is available for as long as needed to | ||
| 306 | satisfy these requirements. | ||
| 307 | |||
| 308 | @item | ||
| 309 | Convey the object code using peer-to-peer transmission, provided you | ||
| 310 | inform other peers where the object code and Corresponding Source of | ||
| 311 | the work are being offered to the general public at no charge under | ||
| 312 | subsection 6d. | ||
| 313 | |||
| 314 | @end enumerate | ||
| 315 | |||
| 316 | A separable portion of the object code, whose source code is excluded | ||
| 317 | from the Corresponding Source as a System Library, need not be | ||
| 318 | included in conveying the object code work. | ||
| 319 | |||
| 320 | A ``User Product'' is either (1) a ``consumer product'', which means any | ||
| 321 | tangible personal property which is normally used for personal, | ||
| 322 | family, or household purposes, or (2) anything designed or sold for | ||
| 323 | incorporation into a dwelling. In determining whether a product is a | ||
| 324 | consumer product, doubtful cases shall be resolved in favor of | ||
| 325 | coverage. For a particular product received by a particular user, | ||
| 326 | ``normally used'' refers to a typical or common use of that class of | ||
| 327 | product, regardless of the status of the particular user or of the way | ||
| 328 | in which the particular user actually uses, or expects or is expected | ||
| 329 | to use, the product. A product is a consumer product regardless of | ||
| 330 | whether the product has substantial commercial, industrial or | ||
| 331 | non-consumer uses, unless such uses represent the only significant | ||
| 332 | mode of use of the product. | ||
| 333 | |||
| 334 | ``Installation Information'' for a User Product means any methods, | ||
| 335 | procedures, authorization keys, or other information required to | ||
| 336 | install and execute modified versions of a covered work in that User | ||
| 337 | Product from a modified version of its Corresponding Source. The | ||
| 338 | information must suffice to ensure that the continued functioning of | ||
| 339 | the modified object code is in no case prevented or interfered with | ||
| 340 | solely because modification has been made. | ||
| 341 | |||
| 342 | If you convey an object code work under this section in, or with, or | ||
| 343 | specifically for use in, a User Product, and the conveying occurs as | ||
| 344 | part of a transaction in which the right of possession and use of the | ||
| 345 | User Product is transferred to the recipient in perpetuity or for a | ||
| 346 | fixed term (regardless of how the transaction is characterized), the | ||
| 347 | Corresponding Source conveyed under this section must be accompanied | ||
| 348 | by the Installation Information. But this requirement does not apply | ||
| 349 | if neither you nor any third party retains the ability to install | ||
| 350 | modified object code on the User Product (for example, the work has | ||
| 351 | been installed in ROM). | ||
| 352 | |||
| 353 | The requirement to provide Installation Information does not include a | ||
| 354 | requirement to continue to provide support service, warranty, or | ||
| 355 | updates for a work that has been modified or installed by the | ||
| 356 | recipient, or for the User Product in which it has been modified or | ||
| 357 | installed. Access to a network may be denied when the modification | ||
| 358 | itself materially and adversely affects the operation of the network | ||
| 359 | or violates the rules and protocols for communication across the | ||
| 360 | network. | ||
| 361 | |||
| 362 | Corresponding Source conveyed, and Installation Information provided, | ||
| 363 | in accord with this section must be in a format that is publicly | ||
| 364 | documented (and with an implementation available to the public in | ||
| 365 | source code form), and must require no special password or key for | ||
| 366 | unpacking, reading or copying. | ||
| 367 | |||
| 368 | @item Additional Terms. | ||
| 369 | |||
| 370 | ``Additional permissions'' are terms that supplement the terms of this | ||
| 371 | License by making exceptions from one or more of its conditions. | ||
| 372 | Additional permissions that are applicable to the entire Program shall | ||
| 373 | be treated as though they were included in this License, to the extent | ||
| 374 | that they are valid under applicable law. If additional permissions | ||
| 375 | apply only to part of the Program, that part may be used separately | ||
| 376 | under those permissions, but the entire Program remains governed by | ||
| 377 | this License without regard to the additional permissions. | ||
| 378 | |||
| 379 | When you convey a copy of a covered work, you may at your option | ||
| 380 | remove any additional permissions from that copy, or from any part of | ||
| 381 | it. (Additional permissions may be written to require their own | ||
| 382 | removal in certain cases when you modify the work.) You may place | ||
| 383 | additional permissions on material, added by you to a covered work, | ||
| 384 | for which you have or can give appropriate copyright permission. | ||
| 385 | |||
| 386 | Notwithstanding any other provision of this License, for material you | ||
| 387 | add to a covered work, you may (if authorized by the copyright holders | ||
| 388 | of that material) supplement the terms of this License with terms: | ||
| 389 | |||
| 390 | @enumerate a | ||
| 391 | @item | ||
| 392 | Disclaiming warranty or limiting liability differently from the terms | ||
| 393 | of sections 15 and 16 of this License; or | ||
| 394 | |||
| 395 | @item | ||
| 396 | Requiring preservation of specified reasonable legal notices or author | ||
| 397 | attributions in that material or in the Appropriate Legal Notices | ||
| 398 | displayed by works containing it; or | ||
| 399 | |||
| 400 | @item | ||
| 401 | Prohibiting misrepresentation of the origin of that material, or | ||
| 402 | requiring that modified versions of such material be marked in | ||
| 403 | reasonable ways as different from the original version; or | ||
| 404 | |||
| 405 | @item | ||
| 406 | Limiting the use for publicity purposes of names of licensors or | ||
| 407 | authors of the material; or | ||
| 408 | |||
| 409 | @item | ||
| 410 | Declining to grant rights under trademark law for use of some trade | ||
| 411 | names, trademarks, or service marks; or | ||
| 412 | |||
| 413 | @item | ||
| 414 | Requiring indemnification of licensors and authors of that material by | ||
| 415 | anyone who conveys the material (or modified versions of it) with | ||
| 416 | contractual assumptions of liability to the recipient, for any | ||
| 417 | liability that these contractual assumptions directly impose on those | ||
| 418 | licensors and authors. | ||
| 419 | @end enumerate | ||
| 420 | |||
| 421 | All other non-permissive additional terms are considered ``further | ||
| 422 | restrictions'' within the meaning of section 10. If the Program as you | ||
| 423 | received it, or any part of it, contains a notice stating that it is | ||
| 424 | governed by this License along with a term that is a further | ||
| 425 | restriction, you may remove that term. If a license document contains | ||
| 426 | a further restriction but permits relicensing or conveying under this | ||
| 427 | License, you may add to a covered work material governed by the terms | ||
| 428 | of that license document, provided that the further restriction does | ||
| 429 | not survive such relicensing or conveying. | ||
| 430 | |||
| 431 | If you add terms to a covered work in accord with this section, you | ||
| 432 | must place, in the relevant source files, a statement of the | ||
| 433 | additional terms that apply to those files, or a notice indicating | ||
| 434 | where to find the applicable terms. | ||
| 435 | |||
| 436 | Additional terms, permissive or non-permissive, may be stated in the | ||
| 437 | form of a separately written license, or stated as exceptions; the | ||
| 438 | above requirements apply either way. | ||
| 439 | |||
| 440 | @item Termination. | ||
| 441 | |||
| 442 | You may not propagate or modify a covered work except as expressly | ||
| 443 | provided under this License. Any attempt otherwise to propagate or | ||
| 444 | modify it is void, and will automatically terminate your rights under | ||
| 445 | this License (including any patent licenses granted under the third | ||
| 446 | paragraph of section 11). | ||
| 447 | |||
| 448 | However, if you cease all violation of this License, then your license | ||
| 449 | from a particular copyright holder is reinstated (a) provisionally, | ||
| 450 | unless and until the copyright holder explicitly and finally | ||
| 451 | terminates your license, and (b) permanently, if the copyright holder | ||
| 452 | fails to notify you of the violation by some reasonable means prior to | ||
| 453 | 60 days after the cessation. | ||
| 454 | |||
| 455 | Moreover, your license from a particular copyright holder is | ||
| 456 | reinstated permanently if the copyright holder notifies you of the | ||
| 457 | violation by some reasonable means, this is the first time you have | ||
| 458 | received notice of violation of this License (for any work) from that | ||
| 459 | copyright holder, and you cure the violation prior to 30 days after | ||
| 460 | your receipt of the notice. | ||
| 461 | |||
| 462 | Termination of your rights under this section does not terminate the | ||
| 463 | licenses of parties who have received copies or rights from you under | ||
| 464 | this License. If your rights have been terminated and not permanently | ||
| 465 | reinstated, you do not qualify to receive new licenses for the same | ||
| 466 | material under section 10. | ||
| 467 | |||
| 468 | @item Acceptance Not Required for Having Copies. | ||
| 469 | |||
| 470 | You are not required to accept this License in order to receive or run | ||
| 471 | a copy of the Program. Ancillary propagation of a covered work | ||
| 472 | occurring solely as a consequence of using peer-to-peer transmission | ||
| 473 | to receive a copy likewise does not require acceptance. However, | ||
| 474 | nothing other than this License grants you permission to propagate or | ||
| 475 | modify any covered work. These actions infringe copyright if you do | ||
| 476 | not accept this License. Therefore, by modifying or propagating a | ||
| 477 | covered work, you indicate your acceptance of this License to do so. | ||
| 478 | |||
| 479 | @item Automatic Licensing of Downstream Recipients. | ||
| 480 | |||
| 481 | Each time you convey a covered work, the recipient automatically | ||
| 482 | receives a license from the original licensors, to run, modify and | ||
| 483 | propagate that work, subject to this License. You are not responsible | ||
| 484 | for enforcing compliance by third parties with this License. | ||
| 485 | |||
| 486 | An ``entity transaction'' is a transaction transferring control of an | ||
| 487 | organization, or substantially all assets of one, or subdividing an | ||
| 488 | organization, or merging organizations. If propagation of a covered | ||
| 489 | work results from an entity transaction, each party to that | ||
| 490 | transaction who receives a copy of the work also receives whatever | ||
| 491 | licenses to the work the party's predecessor in interest had or could | ||
| 492 | give under the previous paragraph, plus a right to possession of the | ||
| 493 | Corresponding Source of the work from the predecessor in interest, if | ||
| 494 | the predecessor has it or can get it with reasonable efforts. | ||
| 495 | |||
| 496 | You may not impose any further restrictions on the exercise of the | ||
| 497 | rights granted or affirmed under this License. For example, you may | ||
| 498 | not impose a license fee, royalty, or other charge for exercise of | ||
| 499 | rights granted under this License, and you may not initiate litigation | ||
| 500 | (including a cross-claim or counterclaim in a lawsuit) alleging that | ||
| 501 | any patent claim is infringed by making, using, selling, offering for | ||
| 502 | sale, or importing the Program or any portion of it. | ||
| 503 | |||
| 504 | @item Patents. | ||
| 505 | |||
| 506 | A ``contributor'' is a copyright holder who authorizes use under this | ||
| 507 | License of the Program or a work on which the Program is based. The | ||
| 508 | work thus licensed is called the contributor's ``contributor version''. | ||
| 509 | |||
| 510 | A contributor's ``essential patent claims'' are all patent claims owned | ||
| 511 | or controlled by the contributor, whether already acquired or | ||
| 512 | hereafter acquired, that would be infringed by some manner, permitted | ||
| 513 | by this License, of making, using, or selling its contributor version, | ||
| 514 | but do not include claims that would be infringed only as a | ||
| 515 | consequence of further modification of the contributor version. For | ||
| 516 | purposes of this definition, ``control'' includes the right to grant | ||
| 517 | patent sublicenses in a manner consistent with the requirements of | ||
| 518 | this License. | ||
| 519 | |||
| 520 | Each contributor grants you a non-exclusive, worldwide, royalty-free | ||
| 521 | patent license under the contributor's essential patent claims, to | ||
| 522 | make, use, sell, offer for sale, import and otherwise run, modify and | ||
| 523 | propagate the contents of its contributor version. | ||
| 524 | |||
| 525 | In the following three paragraphs, a ``patent license'' is any express | ||
| 526 | agreement or commitment, however denominated, not to enforce a patent | ||
| 527 | (such as an express permission to practice a patent or covenant not to | ||
| 528 | sue for patent infringement). To ``grant'' such a patent license to a | ||
| 529 | party means to make such an agreement or commitment not to enforce a | ||
| 530 | patent against the party. | ||
| 531 | |||
| 532 | If you convey a covered work, knowingly relying on a patent license, | ||
| 533 | and the Corresponding Source of the work is not available for anyone | ||
| 534 | to copy, free of charge and under the terms of this License, through a | ||
| 535 | publicly available network server or other readily accessible means, | ||
| 536 | then you must either (1) cause the Corresponding Source to be so | ||
| 537 | available, or (2) arrange to deprive yourself of the benefit of the | ||
| 538 | patent license for this particular work, or (3) arrange, in a manner | ||
| 539 | consistent with the requirements of this License, to extend the patent | ||
| 540 | license to downstream recipients. ``Knowingly relying'' means you have | ||
| 541 | actual knowledge that, but for the patent license, your conveying the | ||
| 542 | covered work in a country, or your recipient's use of the covered work | ||
| 543 | in a country, would infringe one or more identifiable patents in that | ||
| 544 | country that you have reason to believe are valid. | ||
| 545 | |||
| 546 | If, pursuant to or in connection with a single transaction or | ||
| 547 | arrangement, you convey, or propagate by procuring conveyance of, a | ||
| 548 | covered work, and grant a patent license to some of the parties | ||
| 549 | receiving the covered work authorizing them to use, propagate, modify | ||
| 550 | or convey a specific copy of the covered work, then the patent license | ||
| 551 | you grant is automatically extended to all recipients of the covered | ||
| 552 | work and works based on it. | ||
| 553 | |||
| 554 | A patent license is ``discriminatory'' if it does not include within the | ||
| 555 | scope of its coverage, prohibits the exercise of, or is conditioned on | ||
| 556 | the non-exercise of one or more of the rights that are specifically | ||
| 557 | granted under this License. You may not convey a covered work if you | ||
| 558 | are a party to an arrangement with a third party that is in the | ||
| 559 | business of distributing software, under which you make payment to the | ||
| 560 | third party based on the extent of your activity of conveying the | ||
| 561 | work, and under which the third party grants, to any of the parties | ||
| 562 | who would receive the covered work from you, a discriminatory patent | ||
| 563 | license (a) in connection with copies of the covered work conveyed by | ||
| 564 | you (or copies made from those copies), or (b) primarily for and in | ||
| 565 | connection with specific products or compilations that contain the | ||
| 566 | covered work, unless you entered into that arrangement, or that patent | ||
| 567 | license was granted, prior to 28 March 2007. | ||
| 568 | |||
| 569 | Nothing in this License shall be construed as excluding or limiting | ||
| 570 | any implied license or other defenses to infringement that may | ||
| 571 | otherwise be available to you under applicable patent law. | ||
| 572 | |||
| 573 | @item No Surrender of Others' Freedom. | ||
| 574 | |||
| 575 | If conditions are imposed on you (whether by court order, agreement or | ||
| 576 | otherwise) that contradict the conditions of this License, they do not | ||
| 577 | excuse you from the conditions of this License. If you cannot convey | ||
| 578 | a covered work so as to satisfy simultaneously your obligations under | ||
| 579 | this License and any other pertinent obligations, then as a | ||
| 580 | consequence you may not convey it at all. For example, if you agree | ||
| 581 | to terms that obligate you to collect a royalty for further conveying | ||
| 582 | from those to whom you convey the Program, the only way you could | ||
| 583 | satisfy both those terms and this License would be to refrain entirely | ||
| 584 | from conveying the Program. | ||
| 585 | |||
| 586 | @item Use with the GNU Affero General Public License. | ||
| 587 | |||
| 588 | Notwithstanding any other provision of this License, you have | ||
| 589 | permission to link or combine any covered work with a work licensed | ||
| 590 | under version 3 of the GNU Affero General Public License into a single | ||
| 591 | combined work, and to convey the resulting work. The terms of this | ||
| 592 | License will continue to apply to the part which is the covered work, | ||
| 593 | but the special requirements of the GNU Affero General Public License, | ||
| 594 | section 13, concerning interaction through a network will apply to the | ||
| 595 | combination as such. | ||
| 596 | |||
| 597 | @item Revised Versions of this License. | ||
| 598 | |||
| 599 | The Free Software Foundation may publish revised and/or new versions | ||
| 600 | of the GNU General Public License from time to time. Such new | ||
| 601 | versions will be similar in spirit to the present version, but may | ||
| 602 | differ in detail to address new problems or concerns. | ||
| 603 | |||
| 604 | Each version is given a distinguishing version number. If the Program | ||
| 605 | specifies that a certain numbered version of the GNU General Public | ||
| 606 | License ``or any later version'' applies to it, you have the option of | ||
| 607 | following the terms and conditions either of that numbered version or | ||
| 608 | of any later version published by the Free Software Foundation. If | ||
| 609 | the Program does not specify a version number of the GNU General | ||
| 610 | Public License, you may choose any version ever published by the Free | ||
| 611 | Software Foundation. | ||
| 612 | |||
| 613 | If the Program specifies that a proxy can decide which future versions | ||
| 614 | of the GNU General Public License can be used, that proxy's public | ||
| 615 | statement of acceptance of a version permanently authorizes you to | ||
| 616 | choose that version for the Program. | ||
| 617 | |||
| 618 | Later license versions may give you additional or different | ||
| 619 | permissions. However, no additional obligations are imposed on any | ||
| 620 | author or copyright holder as a result of your choosing to follow a | ||
| 621 | later version. | ||
| 622 | |||
| 623 | @item Disclaimer of Warranty. | ||
| 624 | |||
| 625 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY | ||
| 626 | APPLICABLE LAW@. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT | ||
| 627 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT | ||
| 628 | WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT | ||
| 629 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
| 630 | A PARTICULAR PURPOSE@. THE ENTIRE RISK AS TO THE QUALITY AND | ||
| 631 | PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE PROGRAM PROVE | ||
| 632 | DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR | ||
| 633 | CORRECTION. | ||
| 634 | |||
| 635 | @item Limitation of Liability. | ||
| 636 | |||
| 637 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING | ||
| 638 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR | ||
| 639 | CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, | ||
| 640 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES | ||
| 641 | ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT | ||
| 642 | NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR | ||
| 643 | LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM | ||
| 644 | TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER | ||
| 645 | PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. | ||
| 646 | |||
| 647 | @item Interpretation of Sections 15 and 16. | ||
| 648 | |||
| 649 | If the disclaimer of warranty and limitation of liability provided | ||
| 650 | above cannot be given local legal effect according to their terms, | ||
| 651 | reviewing courts shall apply local law that most closely approximates | ||
| 652 | an absolute waiver of all civil liability in connection with the | ||
| 653 | Program, unless a warranty or assumption of liability accompanies a | ||
| 654 | copy of the Program in return for a fee. | ||
| 655 | |||
| 656 | @end enumerate | ||
| 657 | |||
| 658 | @heading END OF TERMS AND CONDITIONS | ||
| 659 | |||
| 660 | @heading How to Apply These Terms to Your New Programs | ||
| 661 | |||
| 662 | If you develop a new program, and you want it to be of the greatest | ||
| 663 | possible use to the public, the best way to achieve this is to make it | ||
| 664 | free software which everyone can redistribute and change under these | ||
| 665 | terms. | ||
| 666 | |||
| 667 | To do so, attach the following notices to the program. It is safest | ||
| 668 | to attach them to the start of each source file to most effectively | ||
| 669 | state the exclusion of warranty; and each file should have at least | ||
| 670 | the ``copyright'' line and a pointer to where the full notice is found. | ||
| 671 | |||
| 672 | @smallexample | ||
| 673 | @var{one line to give the program's name and a brief idea of what it does.} | ||
| 674 | Copyright (C) @var{year} @var{name of author} | ||
| 675 | |||
| 676 | This program is free software: you can redistribute it and/or modify | ||
| 677 | it under the terms of the GNU General Public License as published by | ||
| 678 | the Free Software Foundation, either version 3 of the License, or (at | ||
| 679 | your option) any later version. | ||
| 680 | |||
| 681 | This program is distributed in the hope that it will be useful, but | ||
| 682 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 683 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU | ||
| 684 | General Public License for more details. | ||
| 685 | |||
| 686 | You should have received a copy of the GNU General Public License | ||
| 687 | along with this program. If not, see @url{http://www.gnu.org/licenses/}. | ||
| 688 | @end smallexample | ||
| 689 | |||
| 690 | Also add information on how to contact you by electronic and paper mail. | ||
| 691 | |||
| 692 | If the program does terminal interaction, make it output a short | ||
| 693 | notice like this when it starts in an interactive mode: | ||
| 694 | |||
| 695 | @smallexample | ||
| 696 | @var{program} Copyright (C) @var{year} @var{name of author} | ||
| 697 | This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. | ||
| 698 | This is free software, and you are welcome to redistribute it | ||
| 699 | under certain conditions; type @samp{show c} for details. | ||
| 700 | @end smallexample | ||
| 701 | |||
| 702 | The hypothetical commands @samp{show w} and @samp{show c} should show | ||
| 703 | the appropriate parts of the General Public License. Of course, your | ||
| 704 | program's commands might be different; for a GUI interface, you would | ||
| 705 | use an ``about box''. | ||
| 706 | |||
| 707 | You should also get your employer (if you work as a programmer) or school, | ||
| 708 | if any, to sign a ``copyright disclaimer'' for the program, if necessary. | ||
| 709 | For more information on this, and how to apply and follow the GNU GPL, see | ||
| 710 | @url{http://www.gnu.org/licenses/}. | ||
| 711 | |||
| 712 | The GNU General Public License does not permit incorporating your | ||
| 713 | program into proprietary programs. If your program is a subroutine | ||
| 714 | library, you may consider it more useful to permit linking proprietary | ||
| 715 | applications with the library. If this is what you want to do, use | ||
| 716 | the GNU Lesser General Public License instead of this License. But | ||
| 717 | first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. | ||
diff --git a/doc/documentation/htmlxref.cnf b/doc/documentation/htmlxref.cnf deleted file mode 100644 index a4928f6fe..000000000 --- a/doc/documentation/htmlxref.cnf +++ /dev/null | |||
| @@ -1,668 +0,0 @@ | |||
| 1 | # htmlxref.cnf - reference file for free Texinfo manuals on the web. | ||
| 2 | # Modified by Ludovic Courtès <ludo@gnu.org> for the GNU Guix manual. | ||
| 3 | # Modified by ng0 <ng0@gnunet.org> for the GNUnet manual. | ||
| 4 | |||
| 5 | htmlxrefversion=2017-10-26.06; # UTC | ||
| 6 | |||
| 7 | # Copyright 2010, 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc. | ||
| 8 | # | ||
| 9 | # Copying and distribution of this file, with or without modification, | ||
| 10 | # are permitted in any medium without royalty provided the copyright | ||
| 11 | # notice and this notice are preserved. | ||
| 12 | # | ||
| 13 | # The latest version of this file is available at | ||
| 14 | # http://ftpmirror.gnu.org/texinfo/htmlxref.cnf. | ||
| 15 | # Email corrections or additions to bug-texinfo@gnu.org. | ||
| 16 | # The primary goal is to list all relevant GNU manuals; | ||
| 17 | # other free manuals are also welcome. | ||
| 18 | # | ||
| 19 | # To be included in this list, a manual must: | ||
| 20 | # | ||
| 21 | # - have a generic url, e.g., no version numbers; | ||
| 22 | # - have a unique file name (e.g., manual identifier), i.e., be related to the | ||
| 23 | # package name. Things like "refman" or "tutorial" don't work. | ||
| 24 | # - follow the naming convention for nodes described at | ||
| 25 | # http://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref.html | ||
| 26 | # This is what makeinfo and texi2html implement. | ||
| 27 | # | ||
| 28 | # Unless the above criteria are met, it's not possible to generate | ||
| 29 | # reliable cross-manual references. | ||
| 30 | # | ||
| 31 | # For information on automatically generating all the useful formats for | ||
| 32 | # a manual to put on the web, see | ||
| 33 | # http://www.gnu.org/prep/maintain/html_node/Manuals-on-Web-Pages.html. | ||
| 34 | |||
| 35 | # For people editing this file: when a manual named foo is related to a | ||
| 36 | # package named bar, the url should contain a variable reference ${BAR}. | ||
| 37 | # Otherwise, the gnumaint scripts have no way of knowing they are | ||
| 38 | # associated, and thus gnu.org/manual can't include them. | ||
| 39 | |||
| 40 | # shorten references to manuals on www.gnu.org. | ||
| 41 | G = https://www.gnu.org | ||
| 42 | GS = ${G}/software | ||
| 43 | |||
| 44 | 3dldf mono ${GS}/3dldf/manual/user_ref/3DLDF.html | ||
| 45 | 3dldf node ${GS}/3dldf/manual/user_ref/ | ||
| 46 | |||
| 47 | alive mono ${GS}/alive/manual/alive.html | ||
| 48 | alive node ${GS}/alive/manual/html_node/ | ||
| 49 | |||
| 50 | anubis chapter ${GS}/anubis/manual/html_chapter/ | ||
| 51 | anubis section ${GS}/anubis/manual/html_section/ | ||
| 52 | anubis node ${GS}/anubis/manual/html_node/ | ||
| 53 | |||
| 54 | artanis mono ${GS}/artanis/manual/artanis.html | ||
| 55 | artanis node ${GS}/artanis/manual/html_node/ | ||
| 56 | |||
| 57 | aspell section http://aspell.net/man-html/index.html | ||
| 58 | |||
| 59 | auctex mono ${GS}/auctex/manual/auctex.html | ||
| 60 | auctex node ${GS}/auctex/manual/auctex/ | ||
| 61 | |||
| 62 | autoconf mono ${GS}/autoconf/manual/autoconf.html | ||
| 63 | autoconf node ${GS}/autoconf/manual/html_node/ | ||
| 64 | |||
| 65 | autogen mono ${GS}/autogen/manual/html_mono/autogen.html | ||
| 66 | autogen chapter ${GS}/autogen/manual/html_chapter/ | ||
| 67 | autogen node ${GS}/autoconf/manual/html_node/ | ||
| 68 | |||
| 69 | automake mono ${GS}/automake/manual/automake.html | ||
| 70 | automake node ${GS}/automake/manual/html_node/ | ||
| 71 | |||
| 72 | avl node http://www.stanford.edu/~blp/avl/libavl.html/ | ||
| 73 | |||
| 74 | bash mono ${GS}/bash/manual/bash.html | ||
| 75 | bash node ${GS}/bash/manual/html_node/ | ||
| 76 | |||
| 77 | BINUTILS = http://sourceware.org/binutils/docs | ||
| 78 | binutils node ${BINUTILS}/binutils/ | ||
| 79 | as node ${BINUTILS}/as/ | ||
| 80 | bfd node ${BINUTILS}/bfd/ | ||
| 81 | gprof node ${BINUTILS}/gprof/ | ||
| 82 | ld node ${BINUTILS}/ld/ | ||
| 83 | |||
| 84 | bison mono ${GS}/bison/manual/bison.html | ||
| 85 | bison node ${GS}/bison/manual/html_node/ | ||
| 86 | |||
| 87 | bpel2owfn mono ${GS}/bpel2owfn/manual/2.0.x/bpel2owfn.html | ||
| 88 | |||
| 89 | ccd2cue mono ${GS}/ccd2cue/manual/ccd2cue.html | ||
| 90 | ccd2cue node ${GS}/ccd2cue/manual/html_node/ | ||
| 91 | |||
| 92 | cflow mono ${GS}/cflow/manual/cflow.html | ||
| 93 | cflow node ${GS}/cflow/manual/html_node/ | ||
| 94 | |||
| 95 | chess mono ${GS}/chess/manual/gnuchess.html | ||
| 96 | chess node ${GS}/chess/manual/html_node/ | ||
| 97 | |||
| 98 | combine mono ${GS}/combine/manual/combine.html | ||
| 99 | combine chapter ${GS}/combine/manual/html_chapter/ | ||
| 100 | combine section ${GS}/combine/manual/html_section/ | ||
| 101 | combine node ${GS}/combine/manual/html_node/ | ||
| 102 | |||
| 103 | complexity mono ${GS}/complexity/manual/complexity.html | ||
| 104 | complexity node ${GS}/complexity/manual/html_node/ | ||
| 105 | |||
| 106 | coreutils mono ${GS}/coreutils/manual/coreutils | ||
| 107 | coreutils node ${GS}/coreutils/manual/html_node/ | ||
| 108 | |||
| 109 | cpio mono ${GS}/cpio/manual/cpio | ||
| 110 | cpio node ${GS}/cpio/manual/html_node/ | ||
| 111 | |||
| 112 | cssc node ${GS}/cssc/manual/ | ||
| 113 | |||
| 114 | #cvs cannot be handled here; see http://ximbiot.com/cvs/manual. | ||
| 115 | |||
| 116 | ddd mono ${GS}/ddd/manual/html_mono/ddd.html | ||
| 117 | |||
| 118 | ddrescue mono ${GS}/ddrescue/manual/ddrescue_manual.html | ||
| 119 | |||
| 120 | DICO = http://puszcza.gnu.org.ua/software/dico/manual | ||
| 121 | dico mono ${DICO}/dico.html | ||
| 122 | dico chapter ${DICO}/html_chapter/ | ||
| 123 | dico section ${DICO}/html_section/ | ||
| 124 | dico node ${DICO}/html_node/ | ||
| 125 | |||
| 126 | diffutils mono ${GS}/diffutils/manual/diffutils | ||
| 127 | diffutils node ${GS}/diffutils/manual/html_node/ | ||
| 128 | |||
| 129 | ed mono ${GS}/ed/manual/ed_manual.html | ||
| 130 | |||
| 131 | EMACS = ${GS}/emacs/manual | ||
| 132 | emacs mono ${EMACS}/html_mono/emacs.html | ||
| 133 | emacs node ${EMACS}/html_node/emacs/ | ||
| 134 | # | ||
| 135 | ada-mode mono ${EMACS}/html_mono/ada-mode.html | ||
| 136 | ada-mode node ${EMACS}/html_node/ada-mode/ | ||
| 137 | # | ||
| 138 | autotype mono ${EMACS}/html_mono/autotype.html | ||
| 139 | autotype node ${EMACS}/html_node/autotype/ | ||
| 140 | # | ||
| 141 | ccmode mono ${EMACS}/html_mono/ccmode.html | ||
| 142 | ccmode node ${EMACS}/html_node/ccmode/ | ||
| 143 | # | ||
| 144 | cl mono ${EMACS}/html_mono/cl.html | ||
| 145 | cl node ${EMACS}/html_node/cl/ | ||
| 146 | # | ||
| 147 | ebrowse mono ${EMACS}/html_mono/ebrowse.html | ||
| 148 | ebrowse node ${EMACS}/html_node/ebrowse/ | ||
| 149 | # | ||
| 150 | ediff mono ${EMACS}/html_mono/ediff.html | ||
| 151 | ediff node ${EMACS}/html_node/ediff/ | ||
| 152 | # | ||
| 153 | eieio mono ${EMACS}/html_mono/eieio.html | ||
| 154 | eieio node ${EMACS}/html_node/eieio/ | ||
| 155 | # | ||
| 156 | elisp mono ${EMACS}/html_mono/elisp.html | ||
| 157 | elisp node ${EMACS}/html_node/elisp/ | ||
| 158 | # | ||
| 159 | epa mono ${EMACS}/html_mono/epa.html | ||
| 160 | epa node ${EMACS}/html_node/epa/ | ||
| 161 | # | ||
| 162 | erc mono ${EMACS}/html_mono/erc.html | ||
| 163 | erc node ${EMACS}/html_node/erc/ | ||
| 164 | # | ||
| 165 | dired-x mono ${EMACS}/html_mono/dired-x.html | ||
| 166 | dired-x node ${EMACS}/html_node/dired-x/ | ||
| 167 | # | ||
| 168 | eshell mono ${EMACS}/html_mono/eshell.html | ||
| 169 | eshell node ${EMACS}/html_node/eshell/ | ||
| 170 | # | ||
| 171 | flymake mono ${EMACS}/html_mono/flymake.html | ||
| 172 | flymake node ${EMACS}/html_node/flymake/ | ||
| 173 | # | ||
| 174 | gnus mono ${EMACS}/html_mono/gnus.html | ||
| 175 | gnus node ${EMACS}/html_node/gnus/ | ||
| 176 | # | ||
| 177 | idlwave mono ${EMACS}/html_mono/idlwave.html | ||
| 178 | idlwave node ${EMACS}/html_node/idlwave/ | ||
| 179 | # | ||
| 180 | message mono ${EMACS}/html_mono/message.html | ||
| 181 | message node ${EMACS}/html_node/message/ | ||
| 182 | # | ||
| 183 | mh-e mono ${EMACS}/html_mono/mh-e.html | ||
| 184 | mh-e node ${EMACS}/html_node/mh-e/ | ||
| 185 | # | ||
| 186 | nxml-mode mono ${EMACS}/html_mono/nxml-mode.html | ||
| 187 | nxml-mode node ${EMACS}/html_node/nxml-mode/ | ||
| 188 | # | ||
| 189 | org mono ${EMACS}/html_mono/org.html | ||
| 190 | org node ${EMACS}/html_node/org/ | ||
| 191 | # | ||
| 192 | pcl-cvs mono ${EMACS}/html_mono/pcl-cvs.html | ||
| 193 | pcl-cvs node ${EMACS}/html_node/pcl-cvs/ | ||
| 194 | # | ||
| 195 | rcirc mono ${EMACS}/html_mono/rcirc.html | ||
| 196 | rcirc node ${EMACS}/html_node/rcirc/ | ||
| 197 | # | ||
| 198 | semantic mono ${EMACS}/html_mono/semantic.html | ||
| 199 | semantic node ${EMACS}/html_node/semantic/ | ||
| 200 | # | ||
| 201 | smtp mono ${EMACS}/html_mono/smtpmail.html | ||
| 202 | smtp node ${EMACS}/html_node/smtpmail/ | ||
| 203 | # | ||
| 204 | speedbar mono ${EMACS}/html_mono/speedbar.html | ||
| 205 | speedbar node ${EMACS}/html_node/speedbar/ | ||
| 206 | # | ||
| 207 | tramp mono ${EMACS}/html_mono/tramp.html | ||
| 208 | tramp node ${EMACS}/html_node/tramp/ | ||
| 209 | # | ||
| 210 | vip mono ${EMACS}/html_mono/vip.html | ||
| 211 | vip node ${EMACS}/html_node/vip/ | ||
| 212 | # | ||
| 213 | viper mono ${EMACS}/html_mono/viper.html | ||
| 214 | viper node ${EMACS}/html_node/viper/ | ||
| 215 | # | ||
| 216 | woman mono ${EMACS}/html_mono/woman.html | ||
| 217 | woman node ${EMACS}/html_node/woman/ | ||
| 218 | # (end emacs manuals) | ||
| 219 | |||
| 220 | easejs mono ${GS}/easejs/manual/easejs.html | ||
| 221 | easejs node ${GS}/easejs/manual/ | ||
| 222 | |||
| 223 | EMACS_GUIX = https://alezost.github.io/guix.el/manual/latest | ||
| 224 | emacs-guix mono ${EMACS_GUIX}/emacs-guix.html | ||
| 225 | emacs-guix node ${EMACS_GUIX}/html_node/ | ||
| 226 | |||
| 227 | emacs-muse node ${GS}/emacs-muse/manual/muse.html | ||
| 228 | emacs-muse node ${GS}/emacs-muse/manual/html_node/ | ||
| 229 | |||
| 230 | emms node ${GS}/emms/manual/ | ||
| 231 | |||
| 232 | # The file is called 'find.info' but the package is 'findutils'. | ||
| 233 | find mono ${GS}/findutils/manual/html_mono/find.html | ||
| 234 | find node ${GS}/findutils/manual/html_node/find_html | ||
| 235 | findutils mono ${GS}/findutils/manual/html_mono/find.html | ||
| 236 | findutils node ${GS}/findutils/manual/html_node/find_html | ||
| 237 | |||
| 238 | FLEX = http://flex.sourceforge.net | ||
| 239 | flex node ${FLEX}/manual/ | ||
| 240 | |||
| 241 | gama mono ${GS}/gama/manual/gama.html | ||
| 242 | gama node ${GS}/gama/manual/html_node/ | ||
| 243 | |||
| 244 | GAWK = ${GS}/gawk/manual | ||
| 245 | gawk mono ${GAWK}/gawk.html | ||
| 246 | gawk node ${GAWK}/html_node/ | ||
| 247 | gawkinet mono ${GAWK}/gawkinet/gawkinet.html | ||
| 248 | gawkinet node ${GAWK}/gawkinet/html_node/ | ||
| 249 | |||
| 250 | gcal mono ${GS}/gcal/manual/gcal.html | ||
| 251 | gcal node ${GS}/gcal/manual/html_node/ | ||
| 252 | |||
| 253 | GCC = http://gcc.gnu.org/onlinedocs | ||
| 254 | gcc node ${GCC}/gcc/ | ||
| 255 | cpp node ${GCC}/cpp/ | ||
| 256 | gcj node ${GCC}/gcj/ | ||
| 257 | gfortran node ${GCC}/gfortran/ | ||
| 258 | gnat_rm node ${GCC}/gnat_rm/ | ||
| 259 | gnat_ugn_unw node ${GCC}/gnat_ugn_unw/ | ||
| 260 | libgomp node ${GCC}/libgomp/ | ||
| 261 | libstdc++ node ${GCC}/libstdc++/ | ||
| 262 | # | ||
| 263 | gccint node ${GCC}/gccint/ | ||
| 264 | cppinternals node ${GCC}/cppinternals/ | ||
| 265 | gfc-internals node ${GCC}/gfc-internals/ | ||
| 266 | gnat-style node ${GCC}/gnat-style/ | ||
| 267 | libiberty node ${GCC}/libiberty/ | ||
| 268 | |||
| 269 | GDB = http://sourceware.org/gdb/current/onlinedocs | ||
| 270 | gdb node ${GDB}/gdb/ | ||
| 271 | stabs node ${GDB}/stabs/ | ||
| 272 | |||
| 273 | GDBM = http://www.gnu.org.ua/software/gdbm/manual | ||
| 274 | gdbm mono ${GDBM}/gdbm.html | ||
| 275 | gdbm chapter ${GDBM}/html_chapter/ | ||
| 276 | gdbm section ${GDBM}/html_section/ | ||
| 277 | gdbm node ${GDBM}/html_node/ | ||
| 278 | |||
| 279 | gettext mono ${GS}/gettext/manual/gettext.html | ||
| 280 | gettext node ${GS}/gettext/manual/html_node/ | ||
| 281 | |||
| 282 | gforth node http://www.complang.tuwien.ac.at/forth/gforth/Docs-html/ | ||
| 283 | |||
| 284 | global mono ${GS}/global/manual/global.html | ||
| 285 | |||
| 286 | gmediaserver node ${GS}/gmediaserver/manual/ | ||
| 287 | |||
| 288 | gmp node http://www.gmplib.org/manual/ | ||
| 289 | |||
| 290 | gnu-arch node ${GS}/gnu-arch/tutorial/ | ||
| 291 | |||
| 292 | gnu-c-manual mono ${GS}/gnu-c-manual/gnu-c-manual.html | ||
| 293 | |||
| 294 | gnu-crypto node ${GS}/gnu-crypto/manual/ | ||
| 295 | |||
| 296 | gnubg mono ${GS}/gnubg/manual/gnubg.html | ||
| 297 | gnubg node ${GS}/gnubg/manual/html_node/ | ||
| 298 | |||
| 299 | gnubik mono ${GS}/gnubik/manual/gnubik.html | ||
| 300 | gnubik node ${GS}/gnubik/manual/html_node/ | ||
| 301 | |||
| 302 | gnulib mono ${GS}/gnulib/manual/gnulib.html | ||
| 303 | gnulib node ${GS}/gnulib/manual/html_node/ | ||
| 304 | |||
| 305 | GNUN = ${GS}/trans-coord/manual | ||
| 306 | gnun mono ${GNUN}/gnun/gnun.html | ||
| 307 | gnun node ${GNUN}/gnun/html_node/ | ||
| 308 | web-trans mono ${GNUN}/web-trans/web-trans.html | ||
| 309 | web-trans node ${GNUN}/web-trans/html_node/ | ||
| 310 | |||
| 311 | GNUNET = https://docs.gnunet.org/manuals | ||
| 312 | gnunet node ${GNUNET}/gnunet/ | ||
| 313 | gnunet-c-tutorial node ${GNUNET}/gnunet-c-tutorial/ | ||
| 314 | gnunet-java-tutorial node ${GNUNET}/gnunet-java-tutorial/ | ||
| 315 | |||
| 316 | GNUPG = http://www.gnupg.org/documentation/manuals | ||
| 317 | gnupg node ${GNUPG}/gnupg/ | ||
| 318 | dirmngr node ${GNUPG}/dirmngr/ | ||
| 319 | gcrypt node ${GNUPG}/gcrypt/ | ||
| 320 | libgcrypt node ${GNUPG}/gcrypt/ | ||
| 321 | ksba node ${GNUPG}/ksba/ | ||
| 322 | assuan node ${GNUPG}/assuan/ | ||
| 323 | gpgme node ${GNUPG}/gpgme/ | ||
| 324 | |||
| 325 | gnuprologjava node ${GS}/gnuprologjava/manual/ | ||
| 326 | |||
| 327 | gnuschool mono ${GS}/gnuschool/gnuschool.html | ||
| 328 | |||
| 329 | GNUSTANDARDS = ${G}/prep | ||
| 330 | maintain mono ${GNUSTANDARDS}/maintain/maintain.html | ||
| 331 | maintain node ${GNUSTANDARDS}/maintain/html_node/ | ||
| 332 | # | ||
| 333 | standards mono ${GNUSTANDARDS}/standards/standards.html | ||
| 334 | standards node ${GNUSTANDARDS}/standards/html_node/ | ||
| 335 | |||
| 336 | gnutls mono http://gnutls.org/manual/gnutls.html | ||
| 337 | gnutls node http://gnutls.org/manual/html_node/ | ||
| 338 | |||
| 339 | gnutls-guile mono http://gnutls.org/manual/gnutls-guile.html | ||
| 340 | gnutls-guile node http://gnutls.org/manual/gnutls-guile/ | ||
| 341 | |||
| 342 | gperf mono ${GS}/gperf/manual/gperf.html | ||
| 343 | gperf node ${GS}/gperf/manual/html_node/ | ||
| 344 | |||
| 345 | grep mono ${GS}/grep/manual/grep.html | ||
| 346 | grep node ${GS}/grep/manual/html_node/ | ||
| 347 | |||
| 348 | groff node ${GS}/groff/manual/html_node/ | ||
| 349 | |||
| 350 | GRUB = ${GS}/grub/manual | ||
| 351 | grub mono ${GRUB}/grub.html | ||
| 352 | grub node ${GRUB}/html_node/ | ||
| 353 | # | ||
| 354 | multiboot mono ${GRUB}/multiboot/multiboot.html | ||
| 355 | multiboot node ${GRUB}/multiboot/html_node/ | ||
| 356 | |||
| 357 | gsasl mono ${GS}/gsasl/manual/gsasl.html | ||
| 358 | gsasl node ${GS}/gsasl/manual/html_node/ | ||
| 359 | |||
| 360 | gsl node ${GS}/gsl/manual/html_node/ | ||
| 361 | |||
| 362 | gsrc mono ${GS}/gsrc/manual/gsrc.html | ||
| 363 | gsrc node ${GS}/gsrc/manual/html_node/ | ||
| 364 | |||
| 365 | gss mono ${GS}/gss/manual/gss.html | ||
| 366 | gss node ${GS}/gss/manual/html_node/ | ||
| 367 | |||
| 368 | gtypist mono ${GS}/gtypist/doc/ | ||
| 369 | |||
| 370 | guile mono ${GS}/guile/manual/guile.html | ||
| 371 | guile node ${GS}/guile/manual/html_node/ | ||
| 372 | |||
| 373 | guile-avahi mono http://nongnu.org/guile-avahi/doc/guile-avahi.html | ||
| 374 | |||
| 375 | GUILE_GNOME = ${GS}/guile-gnome/docs | ||
| 376 | gobject node ${GUILE_GNOME}/gobject/html/ | ||
| 377 | glib node ${GUILE_GNOME}/glib/html/ | ||
| 378 | atk node ${GUILE_GNOME}/atk/html/ | ||
| 379 | pango node ${GUILE_GNOME}/pango/html/ | ||
| 380 | pangocairo node ${GUILE_GNOME}/pangocairo/html/ | ||
| 381 | gdk node ${GUILE_GNOME}/gdk/html/ | ||
| 382 | gtk node ${GUILE_GNOME}/gtk/html/ | ||
| 383 | libglade node ${GUILE_GNOME}/libglade/html/ | ||
| 384 | gnome-vfs node ${GUILE_GNOME}/gnome-vfs/html/ | ||
| 385 | libgnomecanvas node ${GUILE_GNOME}/libgnomecanvas/html/ | ||
| 386 | gconf node ${GUILE_GNOME}/gconf/html/ | ||
| 387 | libgnome node ${GUILE_GNOME}/libgnome/html/ | ||
| 388 | libgnomeui node ${GUILE_GNOME}/libgnomeui/html/ | ||
| 389 | corba node ${GUILE_GNOME}/corba/html/ | ||
| 390 | clutter node ${GUILE_GNOME}/clutter/html/ | ||
| 391 | clutter-glx node ${GUILE_GNOME}/clutter-glx/html/ | ||
| 392 | |||
| 393 | guile-gtk node ${GS}/guile-gtk/docs/guile-gtk/ | ||
| 394 | |||
| 395 | guile-rpc mono ${GS}/guile-rpc/manual/guile-rpc.html | ||
| 396 | guile-rpc node ${GS}/guile-rpc/manual/html_node/ | ||
| 397 | |||
| 398 | guix mono ${GS}/guix/manual/guix.html | ||
| 399 | guix node ${GS}/guix/manual/html_node/ | ||
| 400 | |||
| 401 | gv mono ${GS}/gv/manual/gv.html | ||
| 402 | gv node ${GS}/gv/manual/html_node/ | ||
| 403 | |||
| 404 | gzip mono ${GS}/gzip/manual/gzip.html | ||
| 405 | gzip node ${GS}/gzip/manual/html_node/ | ||
| 406 | |||
| 407 | hello mono ${GS}/hello/manual/hello.html | ||
| 408 | hello node ${GS}/hello/manual/html_node/ | ||
| 409 | |||
| 410 | help2man mono ${GS}/help2man/help2man.html | ||
| 411 | |||
| 412 | idutils mono ${GS}/idutils/manual/idutils.html | ||
| 413 | idutils node ${GS}/idutils/manual/html_node/ | ||
| 414 | |||
| 415 | inetutils mono ${GS}/inetutils/manual/inetutils.html | ||
| 416 | inetutils node ${GS}/inetutils/manual/html_node/ | ||
| 417 | |||
| 418 | jwhois mono ${GS}/jwhois/manual/jwhois.html | ||
| 419 | jwhois node ${GS}/jwhois/manual/html_node/ | ||
| 420 | |||
| 421 | libc mono ${GS}/libc/manual/html_mono/libc.html | ||
| 422 | libc node ${GS}/libc/manual/html_node/ | ||
| 423 | |||
| 424 | LIBCDIO = ${GS}/libcdio | ||
| 425 | libcdio mono ${LIBCDIO}/libcdio.html | ||
| 426 | cd-text mono ${LIBCDIO}/cd-text-format.html | ||
| 427 | |||
| 428 | libextractor mono ${GS}/libextractor/manual/libextractor.html | ||
| 429 | libextractor node ${GS}/libextractor/manual/html_node/ | ||
| 430 | |||
| 431 | libidn mono ${GS}/libidn/manual/libidn.html | ||
| 432 | libidn node ${GS}/libidn/manual/html_node/ | ||
| 433 | |||
| 434 | librejs mono ${GS}/librejs/manual/librejs.html | ||
| 435 | librejs node ${GS}/librejs/manual/html_node/ | ||
| 436 | |||
| 437 | libmatheval mono ${GS}/libmatheval/manual/libmatheval.html | ||
| 438 | |||
| 439 | LIBMICROHTTPD = ${GS}/libmicrohttpd | ||
| 440 | libmicrohttpd mono ${LIBMICROHTTPD}/manual/libmicrohttpd.html | ||
| 441 | libmicrohttpd node ${LIBMICROHTTPD}/manual/html_node/ | ||
| 442 | microhttpd-tutorial mono ${LIBMICROHTTPD}/tutorial.html | ||
| 443 | |||
| 444 | libtasn1 mono ${GS}/libtasn1/manual/libtasn1.html | ||
| 445 | libtasn1 node ${GS}/libtasn1/manual/html_node/ | ||
| 446 | |||
| 447 | libtool mono ${GS}/libtool/manual/libtool.html | ||
| 448 | libtool node ${GS}/libtool/manual/html_node/ | ||
| 449 | |||
| 450 | lightning mono ${GS}/lightning/manual/lightning.html | ||
| 451 | lightning node ${GS}/lightning/manual/html_node/ | ||
| 452 | |||
| 453 | # The stable/ url redirects immediately, but that's ok. | ||
| 454 | # The .html extension is omitted on their web site, but it works if given. | ||
| 455 | LILYPOND = http://lilypond.org/doc/stable/Documentation | ||
| 456 | lilypond-internals node ${LILYPOND}/internals/ | ||
| 457 | lilypond-learning node ${LILYPOND}/learning/ | ||
| 458 | lilypond-notation node ${LILYPOND}/notation/ | ||
| 459 | lilypond-snippets node ${LILYPOND}/snippets/ | ||
| 460 | lilypond-usage node ${LILYPOND}/usage/ | ||
| 461 | lilypond-web node ${LILYPOND}/web/ | ||
| 462 | music-glossary node ${LILYPOND}/music-glossary/ | ||
| 463 | |||
| 464 | liquidwar6 mono ${GS}/liquidwar6/manual/liquidwar6.html | ||
| 465 | liquidwar6 node ${GS}/liquidwar6/manual/html_node/ | ||
| 466 | |||
| 467 | lispintro mono ${GS}/emacs/emacs-lisp-intro/html_mono/emacs-lisp-intro.html | ||
| 468 | lispintro node ${GS}/emacs/emacs-lisp-intro/html_node/index.html | ||
| 469 | |||
| 470 | LSH = http://www.lysator.liu.se/~nisse/lsh | ||
| 471 | lsh mono ${LSH}/lsh.html | ||
| 472 | |||
| 473 | m4 mono ${GS}/m4/manual/m4.html | ||
| 474 | m4 node ${GS}/m4/manual/html_node/ | ||
| 475 | |||
| 476 | mailutils mono ${GS}/mailutils/manual/mailutils.html | ||
| 477 | mailutils chapter ${GS}/mailutils/manual/html_chapter/ | ||
| 478 | mailutils section ${GS}/mailutils/manual/html_section/ | ||
| 479 | mailutils node ${GS}/mailutils/manual/html_node/ | ||
| 480 | |||
| 481 | make mono ${GS}/make/manual/make.html | ||
| 482 | make node ${GS}/make/manual/html_node/ | ||
| 483 | |||
| 484 | mcron mono ${GS}/mcron/manual/mcron.html | ||
| 485 | mcron node ${GS}/mcron/manual/html_node/ | ||
| 486 | |||
| 487 | mdk mono ${GS}/mdk/manual/mdk.html | ||
| 488 | mdk node ${GS}/mdk/manual/html_node/ | ||
| 489 | |||
| 490 | METAEXCHANGE = http://ftp.gwdg.de/pub/gnu2/iwfmdh/doc/texinfo | ||
| 491 | iwf_mh node ${METAEXCHANGE}/iwf_mh.html | ||
| 492 | scantest node ${METAEXCHANGE}/scantest.html | ||
| 493 | |||
| 494 | MIT_SCHEME = ${GS}/mit-scheme/documentation | ||
| 495 | mit-scheme-ref node ${MIT_SCHEME}/mit-scheme-ref/ | ||
| 496 | mit-scheme-user node ${MIT_SCHEME}/mit-scheme-user/ | ||
| 497 | sos node ${MIT_SCHEME}/mit-scheme-sos/ | ||
| 498 | mit-scheme-imail node ${MIT_SCHEME}/mit-scheme-imail/ | ||
| 499 | |||
| 500 | moe mono ${GS}/moe/manual/moe_manual.html | ||
| 501 | |||
| 502 | motti node ${GS}/motti/manual/ | ||
| 503 | |||
| 504 | mpc node http://www.multiprecision.org/index.php?prog=mpc&page=html | ||
| 505 | |||
| 506 | mpfr mono http://www.mpfr.org/mpfr-current/mpfr.html | ||
| 507 | |||
| 508 | mtools mono ${GS}/mtools/manual/mtools.html | ||
| 509 | |||
| 510 | myserver node http://www.myserverproject.net/documentation/ | ||
| 511 | |||
| 512 | nano mono http://www.nano-editor.org/dist/latest/nano.html | ||
| 513 | |||
| 514 | nettle chapter http://www.lysator.liu.se/~nisse/nettle/nettle.html | ||
| 515 | |||
| 516 | ocrad mono ${GS}/ocrad/manual/ocrad_manual.html | ||
| 517 | |||
| 518 | parted mono ${GS}/parted/manual/parted.html | ||
| 519 | parted node ${GS}/parted/manual/html_node/ | ||
| 520 | |||
| 521 | pascal mono http://www.gnu-pascal.de/gpc/ | ||
| 522 | |||
| 523 | # can't use pcb since url's contain dates --30nov10 | ||
| 524 | |||
| 525 | perl mono ${GS}/perl/manual/perldoc-all.html | ||
| 526 | |||
| 527 | PIES = http://www.gnu.org.ua/software/pies/manual | ||
| 528 | pies mono ${PIES}/pies.html | ||
| 529 | pies chapter ${PIES}/html_chapter/ | ||
| 530 | pies section ${PIES}/html_section/ | ||
| 531 | pies node ${PIES}/html_node/ | ||
| 532 | |||
| 533 | plotutils mono ${GS}/plotutils/manual/en/plotutils.html | ||
| 534 | plotutils node ${GS}/plotutils/manual/en/html_node/ | ||
| 535 | |||
| 536 | proxyknife mono ${GS}/proxyknife/manual/proxyknife.html | ||
| 537 | proxyknife node ${GS}/proxyknife/manual/html_node/ | ||
| 538 | |||
| 539 | pspp mono ${GS}/pspp/manual/pspp.html | ||
| 540 | pspp node ${GS}/pspp/manual/html_node/ | ||
| 541 | |||
| 542 | pyconfigure mono ${GS}/pyconfigure/manual/pyconfigure.html | ||
| 543 | pyconfigure node ${GS}/pyconfigure/manual/html_node/ | ||
| 544 | |||
| 545 | R = http://cran.r-project.org/doc/manuals | ||
| 546 | R-intro mono ${R}/R-intro.html | ||
| 547 | R-lang mono ${R}/R-lang.html | ||
| 548 | R-exts mono ${R}/R-exts.html | ||
| 549 | R-data mono ${R}/R-data.html | ||
| 550 | R-admin mono ${R}/R-admin.html | ||
| 551 | R-ints mono ${R}/R-ints.html | ||
| 552 | |||
| 553 | rcs mono ${GS}/rcs/manual/rcs.html | ||
| 554 | rcs node ${GS}/rcs/manual/html_node/ | ||
| 555 | |||
| 556 | READLINE = http://cnswww.cns.cwru.edu/php/chet/readline | ||
| 557 | readline mono ${READLINE}/readline.html | ||
| 558 | rluserman mono ${READLINE}/rluserman.html | ||
| 559 | history mono ${READLINE}/history.html | ||
| 560 | |||
| 561 | recode mono http://recode.progiciels-bpi.ca/manual/index.html | ||
| 562 | |||
| 563 | recutils mono ${GS}/recutils/manual/recutils.html | ||
| 564 | recutils node ${GS}/recutils/manual/html_node/ | ||
| 565 | |||
| 566 | reftex mono ${GS}/auctex/manual/reftex.html | ||
| 567 | reftex node ${GS}/auctex/manual/reftex/ | ||
| 568 | |||
| 569 | remotecontrol mono ${GS}/remotecontrol/manual/remotecontrol.html | ||
| 570 | remotecontrol node ${GS}/remotecontrol/manual/html_node/ | ||
| 571 | |||
| 572 | rottlog mono ${GS}/rottlog/manual/rottlog.html | ||
| 573 | rottlog node ${GS}/rottlog/manual/html_node/ | ||
| 574 | |||
| 575 | RUSH = http://www.gnu.org.ua/software/rush/manual | ||
| 576 | rush mono ${RUSH}/rush.html | ||
| 577 | rush chapter ${RUSH}/html_chapter/ | ||
| 578 | rush section ${RUSH}/html_section/ | ||
| 579 | rush node ${RUSH}/html_node/ | ||
| 580 | |||
| 581 | screen mono ${GS}/screen/manual/screen.html | ||
| 582 | screen node ${GS}/screen/manual/html_node/ | ||
| 583 | |||
| 584 | sed mono ${GS}/sed/manual/sed.html | ||
| 585 | sed node ${GS}/sed/manual/html_node/ | ||
| 586 | |||
| 587 | sharutils mono ${GS}/sharutils/manual/html_mono/sharutils.html | ||
| 588 | sharutils chapter ${GS}/sharutils/manual/html_chapter/ | ||
| 589 | sharutils node ${GS}/sharutils/manual/html_node/ | ||
| 590 | |||
| 591 | shepherd mono ${GS}/shepherd/manual/shepherd.html | ||
| 592 | shepherd node ${GS}/shepherd/manual/html_node/ | ||
| 593 | |||
| 594 | # can't use mono files since they have generic names | ||
| 595 | SMALLTALK = ${GS}/smalltalk | ||
| 596 | smalltalk node ${SMALLTALK}/manual/html_node/ | ||
| 597 | smalltalk-base node ${SMALLTALK}/manual-base/html_node/ | ||
| 598 | smalltalk-libs node ${SMALLTALK}/manual-libs/html_node/ | ||
| 599 | |||
| 600 | sourceinstall mono ${GS}/sourceinstall/manual/sourceinstall.html | ||
| 601 | sourceinstall node ${GS}/sourceinstall/manual/html_node/ | ||
| 602 | |||
| 603 | sqltutor mono ${GS}/sqltutor/manual/sqltutor.html | ||
| 604 | sqltutor node ${GS}/sqltutor/manual/html_node/ | ||
| 605 | |||
| 606 | src-highlite mono ${GS}/src-highlite/source-highlight.html | ||
| 607 | |||
| 608 | swbis mono ${GS}/swbis/manual.html | ||
| 609 | |||
| 610 | tar mono ${GS}/tar/manual/tar.html | ||
| 611 | tar chapter ${GS}/tar/manual/html_chapter/ | ||
| 612 | tar section ${GS}/tar/manual/html_section/ | ||
| 613 | tar node ${GS}/autoconf/manual/html_node/ | ||
| 614 | |||
| 615 | teseq mono ${GS}/teseq/teseq.html | ||
| 616 | teseq node ${GS}/teseq/html_node/ | ||
| 617 | |||
| 618 | TEXINFO = ${GS}/texinfo/manual | ||
| 619 | texinfo mono ${TEXINFO}/texinfo/texinfo.html | ||
| 620 | texinfo node ${TEXINFO}/texinfo/html_node/ | ||
| 621 | # | ||
| 622 | info mono ${TEXINFO}/info/info.html | ||
| 623 | info node ${TEXINFO}/info/html_node/ | ||
| 624 | # | ||
| 625 | info-stnd mono ${TEXINFO}/info-stnd/info-stnd.html | ||
| 626 | info-stnd node ${TEXINFO}/info-stnd/html_node/ | ||
| 627 | |||
| 628 | thales node ${GS}/thales/manual/ | ||
| 629 | |||
| 630 | units mono ${GS}/units/manual/units.html | ||
| 631 | units node ${GS}/units/manual/html_node/ | ||
| 632 | |||
| 633 | vc-dwim mono ${GS}/vc-dwim/manual/vc-dwim.html | ||
| 634 | vc-dwim node ${GS}/vc-dwim/manual/html_node/ | ||
| 635 | |||
| 636 | wdiff mono ${GS}/wdiff/manual/wdiff.html | ||
| 637 | wdiff node ${GS}/wdiff/manual/html_node/ | ||
| 638 | |||
| 639 | websocket4j mono ${GS}/websocket4j/manual/websocket4j.html | ||
| 640 | websocket4j node ${GS}/websocket4j/manual/html_node/ | ||
| 641 | |||
| 642 | wget mono ${GS}/wget/manual/wget.html | ||
| 643 | wget node ${GS}/wget/manual/html_node/ | ||
| 644 | |||
| 645 | xboard mono ${GS}/xboard/manual/xboard.html | ||
| 646 | xboard node ${GS}/xboard/manual/html_node/ | ||
| 647 | |||
| 648 | # emacs-page | ||
| 649 | # Free TeX-related Texinfo manuals on tug.org. | ||
| 650 | |||
| 651 | T = http://tug.org/texinfohtml | ||
| 652 | |||
| 653 | dvipng mono ${T}/dvipng.html | ||
| 654 | dvips mono ${T}/dvips.html | ||
| 655 | eplain mono ${T}/eplain.html | ||
| 656 | kpathsea mono ${T}/kpathsea.html | ||
| 657 | latex2e mono ${T}/latex2e.html | ||
| 658 | tlbuild mono ${T}/tlbuild.html | ||
| 659 | web2c mono ${T}/web2c.html | ||
| 660 | |||
| 661 | |||
| 662 | # Local Variables: | ||
| 663 | # eval: (add-hook 'write-file-hooks 'time-stamp) | ||
| 664 | # time-stamp-start: "htmlxrefversion=" | ||
| 665 | # time-stamp-format: "%:y-%02m-%02d.%02H" | ||
| 666 | # time-stamp-time-zone: "UTC" | ||
| 667 | # time-stamp-end: "; # UTC" | ||
| 668 | # End: | ||
diff --git a/doc/documentation/images/daemon_lego_block.png b/doc/documentation/images/daemon_lego_block.png deleted file mode 100644 index 5a088b532..000000000 --- a/doc/documentation/images/daemon_lego_block.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/daemon_lego_block.svg b/doc/documentation/images/daemon_lego_block.svg deleted file mode 100644 index 38ad90d13..000000000 --- a/doc/documentation/images/daemon_lego_block.svg +++ /dev/null | |||
| @@ -1,126 +0,0 @@ | |||
| 1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?> | ||
| 2 | <!-- Created with Inkscape (http://www.inkscape.org/) --> | ||
| 3 | |||
| 4 | <svg | ||
| 5 | xmlns:dc="http://purl.org/dc/elements/1.1/" | ||
| 6 | xmlns:cc="http://creativecommons.org/ns#" | ||
| 7 | xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" | ||
| 8 | xmlns:svg="http://www.w3.org/2000/svg" | ||
| 9 | xmlns="http://www.w3.org/2000/svg" | ||
| 10 | xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" | ||
| 11 | xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" | ||
| 12 | width="744.09448819" | ||
| 13 | height="1052.3622047" | ||
| 14 | id="svg6781" | ||
| 15 | version="1.1" | ||
| 16 | inkscape:version="0.48.2 r9819" | ||
| 17 | sodipodi:docname="New document 58"> | ||
| 18 | <defs | ||
| 19 | id="defs6783" /> | ||
| 20 | <sodipodi:namedview | ||
| 21 | id="base" | ||
| 22 | pagecolor="#ffffff" | ||
| 23 | bordercolor="#666666" | ||
| 24 | borderopacity="1.0" | ||
| 25 | inkscape:pageopacity="0.0" | ||
| 26 | inkscape:pageshadow="2" | ||
| 27 | inkscape:zoom="0.35" | ||
| 28 | inkscape:cx="375" | ||
| 29 | inkscape:cy="520" | ||
| 30 | inkscape:document-units="px" | ||
| 31 | inkscape:current-layer="layer1" | ||
| 32 | showgrid="false" | ||
| 33 | inkscape:window-width="1366" | ||
| 34 | inkscape:window-height="721" | ||
| 35 | inkscape:window-x="-2" | ||
| 36 | inkscape:window-y="-3" | ||
| 37 | inkscape:window-maximized="1" /> | ||
| 38 | <metadata | ||
| 39 | id="metadata6786"> | ||
| 40 | <rdf:RDF> | ||
| 41 | <cc:Work | ||
| 42 | rdf:about=""> | ||
| 43 | <dc:format>image/svg+xml</dc:format> | ||
| 44 | <dc:type | ||
| 45 | rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> | ||
| 46 | <dc:title></dc:title> | ||
| 47 | </cc:Work> | ||
| 48 | </rdf:RDF> | ||
| 49 | </metadata> | ||
| 50 | <g | ||
| 51 | inkscape:label="Layer 1" | ||
| 52 | inkscape:groupmode="layer" | ||
| 53 | id="layer1"> | ||
| 54 | <g | ||
| 55 | transform="translate(-4.5298577,-148.04661)" | ||
| 56 | id="g6746"> | ||
| 57 | <path | ||
| 58 | style="fill:#5fd38d;fill-opacity:1;stroke:#faf6a2;stroke-width:1.99014676;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 59 | d="m 183.84284,595.7683 350.8064,0 0,202.04036 -350.8064,0 z" | ||
| 60 | id="path6693" | ||
| 61 | inkscape:connector-curvature="0" /> | ||
| 62 | <rect | ||
| 63 | style="fill:#ffffff;fill-opacity:1;stroke:#faf6a2;stroke-width:2.22747946;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 64 | id="rect6695" | ||
| 65 | width="66.670067" | ||
| 66 | height="75.18058" | ||
| 67 | x="223.74881" | ||
| 68 | y="737.19458" /> | ||
| 69 | <rect | ||
| 70 | y="737.19458" | ||
| 71 | x="331.83514" | ||
| 72 | height="67.323441" | ||
| 73 | width="66.670067" | ||
| 74 | id="rect6697" | ||
| 75 | style="fill:#ffffff;fill-opacity:1;stroke:#faf6a2;stroke-width:2.10787106;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 76 | <rect | ||
| 77 | style="fill:#ffffff;fill-opacity:1;stroke:#faf6a2;stroke-width:2.06117821;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 78 | id="rect6699" | ||
| 79 | width="66.670067" | ||
| 80 | height="64.373825" | ||
| 81 | x="434.8707" | ||
| 82 | y="737.19458" /> | ||
| 83 | <path | ||
| 84 | style="fill:#37c871;fill-opacity:1;stroke:#faf6a2;stroke-width:0.98368376;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 85 | d="m 223.60976,736.21851 67.23534,0.38374 0,23.63648 -67.23534,37.13818 z" | ||
| 86 | id="path6701" | ||
| 87 | inkscape:connector-curvature="0" | ||
| 88 | sodipodi:nodetypes="ccccc" /> | ||
| 89 | <path | ||
| 90 | sodipodi:nodetypes="ccccc" | ||
| 91 | inkscape:connector-curvature="0" | ||
| 92 | id="path6703" | ||
| 93 | d="m 331.69608,736.21851 67.23534,0.3894 0,23.98466 -67.23534,37.68524 z" | ||
| 94 | style="fill:#37c871;fill-opacity:1;stroke:#faf6a2;stroke-width:0.99090236;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 95 | <path | ||
| 96 | style="fill:#37c871;fill-opacity:1;stroke:#faf6a2;stroke-width:0.98368376;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 97 | d="m 434.73164,736.21851 67.23534,0.38374 0,23.63648 -67.23534,37.13818 z" | ||
| 98 | id="path6705" | ||
| 99 | inkscape:connector-curvature="0" | ||
| 100 | sodipodi:nodetypes="ccccc" /> | ||
| 101 | <path | ||
| 102 | style="fill:#37c871;fill-opacity:1;stroke:#faf6a2;stroke-width:1.92068994;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 103 | d="m 533.72659,595.02309 56.12366,-29.34622 -1.01015,190.24271 -55.11351,41.45733 z" | ||
| 104 | id="path6707" | ||
| 105 | inkscape:connector-curvature="0" | ||
| 106 | sodipodi:nodetypes="ccccc" /> | ||
| 107 | <path | ||
| 108 | style="fill:#37c871;fill-opacity:1;stroke:#faf6a2;stroke-width:1.99424875;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 109 | d="m 245.46708,566.47881 345.46203,-1.01015 -56.56854,31.31472 -349.50264,-1.01014 z" | ||
| 110 | id="path6709" | ||
| 111 | inkscape:connector-curvature="0" | ||
| 112 | sodipodi:nodetypes="ccccc" /> | ||
| 113 | <text | ||
| 114 | sodipodi:linespacing="125%" | ||
| 115 | id="text6715" | ||
| 116 | y="677.59558" | ||
| 117 | x="234.35539" | ||
| 118 | style="font-size:36px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 119 | xml:space="preserve"><tspan | ||
| 120 | y="677.59558" | ||
| 121 | x="234.35539" | ||
| 122 | id="tspan6717" | ||
| 123 | sodipodi:role="line">User Interface</tspan></text> | ||
| 124 | </g> | ||
| 125 | </g> | ||
| 126 | </svg> | ||
diff --git a/doc/documentation/images/gns.dot b/doc/documentation/images/gns.dot deleted file mode 100644 index 55b05d482..000000000 --- a/doc/documentation/images/gns.dot +++ /dev/null | |||
| @@ -1,42 +0,0 @@ | |||
| 1 | // house = interface towards application | ||
| 2 | // circle (default) = storage | ||
| 3 | // diamond = stateless tool | ||
| 4 | // box = legacy system | ||
| 5 | |||
| 6 | // this is what we have...o | ||
| 7 | digraph dataflow { | ||
| 8 | splines = true; | ||
| 9 | |||
| 10 | DNS [shape="box"]; | ||
| 11 | import [label="gnunet-zoneimport", shape="diamond"]; | ||
| 12 | namestore; | ||
| 13 | namecache; | ||
| 14 | gns [shape="diamond"]; | ||
| 15 | dns2gns [shape="house"]; | ||
| 16 | cmdline [label="gnunet-gns", shape="house"]; | ||
| 17 | libnss_gns [shape="house"]; | ||
| 18 | proxy [label="gnunet-gns-proxy", shape="house"]; | ||
| 19 | dht; | ||
| 20 | zonemaster [shape="diamond"]; | ||
| 21 | |||
| 22 | DNS -> import [label="import"]; | ||
| 23 | import -> namestore [label="export"]; | ||
| 24 | |||
| 25 | namestore -> zonemaster [label="notifies"]; | ||
| 26 | zonemaster -> dht [label="publishes"]; | ||
| 27 | |||
| 28 | namestore -> namecache [label="pre-populates"]; | ||
| 29 | |||
| 30 | |||
| 31 | |||
| 32 | libnss_gns -> cmdline [label="invokes"]; | ||
| 33 | cmdline -> gns [label="lookup"]; | ||
| 34 | |||
| 35 | dns2gns -> gns [label="lookup"]; | ||
| 36 | |||
| 37 | proxy -> gns [label="lookup"]; | ||
| 38 | |||
| 39 | gns -> namecache [label="uses"]; | ||
| 40 | gns -> dht [label="queries"]; | ||
| 41 | |||
| 42 | } | ||
diff --git a/doc/documentation/images/gns.eps b/doc/documentation/images/gns.eps deleted file mode 100644 index 3f3c28d98..000000000 --- a/doc/documentation/images/gns.eps +++ /dev/null | |||
| @@ -1,585 +0,0 @@ | |||
| 1 | %!PS-Adobe-3.0 EPSF-3.0 | ||
| 2 | %%Creator: graphviz version 2.40.1 (20161225.0304) | ||
| 3 | %%Title: dataflow | ||
| 4 | %%Pages: 1 | ||
| 5 | %%BoundingBox: 36 36 722 428 | ||
| 6 | %%EndComments | ||
| 7 | save | ||
| 8 | %%BeginProlog | ||
| 9 | /DotDict 200 dict def | ||
| 10 | DotDict begin | ||
| 11 | |||
| 12 | /setupLatin1 { | ||
| 13 | mark | ||
| 14 | /EncodingVector 256 array def | ||
| 15 | EncodingVector 0 | ||
| 16 | |||
| 17 | ISOLatin1Encoding 0 255 getinterval putinterval | ||
| 18 | EncodingVector 45 /hyphen put | ||
| 19 | |||
| 20 | % Set up ISO Latin 1 character encoding | ||
| 21 | /starnetISO { | ||
| 22 | dup dup findfont dup length dict begin | ||
| 23 | { 1 index /FID ne { def }{ pop pop } ifelse | ||
| 24 | } forall | ||
| 25 | /Encoding EncodingVector def | ||
| 26 | currentdict end definefont | ||
| 27 | } def | ||
| 28 | /Times-Roman starnetISO def | ||
| 29 | /Times-Italic starnetISO def | ||
| 30 | /Times-Bold starnetISO def | ||
| 31 | /Times-BoldItalic starnetISO def | ||
| 32 | /Helvetica starnetISO def | ||
| 33 | /Helvetica-Oblique starnetISO def | ||
| 34 | /Helvetica-Bold starnetISO def | ||
| 35 | /Helvetica-BoldOblique starnetISO def | ||
| 36 | /Courier starnetISO def | ||
| 37 | /Courier-Oblique starnetISO def | ||
| 38 | /Courier-Bold starnetISO def | ||
| 39 | /Courier-BoldOblique starnetISO def | ||
| 40 | cleartomark | ||
| 41 | } bind def | ||
| 42 | |||
| 43 | %%BeginResource: procset graphviz 0 0 | ||
| 44 | /coord-font-family /Times-Roman def | ||
| 45 | /default-font-family /Times-Roman def | ||
| 46 | /coordfont coord-font-family findfont 8 scalefont def | ||
| 47 | |||
| 48 | /InvScaleFactor 1.0 def | ||
| 49 | /set_scale { | ||
| 50 | dup 1 exch div /InvScaleFactor exch def | ||
| 51 | scale | ||
| 52 | } bind def | ||
| 53 | |||
| 54 | % styles | ||
| 55 | /solid { [] 0 setdash } bind def | ||
| 56 | /dashed { [9 InvScaleFactor mul dup ] 0 setdash } bind def | ||
| 57 | /dotted { [1 InvScaleFactor mul 6 InvScaleFactor mul] 0 setdash } bind def | ||
| 58 | /invis {/fill {newpath} def /stroke {newpath} def /show {pop newpath} def} bind def | ||
| 59 | /bold { 2 setlinewidth } bind def | ||
| 60 | /filled { } bind def | ||
| 61 | /unfilled { } bind def | ||
| 62 | /rounded { } bind def | ||
| 63 | /diagonals { } bind def | ||
| 64 | /tapered { } bind def | ||
| 65 | |||
| 66 | % hooks for setting color | ||
| 67 | /nodecolor { sethsbcolor } bind def | ||
| 68 | /edgecolor { sethsbcolor } bind def | ||
| 69 | /graphcolor { sethsbcolor } bind def | ||
| 70 | /nopcolor {pop pop pop} bind def | ||
| 71 | |||
| 72 | /beginpage { % i j npages | ||
| 73 | /npages exch def | ||
| 74 | /j exch def | ||
| 75 | /i exch def | ||
| 76 | /str 10 string def | ||
| 77 | npages 1 gt { | ||
| 78 | gsave | ||
| 79 | coordfont setfont | ||
| 80 | 0 0 moveto | ||
| 81 | (\() show i str cvs show (,) show j str cvs show (\)) show | ||
| 82 | grestore | ||
| 83 | } if | ||
| 84 | } bind def | ||
| 85 | |||
| 86 | /set_font { | ||
| 87 | findfont exch | ||
| 88 | scalefont setfont | ||
| 89 | } def | ||
| 90 | |||
| 91 | % draw text fitted to its expected width | ||
| 92 | /alignedtext { % width text | ||
| 93 | /text exch def | ||
| 94 | /width exch def | ||
| 95 | gsave | ||
| 96 | width 0 gt { | ||
| 97 | [] 0 setdash | ||
| 98 | text stringwidth pop width exch sub text length div 0 text ashow | ||
| 99 | } if | ||
| 100 | grestore | ||
| 101 | } def | ||
| 102 | |||
| 103 | /boxprim { % xcorner ycorner xsize ysize | ||
| 104 | 4 2 roll | ||
| 105 | moveto | ||
| 106 | 2 copy | ||
| 107 | exch 0 rlineto | ||
| 108 | 0 exch rlineto | ||
| 109 | pop neg 0 rlineto | ||
| 110 | closepath | ||
| 111 | } bind def | ||
| 112 | |||
| 113 | /ellipse_path { | ||
| 114 | /ry exch def | ||
| 115 | /rx exch def | ||
| 116 | /y exch def | ||
| 117 | /x exch def | ||
| 118 | matrix currentmatrix | ||
| 119 | newpath | ||
| 120 | x y translate | ||
| 121 | rx ry scale | ||
| 122 | 0 0 1 0 360 arc | ||
| 123 | setmatrix | ||
| 124 | } bind def | ||
| 125 | |||
| 126 | /endpage { showpage } bind def | ||
| 127 | /showpage { } def | ||
| 128 | |||
| 129 | /layercolorseq | ||
| 130 | [ % layer color sequence - darkest to lightest | ||
| 131 | [0 0 0] | ||
| 132 | [.2 .8 .8] | ||
| 133 | [.4 .8 .8] | ||
| 134 | [.6 .8 .8] | ||
| 135 | [.8 .8 .8] | ||
| 136 | ] | ||
| 137 | def | ||
| 138 | |||
| 139 | /layerlen layercolorseq length def | ||
| 140 | |||
| 141 | /setlayer {/maxlayer exch def /curlayer exch def | ||
| 142 | layercolorseq curlayer 1 sub layerlen mod get | ||
| 143 | aload pop sethsbcolor | ||
| 144 | /nodecolor {nopcolor} def | ||
| 145 | /edgecolor {nopcolor} def | ||
| 146 | /graphcolor {nopcolor} def | ||
| 147 | } bind def | ||
| 148 | |||
| 149 | /onlayer { curlayer ne {invis} if } def | ||
| 150 | |||
| 151 | /onlayers { | ||
| 152 | /myupper exch def | ||
| 153 | /mylower exch def | ||
| 154 | curlayer mylower lt | ||
| 155 | curlayer myupper gt | ||
| 156 | or | ||
| 157 | {invis} if | ||
| 158 | } def | ||
| 159 | |||
| 160 | /curlayer 0 def | ||
| 161 | |||
| 162 | %%EndResource | ||
| 163 | %%EndProlog | ||
| 164 | %%BeginSetup | ||
| 165 | 14 default-font-family set_font | ||
| 166 | % /arrowlength 10 def | ||
| 167 | % /arrowwidth 5 def | ||
| 168 | |||
| 169 | % make sure pdfmark is harmless for PS-interpreters other than Distiller | ||
| 170 | /pdfmark where {pop} {userdict /pdfmark /cleartomark load put} ifelse | ||
| 171 | % make '<<' and '>>' safe on PS Level 1 devices | ||
| 172 | /languagelevel where {pop languagelevel}{1} ifelse | ||
| 173 | 2 lt { | ||
| 174 | userdict (<<) cvn ([) cvn load put | ||
| 175 | userdict (>>) cvn ([) cvn load put | ||
| 176 | } if | ||
| 177 | |||
| 178 | %%EndSetup | ||
| 179 | setupLatin1 | ||
| 180 | %%Page: 1 1 | ||
| 181 | %%PageBoundingBox: 36 36 722 428 | ||
| 182 | %%PageOrientation: Portrait | ||
| 183 | 0 0 1 beginpage | ||
| 184 | gsave | ||
| 185 | 36 36 686 392 boxprim clip newpath | ||
| 186 | 1 1 set_scale 0 rotate 40 40 translate | ||
| 187 | % DNS | ||
| 188 | gsave | ||
| 189 | 1 setlinewidth | ||
| 190 | 0 0 0 nodecolor | ||
| 191 | newpath 137.2989 384 moveto | ||
| 192 | 83.2989 384 lineto | ||
| 193 | 83.2989 348 lineto | ||
| 194 | 137.2989 348 lineto | ||
| 195 | closepath stroke | ||
| 196 | 0 0 0 nodecolor | ||
| 197 | 14 /Times-Roman set_font | ||
| 198 | 96.2989 362.3 moveto 28 (DNS) alignedtext | ||
| 199 | grestore | ||
| 200 | % import | ||
| 201 | gsave | ||
| 202 | 1 setlinewidth | ||
| 203 | 0 0 0 nodecolor | ||
| 204 | newpath 110.2989 297 moveto | ||
| 205 | .2008 279 lineto | ||
| 206 | 110.2989 261 lineto | ||
| 207 | 220.397 279 lineto | ||
| 208 | closepath stroke | ||
| 209 | 0 0 0 nodecolor | ||
| 210 | 14 /Times-Roman set_font | ||
| 211 | 58.2989 275.3 moveto 104 (gnunet-zoneimport) alignedtext | ||
| 212 | grestore | ||
| 213 | % DNS->import | ||
| 214 | gsave | ||
| 215 | 1 setlinewidth | ||
| 216 | 0 0 0 edgecolor | ||
| 217 | newpath 110.2989 347.9735 moveto | ||
| 218 | 110.2989 336.1918 110.2989 320.5607 110.2989 307.1581 curveto | ||
| 219 | stroke | ||
| 220 | 0 0 0 edgecolor | ||
| 221 | newpath 113.799 307.0033 moveto | ||
| 222 | 110.2989 297.0034 lineto | ||
| 223 | 106.799 307.0034 lineto | ||
| 224 | closepath fill | ||
| 225 | 1 setlinewidth | ||
| 226 | solid | ||
| 227 | 0 0 0 edgecolor | ||
| 228 | newpath 113.799 307.0033 moveto | ||
| 229 | 110.2989 297.0034 lineto | ||
| 230 | 106.799 307.0034 lineto | ||
| 231 | closepath stroke | ||
| 232 | 0 0 0 edgecolor | ||
| 233 | 14 /Times-Roman set_font | ||
| 234 | 110.2989 318.8 moveto 37 (import) alignedtext | ||
| 235 | grestore | ||
| 236 | % namestore | ||
| 237 | gsave | ||
| 238 | 1 setlinewidth | ||
| 239 | 0 0 0 nodecolor | ||
| 240 | 159.2989 192 47.3916 18 ellipse_path stroke | ||
| 241 | 0 0 0 nodecolor | ||
| 242 | 14 /Times-Roman set_font | ||
| 243 | 130.7989 188.3 moveto 57 (namestore) alignedtext | ||
| 244 | grestore | ||
| 245 | % import->namestore | ||
| 246 | gsave | ||
| 247 | 1 setlinewidth | ||
| 248 | 0 0 0 edgecolor | ||
| 249 | newpath 119.7466 262.2255 moveto | ||
| 250 | 126.7274 249.831 136.3701 232.7103 144.3867 218.4767 curveto | ||
| 251 | stroke | ||
| 252 | 0 0 0 edgecolor | ||
| 253 | newpath 147.5178 220.0495 moveto | ||
| 254 | 149.3756 209.6188 lineto | ||
| 255 | 141.4186 216.6143 lineto | ||
| 256 | closepath fill | ||
| 257 | 1 setlinewidth | ||
| 258 | solid | ||
| 259 | 0 0 0 edgecolor | ||
| 260 | newpath 147.5178 220.0495 moveto | ||
| 261 | 149.3756 209.6188 lineto | ||
| 262 | 141.4186 216.6143 lineto | ||
| 263 | closepath stroke | ||
| 264 | 0 0 0 edgecolor | ||
| 265 | 14 /Times-Roman set_font | ||
| 266 | 138.2989 231.8 moveto 35 (export) alignedtext | ||
| 267 | grestore | ||
| 268 | % namecache | ||
| 269 | gsave | ||
| 270 | 1 setlinewidth | ||
| 271 | 0 0 0 nodecolor | ||
| 272 | 300.2989 105 50.0912 18 ellipse_path stroke | ||
| 273 | 0 0 0 nodecolor | ||
| 274 | 14 /Times-Roman set_font | ||
| 275 | 269.7989 101.3 moveto 61 (namecache) alignedtext | ||
| 276 | grestore | ||
| 277 | % namestore->namecache | ||
| 278 | gsave | ||
| 279 | 1 setlinewidth | ||
| 280 | 0 0 0 edgecolor | ||
| 281 | newpath 184.1823 176.6464 moveto | ||
| 282 | 206.9544 162.5955 240.8544 141.6785 266.1545 126.0678 curveto | ||
| 283 | stroke | ||
| 284 | 0 0 0 edgecolor | ||
| 285 | newpath 268.04 129.0171 moveto | ||
| 286 | 274.7125 120.7873 lineto | ||
| 287 | 264.3642 123.0598 lineto | ||
| 288 | closepath fill | ||
| 289 | 1 setlinewidth | ||
| 290 | solid | ||
| 291 | 0 0 0 edgecolor | ||
| 292 | newpath 268.04 129.0171 moveto | ||
| 293 | 274.7125 120.7873 lineto | ||
| 294 | 264.3642 123.0598 lineto | ||
| 295 | closepath stroke | ||
| 296 | 0 0 0 edgecolor | ||
| 297 | 14 /Times-Roman set_font | ||
| 298 | 238.2989 144.8 moveto 74 (pre-populates) alignedtext | ||
| 299 | grestore | ||
| 300 | % zonemaster | ||
| 301 | gsave | ||
| 302 | 1 setlinewidth | ||
| 303 | 0 0 0 nodecolor | ||
| 304 | newpath 159.2989 123 moveto | ||
| 305 | 86.5718 105 lineto | ||
| 306 | 159.2989 87 lineto | ||
| 307 | 232.0259 105 lineto | ||
| 308 | closepath stroke | ||
| 309 | 0 0 0 nodecolor | ||
| 310 | 14 /Times-Roman set_font | ||
| 311 | 127.7989 101.3 moveto 63 (zonemaster) alignedtext | ||
| 312 | grestore | ||
| 313 | % namestore->zonemaster | ||
| 314 | gsave | ||
| 315 | 1 setlinewidth | ||
| 316 | 0 0 0 edgecolor | ||
| 317 | newpath 159.2989 173.9735 moveto | ||
| 318 | 159.2989 162.1918 159.2989 146.5607 159.2989 133.1581 curveto | ||
| 319 | stroke | ||
| 320 | 0 0 0 edgecolor | ||
| 321 | newpath 162.799 133.0033 moveto | ||
| 322 | 159.2989 123.0034 lineto | ||
| 323 | 155.799 133.0034 lineto | ||
| 324 | closepath fill | ||
| 325 | 1 setlinewidth | ||
| 326 | solid | ||
| 327 | 0 0 0 edgecolor | ||
| 328 | newpath 162.799 133.0033 moveto | ||
| 329 | 159.2989 123.0034 lineto | ||
| 330 | 155.799 133.0034 lineto | ||
| 331 | closepath stroke | ||
| 332 | 0 0 0 edgecolor | ||
| 333 | 14 /Times-Roman set_font | ||
| 334 | 159.2989 144.8 moveto 41 (notifies) alignedtext | ||
| 335 | grestore | ||
| 336 | % gns | ||
| 337 | gsave | ||
| 338 | 1 setlinewidth | ||
| 339 | 0 0 0 nodecolor | ||
| 340 | newpath 386.2989 210 moveto | ||
| 341 | 353.957 192 lineto | ||
| 342 | 386.2989 174 lineto | ||
| 343 | 418.6408 192 lineto | ||
| 344 | closepath stroke | ||
| 345 | 0 0 0 nodecolor | ||
| 346 | 14 /Times-Roman set_font | ||
| 347 | 376.7989 188.3 moveto 19 (gns) alignedtext | ||
| 348 | grestore | ||
| 349 | % gns->namecache | ||
| 350 | gsave | ||
| 351 | 1 setlinewidth | ||
| 352 | 0 0 0 edgecolor | ||
| 353 | newpath 373.8052 180.5028 moveto | ||
| 354 | 366.3078 173.5201 356.6389 164.3674 348.2989 156 curveto | ||
| 355 | 339.8869 147.5605 330.8812 138.1087 322.969 129.6563 curveto | ||
| 356 | stroke | ||
| 357 | 0 0 0 edgecolor | ||
| 358 | newpath 325.434 127.1675 moveto | ||
| 359 | 316.0586 122.2327 lineto | ||
| 360 | 320.3103 131.937 lineto | ||
| 361 | closepath fill | ||
| 362 | 1 setlinewidth | ||
| 363 | solid | ||
| 364 | 0 0 0 edgecolor | ||
| 365 | newpath 325.434 127.1675 moveto | ||
| 366 | 316.0586 122.2327 lineto | ||
| 367 | 320.3103 131.937 lineto | ||
| 368 | closepath stroke | ||
| 369 | 0 0 0 edgecolor | ||
| 370 | 14 /Times-Roman set_font | ||
| 371 | 348.2989 144.8 moveto 24 (uses) alignedtext | ||
| 372 | grestore | ||
| 373 | % dht | ||
| 374 | gsave | ||
| 375 | 1 setlinewidth | ||
| 376 | 0 0 0 nodecolor | ||
| 377 | 272.2989 18 27 18 ellipse_path stroke | ||
| 378 | 0 0 0 nodecolor | ||
| 379 | 14 /Times-Roman set_font | ||
| 380 | 263.2989 14.3 moveto 18 (dht) alignedtext | ||
| 381 | grestore | ||
| 382 | % gns->dht | ||
| 383 | gsave | ||
| 384 | 1 setlinewidth | ||
| 385 | 0 0 0 edgecolor | ||
| 386 | newpath 385.181 174.2737 moveto | ||
| 387 | 383.0587 152.2164 376.9318 114.1509 359.2989 87 curveto | ||
| 388 | 344.9772 64.9477 321.2191 46.8067 302.1458 34.6694 curveto | ||
| 389 | stroke | ||
| 390 | 0 0 0 edgecolor | ||
| 391 | newpath 303.8469 31.6069 moveto | ||
| 392 | 293.4925 29.3628 lineto | ||
| 393 | 300.1875 37.5742 lineto | ||
| 394 | closepath fill | ||
| 395 | 1 setlinewidth | ||
| 396 | solid | ||
| 397 | 0 0 0 edgecolor | ||
| 398 | newpath 303.8469 31.6069 moveto | ||
| 399 | 293.4925 29.3628 lineto | ||
| 400 | 300.1875 37.5742 lineto | ||
| 401 | closepath stroke | ||
| 402 | 0 0 0 edgecolor | ||
| 403 | 14 /Times-Roman set_font | ||
| 404 | 376.2989 101.3 moveto 40 (queries) alignedtext | ||
| 405 | grestore | ||
| 406 | % dns2gns | ||
| 407 | gsave | ||
| 408 | 1 setlinewidth | ||
| 409 | 0 0 0 nodecolor | ||
| 410 | newpath 336.3104 284.5623 moveto | ||
| 411 | 287.2989 297 lineto | ||
| 412 | 238.2874 284.5623 lineto | ||
| 413 | 238.3331 264.4377 lineto | ||
| 414 | 336.2646 264.4377 lineto | ||
| 415 | closepath stroke | ||
| 416 | 0 0 0 nodecolor | ||
| 417 | 14 /Times-Roman set_font | ||
| 418 | 264.7989 275.3 moveto 45 (dns2gns) alignedtext | ||
| 419 | grestore | ||
| 420 | % dns2gns->gns | ||
| 421 | gsave | ||
| 422 | 1 setlinewidth | ||
| 423 | 0 0 0 edgecolor | ||
| 424 | newpath 304.0929 264.2416 moveto | ||
| 425 | 321.1237 249.2751 347.504 226.0924 365.7671 210.0431 curveto | ||
| 426 | stroke | ||
| 427 | 0 0 0 edgecolor | ||
| 428 | newpath 368.323 212.4564 moveto | ||
| 429 | 373.5243 203.2262 lineto | ||
| 430 | 363.7022 207.1983 lineto | ||
| 431 | closepath fill | ||
| 432 | 1 setlinewidth | ||
| 433 | solid | ||
| 434 | 0 0 0 edgecolor | ||
| 435 | newpath 368.323 212.4564 moveto | ||
| 436 | 373.5243 203.2262 lineto | ||
| 437 | 363.7022 207.1983 lineto | ||
| 438 | closepath stroke | ||
| 439 | 0 0 0 edgecolor | ||
| 440 | 14 /Times-Roman set_font | ||
| 441 | 343.2989 231.8 moveto 38 (lookup) alignedtext | ||
| 442 | grestore | ||
| 443 | % cmdline | ||
| 444 | gsave | ||
| 445 | 1 setlinewidth | ||
| 446 | 0 0 0 nodecolor | ||
| 447 | newpath 478.0186 284.5623 moveto | ||
| 448 | 416.2989 297 lineto | ||
| 449 | 354.5791 284.5623 lineto | ||
| 450 | 354.6367 264.4377 lineto | ||
| 451 | 477.961 264.4377 lineto | ||
| 452 | closepath stroke | ||
| 453 | 0 0 0 nodecolor | ||
| 454 | 14 /Times-Roman set_font | ||
| 455 | 385.7989 275.3 moveto 61 (gnunet-gns) alignedtext | ||
| 456 | grestore | ||
| 457 | % cmdline->gns | ||
| 458 | gsave | ||
| 459 | 1 setlinewidth | ||
| 460 | 0 0 0 edgecolor | ||
| 461 | newpath 411.2098 264.2416 moveto | ||
| 462 | 406.7547 251.3219 400.1883 232.2795 394.9156 216.9885 curveto | ||
| 463 | stroke | ||
| 464 | 0 0 0 edgecolor | ||
| 465 | newpath 398.0825 215.4359 moveto | ||
| 466 | 391.5138 207.1232 lineto | ||
| 467 | 391.4649 217.7179 lineto | ||
| 468 | closepath fill | ||
| 469 | 1 setlinewidth | ||
| 470 | solid | ||
| 471 | 0 0 0 edgecolor | ||
| 472 | newpath 398.0825 215.4359 moveto | ||
| 473 | 391.5138 207.1232 lineto | ||
| 474 | 391.4649 217.7179 lineto | ||
| 475 | closepath stroke | ||
| 476 | 0 0 0 edgecolor | ||
| 477 | 14 /Times-Roman set_font | ||
| 478 | 403.2989 231.8 moveto 38 (lookup) alignedtext | ||
| 479 | grestore | ||
| 480 | % libnss_gns | ||
| 481 | gsave | ||
| 482 | 1 setlinewidth | ||
| 483 | 0 0 0 nodecolor | ||
| 484 | newpath 475.6981 371.5623 moveto | ||
| 485 | 416.2989 384 lineto | ||
| 486 | 356.8996 371.5623 lineto | ||
| 487 | 356.9551 351.4377 lineto | ||
| 488 | 475.6427 351.4377 lineto | ||
| 489 | closepath stroke | ||
| 490 | 0 0 0 nodecolor | ||
| 491 | 14 /Times-Roman set_font | ||
| 492 | 387.2989 362.3 moveto 58 (libnss_gns) alignedtext | ||
| 493 | grestore | ||
| 494 | % libnss_gns->cmdline | ||
| 495 | gsave | ||
| 496 | 1 setlinewidth | ||
| 497 | 0 0 0 edgecolor | ||
| 498 | newpath 416.2989 351.2416 moveto | ||
| 499 | 416.2989 339.2263 416.2989 321.9156 416.2989 307.2516 curveto | ||
| 500 | stroke | ||
| 501 | 0 0 0 edgecolor | ||
| 502 | newpath 419.799 307.1553 moveto | ||
| 503 | 416.2989 297.1553 lineto | ||
| 504 | 412.799 307.1553 lineto | ||
| 505 | closepath fill | ||
| 506 | 1 setlinewidth | ||
| 507 | solid | ||
| 508 | 0 0 0 edgecolor | ||
| 509 | newpath 419.799 307.1553 moveto | ||
| 510 | 416.2989 297.1553 lineto | ||
| 511 | 412.799 307.1553 lineto | ||
| 512 | closepath stroke | ||
| 513 | 0 0 0 edgecolor | ||
| 514 | 14 /Times-Roman set_font | ||
| 515 | 416.2989 318.8 moveto 43 (invokes) alignedtext | ||
| 516 | grestore | ||
| 517 | % proxy | ||
| 518 | gsave | ||
| 519 | 1 setlinewidth | ||
| 520 | 0 0 0 nodecolor | ||
| 521 | newpath 677.8617 284.5623 moveto | ||
| 522 | 587.2989 297 lineto | ||
| 523 | 496.7361 284.5623 lineto | ||
| 524 | 496.8206 264.4377 lineto | ||
| 525 | 677.7771 264.4377 lineto | ||
| 526 | closepath stroke | ||
| 527 | 0 0 0 nodecolor | ||
| 528 | 14 /Times-Roman set_font | ||
| 529 | 538.7989 275.3 moveto 97 (gnunet-gns-proxy) alignedtext | ||
| 530 | grestore | ||
| 531 | % proxy->gns | ||
| 532 | gsave | ||
| 533 | 1 setlinewidth | ||
| 534 | 0 0 0 edgecolor | ||
| 535 | newpath 553.202 264.2416 moveto | ||
| 536 | 513.9908 247.2697 450.3696 219.7321 414.0521 204.0126 curveto | ||
| 537 | stroke | ||
| 538 | 0 0 0 edgecolor | ||
| 539 | newpath 415.1432 200.6711 moveto | ||
| 540 | 404.5757 199.9109 lineto | ||
| 541 | 412.3626 207.0952 lineto | ||
| 542 | closepath fill | ||
| 543 | 1 setlinewidth | ||
| 544 | solid | ||
| 545 | 0 0 0 edgecolor | ||
| 546 | newpath 415.1432 200.6711 moveto | ||
| 547 | 404.5757 199.9109 lineto | ||
| 548 | 412.3626 207.0952 lineto | ||
| 549 | closepath stroke | ||
| 550 | 0 0 0 edgecolor | ||
| 551 | 14 /Times-Roman set_font | ||
| 552 | 499.2989 231.8 moveto 38 (lookup) alignedtext | ||
| 553 | grestore | ||
| 554 | % zonemaster->dht | ||
| 555 | gsave | ||
| 556 | 1 setlinewidth | ||
| 557 | 0 0 0 edgecolor | ||
| 558 | newpath 177.2041 91.2146 moveto | ||
| 559 | 195.8835 76.8331 225.3438 54.1513 246.5248 37.8438 curveto | ||
| 560 | stroke | ||
| 561 | 0 0 0 edgecolor | ||
| 562 | newpath 248.689 40.5947 moveto | ||
| 563 | 254.4775 31.7209 lineto | ||
| 564 | 244.4186 35.0482 lineto | ||
| 565 | closepath fill | ||
| 566 | 1 setlinewidth | ||
| 567 | solid | ||
| 568 | 0 0 0 edgecolor | ||
| 569 | newpath 248.689 40.5947 moveto | ||
| 570 | 254.4775 31.7209 lineto | ||
| 571 | 244.4186 35.0482 lineto | ||
| 572 | closepath stroke | ||
| 573 | 0 0 0 edgecolor | ||
| 574 | 14 /Times-Roman set_font | ||
| 575 | 223.2989 57.8 moveto 52 (publishes) alignedtext | ||
| 576 | grestore | ||
| 577 | endpage | ||
| 578 | showpage | ||
| 579 | grestore | ||
| 580 | %%PageTrailer | ||
| 581 | %%EndPage: 1 | ||
| 582 | %%Trailer | ||
| 583 | end | ||
| 584 | restore | ||
| 585 | %%EOF | ||
diff --git a/doc/documentation/images/gns.jpg b/doc/documentation/images/gns.jpg deleted file mode 100644 index d71109b95..000000000 --- a/doc/documentation/images/gns.jpg +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-0-10-peerinfo.png b/doc/documentation/images/gnunet-0-10-peerinfo.png deleted file mode 100644 index c5e711aff..000000000 --- a/doc/documentation/images/gnunet-0-10-peerinfo.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-fs-gtk-0-10-star-tab.png b/doc/documentation/images/gnunet-fs-gtk-0-10-star-tab.png deleted file mode 100644 index d7993cc46..000000000 --- a/doc/documentation/images/gnunet-fs-gtk-0-10-star-tab.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-download-area.png b/doc/documentation/images/gnunet-gtk-0-10-download-area.png deleted file mode 100644 index 8500d46c9..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-download-area.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-fs-menu.png b/doc/documentation/images/gnunet-gtk-0-10-fs-menu.png deleted file mode 100644 index dc20c45a9..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-fs-menu.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-fs-publish-editing.png b/doc/documentation/images/gnunet-gtk-0-10-fs-publish-editing.png deleted file mode 100644 index 6f9f75ea6..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-fs-publish-editing.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-fs-publish-select.png b/doc/documentation/images/gnunet-gtk-0-10-fs-publish-select.png deleted file mode 100644 index 50672e379..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-fs-publish-select.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-fs-publish-with-file.png b/doc/documentation/images/gnunet-gtk-0-10-fs-publish-with-file.png deleted file mode 100644 index b46542563..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-fs-publish-with-file.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-fs-publish-with-file_0.png b/doc/documentation/images/gnunet-gtk-0-10-fs-publish-with-file_0.png deleted file mode 100644 index b46542563..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-fs-publish-with-file_0.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-fs-publish.png b/doc/documentation/images/gnunet-gtk-0-10-fs-publish.png deleted file mode 100644 index 033b38fa5..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-fs-publish.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-fs-published.png b/doc/documentation/images/gnunet-gtk-0-10-fs-published.png deleted file mode 100644 index fbd3dd6a3..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-fs-published.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-fs-search.png b/doc/documentation/images/gnunet-gtk-0-10-fs-search.png deleted file mode 100644 index bb64ab92e..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-fs-search.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-fs.png b/doc/documentation/images/gnunet-gtk-0-10-fs.png deleted file mode 100644 index c7a294878..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-fs.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-gns-a-done.png b/doc/documentation/images/gnunet-gtk-0-10-gns-a-done.png deleted file mode 100644 index f8231b3a6..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-gns-a-done.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-gns-a.png b/doc/documentation/images/gnunet-gtk-0-10-gns-a.png deleted file mode 100644 index 39858d72c..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-gns-a.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-gns.png b/doc/documentation/images/gnunet-gtk-0-10-gns.png deleted file mode 100644 index c71a2bd7b..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-gns.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-identity.png b/doc/documentation/images/gnunet-gtk-0-10-identity.png deleted file mode 100644 index d0b426098..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-identity.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-search-selected.png b/doc/documentation/images/gnunet-gtk-0-10-search-selected.png deleted file mode 100644 index da1ad4d31..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-search-selected.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10-traffic.png b/doc/documentation/images/gnunet-gtk-0-10-traffic.png deleted file mode 100644 index 76458f717..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10-traffic.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-namestore-gtk-phone.png b/doc/documentation/images/gnunet-namestore-gtk-phone.png deleted file mode 100644 index 3bb859629..000000000 --- a/doc/documentation/images/gnunet-namestore-gtk-phone.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-namestore-gtk-vpn.png b/doc/documentation/images/gnunet-namestore-gtk-vpn.png deleted file mode 100644 index c716729ba..000000000 --- a/doc/documentation/images/gnunet-namestore-gtk-vpn.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-setup-exit.png b/doc/documentation/images/gnunet-setup-exit.png deleted file mode 100644 index 66bd972bc..000000000 --- a/doc/documentation/images/gnunet-setup-exit.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-tutorial-service.png b/doc/documentation/images/gnunet-tutorial-service.png deleted file mode 100644 index 6daed2f35..000000000 --- a/doc/documentation/images/gnunet-tutorial-service.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-tutorial-system.png b/doc/documentation/images/gnunet-tutorial-system.png deleted file mode 100644 index 8b54e16cf..000000000 --- a/doc/documentation/images/gnunet-tutorial-system.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/iceweasel-preferences.png b/doc/documentation/images/iceweasel-preferences.png deleted file mode 100644 index e62c2c4d9..000000000 --- a/doc/documentation/images/iceweasel-preferences.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/iceweasel-proxy.png b/doc/documentation/images/iceweasel-proxy.png deleted file mode 100644 index 9caad4508..000000000 --- a/doc/documentation/images/iceweasel-proxy.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/lego_stack.svg b/doc/documentation/images/lego_stack.svg deleted file mode 100644 index a0e8017c3..000000000 --- a/doc/documentation/images/lego_stack.svg +++ /dev/null | |||
| @@ -1,737 +0,0 @@ | |||
| 1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?> | ||
| 2 | <!-- Created with Inkscape (http://www.inkscape.org/) --> | ||
| 3 | |||
| 4 | <svg | ||
| 5 | xmlns:osb="http://www.openswatchbook.org/uri/2009/osb" | ||
| 6 | xmlns:dc="http://purl.org/dc/elements/1.1/" | ||
| 7 | xmlns:cc="http://creativecommons.org/ns#" | ||
| 8 | xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" | ||
| 9 | xmlns:svg="http://www.w3.org/2000/svg" | ||
| 10 | xmlns="http://www.w3.org/2000/svg" | ||
| 11 | xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" | ||
| 12 | xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" | ||
| 13 | width="744.09448819" | ||
| 14 | height="1052.3622047" | ||
| 15 | id="svg2" | ||
| 16 | version="1.1" | ||
| 17 | inkscape:version="0.48.1 r9760" | ||
| 18 | sodipodi:docname="System.svg"> | ||
| 19 | <defs | ||
| 20 | id="defs4"> | ||
| 21 | <linearGradient | ||
| 22 | id="linearGradient6602"> | ||
| 23 | <stop | ||
| 24 | style="stop-color:#df8060;stop-opacity:1;" | ||
| 25 | offset="0" | ||
| 26 | id="stop6604" /> | ||
| 27 | <stop | ||
| 28 | style="stop-color:#df8002;stop-opacity:0;" | ||
| 29 | offset="1" | ||
| 30 | id="stop6606" /> | ||
| 31 | </linearGradient> | ||
| 32 | <linearGradient | ||
| 33 | id="linearGradient4392" | ||
| 34 | osb:paint="solid"> | ||
| 35 | <stop | ||
| 36 | style="stop-color:#faf6a6;stop-opacity:1;" | ||
| 37 | offset="0" | ||
| 38 | id="stop4394" /> | ||
| 39 | </linearGradient> | ||
| 40 | <inkscape:perspective | ||
| 41 | sodipodi:type="inkscape:persp3d" | ||
| 42 | inkscape:vp_x="883.99395 : 559.99673 : 1" | ||
| 43 | inkscape:vp_y="13.319386 : 993.87659 : 0" | ||
| 44 | inkscape:vp_z="285.3157 : 504.79962 : 1" | ||
| 45 | inkscape:persp3d-origin="481.39556 : 281.96355 : 1" | ||
| 46 | id="perspective3070" /> | ||
| 47 | <inkscape:perspective | ||
| 48 | sodipodi:type="inkscape:persp3d" | ||
| 49 | inkscape:vp_x="76.097926 : 349.87282 : 1" | ||
| 50 | inkscape:vp_y="-13.319386 : 979.366 : 0" | ||
| 51 | inkscape:vp_z="752.55793 : 376.31441 : 1" | ||
| 52 | inkscape:persp3d-origin="373.64045 : 350.98006 : 1" | ||
| 53 | id="perspective3012" /> | ||
| 54 | </defs> | ||
| 55 | <sodipodi:namedview | ||
| 56 | id="base" | ||
| 57 | pagecolor="#ffffff" | ||
| 58 | bordercolor="#666666" | ||
| 59 | borderopacity="1.0" | ||
| 60 | inkscape:pageopacity="0.0" | ||
| 61 | inkscape:pageshadow="2" | ||
| 62 | inkscape:zoom="0.98994949" | ||
| 63 | inkscape:cx="322.06882" | ||
| 64 | inkscape:cy="568.82291" | ||
| 65 | inkscape:document-units="px" | ||
| 66 | inkscape:current-layer="layer1" | ||
| 67 | showgrid="false" | ||
| 68 | inkscape:window-width="846" | ||
| 69 | inkscape:window-height="963" | ||
| 70 | inkscape:window-x="59" | ||
| 71 | inkscape:window-y="0" | ||
| 72 | inkscape:window-maximized="0" /> | ||
| 73 | <metadata | ||
| 74 | id="metadata7"> | ||
| 75 | <rdf:RDF> | ||
| 76 | <cc:Work | ||
| 77 | rdf:about=""> | ||
| 78 | <dc:format>image/svg+xml</dc:format> | ||
| 79 | <dc:type | ||
| 80 | rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> | ||
| 81 | <dc:title /> | ||
| 82 | </cc:Work> | ||
| 83 | </rdf:RDF> | ||
| 84 | </metadata> | ||
| 85 | <g | ||
| 86 | inkscape:label="Layer 1" | ||
| 87 | inkscape:groupmode="layer" | ||
| 88 | id="layer1"> | ||
| 89 | <text | ||
| 90 | xml:space="preserve" | ||
| 91 | style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 92 | x="352.03815" | ||
| 93 | y="-190.12544" | ||
| 94 | id="text6623" | ||
| 95 | sodipodi:linespacing="125%"><tspan | ||
| 96 | sodipodi:role="line" | ||
| 97 | id="tspan6625" | ||
| 98 | x="352.03815" | ||
| 99 | y="-190.12544" /></text> | ||
| 100 | <text | ||
| 101 | xml:space="preserve" | ||
| 102 | style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 103 | x="338.40109" | ||
| 104 | y="-300.73715" | ||
| 105 | id="text6627" | ||
| 106 | sodipodi:linespacing="125%"><tspan | ||
| 107 | sodipodi:role="line" | ||
| 108 | id="tspan6629" | ||
| 109 | x="338.40109" | ||
| 110 | y="-300.73715" /></text> | ||
| 111 | <g | ||
| 112 | style="font-size:24px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 113 | id="text6643" /> | ||
| 114 | <text | ||
| 115 | xml:space="preserve" | ||
| 116 | style="font-size:24px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 117 | x="71.720833" | ||
| 118 | y="95.747719" | ||
| 119 | id="text6648" | ||
| 120 | sodipodi:linespacing="125%"><tspan | ||
| 121 | sodipodi:role="line" | ||
| 122 | id="tspan6650" | ||
| 123 | x="71.720833" | ||
| 124 | y="95.747719" /></text> | ||
| 125 | <text | ||
| 126 | xml:space="preserve" | ||
| 127 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 128 | x="262.63965" | ||
| 129 | y="666.48389" | ||
| 130 | id="text6711" | ||
| 131 | sodipodi:linespacing="125%"><tspan | ||
| 132 | sodipodi:role="line" | ||
| 133 | id="tspan6713" | ||
| 134 | x="262.63965" | ||
| 135 | y="666.48389" /></text> | ||
| 136 | <path | ||
| 137 | inkscape:connector-curvature="0" | ||
| 138 | id="path3506" | ||
| 139 | d="m 198.00647,673.76257 236.93358,0 0,158.2919 -236.93358,0 z" | ||
| 140 | style="fill:#000000;fill-opacity:1;stroke:#faf6a2;stroke-width:1.44768786;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 141 | <path | ||
| 142 | sodipodi:nodetypes="ccccc" | ||
| 143 | inkscape:connector-curvature="0" | ||
| 144 | id="path3432" | ||
| 145 | d="m 169.32669,654.90334 464.83332,-2.26992 -33.76593,25.73079 -483.97287,-0.12904 z" | ||
| 146 | style="fill:#deaa87;fill-opacity:1;stroke:#faf6a2;stroke-width:2.18398547;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 147 | <rect | ||
| 148 | style="fill:#000000;fill-opacity:1;stroke:#59000c;stroke-width:1.35822594;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0.48230088;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 149 | id="rect3416" | ||
| 150 | width="28.495705" | ||
| 151 | height="172.2845" | ||
| 152 | x="464.19418" | ||
| 153 | y="518.96954" /> | ||
| 154 | <rect | ||
| 155 | style="fill:#000000;fill-opacity:1;stroke:#59000c;stroke-width:1.36876941;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0.48230088;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 156 | id="rect3414" | ||
| 157 | width="34.729141" | ||
| 158 | height="170.67587" | ||
| 159 | x="340.86124" | ||
| 160 | y="517.93475" /> | ||
| 161 | <path | ||
| 162 | style="fill:#deaa87;fill-opacity:1;stroke:#faf6a2;stroke-width:2.04969239;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 163 | d="m 246.8138,499.06358 386.50295,-0.94821 -41.88736,26.04231 -413.96081,0 z" | ||
| 164 | id="rect6568-0" | ||
| 165 | inkscape:connector-curvature="0" | ||
| 166 | sodipodi:nodetypes="ccccc" /> | ||
| 167 | <path | ||
| 168 | style="fill:#ffdd55;fill-opacity:1;stroke:#faf6a2;stroke-width:1.49989259;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 169 | d="m 276.05867,399.52042 323.05541,0 0,124.61741 -323.05541,0 z" | ||
| 170 | id="rect5973" | ||
| 171 | inkscape:connector-curvature="0" /> | ||
| 172 | <path | ||
| 173 | style="fill:#ffcc00;fill-opacity:1;stroke:#faf6a2;stroke-width:1.19094384;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 174 | d="m 599.16863,399.06078 34.35465,-18.10059 0,117.34068 -34.35465,25.57066 z" | ||
| 175 | id="rect6542" | ||
| 176 | inkscape:connector-curvature="0" | ||
| 177 | sodipodi:nodetypes="ccccc" /> | ||
| 178 | <rect | ||
| 179 | style="fill:#c87137;fill-opacity:1;stroke:#c48069;stroke-width:1.50087094;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 180 | id="rect6557" | ||
| 181 | width="322.88623" | ||
| 182 | height="30.529778" | ||
| 183 | x="276.67755" | ||
| 184 | y="368.99368" /> | ||
| 185 | <path | ||
| 186 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:0.50882494;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 187 | d="m 598.94047,368.99367 34.58281,-16.82253 0,28.66061 -34.58281,18.06864 z" | ||
| 188 | id="rect6561" | ||
| 189 | inkscape:connector-curvature="0" | ||
| 190 | sodipodi:nodetypes="ccccc" /> | ||
| 191 | <path | ||
| 192 | sodipodi:nodetypes="ccccc" | ||
| 193 | inkscape:connector-curvature="0" | ||
| 194 | id="path6564" | ||
| 195 | d="m 598.94047,369.07046 34.30741,-17.12981 0,29.18412 -34.30741,18.39868 z" | ||
| 196 | style="fill:#c87137;fill-opacity:1;stroke:#faf6a2;stroke-width:0.51140249;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 197 | inkscape:transform-center-x="-70.147578" | ||
| 198 | inkscape:transform-center-y="15.429055" /> | ||
| 199 | <path | ||
| 200 | style="fill:#d38d5f;fill-opacity:1;stroke:#faf6a2;stroke-width:1.47079194;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 201 | d="m 330.2508,353.23478 302.87005,-0.62306 -38.33414,16.82253 -318.87597,0 z" | ||
| 202 | id="rect6568" | ||
| 203 | inkscape:connector-curvature="0" | ||
| 204 | sodipodi:nodetypes="ccccc" /> | ||
| 205 | <text | ||
| 206 | xml:space="preserve" | ||
| 207 | style="font-size:22.32217598px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 208 | x="391.63083" | ||
| 209 | y="461.858" | ||
| 210 | id="text6656" | ||
| 211 | sodipodi:linespacing="125%" | ||
| 212 | transform="scale(1.0052948,0.9947331)"><tspan | ||
| 213 | sodipodi:role="line" | ||
| 214 | id="tspan6658" | ||
| 215 | x="391.63083" | ||
| 216 | y="461.858">Service</tspan></text> | ||
| 217 | <path | ||
| 218 | sodipodi:nodetypes="ccccc" | ||
| 219 | inkscape:connector-curvature="0" | ||
| 220 | id="path6707" | ||
| 221 | d="m 598.75503,244.83802 34.98432,-18.10059 0.26082,125.2709 -35.24514,17.64044 z" | ||
| 222 | style="fill:#37c871;fill-opacity:1;stroke:#faf6a2;stroke-width:1.19094384;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 223 | <path | ||
| 224 | sodipodi:nodetypes="ccccc" | ||
| 225 | inkscape:connector-curvature="0" | ||
| 226 | id="path6709" | ||
| 227 | d="m 419.07032,228.1132 214.71185,-1.24611 -34.63196,19.9378 L 381.29,246.18184 z" | ||
| 228 | style="fill:#37c871;fill-opacity:1;stroke:#faf6a2;stroke-width:1.23655474;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 229 | <rect | ||
| 230 | style="fill:#5fd38d;fill-opacity:1;stroke:#c48069;stroke-width:1.23640049;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 231 | id="rect7224" | ||
| 232 | width="217.86653" | ||
| 233 | height="122.74216" | ||
| 234 | x="381.70358" | ||
| 235 | y="246.25151" /> | ||
| 236 | <text | ||
| 237 | xml:space="preserve" | ||
| 238 | style="font-size:22.32217598px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 239 | x="409.16376" | ||
| 240 | y="302.05649" | ||
| 241 | id="text6715" | ||
| 242 | sodipodi:linespacing="125%" | ||
| 243 | transform="scale(1.0052948,0.9947331)"><tspan | ||
| 244 | sodipodi:role="line" | ||
| 245 | id="tspan6717" | ||
| 246 | x="409.16376" | ||
| 247 | y="302.05649">User Interface</tspan></text> | ||
| 248 | <g | ||
| 249 | id="g7219" | ||
| 250 | transform="matrix(0.62334353,0,0,0.61679464,281.18563,257.70936)"> | ||
| 251 | <rect | ||
| 252 | y="119.99139" | ||
| 253 | x="198.49498" | ||
| 254 | height="60.609154" | ||
| 255 | width="66.670067" | ||
| 256 | id="rect6571" | ||
| 257 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 258 | <text | ||
| 259 | sodipodi:linespacing="125%" | ||
| 260 | id="text6631" | ||
| 261 | y="160.39748" | ||
| 262 | x="206.07112" | ||
| 263 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 264 | xml:space="preserve"><tspan | ||
| 265 | y="160.39748" | ||
| 266 | x="206.07112" | ||
| 267 | id="tspan6633" | ||
| 268 | sodipodi:role="line">API</tspan></text> | ||
| 269 | </g> | ||
| 270 | <g | ||
| 271 | transform="matrix(0.62334353,0,0,0.61679464,344.78251,257.70936)" | ||
| 272 | id="g7226"> | ||
| 273 | <rect | ||
| 274 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 275 | id="rect7228" | ||
| 276 | width="66.670067" | ||
| 277 | height="60.609154" | ||
| 278 | x="198.49498" | ||
| 279 | y="119.99139" /> | ||
| 280 | <text | ||
| 281 | xml:space="preserve" | ||
| 282 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 283 | x="206.07112" | ||
| 284 | y="160.39748" | ||
| 285 | id="text7230" | ||
| 286 | sodipodi:linespacing="125%"><tspan | ||
| 287 | sodipodi:role="line" | ||
| 288 | id="tspan7232" | ||
| 289 | x="206.07112" | ||
| 290 | y="160.39748">API</tspan></text> | ||
| 291 | </g> | ||
| 292 | <g | ||
| 293 | id="g7234" | ||
| 294 | transform="matrix(0.62334353,0,0,0.61679464,409.3239,257.70936)"> | ||
| 295 | <rect | ||
| 296 | y="119.99139" | ||
| 297 | x="198.49498" | ||
| 298 | height="60.609154" | ||
| 299 | width="66.670067" | ||
| 300 | id="rect7236" | ||
| 301 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 302 | <text | ||
| 303 | sodipodi:linespacing="125%" | ||
| 304 | id="text7238" | ||
| 305 | y="160.39748" | ||
| 306 | x="206.07112" | ||
| 307 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 308 | xml:space="preserve"><tspan | ||
| 309 | y="160.39748" | ||
| 310 | x="206.07112" | ||
| 311 | id="tspan7240" | ||
| 312 | sodipodi:role="line">API</tspan></text> | ||
| 313 | </g> | ||
| 314 | <g | ||
| 315 | transform="matrix(0.62334353,0,0,0.61679464,175.75806,412.85048)" | ||
| 316 | id="g7242"> | ||
| 317 | <rect | ||
| 318 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 319 | id="rect7244" | ||
| 320 | width="66.670067" | ||
| 321 | height="60.609154" | ||
| 322 | x="198.49498" | ||
| 323 | y="119.99139" /> | ||
| 324 | <text | ||
| 325 | xml:space="preserve" | ||
| 326 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 327 | x="206.07112" | ||
| 328 | y="160.39748" | ||
| 329 | id="text7246" | ||
| 330 | sodipodi:linespacing="125%"><tspan | ||
| 331 | sodipodi:role="line" | ||
| 332 | id="tspan7248" | ||
| 333 | x="206.07112" | ||
| 334 | y="160.39748">API</tspan></text> | ||
| 335 | </g> | ||
| 336 | <g | ||
| 337 | id="g7250" | ||
| 338 | transform="matrix(0.62334353,0,0,0.61679464,240.79871,413.29105)"> | ||
| 339 | <rect | ||
| 340 | y="119.99139" | ||
| 341 | x="198.49498" | ||
| 342 | height="60.609154" | ||
| 343 | width="66.670067" | ||
| 344 | id="rect7252" | ||
| 345 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 346 | <text | ||
| 347 | sodipodi:linespacing="125%" | ||
| 348 | id="text7254" | ||
| 349 | y="160.39748" | ||
| 350 | x="206.07112" | ||
| 351 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 352 | xml:space="preserve"><tspan | ||
| 353 | y="160.39748" | ||
| 354 | x="206.07112" | ||
| 355 | id="tspan7256" | ||
| 356 | sodipodi:role="line">API</tspan></text> | ||
| 357 | </g> | ||
| 358 | <g | ||
| 359 | transform="matrix(0.62334353,0,0,0.61679464,303.79756,412.40991)" | ||
| 360 | id="g7258"> | ||
| 361 | <rect | ||
| 362 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 363 | id="rect7260" | ||
| 364 | width="66.670067" | ||
| 365 | height="60.609154" | ||
| 366 | x="198.49498" | ||
| 367 | y="119.99139" /> | ||
| 368 | <text | ||
| 369 | xml:space="preserve" | ||
| 370 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 371 | x="206.07112" | ||
| 372 | y="160.39748" | ||
| 373 | id="text7262" | ||
| 374 | sodipodi:linespacing="125%"><tspan | ||
| 375 | sodipodi:role="line" | ||
| 376 | id="tspan7264" | ||
| 377 | x="206.07112" | ||
| 378 | y="160.39748">API</tspan></text> | ||
| 379 | </g> | ||
| 380 | <g | ||
| 381 | id="g7266" | ||
| 382 | transform="matrix(0.62334353,0,0,0.61679464,369.88148,412.40991)"> | ||
| 383 | <rect | ||
| 384 | y="119.99139" | ||
| 385 | x="198.49498" | ||
| 386 | height="60.609154" | ||
| 387 | width="66.670067" | ||
| 388 | id="rect7268" | ||
| 389 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 390 | <text | ||
| 391 | sodipodi:linespacing="125%" | ||
| 392 | id="text7270" | ||
| 393 | y="160.39748" | ||
| 394 | x="206.07112" | ||
| 395 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 396 | xml:space="preserve"><tspan | ||
| 397 | y="160.39748" | ||
| 398 | x="206.07112" | ||
| 399 | id="tspan7272" | ||
| 400 | sodipodi:role="line">API</tspan></text> | ||
| 401 | </g> | ||
| 402 | <path | ||
| 403 | style="fill:#ffeeaa;fill-opacity:1;stroke:#faf6a2;stroke-width:0.91879815;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 404 | d="m 478.56081,554.09281 121.22633,0 0,124.61741 -121.22633,0 z" | ||
| 405 | id="rect5973-1" | ||
| 406 | inkscape:connector-curvature="0" /> | ||
| 407 | <g | ||
| 408 | transform="matrix(0.62334353,0,0,0.61679464,422.424,566.60858)" | ||
| 409 | id="g3474"> | ||
| 410 | <rect | ||
| 411 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 412 | id="rect3476" | ||
| 413 | width="66.670067" | ||
| 414 | height="60.609154" | ||
| 415 | x="198.49498" | ||
| 416 | y="119.99139" /> | ||
| 417 | <text | ||
| 418 | xml:space="preserve" | ||
| 419 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 420 | x="206.07112" | ||
| 421 | y="160.39748" | ||
| 422 | id="text3478" | ||
| 423 | sodipodi:linespacing="125%"><tspan | ||
| 424 | sodipodi:role="line" | ||
| 425 | id="tspan3480" | ||
| 426 | x="206.07112" | ||
| 427 | y="160.39748">API</tspan></text> | ||
| 428 | </g> | ||
| 429 | <path | ||
| 430 | style="fill:#ffe680;fill-opacity:1;stroke:#faf6a2;stroke-width:1.18771458;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 431 | d="m 599.60339,554.02055 33.72575,-29.55535 0.88568,128.35487 -34.61143,26.01123 z" | ||
| 432 | id="rect6542-8" | ||
| 433 | inkscape:connector-curvature="0" | ||
| 434 | sodipodi:nodetypes="ccccc" /> | ||
| 435 | <path | ||
| 436 | sodipodi:nodetypes="ccccc" | ||
| 437 | inkscape:connector-curvature="0" | ||
| 438 | id="path6564-2" | ||
| 439 | d="m 598.92998,524.03024 34.30741,-25.94116 0,26.5407 -34.30741,29.85344 z" | ||
| 440 | style="fill:#d38d5f;fill-opacity:1;stroke:#faf6a2;stroke-width:0.51140249;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 441 | inkscape:transform-center-x="-70.147578" | ||
| 442 | inkscape:transform-center-y="15.429055" /> | ||
| 443 | <path | ||
| 444 | inkscape:transform-center-y="15.492457" | ||
| 445 | inkscape:transform-center-x="-70.147578" | ||
| 446 | style="fill:#c87137;fill-opacity:1;stroke:#faf6a2;stroke-width:0.51245213;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 447 | d="m 598.92998,524.13683 34.30741,-26.04775 0,26.64977 -34.30741,29.97611 z" | ||
| 448 | id="path3402" | ||
| 449 | inkscape:connector-curvature="0" | ||
| 450 | sodipodi:nodetypes="ccccc" /> | ||
| 451 | <path | ||
| 452 | sodipodi:nodetypes="ccccc" | ||
| 453 | inkscape:connector-curvature="0" | ||
| 454 | id="path3404" | ||
| 455 | d="m 599.82047,678.2289 34.30741,-25.94116 0,26.5407 -34.30741,34.25912 z" | ||
| 456 | style="fill:#c87137;fill-opacity:1;stroke:#faf6a2;stroke-width:0.51140249;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 457 | inkscape:transform-center-x="-70.147578" | ||
| 458 | inkscape:transform-center-y="15.429055" /> | ||
| 459 | <path | ||
| 460 | sodipodi:nodetypes="ccccc" | ||
| 461 | inkscape:connector-curvature="0" | ||
| 462 | id="path3406" | ||
| 463 | d="m 600.04863,707.77865 33.90941,-29.55535 0.89049,128.35487 -34.7999,26.01123 z" | ||
| 464 | style="fill:#37c837;fill-opacity:1;stroke:#faf6a2;stroke-width:1.19094384;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 465 | <path | ||
| 466 | inkscape:connector-curvature="0" | ||
| 467 | id="path3410" | ||
| 468 | d="m 356.56358,554.09281 120.92249,0 0,124.19268 -120.92249,0 z" | ||
| 469 | style="fill:#ffeeaa;fill-opacity:1;stroke:#faf6a2;stroke-width:0.91608089;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 470 | <path | ||
| 471 | style="fill:#ffeeaa;fill-opacity:1;stroke:#faf6a2;stroke-width:1.11023378;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 472 | d="m 177.52518,554.09281 177.51841,0 0,124.25702 -177.51841,0 z" | ||
| 473 | id="path3412" | ||
| 474 | inkscape:connector-curvature="0" /> | ||
| 475 | <rect | ||
| 476 | style="fill:#c87137;fill-opacity:1;stroke:#c48069;stroke-width:1.11264122;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 477 | id="rect6557-7" | ||
| 478 | width="177.44882" | ||
| 479 | height="30.529778" | ||
| 480 | x="177.65657" | ||
| 481 | y="523.95343" /> | ||
| 482 | <rect | ||
| 483 | y="678.1521" | ||
| 484 | x="116.73995" | ||
| 485 | height="29.53463" | ||
| 486 | width="177.54182" | ||
| 487 | id="rect3408" | ||
| 488 | style="fill:#c87137;fill-opacity:1;stroke:#c48069;stroke-width:1.09464383;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 489 | <rect | ||
| 490 | y="523.95343" | ||
| 491 | x="356.55023" | ||
| 492 | height="30.529778" | ||
| 493 | width="120.86897" | ||
| 494 | id="rect3420" | ||
| 495 | style="fill:#c87137;fill-opacity:1;stroke:#c48069;stroke-width:0.91828173;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 496 | <rect | ||
| 497 | style="fill:#c87137;fill-opacity:1;stroke:#c48069;stroke-width:0.91828173;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 498 | id="rect3422" | ||
| 499 | width="120.86897" | ||
| 500 | height="30.529778" | ||
| 501 | x="478.54919" | ||
| 502 | y="523.95343" /> | ||
| 503 | <text | ||
| 504 | xml:space="preserve" | ||
| 505 | style="font-size:22.32217598px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 506 | x="372.34232" | ||
| 507 | y="622.53217" | ||
| 508 | id="text6656-2" | ||
| 509 | sodipodi:linespacing="125%" | ||
| 510 | transform="scale(1.0052948,0.9947331)"><tspan | ||
| 511 | sodipodi:role="line" | ||
| 512 | id="tspan6658-2" | ||
| 513 | x="372.34232" | ||
| 514 | y="622.53217">Service</tspan></text> | ||
| 515 | <text | ||
| 516 | sodipodi:linespacing="125%" | ||
| 517 | id="text3424" | ||
| 518 | y="622.53217" | ||
| 519 | x="220.56013" | ||
| 520 | style="font-size:22.32217598px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 521 | xml:space="preserve" | ||
| 522 | transform="scale(1.0052948,0.9947331)"><tspan | ||
| 523 | y="622.53217" | ||
| 524 | x="220.56013" | ||
| 525 | id="tspan3426" | ||
| 526 | sodipodi:role="line">Service</tspan></text> | ||
| 527 | <text | ||
| 528 | xml:space="preserve" | ||
| 529 | style="font-size:22.32217598px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 530 | x="493.85532" | ||
| 531 | y="622.54492" | ||
| 532 | id="text3428" | ||
| 533 | sodipodi:linespacing="125%" | ||
| 534 | transform="scale(1.0052948,0.9947331)"><tspan | ||
| 535 | sodipodi:role="line" | ||
| 536 | id="tspan3430" | ||
| 537 | x="493.85532" | ||
| 538 | y="622.54492">Service</tspan></text> | ||
| 539 | <g | ||
| 540 | id="g3434" | ||
| 541 | transform="matrix(0.62334353,0,0,0.61679464,120.10238,566.60858)"> | ||
| 542 | <rect | ||
| 543 | y="119.99139" | ||
| 544 | x="198.49498" | ||
| 545 | height="60.609154" | ||
| 546 | width="66.670067" | ||
| 547 | id="rect3436" | ||
| 548 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 549 | <text | ||
| 550 | sodipodi:linespacing="125%" | ||
| 551 | id="text3438" | ||
| 552 | y="160.39748" | ||
| 553 | x="206.07112" | ||
| 554 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 555 | xml:space="preserve"><tspan | ||
| 556 | y="160.39748" | ||
| 557 | x="206.07112" | ||
| 558 | id="tspan3440" | ||
| 559 | sodipodi:role="line">API</tspan></text> | ||
| 560 | </g> | ||
| 561 | <g | ||
| 562 | transform="matrix(0.62334353,0,0,0.61679464,181.54625,566.60858)" | ||
| 563 | id="g3442"> | ||
| 564 | <rect | ||
| 565 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 566 | id="rect3444" | ||
| 567 | width="66.670067" | ||
| 568 | height="60.609154" | ||
| 569 | x="198.49498" | ||
| 570 | y="119.99139" /> | ||
| 571 | <text | ||
| 572 | xml:space="preserve" | ||
| 573 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 574 | x="206.07112" | ||
| 575 | y="160.39748" | ||
| 576 | id="text3446" | ||
| 577 | sodipodi:linespacing="125%"><tspan | ||
| 578 | sodipodi:role="line" | ||
| 579 | id="tspan3448" | ||
| 580 | x="206.07112" | ||
| 581 | y="160.39748">API</tspan></text> | ||
| 582 | </g> | ||
| 583 | <g | ||
| 584 | id="g3450" | ||
| 585 | transform="matrix(0.62334353,0,0,0.61679464,242.09962,566.60858)"> | ||
| 586 | <rect | ||
| 587 | y="119.99139" | ||
| 588 | x="198.49498" | ||
| 589 | height="60.609154" | ||
| 590 | width="66.670067" | ||
| 591 | id="rect3452" | ||
| 592 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 593 | <text | ||
| 594 | sodipodi:linespacing="125%" | ||
| 595 | id="text3454" | ||
| 596 | y="160.39748" | ||
| 597 | x="206.07112" | ||
| 598 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 599 | xml:space="preserve"><tspan | ||
| 600 | y="160.39748" | ||
| 601 | x="206.07112" | ||
| 602 | id="tspan3456" | ||
| 603 | sodipodi:role="line">API</tspan></text> | ||
| 604 | </g> | ||
| 605 | <g | ||
| 606 | transform="matrix(0.62334353,0,0,0.61679464,303.54348,566.60858)" | ||
| 607 | id="g3458"> | ||
| 608 | <rect | ||
| 609 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 610 | id="rect3460" | ||
| 611 | width="66.670067" | ||
| 612 | height="60.609154" | ||
| 613 | x="198.49498" | ||
| 614 | y="119.99139" /> | ||
| 615 | <text | ||
| 616 | xml:space="preserve" | ||
| 617 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 618 | x="206.07112" | ||
| 619 | y="160.39748" | ||
| 620 | id="text3462" | ||
| 621 | sodipodi:linespacing="125%"><tspan | ||
| 622 | sodipodi:role="line" | ||
| 623 | id="tspan3464" | ||
| 624 | x="206.07112" | ||
| 625 | y="160.39748">API</tspan></text> | ||
| 626 | </g> | ||
| 627 | <g | ||
| 628 | id="g3466" | ||
| 629 | transform="matrix(0.62334353,0,0,0.61679464,362.76112,566.60858)"> | ||
| 630 | <rect | ||
| 631 | y="119.99139" | ||
| 632 | x="198.49498" | ||
| 633 | height="60.609154" | ||
| 634 | width="66.670067" | ||
| 635 | id="rect3468" | ||
| 636 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 637 | <text | ||
| 638 | sodipodi:linespacing="125%" | ||
| 639 | id="text3470" | ||
| 640 | y="160.39748" | ||
| 641 | x="206.07112" | ||
| 642 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 643 | xml:space="preserve"><tspan | ||
| 644 | y="160.39748" | ||
| 645 | x="206.07112" | ||
| 646 | id="tspan3472" | ||
| 647 | sodipodi:role="line">API</tspan></text> | ||
| 648 | </g> | ||
| 649 | <path | ||
| 650 | style="fill:#5fd35f;fill-opacity:1;stroke:#faf6a2;stroke-width:1.11993289;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 651 | d="m 420.2626,707.53388 180.11119,0 0,124.61741 -180.11119,0 z" | ||
| 652 | id="path3490" | ||
| 653 | inkscape:connector-curvature="0" /> | ||
| 654 | <g | ||
| 655 | transform="matrix(0.62334353,0,0,0.61679464,62.665728,566.60858)" | ||
| 656 | id="g3492"> | ||
| 657 | <rect | ||
| 658 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 659 | id="rect3494" | ||
| 660 | width="66.670067" | ||
| 661 | height="60.609154" | ||
| 662 | x="198.49498" | ||
| 663 | y="119.99139" /> | ||
| 664 | <text | ||
| 665 | xml:space="preserve" | ||
| 666 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 667 | x="206.07112" | ||
| 668 | y="160.39748" | ||
| 669 | id="text3496" | ||
| 670 | sodipodi:linespacing="125%"><tspan | ||
| 671 | sodipodi:role="line" | ||
| 672 | id="tspan3498" | ||
| 673 | x="206.07112" | ||
| 674 | y="160.39748">API</tspan></text> | ||
| 675 | </g> | ||
| 676 | <path | ||
| 677 | inkscape:connector-curvature="0" | ||
| 678 | id="path3500" | ||
| 679 | d="m 116.52597,707.54132 177.63643,0 0,124.61741 -177.63643,0 z" | ||
| 680 | style="fill:#5fd35f;fill-opacity:1;stroke:#faf6a2;stroke-width:1.11221218;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 681 | <path | ||
| 682 | style="fill:#5fd35f;fill-opacity:1;stroke:#faf6a2;stroke-width:0.92545629;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 683 | d="m 295.65636,707.63061 122.98965,0 0,124.61741 -122.98965,0 z" | ||
| 684 | id="path3502" | ||
| 685 | inkscape:connector-curvature="0" /> | ||
| 686 | <text | ||
| 687 | xml:space="preserve" | ||
| 688 | style="font-size:22.32217598px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 689 | x="162.54019" | ||
| 690 | y="779.76184" | ||
| 691 | id="text3508" | ||
| 692 | sodipodi:linespacing="125%" | ||
| 693 | transform="scale(1.0052948,0.9947331)"><tspan | ||
| 694 | sodipodi:role="line" | ||
| 695 | id="tspan3510" | ||
| 696 | x="162.54019" | ||
| 697 | y="779.76184">Service</tspan></text> | ||
| 698 | <text | ||
| 699 | sodipodi:linespacing="125%" | ||
| 700 | id="text3512" | ||
| 701 | y="779.7619" | ||
| 702 | x="313.56918" | ||
| 703 | style="font-size:22.32217598px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 704 | xml:space="preserve" | ||
| 705 | transform="scale(1.0052948,0.9947331)"><tspan | ||
| 706 | y="779.7619" | ||
| 707 | x="313.56918" | ||
| 708 | id="tspan3514" | ||
| 709 | sodipodi:role="line">Service</tspan></text> | ||
| 710 | <text | ||
| 711 | xml:space="preserve" | ||
| 712 | style="font-size:22.32217598px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 713 | x="465.48401" | ||
| 714 | y="779.7619" | ||
| 715 | id="text3516" | ||
| 716 | sodipodi:linespacing="125%" | ||
| 717 | transform="scale(1.0052948,0.9947331)"><tspan | ||
| 718 | sodipodi:role="line" | ||
| 719 | id="tspan3518" | ||
| 720 | x="465.48401" | ||
| 721 | y="779.7619">Service</tspan></text> | ||
| 722 | <rect | ||
| 723 | style="fill:#c87137;fill-opacity:1;stroke:#c48069;stroke-width:0.91063529;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 724 | id="rect3520" | ||
| 725 | width="122.86946" | ||
| 726 | height="29.53463" | ||
| 727 | x="295.75125" | ||
| 728 | y="678.1521" /> | ||
| 729 | <rect | ||
| 730 | y="678.1521" | ||
| 731 | x="420.27423" | ||
| 732 | height="29.53463" | ||
| 733 | width="179.80205" | ||
| 734 | id="rect3522" | ||
| 735 | style="fill:#c87137;fill-opacity:1;stroke:#c48069;stroke-width:1.10158956;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 736 | </g> | ||
| 737 | </svg> | ||
diff --git a/doc/documentation/images/service_lego_block.png b/doc/documentation/images/service_lego_block.png deleted file mode 100644 index 56caf6b9c..000000000 --- a/doc/documentation/images/service_lego_block.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/service_lego_block.svg b/doc/documentation/images/service_lego_block.svg deleted file mode 100644 index ef0d0234f..000000000 --- a/doc/documentation/images/service_lego_block.svg +++ /dev/null | |||
| @@ -1,345 +0,0 @@ | |||
| 1 | <?xml version="1.0" encoding="UTF-8" standalone="no"?> | ||
| 2 | <!-- Created with Inkscape (http://www.inkscape.org/) --> | ||
| 3 | |||
| 4 | <svg | ||
| 5 | xmlns:osb="http://www.openswatchbook.org/uri/2009/osb" | ||
| 6 | xmlns:dc="http://purl.org/dc/elements/1.1/" | ||
| 7 | xmlns:cc="http://creativecommons.org/ns#" | ||
| 8 | xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" | ||
| 9 | xmlns:svg="http://www.w3.org/2000/svg" | ||
| 10 | xmlns="http://www.w3.org/2000/svg" | ||
| 11 | xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" | ||
| 12 | xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" | ||
| 13 | width="744.09448819" | ||
| 14 | height="1052.3622047" | ||
| 15 | id="svg2" | ||
| 16 | version="1.1" | ||
| 17 | inkscape:version="0.48.2 r9819" | ||
| 18 | sodipodi:docname="Lego block 3.svg"> | ||
| 19 | <defs | ||
| 20 | id="defs4"> | ||
| 21 | <linearGradient | ||
| 22 | id="linearGradient6602"> | ||
| 23 | <stop | ||
| 24 | style="stop-color:#df8060;stop-opacity:1;" | ||
| 25 | offset="0" | ||
| 26 | id="stop6604" /> | ||
| 27 | <stop | ||
| 28 | style="stop-color:#df8002;stop-opacity:0;" | ||
| 29 | offset="1" | ||
| 30 | id="stop6606" /> | ||
| 31 | </linearGradient> | ||
| 32 | <linearGradient | ||
| 33 | id="linearGradient4392" | ||
| 34 | osb:paint="solid"> | ||
| 35 | <stop | ||
| 36 | style="stop-color:#faf6a6;stop-opacity:1;" | ||
| 37 | offset="0" | ||
| 38 | id="stop4394" /> | ||
| 39 | </linearGradient> | ||
| 40 | <inkscape:perspective | ||
| 41 | sodipodi:type="inkscape:persp3d" | ||
| 42 | inkscape:vp_x="883.99395 : 559.99673 : 1" | ||
| 43 | inkscape:vp_y="13.319386 : 993.87659 : 0" | ||
| 44 | inkscape:vp_z="285.3157 : 504.79962 : 1" | ||
| 45 | inkscape:persp3d-origin="481.39556 : 281.96355 : 1" | ||
| 46 | id="perspective3070" /> | ||
| 47 | <inkscape:perspective | ||
| 48 | sodipodi:type="inkscape:persp3d" | ||
| 49 | inkscape:vp_x="76.097926 : 349.87282 : 1" | ||
| 50 | inkscape:vp_y="-13.319386 : 979.366 : 0" | ||
| 51 | inkscape:vp_z="752.55793 : 376.31441 : 1" | ||
| 52 | inkscape:persp3d-origin="373.64045 : 350.98006 : 1" | ||
| 53 | id="perspective3012" /> | ||
| 54 | </defs> | ||
| 55 | <sodipodi:namedview | ||
| 56 | id="base" | ||
| 57 | pagecolor="#ffffff" | ||
| 58 | bordercolor="#666666" | ||
| 59 | borderopacity="1.0" | ||
| 60 | inkscape:pageopacity="0.0" | ||
| 61 | inkscape:pageshadow="2" | ||
| 62 | inkscape:zoom="0.49497475" | ||
| 63 | inkscape:cx="385.59974" | ||
| 64 | inkscape:cy="826.03166" | ||
| 65 | inkscape:document-units="px" | ||
| 66 | inkscape:current-layer="layer1" | ||
| 67 | showgrid="false" | ||
| 68 | inkscape:window-width="1366" | ||
| 69 | inkscape:window-height="721" | ||
| 70 | inkscape:window-x="-2" | ||
| 71 | inkscape:window-y="-3" | ||
| 72 | inkscape:window-maximized="1" /> | ||
| 73 | <metadata | ||
| 74 | id="metadata7"> | ||
| 75 | <rdf:RDF> | ||
| 76 | <cc:Work | ||
| 77 | rdf:about=""> | ||
| 78 | <dc:format>image/svg+xml</dc:format> | ||
| 79 | <dc:type | ||
| 80 | rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> | ||
| 81 | <dc:title></dc:title> | ||
| 82 | </cc:Work> | ||
| 83 | </rdf:RDF> | ||
| 84 | </metadata> | ||
| 85 | <g | ||
| 86 | inkscape:label="Layer 1" | ||
| 87 | inkscape:groupmode="layer" | ||
| 88 | id="layer1"> | ||
| 89 | <path | ||
| 90 | style="fill:#ffdd55;fill-opacity:1;stroke:#faf6a2;stroke-width:2.26315212;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 91 | d="m 74.934278,230.09308 453.654042,0 0,202.04036 -453.654042,0 z" | ||
| 92 | id="rect5973" | ||
| 93 | inkscape:connector-curvature="0" /> | ||
| 94 | <path | ||
| 95 | style="fill:#ffcc00;fill-opacity:1;stroke:#faf6a2;stroke-width:1.92068994;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 96 | d="m 528.67583,229.34787 55.11351,-29.34622 0,190.24271 -55.11351,41.45733 z" | ||
| 97 | id="rect6542" | ||
| 98 | inkscape:connector-curvature="0" | ||
| 99 | sodipodi:nodetypes="ccccc" /> | ||
| 100 | <rect | ||
| 101 | style="fill:#d38d5f;fill-opacity:1;stroke:#c48069;stroke-width:2.2674458;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 102 | id="rect6557" | ||
| 103 | width="454.54535" | ||
| 104 | height="49.497475" | ||
| 105 | x="74.764442" | ||
| 106 | y="180.60052" /> | ||
| 107 | <path | ||
| 108 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:0.8206054;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 109 | d="m 528.30981,180.60052 55.47954,-27.27412 0,46.46702 -55.47954,29.29442 z" | ||
| 110 | id="rect6561" | ||
| 111 | inkscape:connector-curvature="0" | ||
| 112 | sodipodi:nodetypes="ccccc" /> | ||
| 113 | <path | ||
| 114 | sodipodi:nodetypes="ccccc" | ||
| 115 | inkscape:connector-curvature="0" | ||
| 116 | id="path6564" | ||
| 117 | d="m 528.30981,180.72501 55.03773,-27.7723 0,47.31578 -55.03773,29.8295 z" | ||
| 118 | style="fill:#d38d5f;fill-opacity:1;stroke:#faf6a2;stroke-width:0.82476228;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 119 | inkscape:transform-center-x="-70.147578" | ||
| 120 | inkscape:transform-center-y="15.429055" /> | ||
| 121 | <path | ||
| 122 | style="fill:#deaa87;fill-opacity:1;stroke:#faf6a2;stroke-width:2.23265362;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 123 | d="m 153.39374,154.33657 430.4643,-1.01015 -54.4837,27.27411 -453.213248,0 z" | ||
| 124 | id="rect6568" | ||
| 125 | inkscape:connector-curvature="0" | ||
| 126 | sodipodi:nodetypes="ccccc" /> | ||
| 127 | <text | ||
| 128 | xml:space="preserve" | ||
| 129 | style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 130 | x="352.03815" | ||
| 131 | y="-190.12544" | ||
| 132 | id="text6623" | ||
| 133 | sodipodi:linespacing="125%"><tspan | ||
| 134 | sodipodi:role="line" | ||
| 135 | id="tspan6625" | ||
| 136 | x="352.03815" | ||
| 137 | y="-190.12544" /></text> | ||
| 138 | <text | ||
| 139 | xml:space="preserve" | ||
| 140 | style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 141 | x="338.40109" | ||
| 142 | y="-300.73715" | ||
| 143 | id="text6627" | ||
| 144 | sodipodi:linespacing="125%"><tspan | ||
| 145 | sodipodi:role="line" | ||
| 146 | id="tspan6629" | ||
| 147 | x="338.40109" | ||
| 148 | y="-300.73715" /></text> | ||
| 149 | <rect | ||
| 150 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 151 | id="rect6571" | ||
| 152 | width="66.670067" | ||
| 153 | height="60.609154" | ||
| 154 | x="198.49498" | ||
| 155 | y="119.99139" /> | ||
| 156 | <path | ||
| 157 | style="fill:#ff6600;fill-opacity:1;stroke:#faf6a2;stroke-width:1.98413372;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 158 | d="m 265.16503,119.45792 44.95179,-22.465406 0,57.057986 -44.95179,26.55003 z" | ||
| 159 | id="path6600" | ||
| 160 | inkscape:connector-curvature="0" | ||
| 161 | sodipodi:nodetypes="ccccc" /> | ||
| 162 | <path | ||
| 163 | style="fill:#ff6600;fill-opacity:1;stroke:#c48069;stroke-width:1.99687159;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 164 | d="m 243.06977,97.26295 66.86223,10e-7 -45.08135,22.728439 -66.3557,0 z" | ||
| 165 | id="path6617" | ||
| 166 | inkscape:connector-curvature="0" | ||
| 167 | sodipodi:nodetypes="ccccc" /> | ||
| 168 | <text | ||
| 169 | xml:space="preserve" | ||
| 170 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 171 | x="206.07112" | ||
| 172 | y="160.39748" | ||
| 173 | id="text6631" | ||
| 174 | sodipodi:linespacing="125%"><tspan | ||
| 175 | sodipodi:role="line" | ||
| 176 | id="tspan6633" | ||
| 177 | x="206.07112" | ||
| 178 | y="160.39748">API</tspan></text> | ||
| 179 | <rect | ||
| 180 | y="119.99139" | ||
| 181 | x="313.65237" | ||
| 182 | height="60.609154" | ||
| 183 | width="66.670067" | ||
| 184 | id="rect6573" | ||
| 185 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 186 | <path | ||
| 187 | sodipodi:nodetypes="ccccc" | ||
| 188 | inkscape:connector-curvature="0" | ||
| 189 | id="path6598" | ||
| 190 | d="m 379.81735,119.56755 44.95179,-22.425126 0,56.955676 -44.95179,26.50243 z" | ||
| 191 | style="fill:#ff6600;fill-opacity:1;stroke:#faf6a2;stroke-width:1.98235416;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 192 | <path | ||
| 193 | sodipodi:nodetypes="ccccc" | ||
| 194 | inkscape:connector-curvature="0" | ||
| 195 | id="path6615" | ||
| 196 | d="m 358.25117,97.26295 66.89824,10e-7 -45.10563,22.728439 -66.39143,0 z" | ||
| 197 | style="fill:#ff6600;fill-opacity:1;stroke:#c48069;stroke-width:1.99740911;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 198 | <text | ||
| 199 | sodipodi:linespacing="125%" | ||
| 200 | id="text6635" | ||
| 201 | y="160.39748" | ||
| 202 | x="322.23865" | ||
| 203 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 204 | xml:space="preserve"><tspan | ||
| 205 | y="160.39748" | ||
| 206 | x="322.23865" | ||
| 207 | id="tspan6637" | ||
| 208 | sodipodi:role="line">API</tspan></text> | ||
| 209 | <rect | ||
| 210 | style="fill:#ff9955;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 211 | id="rect6575" | ||
| 212 | width="66.670067" | ||
| 213 | height="60.609154" | ||
| 214 | x="428.80978" | ||
| 215 | y="119.99139" /> | ||
| 216 | <path | ||
| 217 | style="fill:#ff6600;fill-opacity:1;stroke:#faf6a2;stroke-width:1.98960423;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 218 | d="m 494.97474,119.62537 44.95179,-22.589454 0,57.373054 -44.95179,26.69664 z" | ||
| 219 | id="rect6595" | ||
| 220 | inkscape:connector-curvature="0" | ||
| 221 | sodipodi:nodetypes="ccccc" /> | ||
| 222 | <path | ||
| 223 | style="fill:#ff6600;fill-opacity:1;stroke:#c48069;stroke-width:1.99399996;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 224 | d="m 473.25645,97.26295 66.67007,10e-7 -44.95179,22.728439 -66.16499,0 z" | ||
| 225 | id="rect6612" | ||
| 226 | inkscape:connector-curvature="0" | ||
| 227 | sodipodi:nodetypes="ccccc" /> | ||
| 228 | <text | ||
| 229 | xml:space="preserve" | ||
| 230 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 231 | x="439.41635" | ||
| 232 | y="159.89241" | ||
| 233 | id="text6639" | ||
| 234 | sodipodi:linespacing="125%"><tspan | ||
| 235 | sodipodi:role="line" | ||
| 236 | id="tspan6641" | ||
| 237 | x="439.41635" | ||
| 238 | y="159.89241">API</tspan></text> | ||
| 239 | <g | ||
| 240 | style="font-size:24px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 241 | id="text6643" /> | ||
| 242 | <text | ||
| 243 | xml:space="preserve" | ||
| 244 | style="font-size:24px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 245 | x="71.720833" | ||
| 246 | y="95.747719" | ||
| 247 | id="text6648" | ||
| 248 | sodipodi:linespacing="125%"><tspan | ||
| 249 | sodipodi:role="line" | ||
| 250 | id="tspan6650" | ||
| 251 | x="71.720833" | ||
| 252 | y="95.747719" /></text> | ||
| 253 | <text | ||
| 254 | xml:space="preserve" | ||
| 255 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 256 | x="176.77669" | ||
| 257 | y="216.96603" | ||
| 258 | id="text6652" | ||
| 259 | sodipodi:linespacing="125%"><tspan | ||
| 260 | sodipodi:role="line" | ||
| 261 | id="tspan6654" | ||
| 262 | x="176.77669" | ||
| 263 | y="216.96603">Network Protocol</tspan></text> | ||
| 264 | <text | ||
| 265 | xml:space="preserve" | ||
| 266 | style="font-size:36px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 267 | x="233.34526" | ||
| 268 | y="312.93051" | ||
| 269 | id="text6656" | ||
| 270 | sodipodi:linespacing="125%"><tspan | ||
| 271 | sodipodi:role="line" | ||
| 272 | id="tspan6658" | ||
| 273 | x="233.34526" | ||
| 274 | y="312.93051">Service</tspan></text> | ||
| 275 | <rect | ||
| 276 | style="fill:#ffffff;fill-opacity:1;stroke:#faf6a2;stroke-width:2.09665918;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 277 | id="rect6660" | ||
| 278 | width="66.670067" | ||
| 279 | height="66.609154" | ||
| 280 | x="216.67773" | ||
| 281 | y="371.51938" /> | ||
| 282 | <rect | ||
| 283 | y="371.51938" | ||
| 284 | x="322.74374" | ||
| 285 | height="64.373825" | ||
| 286 | width="66.670067" | ||
| 287 | id="rect6662" | ||
| 288 | style="fill:#ffffff;fill-opacity:1;stroke:#faf6a2;stroke-width:2.06117821;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 289 | <rect | ||
| 290 | style="fill:#ffffff;fill-opacity:1;stroke:#faf6a2;stroke-width:2;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" | ||
| 291 | id="rect6664" | ||
| 292 | width="66.670067" | ||
| 293 | height="60.609154" | ||
| 294 | x="423.75903" | ||
| 295 | y="372.52951" /> | ||
| 296 | <path | ||
| 297 | sodipodi:nodetypes="ccccc" | ||
| 298 | inkscape:connector-curvature="0" | ||
| 299 | id="path6666" | ||
| 300 | d="m 423.61996,372.56359 67.23534,-0.62641 0,19.59587 -68.24549,41.17879 z" | ||
| 301 | style="fill:#ffcc00;fill-opacity:1;stroke:#faf6a2;stroke-width:0.98368376;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 302 | <path | ||
| 303 | style="fill:#ffcc00;fill-opacity:1;stroke:#faf6a2;stroke-width:0.98368376;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 304 | d="m 322.60471,371.55344 67.23534,0.38374 0,23.63648 -67.23534,37.13818 z" | ||
| 305 | id="path6668" | ||
| 306 | inkscape:connector-curvature="0" | ||
| 307 | sodipodi:nodetypes="ccccc" /> | ||
| 308 | <path | ||
| 309 | sodipodi:nodetypes="ccccc" | ||
| 310 | inkscape:connector-curvature="0" | ||
| 311 | id="path6670" | ||
| 312 | d="m 322.60471,371.55344 67.23534,0.38374 0,23.63648 -67.23534,37.13818 z" | ||
| 313 | style="fill:#ffcc00;fill-opacity:1;stroke:#faf6a2;stroke-width:0.98368376;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 314 | <path | ||
| 315 | style="fill:#ffcc00;fill-opacity:1;stroke:#faf6a2;stroke-width:0.98368376;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" | ||
| 316 | d="m 216.53869,371.55344 67.23534,0.38374 0,23.63648 -67.23534,37.13818 z" | ||
| 317 | id="path6672" | ||
| 318 | inkscape:connector-curvature="0" | ||
| 319 | sodipodi:nodetypes="ccccc" /> | ||
| 320 | <text | ||
| 321 | xml:space="preserve" | ||
| 322 | style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" | ||
| 323 | x="262.63965" | ||
| 324 | y="666.48389" | ||
| 325 | id="text6711" | ||
| 326 | sodipodi:linespacing="125%"><tspan | ||
| 327 | sodipodi:role="line" | ||
| 328 | id="tspan6713" | ||
| 329 | x="262.63965" | ||
| 330 | y="666.48389" /></text> | ||
| 331 | <rect | ||
| 332 | y="371.51938" | ||
| 333 | x="111.62187" | ||
| 334 | height="70.798637" | ||
| 335 | width="66.670067" | ||
| 336 | id="rect6721" | ||
| 337 | style="fill:#ffffff;fill-opacity:1;stroke:#faf6a2;stroke-width:2.1615901;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dasharray:none;stroke-dashoffset:0" /> | ||
| 338 | <path | ||
| 339 | sodipodi:nodetypes="ccccc" | ||
| 340 | inkscape:connector-curvature="0" | ||
| 341 | id="path6723" | ||
| 342 | d="m 111.48283,370.54329 67.23534,0.38374 0,23.63648 -67.23534,37.13818 z" | ||
| 343 | style="fill:#ffcc00;fill-opacity:1;stroke:#faf6a2;stroke-width:0.98368376;stroke-linejoin:bevel;stroke-miterlimit:4;stroke-opacity:0;stroke-dashoffset:0" /> | ||
| 344 | </g> | ||
| 345 | </svg> | ||
diff --git a/doc/documentation/images/service_stack.png b/doc/documentation/images/service_stack.png deleted file mode 100644 index 747d087b2..000000000 --- a/doc/documentation/images/service_stack.png +++ /dev/null | |||
| Binary files differ | |||
diff --git a/doc/documentation/images/structure.dot b/doc/documentation/images/structure.dot deleted file mode 100644 index a53db90b8..000000000 --- a/doc/documentation/images/structure.dot +++ /dev/null | |||
| @@ -1,124 +0,0 @@ | |||
| 1 | // house = application | ||
| 2 | // circle (default) = service | ||
| 3 | // box = daemon | ||
| 4 | // diamond = library | ||
| 5 | // black line = dependency | ||
| 6 | // blue line = extension via plugin | ||
| 7 | // red line = possibly useful | ||
| 8 | // dashed = in planning | ||
| 9 | |||
| 10 | // this is what we have...o | ||
| 11 | digraph dependencies { | ||
| 12 | splines = true; | ||
| 13 | |||
| 14 | voting [shape=house]; | ||
| 15 | voting -> consensus; | ||
| 16 | voting -> identity; | ||
| 17 | voting -> cadet; | ||
| 18 | voting -> secretsharing; | ||
| 19 | secretsharing -> consensus; | ||
| 20 | |||
| 21 | fs [shape=house]; | ||
| 22 | fs -> dht; | ||
| 23 | fs -> core; | ||
| 24 | fs -> datastore; | ||
| 25 | fs -> cadet; | ||
| 26 | fs -> ats; | ||
| 27 | fs -> block [style=dotted,color=blue]; | ||
| 28 | fs -> identity; | ||
| 29 | exit [shape=box]; | ||
| 30 | exit -> cadet; | ||
| 31 | exit -> tun; | ||
| 32 | exit -> dnsstub; | ||
| 33 | vpn -> cadet; | ||
| 34 | vpn -> regex; | ||
| 35 | vpn -> tun; | ||
| 36 | pt [shape=house]; | ||
| 37 | pt -> cadet; | ||
| 38 | pt -> vpn; | ||
| 39 | pt -> dns; | ||
| 40 | pt -> dnsparser; | ||
| 41 | dns -> tun; | ||
| 42 | dns -> dnsstub; | ||
| 43 | zonemaster [shape=house]; | ||
| 44 | zonemaster -> namestore; | ||
| 45 | zonemaster -> dht; | ||
| 46 | gns -> dns; | ||
| 47 | gns -> dht; | ||
| 48 | gns -> block [style=dotted,color=blue]; | ||
| 49 | gns -> revocation; | ||
| 50 | gns -> vpn; | ||
| 51 | gns -> dnsparser; | ||
| 52 | gns -> dnsstub; | ||
| 53 | gns -> identity; | ||
| 54 | revocation -> core; | ||
| 55 | revocation -> set; | ||
| 56 | namestore -> identity; | ||
| 57 | namestore -> gnsrecord; | ||
| 58 | dnsparser -> gnsrecord [style=dotted,color=blue]; | ||
| 59 | conversation -> gnsrecord [style=dotted,color=blue]; | ||
| 60 | gns -> gnsrecord; | ||
| 61 | dht -> core; | ||
| 62 | dht -> nse; | ||
| 63 | dht -> block; | ||
| 64 | dht -> datacache; | ||
| 65 | dht -> peerinfo; | ||
| 66 | dht -> hello; | ||
| 67 | nse -> core; | ||
| 68 | regex -> block [style=dotted,color=blue]; | ||
| 69 | block [shape=diamond]; | ||
| 70 | datacache [shape=diamond]; | ||
| 71 | cadet -> core [weight=2]; | ||
| 72 | cadet -> dht; | ||
| 73 | cadet -> block [style=dotted,color=blue]; | ||
| 74 | conversation [shape=house]; | ||
| 75 | conversation -> cadet; | ||
| 76 | conversation -> gns; | ||
| 77 | conversation -> speaker; | ||
| 78 | conversation -> microphone; | ||
| 79 | speaker [shape=diamond]; | ||
| 80 | microphone [shape=diamond]; | ||
| 81 | regex -> dht; | ||
| 82 | core -> transport; | ||
| 83 | topology [shape=box]; | ||
| 84 | topology -> peerinfo; | ||
| 85 | topology -> transport; | ||
| 86 | topology -> core; | ||
| 87 | topology -> hello; | ||
| 88 | hostlist [shape=box]; | ||
| 89 | hostlist -> core; | ||
| 90 | hostlist -> peerinfo; | ||
| 91 | hostlist -> hello; | ||
| 92 | transport -> ats; | ||
| 93 | transport -> hello; | ||
| 94 | transport -> peerinfo; | ||
| 95 | transport -> nat; | ||
| 96 | transport -> fragmentation; | ||
| 97 | consensus -> set; | ||
| 98 | consensus -> cadet; | ||
| 99 | scalarproduct -> set; | ||
| 100 | scalarproduct -> cadet; | ||
| 101 | set -> cadet; | ||
| 102 | peerinfo -> hello; | ||
| 103 | fragmentation [shape=diamond]; | ||
| 104 | hello [shape=diamond]; | ||
| 105 | nat [shape=diamond]; | ||
| 106 | tun [shape=diamond]; | ||
| 107 | dnsparser [shape=diamond]; | ||
| 108 | dnsstub [shape=diamond]; | ||
| 109 | |||
| 110 | secushare [shape=house]; | ||
| 111 | multicast; | ||
| 112 | psyc; | ||
| 113 | social -> psyc; | ||
| 114 | social -> gns; | ||
| 115 | psyc -> psycstore; | ||
| 116 | psycstore; | ||
| 117 | social; | ||
| 118 | secushare -> social; | ||
| 119 | psyc -> multicast; | ||
| 120 | multicast -> cadet; | ||
| 121 | |||
| 122 | rps; | ||
| 123 | rps -> core; | ||
| 124 | } | ||
diff --git a/doc/documentation/index.html b/doc/documentation/index.html deleted file mode 100644 index 1bd6da033..000000000 --- a/doc/documentation/index.html +++ /dev/null | |||
| @@ -1,58 +0,0 @@ | |||
| 1 | <html> | ||
| 2 | <head> | ||
| 3 | <title>GNUnet - GNUnet Manuals and Handbooks</title> | ||
| 4 | <meta charset="utf-8"> | ||
| 5 | <meta name="keywords" content="gnunet,GNUnet,Manual,Manuals,preview,developer-preview,inofficial,GNU"> | ||
| 6 | <meta name="description" content="The GNUnet Manuals"> | ||
| 7 | <meta name="viewport" content="width=device-width, initial-scale=1"> | ||
| 8 | </head> | ||
| 9 | |||
| 10 | <body> | ||
| 11 | <h2>GNUnet - GNUnet Manuals and Handbooks</h2> | ||
| 12 | |||
| 13 | <blockquote><address> | ||
| 14 | GNUnet e.V.<br/> | ||
| 15 | Fakultät für Informatik -- I8<br/> | ||
| 16 | Technische Universität München<br/> | ||
| 17 | Boltzmannstraße 3<br/> | ||
| 18 | 85748 Garching<br/> | ||
| 19 | GERMANY<br/> | ||
| 20 | </address></blockquote> | ||
| 21 | |||
| 22 | <p>The following handbooks and manuals are available:</p> | ||
| 23 | |||
| 24 | <ul> | ||
| 25 | <li><a href="gnunet/index.html">GNUnet Reference Manual</li> | ||
| 26 | <li><a href="gnunet-c-tutorial/index.html">GNUnet C Tutorial</li> | ||
| 27 | </ul> | ||
| 28 | |||
| 29 | <div id="footer"> | ||
| 30 | <div class="unprintable"> | ||
| 31 | |||
| 32 | <p>Please send general FSF & GNU inquiries to | ||
| 33 | <a href="mailto:gnu@gnu.org"><gnu@gnu.org></a>. | ||
| 34 | There are also <a href="/contact/">other ways to contact</a> | ||
| 35 | the FSF. Broken links and other corrections or suggestions can be sent | ||
| 36 | to <a href="mailto:gnunet-developers@gnu.org"><gnunet-developers@gnu.org></a>.</p> | ||
| 37 | </div> | ||
| 38 | |||
| 39 | <p>Copyright © 2001 - 2018 GNUnet e.V.</p> | ||
| 40 | |||
| 41 | <p> | ||
| 42 | <a rel="license" href="http://creativecommons.org/licenses/by-nd/4.0/"> | ||
| 43 | <img alt="Creative Commons License" | ||
| 44 | style="border-width:0" | ||
| 45 | src="https://i.creativecommons.org/l/by-nd/4.0/88x31.png" /> | ||
| 46 | </a> | ||
| 47 | <br /> | ||
| 48 | This page is licensed under a | ||
| 49 | <a rel="license" | ||
| 50 | href="http://creativecommons.org/licenses/by-nd/4.0/"> | ||
| 51 | Creative Commons Attribution-NoDerivatives 4.0 International License | ||
| 52 | </a>. Individual Manuals are licensed under the licenses mentioned within | ||
| 53 | the books (GNU Free Documentation License, GNU General Public License). | ||
| 54 | </p> | ||
| 55 | </div> | ||
| 56 | |||
| 57 | </body> | ||
| 58 | </html> | ||
diff --git a/doc/documentation/run-gendocs.sh b/doc/documentation/run-gendocs.sh deleted file mode 100755 index 5e60a2d0f..000000000 --- a/doc/documentation/run-gendocs.sh +++ /dev/null | |||
| @@ -1,18 +0,0 @@ | |||
| 1 | #!/bin/sh | ||
| 2 | |||
| 3 | make version.texi/replacement | ||
| 4 | |||
| 5 | ./gendocs.sh --email gnunet-developers@gnu.org gnunet-c-tutorial "GNUnet C Tutorial" -o "manual/gnunet-c-tutorial" | ||
| 6 | #cd manual | ||
| 7 | #mkdir gnunet-c-tutorial | ||
| 8 | #mv * gnunet-c-tutorial/ | ||
| 9 | #cd .. | ||
| 10 | ./gendocs.sh --email gnunet-developers@gnu.org gnunet "GNUnet Reference Manual" -o "manual/gnunet" | ||
| 11 | #cd manual | ||
| 12 | #mkdir handbook | ||
| 13 | #mkdir ../tmp-gnunet | ||
| 14 | #mv gnunet ../tmp-gnunet | ||
| 15 | #mv * handbook/ | ||
| 16 | #mv ../tmp-gnunet gnunet | ||
| 17 | cp "index.html" manual/ | ||
| 18 | printf "Success" | ||
diff --git a/doc/documentation/testbed_test.c b/doc/documentation/testbed_test.c deleted file mode 100644 index 1696234b0..000000000 --- a/doc/documentation/testbed_test.c +++ /dev/null | |||
| @@ -1,99 +0,0 @@ | |||
| 1 | #include <unistd.h> | ||
| 2 | #include <gnunet/platform.h> | ||
| 3 | #include <gnunet/gnunet_util_lib.h> | ||
| 4 | #include <gnunet/gnunet_testbed_service.h> | ||
| 5 | #include <gnunet/gnunet_dht_service.h> | ||
| 6 | |||
| 7 | #define NUM_PEERS 20 | ||
| 8 | |||
| 9 | static struct GNUNET_TESTBED_Operation *dht_op; | ||
| 10 | |||
| 11 | static struct GNUNET_DHT_Handle *dht_handle; | ||
| 12 | |||
| 13 | |||
| 14 | struct MyContext | ||
| 15 | { | ||
| 16 | int ht_len; | ||
| 17 | } ctxt; | ||
| 18 | |||
| 19 | |||
| 20 | static int result; | ||
| 21 | |||
| 22 | |||
| 23 | static void | ||
| 24 | shutdown_task (void *cls) | ||
| 25 | { | ||
| 26 | if (NULL != dht_op) | ||
| 27 | { | ||
| 28 | GNUNET_TESTBED_operation_done (dht_op); | ||
| 29 | dht_op = NULL; | ||
| 30 | dht_handle = NULL; | ||
| 31 | } | ||
| 32 | result = GNUNET_OK; | ||
| 33 | } | ||
| 34 | |||
| 35 | |||
| 36 | static void | ||
| 37 | service_connect_comp (void *cls, | ||
| 38 | struct GNUNET_TESTBED_Operation *op, | ||
| 39 | void *ca_result, | ||
| 40 | const char *emsg) | ||
| 41 | { | ||
| 42 | GNUNET_assert (op == dht_op); | ||
| 43 | dht_handle = ca_result; | ||
| 44 | // Do work here... | ||
| 45 | GNUNET_SCHEDULER_shutdown (); | ||
| 46 | } | ||
| 47 | |||
| 48 | |||
| 49 | static void * | ||
| 50 | dht_ca (void *cls, const struct GNUNET_CONFIGURATION_Handle *cfg) | ||
| 51 | { | ||
| 52 | struct MyContext *ctxt = cls; | ||
| 53 | |||
| 54 | dht_handle = GNUNET_DHT_connect (cfg, ctxt->ht_len); | ||
| 55 | return dht_handle; | ||
| 56 | } | ||
| 57 | |||
| 58 | |||
| 59 | static void | ||
| 60 | dht_da (void *cls, void *op_result) | ||
| 61 | { | ||
| 62 | struct MyContext *ctxt = cls; | ||
| 63 | |||
| 64 | GNUNET_DHT_disconnect ((struct GNUNET_DHT_Handle *) op_result); | ||
| 65 | dht_handle = NULL; | ||
| 66 | } | ||
| 67 | |||
| 68 | |||
| 69 | static void | ||
| 70 | test_master (void *cls, | ||
| 71 | struct GNUNET_TESTBED_RunHandle *h, | ||
| 72 | unsigned int num_peers, | ||
| 73 | struct GNUNET_TESTBED_Peer **peers, | ||
| 74 | unsigned int links_succeeded, | ||
| 75 | unsigned int links_failed) | ||
| 76 | { | ||
| 77 | ctxt.ht_len = 10; | ||
| 78 | dht_op = GNUNET_TESTBED_service_connect | ||
| 79 | (NULL, peers[0], "dht", | ||
| 80 | &service_connect_comp, NULL, | ||
| 81 | &dht_ca, &dht_da, &ctxt); | ||
| 82 | GNUNET_SCHEDULER_add_shutdown (&shutdown_task, NULL); | ||
| 83 | } | ||
| 84 | |||
| 85 | |||
| 86 | int | ||
| 87 | main (int argc, char **argv) | ||
| 88 | { | ||
| 89 | int ret; | ||
| 90 | |||
| 91 | result = GNUNET_SYSERR; | ||
| 92 | ret = GNUNET_TESTBED_test_run | ||
| 93 | ("awesome-test", "template.conf", | ||
| 94 | NUM_PEERS, 0LL, | ||
| 95 | NULL, NULL, &test_master, NULL); | ||
| 96 | if ( (GNUNET_OK != ret) || (GNUNET_OK != result) ) | ||
| 97 | return 1; | ||
| 98 | return 0; | ||
| 99 | } | ||
diff --git a/doc/documentation/tutorial-examples/001.c b/doc/documentation/tutorial-examples/001.c deleted file mode 100644 index 7f6699dd2..000000000 --- a/doc/documentation/tutorial-examples/001.c +++ /dev/null | |||
| @@ -1,29 +0,0 @@ | |||
| 1 | #include <gnunet/platform.h> | ||
| 2 | #include <gnunet/gnunet_util_lib.h> | ||
| 3 | |||
| 4 | static int ret; | ||
| 5 | |||
| 6 | static void | ||
| 7 | run (void *cls, | ||
| 8 | char *const *args, | ||
| 9 | const char *cfgfile, | ||
| 10 | const struct GNUNET_CONFIGURATION_Handle *cfg) | ||
| 11 | { | ||
| 12 | // main code here | ||
| 13 | ret = 0; | ||
| 14 | } | ||
| 15 | |||
| 16 | int | ||
| 17 | main (int argc, char *const *argv) | ||
| 18 | { | ||
| 19 | struct GNUNET_GETOPT_CommandLineOption options[] = { | ||
| 20 | GNUNET_GETOPT_OPTION_END | ||
| 21 | }; | ||
| 22 | return (GNUNET_OK == | ||
| 23 | GNUNET_PROGRAM_run (argc, | ||
| 24 | argv, | ||
| 25 | "binary-name", | ||
| 26 | gettext_noop ("binary description text"), | ||
| 27 | options, &run, NULL)) ? ret : 1; | ||
| 28 | } | ||
| 29 | |||
diff --git a/doc/documentation/tutorial-examples/002.c b/doc/documentation/tutorial-examples/002.c deleted file mode 100644 index 02233fd61..000000000 --- a/doc/documentation/tutorial-examples/002.c +++ /dev/null | |||
| @@ -1,17 +0,0 @@ | |||
| 1 | static char *string_option; | ||
| 2 | static int a_flag; | ||
| 3 | |||
| 4 | // ... | ||
| 5 | struct GNUNET_GETOPT_CommandLineOption options[] = { | ||
| 6 | GNUNET_GETOPT_option_string ('s', "name", "SOMESTRING", | ||
| 7 | gettext_noop ("text describing the string_option NAME"), | ||
| 8 | &string_option}, | ||
| 9 | GNUNET_GETOPT_option_flag ('f', "flag", | ||
| 10 | gettext_noop ("text describing the flag option"), | ||
| 11 | &a_flag), | ||
| 12 | GNUNET_GETOPT_OPTION_END | ||
| 13 | }; | ||
| 14 | string_option = NULL; | ||
| 15 | a_flag = GNUNET_SYSERR; | ||
| 16 | // ... | ||
| 17 | |||
diff --git a/doc/documentation/tutorial-examples/003.c b/doc/documentation/tutorial-examples/003.c deleted file mode 100644 index d158d7e75..000000000 --- a/doc/documentation/tutorial-examples/003.c +++ /dev/null | |||
| @@ -1,11 +0,0 @@ | |||
| 1 | struct GNUNET_MQ_MessageHandlers handlers[] = { | ||
| 2 | // ... | ||
| 3 | GNUNET_MQ_handler_end () | ||
| 4 | }; | ||
| 5 | struct GNUNET_MQ_Handle *mq; | ||
| 6 | |||
| 7 | mq = GNUNET_CLIENT_connect (cfg, | ||
| 8 | "service-name", | ||
| 9 | handlers, | ||
| 10 | &error_cb, | ||
| 11 | NULL); | ||
diff --git a/doc/documentation/tutorial-examples/004.c b/doc/documentation/tutorial-examples/004.c deleted file mode 100644 index 0ef007907..000000000 --- a/doc/documentation/tutorial-examples/004.c +++ /dev/null | |||
| @@ -1,5 +0,0 @@ | |||
| 1 | struct GNUNET_MessageHeader | ||
| 2 | { | ||
| 3 | uint16_t size GNUNET_PACKED; | ||
| 4 | uint16_t type GNUNET_PACKED; | ||
| 5 | }; | ||
diff --git a/doc/documentation/tutorial-examples/005.c b/doc/documentation/tutorial-examples/005.c deleted file mode 100644 index 1b59f85a6..000000000 --- a/doc/documentation/tutorial-examples/005.c +++ /dev/null | |||
| @@ -1,9 +0,0 @@ | |||
| 1 | struct GNUNET_MQ_Envelope *env; | ||
| 2 | struct GNUNET_MessageHeader *msg; | ||
| 3 | |||
| 4 | env = GNUNET_MQ_msg_extra (msg, payload_size, GNUNET_MY_MESSAGE_TYPE); | ||
| 5 | GNUNET_memcpy (&msg[1], | ||
| 6 | &payload, | ||
| 7 | payload_size); | ||
| 8 | // Send message via message queue 'mq' | ||
| 9 | GNUNET_mq_send (mq, env); | ||
diff --git a/doc/documentation/tutorial-examples/006.c b/doc/documentation/tutorial-examples/006.c deleted file mode 100644 index 944d2b18c..000000000 --- a/doc/documentation/tutorial-examples/006.c +++ /dev/null | |||
| @@ -1,31 +0,0 @@ | |||
| 1 | static void | ||
| 2 | handle_fix (void *cls, const struct MyMessage *msg) | ||
| 3 | { | ||
| 4 | // process 'msg' | ||
| 5 | } | ||
| 6 | |||
| 7 | static int | ||
| 8 | check_var (void *cls, const struct MyVarMessage *msg) | ||
| 9 | { | ||
| 10 | // check 'msg' is well-formed | ||
| 11 | return GNUNET_OK; | ||
| 12 | } | ||
| 13 | |||
| 14 | static void | ||
| 15 | handle_var (void *cls, const struct MyVarMessage *msg) | ||
| 16 | { | ||
| 17 | // process 'msg' | ||
| 18 | } | ||
| 19 | |||
| 20 | struct GNUNET_MQ_MessageHandler handlers[] = { | ||
| 21 | GNUNET_MQ_hd_fixed_size (fix, | ||
| 22 | GNUNET_MESSAGE_TYPE_MY_FIX, | ||
| 23 | struct MyMessage, | ||
| 24 | NULL), | ||
| 25 | GNUNET_MQ_hd_fixed_size (var, | ||
| 26 | GNUNET_MESSAGE_TYPE_MY_VAR, | ||
| 27 | struct MyVarMessage, | ||
| 28 | NULL), | ||
| 29 | |||
| 30 | GNUNET_MQ_handler_end () | ||
| 31 | }; | ||
diff --git a/doc/documentation/tutorial-examples/007.c b/doc/documentation/tutorial-examples/007.c deleted file mode 100644 index 096539e43..000000000 --- a/doc/documentation/tutorial-examples/007.c +++ /dev/null | |||
| @@ -1,10 +0,0 @@ | |||
| 1 | GNUNET_SERVICE_MAIN | ||
| 2 | ("service-name", | ||
| 3 | GNUNET_SERVICE_OPTION_NONE, | ||
| 4 | &run, | ||
| 5 | &client_connect_cb, | ||
| 6 | &client_disconnect_cb, | ||
| 7 | NULL, | ||
| 8 | GNUNET_MQ_hd_fixed_size (...), | ||
| 9 | GNUNET_MQ_hd_var_size (...), | ||
| 10 | GNUNET_MQ_handler_end ()); | ||
diff --git a/doc/documentation/tutorial-examples/008.c b/doc/documentation/tutorial-examples/008.c deleted file mode 100644 index 2dffe2cf9..000000000 --- a/doc/documentation/tutorial-examples/008.c +++ /dev/null | |||
| @@ -1,22 +0,0 @@ | |||
| 1 | static void | ||
| 2 | run (void *cls, | ||
| 3 | const struct GNUNET_CONFIGURATION_Handle *c, | ||
| 4 | struct GNUNET_SERVICE_Handle *service) | ||
| 5 | { | ||
| 6 | } | ||
| 7 | |||
| 8 | static void * | ||
| 9 | client_connect_cb (void *cls, | ||
| 10 | struct GNUNET_SERVICE_Client *c, | ||
| 11 | struct GNUNET_MQ_Handle *mq) | ||
| 12 | { | ||
| 13 | return c; | ||
| 14 | } | ||
| 15 | |||
| 16 | static void | ||
| 17 | client_disconnect_cb (void *cls, | ||
| 18 | struct GNUNET_SERVICE_Client *c, | ||
| 19 | void *internal_cls) | ||
| 20 | { | ||
| 21 | GNUNET_assert (c == internal_cls); | ||
| 22 | } | ||
diff --git a/doc/documentation/tutorial-examples/009.c b/doc/documentation/tutorial-examples/009.c deleted file mode 100644 index 26d918fb0..000000000 --- a/doc/documentation/tutorial-examples/009.c +++ /dev/null | |||
| @@ -1,9 +0,0 @@ | |||
| 1 | #include <gnunet/gnunet_core_service.h> | ||
| 2 | |||
| 3 | struct GNUNET_CORE_Handle * | ||
| 4 | GNUNET_CORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
| 5 | void *cls, | ||
| 6 | GNUNET_CORE_StartupCallback init, | ||
| 7 | GNUNET_CORE_ConnectEventHandler connects, | ||
| 8 | GNUNET_CORE_DisconnectEventHandler disconnects, | ||
| 9 | const struct GNUNET_MQ_MessageHandler *handlers); | ||
diff --git a/doc/documentation/tutorial-examples/010.c b/doc/documentation/tutorial-examples/010.c deleted file mode 100644 index 33494490d..000000000 --- a/doc/documentation/tutorial-examples/010.c +++ /dev/null | |||
| @@ -1,8 +0,0 @@ | |||
| 1 | void * | ||
| 2 | connects (void *cls, | ||
| 3 | const struct GNUNET_PeerIdentity *peer, | ||
| 4 | struct GNUNET_MQ_Handle *mq) | ||
| 5 | { | ||
| 6 | return mq; | ||
| 7 | } | ||
| 8 | |||
diff --git a/doc/documentation/tutorial-examples/011.c b/doc/documentation/tutorial-examples/011.c deleted file mode 100644 index 23bc051de..000000000 --- a/doc/documentation/tutorial-examples/011.c +++ /dev/null | |||
| @@ -1,8 +0,0 @@ | |||
| 1 | void | ||
| 2 | disconnects (void *cls, | ||
| 3 | const struct GNUNET_PeerIdentity * peer) | ||
| 4 | { | ||
| 5 | /* Remove peer's identity from known peers */ | ||
| 6 | /* Make sure no messages are sent to peer from now on */ | ||
| 7 | } | ||
| 8 | |||
diff --git a/doc/documentation/tutorial-examples/012.c b/doc/documentation/tutorial-examples/012.c deleted file mode 100644 index cb21d78ab..000000000 --- a/doc/documentation/tutorial-examples/012.c +++ /dev/null | |||
| @@ -1,4 +0,0 @@ | |||
| 1 | #include "gnunet_peerstore_service.h" | ||
| 2 | |||
| 3 | peerstore_handle = GNUNET_PEERSTORE_connect (cfg); | ||
| 4 | |||
diff --git a/doc/documentation/tutorial-examples/013.1.c b/doc/documentation/tutorial-examples/013.1.c deleted file mode 100644 index fa5212868..000000000 --- a/doc/documentation/tutorial-examples/013.1.c +++ /dev/null | |||
| @@ -1,3 +0,0 @@ | |||
| 1 | void | ||
| 2 | GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext | ||
| 3 | *sc); | ||
diff --git a/doc/documentation/tutorial-examples/013.c b/doc/documentation/tutorial-examples/013.c deleted file mode 100644 index 6792417e1..000000000 --- a/doc/documentation/tutorial-examples/013.c +++ /dev/null | |||
| @@ -1,12 +0,0 @@ | |||
| 1 | struct GNUNET_PEERSTORE_StoreContext * | ||
| 2 | GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h, | ||
| 3 | const char *sub_system, | ||
| 4 | const struct GNUNET_PeerIdentity *peer, | ||
| 5 | const char *key, | ||
| 6 | const void *value, | ||
| 7 | size_t size, | ||
| 8 | struct GNUNET_TIME_Absolute expiry, | ||
| 9 | enum GNUNET_PEERSTORE_StoreOption options, | ||
| 10 | GNUNET_PEERSTORE_Continuation cont, | ||
| 11 | void *cont_cls); | ||
| 12 | |||
diff --git a/doc/documentation/tutorial-examples/014.c b/doc/documentation/tutorial-examples/014.c deleted file mode 100644 index ce204f795..000000000 --- a/doc/documentation/tutorial-examples/014.c +++ /dev/null | |||
| @@ -1,9 +0,0 @@ | |||
| 1 | struct GNUNET_PEERSTORE_IterateContext * | ||
| 2 | GNUNET_PEERSTORE_iterate (struct GNUNET_PEERSTORE_Handle *h, | ||
| 3 | const char *sub_system, | ||
| 4 | const struct GNUNET_PeerIdentity *peer, | ||
| 5 | const char *key, | ||
| 6 | struct GNUNET_TIME_Relative timeout, | ||
| 7 | GNUNET_PEERSTORE_Processor callback, | ||
| 8 | void *callback_cls); | ||
| 9 | |||
diff --git a/doc/documentation/tutorial-examples/015.c b/doc/documentation/tutorial-examples/015.c deleted file mode 100644 index 0dd267e8e..000000000 --- a/doc/documentation/tutorial-examples/015.c +++ /dev/null | |||
| @@ -1,8 +0,0 @@ | |||
| 1 | struct GNUNET_PEERSTORE_WatchContext * | ||
| 2 | GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h, | ||
| 3 | const char *sub_system, | ||
| 4 | const struct GNUNET_PeerIdentity *peer, | ||
| 5 | const char *key, | ||
| 6 | GNUNET_PEERSTORE_Processor callback, | ||
| 7 | void *callback_cls); | ||
| 8 | |||
diff --git a/doc/documentation/tutorial-examples/016.c b/doc/documentation/tutorial-examples/016.c deleted file mode 100644 index d169da16d..000000000 --- a/doc/documentation/tutorial-examples/016.c +++ /dev/null | |||
| @@ -1,4 +0,0 @@ | |||
| 1 | void | ||
| 2 | GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext | ||
| 3 | *wc); | ||
| 4 | |||
diff --git a/doc/documentation/tutorial-examples/017.c b/doc/documentation/tutorial-examples/017.c deleted file mode 100644 index c86fbcd1f..000000000 --- a/doc/documentation/tutorial-examples/017.c +++ /dev/null | |||
| @@ -1,4 +0,0 @@ | |||
| 1 | void | ||
| 2 | GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, | ||
| 3 | int sync_first); | ||
| 4 | |||
diff --git a/doc/documentation/tutorial-examples/018.c b/doc/documentation/tutorial-examples/018.c deleted file mode 100644 index 3fc22584c..000000000 --- a/doc/documentation/tutorial-examples/018.c +++ /dev/null | |||
| @@ -1,2 +0,0 @@ | |||
| 1 | dht_handle = GNUNET_DHT_connect (cfg, parallel_requests); | ||
| 2 | |||
diff --git a/doc/documentation/tutorial-examples/019.c b/doc/documentation/tutorial-examples/019.c deleted file mode 100644 index aaf001516..000000000 --- a/doc/documentation/tutorial-examples/019.c +++ /dev/null | |||
| @@ -1,18 +0,0 @@ | |||
| 1 | message_sent_cont (void *cls, | ||
| 2 | const struct GNUNET_SCHEDULER_TaskContext *tc) | ||
| 3 | { | ||
| 4 | // Request has left local node | ||
| 5 | } | ||
| 6 | |||
| 7 | struct GNUNET_DHT_PutHandle * | ||
| 8 | GNUNET_DHT_put (struct GNUNET_DHT_Handle *handle, | ||
| 9 | const struct GNUNET_HashCode *key, | ||
| 10 | uint32_t desired_replication_level, | ||
| 11 | enum GNUNET_DHT_RouteOption options, | ||
| 12 | enum GNUNET_BLOCK_Type type, | ||
| 13 | size_t size, | ||
| 14 | const void *data, | ||
| 15 | struct GNUNET_TIME_Absolute exp, | ||
| 16 | struct GNUNET_TIME_Relative timeout, | ||
| 17 | GNUNET_DHT_PutContinuation cont, void *cont_cls) | ||
| 18 | |||
diff --git a/doc/documentation/tutorial-examples/020.c b/doc/documentation/tutorial-examples/020.c deleted file mode 100644 index 596db3069..000000000 --- a/doc/documentation/tutorial-examples/020.c +++ /dev/null | |||
| @@ -1,25 +0,0 @@ | |||
| 1 | static void | ||
| 2 | get_result_iterator (void *cls, struct GNUNET_TIME_Absolute expiration, | ||
| 3 | const struct GNUNET_HashCode *key, | ||
| 4 | const struct GNUNET_PeerIdentity *get_path, | ||
| 5 | unsigned int get_path_length, | ||
| 6 | const struct GNUNET_PeerIdentity *put_path, | ||
| 7 | unsigned int put_path_length, | ||
| 8 | enum GNUNET_BLOCK_Type type, size_t size, | ||
| 9 | const void *data) | ||
| 10 | { | ||
| 11 | // Optionally: | ||
| 12 | GNUNET_DHT_get_stop (get_handle); | ||
| 13 | } | ||
| 14 | |||
| 15 | get_handle = | ||
| 16 | GNUNET_DHT_get_start (dht_handle, | ||
| 17 | block_type, | ||
| 18 | &key, | ||
| 19 | replication, | ||
| 20 | GNUNET_DHT_RO_NONE, | ||
| 21 | NULL, | ||
| 22 | 0, | ||
| 23 | &get_result_iterator, | ||
| 24 | cls) | ||
| 25 | |||
diff --git a/doc/documentation/tutorial-examples/021.c b/doc/documentation/tutorial-examples/021.c deleted file mode 100644 index 688a31fe0..000000000 --- a/doc/documentation/tutorial-examples/021.c +++ /dev/null | |||
| @@ -1,13 +0,0 @@ | |||
| 1 | static enum GNUNET_BLOCK_EvaluationResult | ||
| 2 | block_plugin_SERVICE_evaluate (void *cls, | ||
| 3 | enum GNUNET_BLOCK_Type type, | ||
| 4 | struct GNUNET_BlockGroup *bg, | ||
| 5 | const GNUNET_HashCode *query, | ||
| 6 | const void *xquery, | ||
| 7 | size_t xquery_size, | ||
| 8 | const void *reply_block, | ||
| 9 | size_t reply_block_size) | ||
| 10 | { | ||
| 11 | // Verify type, block and bg | ||
| 12 | } | ||
| 13 | |||
diff --git a/doc/documentation/tutorial-examples/022.c b/doc/documentation/tutorial-examples/022.c deleted file mode 100644 index a373619bd..000000000 --- a/doc/documentation/tutorial-examples/022.c +++ /dev/null | |||
| @@ -1,8 +0,0 @@ | |||
| 1 | static int | ||
| 2 | block_plugin_SERVICE_get_key (void *cls, enum GNUNET_BLOCK_Type type, | ||
| 3 | const void *block, size_t block_size, | ||
| 4 | struct GNUNET_HashCode *key) | ||
| 5 | { | ||
| 6 | // Store the key in the key argument, return GNUNET_OK on success. | ||
| 7 | } | ||
| 8 | |||
diff --git a/doc/documentation/tutorial-examples/023.c b/doc/documentation/tutorial-examples/023.c deleted file mode 100644 index 820c38b10..000000000 --- a/doc/documentation/tutorial-examples/023.c +++ /dev/null | |||
| @@ -1,17 +0,0 @@ | |||
| 1 | void * | ||
| 2 | libgnunet_plugin_block_SERVICE_init (void *cls) | ||
| 3 | { | ||
| 4 | static enum GNUNET_BLOCK_Type types[] = | ||
| 5 | { | ||
| 6 | GNUNET_BLOCK_TYPE_SERVICE_BLOCKYPE, | ||
| 7 | GNUNET_BLOCK_TYPE_ANY | ||
| 8 | }; | ||
| 9 | struct GNUNET_BLOCK_PluginFunctions *api; | ||
| 10 | |||
| 11 | api = GNUNET_new (struct GNUNET_BLOCK_PluginFunctions); | ||
| 12 | api->evaluate = &block_plugin_SERICE_evaluate; | ||
| 13 | api->get_key = &block_plugin_SERVICE_get_key; | ||
| 14 | api->types = types; | ||
| 15 | return api; | ||
| 16 | } | ||
| 17 | |||
diff --git a/doc/documentation/tutorial-examples/024.c b/doc/documentation/tutorial-examples/024.c deleted file mode 100644 index 2e84b5905..000000000 --- a/doc/documentation/tutorial-examples/024.c +++ /dev/null | |||
| @@ -1,9 +0,0 @@ | |||
| 1 | void * | ||
| 2 | libgnunet_plugin_block_SERVICE_done (void *cls) | ||
| 3 | { | ||
| 4 | struct GNUNET_TRANSPORT_PluginFunctions *api = cls; | ||
| 5 | |||
| 6 | GNUNET_free (api); | ||
| 7 | return NULL; | ||
| 8 | } | ||
| 9 | |||
diff --git a/doc/documentation/tutorial-examples/025.Makefile.am b/doc/documentation/tutorial-examples/025.Makefile.am deleted file mode 100644 index 66d4f80ec..000000000 --- a/doc/documentation/tutorial-examples/025.Makefile.am +++ /dev/null | |||
| @@ -1,15 +0,0 @@ | |||
| 1 | plugindir = $(libdir)/gnunet | ||
| 2 | |||
| 3 | plugin_LTLIBRARIES = \ | ||
| 4 | libgnunet_plugin_block_ext.la | ||
| 5 | libgnunet_plugin_block_ext_la_SOURCES = \ | ||
| 6 | plugin_block_ext.c | ||
| 7 | libgnunet_plugin_block_ext_la_LIBADD = \ | ||
| 8 | $(prefix)/lib/libgnunethello.la \ | ||
| 9 | $(prefix)/lib/libgnunetblock.la \ | ||
| 10 | $(prefix)/lib/libgnunetutil.la | ||
| 11 | libgnunet_plugin_block_ext_la_LDFLAGS = \ | ||
| 12 | $(GN_PLUGIN_LDFLAGS) | ||
| 13 | libgnunet_plugin_block_ext_la_DEPENDENCIES = \ | ||
| 14 | $(prefix)/lib/libgnunetblock.la | ||
| 15 | |||
diff --git a/doc/documentation/tutorial-examples/026.c b/doc/documentation/tutorial-examples/026.c deleted file mode 100644 index 264e0b6b9..000000000 --- a/doc/documentation/tutorial-examples/026.c +++ /dev/null | |||
| @@ -1,52 +0,0 @@ | |||
| 1 | static void | ||
| 2 | get_callback (void *cls, | ||
| 3 | enum GNUNET_DHT_RouteOption options, | ||
| 4 | enum GNUNET_BLOCK_Type type, | ||
| 5 | uint32_t hop_count, | ||
| 6 | uint32_t desired_replication_level, | ||
| 7 | unsigned int path_length, | ||
| 8 | const struct GNUNET_PeerIdentity *path, | ||
| 9 | const struct GNUNET_HashCode * key) | ||
| 10 | { | ||
| 11 | } | ||
| 12 | |||
| 13 | |||
| 14 | static void | ||
| 15 | get_resp_callback (void *cls, | ||
| 16 | enum GNUNET_BLOCK_Type type, | ||
| 17 | const struct GNUNET_PeerIdentity *get_path, | ||
| 18 | unsigned int get_path_length, | ||
| 19 | const struct GNUNET_PeerIdentity *put_path, | ||
| 20 | unsigned int put_path_length, | ||
| 21 | struct GNUNET_TIME_Absolute exp, | ||
| 22 | const struct GNUNET_HashCode * key, | ||
| 23 | const void *data, | ||
| 24 | size_t size) | ||
| 25 | { | ||
| 26 | } | ||
| 27 | |||
| 28 | |||
| 29 | static void | ||
| 30 | put_callback (void *cls, | ||
| 31 | enum GNUNET_DHT_RouteOption options, | ||
| 32 | enum GNUNET_BLOCK_Type type, | ||
| 33 | uint32_t hop_count, | ||
| 34 | uint32_t desired_replication_level, | ||
| 35 | unsigned int path_length, | ||
| 36 | const struct GNUNET_PeerIdentity *path, | ||
| 37 | struct GNUNET_TIME_Absolute exp, | ||
| 38 | const struct GNUNET_HashCode * key, | ||
| 39 | const void *data, | ||
| 40 | size_t size) | ||
| 41 | { | ||
| 42 | } | ||
| 43 | |||
| 44 | |||
| 45 | monitor_handle = GNUNET_DHT_monitor_start (dht_handle, | ||
| 46 | block_type, | ||
| 47 | key, | ||
| 48 | &get_callback, | ||
| 49 | &get_resp_callback, | ||
| 50 | &put_callback, | ||
| 51 | cls); | ||
| 52 | |||
