diff options
Diffstat (limited to 'doc')
70 files changed, 5954 insertions, 3676 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index c56a90359..b12f3e008 100644 --- a/doc/.gitignore +++ b/doc/.gitignore | |||
@@ -19,4 +19,4 @@ gnunet.t2p/ | |||
19 | gnunet-c-tutorial.t2p/ | 19 | gnunet-c-tutorial.t2p/ |
20 | *.t2p/ | 20 | *.t2p/ |
21 | documentation/manuals | 21 | documentation/manuals |
22 | .\#* \ No newline at end of file | 22 | .\#*doxygen/gnunet.tag |
diff --git a/doc/Makefile.am b/doc/Makefile.am index 28db606c5..f60bde084 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am | |||
@@ -7,4 +7,5 @@ if !DOCUMENTATION | |||
7 | endif | 7 | endif |
8 | 8 | ||
9 | EXTRA_DIST = \ | 9 | EXTRA_DIST = \ |
10 | outdated-and-old-installation-instructions.txt | 10 | system_specific/outdated-and-old-installation-instructions.txt \ |
11 | system_specific/FROM_SOURCE | ||
diff --git a/doc/documentation/.gitignore b/doc/documentation/.gitignore index 2e914d9c9..f490c3412 100644 --- a/doc/documentation/.gitignore +++ b/doc/documentation/.gitignore | |||
@@ -1,2 +1,9 @@ | |||
1 | stamp-1 | 1 | stamp-1 |
2 | version2.texi | 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 index 991b1926b..b6c666c4d 100644 --- a/doc/documentation/Makefile.am +++ b/doc/documentation/Makefile.am | |||
@@ -19,7 +19,6 @@ dist_infoimage_DATA = \ | |||
19 | images/gnunet-0-10-peerinfo.png \ | 19 | images/gnunet-0-10-peerinfo.png \ |
20 | images/gnunet-gtk-0-10-identity.png \ | 20 | images/gnunet-gtk-0-10-identity.png \ |
21 | images/gnunet-fs-gtk-0-10-star-tab.png \ | 21 | images/gnunet-fs-gtk-0-10-star-tab.png \ |
22 | images/gnunet-gtk-0-10.png \ | ||
23 | images/gnunet-gtk-0-10-download-area.png \ | 22 | images/gnunet-gtk-0-10-download-area.png \ |
24 | images/gnunet-gtk-0-10-search-selected.png \ | 23 | images/gnunet-gtk-0-10-search-selected.png \ |
25 | images/gnunet-gtk-0-10-fs-menu.png \ | 24 | images/gnunet-gtk-0-10-fs-menu.png \ |
@@ -44,7 +43,8 @@ dist_infoimage_DATA = \ | |||
44 | images/daemon_lego_block.svg \ | 43 | images/daemon_lego_block.svg \ |
45 | images/lego_stack.svg \ | 44 | images/lego_stack.svg \ |
46 | images/service_lego_block.svg \ | 45 | images/service_lego_block.svg \ |
47 | images/structure.dot | 46 | images/structure.dot \ |
47 | images/gns.dot | ||
48 | 48 | ||
49 | # images/$(wildcard *.png) \ | 49 | # images/$(wildcard *.png) \ |
50 | # images/$(wildcard *.svg) | 50 | # images/$(wildcard *.svg) |
@@ -112,9 +112,9 @@ info_TEXINFOS = \ | |||
112 | 112 | ||
113 | gnunet_TEXINFOS = \ | 113 | gnunet_TEXINFOS = \ |
114 | chapters/developer.texi \ | 114 | chapters/developer.texi \ |
115 | chapters/terminology.texi \ | 115 | chapters/preface.texi \ |
116 | chapters/installation.texi \ | ||
117 | chapters/philosophy.texi \ | 116 | chapters/philosophy.texi \ |
117 | chapters/installation.texi \ | ||
118 | chapters/user.texi \ | 118 | chapters/user.texi \ |
119 | chapters/vocabulary.texi \ | 119 | chapters/vocabulary.texi \ |
120 | chapters/configuration.texi \ | 120 | chapters/configuration.texi \ |
@@ -144,6 +144,7 @@ DISTCLEANFILES = \ | |||
144 | chapters/terminology.cps \ | 144 | chapters/terminology.cps \ |
145 | chapters/vocabulary.cps \ | 145 | chapters/vocabulary.cps \ |
146 | fdl-1.3.cps \ | 146 | fdl-1.3.cps \ |
147 | agpl-3.0.cps \ | ||
147 | gpl-3.0.cps | 148 | gpl-3.0.cps |
148 | 149 | ||
149 | # if HAVE_EXTENDED_DOCUMENTATION_BUILDING | 150 | # if HAVE_EXTENDED_DOCUMENTATION_BUILDING |
@@ -166,8 +167,8 @@ lego_stack.png: images/lego_stack.svg | |||
166 | # echo "@set EDITION $(PACKAGE_VERSION)" >> $@ | 167 | # echo "@set EDITION $(PACKAGE_VERSION)" >> $@ |
167 | # echo "@set VERSION $(PACKAGE_VERSION)" >> $@ | 168 | # echo "@set VERSION $(PACKAGE_VERSION)" >> $@ |
168 | 169 | ||
169 | # Workaround for makeinfo error. Whcih in turn introduces more | 170 | # Workaround for makeinfo error. Which in turn introduces more |
170 | # date-related 'warnings'. Well. | 171 | # date-related 'warnings' for GNUism. Well. |
171 | version2.texi: | 172 | version2.texi: |
172 | echo "@set UPDATED $(date +'%d %B %Y')" > $@ | 173 | echo "@set UPDATED $(date +'%d %B %Y')" > $@ |
173 | echo "@set UPDATED-MONTH $(date +'%B %Y')" >> $@ | 174 | echo "@set UPDATED-MONTH $(date +'%B %Y')" >> $@ |
diff --git a/doc/documentation/README.txt b/doc/documentation/README.txt deleted file mode 100644 index 9e76394c3..000000000 --- a/doc/documentation/README.txt +++ /dev/null | |||
@@ -1,63 +0,0 @@ | |||
1 | * Completion Levels: | ||
2 | |||
3 | ** chapters/philosophy: around 100% fixed after initial export. | ||
4 | |||
5 | * What's left to do | ||
6 | |||
7 | - Which Texlive modules are needed? Decrease the size. | ||
8 | - distro specific, or can we set requirements? | ||
9 | - Update the content of gnunet documentation. | ||
10 | - XXX: images are only generated for the html documentation | ||
11 | with gendoc.sh … FIXME! | ||
12 | - XXX: png,dot, and svg images MUST be converted to eps by the | ||
13 | build system. Right now they aren't, as a result: No images. | ||
14 | |||
15 | * How to use (hack) on this | ||
16 | |||
17 | ** with guix | ||
18 | |||
19 | Adjust accordingly, ie read the Guix Documentation: | ||
20 | setenv GUIX_PACKAGE_PATH "gnunet/contrib/packages/guix/packages" | ||
21 | guix environment gnunet-doc | ||
22 | and | ||
23 | guix build -f contrib/packages/guix/gnunet-doc.scm | ||
24 | |||
25 | ** without guix | ||
26 | |||
27 | You need to have Texinfo and Texlive in your path. | ||
28 | sh bootstrap | ||
29 | ./configure --enable-documentation | ||
30 | cd doc | ||
31 | make (format you want) | ||
32 | |||
33 | for example: make html, make info, make pdf | ||
34 | |||
35 | * structure (relations) | ||
36 | |||
37 | ** gnunet.texi | ||
38 | -> chapters/developer.texi | ||
39 | -> chapters/installation.texi | ||
40 | -> chapters/philosophy.texi | ||
41 | -> chapters/user.texi | ||
42 | -> chapters/vocabulary.texi | ||
43 | -> images/* | ||
44 | -> gpl-3.0.texi | ||
45 | -> fdl-1.3.texi | ||
46 | |||
47 | ** gnunet-c-tutorial.texi | ||
48 | -> figs/Service.pdf | ||
49 | -> figs/System.pdf | ||
50 | -> tutorial-examples/*.c | ||
51 | -> gpl-3.0.texi | ||
52 | -> fdl-1.3.texi | ||
53 | |||
54 | - gnunet-c-tutorial-v1.pdf: original LaTeX "gnunet-c-tutorial.pdf". | ||
55 | - man folder: the man pages. | ||
56 | - doxygen folder | ||
57 | - outdated-and-old-installation-instructions.txt: self described within the file. | ||
58 | |||
59 | |||
60 | Use `gendocs', add to the manual/ directory of the web site. | ||
61 | |||
62 | $ cd doc | ||
63 | $ gendocs.sh gnunet "GNUnet 0.10.X Reference Manual" | ||
diff --git a/doc/documentation/TODO b/doc/documentation/TODO new file mode 100644 index 000000000..fa1ce7a23 --- /dev/null +++ b/doc/documentation/TODO | |||
@@ -0,0 +1,106 @@ | |||
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 new file mode 100644 index 000000000..eabb0c6df --- /dev/null +++ b/doc/documentation/agpl-3.0.texi | |||
@@ -0,0 +1,698 @@ | |||
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/contributing.texi b/doc/documentation/chapters/contributing.texi index 745acca77..a92df45c3 100644 --- a/doc/documentation/chapters/contributing.texi +++ b/doc/documentation/chapters/contributing.texi | |||
@@ -6,17 +6,20 @@ | |||
6 | * Licenses of contributions:: | 6 | * Licenses of contributions:: |
7 | * Copyright Assignment:: | 7 | * Copyright Assignment:: |
8 | * Contributing to the Reference Manual:: | 8 | * Contributing to the Reference Manual:: |
9 | * Contributing testcases:: | ||
9 | @end menu | 10 | @end menu |
10 | 11 | ||
11 | @node Contributing to GNUnet | 12 | @node Contributing to GNUnet |
12 | @section Contributing to GNUnet | 13 | @section Contributing to GNUnet |
13 | 14 | ||
15 | @cindex licenses | ||
16 | @cindex licenses of contributions | ||
14 | @node Licenses of contributions | 17 | @node Licenses of contributions |
15 | @section Licenses of contributions | 18 | @section Licenses of contributions |
16 | 19 | ||
17 | GNUnet is a @uref{https://www.gnu.org/, GNU} package. | 20 | GNUnet is a @uref{https://www.gnu.org/, GNU} package. |
18 | All code contributions must thus be put under the | 21 | All code contributions must thus be put under the |
19 | @uref{https://www.gnu.org/copyleft/gpl.html, GNU Public License (GPL)}. | 22 | @uref{https://www.gnu.org/licenses/agpl.html, GNU Affero Public License (AGPL)}. |
20 | All documentation should be put under FSF approved licenses | 23 | All documentation should be put under FSF approved licenses |
21 | (see @uref{https://www.gnu.org/copyleft/fdl.html, fdl}). | 24 | (see @uref{https://www.gnu.org/copyleft/fdl.html, fdl}). |
22 | 25 | ||
@@ -40,7 +43,7 @@ rights, and in particular is allowed to dual-license the code. You | |||
40 | retain non-exclusive rights to your contributions, so you can also | 43 | retain non-exclusive rights to your contributions, so you can also |
41 | share your contributions freely with other projects. | 44 | share your contributions freely with other projects. |
42 | 45 | ||
43 | GNUnet e.V. will publish all accepted contributions under the GPLv3 | 46 | GNUnet e.V. will publish all accepted contributions under the AGPLv3 |
44 | or any later version. The association may decide to publish | 47 | or any later version. The association may decide to publish |
45 | contributions under additional licenses (dual-licensing). | 48 | contributions under additional licenses (dual-licensing). |
46 | 49 | ||
@@ -88,3 +91,21 @@ In a 200+ pages handbook it's better to have footnotes accessible | |||
88 | without having to skip over to the end. | 91 | without having to skip over to the end. |
89 | 92 | ||
90 | @end itemize | 93 | @end itemize |
94 | |||
95 | @node Contributing testcases | ||
96 | @section Contributing testcases | ||
97 | |||
98 | In the core of gnunet, we restrict new testcases to a small subset | ||
99 | of languages, in order of preference: | ||
100 | @enumerate | ||
101 | @item C | ||
102 | @item Bash (preferable portable without too much specifics to Bash) | ||
103 | @item Python (@geq{}3.6) | ||
104 | @end enumerate | ||
105 | |||
106 | We welcome efforts to remove our existing python-2.7 scripts to | ||
107 | replace them either with Bash or, at your choice, python-3.6+. | ||
108 | |||
109 | If you contribute new python based testcases, we advise you to | ||
110 | not repeat our past misfortunes and write the tests in a standard | ||
111 | test framework like for example pytest. | ||
diff --git a/doc/documentation/chapters/developer.texi b/doc/documentation/chapters/developer.texi index e95355302..e82e32b59 100644 --- a/doc/documentation/chapters/developer.texi +++ b/doc/documentation/chapters/developer.texi | |||
@@ -11,7 +11,7 @@ For developers, GNUnet is: | |||
11 | @itemize @bullet | 11 | @itemize @bullet |
12 | @item developed by a community that believes in the GNU philosophy | 12 | @item developed by a community that believes in the GNU philosophy |
13 | @item Free Software (Free as in Freedom), licensed under the | 13 | @item Free Software (Free as in Freedom), licensed under the |
14 | GNU General Public License@footnote{@uref{https://www.gnu.org/licenses/licenses.html#GPL, https://www.gnu.org/licenses/licenses.html#GPL}} | 14 | GNU Affero General Public License@footnote{@uref{https://www.gnu.org/licenses/licenses.html#AGPL, https://www.gnu.org/licenses/licenses.html#AGPL}} |
15 | @item A set of standards, including coding conventions and | 15 | @item A set of standards, including coding conventions and |
16 | architectural rules | 16 | architectural rules |
17 | @item A set of layered protocols, both specifying the communication | 17 | @item A set of layered protocols, both specifying the communication |
@@ -40,6 +40,7 @@ new chapters, sections or insightful comments. | |||
40 | 40 | ||
41 | @menu | 41 | @menu |
42 | * Developer Introduction:: | 42 | * Developer Introduction:: |
43 | * Internal dependencies:: | ||
43 | * Code overview:: | 44 | * Code overview:: |
44 | * System Architecture:: | 45 | * System Architecture:: |
45 | * Subsystem stability:: | 46 | * Subsystem stability:: |
@@ -47,6 +48,7 @@ new chapters, sections or insightful comments. | |||
47 | * Build-system:: | 48 | * Build-system:: |
48 | * Developing extensions for GNUnet using the gnunet-ext template:: | 49 | * Developing extensions for GNUnet using the gnunet-ext template:: |
49 | * Writing testcases:: | 50 | * Writing testcases:: |
51 | * Building GNUnet and its dependencies:: | ||
50 | * TESTING library:: | 52 | * TESTING library:: |
51 | * Performance regression analysis with Gauger:: | 53 | * Performance regression analysis with Gauger:: |
52 | * TESTBED Subsystem:: | 54 | * TESTBED Subsystem:: |
@@ -212,9 +214,7 @@ Installation and update tool | |||
212 | Template for starting 'external' GNUnet projects | 214 | Template for starting 'external' GNUnet projects |
213 | @item @command{gnunet-java} | 215 | @item @command{gnunet-java} |
214 | Java APIs for writing GNUnet services and applications | 216 | Java APIs for writing GNUnet services and applications |
215 | @c ** FIXME: Point to new website repository once we have it: | 217 | @item @command{gnunet-java-ext} |
216 | @c ** @item svn/gnunet-www/ Code and media helping drive the GNUnet | ||
217 | @c website | ||
218 | @item @command{eclectic} | 218 | @item @command{eclectic} |
219 | Code to run GNUnet nodes on testbeds for research, development, | 219 | Code to run GNUnet nodes on testbeds for research, development, |
220 | testing and evaluation | 220 | testing and evaluation |
@@ -225,6 +225,8 @@ Qt-based GNUnet GUI (is it deprecated?) | |||
225 | cocoa-based GNUnet GUI (is it deprecated?) | 225 | cocoa-based GNUnet GUI (is it deprecated?) |
226 | @item @command{gnunet-guile} | 226 | @item @command{gnunet-guile} |
227 | Guile bindings for GNUnet | 227 | Guile bindings for GNUnet |
228 | @item @command{gnunet-python} | ||
229 | Python bindings for GNUnet | ||
228 | 230 | ||
229 | @end table | 231 | @end table |
230 | 232 | ||
@@ -244,6 +246,13 @@ Tool for automated debugging of distributed systems | |||
244 | Library for accessing satellite connection quality reports | 246 | Library for accessing satellite connection quality reports |
245 | @item @command{libgnurl} | 247 | @item @command{libgnurl} |
246 | gnURL (feature-restricted variant of cURL/libcurl) | 248 | gnURL (feature-restricted variant of cURL/libcurl) |
249 | @item @command{www} | ||
250 | work in progress of the new gnunet.org website (Jinja2 framework based to | ||
251 | replace our current Drupal website) | ||
252 | @item @command{bibliography} | ||
253 | Our collected bibliography, papers, references, and so forth | ||
254 | @item @command{gnunet-videos-} | ||
255 | Videos about and around gnunet activities | ||
247 | @end table | 256 | @end table |
248 | 257 | ||
249 | Finally, there are various external projects (see links for a list of | 258 | Finally, there are various external projects (see links for a list of |
@@ -251,6 +260,77 @@ those that have a public website) which build on top of the GNUnet | |||
251 | framework. | 260 | framework. |
252 | 261 | ||
253 | @c *********************************************************************** | 262 | @c *********************************************************************** |
263 | @node Internal dependencies | ||
264 | @section Internal dependencies | ||
265 | |||
266 | This section tries to give an overview of what processes a typical GNUnet | ||
267 | peer running a particular application would consist of. All of the | ||
268 | processes listed here should be automatically started by | ||
269 | @command{gnunet-arm -s}. | ||
270 | The list is given as a rough first guide to users for failure diagnostics. | ||
271 | Ideally, end-users should never have to worry about these internal | ||
272 | dependencies. | ||
273 | |||
274 | In terms of internal dependencies, a minimum file-sharing system consists | ||
275 | of the following GNUnet processes (in order of dependency): | ||
276 | |||
277 | @itemize @bullet | ||
278 | @item gnunet-service-arm | ||
279 | @item gnunet-service-resolver (required by all) | ||
280 | @item gnunet-service-statistics (required by all) | ||
281 | @item gnunet-service-peerinfo | ||
282 | @item gnunet-service-transport (requires peerinfo) | ||
283 | @item gnunet-service-core (requires transport) | ||
284 | @item gnunet-daemon-hostlist (requires core) | ||
285 | @item gnunet-daemon-topology (requires hostlist, peerinfo) | ||
286 | @item gnunet-service-datastore | ||
287 | @item gnunet-service-dht (requires core) | ||
288 | @item gnunet-service-identity | ||
289 | @item gnunet-service-fs (requires identity, mesh, dht, datastore, core) | ||
290 | @end itemize | ||
291 | |||
292 | @noindent | ||
293 | A minimum VPN system consists of the following GNUnet processes (in | ||
294 | order of dependency): | ||
295 | |||
296 | @itemize @bullet | ||
297 | @item gnunet-service-arm | ||
298 | @item gnunet-service-resolver (required by all) | ||
299 | @item gnunet-service-statistics (required by all) | ||
300 | @item gnunet-service-peerinfo | ||
301 | @item gnunet-service-transport (requires peerinfo) | ||
302 | @item gnunet-service-core (requires transport) | ||
303 | @item gnunet-daemon-hostlist (requires core) | ||
304 | @item gnunet-service-dht (requires core) | ||
305 | @item gnunet-service-mesh (requires dht, core) | ||
306 | @item gnunet-service-dns (requires dht) | ||
307 | @item gnunet-service-regex (requires dht) | ||
308 | @item gnunet-service-vpn (requires regex, dns, mesh, dht) | ||
309 | @end itemize | ||
310 | |||
311 | @noindent | ||
312 | A minimum GNS system consists of the following GNUnet processes (in | ||
313 | order of dependency): | ||
314 | |||
315 | @itemize @bullet | ||
316 | @item gnunet-service-arm | ||
317 | @item gnunet-service-resolver (required by all) | ||
318 | @item gnunet-service-statistics (required by all) | ||
319 | @item gnunet-service-peerinfo | ||
320 | @item gnunet-service-transport (requires peerinfo) | ||
321 | @item gnunet-service-core (requires transport) | ||
322 | @item gnunet-daemon-hostlist (requires core) | ||
323 | @item gnunet-service-dht (requires core) | ||
324 | @item gnunet-service-mesh (requires dht, core) | ||
325 | @item gnunet-service-dns (requires dht) | ||
326 | @item gnunet-service-regex (requires dht) | ||
327 | @item gnunet-service-vpn (requires regex, dns, mesh, dht) | ||
328 | @item gnunet-service-identity | ||
329 | @item gnunet-service-namestore (requires identity) | ||
330 | @item gnunet-service-gns (requires vpn, dns, dht, namestore, identity) | ||
331 | @end itemize | ||
332 | |||
333 | @c *********************************************************************** | ||
254 | @node Code overview | 334 | @node Code overview |
255 | @section Code overview | 335 | @section Code overview |
256 | 336 | ||
@@ -279,7 +359,7 @@ The DHT and other components of GNUnet | |||
279 | store information in units called 'blocks'. Each block has a type and the | 359 | store information in units called 'blocks'. Each block has a type and the |
280 | type defines a particular format and how that binary format is to be | 360 | type defines a particular format and how that binary format is to be |
281 | linked to a hash code (the key for the DHT and for databases). The block | 361 | linked to a hash code (the key for the DHT and for databases). The block |
282 | library is a wapper around block plugins which provide the necessary | 362 | library is a wrapper around block plugins which provide the necessary |
283 | functions for each block type. | 363 | functions for each block type. |
284 | @item @file{statistics/} --- statistics service | 364 | @item @file{statistics/} --- statistics service |
285 | The statistics service enables associating | 365 | The statistics service enables associating |
@@ -327,7 +407,7 @@ external service to test the local configuration. | |||
327 | Some transports (UDP and WLAN, mostly) have restrictions on the maximum | 407 | Some transports (UDP and WLAN, mostly) have restrictions on the maximum |
328 | transfer unit (MTU) for packets. The fragmentation library can be used to | 408 | transfer unit (MTU) for packets. The fragmentation library can be used to |
329 | break larger packets into chunks of at most 1k and transmit the resulting | 409 | break larger packets into chunks of at most 1k and transmit the resulting |
330 | fragments reliabily (with acknowledgement, retransmission, timeouts, | 410 | fragments reliably (with acknowledgment, retransmission, timeouts, |
331 | etc.). | 411 | etc.). |
332 | @item @file{transport/} --- transport service | 412 | @item @file{transport/} --- transport service |
333 | The transport service is responsible for managing the | 413 | The transport service is responsible for managing the |
@@ -352,8 +432,8 @@ the foundation for the testbed service | |||
352 | @item @file{testbed/} --- testbed service | 432 | @item @file{testbed/} --- testbed service |
353 | The testbed service is used for creating small or large scale deployments | 433 | The testbed service is used for creating small or large scale deployments |
354 | of GNUnet peers for evaluation of protocols. | 434 | of GNUnet peers for evaluation of protocols. |
355 | It facilitates peer depolyments on multiple | 435 | It facilitates peer deployments on multiple |
356 | hosts (for example, in a cluster) and establishing varous network | 436 | hosts (for example, in a cluster) and establishing various network |
357 | topologies (both underlay and overlay). | 437 | topologies (both underlay and overlay). |
358 | @item @file{nse/} --- Network Size Estimation | 438 | @item @file{nse/} --- Network Size Estimation |
359 | The network size estimation (NSE) service | 439 | The network size estimation (NSE) service |
@@ -965,7 +1045,7 @@ if (0 == bar && x != y) | |||
965 | @end example | 1045 | @end example |
966 | 1046 | ||
967 | @noindent | 1047 | @noindent |
968 | Note that splitting the @code{if} statement above is debateable as the | 1048 | Note that splitting the @code{if} statement above is debatable as the |
969 | @code{return x} is a very trivial statement. However, once the logic after | 1049 | @code{return x} is a very trivial statement. However, once the logic after |
970 | the branch becomes more complicated (and is still identical), the "or" | 1050 | the branch becomes more complicated (and is still identical), the "or" |
971 | formulation should be used for sure. | 1051 | formulation should be used for sure. |
@@ -1089,6 +1169,313 @@ typically necessary to run @code{make install} before running any | |||
1089 | testcases. Thus the canonical command @code{make check install} has to be | 1169 | testcases. Thus the canonical command @code{make check install} has to be |
1090 | changed to @code{make install check} for GNUnet. | 1170 | changed to @code{make install check} for GNUnet. |
1091 | 1171 | ||
1172 | @c *********************************************************************** | ||
1173 | @cindex Building GNUnet | ||
1174 | @node Building GNUnet and its dependencies | ||
1175 | @section Building GNUnet and its dependencies | ||
1176 | |||
1177 | In the following section we will outline how to build GNUnet and | ||
1178 | some of its dependencies. We will assume a fair amount of knowledge | ||
1179 | for building applications under UNIX-like systems. Furthermore we | ||
1180 | assume that the build environment is sane and that you are aware of | ||
1181 | any implications actions in this process could have. | ||
1182 | Instructions here can be seen as notes for developers (an extension to | ||
1183 | the 'HACKING' section in README) as well as package maintainers. | ||
1184 | @b{Users should rely on the available binary packages.} | ||
1185 | We will use Debian as an example Operating System environment. Substitute | ||
1186 | accordingly with your own Operating System environment. | ||
1187 | |||
1188 | For the full list of dependencies, consult the appropriate, up-to-date | ||
1189 | section in the @file{README} file. | ||
1190 | |||
1191 | First, we need to build or install (depending on your OS) the following | ||
1192 | packages. If you build them from source, build them in this exact order: | ||
1193 | |||
1194 | @example | ||
1195 | libgpgerror, libgcrypt, libnettle, libunbound, GnuTLS (with libunbound | ||
1196 | support) | ||
1197 | @end example | ||
1198 | |||
1199 | After we have build and installed those packages, we continue with | ||
1200 | packages closer to GNUnet in this step: libgnurl (our libcurl fork), | ||
1201 | GNU libmicrohttpd, and GNU libextractor. Again, if your package manager | ||
1202 | provides one of these packages, use the packages provided from it | ||
1203 | unless you have good reasons (package version too old, conflicts, etc). | ||
1204 | We advise against compiling widely used packages such as GnuTLS | ||
1205 | yourself if your OS provides a variant already unless you take care | ||
1206 | of maintenance of the packages then. | ||
1207 | |||
1208 | In the optimistic case, this command will give you all the dependencies: | ||
1209 | |||
1210 | @example | ||
1211 | sudo apt-get install libgnurl libmicrohttpd libextractor | ||
1212 | @end example | ||
1213 | |||
1214 | From experience we know that at the very least libgnurl is not | ||
1215 | available in some environments. You could substitute libgnurl | ||
1216 | with libcurl, but we recommend to install libgnurl, as it gives | ||
1217 | you a predefined libcurl with the small set GNUnet requires. In | ||
1218 | the past namespaces of libcurl and libgnurl were shared, which | ||
1219 | caused problems when you wanted to integrate both of them in one | ||
1220 | Operating System. This has been resolved, and they can be installed | ||
1221 | side by side now. | ||
1222 | |||
1223 | @cindex libgnurl | ||
1224 | @cindex compiling libgnurl | ||
1225 | GNUnet and some of its function depend on a limited subset of cURL/libcurl. | ||
1226 | Rather than trying to enforce a certain configuration on the world, we | ||
1227 | opted to maintain a microfork of it that ensures we can link against the | ||
1228 | right set of features. We called this specialized set of libcurl | ||
1229 | ``libgnurl''. It is fully ABI compatible with libcurl and currently used | ||
1230 | by GNUnet and some of its dependencies. | ||
1231 | |||
1232 | We download libgnurl and its digital signature from the GNU fileserver, | ||
1233 | assuming @env{TMPDIR} exists@footnote{It might be @file{/tmp}, @env{TMPDIR}, @env{TMP} or any other location. For consistency we assume @env{TMPDIR} points to @file{/tmp} for the remainder of this section.} | ||
1234 | |||
1235 | @example | ||
1236 | cd \$TMPDIR | ||
1237 | wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z | ||
1238 | wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z.sig | ||
1239 | @end example | ||
1240 | |||
1241 | Next, verify the digital signature of the file: | ||
1242 | |||
1243 | @example | ||
1244 | gpg --verify gnurl-7.60.0.tar.Z.sig | ||
1245 | @end example | ||
1246 | |||
1247 | If gpg fails, you might try with @command{gpg2} on your OS. If the error | ||
1248 | states that ``the key can not be found'' or it is unknown, you have to | ||
1249 | retrieve the key (A88C8ADD129828D7EAC02E52E22F9BBFEE348588) from a | ||
1250 | keyserver first: | ||
1251 | |||
1252 | @example | ||
1253 | gpg --keyserver pgp.mit.edu --recv-keys A88C8ADD129828D7EAC02E52E22F9BBFEE348588 | ||
1254 | @end example | ||
1255 | |||
1256 | and rerun the verification command. | ||
1257 | |||
1258 | libgnurl will require the following packages to be present at runtime: | ||
1259 | gnutls (with DANE support / libunbound), libidn, zlib and at compile time: | ||
1260 | libtool, groff, perl, pkg-config, and python 2.7. | ||
1261 | |||
1262 | Once you have verified that all the required packages are present on your | ||
1263 | system, we can proceed to compile libgnurl: | ||
1264 | |||
1265 | @example | ||
1266 | tar -xvf gnurl-7.60.0.tar.Z | ||
1267 | cd gnurl-7.60.0 | ||
1268 | sh configure --disable-ntlm-wb | ||
1269 | make | ||
1270 | make -C tests test | ||
1271 | sudo make install | ||
1272 | @end example | ||
1273 | |||
1274 | After you've compiled and installed libgnurl, we can proceed to building | ||
1275 | GNUnet. | ||
1276 | |||
1277 | |||
1278 | |||
1279 | |||
1280 | First, in addition to the GNUnet sources you might require downloading the | ||
1281 | latest version of various dependencies, depending on how recent the | ||
1282 | software versions in your distribution of GNU/Linux are. | ||
1283 | Most distributions do not include sufficiently recent versions of these | ||
1284 | dependencies. | ||
1285 | Thus, a typically installation on a "modern" GNU/Linux distribution | ||
1286 | requires you to install the following dependencies (ideally in this | ||
1287 | order): | ||
1288 | |||
1289 | @itemize @bullet | ||
1290 | @item libgpgerror and libgcrypt | ||
1291 | @item libnettle and libunbound (possibly from distribution), GnuTLS | ||
1292 | @item libgnurl (read the README) | ||
1293 | @item GNU libmicrohttpd | ||
1294 | @item GNU libextractor | ||
1295 | @end itemize | ||
1296 | |||
1297 | Make sure to first install the various mandatory and optional | ||
1298 | dependencies including development headers from your distribution. | ||
1299 | |||
1300 | Other dependencies that you should strongly consider to install is a | ||
1301 | database (MySQL, sqlite or Postgres). | ||
1302 | The following instructions will assume that you installed at least sqlite. | ||
1303 | For most distributions you should be able to find pre-build packages for | ||
1304 | the database. Again, make sure to install the client libraries @b{and} the | ||
1305 | respective development headers (if they are packaged separately) as well. | ||
1306 | |||
1307 | You can find specific, detailed instructions for installing of the | ||
1308 | dependencies (and possibly the rest of the GNUnet installation) in the | ||
1309 | platform-specific descriptions, which can be found in the Index. | ||
1310 | Please consult them now. | ||
1311 | If your distribution is not listed, please study the build | ||
1312 | instructions for Debian stable, carefully as you try to install the | ||
1313 | dependencies for your own distribution. | ||
1314 | Contributing additional instructions for further platforms is always | ||
1315 | appreciated. | ||
1316 | Please take in mind that operating system development tends to move at | ||
1317 | a rather fast speed. Due to this you should be aware that some of | ||
1318 | the instructions could be outdated by the time you are reading this. | ||
1319 | If you find a mistake, please tell us about it (or even better: send | ||
1320 | a patch to the documentation to fix it!). | ||
1321 | |||
1322 | Before proceeding further, please double-check the dependency list. | ||
1323 | Note that in addition to satisfying the dependencies, you might have to | ||
1324 | make sure that development headers for the various libraries are also | ||
1325 | installed. | ||
1326 | There maybe files for other distributions, or you might be able to find | ||
1327 | equivalent packages for your distribution. | ||
1328 | |||
1329 | While it is possible to build and install GNUnet without having root | ||
1330 | access, we will assume that you have full control over your system in | ||
1331 | these instructions. | ||
1332 | First, you should create a system user @emph{gnunet} and an additional | ||
1333 | group @emph{gnunetdns}. On the GNU/Linux distributions Debian and Ubuntu, | ||
1334 | type: | ||
1335 | |||
1336 | @example | ||
1337 | sudo adduser --system --home /var/lib/gnunet --group \ | ||
1338 | --disabled-password gnunet | ||
1339 | sudo addgroup --system gnunetdns | ||
1340 | @end example | ||
1341 | |||
1342 | @noindent | ||
1343 | On other Unixes and GNU systems, this should have the same effect: | ||
1344 | |||
1345 | @example | ||
1346 | sudo useradd --system --groups gnunet --home-dir /var/lib/gnunet | ||
1347 | sudo addgroup --system gnunetdns | ||
1348 | @end example | ||
1349 | |||
1350 | Now compile and install GNUnet using: | ||
1351 | |||
1352 | @example | ||
1353 | tar xvf gnunet-@value{VERSION}.tar.gz | ||
1354 | cd gnunet-@value{VERSION} | ||
1355 | ./configure --with-sudo=sudo --with-nssdir=/lib | ||
1356 | make | ||
1357 | sudo make install | ||
1358 | @end example | ||
1359 | |||
1360 | If you want to be able to enable DEBUG-level log messages, add | ||
1361 | @code{--enable-logging=verbose} to the end of the | ||
1362 | @command{./configure} command. | ||
1363 | @code{DEBUG}-level log messages are in English only and | ||
1364 | should only be useful for developers (or for filing | ||
1365 | really detailed bug reports). | ||
1366 | |||
1367 | @noindent | ||
1368 | Next, edit the file @file{/etc/gnunet.conf} to contain the following: | ||
1369 | |||
1370 | @example | ||
1371 | [arm] | ||
1372 | START_SYSTEM_SERVICES = YES | ||
1373 | START_USER_SERVICES = NO | ||
1374 | @end example | ||
1375 | |||
1376 | @noindent | ||
1377 | You may need to update your @code{ld.so} cache to include | ||
1378 | files installed in @file{/usr/local/lib}: | ||
1379 | |||
1380 | @example | ||
1381 | # ldconfig | ||
1382 | @end example | ||
1383 | |||
1384 | @noindent | ||
1385 | Then, switch from user @code{root} to user @code{gnunet} to start | ||
1386 | the peer: | ||
1387 | |||
1388 | @example | ||
1389 | # su -s /bin/sh - gnunet | ||
1390 | $ gnunet-arm -c /etc/gnunet.conf -s | ||
1391 | @end example | ||
1392 | |||
1393 | You may also want to add the last line in the gnunet user's @file{crontab} | ||
1394 | prefixed with @code{@@reboot} so that it is executed whenever the system | ||
1395 | is booted: | ||
1396 | |||
1397 | @example | ||
1398 | @@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s | ||
1399 | @end example | ||
1400 | |||
1401 | @noindent | ||
1402 | This will only start the system-wide GNUnet services. | ||
1403 | Type @command{exit} to get back your root shell. | ||
1404 | Now, you need to configure the per-user part. For each | ||
1405 | user that should get access to GNUnet on the system, run | ||
1406 | (replace alice with your username): | ||
1407 | |||
1408 | @example | ||
1409 | sudo adduser alice gnunet | ||
1410 | @end example | ||
1411 | |||
1412 | @noindent | ||
1413 | to allow them to access the system-wide GNUnet services. Then, each | ||
1414 | user should create a configuration file @file{~/.config/gnunet.conf} | ||
1415 | with the lines: | ||
1416 | |||
1417 | @example | ||
1418 | [arm] | ||
1419 | START_SYSTEM_SERVICES = NO | ||
1420 | START_USER_SERVICES = YES | ||
1421 | DEFAULTSERVICES = gns | ||
1422 | @end example | ||
1423 | |||
1424 | @noindent | ||
1425 | and start the per-user services using | ||
1426 | |||
1427 | @example | ||
1428 | $ gnunet-arm -c ~/.config/gnunet.conf -s | ||
1429 | @end example | ||
1430 | |||
1431 | @noindent | ||
1432 | Again, adding a @code{crontab} entry to autostart the peer is advised: | ||
1433 | |||
1434 | @example | ||
1435 | @@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s | ||
1436 | @end example | ||
1437 | |||
1438 | @noindent | ||
1439 | Note that some GNUnet services (such as SOCKS5 proxies) may need a | ||
1440 | system-wide TCP port for each user. | ||
1441 | For those services, systems with more than one user may require each user | ||
1442 | to specify a different port number in their personal configuration file. | ||
1443 | |||
1444 | Finally, the user should perform the basic initial setup for the GNU Name | ||
1445 | System (GNS) certificate authority. This is done by running: | ||
1446 | |||
1447 | @example | ||
1448 | $ gnunet-gns-proxy-setup-ca | ||
1449 | @end example | ||
1450 | |||
1451 | @noindent | ||
1452 | The first generates the default zones, whereas the second setups the GNS | ||
1453 | Certificate Authority with the user's browser. Now, to activate GNS in the | ||
1454 | normal DNS resolution process, you need to edit your | ||
1455 | @file{/etc/nsswitch.conf} where you should find a line like this: | ||
1456 | |||
1457 | @example | ||
1458 | hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 | ||
1459 | @end example | ||
1460 | |||
1461 | @noindent | ||
1462 | The exact details may differ a bit, which is fine. Add the text | ||
1463 | @emph{"gns [NOTFOUND=return]"} after @emph{"files"}. | ||
1464 | Keep in mind that we included a backslash ("\") here just for | ||
1465 | markup reasons. You should write the text below on @b{one line} | ||
1466 | and @b{without} the "\": | ||
1467 | |||
1468 | @example | ||
1469 | hosts: files gns [NOTFOUND=return] mdns4_minimal \ | ||
1470 | [NOTFOUND=return] dns mdns4 | ||
1471 | @end example | ||
1472 | |||
1473 | @c FIXME: Document new behavior. | ||
1474 | You might want to make sure that @file{/lib/libnss_gns.so.2} exists on | ||
1475 | your system, it should have been created during the installation. | ||
1476 | |||
1477 | |||
1478 | @c ********************************************************************** | ||
1092 | @cindex TESTING library | 1479 | @cindex TESTING library |
1093 | @node TESTING library | 1480 | @node TESTING library |
1094 | @section TESTING library | 1481 | @section TESTING library |
@@ -1156,7 +1543,7 @@ This range can be customised with the function | |||
1156 | similar to @code{GNUNET_TESTING_system_create()} except that it take 2 | 1543 | similar to @code{GNUNET_TESTING_system_create()} except that it take 2 |
1157 | additional parameters --- the start and end of the port range to use. | 1544 | additional parameters --- the start and end of the port range to use. |
1158 | 1545 | ||
1159 | A TESTING system is destroyed with the funciton | 1546 | A TESTING system is destroyed with the function |
1160 | @code{GNUNET_TESTING_system_destory()}. This function takes the handle of | 1547 | @code{GNUNET_TESTING_system_destory()}. This function takes the handle of |
1161 | the system and a flag to remove the files created in the directory used | 1548 | the system and a flag to remove the files created in the directory used |
1162 | to generate configurations. | 1549 | to generate configurations. |
@@ -1165,7 +1552,7 @@ A peer is created with the function | |||
1165 | @code{GNUNET_TESTING_peer_configure()}. This functions takes the system | 1552 | @code{GNUNET_TESTING_peer_configure()}. This functions takes the system |
1166 | handle, a configuration template from which the configuration for the peer | 1553 | handle, a configuration template from which the configuration for the peer |
1167 | is auto-generated and the index from where the hostkey for the peer has to | 1554 | is auto-generated and the index from where the hostkey for the peer has to |
1168 | be copied from. When successfull, this function returs a handle to the | 1555 | be copied from. When successful, this function returns a handle to the |
1169 | peer which can be used to start and stop it and to obtain the identity of | 1556 | peer which can be used to start and stop it and to obtain the identity of |
1170 | the peer. If unsuccessful, a NULL pointer is returned with an error | 1557 | the peer. If unsuccessful, a NULL pointer is returned with an error |
1171 | message. This function handles the generated configuration to have | 1558 | message. This function handles the generated configuration to have |
@@ -1199,7 +1586,7 @@ to the handle to the peer to stop. The callback function is called with | |||
1199 | the given closure when the peer is stopped. Using this function | 1586 | the given closure when the peer is stopped. Using this function |
1200 | eliminates blocking while waiting for the peer to terminate. | 1587 | eliminates blocking while waiting for the peer to terminate. |
1201 | 1588 | ||
1202 | An asynchronous peer stop can be cancelled by calling the function | 1589 | An asynchronous peer stop can be canceled by calling the function |
1203 | @code{GNUNET_TESTING_peer_stop_async_cancel()}. Note that calling this | 1590 | @code{GNUNET_TESTING_peer_stop_async_cancel()}. Note that calling this |
1204 | function does not prevent the peer from terminating if the termination | 1591 | function does not prevent the peer from terminating if the termination |
1205 | signal has already been sent to it. It does, however, cancels the | 1592 | signal has already been sent to it. It does, however, cancels the |
@@ -1280,12 +1667,12 @@ simply load the plugin directly. | |||
1280 | To help avoid performance regressions, GNUnet uses Gauger. Gauger is a | 1667 | To help avoid performance regressions, GNUnet uses Gauger. Gauger is a |
1281 | simple logging tool that allows remote hosts to send performance data to | 1668 | simple logging tool that allows remote hosts to send performance data to |
1282 | a central server, where this data can be analyzed and visualized. Gauger | 1669 | a central server, where this data can be analyzed and visualized. Gauger |
1283 | shows graphs of the repository revisions and the performace data recorded | 1670 | shows graphs of the repository revisions and the performance data recorded |
1284 | for each revision, so sudden performance peaks or drops can be identified | 1671 | for each revision, so sudden performance peaks or drops can be identified |
1285 | and linked to a specific revision number. | 1672 | and linked to a specific revision number. |
1286 | 1673 | ||
1287 | In the case of GNUnet, the buildbots log the performance data obtained | 1674 | In the case of GNUnet, the buildbots log the performance data obtained |
1288 | during the tests after each build. The data can be accesed on GNUnet's | 1675 | during the tests after each build. The data can be accessed on GNUnet's |
1289 | Gauger page. | 1676 | Gauger page. |
1290 | 1677 | ||
1291 | The menu on the left allows to select either the results of just one | 1678 | The menu on the left allows to select either the results of just one |
@@ -1298,7 +1685,7 @@ performance evolution across all hosts. | |||
1298 | Using Gauger in GNUnet and having the performance of a module tracked over | 1685 | Using Gauger in GNUnet and having the performance of a module tracked over |
1299 | time is very easy. First of course, the testcase must generate some | 1686 | time is very easy. First of course, the testcase must generate some |
1300 | consistent metric, which makes sense to have logged. Highly volatile or | 1687 | consistent metric, which makes sense to have logged. Highly volatile or |
1301 | random dependant metrics probably are not ideal candidates for meaningful | 1688 | random dependent metrics probably are not ideal candidates for meaningful |
1302 | regression detection. | 1689 | regression detection. |
1303 | 1690 | ||
1304 | To start logging any value, just include @code{gauger.h} in your testcase | 1691 | To start logging any value, just include @code{gauger.h} in your testcase |
@@ -1510,7 +1897,7 @@ random links are to be given | |||
1510 | 1897 | ||
1511 | @item @code{GNUNET_TESTBED_TOPOLOGY_SCALE_FREE}: Connects peers in a | 1898 | @item @code{GNUNET_TESTBED_TOPOLOGY_SCALE_FREE}: Connects peers in a |
1512 | topology where peer connectivity follows power law - new peers are | 1899 | topology where peer connectivity follows power law - new peers are |
1513 | connected with high probabililty to well connected peers. | 1900 | connected with high probability to well connected peers. |
1514 | @footnote{See Emergence of Scaling in Random Networks. Science 286, | 1901 | @footnote{See Emergence of Scaling in Random Networks. Science 286, |
1515 | 509-512, 1999 | 1902 | 509-512, 1999 |
1516 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/emergence_of_scaling_in_random_networks__barabasi_albert_science_286__1999.pdf, pdf})} | 1903 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/emergence_of_scaling_in_random_networks__barabasi_albert_science_286__1999.pdf, pdf})} |
@@ -1551,7 +1938,7 @@ ignored for the rest of the topologies. | |||
1551 | Topology @code{SCALE_FREE} requires the options | 1938 | Topology @code{SCALE_FREE} requires the options |
1552 | @code{SCALE_FREE_TOPOLOGY_CAP} to be set to the maximum number of peers | 1939 | @code{SCALE_FREE_TOPOLOGY_CAP} to be set to the maximum number of peers |
1553 | which can connect to a peer and @code{SCALE_FREE_TOPOLOGY_M} to be set to | 1940 | which can connect to a peer and @code{SCALE_FREE_TOPOLOGY_M} to be set to |
1554 | how many peers a peer should be atleast connected to. | 1941 | how many peers a peer should be at least connected to. |
1555 | 1942 | ||
1556 | Similarly, the topology @code{FROM_FILE} requires the option | 1943 | Similarly, the topology @code{FROM_FILE} requires the option |
1557 | @code{OVERLAY_TOPOLOGY_FILE} to contain the path of the file containing | 1944 | @code{OVERLAY_TOPOLOGY_FILE} to contain the path of the file containing |
@@ -1597,7 +1984,7 @@ A topology file describes how peers are to be connected. It should adhere | |||
1597 | to the following format for testbed to parse it correctly. | 1984 | to the following format for testbed to parse it correctly. |
1598 | 1985 | ||
1599 | Each line should begin with the target peer id. This should be followed by | 1986 | Each line should begin with the target peer id. This should be followed by |
1600 | a colon(`:') and origin peer ids seperated by `|'. All spaces except for | 1987 | a colon(`:') and origin peer ids separated by `|'. All spaces except for |
1601 | newline characters are ignored. The API will then try to connect each | 1988 | newline characters are ignored. The API will then try to connect each |
1602 | origin peer to the target peer. | 1989 | origin peer to the target peer. |
1603 | 1990 | ||
@@ -1623,9 +2010,9 @@ deemed as crossed after all the peers waiting on it are notified. | |||
1623 | The barriers API provides the following functions: | 2010 | The barriers API provides the following functions: |
1624 | @itemize @bullet | 2011 | @itemize @bullet |
1625 | @item @strong{@code{GNUNET_TESTBED_barrier_init()}:} function to | 2012 | @item @strong{@code{GNUNET_TESTBED_barrier_init()}:} function to |
1626 | initialse a barrier in the experiment | 2013 | initialize a barrier in the experiment |
1627 | @item @strong{@code{GNUNET_TESTBED_barrier_cancel()}:} function to cancel | 2014 | @item @strong{@code{GNUNET_TESTBED_barrier_cancel()}:} function to cancel |
1628 | a barrier which has been initialised before | 2015 | a barrier which has been initialized before |
1629 | @item @strong{@code{GNUNET_TESTBED_barrier_wait()}:} function to signal | 2016 | @item @strong{@code{GNUNET_TESTBED_barrier_wait()}:} function to signal |
1630 | barrier service that the caller has reached a barrier and is waiting for | 2017 | barrier service that the caller has reached a barrier and is waiting for |
1631 | it to be crossed | 2018 | it to be crossed |
@@ -1742,7 +2129,7 @@ the large-scale deployment. We provide you a set of scripts you can use | |||
1742 | to deploy GNUnet on a set of nodes and manage your installation. | 2129 | to deploy GNUnet on a set of nodes and manage your installation. |
1743 | 2130 | ||
1744 | Please also check @uref{https://gnunet.org/installation-fedora8-svn} and | 2131 | Please also check @uref{https://gnunet.org/installation-fedora8-svn} and |
1745 | @uref{https://gnunet.org/installation-fedora12-svn} to find detailled | 2132 | @uref{https://gnunet.org/installation-fedora12-svn} to find detailed |
1746 | instructions how to install GNUnet on a PlanetLab node. | 2133 | instructions how to install GNUnet on a PlanetLab node. |
1747 | 2134 | ||
1748 | 2135 | ||
@@ -1768,7 +2155,7 @@ image, installing the buildslave software is quite some pain. For our | |||
1768 | PlanetLab testbed we figured out how to install the buildslave software | 2155 | PlanetLab testbed we figured out how to install the buildslave software |
1769 | best. | 2156 | best. |
1770 | 2157 | ||
1771 | @c This is a vvery terrible way to suggest installing software. | 2158 | @c This is a very terrible way to suggest installing software. |
1772 | @c FIXME: Is there an official, safer way instead of blind-piping a | 2159 | @c FIXME: Is there an official, safer way instead of blind-piping a |
1773 | @c script? | 2160 | @c script? |
1774 | @c FIXME: Use newer pypi URLs below. | 2161 | @c FIXME: Use newer pypi URLs below. |
@@ -1917,15 +2304,15 @@ is to set | |||
1917 | 2304 | ||
1918 | @example | 2305 | @example |
1919 | [core] | 2306 | [core] |
1920 | FORCESTART = YES | 2307 | IMMEDIATE_START = YES |
1921 | @end example | 2308 | @end example |
1922 | 2309 | ||
1923 | @noindent | 2310 | @noindent |
1924 | in the configuration file. | 2311 | in the configuration file. |
1925 | Alternatively, having any service that directly or indirectly depends on | 2312 | Alternatively, having any service that directly or indirectly depends on |
1926 | @code{CORE} being started with @code{FORCESTART} will also do. | 2313 | @code{CORE} being started with @code{IMMEDIATE_START} will also do. |
1927 | This issue largely arises if users try to over-optimize by not | 2314 | This issue largely arises if users try to over-optimize by not |
1928 | starting any services with @code{FORCESTART}. | 2315 | starting any services with @code{IMMEDIATE_START}. |
1929 | 2316 | ||
1930 | @c *********************************************************************** | 2317 | @c *********************************************************************** |
1931 | @node ATS must want the connections | 2318 | @node ATS must want the connections |
@@ -1974,7 +2361,7 @@ for new developers): | |||
1974 | @item CPS-style scheduling (scheduler.c) | 2361 | @item CPS-style scheduling (scheduler.c) |
1975 | @item Program initialization (program.c) | 2362 | @item Program initialization (program.c) |
1976 | @item Networking (network.c, client.c, server*.c, service.c) | 2363 | @item Networking (network.c, client.c, server*.c, service.c) |
1977 | @item message queueing (mq.c) | 2364 | @item message queuing (mq.c) |
1978 | @item bandwidth calculations (bandwidth.c) | 2365 | @item bandwidth calculations (bandwidth.c) |
1979 | @item Other OS-related (os*.c, plugin.c, signal.c) | 2366 | @item Other OS-related (os*.c, plugin.c, signal.c) |
1980 | @item Pseudonym management (pseudonym.c) | 2367 | @item Pseudonym management (pseudonym.c) |
@@ -2045,7 +2432,7 @@ level to "loglevel". Thus it is possible to run some processes | |||
2045 | with -L DEBUG, for example, and others with -L ERROR to enable specific | 2432 | with -L DEBUG, for example, and others with -L ERROR to enable specific |
2046 | settings to diagnose problems with a particular process. | 2433 | settings to diagnose problems with a particular process. |
2047 | @item Configuration files. Because GNUnet | 2434 | @item Configuration files. Because GNUnet |
2048 | service and deamon processes are usually launched by gnunet-arm, it is not | 2435 | service and daemon processes are usually launched by gnunet-arm, it is not |
2049 | possible to pass different custom command line options directly to every | 2436 | possible to pass different custom command line options directly to every |
2050 | one of them. The options passed to @code{gnunet-arm} only affect | 2437 | one of them. The options passed to @code{gnunet-arm} only affect |
2051 | gnunet-arm and not the rest of GNUnet. However, one can specify a | 2438 | gnunet-arm and not the rest of GNUnet. However, one can specify a |
@@ -2337,7 +2724,7 @@ will have | |||
2337 | no effect. Other messages (ERROR, WARNING, INFO, etc) will be included. | 2724 | no effect. Other messages (ERROR, WARNING, INFO, etc) will be included. |
2338 | @item If @code{--enable-logging} is set to @code{verbose}, or | 2725 | @item If @code{--enable-logging} is set to @code{verbose}, or |
2339 | @code{veryverbose} the binary will contain DEBUG messages (still, it will | 2726 | @code{veryverbose} the binary will contain DEBUG messages (still, it will |
2340 | be neccessary to run with @command{-L DEBUG} or set the DEBUG config option | 2727 | be necessary to run with @command{-L DEBUG} or set the DEBUG config option |
2341 | to show | 2728 | to show |
2342 | them). | 2729 | them). |
2343 | @end itemize | 2730 | @end itemize |
@@ -2348,7 +2735,7 @@ If you are a developer: | |||
2348 | @item please make sure that you @code{./configure | 2735 | @item please make sure that you @code{./configure |
2349 | --enable-logging=@{verbose,veryverbose@}}, so you can see DEBUG messages. | 2736 | --enable-logging=@{verbose,veryverbose@}}, so you can see DEBUG messages. |
2350 | @item please remove the @code{#if} statements around @code{GNUNET_log | 2737 | @item please remove the @code{#if} statements around @code{GNUNET_log |
2351 | (GNUNET_ERROR_TYPE_DEBUG, ...)} lines, to improve the readibility of your | 2738 | (GNUNET_ERROR_TYPE_DEBUG, ...)} lines, to improve the readability of your |
2352 | code. | 2739 | code. |
2353 | @end itemize | 2740 | @end itemize |
2354 | 2741 | ||
@@ -2361,7 +2748,7 @@ A suitable configuration could be: | |||
2361 | $ export GNUNET_FORCE_LOG="^YOUR_SUBSYSTEM$;;;;DEBUG/;;;;WARNING" | 2748 | $ export GNUNET_FORCE_LOG="^YOUR_SUBSYSTEM$;;;;DEBUG/;;;;WARNING" |
2362 | @end example | 2749 | @end example |
2363 | 2750 | ||
2364 | Which will behave almost like enabling DEBUG in that subsytem before the | 2751 | Which will behave almost like enabling DEBUG in that subsystem before the |
2365 | change. Of course you can adapt it to your particular needs, this is only | 2752 | change. Of course you can adapt it to your particular needs, this is only |
2366 | a quick example. | 2753 | a quick example. |
2367 | 2754 | ||
@@ -2572,7 +2959,7 @@ function, which is set to @code{NULL} in most cases, and the last | |||
2572 | parameter is the expected size of the message of this type, usually we | 2959 | parameter is the expected size of the message of this type, usually we |
2573 | set it to 0 to accept variable size, for special cases the exact size of | 2960 | set it to 0 to accept variable size, for special cases the exact size of |
2574 | the specified message also can be set. In addition, the terminator sign | 2961 | the specified message also can be set. In addition, the terminator sign |
2575 | depicted as @code{@{NULL, NULL, 0, 0@}} is set in the last aera. | 2962 | depicted as @code{@{NULL, NULL, 0, 0@}} is set in the last area. |
2576 | 2963 | ||
2577 | @c *********************************************************************** | 2964 | @c *********************************************************************** |
2578 | @node Server - Process request message | 2965 | @node Server - Process request message |
@@ -2622,7 +3009,7 @@ understand the request message, and the processing of this request would | |||
2622 | be terminated. | 3009 | be terminated. |
2623 | 3010 | ||
2624 | In comparison to the aforementioned situation, when the argument is equal | 3011 | In comparison to the aforementioned situation, when the argument is equal |
2625 | to @code{GNUNET_OK}, the service would continue to process the requst | 3012 | to @code{GNUNET_OK}, the service would continue to process the request |
2626 | message. | 3013 | message. |
2627 | 3014 | ||
2628 | @c *********************************************************************** | 3015 | @c *********************************************************************** |
@@ -2771,7 +3158,7 @@ GNUnet uses SHA-512 for computing one-way hash codes. The API provides | |||
2771 | functions to compute a hash over a block in memory or over a file on disk. | 3158 | functions to compute a hash over a block in memory or over a file on disk. |
2772 | 3159 | ||
2773 | The crypto API also provides functions for randomizing a block of memory, | 3160 | The crypto API also provides functions for randomizing a block of memory, |
2774 | obtaining a single random number and for generating a permuation of the | 3161 | obtaining a single random number and for generating a permutation of the |
2775 | numbers 0 to n-1. Random number generation distinguishes between WEAK and | 3162 | numbers 0 to n-1. Random number generation distinguishes between WEAK and |
2776 | STRONG random number quality; WEAK random numbers are pseudo-random | 3163 | STRONG random number quality; WEAK random numbers are pseudo-random |
2777 | whereas STRONG random numbers use entropy gathered from the operating | 3164 | whereas STRONG random numbers use entropy gathered from the operating |
@@ -2850,7 +3237,7 @@ message. | |||
2850 | 3237 | ||
2851 | Consider the following simple message, with the body consisting of a | 3238 | Consider the following simple message, with the body consisting of a |
2852 | single number value. | 3239 | single number value. |
2853 | @c why the empy code function? | 3240 | @c why the empty code function? |
2854 | @code{} | 3241 | @code{} |
2855 | 3242 | ||
2856 | @example | 3243 | @example |
@@ -3125,7 +3512,7 @@ or in some other transient data structure and thus having the hash map | |||
3125 | keep a pointer to @code{key} would not work. Only the key inside of | 3512 | keep a pointer to @code{key} would not work. Only the key inside of |
3126 | @code{val} has the same lifetime as the entry in the map (this must of | 3513 | @code{val} has the same lifetime as the entry in the map (this must of |
3127 | course be checked as well). Naturally, @code{val->key} must be | 3514 | course be checked as well). Naturally, @code{val->key} must be |
3128 | intiialized before the @code{put} call. Once all @code{put} calls have | 3515 | initialized before the @code{put} call. Once all @code{put} calls have |
3129 | been converted and double-checked, you can change the call to create the | 3516 | been converted and double-checked, you can change the call to create the |
3130 | hash map from | 3517 | hash map from |
3131 | 3518 | ||
@@ -3322,10 +3709,10 @@ running a service with "valgrind" or "gdb" | |||
3322 | 3709 | ||
3323 | @item DEBUG Run in debug mode (much verbosity). | 3710 | @item DEBUG Run in debug mode (much verbosity). |
3324 | 3711 | ||
3325 | @item AUTOSTART ARM will listen to UNIX domain socket and/or TCP port of | 3712 | @item START_ON_DEMAND ARM will listen to UNIX domain socket and/or TCP port of |
3326 | the service and start the service on-demand. | 3713 | the service and start the service on-demand. |
3327 | 3714 | ||
3328 | @item FORCESTART ARM will always start this service when the peer | 3715 | @item IMMEDIATE_START ARM will always start this service when the peer |
3329 | is started. | 3716 | is started. |
3330 | 3717 | ||
3331 | @item ACCEPT_FROM IPv4 addresses the service accepts connections from. | 3718 | @item ACCEPT_FROM IPv4 addresses the service accepts connections from. |
@@ -3336,7 +3723,7 @@ is started. | |||
3336 | 3723 | ||
3337 | 3724 | ||
3338 | Options that impact the operation of ARM overall are in the "[arm]" | 3725 | Options that impact the operation of ARM overall are in the "[arm]" |
3339 | section. ARM is a normal service and has (except for AUTOSTART) all of the | 3726 | section. ARM is a normal service and has (except for START_ON_DEMAND) all of the |
3340 | options that other services do. In addition, ARM has the | 3727 | options that other services do. In addition, ARM has the |
3341 | following options: | 3728 | following options: |
3342 | 3729 | ||
@@ -3513,7 +3900,7 @@ The goal of transport-level address validation is to minimize the chances | |||
3513 | of a successful man-in-the-middle attack against GNUnet peers on the | 3900 | of a successful man-in-the-middle attack against GNUnet peers on the |
3514 | transport level. Such an attack would not allow the adversary to decrypt | 3901 | transport level. Such an attack would not allow the adversary to decrypt |
3515 | the P2P transmissions, but a successful attacker could at least measure | 3902 | the P2P transmissions, but a successful attacker could at least measure |
3516 | traffic volumes and latencies (raising the adversaries capablities by | 3903 | traffic volumes and latencies (raising the adversaries capabilities by |
3517 | those of a global passive adversary in the worst case). The scenarios we | 3904 | those of a global passive adversary in the worst case). The scenarios we |
3518 | are concerned about is an attacker, Mallory, giving a @code{HELLO} to | 3905 | are concerned about is an attacker, Mallory, giving a @code{HELLO} to |
3519 | Alice that claims to be for Bob, but contains Mallory's IP address | 3906 | Alice that claims to be for Bob, but contains Mallory's IP address |
@@ -3639,7 +4026,7 @@ connected peers, but they are sent about other knowns peers within the | |||
3639 | to each other about their appropriate other neighbors. They also gossip | 4026 | to each other about their appropriate other neighbors. They also gossip |
3640 | about the newly connected peer to previously | 4027 | about the newly connected peer to previously |
3641 | connected neighbors. In order to keep the routing tables up to date, | 4028 | connected neighbors. In order to keep the routing tables up to date, |
3642 | disconnect notifications are propogated as gossip as well (because | 4029 | disconnect notifications are propagated as gossip as well (because |
3643 | disconnects may not be sent/received, timeouts are also used remove | 4030 | disconnects may not be sent/received, timeouts are also used remove |
3644 | stagnant routing table entries). | 4031 | stagnant routing table entries). |
3645 | 4032 | ||
@@ -3830,7 +4217,7 @@ to send and receive messages. | |||
3830 | 4217 | ||
3831 | We have measured the performance of the UDP, TCP and SMTP transport layer | 4218 | We have measured the performance of the UDP, TCP and SMTP transport layer |
3832 | directly and when used from an application using the GNUnet core. | 4219 | directly and when used from an application using the GNUnet core. |
3833 | Measureing just the transport layer gives the better view of the actual | 4220 | Measuring just the transport layer gives the better view of the actual |
3834 | overhead of the protocol, whereas evaluating the transport from the | 4221 | overhead of the protocol, whereas evaluating the transport from the |
3835 | application puts the overhead into perspective from a practical point of | 4222 | application puts the overhead into perspective from a practical point of |
3836 | view. | 4223 | view. |
@@ -3850,7 +4237,7 @@ wire have no impact on the timings. n messages were sent sequentially over | |||
3850 | the transport layer, sending message i+1 after the i-th message was | 4237 | the transport layer, sending message i+1 after the i-th message was |
3851 | received. All messages were sent over the same connection and the time to | 4238 | received. All messages were sent over the same connection and the time to |
3852 | establish the connection was not taken into account since this overhead is | 4239 | establish the connection was not taken into account since this overhead is |
3853 | miniscule in practice --- as long as a connection is used for a | 4240 | minuscule in practice --- as long as a connection is used for a |
3854 | significant number of messages. | 4241 | significant number of messages. |
3855 | 4242 | ||
3856 | @multitable @columnfractions .20 .15 .15 .15 .15 .15 | 4243 | @multitable @columnfractions .20 .15 .15 .15 .15 .15 |
@@ -3881,9 +4268,9 @@ given time-bounds. For this benchmark we report the message loss after | |||
3881 | allowing t time for sending m messages. If messages were not sent (or | 4268 | allowing t time for sending m messages. If messages were not sent (or |
3882 | received) after an overall timeout of t, they were considered lost. The | 4269 | received) after an overall timeout of t, they were considered lost. The |
3883 | benchmark was performed using two Xeon 2 GHZ machines running RedHat 8.0 | 4270 | benchmark was performed using two Xeon 2 GHZ machines running RedHat 8.0 |
3884 | with sendmail. The machines were connected with a direct 100 MBit ethernet | 4271 | with sendmail. The machines were connected with a direct 100 MBit Ethernet |
3885 | connection.@ Figures udp1200, tcp1200 and smtp-MTUs show that the | 4272 | connection.@ Figures udp1200, tcp1200 and smtp-MTUs show that the |
3886 | throughput for messages of size 1,200 octects is 2,343 kbps, 3,310 kbps | 4273 | throughput for messages of size 1,200 octets is 2,343 kbps, 3,310 kbps |
3887 | and 6 kbps for UDP, TCP and SMTP respectively. The high per-message | 4274 | and 6 kbps for UDP, TCP and SMTP respectively. The high per-message |
3888 | overhead of SMTP can be improved by increasing the MTU, for example, an | 4275 | overhead of SMTP can be improved by increasing the MTU, for example, an |
3889 | MTU of 12,000 octets improves the throughput to 13 kbps as figure | 4276 | MTU of 12,000 octets improves the throughput to 13 kbps as figure |
@@ -3928,7 +4315,7 @@ installed). | |||
3928 | For instructions about how to install the libraries you should | 4315 | For instructions about how to install the libraries you should |
3929 | check out the BlueZ site | 4316 | check out the BlueZ site |
3930 | (@uref{http://www.bluez.org/, http://www.bluez.org}). If you don't know if | 4317 | (@uref{http://www.bluez.org/, http://www.bluez.org}). If you don't know if |
3931 | you have the necesarry libraries, don't worry, just run the GNUnet | 4318 | you have the necessary libraries, don't worry, just run the GNUnet |
3932 | configure script and you will be able to see a notification at the end | 4319 | configure script and you will be able to see a notification at the end |
3933 | which will warn you if you don't have the necessary libraries. | 4320 | which will warn you if you don't have the necessary libraries. |
3934 | 4321 | ||
@@ -3956,7 +4343,7 @@ helper binary used on GNU/Linux: | |||
3956 | 4343 | ||
3957 | @itemize @bullet | 4344 | @itemize @bullet |
3958 | @item it verifies if the name corresponds to a Bluetooth interface name | 4345 | @item it verifies if the name corresponds to a Bluetooth interface name |
3959 | @item it verifies if the iterface is up (if it is not, it tries to bring | 4346 | @item it verifies if the interface is up (if it is not, it tries to bring |
3960 | it up) | 4347 | it up) |
3961 | @item it tries to enable the page and inquiry scan in order to make the | 4348 | @item it tries to enable the page and inquiry scan in order to make the |
3962 | device discoverable and to accept incoming connection requests | 4349 | device discoverable and to accept incoming connection requests |
@@ -3997,12 +4384,12 @@ Bluetooth address has the form 00:00:00:00:00:00 it means that there is | |||
3997 | something wrong with the D-Bus daemon or with the Bluetooth daemon. Use | 4384 | something wrong with the D-Bus daemon or with the Bluetooth daemon. Use |
3998 | @code{bluetoothd} tool to see the logs | 4385 | @code{bluetoothd} tool to see the logs |
3999 | 4386 | ||
4000 | @item @code{sdptool} can be used to control and interogate SDP servers. | 4387 | @item @code{sdptool} can be used to control and interrogate SDP servers. |
4001 | If you encounter problems regarding the SDP server (like the SDP server is | 4388 | If you encounter problems regarding the SDP server (like the SDP server is |
4002 | down) you should check out if the D-Bus daemon is running correctly and to | 4389 | down) you should check out if the D-Bus daemon is running correctly and to |
4003 | see if the Bluetooth daemon started correctly(use @code{bluetoothd} tool). | 4390 | see if the Bluetooth daemon started correctly(use @code{bluetoothd} tool). |
4004 | Also, sometimes the SDP service could work but somehow the device couldn't | 4391 | Also, sometimes the SDP service could work but somehow the device couldn't |
4005 | register his service. Use @code{sdptool browse [dev-address]} to see if | 4392 | register its service. Use @code{sdptool browse [dev-address]} to see if |
4006 | the service is registered. There should be a service with the name of the | 4393 | the service is registered. There should be a service with the name of the |
4007 | interface and GNUnet as provider. | 4394 | interface and GNUnet as provider. |
4008 | 4395 | ||
@@ -4084,11 +4471,11 @@ then start sending data for benchmarking. | |||
4084 | On Windows you cannot test the plugin functionality using two Bluetooth | 4471 | On Windows you cannot test the plugin functionality using two Bluetooth |
4085 | devices from the same machine because after you install the drivers there | 4472 | devices from the same machine because after you install the drivers there |
4086 | will occur some conflicts between the Bluetooth stacks. (At least that is | 4473 | will occur some conflicts between the Bluetooth stacks. (At least that is |
4087 | what happend on my machine : I wasn't able to use the Bluesoleil stack and | 4474 | what happened on my machine : I wasn't able to use the Bluesoleil stack and |
4088 | the WINDCOMM one in the same time). | 4475 | the WINDCOMM one in the same time). |
4089 | 4476 | ||
4090 | If you have two different machines and your configuration files are good | 4477 | If you have two different machines and your configuration files are good |
4091 | you can use the same scenario presented on the begining of this section. | 4478 | you can use the same scenario presented on the beginning of this section. |
4092 | 4479 | ||
4093 | Another way to test the plugin functionality is to create your own | 4480 | Another way to test the plugin functionality is to create your own |
4094 | application which will use the GNUnet framework with the Bluetooth | 4481 | application which will use the GNUnet framework with the Bluetooth |
@@ -4103,8 +4490,8 @@ This page describes the implementation of the Bluetooth transport plugin. | |||
4103 | First I want to remind you that the Bluetooth transport plugin uses | 4490 | First I want to remind you that the Bluetooth transport plugin uses |
4104 | virtually the same code as the WLAN plugin and only the helper binary is | 4491 | virtually the same code as the WLAN plugin and only the helper binary is |
4105 | different. Also the scope of the helper binary from the Bluetooth | 4492 | different. Also the scope of the helper binary from the Bluetooth |
4106 | transport plugin is the same as the one used for the wlan transport | 4493 | transport plugin is the same as the one used for the WLAN transport |
4107 | plugin: it acceses the interface and then it forwards traffic in both | 4494 | plugin: it accesses the interface and then it forwards traffic in both |
4108 | directions between the Bluetooth interface and stdin/stdout of the | 4495 | directions between the Bluetooth interface and stdin/stdout of the |
4109 | process involved. | 4496 | process involved. |
4110 | 4497 | ||
@@ -4145,8 +4532,8 @@ Bluetooth interface) and is separated in two stages: | |||
4145 | @subsubsection THE INITIALIZATION | 4532 | @subsubsection THE INITIALIZATION |
4146 | 4533 | ||
4147 | @itemize @bullet | 4534 | @itemize @bullet |
4148 | @item first, it checks if we have root privilegies | 4535 | @item first, it checks if we have root privileges |
4149 | (@emph{Remember that we need to have root privilegies in order to be able | 4536 | (@emph{Remember that we need to have root privileges in order to be able |
4150 | to bring the interface up if it is down or to change its state.}). | 4537 | to bring the interface up if it is down or to change its state.}). |
4151 | 4538 | ||
4152 | @item second, it verifies if the interface with the given name exists. | 4539 | @item second, it verifies if the interface with the given name exists. |
@@ -4171,7 +4558,7 @@ discoverable | |||
4171 | devices to get the port on which this device is listening on) | 4558 | devices to get the port on which this device is listening on) |
4172 | @end itemize | 4559 | @end itemize |
4173 | 4560 | ||
4174 | @item drops the root privilegies | 4561 | @item drops the root privileges |
4175 | 4562 | ||
4176 | @strong{If the interface is not a Bluetooth interface the helper exits | 4563 | @strong{If the interface is not a Bluetooth interface the helper exits |
4177 | with a suitable error} | 4564 | with a suitable error} |
@@ -4216,7 +4603,7 @@ the STDOUT file descriptor, then we write to STDOUT the message from the | |||
4216 | @emph{write_std} buffer. | 4603 | @emph{write_std} buffer. |
4217 | 4604 | ||
4218 | To find out on which port a device is listening on we connect to the local | 4605 | To find out on which port a device is listening on we connect to the local |
4219 | SDP server and searche the registered service for that device. | 4606 | SDP server and search the registered service for that device. |
4220 | 4607 | ||
4221 | @emph{You should be aware of the fact that if the device fails to connect | 4608 | @emph{You should be aware of the fact that if the device fails to connect |
4222 | to another one when trying to send a message it will attempt one more | 4609 | to another one when trying to send a message it will attempt one more |
@@ -4279,17 +4666,17 @@ For Windows I decided to use the Microsoft Bluetooth stack which has the | |||
4279 | advantage of coming standard from Windows XP SP2. The main disadvantage is | 4666 | advantage of coming standard from Windows XP SP2. The main disadvantage is |
4280 | that it only supports the RFCOMM protocol so we will not be able to have | 4667 | that it only supports the RFCOMM protocol so we will not be able to have |
4281 | a low level control over the Bluetooth device. Therefore it is the user | 4668 | a low level control over the Bluetooth device. Therefore it is the user |
4282 | responsability to check if the device is up and in the discoverable mode. | 4669 | responsibility to check if the device is up and in the discoverable mode. |
4283 | Also there are no tools which could be used for debugging in order to read | 4670 | Also there are no tools which could be used for debugging in order to read |
4284 | the data coming from and going to a Bluetooth device, which obviously | 4671 | the data coming from and going to a Bluetooth device, which obviously |
4285 | hindered my work. Another thing that slowed down the implementation of the | 4672 | hindered my work. Another thing that slowed down the implementation of the |
4286 | plugin (besides that I wasn't too accomodated with the win32 API) was that | 4673 | plugin (besides that I wasn't too accommodated with the win32 API) was that |
4287 | there were some bugs on MinGW regarding the Bluetooth. Now they are solved | 4674 | there were some bugs on MinGW regarding the Bluetooth. Now they are solved |
4288 | but you should keep in mind that you should have the latest updates | 4675 | but you should keep in mind that you should have the latest updates |
4289 | (especially the @emph{ws2bth} header). | 4676 | (especially the @emph{ws2bth} header). |
4290 | 4677 | ||
4291 | Besides the fact that it uses the Windows Sockets, the Windows | 4678 | Besides the fact that it uses the Windows Sockets, the Windows |
4292 | implemenation follows the same principles as the GNU/Linux one: | 4679 | implementation follows the same principles as the GNU/Linux one: |
4293 | 4680 | ||
4294 | @itemize @bullet | 4681 | @itemize @bullet |
4295 | @item It has a initalization part where it initializes the | 4682 | @item It has a initalization part where it initializes the |
@@ -4334,7 +4721,7 @@ broadcast messages. When it receives a broadcast message it will skip it. | |||
4334 | @item Implement the broadcast functionality on Windows @emph{(currently | 4721 | @item Implement the broadcast functionality on Windows @emph{(currently |
4335 | working on)} | 4722 | working on)} |
4336 | @item Implement a testcase for the helper :@ @emph{The testcase | 4723 | @item Implement a testcase for the helper :@ @emph{The testcase |
4337 | consists of a program which emaluates the plugin and uses the helper. It | 4724 | consists of a program which emulates the plugin and uses the helper. It |
4338 | will simulate connections, disconnections and data transfers.} | 4725 | will simulate connections, disconnections and data transfers.} |
4339 | @end itemize | 4726 | @end itemize |
4340 | 4727 | ||
@@ -4522,7 +4909,7 @@ peers connecting, peers disconnecting and incoming messages) and send | |||
4522 | messages to connected peers using | 4909 | messages to connected peers using |
4523 | @code{GNUNET_CORE_notify_transmit_ready}. Note that applications must | 4910 | @code{GNUNET_CORE_notify_transmit_ready}. Note that applications must |
4524 | cancel pending transmission requests if they receive a disconnect event | 4911 | cancel pending transmission requests if they receive a disconnect event |
4525 | for a peer that had a transmission pending; furthermore, queueing more | 4912 | for a peer that had a transmission pending; furthermore, queuing more |
4526 | than one transmission request per peer per application using the | 4913 | than one transmission request per peer per application using the |
4527 | service is not permitted. | 4914 | service is not permitted. |
4528 | 4915 | ||
@@ -4817,11 +5204,11 @@ The API is heavily base on the CORE API. | |||
4817 | CADET delivers messages to other peers in "channels". | 5204 | CADET delivers messages to other peers in "channels". |
4818 | A channel is a permanent connection defined by a destination peer | 5205 | A channel is a permanent connection defined by a destination peer |
4819 | (identified by its public key) and a port number. | 5206 | (identified by its public key) and a port number. |
4820 | Internally, CADET tunnels all channels towards a destiantion peer | 5207 | Internally, CADET tunnels all channels towards a destination peer |
4821 | using one session key and relays the data on multiple "connections", | 5208 | using one session key and relays the data on multiple "connections", |
4822 | independent from the channels. | 5209 | independent from the channels. |
4823 | 5210 | ||
4824 | Each channel has optional paramenters, the most important being the | 5211 | Each channel has optional parameters, the most important being the |
4825 | reliability flag. | 5212 | reliability flag. |
4826 | Should a message get lost on TRANSPORT/CORE level, if a channel is | 5213 | Should a message get lost on TRANSPORT/CORE level, if a channel is |
4827 | created with as reliable, CADET will retransmit the lost message and | 5214 | created with as reliable, CADET will retransmit the lost message and |
@@ -4862,15 +5249,15 @@ case. To be alerted when a channel is online, a client can call | |||
4862 | @code{GNUNET_CADET_notify_transmit_ready} immediately after | 5249 | @code{GNUNET_CADET_notify_transmit_ready} immediately after |
4863 | @code{GNUNET_CADET_create_channel}. When the callback is activated, it | 5250 | @code{GNUNET_CADET_create_channel}. When the callback is activated, it |
4864 | means that the channel is online. The callback can give 0 bytes to CADET | 5251 | means that the channel is online. The callback can give 0 bytes to CADET |
4865 | if no message is to be sent, this is ok. | 5252 | if no message is to be sent, this is OK. |
4866 | 5253 | ||
4867 | If a transmission was requested but before the callback fires it is no | 5254 | If a transmission was requested but before the callback fires it is no |
4868 | longer needed, it can be cancelled with | 5255 | longer needed, it can be canceled with |
4869 | @code{GNUNET_CADET_notify_transmit_ready_cancel}, which uses the handle | 5256 | @code{GNUNET_CADET_notify_transmit_ready_cancel}, which uses the handle |
4870 | given back by @code{GNUNET_CADET_notify_transmit_ready}. | 5257 | given back by @code{GNUNET_CADET_notify_transmit_ready}. |
4871 | As in the case of CORE, only one message can be requested at a time: a | 5258 | As in the case of CORE, only one message can be requested at a time: a |
4872 | client must not call @code{GNUNET_CADET_notify_transmit_ready} again until | 5259 | client must not call @code{GNUNET_CADET_notify_transmit_ready} again until |
4873 | the callback is called or the request is cancelled. | 5260 | the callback is called or the request is canceled. |
4874 | 5261 | ||
4875 | When a channel is no longer needed, a client can call | 5262 | When a channel is no longer needed, a client can call |
4876 | @code{GNUNET_CADET_channel_destroy} to get rid of it. | 5263 | @code{GNUNET_CADET_channel_destroy} to get rid of it. |
@@ -4918,10 +5305,10 @@ all of the details can be found in this technical report. | |||
4918 | @subsection Motivation | 5305 | @subsection Motivation |
4919 | 5306 | ||
4920 | 5307 | ||
4921 | Some subsytems, like DHT, need to know the size of the GNUnet network to | 5308 | Some subsystems, like DHT, need to know the size of the GNUnet network to |
4922 | optimize some parameters of their own protocol. The decentralized nature | 5309 | optimize some parameters of their own protocol. The decentralized nature |
4923 | of GNUnet makes efficient and securely counting the exact number of peers | 5310 | of GNUnet makes efficient and securely counting the exact number of peers |
4924 | infeasable. Although there are several decentralized algorithms to count | 5311 | infeasible. Although there are several decentralized algorithms to count |
4925 | the number of peers in a system, so far there is none to do so securely. | 5312 | the number of peers in a system, so far there is none to do so securely. |
4926 | Other protocols may allow any malicious peer to manipulate the final | 5313 | Other protocols may allow any malicious peer to manipulate the final |
4927 | result or to take advantage of the system to perform | 5314 | result or to take advantage of the system to perform |
@@ -4943,7 +5330,7 @@ GNUnet's NSE protocol avoids these drawbacks. | |||
4943 | The NSE subsystem is designed to be resilient against these attacks. | 5330 | The NSE subsystem is designed to be resilient against these attacks. |
4944 | It uses @uref{http://en.wikipedia.org/wiki/Proof-of-work_system, proofs of work} | 5331 | It uses @uref{http://en.wikipedia.org/wiki/Proof-of-work_system, proofs of work} |
4945 | to prevent one peer from impersonating a large number of participants, | 5332 | to prevent one peer from impersonating a large number of participants, |
4946 | which would otherwise allow an adversary to artifically inflate the | 5333 | which would otherwise allow an adversary to artificially inflate the |
4947 | estimate. | 5334 | estimate. |
4948 | The DoS protection comes from the time-based nature of the protocol: | 5335 | The DoS protection comes from the time-based nature of the protocol: |
4949 | the estimates are calculated periodically and out-of-time traffic is | 5336 | the estimates are calculated periodically and out-of-time traffic is |
@@ -5005,7 +5392,7 @@ to all the other peers, who will calculate the estimate from it. | |||
5005 | The target value itself is generated by hashing the current time, rounded | 5392 | The target value itself is generated by hashing the current time, rounded |
5006 | down to an agreed value. If the rounding amount is 1h (default) and the | 5393 | down to an agreed value. If the rounding amount is 1h (default) and the |
5007 | time is 12:34:56, the time to hash would be 12:00:00. The process is | 5394 | time is 12:34:56, the time to hash would be 12:00:00. The process is |
5008 | repeated each rouning amount (in this example would be every hour). | 5395 | repeated each rounding amount (in this example would be every hour). |
5009 | Every repetition is called a round. | 5396 | Every repetition is called a round. |
5010 | 5397 | ||
5011 | @node Timing | 5398 | @node Timing |
@@ -5017,12 +5404,12 @@ its ID all at one. Once each peer has the target random value, it | |||
5017 | compares its own ID to the target and calculates the hypothetical size of | 5404 | compares its own ID to the target and calculates the hypothetical size of |
5018 | the network if that peer were to be the closest. | 5405 | the network if that peer were to be the closest. |
5019 | Then it compares the hypothetical size with the estimate from the previous | 5406 | Then it compares the hypothetical size with the estimate from the previous |
5020 | rounds. For each value there is an assiciated point in the period, | 5407 | rounds. For each value there is an associated point in the period, |
5021 | let's call it "broadcast time". If its own hypothetical estimate | 5408 | let's call it "broadcast time". If its own hypothetical estimate |
5022 | is the same as the previous global estimate, its "broadcast time" will be | 5409 | is the same as the previous global estimate, its "broadcast time" will be |
5023 | in the middle of the round. If its bigger it will be earlier and if its | 5410 | in the middle of the round. If its bigger it will be earlier and if its |
5024 | smaller (the most likely case) it will be later. This ensures that the | 5411 | smaller (the most likely case) it will be later. This ensures that the |
5025 | peers closests to the target value start broadcasting their ID the first. | 5412 | peers closest to the target value start broadcasting their ID the first. |
5026 | 5413 | ||
5027 | @node Controlled Flooding | 5414 | @node Controlled Flooding |
5028 | @subsubsection Controlled Flooding | 5415 | @subsubsection Controlled Flooding |
@@ -5035,7 +5422,7 @@ with a message containing the better value. Then it checks a proof of | |||
5035 | work that must be included in the incoming message, to ensure that the | 5422 | work that must be included in the incoming message, to ensure that the |
5036 | other peer's ID is not made up (otherwise a malicious peer could claim to | 5423 | other peer's ID is not made up (otherwise a malicious peer could claim to |
5037 | have an ID of exactly the target value every round). Once validated, it | 5424 | have an ID of exactly the target value every round). Once validated, it |
5038 | compares the brodcast time of the received value with the current time | 5425 | compares the broadcast time of the received value with the current time |
5039 | and if it's not too early, sends the received value to its neighbors. | 5426 | and if it's not too early, sends the received value to its neighbors. |
5040 | Otherwise it stores the value until the correct broadcast time comes. | 5427 | Otherwise it stores the value until the correct broadcast time comes. |
5041 | This prevents unnecessary traffic of sub-optimal values, since a better | 5428 | This prevents unnecessary traffic of sub-optimal values, since a better |
@@ -5049,7 +5436,7 @@ to the neighbors. | |||
5049 | @c %**end of header | 5436 | @c %**end of header |
5050 | 5437 | ||
5051 | Once the closest ID has been spread across the network each peer gets the | 5438 | Once the closest ID has been spread across the network each peer gets the |
5052 | exact distance betweed this ID and the target value of the round and | 5439 | exact distance between this ID and the target value of the round and |
5053 | calculates the estimate with a mathematical formula described in the tech | 5440 | calculates the estimate with a mathematical formula described in the tech |
5054 | report. The estimate generated with this method for a single round is not | 5441 | report. The estimate generated with this method for a single round is not |
5055 | very precise. Remember the case of the example, where the only peer is the | 5442 | very precise. Remember the case of the example, where the only peer is the |
@@ -5073,7 +5460,7 @@ calls: @code{GNUNET_NSE_connect} and @code{GNUNET_NSE_disconnect}. | |||
5073 | The connect call gets a callback function as a parameter and this function | 5460 | The connect call gets a callback function as a parameter and this function |
5074 | is called each time the network agrees on an estimate. This usually is | 5461 | is called each time the network agrees on an estimate. This usually is |
5075 | once per round, with some exceptions: if the closest peer has a late | 5462 | once per round, with some exceptions: if the closest peer has a late |
5076 | local clock and starts spreading his ID after everyone else agreed on a | 5463 | local clock and starts spreading its ID after everyone else agreed on a |
5077 | value, the callback might be activated twice in a round, the second value | 5464 | value, the callback might be activated twice in a round, the second value |
5078 | being always bigger than the first. The default round time is set to | 5465 | being always bigger than the first. The default round time is set to |
5079 | 1 hour. | 5466 | 1 hour. |
@@ -5123,7 +5510,7 @@ size is between one third and three times the estimate. This can of | |||
5123 | course vary with network conditions. | 5510 | course vary with network conditions. |
5124 | Thus, applications may want to also consider the provided standard | 5511 | Thus, applications may want to also consider the provided standard |
5125 | deviation value, not only the average (in particular, if the standard | 5512 | deviation value, not only the average (in particular, if the standard |
5126 | veriation is very high, the average maybe meaningless: the network size is | 5513 | variation is very high, the average maybe meaningless: the network size is |
5127 | changing rapidly). | 5514 | changing rapidly). |
5128 | 5515 | ||
5129 | @node libgnunetnse - Examples | 5516 | @node libgnunetnse - Examples |
@@ -5199,12 +5586,12 @@ is what we are flooding the network with right now. | |||
5199 | At the beginning of each round the peer does the following: | 5586 | At the beginning of each round the peer does the following: |
5200 | 5587 | ||
5201 | @itemize @bullet | 5588 | @itemize @bullet |
5202 | @item calculates his own distance to the target value | 5589 | @item calculates its own distance to the target value |
5203 | @item creates, signs and stores the message for the current round (unless | 5590 | @item creates, signs and stores the message for the current round (unless |
5204 | it has a better message in the "next round" slot which came early in the | 5591 | it has a better message in the "next round" slot which came early in the |
5205 | previous round) | 5592 | previous round) |
5206 | @item calculates, based on the stored round message (own or received) when | 5593 | @item calculates, based on the stored round message (own or received) when |
5207 | to stard flooding it to its neighbors | 5594 | to start flooding it to its neighbors |
5208 | @end itemize | 5595 | @end itemize |
5209 | 5596 | ||
5210 | Upon receiving a message the peer checks the validity of the message | 5597 | Upon receiving a message the peer checks the validity of the message |
@@ -5705,7 +6092,7 @@ convenience API to do just that. Use @code{GNUNET_IDENTITY_ego_lookup} to | |||
5705 | lookup a single ego by name. Note that this is the user's name for the | 6092 | lookup a single ego by name. Note that this is the user's name for the |
5706 | ego, not the service function. The resulting ego will be returned via a | 6093 | ego, not the service function. The resulting ego will be returned via a |
5707 | callback and will only be valid during that callback. The operation can | 6094 | callback and will only be valid during that callback. The operation can |
5708 | be cancelled via @code{GNUNET_IDENTITY_ego_lookup_cancel} | 6095 | be canceled via @code{GNUNET_IDENTITY_ego_lookup_cancel} |
5709 | (cancellation is only legal before the callback is invoked). | 6096 | (cancellation is only legal before the callback is invoked). |
5710 | 6097 | ||
5711 | @node Associating egos with service functions | 6098 | @node Associating egos with service functions |
@@ -5835,8 +6222,8 @@ So a client has first to retrieve records, merge with existing records | |||
5835 | and then store the result. | 6222 | and then store the result. |
5836 | 6223 | ||
5837 | To perform a lookup operation, the client uses the | 6224 | To perform a lookup operation, the client uses the |
5838 | @code{GNUNET_NAMESTORE_records_store} function. Here he has to pass the | 6225 | @code{GNUNET_NAMESTORE_records_store} function. Here it has to pass the |
5839 | namestore handle, the private key of the zone and the label. He also has | 6226 | namestore handle, the private key of the zone and the label. It also has |
5840 | to provide a callback function which will be called with the result of | 6227 | to provide a callback function which will be called with the result of |
5841 | the lookup operation: | 6228 | the lookup operation: |
5842 | the zone for the records, the label, and the records including the | 6229 | the zone for the records, the label, and the records including the |
@@ -5859,7 +6246,7 @@ by NAMESTORE. | |||
5859 | Here a client uses the @code{GNUNET_NAMESTORE_zone_iteration_start} | 6246 | Here a client uses the @code{GNUNET_NAMESTORE_zone_iteration_start} |
5860 | function and passes the namestore handle, the zone to iterate over and a | 6247 | function and passes the namestore handle, the zone to iterate over and a |
5861 | callback function to call with the result. | 6248 | callback function to call with the result. |
5862 | If the client wants to iterate over all the, he passes NULL for the zone. | 6249 | If the client wants to iterate over all the WHAT!? FIXME, it passes NULL for the zone. |
5863 | A @code{GNUNET_NAMESTORE_ZoneIterator} handle is returned to be used to | 6250 | A @code{GNUNET_NAMESTORE_ZoneIterator} handle is returned to be used to |
5864 | continue iteration. | 6251 | continue iteration. |
5865 | 6252 | ||
@@ -6278,7 +6665,7 @@ The size of an element's data is limited to around 62 KB. | |||
6278 | 6665 | ||
6279 | Sets created by a local client can be modified and reused for multiple | 6666 | Sets created by a local client can be modified and reused for multiple |
6280 | operations. As each set operation requires potentially expensive special | 6667 | operations. As each set operation requires potentially expensive special |
6281 | auxilliary data to be computed for each element of a set, a set can only | 6668 | auxiliary data to be computed for each element of a set, a set can only |
6282 | participate in one type of set operation (i.e. union or intersection). | 6669 | participate in one type of set operation (i.e. union or intersection). |
6283 | The type of a set is determined upon its creation. | 6670 | The type of a set is determined upon its creation. |
6284 | If a the elements of a set are needed for an operation of a different | 6671 | If a the elements of a set are needed for an operation of a different |
@@ -6398,7 +6785,7 @@ until the client calls @code{GNUNET_SET_commit} | |||
6398 | @c %**end of header | 6785 | @c %**end of header |
6399 | 6786 | ||
6400 | To create symmetry between the two ways of starting a set operation | 6787 | To create symmetry between the two ways of starting a set operation |
6401 | (accepting and nitiating it), the operation handles returned by | 6788 | (accepting and initiating it), the operation handles returned by |
6402 | @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare} do not yet have a | 6789 | @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare} do not yet have a |
6403 | set to operate on, thus they can not do any work yet. | 6790 | set to operate on, thus they can not do any work yet. |
6404 | 6791 | ||
@@ -6555,10 +6942,10 @@ number of iterations). | |||
6555 | The receiver of the message removes all elements from its local set that | 6942 | The receiver of the message removes all elements from its local set that |
6556 | do not pass the Bloom filter test. | 6943 | do not pass the Bloom filter test. |
6557 | It then checks if the set size of the sender and the XOR over the keys | 6944 | It then checks if the set size of the sender and the XOR over the keys |
6558 | match what is left of his own set. If they do, he sends a | 6945 | match what is left of its own set. If they do, it sends a |
6559 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_DONE} back to indicate | 6946 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_DONE} back to indicate |
6560 | that the latest set is the final result. | 6947 | that the latest set is the final result. |
6561 | Otherwise, the receiver starts another Bloom fitler exchange, except | 6948 | Otherwise, the receiver starts another Bloom filter exchange, except |
6562 | this time as the sender. | 6949 | this time as the sender. |
6563 | 6950 | ||
6564 | @node Salt | 6951 | @node Salt |
@@ -6566,7 +6953,7 @@ this time as the sender. | |||
6566 | 6953 | ||
6567 | @c %**end of header | 6954 | @c %**end of header |
6568 | 6955 | ||
6569 | Bloomfilter operations are probablistic: With some non-zero probability | 6956 | Bloomfilter operations are probabilistic: With some non-zero probability |
6570 | the test may incorrectly say an element is in the set, even though it is | 6957 | the test may incorrectly say an element is in the set, even though it is |
6571 | not. | 6958 | not. |
6572 | 6959 | ||
@@ -6619,7 +7006,7 @@ message. If the IBF fully decodes, the peer responds with a | |||
6619 | GNUNET_MESSAGE_TYPE_SET_UNION_P2P_DONE message instead of another | 7006 | GNUNET_MESSAGE_TYPE_SET_UNION_P2P_DONE message instead of another |
6620 | GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF. | 7007 | GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF. |
6621 | 7008 | ||
6622 | All Bloom filter operations use a salt to mingle keys before hasing them | 7009 | All Bloom filter operations use a salt to mingle keys before hashing them |
6623 | into buckets, such that future iterations have a fresh chance of | 7010 | into buckets, such that future iterations have a fresh chance of |
6624 | succeeding if they failed due to collisions before. | 7011 | succeeding if they failed due to collisions before. |
6625 | 7012 | ||
@@ -7177,7 +7564,7 @@ already knows more than about a thousand blocks may need to send | |||
7177 | several of these messages. Naturally, the client should transmit these | 7564 | several of these messages. Naturally, the client should transmit these |
7178 | messages as quickly as possible after the original GET request such that | 7565 | messages as quickly as possible after the original GET request such that |
7179 | the DHT can filter those results in the network early on. Naturally, as | 7566 | the DHT can filter those results in the network early on. Naturally, as |
7180 | these messages are sent after the original request, it is conceivalbe | 7567 | these messages are sent after the original request, it is conceivable |
7181 | that the DHT service may return blocks that match those already known | 7568 | that the DHT service may return blocks that match those already known |
7182 | to the client anyway. | 7569 | to the client anyway. |
7183 | 7570 | ||
@@ -7290,7 +7677,7 @@ duplicate results) and when they obtain a matching, non-filtered response | |||
7290 | a @code{struct PeerResultMessage} of type | 7677 | a @code{struct PeerResultMessage} of type |
7291 | @code{GNUNET_MESSAGE_TYPE_DHT_P2P_RESULT} is forwarded to the previous | 7678 | @code{GNUNET_MESSAGE_TYPE_DHT_P2P_RESULT} is forwarded to the previous |
7292 | hop. | 7679 | hop. |
7293 | Whenver a result is forwarded, the block plugin is used to update the | 7680 | Whenever a result is forwarded, the block plugin is used to update the |
7294 | Bloom filter accordingly, to ensure that the same result is never | 7681 | Bloom filter accordingly, to ensure that the same result is never |
7295 | forwarded more than once. | 7682 | forwarded more than once. |
7296 | The DHT service may also cache forwarded results locally if the | 7683 | The DHT service may also cache forwarded results locally if the |
@@ -7357,7 +7744,7 @@ record types. | |||
7357 | 7744 | ||
7358 | @c %**end of header | 7745 | @c %**end of header |
7359 | 7746 | ||
7360 | The GNS API itself is extremely simple. Clients first connec to the | 7747 | The GNS API itself is extremely simple. Clients first connect to the |
7361 | GNS service using @code{GNUNET_GNS_connect}. | 7748 | GNS service using @code{GNUNET_GNS_connect}. |
7362 | They can then perform lookups using @code{GNUNET_GNS_lookup} or cancel | 7749 | They can then perform lookups using @code{GNUNET_GNS_lookup} or cancel |
7363 | pending lookups using @code{GNUNET_GNS_lookup_cancel}. | 7750 | pending lookups using @code{GNUNET_GNS_lookup_cancel}. |
@@ -7406,9 +7793,9 @@ their respective zones can automatically be learned and added to the | |||
7406 | the shorten zone. If NULL is passed, shortening is disabled. | 7793 | the shorten zone. If NULL is passed, shortening is disabled. |
7407 | @item proc This argument identifies | 7794 | @item proc This argument identifies |
7408 | the function to call with the result. It is given proc_cls, the number of | 7795 | the function to call with the result. It is given proc_cls, the number of |
7409 | records found (possilby zero) and the array of the records as arguments. | 7796 | records found (possibly zero) and the array of the records as arguments. |
7410 | proc will only be called once. After proc,> has been called, the lookup | 7797 | proc will only be called once. After proc,> has been called, the lookup |
7411 | must no longer be cancelled. | 7798 | must no longer be canceled. |
7412 | @item proc_cls The closure for proc. | 7799 | @item proc_cls The closure for proc. |
7413 | @end table | 7800 | @end table |
7414 | 7801 | ||
@@ -7563,7 +7950,7 @@ This is merely one method for how we can obtain GNS queries. | |||
7563 | It is also possible to change @code{resolv.conf} to point to a machine | 7950 | It is also possible to change @code{resolv.conf} to point to a machine |
7564 | running @code{gnunet-dns2gns} or to modify libc's name system switch | 7951 | running @code{gnunet-dns2gns} or to modify libc's name system switch |
7565 | (NSS) configuration to include a GNS resolution plugin. | 7952 | (NSS) configuration to include a GNS resolution plugin. |
7566 | The method described in this chaper is more of a last-ditch catch-all | 7953 | The method described in this chapter is more of a last-ditch catch-all |
7567 | approach. | 7954 | approach. |
7568 | 7955 | ||
7569 | @code{gnunet-service-dns} enables intercepting DNS traffic using policy | 7956 | @code{gnunet-service-dns} enables intercepting DNS traffic using policy |
@@ -7731,8 +8118,8 @@ This returns the handle required for all other operations on the | |||
7731 | NAMECACHE. Using @code{GNUNET_NAMECACHE_block_cache} clients can insert a | 8118 | NAMECACHE. Using @code{GNUNET_NAMECACHE_block_cache} clients can insert a |
7732 | block into the cache. | 8119 | block into the cache. |
7733 | @code{GNUNET_NAMECACHE_lookup_block} can be used to lookup blocks that | 8120 | @code{GNUNET_NAMECACHE_lookup_block} can be used to lookup blocks that |
7734 | were stored in the NAMECACHE. Both operations can be cancelled using | 8121 | were stored in the NAMECACHE. Both operations can be canceled using |
7735 | @code{GNUNET_NAMECACHE_cancel}. Note that cancelling a | 8122 | @code{GNUNET_NAMECACHE_cancel}. Note that canceling a |
7736 | @code{GNUNET_NAMECACHE_block_cache} operation can result in the block | 8123 | @code{GNUNET_NAMECACHE_block_cache} operation can result in the block |
7737 | being stored in the NAMECACHE --- or not. Cancellation primarily ensures | 8124 | being stored in the NAMECACHE --- or not. Cancellation primarily ensures |
7738 | that the continuation function with the result of the operation will no | 8125 | that the continuation function with the result of the operation will no |
@@ -7859,7 +8246,7 @@ When a revocation is performed, the revocation is first of all | |||
7859 | disseminated by flooding the overlay network. | 8246 | disseminated by flooding the overlay network. |
7860 | The goal is to reach every peer, so that when a peer needs to check if a | 8247 | The goal is to reach every peer, so that when a peer needs to check if a |
7861 | key has been revoked, this will be purely a local operation where the | 8248 | key has been revoked, this will be purely a local operation where the |
7862 | peer looks at his local revocation list. Flooding the network is also the | 8249 | peer looks at its local revocation list. Flooding the network is also the |
7863 | most robust form of key revocation --- an adversary would have to control | 8250 | most robust form of key revocation --- an adversary would have to control |
7864 | a separator of the overlay graph to restrict the propagation of the | 8251 | a separator of the overlay graph to restrict the propagation of the |
7865 | revocation message. Flooding is also very easy to implement --- peers that | 8252 | revocation message. Flooding is also very easy to implement --- peers that |
@@ -7919,7 +8306,7 @@ revocations. | |||
7919 | @code{GNUNET_REVOCATION_query} is used to check if a given ECDSA public | 8306 | @code{GNUNET_REVOCATION_query} is used to check if a given ECDSA public |
7920 | key has been revoked. | 8307 | key has been revoked. |
7921 | The given callback will be invoked with the result of the check. | 8308 | The given callback will be invoked with the result of the check. |
7922 | The query can be cancelled using @code{GNUNET_REVOCATION_query_cancel} on | 8309 | The query can be canceled using @code{GNUNET_REVOCATION_query_cancel} on |
7923 | the return value. | 8310 | the return value. |
7924 | 8311 | ||
7925 | @node Preparing revocations | 8312 | @node Preparing revocations |
@@ -8097,7 +8484,7 @@ metadata describing the content of the namespace. | |||
8097 | Instead of the name of the identifier for a potential update, it contains | 8484 | Instead of the name of the identifier for a potential update, it contains |
8098 | the identifier for the root of the namespace. | 8485 | the identifier for the root of the namespace. |
8099 | The URI should always be empty. The @code{SBlock} is signed with the | 8486 | The URI should always be empty. The @code{SBlock} is signed with the |
8100 | content provder's RSA private key (just like any other SBlock). Peers | 8487 | content provider's RSA private key (just like any other SBlock). Peers |
8101 | can search for @code{SBlock}s in order to find out more about a namespace. | 8488 | can search for @code{SBlock}s in order to find out more about a namespace. |
8102 | 8489 | ||
8103 | @node KSBlocks | 8490 | @node KSBlocks |
@@ -8262,11 +8649,11 @@ In the following paragraph the important details are highlighted. | |||
8262 | 8649 | ||
8263 | Announcing of the regular expressions is done by the | 8650 | Announcing of the regular expressions is done by the |
8264 | gnunet-daemon-regexprofiler, therefore you have to make sure it is | 8651 | gnunet-daemon-regexprofiler, therefore you have to make sure it is |
8265 | started, by adding it to the AUTOSTART set of ARM: | 8652 | started, by adding it to the START_ON_DEMAND set of ARM: |
8266 | 8653 | ||
8267 | @example | 8654 | @example |
8268 | [regexprofiler] | 8655 | [regexprofiler] |
8269 | AUTOSTART = YES | 8656 | START_ON_DEMAND = YES |
8270 | @end example | 8657 | @end example |
8271 | 8658 | ||
8272 | @noindent | 8659 | @noindent |
@@ -8381,7 +8768,7 @@ The REST service will automatically load all REST plugins on startup. | |||
8381 | 8768 | ||
8382 | @strong{Configuration} | 8769 | @strong{Configuration} |
8383 | 8770 | ||
8384 | The rest service can be configured in various ways. | 8771 | The REST service can be configured in various ways. |
8385 | The reference config file can be found in | 8772 | The reference config file can be found in |
8386 | @file{src/rest/rest.conf}: | 8773 | @file{src/rest/rest.conf}: |
8387 | @example | 8774 | @example |
@@ -8392,8 +8779,11 @@ REST_ALLOW_ORIGIN=* | |||
8392 | REST_ALLOW_CREDENTIALS=true | 8779 | REST_ALLOW_CREDENTIALS=true |
8393 | @end example | 8780 | @end example |
8394 | 8781 | ||
8395 | The port as well as Cross-origin resource sharing (CORS) headers that | 8782 | The port as well as |
8396 | are supposed to be advertised by the rest service are configurable. | 8783 | @deffn{cross-origin resource sharing} (CORS) |
8784 | @end deffn | ||
8785 | headers that are supposed to be advertised by the rest service are | ||
8786 | configurable. | ||
8397 | 8787 | ||
8398 | @menu | 8788 | @menu |
8399 | * Namespace considerations:: | 8789 | * Namespace considerations:: |
@@ -8403,19 +8793,19 @@ are supposed to be advertised by the rest service are configurable. | |||
8403 | @node Namespace considerations | 8793 | @node Namespace considerations |
8404 | @subsection Namespace considerations | 8794 | @subsection Namespace considerations |
8405 | 8795 | ||
8406 | The gnunet-rest-service will load all plugins that are installed. | 8796 | The @command{gnunet-rest-service} will load all plugins that are installed. |
8407 | As such it is important that the endpoint namespaces do not clash. | 8797 | As such it is important that the endpoint namespaces do not clash. |
8408 | For example, plugin X might expose the endpoint ``/xxx'' while plugin Y exposes | 8798 | |
8409 | endpoint ``/xxx/yyy''. | 8799 | For example, plugin X might expose the endpoint ``/xxx'' while plugin Y |
8410 | This is a problem if plugins X is also supposed to handle a call to | 8800 | exposes endpoint ``/xxx/yyy''. |
8411 | ``/xxx/yyy''. | 8801 | This is a problem if plugin X is also supposed to handle a call |
8412 | Currently, the REST service will not complain or warn about such clashes so | 8802 | to ``/xxx/yyy''. |
8413 | please make sure that endpoints are unambiguous. | 8803 | Currently the REST service will not complain or warn about such clashes, |
8804 | so please make sure that endpoints are unambiguous. | ||
8414 | 8805 | ||
8415 | @node Endpoint documentation | 8806 | @node Endpoint documentation |
8416 | @subsection Endpoint documentation | 8807 | @subsection Endpoint documentation |
8417 | 8808 | ||
8418 | This is WIP. Endpoints should be documented appropriately. | 8809 | This is WIP. Endpoints should be documented appropriately. |
8419 | Perferably using annotations. | 8810 | Preferably using annotations. |
8420 | |||
8421 | 8811 | ||
diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi index 3a76fb162..559a97f96 100644 --- a/doc/documentation/chapters/installation.texi +++ b/doc/documentation/chapters/installation.texi | |||
@@ -1,2185 +1,317 @@ | |||
1 | @node GNUnet Installation Handbook | 1 | @node Installing GNUnet |
2 | @chapter GNUnet Installation Handbook | 2 | @chapter Installing GNUnet |
3 | 3 | ||
4 | This handbook describes how to install (build, setup, compile) and | 4 | This guide is intended for those who want to install Gnunet from |
5 | setup (configure, start) GNUnet @value{VERSION}. After following these | 5 | source. For instructions on how to install GNUnet as a binary package |
6 | instructions you should be able to install and then start user-interfaces | 6 | please refer to the official documentation of your operating system or |
7 | to interact with the network. | 7 | package manager. |
8 | |||
9 | Note: This manual is far from complete, and we welcome contributions, be | ||
10 | it in the form of new chapters or insightful comments. | ||
11 | |||
12 | @menu | ||
13 | * Dependencies:: | ||
14 | * Pre-installation notes:: | ||
15 | * Generic installation instructions:: | ||
16 | * Build instructions for Ubuntu 12.04 using Git:: | ||
17 | * Build instructions for software builds from source:: | ||
18 | * Build Instructions for Microsoft Windows Platforms:: | ||
19 | * Build instructions for Debian 7.5:: | ||
20 | * Installing GNUnet from Git on Ubuntu 14.4:: | ||
21 | * Build instructions for Debian 8:: | ||
22 | @c * Build instructions for OpenBSD 6.2:: | ||
23 | * Outdated build instructions for previous revisions:: | ||
24 | @c * Portable GNUnet:: | ||
25 | * The graphical configuration interface:: | ||
26 | * How to start and stop a GNUnet peer:: | ||
27 | @end menu | ||
28 | |||
29 | @node Dependencies | ||
30 | @section Dependencies | ||
31 | @c %**end of header | ||
32 | |||
33 | This section lists the various known dependencies for | ||
34 | GNUnet @value{EDITION}. | ||
35 | Suggestions for missing dependencies or wrong version numbers are welcome. | ||
36 | 8 | ||
37 | @menu | 9 | @menu |
38 | * External dependencies:: | 10 | * Installing dependencies:: |
39 | * Optional dependencies:: | 11 | * Getting the Source Code:: |
40 | * Internal dependencies:: | 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:: | ||
41 | @end menu | 18 | @end menu |
42 | 19 | ||
43 | @node External dependencies | 20 | @c ----------------------------------------------------------------------- |
44 | @subsection External dependencies | 21 | @node Installing dependencies |
45 | @c %**end of header | 22 | @section Installing dependencies |
46 | 23 | GNUnet needs few libraries and applications for being able to run and | |
47 | These packages must be installed before a typical GNUnet installation | 24 | another few optional ones for using certain features. Preferably they |
48 | can be performed: | 25 | should be installed with a package manager. Just in case we include a |
26 | link to the project websites. | ||
49 | 27 | ||
28 | The mandatory libraries and applications are | ||
50 | @itemize @bullet | 29 | @itemize @bullet |
51 | @item autoconf | 30 | @item libtool |
52 | @item automake | 31 | @item autoconf @geq{}2.59 |
32 | @item automake @geq{}1.11.1 | ||
53 | @item pkg-config | 33 | @item pkg-config |
54 | @item libltdl | 34 | @item libgcrypt @geq{}1.6 |
55 | @item gstreamer | 35 | @item libextractor |
56 | @item gst-plugins-base | 36 | @item libidn |
57 | @item perl | 37 | @item libmicrohttpd @geq{}0.9.52 |
58 | @item python (only 2.7 supported)@footnote{tests and gnunet-qr} | 38 | @item libnss |
59 | @item jansson | 39 | @item libunistring |
60 | @item nss | ||
61 | @item glib | ||
62 | @item gmp | ||
63 | @item bluez | ||
64 | @item miniupnpc | ||
65 | @item gettext | 40 | @item gettext |
66 | @item which | 41 | @item glibc |
67 | @item texinfo @geq{} 5.2 | 42 | @item libgmp |
68 | @item GNU libmicrohttpd @geq{} 0.9.30 @footnote{We recommend to build it | 43 | @item gnutls |
69 | with a GnuTLS version that was configured with libunbound} | 44 | @item libcurl (has to be linked to GnuTLS) or libgnurl |
70 | @item GNU libextractor @geq{} 1.0 | ||
71 | @item GNU libtool @geq{} 2.2 | ||
72 | @item GNU libunistring @geq{} 0.9.1.1 | ||
73 | @item GNU libidn @geq{} 1.0.0 | ||
74 | @item @uref{https://gnupg.org/software/libgcrypt/, GNU libgcrypt} @geq{} | ||
75 | @uref{https://gnupg.org/ftp/gcrypt/libgcrypt/, 1.6.0} | ||
76 | @item @uref{https://gnutls.org/, GnuTLS} @geq{} 3.2.7 | ||
77 | @footnote{We recommend to compile with libunbound for DANE support; | ||
78 | GnuTLS also requires GNU nettle 2.7 (update: GnuTLS 3.2.7 appears NOT | ||
79 | to work against GNU nettle > 2.7, due to some API updatings done by | ||
80 | nettle. Thus it should be compiled against nettle 2.7 | ||
81 | and, in case you get some error on the reference to `rpl_strerror' being | ||
82 | undefined, follow the instructions on | ||
83 | @uref{http://lists.gnupg.org/pipermail/gnutls-devel/2013-November/006588.html, this} | ||
84 | post (and the link inside it)).} | ||
85 | @item @uref{https://gnunet.org/gnurl, gnURL} libgnurl @geq{} 7.34.0 | ||
86 | @footnote{must be compiled after @code{GnuTLS}} | ||
87 | @item libglpk @geq{} 4.45 | ||
88 | @item @uref{http://www.openssl.org/, OpenSSL} @geq{} 1.0 | ||
89 | @item TeX Live @geq{} 2012, optional (for gnunet-bcd) | ||
90 | @item Texinfo @geq{} 5.2 (for documentation) | ||
91 | @item libsqlite @geq{} 3.8.0 @footnote{(note that the code will | ||
92 | compile and often work with lower version numbers, but you may get subtle | ||
93 | bugs with respect to quota management in certain rare cases); | ||
94 | alternatively, MySQL or Postgres can also be installed, but those | ||
95 | databases will require more complex configurations (not | ||
96 | recommended for first-time users)} | ||
97 | @item zlib | 45 | @item zlib |
98 | @end itemize | 46 | @end itemize |
99 | 47 | ||
100 | @node Optional dependencies | 48 | In addition GNUnet needs one of of these three databases |
101 | @subsection Optional dependencies | ||
102 | |||
103 | These applications must be installed for various experimental or otherwise | ||
104 | optional features such as @command{gnunet-conversation}, | ||
105 | and @command{gnunet-gtk} (most of these features are only build if you | ||
106 | configure GNUnet with @command{--enable-experimental}): | ||
107 | |||
108 | @itemize @bullet | ||
109 | @item libpulse @geq{} 2.0, | ||
110 | optional (for @command{gnunet-conversation}) | ||
111 | @item libopus @geq{} 1.0.1, | ||
112 | optional (for @command{gnunet-conversation}) | ||
113 | @item libogg @geq{} 1.3.0, | ||
114 | optional (for @command{gnunet-conversation}) | ||
115 | @item libnss contained @command{certool} binary, | ||
116 | optional for convenient installation of | ||
117 | the GNS proxy. | ||
118 | @item python-zbar @geq{} 0.10, | ||
119 | optional (for @command{gnunet-qr}) | ||
120 | @item Gtk+ @geq{} 3.0, | ||
121 | optional (for @command{gnunet-gtk}) | ||
122 | @item libgladeui (must match Gtk+ version), | ||
123 | optional (for @command{gnunet-gtk}) | ||
124 | @item libqrencode @geq{} 3.0, | ||
125 | optional (for @command{gnunet-namestore-gtk}) | ||
126 | @item libpbc @geq{} 0.5.14, optional for Attribute-Based Encryption and Identity Provider functionality | ||
127 | @item libgabe (https://github.com/schanzen/libgabe), optional for Attribute-Based Encryption and Identity Provider functionality | ||
128 | @end itemize | ||
129 | |||
130 | @node Internal dependencies | ||
131 | @subsection Internal dependencies | ||
132 | |||
133 | This section tries to give an overview of what processes a typical GNUnet | ||
134 | peer running a particular application would consist of. All of the | ||
135 | processes listed here should be automatically started by | ||
136 | @command{gnunet-arm -s}. | ||
137 | The list is given as a rough first guide to users for failure diagnostics. | ||
138 | Ideally, end-users should never have to worry about these internal | ||
139 | dependencies. | ||
140 | |||
141 | In terms of internal dependencies, a minimum file-sharing system consists | ||
142 | of the following GNUnet processes (in order of dependency): | ||
143 | |||
144 | @itemize @bullet | ||
145 | @item gnunet-service-arm | ||
146 | @item gnunet-service-resolver (required by all) | ||
147 | @item gnunet-service-statistics (required by all) | ||
148 | @item gnunet-service-peerinfo | ||
149 | @item gnunet-service-transport (requires peerinfo) | ||
150 | @item gnunet-service-core (requires transport) | ||
151 | @item gnunet-daemon-hostlist (requires core) | ||
152 | @item gnunet-daemon-topology (requires hostlist, peerinfo) | ||
153 | @item gnunet-service-datastore | ||
154 | @item gnunet-service-dht (requires core) | ||
155 | @item gnunet-service-identity | ||
156 | @item gnunet-service-fs (requires identity, mesh, dht, datastore, core) | ||
157 | @end itemize | ||
158 | |||
159 | @noindent | ||
160 | A minimum VPN system consists of the following GNUnet processes (in | ||
161 | order of dependency): | ||
162 | |||
163 | @itemize @bullet | ||
164 | @item gnunet-service-arm | ||
165 | @item gnunet-service-resolver (required by all) | ||
166 | @item gnunet-service-statistics (required by all) | ||
167 | @item gnunet-service-peerinfo | ||
168 | @item gnunet-service-transport (requires peerinfo) | ||
169 | @item gnunet-service-core (requires transport) | ||
170 | @item gnunet-daemon-hostlist (requires core) | ||
171 | @item gnunet-service-dht (requires core) | ||
172 | @item gnunet-service-mesh (requires dht, core) | ||
173 | @item gnunet-service-dns (requires dht) | ||
174 | @item gnunet-service-regex (requires dht) | ||
175 | @item gnunet-service-vpn (requires regex, dns, mesh, dht) | ||
176 | @end itemize | ||
177 | |||
178 | @noindent | ||
179 | A minimum GNS system consists of the following GNUnet processes (in | ||
180 | order of dependency): | ||
181 | |||
182 | @itemize @bullet | ||
183 | @item gnunet-service-arm | ||
184 | @item gnunet-service-resolver (required by all) | ||
185 | @item gnunet-service-statistics (required by all) | ||
186 | @item gnunet-service-peerinfo | ||
187 | @item gnunet-service-transport (requires peerinfo) | ||
188 | @item gnunet-service-core (requires transport) | ||
189 | @item gnunet-daemon-hostlist (requires core) | ||
190 | @item gnunet-service-dht (requires core) | ||
191 | @item gnunet-service-mesh (requires dht, core) | ||
192 | @item gnunet-service-dns (requires dht) | ||
193 | @item gnunet-service-regex (requires dht) | ||
194 | @item gnunet-service-vpn (requires regex, dns, mesh, dht) | ||
195 | @item gnunet-service-identity | ||
196 | @item gnunet-service-namestore (requires identity) | ||
197 | @item gnunet-service-gns (requires vpn, dns, dht, namestore, identity) | ||
198 | @end itemize | ||
199 | |||
200 | @node Pre-installation notes | ||
201 | @section Pre-installation notes | ||
202 | |||
203 | Please note that in the code instructions for the installation, | ||
204 | @emph{#} indicates commands run as privileged root user and | ||
205 | @emph{$} shows commands run as unprivileged ("normal") system user. | ||
206 | |||
207 | |||
208 | @node Generic installation instructions | ||
209 | @section Generic installation instructions | ||
210 | |||
211 | First, in addition to the GNUnet sources you might require downloading the | ||
212 | latest version of various dependencies, depending on how recent the | ||
213 | software versions in your distribution of GNU/Linux are. | ||
214 | Most distributions do not include sufficiently recent versions of these | ||
215 | dependencies. | ||
216 | Thus, a typically installation on a "modern" GNU/Linux distribution | ||
217 | requires you to install the following dependencies (ideally in this | ||
218 | order): | ||
219 | |||
220 | @itemize @bullet | ||
221 | @item libgpgerror and libgcrypt | ||
222 | @item libnettle and libunbound (possibly from distribution), GnuTLS | ||
223 | @item libgnurl (read the README) | ||
224 | @item GNU libmicrohttpd | ||
225 | @item GNU libextractor | ||
226 | @end itemize | ||
227 | |||
228 | Make sure to first install the various mandatory and optional | ||
229 | dependencies including development headers from your distribution. | ||
230 | |||
231 | Other dependencies that you should strongly consider to install is a | ||
232 | database (MySQL, sqlite or Postgres). | ||
233 | The following instructions will assume that you installed at least sqlite. | ||
234 | For most distributions you should be able to find pre-build packages for | ||
235 | the database. Again, make sure to install the client libraries @b{and} the | ||
236 | respective development headers (if they are packaged separately) as well. | ||
237 | |||
238 | You can find specific, detailed instructions for installing of the | ||
239 | dependencies (and possibly the rest of the GNUnet installation) in the | ||
240 | platform-specific descriptions, which can be found in the Index. | ||
241 | Please consult them now. | ||
242 | If your distribution is not listed, please study | ||
243 | @ref{Build instructions for Debian 8}, the build instructions for | ||
244 | Debian stable, carefully as you try to install the dependencies for your | ||
245 | own distribution. | ||
246 | Contributing additional instructions for further platforms is always | ||
247 | appreciated. | ||
248 | Please take in mind that operating system development tends to move at | ||
249 | a rather fast speed. Due to this you should be aware that some of | ||
250 | the instructions could be outdated by the time you are reading this. | ||
251 | If you find a mistake, please tell us about it (or even better: send | ||
252 | a patch to the documentation to fix it!). | ||
253 | |||
254 | Before proceeding further, please double-check the dependency list. | ||
255 | Note that in addition to satisfying the dependencies, you might have to | ||
256 | make sure that development headers for the various libraries are also | ||
257 | installed. | ||
258 | There maybe files for other distributions, or you might be able to find | ||
259 | equivalent packages for your distribution. | ||
260 | |||
261 | While it is possible to build and install GNUnet without having root | ||
262 | access, we will assume that you have full control over your system in | ||
263 | these instructions. | ||
264 | First, you should create a system user @emph{gnunet} and an additional | ||
265 | group @emph{gnunetdns}. On the GNU/Linux distributions Debian and Ubuntu, | ||
266 | type: | ||
267 | |||
268 | @example | ||
269 | # adduser --system --home /var/lib/gnunet --group \ | ||
270 | --disabled-password gnunet | ||
271 | # addgroup --system gnunetdns | ||
272 | @end example | ||
273 | |||
274 | @noindent | ||
275 | On other Unixes and GNU systems, this should have the same effect: | ||
276 | |||
277 | @example | ||
278 | # useradd --system --groups gnunet --home-dir /var/lib/gnunet | ||
279 | # addgroup --system gnunetdns | ||
280 | @end example | ||
281 | |||
282 | Now compile and install GNUnet using: | ||
283 | |||
284 | @example | ||
285 | $ tar xvf gnunet-@value{VERSION}.tar.gz | ||
286 | $ cd gnunet-@value{VERSION} | ||
287 | $ ./configure --with-sudo=sudo --with-nssdir=/lib | ||
288 | $ make | ||
289 | $ sudo make install | ||
290 | @end example | ||
291 | |||
292 | If you want to be able to enable DEBUG-level log messages, add | ||
293 | @code{--enable-logging=verbose} to the end of the | ||
294 | @command{./configure} command. | ||
295 | @code{DEBUG}-level log messages are in English only and | ||
296 | should only be useful for developers (or for filing | ||
297 | really detailed bug reports). | ||
298 | |||
299 | Finally, you probably want to compile @command{gnunet-gtk}, which | ||
300 | includes @command{gnunet-setup} (a graphical tool for | ||
301 | GNUnet configuration) and @command{gnunet-fs-gtk} (a graphical tool for | ||
302 | GNUnet file-sharing): | ||
303 | |||
304 | @example | ||
305 | $ tar xvf gnunet-gtk-@value{VERSION}.tar.gz | ||
306 | $ cd gnunet-gtk-@value{VERSION} | ||
307 | $ ./configure --with-gnunet=/usr/local/ | ||
308 | $ make | ||
309 | $ sudo make install | ||
310 | $ cd .. | ||
311 | # just to be safe run this: | ||
312 | $ sudo ldconfig | ||
313 | @end example | ||
314 | |||
315 | @noindent | ||
316 | Next, edit the file @file{/etc/gnunet.conf} to contain the following: | ||
317 | |||
318 | @example | ||
319 | [arm] | ||
320 | SYSTEM_ONLY = YES | ||
321 | USER_ONLY = NO | ||
322 | @end example | ||
323 | |||
324 | @noindent | ||
325 | You may need to update your @code{ld.so} cache to include | ||
326 | files installed in @file{/usr/local/lib}: | ||
327 | |||
328 | @example | ||
329 | # ldconfig | ||
330 | @end example | ||
331 | |||
332 | @noindent | ||
333 | Then, switch from user @code{root} to user @code{gnunet} to start | ||
334 | the peer: | ||
335 | |||
336 | @example | ||
337 | # su -s /bin/sh - gnunet | ||
338 | $ gnunet-arm -c /etc/gnunet.conf -s | ||
339 | @end example | ||
340 | |||
341 | You may also want to add the last line in the gnunet user's @file{crontab} | ||
342 | prefixed with @code{@@reboot} so that it is executed whenever the system | ||
343 | is booted: | ||
344 | |||
345 | @example | ||
346 | @@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s | ||
347 | @end example | ||
348 | |||
349 | @noindent | ||
350 | This will only start the system-wide GNUnet services. | ||
351 | Type exit to get back your root shell. | ||
352 | Now, you need to configure the per-user part. For each | ||
353 | $USER that should get access to GNUnet on the system, run: | ||
354 | |||
355 | @example | ||
356 | # adduser $USER gnunet | ||
357 | @end example | ||
358 | |||
359 | @noindent | ||
360 | to allow them to access the system-wide GNUnet services. Then, each | ||
361 | user should create a configuration file @file{~/.config/gnunet.conf} | ||
362 | with the lines: | ||
363 | |||
364 | @example | ||
365 | [arm] | ||
366 | SYSTEM_ONLY = NO | ||
367 | USER_ONLY = YES | ||
368 | DEFAULTSERVICES = gns | ||
369 | @end example | ||
370 | |||
371 | @noindent | ||
372 | and start the per-user services using | ||
373 | |||
374 | @example | ||
375 | $ gnunet-arm -c ~/.config/gnunet.conf -s | ||
376 | @end example | ||
377 | |||
378 | @noindent | ||
379 | Again, adding a @code{crontab} entry to autostart the peer is advised: | ||
380 | |||
381 | @example | ||
382 | @@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s | ||
383 | @end example | ||
384 | |||
385 | @noindent | ||
386 | Note that some GNUnet services (such as SOCKS5 proxies) may need a | ||
387 | system-wide TCP port for each user. | ||
388 | For those services, systems with more than one user may require each user | ||
389 | to specify a different port number in their personal configuration file. | ||
390 | |||
391 | Finally, the user should perform the basic initial setup for the GNU Name | ||
392 | System (GNS) certificate authority. This is done by running: | ||
393 | |||
394 | @example | ||
395 | $ gnunet-gns-proxy-setup-ca | ||
396 | @end example | ||
397 | |||
398 | @noindent | ||
399 | The first generates the default zones, wheras the second setups the GNS | ||
400 | Certificate Authority with the user's browser. Now, to activate GNS in the | ||
401 | normal DNS resolution process, you need to edit your | ||
402 | @file{/etc/nsswitch.conf} where you should find a line like this: | ||
403 | |||
404 | @example | ||
405 | hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 | ||
406 | @end example | ||
407 | |||
408 | @noindent | ||
409 | The exact details may differ a bit, which is fine. Add the text | ||
410 | @emph{"gns [NOTFOUND=return]"} after @emph{"files"}. | ||
411 | Keep in mind that we included a backslash ("\") here just for | ||
412 | markup reasons. You should write the text below on @b{one line} | ||
413 | and @b{without} the "\": | ||
414 | |||
415 | @example | ||
416 | hosts: files gns [NOTFOUND=return] mdns4_minimal \ | ||
417 | [NOTFOUND=return] dns mdns4 | ||
418 | @end example | ||
419 | |||
420 | @c FIXME: Document new behavior. | ||
421 | You might want to make sure that @file{/lib/libnss_gns.so.2} exists on | ||
422 | your system, it should have been created during the installation. | ||
423 | |||
424 | @node Build instructions for Ubuntu 12.04 using Git | ||
425 | @section Build instructions for Ubuntu 12.04 using Git | ||
426 | |||
427 | @menu | ||
428 | * Install the required build tools:: | ||
429 | * Install libgcrypt 1.6 and libgpg-error:: | ||
430 | * Install gnutls with DANE support:: | ||
431 | * Install libgnurl:: | ||
432 | * Install libmicrohttpd from Git:: | ||
433 | * Install libextractor from Git:: | ||
434 | * Install GNUnet dependencies:: | ||
435 | * Build GNUnet:: | ||
436 | * Install the GNUnet-gtk user interface from Git:: | ||
437 | @end menu | ||
438 | |||
439 | @node Install the required build tools | ||
440 | @subsection Install the required build tools | ||
441 | |||
442 | First, make sure Git is installed on your system: | ||
443 | |||
444 | @example | ||
445 | $ sudo apt-get install git | ||
446 | @end example | ||
447 | |||
448 | Install the essential buildtools: | ||
449 | |||
450 | @example | ||
451 | $ sudo apt-get install automake autopoint autoconf libtool | ||
452 | @end example | ||
453 | |||
454 | @node Install libgcrypt 1.6 and libgpg-error | ||
455 | @subsection Install libgcrypt 1.6 and libgpg-error | ||
456 | |||
457 | @ref{generic source installation - libgpg-error} | ||
458 | |||
459 | @node Install gnutls with DANE support | ||
460 | @subsection Install gnutls with DANE support | ||
461 | |||
462 | @itemize @bullet | ||
463 | @item @ref{generic source installation - nettle} | ||
464 | @item @ref{generic source installation - ldns} | ||
465 | @item @ref{generic source installation - libunbound/unbound} | ||
466 | @item @ref{generic source installation - gnutls} | ||
467 | @item @ref{generic source installation - libgcrypt} | ||
468 | @end itemize | ||
469 | |||
470 | @node Install libgnurl | ||
471 | @subsection Install libgnurl | ||
472 | |||
473 | Follow the @ref{generic source installation - libgnurl}. | ||
474 | |||
475 | @node Install libmicrohttpd from Git | ||
476 | @subsection Install libmicrohttpd from Git | ||
477 | |||
478 | @example | ||
479 | $ git clone https://gnunet.org/git/libmicrohttpd | ||
480 | $ cd libmicrohttpd/ | ||
481 | $ ./bootstrap | ||
482 | $ ./configure | ||
483 | $ sudo make install ; cd .. | ||
484 | @end example | ||
485 | |||
486 | @node Install libextractor from Git | ||
487 | @subsection Install libextractor from Git | ||
488 | |||
489 | Install libextractor dependencies: | ||
490 | |||
491 | @example | ||
492 | $ sudo apt-get install zlib1g-dev libgsf-1-dev libmpeg2-4-dev \ | ||
493 | libpoppler-dev libvorbis-dev libexiv2-dev libjpeg-dev \ | ||
494 | libtiff-dev libgif-dev libvorbis-dev libflac-dev libsmf-dev \ | ||
495 | g++ | ||
496 | @end example | ||
497 | |||
498 | Build libextractor: | ||
499 | |||
500 | @example | ||
501 | $ git clone https://gnunet.org/git/libextractor | ||
502 | $ cd libextractor | ||
503 | $ ./bootstrap | ||
504 | $ ./configure | ||
505 | $ sudo make install ; cd .. | ||
506 | @end example | ||
507 | |||
508 | @node Install GNUnet dependencies | ||
509 | @subsection Install GNUnet dependencies | ||
510 | |||
511 | @example | ||
512 | $ sudo apt-get install libidn11-dev libunistring-dev libglpk-dev \ | ||
513 | libpulse-dev libbluetooth-dev libsqlite-dev | ||
514 | @end example | ||
515 | |||
516 | Install libopus: | ||
517 | |||
518 | @example | ||
519 | $ wget http://downloads.xiph.org/releases/opus/opus-1.1.tar.gz | ||
520 | $ tar xf opus-1.1.tar.gz | ||
521 | $ cd opus-1.1/ | ||
522 | $ ./configure | ||
523 | $ sudo make install ; cd .. | ||
524 | @end example | ||
525 | |||
526 | Choose one or more database backends: | ||
527 | |||
528 | SQLite3: | ||
529 | @example | ||
530 | $ sudo apt-get install libsqlite3-dev | ||
531 | @end example | ||
532 | MySQL: | ||
533 | @example | ||
534 | $ sudo apt-get install libmysqlclient-dev | ||
535 | @end example | ||
536 | PostgreSQL: | ||
537 | @example | ||
538 | $ sudo apt-get install libpq-dev postgresql | ||
539 | @end example | ||
540 | |||
541 | |||
542 | |||
543 | @node Build GNUnet | ||
544 | @subsection Build GNUnet | ||
545 | |||
546 | |||
547 | |||
548 | @menu | ||
549 | * Configuring the installation path:: | ||
550 | * Configuring the system:: | ||
551 | * Installing components requiring sudo permission:: | ||
552 | * Build:: | ||
553 | @end menu | ||
554 | |||
555 | @node Configuring the installation path | ||
556 | @subsubsection Configuring the installation path | ||
557 | |||
558 | You can specify the location of the GNUnet installation by setting the | ||
559 | prefix when calling the configure script with @code{--prefix=DIRECTORY} | ||
560 | |||
561 | @example | ||
562 | $ export PATH=$PATH:DIRECTORY/bin | ||
563 | @end example | ||
564 | |||
565 | @node Configuring the system | ||
566 | @subsubsection Configuring the system | ||
567 | |||
568 | Please make sure NOW that you have created a user and group 'gnunet' | ||
569 | and additionally a group 'gnunetdns': | ||
570 | |||
571 | @example | ||
572 | $ sudo addgroup gnunet | ||
573 | $ sudo addgroup gnunetdns | ||
574 | $ sudo adduser gnunet | ||
575 | @end example | ||
576 | |||
577 | Each GNUnet user should be added to the 'gnunet' group (may | ||
578 | require fresh login to come into effect): | ||
579 | |||
580 | @example | ||
581 | $ sudo useradd -G gnunet | ||
582 | @end example | ||
583 | |||
584 | @node Installing components requiring sudo permission | ||
585 | @subsubsection Installing components requiring sudo permission | ||
586 | |||
587 | Some components, like the nss plugin required for GNS, may require root | ||
588 | permissions. To allow these few components to be installed use: | ||
589 | |||
590 | @example | ||
591 | $ ./configure --with-sudo | ||
592 | @end example | ||
593 | |||
594 | @node Build | ||
595 | @subsubsection Build | ||
596 | |||
597 | @example | ||
598 | $ git clone https://gnunet.org/git/gnunet/ | ||
599 | $ cd gnunet/ | ||
600 | $ ./bootstrap | ||
601 | @end example | ||
602 | |||
603 | Use the required configure call including the optional installation prefix | ||
604 | @code{PREFIX} or the sudo permissions: | ||
605 | |||
606 | @example | ||
607 | $ ./configure [ --with-sudo | --with-prefix=PREFIX ] | ||
608 | @end example | ||
609 | |||
610 | @example | ||
611 | $ make; sudo make install | ||
612 | @end example | ||
613 | |||
614 | After installing it, you need to create an empty configuration file: | ||
615 | |||
616 | @example | ||
617 | mkdir ~/.gnunet; touch ~/.gnunet/gnunet.conf | ||
618 | @end example | ||
619 | |||
620 | And finally you can start GNUnet with: | ||
621 | |||
622 | @example | ||
623 | $ gnunet-arm -s | ||
624 | @end example | ||
625 | |||
626 | @node Install the GNUnet-gtk user interface from Git | ||
627 | @subsection Install the GNUnet-gtk user interface from Git | ||
628 | |||
629 | |||
630 | Install depencies: | ||
631 | |||
632 | @example | ||
633 | $ sudo apt-get install libgtk-3-dev libunique-3.0-dev libgladeui-dev \ | ||
634 | libqrencode-dev | ||
635 | @end example | ||
636 | |||
637 | Build GNUnet (with an optional prefix) and execute: | ||
638 | |||
639 | @example | ||
640 | $ git clone https://gnunet.org/git/gnunet-gtk/ | ||
641 | $ cd gnunet-gtk/ | ||
642 | $ ./bootstrap | ||
643 | $ ./configure [--prefix=PREFIX] --with-gnunet=DIRECTORY | ||
644 | $ make; sudo make install | ||
645 | @end example | ||
646 | |||
647 | @node Build instructions for software builds from source | ||
648 | @section Build instructions for software builds from source | ||
649 | |||
650 | This section describes software builds in case your operating | ||
651 | system lacks binary substitutes / binary builds for some dependencies | ||
652 | of GNUnet. | ||
653 | It is assumed that you have installed common build dependencies | ||
654 | and that these instructions are treated as generic without any | ||
655 | debugging help. | ||
656 | It is furthermore assumed that you use the release tarballs of | ||
657 | the software, installation from the respective version control | ||
658 | sources might differ in ways that are only minimal different | ||
659 | (for example a dependency on autotools etc). | ||
660 | |||
661 | @menu | ||
662 | * generic source installation - nettle:: | ||
663 | * generic source installation - ldns:: | ||
664 | * generic source installation - libunbound/unbound:: | ||
665 | * generic source installation - libav:: | ||
666 | * generic source installation - libextractor:: | ||
667 | * generic source installation - libgpg-error:: | ||
668 | * generic source installation - libgcrypt:: | ||
669 | * generic source installation - gnutls:: | ||
670 | * generic source installation - libmicrohttpd:: | ||
671 | * generic source installation - libgnurl:: | ||
672 | @end menu | ||
673 | |||
674 | @node generic source installation - nettle | ||
675 | @subsection generic source installation - nettle | ||
676 | |||
677 | @example | ||
678 | $ wget http://www.lysator.liu.se/~nisse/archive/nettle-2.7.1.tar.gz | ||
679 | $ tar xf nettle-2.7.1.tar.gz | ||
680 | $ cd nettle-2.7.1 | ||
681 | $ ./configure | ||
682 | $ sudo make install ; cd .. | ||
683 | @end example | ||
684 | |||
685 | @node generic source installation - ldns | ||
686 | @subsection generic source installation - ldns | ||
687 | |||
688 | @example | ||
689 | $ wget https://www.nlnetlabs.nl/downloads/ldns/ldns-1.6.16.tar.gz | ||
690 | $ tar xf ldns-1.6.16.tar.gz | ||
691 | $ cd ldns-1.6.16 | ||
692 | $ ./configure | ||
693 | $ sudo make install ; cd .. | ||
694 | @end example | ||
695 | |||
696 | @node generic source installation - libunbound/unbound | ||
697 | @subsection generic source installation - libunbound/unbound | ||
698 | |||
699 | @example | ||
700 | $ wget https://unbound.net/downloads/unbound-1.4.21.tar.gz | ||
701 | $ tar xf unbound-1.4.21.tar.gz | ||
702 | $ cd unbound-1.4.21 | ||
703 | $ ./configure | ||
704 | $ sudo make install ; cd .. | ||
705 | @end example | ||
706 | |||
707 | @node generic source installation - libav | ||
708 | @subsection generic source installation - libav | ||
709 | |||
710 | @example | ||
711 | $ wget https://libav.org/releases/libav-9.10.tar.xz | ||
712 | $ cd libav-0.9 ; ./configure --enable-shared; | ||
713 | $ make; sudo make install; cd .. | ||
714 | @end example | ||
715 | |||
716 | @node generic source installation - libextractor | ||
717 | @subsection generic source installation - libextractor | ||
718 | |||
719 | @example | ||
720 | $ wget https://ftp.gnu.org/gnu/libextractor/libextractor-1.3.tar.gz | ||
721 | $ tar xvf libextractor-1.3.tar.gz | ||
722 | $ cd libextractor-1.3 ; ./configure; | ||
723 | $ make ; sudo make install; cd .. | ||
724 | @end example | ||
725 | |||
726 | @node generic source installation - libgpg-error | ||
727 | @subsection generic source installation - libgpg-error | ||
728 | |||
729 | @example | ||
730 | $ wget https://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2 | ||
731 | $ tar xvf libgpg-error-1.12.tar.bz2 | ||
732 | $ cd libgpg-error-1.12; ./configure; | ||
733 | $ make ; sudo make install; cd .. | ||
734 | @end example | ||
735 | |||
736 | @node generic source installation - libgcrypt | ||
737 | @subsection generic source installation - libgcrypt | ||
738 | @example | ||
739 | $ wget https://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2 | ||
740 | $ tar xvf libgcrypt-1.6.0.tar.bz2 | ||
741 | $ cd libgcrypt-1.6.0; ./configure --with-gpg-error-prefix=/usr/local; | ||
742 | $ make ; sudo make install ; cd .. | ||
743 | @end example | ||
744 | |||
745 | @node generic source installation - gnutls | ||
746 | @subsection generic source installation - gnutls | ||
747 | |||
748 | @example | ||
749 | $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.2/gnutls-3.2.7.tar.xz | ||
750 | $ tar xvf gnutls-3.2.7.tar.xz | ||
751 | $ cd gnutls-3.2.7 | ||
752 | @end example | ||
753 | |||
754 | @noindent | ||
755 | If you want a GnuTLS with DANE functionality (recommended for GNUnet), | ||
756 | you have to compile it against libunbound. Assuming that libunbound | ||
757 | is installed on your system: | ||
758 | |||
759 | @example | ||
760 | $ ./configure --enable-libdane | ||
761 | @end example | ||
762 | |||
763 | @noindent | ||
764 | Note that the build system of GnuTLS should pick up libunbound without | ||
765 | the explicit mention of @code{--enable-libdane}. | ||
766 | If you don't want libdane support you should pass @code{--disable-libdane} | ||
767 | instead. | ||
768 | |||
769 | @example | ||
770 | $ ./configure | ||
771 | $ make ; sudo make install ; cd .. | ||
772 | @end example | ||
773 | |||
774 | @node generic source installation - libmicrohttpd | ||
775 | @subsection generic source installation - libmicrohttpd | ||
776 | |||
777 | @example | ||
778 | $ wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.33.tar.gz | ||
779 | $ tar xvf libmicrohttpd-0.9.33.tar.gz | ||
780 | $ cd libmicrohttpd-0.9.33; ./configure; | ||
781 | $ make ; sudo make install ; cd .. | ||
782 | @end example | ||
783 | |||
784 | @node generic source installation - libgnurl | ||
785 | @subsection generic source installation - libgnurl | ||
786 | |||
787 | Example installation of libgnurl version 7.57.0 from source. | ||
788 | |||
789 | @example | ||
790 | $ wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.57.0.tar.xz | ||
791 | $ wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.57.0.tar.xz.sig | ||
792 | $ gpg --verify gnurl-7.57.0.tar.xz.sig | ||
793 | @end example | ||
794 | |||
795 | @noindent | ||
796 | If that command fails because you do not have the required public key, | ||
797 | then run this command to import it: | ||
798 | |||
799 | @example | ||
800 | $ gpg --keyserver pgp.mit.edu --recv-keys A88C8ADD129828D7EAC02E52E22F9BBFEE348588 | ||
801 | @end example | ||
802 | |||
803 | @noindent | ||
804 | and rerun the gpg --verify command. | ||
805 | |||
806 | @example | ||
807 | $ tar xvf gnurl-7.57.0.tar.xz | ||
808 | $ cd gnurl-7.57.0 | ||
809 | $ ./configure --disable-ntlm-wb | ||
810 | $ make ; sudo make install; cd .. | ||
811 | @end example | ||
812 | |||
813 | You have now build and installed libgnurl from source. | ||
814 | |||
815 | @menu | ||
816 | * Fixing libgnurl build issues:: | ||
817 | @end menu | ||
818 | |||
819 | @node Fixing libgnurl build issues | ||
820 | @subsubsection Fixing libgnurl build issues | ||
821 | |||
822 | @c FIXME: Obviously this subsection should be evaluated and | ||
823 | @c if still necessary moved into gnURL itself (README) or | ||
824 | @c into a separate section which deals with gnURL. | ||
825 | If you have to compile libgnurl from source (for example if the version | ||
826 | included in your distribution is too old or it's not included at all) | ||
827 | you perhaps might get an error message while running the | ||
828 | @command{configure} script: | ||
829 | |||
830 | @example | ||
831 | $ configure | ||
832 | ... | ||
833 | checking for 64-bit curl_off_t data type... unknown | ||
834 | checking for 32-bit curl_off_t data type... unknown | ||
835 | checking for 16-bit curl_off_t data type... unknown | ||
836 | configure: error: cannot find data type for curl_off_t. | ||
837 | @end example | ||
838 | |||
839 | @noindent | ||
840 | Solution: | ||
841 | |||
842 | Before running the @command{configure} script, set: | ||
843 | |||
844 | @example | ||
845 | CFLAGS="-I. -I$BUILD_ROOT/include" | ||
846 | @end example | ||
847 | |||
848 | @node Build Instructions for Microsoft Windows Platforms | ||
849 | @section Build Instructions for Microsoft Windows Platforms | ||
850 | |||
851 | @menu | ||
852 | * Introduction to building on MS Windows:: | ||
853 | * Requirements:: | ||
854 | * Dependencies & Initial Setup:: | ||
855 | * GNUnet Installation:: | ||
856 | * Adjusting Windows for running and testing GNUnet:: | ||
857 | * Building the GNUnet Installer:: | ||
858 | * Using GNUnet with Netbeans on Windows:: | ||
859 | @end menu | ||
860 | |||
861 | @node Introduction to building on MS Windows | ||
862 | @subsection Introduction to building on MS Windows | ||
863 | |||
864 | |||
865 | This document is a guide to building GNUnet and its dependencies on | ||
866 | Windows platforms. GNUnet development is mostly done under GNU/Linux and | ||
867 | especially git checkouts may not build out of the box. | ||
868 | We regret any inconvenience, and if you have problems, please report | ||
869 | them. | ||
870 | |||
871 | @node Requirements | ||
872 | @subsection Requirements | ||
873 | |||
874 | The Howto is based upon a @strong{Windows Server 2008 32bit} | ||
875 | @strong{Installation}, @strong{sbuild} and thus a | ||
876 | @uref{http://www.mingw.org/wiki/MSYS, MSYS+MinGW} | ||
877 | (W32-GCC-Compiler-Suite + Unix-like Userland) installation. sbuild | ||
878 | is a convenient set of scripts which creates a working msys/mingw | ||
879 | installation and installs most dependencies required for GNUnet. | ||
880 | |||
881 | As of the point of the creation of these instructions, | ||
882 | GNUnet @strong{requires} a Windows @strong{Server} 2003 or | ||
883 | newer for full feature support. | ||
884 | Windows Vista and later will also work, but | ||
885 | @strong{non-server version can not run a VPN-Exit-Node} as the NAT | ||
886 | features have been removed as of Windows Vista. | ||
887 | |||
888 | @c TODO: We should document Windows 10! | ||
889 | @c It seems like the situation hasn't changed with W10 | ||
890 | |||
891 | @node Dependencies & Initial Setup | ||
892 | @subsection Dependencies & Initial Setup | ||
893 | |||
894 | |||
895 | @itemize @bullet | ||
896 | |||
897 | @item | ||
898 | Install a fresh version of @strong{Python 2.x}, even if you are using a | ||
899 | x64-OS, install a 32-bit version for use with sbuild. | ||
900 | Python 3.0 is currently incompatible. | ||
901 | |||
902 | @item | ||
903 | Install your favorite @uref{http://code.google.com/p/tortoisegit/, git} & | ||
904 | @uref{http://tortoisesvn.net/, subversion}-clients. | ||
905 | |||
906 | @item | ||
907 | You will also need some archive-manager like | ||
908 | @uref{http://www.7-zip.org/, 7zip}. | ||
909 | |||
910 | @item | ||
911 | Pull a copy of sbuild to a directory of your choice, which will be used | ||
912 | in the remainder of this guide. For now, we will use | ||
913 | @file{c:\gnunet\sbuild\} | ||
914 | |||
915 | @item | ||
916 | in @file{sbuild\src\mingw\mingw32-buildall.sh}, comment out the packages | ||
917 | @strong{gnunet-svn} and @strong{gnunet-gtk-svn}, as we don't want sbuild | ||
918 | to compile/install those for us. | ||
919 | |||
920 | @item | ||
921 | Follow LRN's sbuild installation instructions.- | ||
922 | @end itemize | ||
923 | |||
924 | Please note that sbuild may (or will most likely) fail during | ||
925 | installation, thus you really HAVE to @strong{check the logfiles} created | ||
926 | during the installation process. | ||
927 | Certain packages may fail to build initially due to missing dependencies, | ||
928 | thus you may have to | ||
929 | @strong{substitute those with binary-versions initially}. Later on once | ||
930 | dependencies are satisfied you can re-build the newer package versions. | ||
931 | |||
932 | @strong{It is normal that you may have to repeat this step multiple times | ||
933 | and there is no uniform way to fix all compile-time issues, as the | ||
934 | build-process of many of the dependencies installed are rather unstable | ||
935 | on win32 and certain releases may not even compile at all.} | ||
936 | |||
937 | Most dependencies for GNUnet have been set up by sbuild, thus we now | ||
938 | should add the @file{bin/} directories in your new msys and mingw | ||
939 | installations to PATH. You will want to create a backup of your finished | ||
940 | msys-environment by now. | ||
941 | |||
942 | @node GNUnet Installation | ||
943 | @subsection GNUnet Installation | ||
944 | |||
945 | First, we need to launch our msys-shell, you can do this via | ||
946 | |||
947 | @file{C:\gnunet\sbuild\msys\msys.bat} | ||
948 | |||
949 | You might wish to take a look at this file and adjust some | ||
950 | login-parameters to your msys environment. | ||
951 | |||
952 | Also, sbuild added two pointpoints to your msys-environment, though those | ||
953 | might remain invisible: | ||
954 | |||
955 | @itemize @bullet | 49 | @itemize @bullet |
956 | 50 | @item sqlite + libsqlite (the default, requires no further configuration) | |
957 | @item | 51 | @item postgres + libpq |
958 | /mingw, which will mount your mingw-directory from sbuild/mingw and the | 52 | @item mysql + libmysqlclient |
959 | other one is | ||
960 | |||
961 | @item | ||
962 | /src which contains all the installation sources sbuild just compiled. | ||
963 | @end itemize | 53 | @end itemize |
964 | 54 | ||
965 | Check out the current GNUnet sources (git HEAD) from the | 55 | These are the dependencies only required for certain features |
966 | GNUnet repository "gnunet.git", we will do this in your home directory: | ||
967 | |||
968 | @code{git clone https://gnunet.org/git/gnunet/ ~/gnunet} | ||
969 | |||
970 | Now, we will first need to bootstrap the checked out installation and then | ||
971 | configure it accordingly. | ||
972 | |||
973 | @example | ||
974 | cd ~/gnunet | ||
975 | ./bootstrap | ||
976 | STRIP=true CPPFLAGS="-DUSE_IPV6=1 -DW32_VEH" CFLAGS="$CFLAGS -g -O2" \ | ||
977 | ./configure --prefix=/ --docdir=/share/doc/gnunet \ | ||
978 | --with-libiconv-prefix=/mingw --with-libintl-prefix=/mingw \ | ||
979 | --with-libcurl=/mingw --with-extractor=/mingw --with-sqlite=/mingw \ | ||
980 | --with-microhttpd=/mingw --with-plibc=/mingw --enable-benchmarks \ | ||
981 | --enable-expensivetests --enable-experimental --with-qrencode=/mingw \ | ||
982 | --enable-silent-rules --enable-experimental 2>&1 | tee -a ./configure.log | ||
983 | @end example | ||
984 | |||
985 | The parameters above will configure for a reasonable GNUnet installation | ||
986 | to the your msys-root directory. | ||
987 | Depending on which features your would like to build or you may need to | ||
988 | specify additional dependencies. Sbuild installed most libs into | ||
989 | the /mingw subdirectory, so remember to prefix library locations with | ||
990 | this path. | ||
991 | |||
992 | Like on a unixoid system, you might want to use your home directory as | ||
993 | prefix for your own GNUnet installation for development, without tainting | ||
994 | the buildenvironment. Just change the "prefix" parameter to point towards | ||
995 | ~/ in this case. | ||
996 | |||
997 | Now it's time to compile GNUnet as usual. Though this will take some time, | ||
998 | so you may fetch yourself a coffee or some Mate now... | ||
999 | |||
1000 | @example | ||
1001 | make ; make install | ||
1002 | @end example | ||
1003 | |||
1004 | @node Adjusting Windows for running and testing GNUnet | ||
1005 | @subsection Adjusting Windows for running and testing GNUnet | ||
1006 | |||
1007 | Assuming the build succeeded and you | ||
1008 | @strong{added the bin directory of your GNUnet to PATH}, you can now use | ||
1009 | your gnunet-installation as usual. | ||
1010 | Remember that UAC or the windows firewall may popup initially, blocking | ||
1011 | further execution of gnunet until you acknowledge them. | ||
1012 | |||
1013 | You will also have to take the usual steps to get peer-to-peer (p2p) | ||
1014 | software running properly (port forwarding, ...), | ||
1015 | and GNUnet will require administrative permissions as it may even | ||
1016 | install a device-driver (in case you are using gnunet-vpn and/or | ||
1017 | gnunet-exit). | ||
1018 | |||
1019 | @node Building the GNUnet Installer | ||
1020 | @subsection Building the GNUnet Installer | ||
1021 | |||
1022 | The GNUnet installer is made with | ||
1023 | @uref{http://nsis.sourceforge.net/, NSIS}. | ||
1024 | The installer script is located in @file{contrib\win} in the | ||
1025 | GNUnet source tree. | ||
1026 | |||
1027 | @node Using GNUnet with Netbeans on Windows | ||
1028 | @subsection Using GNUnet with Netbeans on Windows | ||
1029 | |||
1030 | TODO | ||
1031 | |||
1032 | @node Build instructions for Debian 7.5 | ||
1033 | @section Build instructions for Debian 7.5 | ||
1034 | |||
1035 | |||
1036 | These are the installation instructions for Debian 7.5. They were tested | ||
1037 | using a minimal, fresh Debian 7.5 AMD64 installation without non-free | ||
1038 | software (no contrib or non-free). | ||
1039 | By "minimal", we mean that during installation, we did not select any | ||
1040 | desktop environment, servers or system utilities during the "tasksel" | ||
1041 | step. Note that the packages and the dependencies that we will install | ||
1042 | during this chapter take about 1.5 GB of disk space. | ||
1043 | Combined with GNUnet and space for objects during compilation, you should | ||
1044 | not even attempt this unless you have about 2.5 GB free after the minimal | ||
1045 | Debian installation. | ||
1046 | Using these instructions to build a VM image is likely to require a | ||
1047 | minimum of 4-5 GB for the VM (as you will likely also want a desktop | ||
1048 | manager). | ||
1049 | |||
1050 | GNUnet's security model assumes that your @file{/home} directory is | ||
1051 | encrypted. Thus, if possible, you should encrypt your home partition | ||
1052 | (or per-user home directory). | ||
1053 | |||
1054 | Naturally, the exact details of the starting state for your installation | ||
1055 | should not matter much. For example, if you selected any of those | ||
1056 | installation groups you might simply already have some of the necessary | ||
1057 | packages installed. | ||
1058 | We did this for testing, as this way we are less likely to forget to | ||
1059 | mention a required package. | ||
1060 | Note that we will not install a desktop environment, but of course you | ||
1061 | will need to install one to use GNUnet's graphical user interfaces. | ||
1062 | Thus, it is suggested that you simply install the desktop environment of | ||
1063 | your choice before beginning with the instructions. | ||
1064 | |||
1065 | |||
1066 | |||
1067 | @menu | ||
1068 | * Update:: | ||
1069 | * Stable? Hah!:: | ||
1070 | * Update again:: | ||
1071 | * Installing packages:: | ||
1072 | * Installing dependencies from source:: | ||
1073 | * Installing GNUnet from source:: | ||
1074 | * But wait there is more!:: | ||
1075 | @end menu | ||
1076 | |||
1077 | @node Update | ||
1078 | @subsection Update | ||
1079 | |||
1080 | After any installation, you should begin by running | ||
1081 | |||
1082 | @example | ||
1083 | # apt-get update ; apt-get upgrade | ||
1084 | @end example | ||
1085 | |||
1086 | to ensure that all of your packages are up-to-date. Note that the "#" is | ||
1087 | used to indicate that you need to type in this command as "root" | ||
1088 | (or prefix with "sudo"), whereas "$" is used to indicate typing in a | ||
1089 | command as a normal user. | ||
1090 | |||
1091 | @node Stable? Hah! | ||
1092 | @subsection Stable? Hah! | ||
1093 | |||
1094 | Yes, we said we start with a Debian 7.5 "stable" system. However, to | ||
1095 | reduce the amount of compilation by hand, we will begin by allowing the | ||
1096 | installation of packages from the testing and unstable distributions as | ||
1097 | well. | ||
1098 | We will stick to "stable" packages where possible, but some packages will | ||
1099 | be taken from the other distributions. | ||
1100 | Start by modifying @file{/etc/apt/sources.list} to contain the | ||
1101 | following (possibly adjusted to point to your mirror of choice): | ||
1102 | |||
1103 | @example | ||
1104 | # These were there before: | ||
1105 | deb http://ftp.de.debian.org/debian/ wheezy main | ||
1106 | deb-src http://ftp.de.debian.org/debian/ wheezy main | ||
1107 | deb http://security.debian.org/ wheezy/updates main | ||
1108 | deb-src http://security.debian.org/ wheezy/updates main | ||
1109 | deb http://ftp.de.debian.org/debian/ wheezy-updates main | ||
1110 | deb-src http://ftp.de.debian.org/debian/ wheezy-updates main | ||
1111 | |||
1112 | # Add these lines (feel free to adjust the mirror): | ||
1113 | deb http://ftp.de.debian.org/debian/ testing main | ||
1114 | deb http://ftp.de.debian.org/debian/ unstable main | ||
1115 | @end example | ||
1116 | |||
1117 | The next step is to create/edit your @file{/etc/apt/preferences} | ||
1118 | file to look like this: | ||
1119 | |||
1120 | @example | ||
1121 | Package: * | ||
1122 | Pin: release a=stable,n=wheezy | ||
1123 | Pin-Priority: 700 | ||
1124 | |||
1125 | Package: * | ||
1126 | Pin: release o=Debian,a=testing | ||
1127 | Pin-Priority: 650 | ||
1128 | |||
1129 | Package: * | ||
1130 | Pin: release o=Debian,a=unstable | ||
1131 | Pin-Priority: 600 | ||
1132 | @end example | ||
1133 | |||
1134 | You can read more about Apt Preferences here and here. | ||
1135 | Note that other pinnings are likely to also work for GNUnet, the key | ||
1136 | thing is that you need some packages from unstable (as shown below). | ||
1137 | However, as unstable is unlikely to be comprehensive (missing packages) | ||
1138 | or might be problematic (crashing packages), you probably want others | ||
1139 | from stable and/or testing. | ||
1140 | |||
1141 | @node Update again | ||
1142 | @subsection Update again | ||
1143 | |||
1144 | Now, run again@ | ||
1145 | |||
1146 | @example | ||
1147 | # apt-get update@ | ||
1148 | # apt-get upgrade@ | ||
1149 | @end example | ||
1150 | |||
1151 | to ensure that all your new distribution indices are downloaded, and | ||
1152 | that your pinning is correct: the upgrade step should cause no changes | ||
1153 | at all. | ||
1154 | |||
1155 | @node Installing packages | ||
1156 | @subsection Installing packages | ||
1157 | |||
1158 | We begin by installing a few Debian packages from stable:@ | ||
1159 | |||
1160 | @example | ||
1161 | # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \ | ||
1162 | libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev \ | ||
1163 | texlive libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev \ | ||
1164 | libbz2-dev libexiv2-dev libflac-dev libgif-dev libglib2.0-dev \ | ||
1165 | libgtk-3-dev libmagic-dev libjpeg8-dev libmpeg2-4-dev libmp4v2-dev \ | ||
1166 | librpm-dev libsmf-dev libtidy-dev libtiff5-dev libvorbis-dev \ | ||
1167 | libogg-dev zlib1g-dev g++ gettext libgsf-1-dev libunbound-dev \ | ||
1168 | libqrencode-dev libgladeui-dev nasm texlive-latex-extra \ | ||
1169 | libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev | ||
1170 | @end example | ||
1171 | |||
1172 | After that, we install a few more packages from unstable:@ | ||
1173 | |||
1174 | @example | ||
1175 | # apt-get install -t unstable nettle-dev libgstreamer1.0-dev \ | ||
1176 | gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ | ||
1177 | libgstreamer-plugins-base1.0-dev | ||
1178 | @end example | ||
1179 | |||
1180 | @node Installing dependencies from source | ||
1181 | @subsection Installing dependencies from source | ||
1182 | |||
1183 | Next, we need to install a few dependencies from source. | ||
1184 | You might want to do this as a "normal" user and only run the | ||
1185 | @code{make install} steps as root (hence the @code{sudo} in the | ||
1186 | commands below). Also, you do this from any | ||
1187 | directory. We begin by downloading all dependencies, then extracting the | ||
1188 | sources, and finally compiling and installing the libraries. | ||
1189 | |||
1190 | For these steps, follow the instructions given in the | ||
1191 | installation from source instruction in this order: | ||
1192 | |||
1193 | @itemize @bullet | 56 | @itemize @bullet |
1194 | @item @ref{generic source installation - libav} | 57 | @item Texinfo (for building the documentation) |
1195 | @item @ref{generic source installation - libextractor} | 58 | @item Texlive (for building the documentation) |
1196 | @item @ref{generic source installation - libgpg-error} | 59 | @item miniupnpc (for traversing NAT boxes more reliably) |
1197 | @item @ref{generic source installation - libgcrypt} | 60 | @item libopus (for running the GNUnet conversation telephony application) |
1198 | @item @ref{generic source installation - gnutls} | 61 | @item libpulse (for running the GNUnet conversation telephony application) |
1199 | @item @ref{generic source installation - libmicrohttpd} | 62 | @item libogg (for running the GNUnet conversation telephony application) |
1200 | @item @ref{generic source installation - libgnurl} | 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) | ||
1201 | @end itemize | 68 | @end itemize |
1202 | 69 | ||
1203 | @node Installing GNUnet from source | 70 | @c ----------------------------------------------------------------------- |
1204 | @subsection Installing GNUnet from source | 71 | @node Getting the Source Code |
1205 | 72 | @section Getting the Source Code | |
1206 | 73 | You can either download the source code using git (you obviously need | |
1207 | For this, simply follow the generic installation instructions from | 74 | git installed) or as an archive. |
1208 | here. | ||
1209 | |||
1210 | @node But wait there is more! | ||
1211 | @subsection But wait there is more! | ||
1212 | |||
1213 | So far, we installed all of the packages and dependencies required to | ||
1214 | ensure that all of GNUnet would be built. | ||
1215 | However, while for example the plugins to interact with the MySQL or | ||
1216 | Postgres databases have been created, we did not actually install or | ||
1217 | configure those databases. Thus, you will need to install | ||
1218 | and configure those databases or stick with the default Sqlite database. | ||
1219 | Sqlite is usually fine for most applications, but MySQL can offer better | ||
1220 | performance and Postgres better resillience. | ||
1221 | |||
1222 | |||
1223 | @node Installing GNUnet from Git on Ubuntu 14.4 | ||
1224 | @section Installing GNUnet from Git on Ubuntu 14.4 | ||
1225 | |||
1226 | @strong{Install the required build tools:} | ||
1227 | 75 | ||
76 | Using git type | ||
1228 | @example | 77 | @example |
1229 | $ sudo apt-get install git automake autopoint autoconf | 78 | git clone https://gnunet.org/git/gnunet.git |
1230 | @end example | 79 | @end example |
1231 | 80 | ||
1232 | @strong{Install the required dependencies} | 81 | The archive can be found at |
1233 | 82 | @uref{https://gnunet.org/downloads}. Extract it using a graphical | |
83 | archive tool or @code{tar}: | ||
1234 | @example | 84 | @example |
1235 | $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ | 85 | tar xzvf gnunet-0.11.0pre66.tar.gz |
1236 | libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \ | ||
1237 | libmicrohttpd-dev libgnutls28-dev | ||
1238 | @end example | 86 | @end example |
1239 | 87 | ||
1240 | @strong{Choose one or more database backends} | 88 | In the next chapter we will assume that the source code is available |
1241 | 89 | in the home directory at @code{~/gnunet}. | |
1242 | @itemize @bullet | ||
1243 | 90 | ||
1244 | @item SQLite3: | 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. | ||
1245 | 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. | ||
1246 | @example | 101 | @example |
1247 | $ sudo apt-get install libsqlite3-dev | 102 | $ sudo useradd --system --groups gnunet --home-dir /var/lib/gnunet |
1248 | @end example | 103 | @end example |
1249 | 104 | ||
1250 | @item MySQL: | 105 | Now add your own user to the @code{gnunet} group. |
1251 | |||
1252 | @example | 106 | @example |
1253 | $ sudo apt-get install libmysqlclient-dev | 107 | $ sudo adduser alice gnunet |
1254 | @end example | 108 | @end example |
1255 | 109 | ||
1256 | @item PostgreSQL: | 110 | @c ----------------------------------------------------------------------- |
1257 | 111 | @node Preparing and Compiling the Source Code | |
1258 | @example | 112 | @section Preparing and Compiling the Source Code |
1259 | $ sudo apt-get install libpq-dev postgresql | 113 | For preparing the source code for compilation a bootstrap script and |
1260 | @end example | 114 | @code{configure} has to be run from the source code directory. When |
1261 | 115 | running @code{configure} the following options can be specified to | |
1262 | @end itemize | 116 | customize the compilation and installation process: |
1263 | |||
1264 | @strong{Install the optional dependencies for gnunet-conversation:} | ||
1265 | |||
1266 | @example | ||
1267 | $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev | ||
1268 | @end example | ||
1269 | |||
1270 | @strong{Install the libgrypt 1.6.1:} | ||
1271 | 117 | ||
1272 | @itemize @bullet | 118 | @itemize @bullet |
1273 | 119 | @item @code{--disable-documentation} - don't build the configuration documents | |
1274 | @item For Ubuntu 14.04: | 120 | @item @code{--enable-looging=[LOGLEVEL]} - choose a loglevel (@code{debug}, @code{info}, @code{warning} or @code{error}) |
1275 | 121 | @item @code{--prefix=[PATH]} - the directory where the GNUnet libraries and binaries will be installed | |
1276 | @example | 122 | @item @code{--with-extractor=[PATH]} - the path to libextractor |
1277 | $ sudo apt-get install libgcrypt20-dev | 123 | @item @code{--with-libidn=[PATH]} - the path to libidn |
1278 | @end example | 124 | @item @code{--with-microhttpd=[PATH]} - the path to libmicrohttpd |
1279 | 125 | @item @code{--with-sqlite=[PATH]} - the path to libsqlite | |
1280 | @item For Ubuntu older 14.04: | 126 | @item @code{--with-zlib=[PATH]} - the path to zlib |
1281 | 127 | @item @code{--with-sudo=[PATH]} - path to the sudo binary (no need to run @code{make install} as root if specified) | |
1282 | @example | ||
1283 | $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2 | ||
1284 | $ tar xf libgcrypt-1.6.1.tar.bz2 | ||
1285 | $ cd libgcrypt-1.6.1 | ||
1286 | $ ./configure | ||
1287 | $ sudo make install | ||
1288 | $ cd .. | ||
1289 | @end example | ||
1290 | |||
1291 | @end itemize | 128 | @end itemize |
1292 | 129 | ||
1293 | @strong{Install libgnurl} | 130 | The following example configures the installation prefix |
1294 | 131 | @code{/usr/lib} and disables building the documentation | |
1295 | @example | ||
1296 | $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2 | ||
1297 | $ tar xf gnurl-7.35.0.tar.bz2 | ||
1298 | $ cd gnurl-7.35.0 | ||
1299 | $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \ | ||
1300 | --without-libmetalink --without-winidn --without-librtmp \ | ||
1301 | --without-nghttp2 --without-nss --without-cyassl --without-polarssl \ | ||
1302 | --without-ssl --without-winssl --without-darwinssl --disable-sspi \ | ||
1303 | --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \ | ||
1304 | --disable-telnet --disable-tftp --disable-pop3 --disable-imap \ | ||
1305 | --disable-smtp --disable-gopher --disable-file --disable-ftp | ||
1306 | $ sudo make install | ||
1307 | $ cd .. | ||
1308 | @end example | ||
1309 | |||
1310 | @strong{Install GNUnet} | ||
1311 | |||
1312 | @example | 132 | @example |
1313 | $ git clone https://gnunet.org/git/gnunet/ | 133 | $ cd ~/gnunet |
1314 | $ cd gnunet/ | ||
1315 | $ ./bootstrap | 134 | $ ./bootstrap |
135 | $ configure --prefix=/usr/lib --disable-configuration | ||
1316 | @end example | 136 | @end example |
1317 | 137 | ||
1318 | If you want to: | 138 | After running the bootstrap script and @code{configure} successfully |
1319 | 139 | the source code can be compiled with make. Here @code{-j5} specifies | |
1320 | @itemize @bullet | 140 | that 5 threads should be used. |
1321 | |||
1322 | @item Install to a different directory: | ||
1323 | |||
1324 | @example | ||
1325 | --prefix=PREFIX | ||
1326 | @end example | ||
1327 | |||
1328 | @item | ||
1329 | Have sudo permission, but do not want to compile as root: | ||
1330 | |||
1331 | @example | ||
1332 | --with-sudo | ||
1333 | @end example | ||
1334 | |||
1335 | @item | ||
1336 | Want debug message enabled: | ||
1337 | |||
1338 | @example | ||
1339 | --enable-logging=verbose | ||
1340 | @end example | ||
1341 | |||
1342 | @end itemize | ||
1343 | |||
1344 | |||
1345 | @example | ||
1346 | $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose] | ||
1347 | $ make; sudo make install | ||
1348 | @end example | ||
1349 | |||
1350 | After installing it, you need to create an empty configuration file: | ||
1351 | |||
1352 | @example | ||
1353 | touch ~/.config/gnunet.conf | ||
1354 | @end example | ||
1355 | |||
1356 | And finally you can start GNUnet with | ||
1357 | |||
1358 | @example | ||
1359 | $ gnunet-arm -s | ||
1360 | @end example | ||
1361 | |||
1362 | @node Build instructions for Debian 8 | ||
1363 | @section Build instructions for Debian 8 | ||
1364 | @c FIXME: I -> we | ||
1365 | |||
1366 | These are the installation instructions for Debian 8. They were tested | ||
1367 | sing a fresh Debian 8 AMD64 installation without non-free software (no | ||
1368 | contrib or non-free). During installation, I only selected "lxde" for the | ||
1369 | desktop environment. | ||
1370 | Note that the packages and the dependencies that we will install during | ||
1371 | this chapter take about 1.5 GB of disk space. Combined with GNUnet and | ||
1372 | space for objects during compilation, you should not even attempt this | ||
1373 | unless you have about 2.5 GB free after the Debian installation. | ||
1374 | Using these instructions to build a VM image is likely to require a | ||
1375 | minimum of 4-5 GB for the VM (as you will likely also want a desktop | ||
1376 | manager). | ||
1377 | |||
1378 | GNUnet's security model assumes that your @code{/home} directory is | ||
1379 | encrypted. | ||
1380 | Thus, if possible, you should encrypt your entire disk, or at least just | ||
1381 | your home partition (or per-user home directory). | ||
1382 | |||
1383 | Naturally, the exact details of the starting state for your installation | ||
1384 | should not matter much. | ||
1385 | For example, if you selected any of those installation groups you might | ||
1386 | simply already have some of the necessary packages installed. Thus, it is | ||
1387 | suggested that you simply install the desktop environment of your choice | ||
1388 | before beginning with the instructions. | ||
1389 | |||
1390 | |||
1391 | @menu | ||
1392 | * Update Debian:: | ||
1393 | * Installing Debian Packages:: | ||
1394 | * Installing Dependencies from Source2:: | ||
1395 | * Installing GNUnet from Source2:: | ||
1396 | * But wait (again) there is more!:: | ||
1397 | @end menu | ||
1398 | |||
1399 | @node Update Debian | ||
1400 | @subsection Update Debian | ||
1401 | |||
1402 | After any installation, you should begin by running | ||
1403 | |||
1404 | @example | ||
1405 | # apt-get update | ||
1406 | # apt-get upgrade | ||
1407 | @end example | ||
1408 | |||
1409 | to ensure that all of your packages are up-to-date. Note that the "#" is | ||
1410 | used to indicate that you need to type in this command as "root" (or | ||
1411 | prefix with "sudo"), whereas "$" is used to indicate typing in a command | ||
1412 | as a normal user. | ||
1413 | |||
1414 | @node Installing Debian Packages | ||
1415 | @subsection Installing Debian Packages | ||
1416 | |||
1417 | We begin by installing a few Debian packages from stable: | ||
1418 | |||
1419 | @example | 141 | @example |
1420 | # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \ | 142 | $ make -j5 |
1421 | libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev texlive \ | ||
1422 | libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev libbz2-dev \ | ||
1423 | libflac-dev libgif-dev libglib2.0-dev libgtk-3-dev libmpeg2-4-dev \ | ||
1424 | libtidy-dev libvorbis-dev libogg-dev zlib1g-dev g++ gettext \ | ||
1425 | libgsf-1-dev libunbound-dev libqrencode-dev libgladeui-dev nasm \ | ||
1426 | texlive-latex-extra libunique-3.0-dev gawk miniupnpc libfuse-dev \ | ||
1427 | libbluetooth-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ | ||
1428 | libgstreamer-plugins-base1.0-dev nettle-dev libextractor-dev \ | ||
1429 | libgcrypt20-dev libmicrohttpd-dev | ||
1430 | @end example | 143 | @end example |
1431 | 144 | ||
1432 | @node Installing Dependencies from Source2 | 145 | @c ----------------------------------------------------------------------- |
1433 | @subsection Installing Dependencies from Source2 | 146 | @node Installation |
1434 | 147 | @section Installation | |
1435 | Yes, we said we start with a Debian 8 "stable" system, but because Debian | 148 | The compiled binaries can be installed using @code{make install}. It |
1436 | linked GnuTLS without support for DANE, we need to compile a few things, | 149 | needs to be run as root (or with sudo) because some binaries need the |
1437 | in addition to GNUnet, still by hand. Yes, you can run GNUnet using the | 150 | @code{suid} bit set. Without that some GNUnet subsystems (such as VPN) |
1438 | respective Debian packages, but then you will not get DANE support. | 151 | will not work. |
1439 | |||
1440 | Next, we need to install a few dependencies from source. You might want | ||
1441 | to do this as a "normal" user and only run the @code{make install} steps | ||
1442 | as root (hence the @code{sudo} in the commands below). Also, you do this | ||
1443 | from any directory. We begin by downloading all dependencies, then | ||
1444 | extracting the sources, and finally compiling and installing the | ||
1445 | libraries: | ||
1446 | |||
1447 | @example | ||
1448 | $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz | ||
1449 | $ tar xvf gnutls-3.3.12.tar.xz | ||
1450 | $ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd .. | ||
1451 | @end example | ||
1452 | |||
1453 | For the installation and compilation of libgnurl/gnURL refer to | ||
1454 | the generic installation section, | ||
1455 | @xref{generic source installation - libgnurl}. | ||
1456 | |||
1457 | @node Installing GNUnet from Source2 | ||
1458 | @subsection Installing GNUnet from Source2 | ||
1459 | |||
1460 | For this, simply follow the generic installation instructions from@ | ||
1461 | here. | ||
1462 | |||
1463 | @node But wait (again) there is more! | ||
1464 | @subsection But wait (again) there is more! | ||
1465 | |||
1466 | So far, we installed all of the packages and dependencies required to | ||
1467 | ensure that all of GNUnet would be built. However, while for example the | ||
1468 | plugins to interact with the MySQL or Postgres databases have been | ||
1469 | created, we did not actually install or configure those databases. | ||
1470 | Thus, you will need to install and configure those databases or stick | ||
1471 | with the default Sqlite database. Sqlite is usually fine for most | ||
1472 | applications, but MySQL can offer better performance and Postgres better | ||
1473 | resillience. | ||
1474 | |||
1475 | @c @node Build instructions for OpenBSD 6.2 | ||
1476 | @c @section Build instructions for OpenBSD 6.2 | ||
1477 | |||
1478 | @node Outdated build instructions for previous revisions | ||
1479 | @section Outdated build instructions for previous revisions | ||
1480 | |||
1481 | This chapter contains a collection of outdated, older installation guides. | ||
1482 | They are mostly intended to serve as a starting point for writing | ||
1483 | up-to-date instructions and should not be expected to work for | ||
1484 | GNUnet 0.10.x. | ||
1485 | A set of older installation instructions can also be found in the | ||
1486 | file @file{doc/outdated-and-old-installation-instructions.txt} in the | ||
1487 | source tree of GNUnet. | ||
1488 | |||
1489 | This file covers old instructions which no longer receive security | ||
1490 | updates or any kind of support. | ||
1491 | |||
1492 | @menu | ||
1493 | * Installing GNUnet 0.10.1 on Ubuntu 14.04:: | ||
1494 | * Building GLPK for MinGW:: | ||
1495 | * GUI build instructions for Ubuntu 12.04 using Subversion:: | ||
1496 | @c * Installation with gnunet-update:: | ||
1497 | * Instructions for Microsoft Windows Platforms (Old):: | ||
1498 | @end menu | ||
1499 | |||
1500 | |||
1501 | @node Installing GNUnet 0.10.1 on Ubuntu 14.04 | ||
1502 | @subsection Installing GNUnet 0.10.1 on Ubuntu 14.04 | ||
1503 | |||
1504 | Install the required dependencies: | ||
1505 | |||
1506 | @example | ||
1507 | $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ | ||
1508 | libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \ | ||
1509 | libmicrohttpd-dev libgnutls28-dev | ||
1510 | @end example | ||
1511 | |||
1512 | Choose one or more database backends: | ||
1513 | |||
1514 | @itemize @bullet | ||
1515 | |||
1516 | @item SQLite3 | ||
1517 | |||
1518 | @example | ||
1519 | $ sudo apt-get install libsqlite3-dev@ | ||
1520 | @end example | ||
1521 | |||
1522 | @item MySQL | ||
1523 | |||
1524 | @example | ||
1525 | $ sudo apt-get install libmysqlclient-dev@ | ||
1526 | @end example | ||
1527 | |||
1528 | @item PostgreSQL | ||
1529 | |||
1530 | @example | ||
1531 | $ sudo apt-get install libpq-dev postgresql@ | ||
1532 | @end example | ||
1533 | |||
1534 | @end itemize | ||
1535 | |||
1536 | Install the optional dependencies for gnunet-conversation: | ||
1537 | |||
1538 | @example | ||
1539 | $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev | ||
1540 | @end example | ||
1541 | |||
1542 | Install libgcrypt 1.6: | ||
1543 | |||
1544 | @itemize @bullet | ||
1545 | |||
1546 | @item For Ubuntu 14.04: | ||
1547 | |||
1548 | @example | ||
1549 | $ sudo apt-get install libgcrypt20-dev | ||
1550 | @end example | ||
1551 | |||
1552 | @item For Ubuntu older than 14.04: | ||
1553 | 152 | ||
1554 | @example | 153 | @example |
1555 | wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2 | ||
1556 | $ tar xf libgcrypt-1.6.1.tar.bz2 | ||
1557 | $ cd libgcrypt-1.6.1 | ||
1558 | $ ./configure | ||
1559 | $ sudo make install | 154 | $ sudo make install |
1560 | $ cd .. | ||
1561 | @end example | ||
1562 | @end itemize | ||
1563 | |||
1564 | Install libgnurl: | ||
1565 | |||
1566 | @pxref{generic source installation - libgnurl}. | ||
1567 | |||
1568 | Install GNUnet: | ||
1569 | |||
1570 | @example | ||
1571 | $ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz | ||
1572 | $ tar xf gnunet-0.10.1.tar.gz | ||
1573 | $ cd gnunet-0.10.1 | ||
1574 | @end example | ||
1575 | |||
1576 | If you want to: | ||
1577 | |||
1578 | @itemize @bullet | ||
1579 | |||
1580 | @item | ||
1581 | Install to a different directory: | ||
1582 | |||
1583 | @example | ||
1584 | --prefix=PREFIX | ||
1585 | @end example | 155 | @end example |
1586 | 156 | ||
1587 | @item | 157 | One important library is the GNS plugin for NSS (the name services |
1588 | Have sudo permission, but do not want to compile as root: | 158 | switch) which allows using GNS (the GNU name system) in the normal DNS |
1589 | 159 | resolution process. Unfortunately NSS expects it in a specific | |
1590 | @example | 160 | location (probably @code{/lib}) which may differ from the installation |
1591 | --with-sudo | 161 | prefix (see @code{--prefix} option in the previous section). This is |
1592 | @end example | 162 | why the pugin has to be installed manually. |
1593 | |||
1594 | @item | ||
1595 | Want debug message enabled: | ||
1596 | |||
1597 | @example | ||
1598 | --enable-logging=verbose | ||
1599 | @end example | ||
1600 | |||
1601 | @end itemize | ||
1602 | |||
1603 | @example | ||
1604 | $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose] | ||
1605 | $ make; sudo make install | ||
1606 | @end example | ||
1607 | 163 | ||
1608 | After installing it, you need to create an empty configuration file: | 164 | Find the directory where nss plugins are installed on your system, e.g. |
1609 | 165 | ||
1610 | @example | 166 | @example |
1611 | touch ~/.config/gnunet.conf | 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 | ||
1612 | @end example | 172 | @end example |
1613 | 173 | ||
1614 | And finally you can start GNUnet with | 174 | Copy the GNS NSS plugin to that directory: |
1615 | 175 | ||
1616 | @example | 176 | @example |
1617 | $ gnunet-arm -s | 177 | cp ~/gnunet/src/gns/nss/libnss_gns.so.2 /lib |
1618 | @end example | 178 | @end example |
1619 | 179 | ||
1620 | @node Building GLPK for MinGW | 180 | Now, to activate the plugin, you need to edit your |
1621 | @subsection Building GLPK for MinGW | 181 | @code{/etc/nsswitch.conf} where you should find a line like this: |
1622 | |||
1623 | GNUnet now requires the GNU Linear Programming Kit (GLPK). | ||
1624 | Since there's is no package you can install with @code{mingw-get} you | ||
1625 | have to compile it from source: | ||
1626 | |||
1627 | @itemize @bullet | ||
1628 | |||
1629 | @item Download the latest version from | ||
1630 | @uref{http://ftp.gnu.org/gnu/glpk/} | ||
1631 | |||
1632 | @item Unzip the downloaded source tarball using your favourite | ||
1633 | unzipper application In the MSYS shell | ||
1634 | |||
1635 | @item change to the respective directory | ||
1636 | |||
1637 | @item Configure glpk for "i686-pc-mingw32": | ||
1638 | 182 | ||
1639 | @example | 183 | @example |
1640 | ./configure '--build=i686-pc-mingw32' | 184 | hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 |
1641 | @end example | 185 | @end example |
1642 | 186 | ||
1643 | @item run | 187 | The exact details may differ a bit, which is fine. Add the text |
188 | @code{"gns [NOTFOUND=return]"} after @code{"files"}. | ||
1644 | 189 | ||
1645 | @example | 190 | @example |
1646 | make install check | 191 | hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 |
1647 | @end example | 192 | @end example |
1648 | 193 | ||
1649 | @end itemize | 194 | Optionally, if GNS shall be used with a browser, execute the GNS |
1650 | 195 | CA-setup script. It will isetup the GNS Certificate Authority with the | |
1651 | MinGW does not automatically detect the correct buildtype so you have to | 196 | user's browser. |
1652 | specify it manually. | ||
1653 | |||
1654 | |||
1655 | @node GUI build instructions for Ubuntu 12.04 using Subversion | ||
1656 | @subsection GUI build instructions for Ubuntu 12.04 using Subversion | ||
1657 | |||
1658 | After installing GNUnet you can continue installing the GNUnet GUI tools: | ||
1659 | |||
1660 | First, install the required dependencies: | ||
1661 | |||
1662 | @example | 197 | @example |
1663 | $ sudo apt-get install libgladeui-dev libqrencode-dev | 198 | $ gnunet-gns-proxy-setup-ca |
1664 | @end example | 199 | @end example |
1665 | 200 | ||
1666 | Please ensure that the GNUnet shared libraries can be found by the linker. | 201 | Finally install a configuration file in |
1667 | If you installed GNUnet libraries in a non standard path | 202 | @code{~/.gnunet/gnunet.conf}. Below you find an example config which |
1668 | (say GNUNET_PREFIX=/usr/local/lib/), you can | 203 | allows you to start GNUnet. |
1669 | |||
1670 | @itemize @bullet | ||
1671 | |||
1672 | @item set the environmental variable permanently to: | ||
1673 | 204 | ||
1674 | @example | 205 | @example |
1675 | LD_LIBRARY_PATH=$GNUNET_PREFIX | 206 | [arm] |
1676 | @end example | 207 | SYSTEM_ONLY = NO |
1677 | 208 | USER_ONLY = NO | |
1678 | @item or add @code{$GNUNET_PREFIX} to @file{/etc/ld.so.conf} | ||
1679 | |||
1680 | @end itemize | ||
1681 | |||
1682 | Now you can checkout and compile the GNUnet GUI tools: | ||
1683 | 209 | ||
1684 | @example | 210 | [transport] |
1685 | $ git clone https://gnunet.org/git/gnunet-gtk | 211 | PLUGINS = tcp |
1686 | $ cd gnunet-gtk | ||
1687 | $ ./bootstrap | ||
1688 | $ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/.. | ||
1689 | $ make install | ||
1690 | @end example | 212 | @end example |
1691 | 213 | ||
1692 | @c @node Installation with gnunet-update | ||
1693 | @c @subsection Installation with gnunet-update | ||
1694 | |||
1695 | @c gnunet-update project is an effort to introduce updates to GNUnet | ||
1696 | @c installations. An interesting to-be-implemented-feature of gnunet-update | ||
1697 | @c is that these updates are propagated through GNUnet's peer-to-peer | ||
1698 | @c network. More information about gnunet-update can be found at | ||
1699 | @c @c FIXME: Use correct cgit URL | ||
1700 | @c @uref{https://gnunet.org/git/gnunet-update.git/tree/plain/README}. | ||
1701 | |||
1702 | @c While the project is still under development, we have implemented the | ||
1703 | @c following features which we believe may be helpful for users and we | ||
1704 | @c would like them to be tested: | ||
1705 | |||
1706 | @c @itemize @bullet | ||
1707 | |||
1708 | @c @item | ||
1709 | @c Packaging GNUnet installation along with its run-time dependencies into | ||
1710 | @c update packages | ||
1711 | |||
1712 | @c @item | ||
1713 | @c Installing update packages into compatible hosts | ||
1714 | |||
1715 | @c @item | ||
1716 | @c Updating an existing installation (which had been installed by | ||
1717 | @c gnunet-update) to a newer one | ||
1718 | |||
1719 | @c @end itemize | ||
1720 | |||
1721 | @c The above said features of gnunet-update are currently available for | ||
1722 | @c testing on GNU/Linux systems. | ||
1723 | |||
1724 | @c The following is a guide to help you get started with gnunet-update. | ||
1725 | @c It shows you how to install the testing binary packages of GNUnet | ||
1726 | @c 0.9.1 we have at @uref{https://gnunet.org/install/}. | ||
1727 | |||
1728 | @c gnunet-update needs the following dependencies: | ||
1729 | |||
1730 | @c @itemize @bullet | ||
1731 | @c @item | ||
1732 | @c python @geq{} 2.6 | ||
1733 | |||
1734 | @c @item | ||
1735 | @c gnupg | ||
1736 | |||
1737 | @c @item | ||
1738 | @c python-gpgme | ||
1739 | @c @end itemize | ||
1740 | |||
1741 | |||
1742 | @c Checkout gnunet-update: | ||
1743 | 214 | ||
1744 | @c @c FIXME: git! | ||
1745 | @c @example | ||
1746 | @c $ svn checkout -r24905 https://gnunet.org/svn/gnunet-update@ | ||
1747 | @c @end example | ||
1748 | 215 | ||
1749 | @c For security reasons, all packages released for gnunet-update from us are | ||
1750 | @c signed with the key at @uref{https://gnunet.org/install/key.txt}. | ||
1751 | @c You would need to import this key into your gpg key ring. | ||
1752 | @c gnunet-update uses this key to verify the integrity of the packages it | ||
1753 | @c installs: | ||
1754 | 216 | ||
1755 | @c @example | ||
1756 | @c $ gpg --recv-keys 7C613D78@ | ||
1757 | @c @end example | ||
1758 | 217 | ||
1759 | @c Download the packages relevant to your architecture (currently I have | ||
1760 | @c access to GNU/Linux machines on x86_64 and i686, so only two for now, | ||
1761 | @c hopefully more later) from https://gnunet.org/install/. | ||
1762 | 218 | ||
1763 | @c To install the downloaded package into the directory /foo: | 219 | @node MOVED FROM USER Checking the Installation |
1764 | 220 | @section MOVED FROM USER Checking the Installation | |
1765 | @c @example | 221 | @c %**end of header |
1766 | @c gnunet-update/bin/gnunet-update install downloaded/package /foo | ||
1767 | @c @end example | ||
1768 | |||
1769 | @c The installer reports the directories into which shared libraries and | ||
1770 | @c dependencies have been installed. You may need to add the reported shared | ||
1771 | @c library installation paths to LD_LIBRARY_PATH before you start running any | ||
1772 | @c installed binaries. | ||
1773 | |||
1774 | @c Please report bugs at https://gnunet.org/bugs/ under the project | ||
1775 | @c 'gnunet-update'. | ||
1776 | |||
1777 | @node Instructions for Microsoft Windows Platforms (Old) | ||
1778 | @subsection Instructions for Microsoft Windows Platforms (Old) | ||
1779 | |||
1780 | This document is a @b{DEPRECATED} installation guide for GNUnet on | ||
1781 | Windows. | ||
1782 | It will not work for recent GNUnet versions, but maybe it will be of | ||
1783 | some use if problems arise. | ||
1784 | 222 | ||
1785 | The Windows build uses a UNIX emulator for Windows, | 223 | This section describes a quick, casual way to check if your GNUnet |
1786 | @uref{http://www.mingw.org/, MinGW}, to build the executable modules. | 224 | installation works. However, if it does not, we do not cover |
1787 | These modules run natively on Windows and do not require additional | 225 | steps for recovery --- for this, please study the instructions |
1788 | emulation software besides the usual dependencies. | 226 | provided in the developer handbook as well as the system-specific |
227 | instruction in the source code repository@footnote{The system specific | ||
228 | instructions are not provided as part of this handbook!}. | ||
1789 | 229 | ||
1790 | GNUnet development is mostly done under GNU/Linux and especially git | ||
1791 | checkouts may not build out of the box. | ||
1792 | We regret any inconvenience, and if you have problems, please report them. | ||
1793 | 230 | ||
1794 | @menu | 231 | @menu |
1795 | * Hardware and OS requirements:: | 232 | * gnunet-gtk:: |
1796 | * Software installation:: | 233 | * Statistics:: |
1797 | * Building libextractor and GNUnet:: | 234 | * Peer Information:: |
1798 | * Installer:: | ||
1799 | * Source:: | ||
1800 | @end menu | 235 | @end menu |
1801 | 236 | ||
1802 | @node Hardware and OS requirements | 237 | @cindex GNUnet GTK |
1803 | @subsubsection Hardware and OS requirements | 238 | @cindex GTK |
1804 | 239 | @cindex GTK user interface | |
1805 | @itemize @bullet | 240 | @node gnunet-gtk |
1806 | 241 | @subsection gnunet-gtk | |
1807 | @item Pentium II or equivalent processor, @geq{} 350 MHz | 242 | @c %**end of header |
1808 | |||
1809 | @item 128 MB RAM | ||
1810 | |||
1811 | @item 600 MB free disk space | ||
1812 | |||
1813 | @item Windows 2000 or Windows XP are recommended | ||
1814 | |||
1815 | @end itemize | ||
1816 | |||
1817 | @node Software installation | ||
1818 | @subsubsection Software installation | ||
1819 | |||
1820 | @itemize @bullet | ||
1821 | |||
1822 | @item | ||
1823 | @strong{Compression software}@ | ||
1824 | |||
1825 | The software packages GNUnet depends on are usually compressed using UNIX | ||
1826 | tools like @command{tar}, @command{gzip}, @command{xzip} and | ||
1827 | @command{bzip2}. | ||
1828 | If you do not already have an utility that is able to extract such | ||
1829 | archives, get @uref{http://www.7-zip.org/, 7-Zip}. | ||
1830 | |||
1831 | @item | ||
1832 | @strong{UNIX environment}@ | ||
1833 | |||
1834 | The MinGW project provides the compiler toolchain that is used to build | ||
1835 | GNUnet. | ||
1836 | Get the following packages from the | ||
1837 | @uref{http://sourceforge.net/projects/mingw/files/, MinGW} project: | ||
1838 | |||
1839 | @itemize @bullet | ||
1840 | |||
1841 | @item GCC core | ||
1842 | @item GCC g++ | ||
1843 | @item MSYS | ||
1844 | @item MSYS Developer Tool Kit (msysDTK) | ||
1845 | @item MSYS Developer Tool Kit - msys-autoconf (bin) | ||
1846 | @item MSYS Developer Tool Kit - msys-automake (bin) | ||
1847 | @item MinGW Runtime | ||
1848 | @item MinGW Utilities | ||
1849 | @item Windows API | ||
1850 | @item Binutils | ||
1851 | @item make | ||
1852 | @item pdcurses | ||
1853 | @item GDB (snapshot) | ||
1854 | @end itemize | ||
1855 | |||
1856 | @itemize @bullet | ||
1857 | |||
1858 | |||
1859 | @item Install MSYS (to c:\mingw, for example.)@ | ||
1860 | Do @strong{not} use spaces in the pathname. | ||
1861 | For example, avoid a location such as @file{c:\program files\mingw}. | ||
1862 | |||
1863 | @item Install MinGW runtime, utilities and GCC to a subdirectory | ||
1864 | (to @file{c:\mingw\mingw}, for example) | ||
1865 | |||
1866 | @item Install the Development Kit to the MSYS directory | ||
1867 | (@file{c:\mingw}) | ||
1868 | |||
1869 | @item Create a batch file bash.bat in your MSYS directory with | ||
1870 | the files: | ||
1871 | |||
1872 | @example | ||
1873 | bin\sh.exe --login | ||
1874 | @end example | ||
1875 | |||
1876 | This batch file opens a shell which is used to invoke the build | ||
1877 | processes. | ||
1878 | MinGW's standard shell (@command{msys.bat}) is not suitable | ||
1879 | because it opens a separate console window. | ||
1880 | On Vista, @command{bash.bat} needs to be run as Administrator. | ||
1881 | |||
1882 | @item | ||
1883 | Start @command{bash.sh} and rename | ||
1884 | @file{c:\mingw\mingw\lib\libstdc++.la} to avoid problems: | ||
1885 | |||
1886 | @example | ||
1887 | mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken | ||
1888 | @end example | ||
1889 | |||
1890 | @item | ||
1891 | Unpack the Windows API to the MinGW directory (@file{c:\mingw\mingw\}) and | ||
1892 | remove the declaration of DATADIR from | ||
1893 | (@file{c:\mingw\mingw\include\objidl.h} (lines 55-58) | ||
1894 | |||
1895 | @item | ||
1896 | Unpack autoconf, automake to the MSYS directory (@file{c:\mingw}) | ||
1897 | |||
1898 | @item | ||
1899 | Install all other packages to the MinGW directory (@file{c:\mingw\mingw\}) | ||
1900 | @end itemize | ||
1901 | |||
1902 | |||
1903 | @item @strong{GNU Libtool}@ | ||
1904 | GNU Libtool is required to use shared libraries. | ||
1905 | Get the prebuilt package from here and unpack it to the | ||
1906 | MinGW directory (@file{c:\mingw}) | ||
1907 | 243 | ||
1908 | @item @strong{Pthreads}@ | 244 | The @command{gnunet-gtk} package contains several graphical |
1909 | GNUnet uses the portable POSIX thread library for multi-threading: | 245 | user interfaces for the respective GNUnet applications. |
246 | Currently these interfaces cover: | ||
1910 | 247 | ||
1911 | @itemize @bullet | 248 | @itemize @bullet |
1912 | 249 | @item Statistics | |
1913 | @item Save | 250 | @item Peer Information |
1914 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/libpthreadGC2.a, libpthreadGC2.a} | 251 | @item GNU Name System |
1915 | (x86) or | 252 | @item File Sharing |
1916 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/libpthreadGC2.a, libpthreadGC2.a} | 253 | @item Identity Management |
1917 | (x64) as libpthread.a into the @file{lib} | 254 | @item Conversation |
1918 | directory (@file{c:\mingw\mingw\lib\libpthread.a}). | ||
1919 | |||
1920 | @item Save | ||
1921 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/pthreadGC2.dll, pthreadGC2.dll} | ||
1922 | (x86) or | ||
1923 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/pthreadGC2.dll, libpthreadGC2.a} | ||
1924 | (x64) into the MinGW @file{bin} directory (@file{c:\mingw\mingw\bin}). | ||
1925 | |||
1926 | @item Download all header files from | ||
1927 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/include/, include/} | ||
1928 | to the @file{include} directory (@file{c:\mingw\mingw\include}). | ||
1929 | @end itemize | 255 | @end itemize |
1930 | 256 | ||
257 | @node Statistics | ||
258 | @subsection Statistics | ||
259 | @c %**end of header | ||
1931 | 260 | ||
1932 | @item @strong{GNU MP}@ | 261 | First, you should launch GNUnet gtk@footnote{Obviously you should also |
1933 | GNUnet uses the GNU Multiple Precision library for special cryptographic | 262 | start gnunet, via gnunet-arm or the system provided method}. |
1934 | operations. Get the GMP binary package from the | 263 | You can do this from the command-line by typing |
1935 | @uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and | ||
1936 | unpack it to the MinGW directory (@file{c:\mingw\mingw}) | ||
1937 | |||
1938 | @item @strong{GNU Gettext}@ | ||
1939 | GNU gettext is used to provide national language support. | ||
1940 | Get the prebuilt package from hereand unpack it to the MinGW | ||
1941 | directory (@file{c:\mingw\mingw}) | ||
1942 | |||
1943 | @item @strong{GNU iconv}@ | ||
1944 | GNU Libiconv is used for character encoding conversion. | ||
1945 | Get the prebuilt package from here and unpack it to the MinGW | ||
1946 | directory (@file{c:\mingw\mingw}). | ||
1947 | |||
1948 | @item @strong{SQLite}@ | ||
1949 | GNUnet uses the SQLite database to store data. | ||
1950 | Get the prebuilt binary from here and unpack it to your MinGW directory. | ||
1951 | |||
1952 | @item @strong{MySQL}@ | ||
1953 | As an alternative to SQLite, GNUnet also supports MySQL. | ||
1954 | |||
1955 | @itemize @bullet | ||
1956 | |||
1957 | @item Get the binary installer from the | ||
1958 | @uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project} | ||
1959 | (version 4.1), install it and follow the instructions in | ||
1960 | @file{README.mysql}. | ||
1961 | |||
1962 | @item Create a temporary build directory (@file{c:\mysql}) | ||
1963 | |||
1964 | @item Copy the directories @file{include\} and @file{lib\} from the | ||
1965 | MySQL directory to the new directory | ||
1966 | |||
1967 | @item Get the patches from | ||
1968 | @uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and | ||
1969 | @uref{http://bugs.mysql.com/bug.php?id=8872&files=1, Bug #8872} (the | ||
1970 | latter is only required for MySQL | ||
1971 | |||
1972 | @example | ||
1973 | patch -p 0 | ||
1974 | @end example | ||
1975 | |||
1976 | @item Move @file{lib\opt\libmysql.dll} to @file{lib\libmysql.dll} | ||
1977 | |||
1978 | @item Change to @file{lib\} and create an import library: | ||
1979 | 264 | ||
1980 | @example | 265 | @example |
1981 | dlltool --input-def ../include/libmySQL.def \ | 266 | gnunet-statistics-gtk |
1982 | --dllname libmysql.dll \ | ||
1983 | --output-lib libmysqlclient.a -k | ||
1984 | @end example | 267 | @end example |
1985 | 268 | ||
1986 | @item Copy include\* to include\mysql\ | 269 | If your peer@footnote{The term ``peer'' is a common word used in |
1987 | 270 | federated and distributed networks to describe a participating device | |
1988 | @item Pass @code{--with-mysql=/c/mysql} to | 271 | which is connected to the network. Thus, your Personal Computer or |
1989 | @command{./configure} and copy @file{libmysql.dll} | 272 | whatever it is you are looking at the Gtk+ interface describes a |
1990 | to your PATH or GNUnet's @file{bin} directory | 273 | ``Peer'' or a ``Node''.} is running correctly, you should see a bunch |
1991 | @end itemize | 274 | of lines, all of which should be ``significantly'' above zero (at |
1992 | 275 | least if your peer has been running for more than a few seconds). The | |
1993 | 276 | lines indicate how many other peers your peer is connected to (via | |
1994 | @item @strong{GTK+}@ | 277 | different mechanisms) and how large the entire overlay network is |
1995 | @command{gnunet-gtk} and @command{libextractor} depend on GTK. | 278 | currently estimated to be. The X-axis represents time (in seconds |
1996 | Get the the binary and developer packages of @command{atk}, | 279 | since the start of @command{gnunet-gtk}). |
1997 | @command{glib}, @command{gtk}, @command{iconv}, | ||
1998 | @command{gettext-runtime}, @command{pango} from | ||
1999 | @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack them | ||
2000 | to the MinGW directory (@file{c:\mingw\mingw}). | ||
2001 | @c FIXME: The URL below for pkg-config seems wrong. | ||
2002 | Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and | ||
2003 | @command{libpng} and unpack them to the MinGW directory | ||
2004 | (@file{c:\mingw\mingw}). | ||
2005 | Here is an all-in-one package for the | ||
2006 | @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies} | ||
2007 | . Do not overwrite any existing files! | ||
2008 | |||
2009 | @item @strong{Glade}@ | ||
2010 | @command{gnunet-gtk} and @command{gnunet-setup} were created using | ||
2011 | this interface builder | ||
2012 | 280 | ||
2013 | @itemize @bullet | 281 | You can click on "Traffic" to see information about the amount of |
2014 | 282 | bandwidth your peer has consumed, and on "Storage" to check the amount | |
2015 | @item Get the Glade and libglade (-bin and -devel) packages | 283 | of storage available and used by your peer. Note that "Traffic" is |
2016 | (without GTK!) from | 284 | plotted cumulatively, so you should see a strict upwards trend in the |
2017 | @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack them to | 285 | traffic. |
2018 | the MinGW directory (@file{c:\mingw\mingw}). | ||
2019 | |||
2020 | @item Get @command{libxml} from here and unpack it to the MinGW | ||
2021 | directory (@file{c:\mingw\mingw}). | ||
2022 | @end itemize | ||
2023 | |||
2024 | @c FIXME: URLs | ||
2025 | @item @strong{zLib}@ | ||
2026 | @command{libextractor} requires @command{zLib} to decompress some file | ||
2027 | formats. GNUnet uses it to (de)compress meta-data. | ||
2028 | Get zLib from here (Signature) and unpack it to the MinGW directory | ||
2029 | (@file{c:\mingw\mingw}). | ||
2030 | |||
2031 | @item @strong{Bzip2}@ | ||
2032 | @command{libextractor} also requires @command{Bzip2} to | ||
2033 | decompress some file formats. | ||
2034 | Get the Bzip2 (binary and developer package) from | ||
2035 | @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and | ||
2036 | unpack it to the MinGW directory (@file{c:\mingw\mingw}). | ||
2037 | |||
2038 | @item @strong{Libgcrypt}@ | ||
2039 | @command{Libgcrypt} provides the cryptographic functions used by GNUnet. | ||
2040 | Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here}, | ||
2041 | compile and place it in the MinGW directory | ||
2042 | (@file{c:\mingw\mingw}). Currently libgcrypt @geq{} 1.4.2 is required to | ||
2043 | compile GNUnet. | ||
2044 | |||
2045 | @item @strong{PlibC}@ | ||
2046 | PlibC emulates Unix functions under Windows. Get PlibC from here and | ||
2047 | unpack it to the MinGW directory (c:\mingw\mingw) | ||
2048 | |||
2049 | @item @strong{OGG Vorbis}@ | ||
2050 | @command{OGG Vorbis} is used to extract meta-data from @file{.ogg} files. | ||
2051 | Get the packages | ||
2052 | @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg} | ||
2053 | and | ||
2054 | @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis} | ||
2055 | from the | ||
2056 | @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build} | ||
2057 | and unpack them to the MinGW directory (c:\mingw\mingw). | ||
2058 | |||
2059 | @item @strong{Exiv2}@ | ||
2060 | (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data. | ||
2061 | Download | ||
2062 | @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2} | ||
2063 | and unpack it to the MSYS directory (c:\mingw). | ||
2064 | @end itemize | ||
2065 | 286 | ||
2066 | @node Building libextractor and GNUnet | 287 | @node Peer Information |
2067 | @subsubsection Building libextractor and GNUnet | 288 | @subsection Peer Information |
2068 | 289 | @c %**end of header | |
2069 | Before you compile @command{libextractor} or @command{GNUnet}, | ||
2070 | be sure to set @code{PKG_CONFIG_PATH}: | ||
2071 | |||
2072 | @example | ||
2073 | export PKG_CONFIG_PATH=/mingw/lib/pkgconfig | ||
2074 | @end example | ||
2075 | 290 | ||
2076 | @noindent | 291 | First, you should launch the graphical user interface. You can do |
2077 | @xref{GNUnet Installation Handbook}, for basic instructions on building | 292 | this from the command-line by typing |
2078 | @command{libextractor} and @command{GNUnet}. | ||
2079 | By default, all modules that are created in this way contain | ||
2080 | debug information and are quite large. To compile release versions | ||
2081 | (small and fast) set the variable @code{CFLAGS}: | ||
2082 | 293 | ||
2083 | @example | 294 | @example |
2084 | export CFLAGS='-O2 -march=pentium -fomit-frame-pointer' | 295 | $ gnunet-peerinfo-gtk |
2085 | ./configure --prefix=$HOME --with-extractor=$HOME | ||
2086 | @end example | 296 | @end example |
2087 | 297 | ||
2088 | @node Installer | 298 | Once you have done this, you will see a list of known peers (by the |
2089 | @subsubsection Installer | 299 | first four characters of their public key), their friend status (all |
2090 | 300 | should be marked as not-friends initially), their connectivity (green | |
2091 | The GNUnet installer is made with | 301 | is connected, red is disconnected), assigned bandwidth, country of |
2092 | @uref{http://nsis.sourceforge.net/, NSIS}. The installer script is | 302 | origin (if determined) and address information. If hardly any peers |
2093 | located in @file{contrib\win} in the GNUnet source tree. | 303 | are listed and/or if there are very few peers with a green light for |
2094 | 304 | connectivity, there is likely a problem with your network | |
2095 | @node Source | 305 | configuration. |
2096 | @subsubsection Source | ||
2097 | |||
2098 | @c FIXME: URL | ||
2099 | The sources of all dependencies are available here. | ||
2100 | |||
2101 | @c @node Portable GNUnet | ||
2102 | @c @section Portable GNUnet | ||
2103 | |||
2104 | @c Quick instructions on how to use the most recent GNUnet on most GNU/Linux | ||
2105 | @c distributions | ||
2106 | 306 | ||
2107 | @c Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian | 307 | @c NOTE: Inserted from Installation Handbook in original ``order'': |
2108 | @c and CentOS 6, but it should work on almost any GNU/Linux distribution. | 308 | @c FIXME: Move this to User Handbook. |
2109 | @c More in-detail information can be found in the handbook. | 309 | @node MOVED FROM USER The graphical configuration interface |
2110 | 310 | @section MOVED FROM USER The graphical configuration interface | |
2111 | @c Note 2017-10: Currently this section assumes the old SVN repo of GNUnet | ||
2112 | @c which no longer exists. | ||
2113 | |||
2114 | @c @menu | ||
2115 | @c * Prerequisites:: | ||
2116 | @c * Download & set up gnunet-update:: | ||
2117 | @c * Install GNUnet:: | ||
2118 | @c @end menu | ||
2119 | |||
2120 | @c @node Prerequisites | ||
2121 | @c @subsection Prerequisites | ||
2122 | |||
2123 | @c Open a terminal and paste this line into it to install all required tools | ||
2124 | @c needed: | ||
2125 | |||
2126 | @c @example | ||
2127 | @c sudo apt-get install python-gpgme subversion | ||
2128 | @c @end example | ||
2129 | |||
2130 | @c @node Download & set up gnunet-update | ||
2131 | @c @subsection Download & set up gnunet-update | ||
2132 | |||
2133 | @c The following command will download a working version of gnunet-update | ||
2134 | @c with the subversion tool and import the public key which is needed for | ||
2135 | @c authentication: | ||
2136 | |||
2137 | @c @example | ||
2138 | @c svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update | ||
2139 | @c cd ~/gnunet-update | ||
2140 | @c gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78 | ||
2141 | @c @end example | ||
2142 | |||
2143 | @c @node Install GNUnet | ||
2144 | @c @subsection Install GNUnet | ||
2145 | |||
2146 | @c Download and install GNUnet binaries which can be found here and set | ||
2147 | @c library paths: | ||
2148 | |||
2149 | @c @example | ||
2150 | @c wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz | ||
2151 | @c ./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~ | ||
2152 | @c echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment | ||
2153 | @c echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee \ | ||
2154 | @c /etc/ld.so.conf.d/gnunet.conf > /dev/null | ||
2155 | @c sudo ldconfig | ||
2156 | @c @end example | ||
2157 | |||
2158 | @c You may need to re-login once after executing these last commands | ||
2159 | |||
2160 | @c That's it, GNUnet is installed in your home directory now. GNUnet can be | ||
2161 | @c configured and afterwards started by executing: | ||
2162 | |||
2163 | @c @example | ||
2164 | @c gnunet-arm -s | ||
2165 | @c @end example | ||
2166 | |||
2167 | @node The graphical configuration interface | ||
2168 | @section The graphical configuration interface | ||
2169 | 311 | ||
2170 | If you also would like to use @command{gnunet-gtk} and | 312 | If you also would like to use @command{gnunet-gtk} and |
2171 | @command{gnunet-setup} (highly recommended for beginners), do: | 313 | @command{gnunet-setup} (highly recommended for beginners), do: |
2172 | 314 | ||
2173 | @example | ||
2174 | wget -P /tmp \ | ||
2175 | https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz | ||
2176 | sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~ | ||
2177 | sudo ldconfig | ||
2178 | @end example | ||
2179 | |||
2180 | Now you can run @command{gnunet-setup} for easy configuration of your | ||
2181 | GNUnet peer. | ||
2182 | |||
2183 | @menu | 315 | @menu |
2184 | * Configuring your peer:: | 316 | * Configuring your peer:: |
2185 | * Configuring the Friend-to-Friend (F2F) mode:: | 317 | * Configuring the Friend-to-Friend (F2F) mode:: |
@@ -2203,7 +335,7 @@ GNUnet peer. | |||
2203 | * Configuring the file-sharing service:: | 335 | * Configuring the file-sharing service:: |
2204 | * Configuring logging:: | 336 | * Configuring logging:: |
2205 | * Configuring the transport service and plugins:: | 337 | * Configuring the transport service and plugins:: |
2206 | * Configuring the wlan transport plugin:: | 338 | * Configuring the WLAN transport plugin:: |
2207 | * Configuring HTTP(S) reverse proxy functionality using Apache or nginx:: | 339 | * Configuring HTTP(S) reverse proxy functionality using Apache or nginx:: |
2208 | * Blacklisting peers:: | 340 | * Blacklisting peers:: |
2209 | * Configuration of the HTTP and HTTPS transport plugins:: | 341 | * Configuration of the HTTP and HTTPS transport plugins:: |
@@ -2320,7 +452,7 @@ SERVERS = http://v10.gnunet.org/hostlist [^] | |||
2320 | 452 | ||
2321 | @noindent | 453 | @noindent |
2322 | Besides using bootstrap servers you can configure your GNUnet peer to | 454 | Besides using bootstrap servers you can configure your GNUnet peer to |
2323 | recieve hostlist advertisements. | 455 | receive hostlist advertisements. |
2324 | Peers offering hostlists to other peers can send advertisement messages | 456 | Peers offering hostlists to other peers can send advertisement messages |
2325 | to peers that connect to them. If you configure your peer to receive these | 457 | to peers that connect to them. If you configure your peer to receive these |
2326 | messages, your peer can download these lists and connect to the peers | 458 | messages, your peer can download these lists and connect to the peers |
@@ -2413,8 +545,6 @@ list of peers can contact it to download this list. | |||
2413 | To download this hostlist the peer uses HTTP. | 545 | To download this hostlist the peer uses HTTP. |
2414 | For this reason you have to build your peer with libgnurl (or libcurl) | 546 | For this reason you have to build your peer with libgnurl (or libcurl) |
2415 | and microhttpd support. | 547 | and microhttpd support. |
2416 | How you build your peer with these options can be found here: | ||
2417 | @xref{Generic installation instructions}. | ||
2418 | 548 | ||
2419 | To configure your peer to act as a bootstrap server you have to add the | 549 | To configure your peer to act as a bootstrap server you have to add the |
2420 | @command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section | 550 | @command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section |
@@ -2547,10 +677,10 @@ password=$the_password_you_like | |||
2547 | 677 | ||
2548 | @end itemize | 678 | @end itemize |
2549 | 679 | ||
2550 | Thats it. Note that @file{.my.cnf} file is a slight security risk unless | 680 | That's it. Note that @file{.my.cnf} file is a slight security risk unless |
2551 | its on a safe partition. The @file{$HOME/.my.cnf} can of course be | 681 | its on a safe partition. The @file{$HOME/.my.cnf} can of course be |
2552 | a symbolic link. | 682 | a symbolic link. |
2553 | Luckily $USER has only priviledges to mess up GNUnet's tables, | 683 | Luckily $USER has only privileges to mess up GNUnet's tables, |
2554 | which should be pretty harmless. | 684 | which should be pretty harmless. |
2555 | 685 | ||
2556 | @node Testing | 686 | @node Testing |
@@ -2720,7 +850,7 @@ sqLite, MySQL and Postgres. | |||
2720 | 850 | ||
2721 | In order to use GNUnet for file-sharing, you first need to make sure | 851 | In order to use GNUnet for file-sharing, you first need to make sure |
2722 | that the file-sharing service is loaded. | 852 | that the file-sharing service is loaded. |
2723 | This is done by setting the @code{AUTOSTART} option in | 853 | This is done by setting the @code{START_ON_DEMAND} option in |
2724 | section @code{[fs]} to "YES". Alternatively, you can run | 854 | section @code{[fs]} to "YES". Alternatively, you can run |
2725 | 855 | ||
2726 | @example | 856 | @example |
@@ -2812,7 +942,7 @@ The configuration section for the transport service itself is quite | |||
2812 | similar to all the other services | 942 | similar to all the other services |
2813 | 943 | ||
2814 | @example | 944 | @example |
2815 | AUTOSTART = YES | 945 | START_ON_DEMAND = YES |
2816 | @@UNIXONLY@@ PORT = 2091 | 946 | @@UNIXONLY@@ PORT = 2091 |
2817 | HOSTNAME = localhost | 947 | HOSTNAME = localhost |
2818 | HOME = $SERVICEHOME | 948 | HOME = $SERVICEHOME |
@@ -2886,7 +1016,7 @@ TESTING_IGNORE_KEYS = ACCEPT_FROM; | |||
2886 | @end example | 1016 | @end example |
2887 | 1017 | ||
2888 | @noindent | 1018 | @noindent |
2889 | The server has a port configured and the maximum nunber of connections. | 1019 | The server has a port configured and the maximum number of connections. |
2890 | The HTTPS part has two files with the certificate key and the certificate | 1020 | The HTTPS part has two files with the certificate key and the certificate |
2891 | file. | 1021 | file. |
2892 | 1022 | ||
@@ -2928,8 +1058,8 @@ TESTING_IGNORE_KEYS = ACCEPT_FROM; | |||
2928 | @end example | 1058 | @end example |
2929 | @end itemize | 1059 | @end itemize |
2930 | 1060 | ||
2931 | @node Configuring the wlan transport plugin | 1061 | @node Configuring the WLAN transport plugin |
2932 | @subsection Configuring the wlan transport plugin | 1062 | @subsection Configuring the WLAN transport plugin |
2933 | 1063 | ||
2934 | The wlan transport plugin enables GNUnet to send and to receive data on a | 1064 | The wlan transport plugin enables GNUnet to send and to receive data on a |
2935 | wlan interface. | 1065 | wlan interface. |
@@ -3290,7 +1420,6 @@ and @code{[transport-https_client]} section of the configuration: | |||
3290 | * GNS Proxy Setup:: | 1420 | * GNS Proxy Setup:: |
3291 | * Setup of the GNS CA:: | 1421 | * Setup of the GNS CA:: |
3292 | * Testing the GNS setup:: | 1422 | * Testing the GNS setup:: |
3293 | * Automatic Shortening in the GNU Name System:: | ||
3294 | @end menu | 1423 | @end menu |
3295 | 1424 | ||
3296 | 1425 | ||
@@ -3526,8 +1655,11 @@ Now for testing purposes we can create some records in our zone to test | |||
3526 | the SSL functionality of the proxy: | 1655 | the SSL functionality of the proxy: |
3527 | 1656 | ||
3528 | @example | 1657 | @example |
3529 | $ gnunet-namestore -a -e "1 d" -n "homepage" -t A -V 131.159.74.67 | 1658 | $ gnunet-identity -C test |
3530 | $ gnunet-namestore -a -e "1 d" -n "homepage" -t LEHO -V "gnunet.org" | 1659 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ |
1660 | -t A -V 131.159.74.67 -z test | ||
1661 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ | ||
1662 | -t LEHO -V "gnunet.org" -z test | ||
3531 | @end example | 1663 | @end example |
3532 | 1664 | ||
3533 | @noindent | 1665 | @noindent |
@@ -3540,11 +1672,11 @@ $ gnunet-gns-proxy | |||
3540 | @noindent | 1672 | @noindent |
3541 | Configure your browser to use this SOCKSv5 proxy on port 7777 and visit | 1673 | Configure your browser to use this SOCKSv5 proxy on port 7777 and visit |
3542 | this link. | 1674 | this link. |
3543 | If you use @command{Firefox} (or one of its deriviates/forks such as | 1675 | If you use @command{Firefox} (or one of its derivatives/forks such as |
3544 | Icecat) you also have to go to @code{about:config} and set the key | 1676 | Icecat) you also have to go to @code{about:config} and set the key |
3545 | @code{network.proxy.socks_remote_dns} to @code{true}. | 1677 | @code{network.proxy.socks_remote_dns} to @code{true}. |
3546 | 1678 | ||
3547 | When you visit @code{https://homepage.gnu/}, you should get to the | 1679 | When you visit @code{https://homepage.test/}, you should get to the |
3548 | @code{https://gnunet.org/} frontpage and the browser (with the correctly | 1680 | @code{https://gnunet.org/} frontpage and the browser (with the correctly |
3549 | configured proxy) should give you a valid SSL certificate for | 1681 | configured proxy) should give you a valid SSL certificate for |
3550 | @code{homepage.gnu} and no warnings. It should look like this: | 1682 | @code{homepage.gnu} and no warnings. It should look like this: |
@@ -3552,26 +1684,6 @@ configured proxy) should give you a valid SSL certificate for | |||
3552 | @c FIXME: Image does not exist, create it or save it from Drupal? | 1684 | @c FIXME: Image does not exist, create it or save it from Drupal? |
3553 | @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} | 1685 | @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} |
3554 | 1686 | ||
3555 | @node Automatic Shortening in the GNU Name System | ||
3556 | @subsubsection Automatic Shortening in the GNU Name System | ||
3557 | |||
3558 | This page describes a possible option for 'automatic name shortening', | ||
3559 | which you can choose to enable with the GNU Name System. | ||
3560 | |||
3561 | When GNS encounters a name for the first time, it can use the 'NICK' | ||
3562 | record of the originating zone to automatically generate a name for the | ||
3563 | zone. If automatic shortening is enabled, those auto-generated names will | ||
3564 | be placed (as private records) into your personal 'shorten' zone (to | ||
3565 | prevent confusion with manually selected names). | ||
3566 | Then, in the future, if the same name is encountered again, GNS will | ||
3567 | display the shortened name instead (the first time, the long name will | ||
3568 | still be used as shortening typically happens asynchronously as looking up | ||
3569 | the 'NICK' record takes some time). Using this feature can be a convenient | ||
3570 | way to avoid very long @code{.gnu} names; however, note that names from | ||
3571 | the shorten-zone are assigned on a first-come-first-serve basis and should | ||
3572 | not be trusted. Furthermore, if you enable this feature, you will no | ||
3573 | longer see the full delegation chain for zones once shortening has been | ||
3574 | applied. | ||
3575 | 1687 | ||
3576 | @node Configuring the GNUnet VPN | 1688 | @node Configuring the GNUnet VPN |
3577 | @subsection Configuring the GNUnet VPN | 1689 | @subsection Configuring the GNUnet VPN |
@@ -3742,7 +1854,7 @@ configuration file). | |||
3742 | 1854 | ||
3743 | Some NAT boxes can be traversed using the autonomous NAT traversal method. | 1855 | Some NAT boxes can be traversed using the autonomous NAT traversal method. |
3744 | This requires certain GNUnet components to be installed with "SUID" | 1856 | This requires certain GNUnet components to be installed with "SUID" |
3745 | prividledges on your system (so if you're installing on a system you do | 1857 | privileges on your system (so if you're installing on a system you do |
3746 | not have administrative rights to, this will not work). | 1858 | not have administrative rights to, this will not work). |
3747 | If you installed as 'root', you can enable autonomous NAT traversal by | 1859 | If you installed as 'root', you can enable autonomous NAT traversal by |
3748 | checking the "Enable NAT traversal using ICMP method". | 1860 | checking the "Enable NAT traversal using ICMP method". |
@@ -3781,8 +1893,8 @@ desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account | |||
3781 | and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in | 1893 | and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in |
3782 | sequence. | 1894 | sequence. |
3783 | 1895 | ||
3784 | @node How to start and stop a GNUnet peer | 1896 | @node MOVED FROM USER Config Leftovers |
3785 | @section How to start and stop a GNUnet peer | 1897 | @section MOVED FROM USER Config Leftovers |
3786 | 1898 | ||
3787 | This section describes how to start a GNUnet peer. It assumes that you | 1899 | This section describes how to start a GNUnet peer. It assumes that you |
3788 | have already compiled and installed GNUnet and its' dependencies. | 1900 | have already compiled and installed GNUnet and its' dependencies. |
@@ -3867,7 +1979,7 @@ gnunet-arm -c ~/.config/gnunet.conf -k fs | |||
3867 | @noindent | 1979 | @noindent |
3868 | Assuming that you want certain services (like file-sharing) to be always | 1980 | Assuming that you want certain services (like file-sharing) to be always |
3869 | automatically started whenever you start GNUnet, you can activate them by | 1981 | automatically started whenever you start GNUnet, you can activate them by |
3870 | setting "FORCESTART=YES" in the respective section of the configuration | 1982 | setting "IMMEDIATE_START=YES" in the respective section of the configuration |
3871 | file (for example, "[fs]"). Then GNUnet with file-sharing support would | 1983 | file (for example, "[fs]"). Then GNUnet with file-sharing support would |
3872 | be started whenever you@ enter: | 1984 | be started whenever you@ enter: |
3873 | 1985 | ||
@@ -3906,8 +2018,8 @@ contain the lines:@ | |||
3906 | 2018 | ||
3907 | @example | 2019 | @example |
3908 | [arm] | 2020 | [arm] |
3909 | SYSTEM_ONLY = YES | 2021 | START_SYSTEM_SERVICES = YES |
3910 | USER_ONLY = NO | 2022 | START_USER_SERVICES = NO |
3911 | @end example | 2023 | @end example |
3912 | 2024 | ||
3913 | @noindent | 2025 | @noindent |
@@ -3935,8 +2047,8 @@ $USER with the lines: | |||
3935 | 2047 | ||
3936 | @example | 2048 | @example |
3937 | [arm] | 2049 | [arm] |
3938 | SYSTEM_ONLY = NO | 2050 | START_SYSTEM_SERVICES = NO |
3939 | USER_ONLY = YES | 2051 | START_USER_SERVICES = YES |
3940 | @end example | 2052 | @end example |
3941 | 2053 | ||
3942 | @noindent | 2054 | @noindent |
@@ -4004,7 +2116,7 @@ specific to a particular user, they probably should not run as a | |||
4004 | particular user. Also, there should typically only be one GNUnet peer per | 2116 | particular user. Also, there should typically only be one GNUnet peer per |
4005 | host. System services include the gnunet-service and gnunet-daemon | 2117 | host. System services include the gnunet-service and gnunet-daemon |
4006 | programs; support tools include command-line programs such as gnunet-arm. | 2118 | programs; support tools include command-line programs such as gnunet-arm. |
4007 | @item Priviledged helpers | 2119 | @item Privileged helpers |
4008 | Some GNUnet components require root rights to open raw sockets or perform | 2120 | Some GNUnet components require root rights to open raw sockets or perform |
4009 | other special operations. These gnunet-helper binaries are typically | 2121 | other special operations. These gnunet-helper binaries are typically |
4010 | installed SUID and run from services or daemons. | 2122 | installed SUID and run from services or daemons. |
@@ -4013,7 +2125,7 @@ Some GNUnet services (such as the DNS service) can manipulate the service | |||
4013 | in deep and possibly highly security sensitive ways. For example, the DNS | 2125 | in deep and possibly highly security sensitive ways. For example, the DNS |
4014 | service can be used to intercept and alter any DNS query originating from | 2126 | service can be used to intercept and alter any DNS query originating from |
4015 | the local machine. Access to the APIs of these critical services and their | 2127 | the local machine. Access to the APIs of these critical services and their |
4016 | priviledged helpers must be tightly controlled. | 2128 | privileged helpers must be tightly controlled. |
4017 | @end table | 2129 | @end table |
4018 | 2130 | ||
4019 | @c FIXME: The titles of these chapters are too long in the index. | 2131 | @c FIXME: The titles of these chapters are too long in the index. |
@@ -4111,3 +2223,4 @@ Furthermore, 'make install' will silently fail to set the DNS binaries to | |||
4111 | be owned by group "gnunetdns" unless that group already exists (!). | 2223 | be owned by group "gnunetdns" unless that group already exists (!). |
4112 | An alternative name for the "gnunetdns" group can be specified using the | 2224 | An alternative name for the "gnunetdns" group can be specified using the |
4113 | @code{--with-gnunetdns=GRPNAME} configure option. | 2225 | @code{--with-gnunetdns=GRPNAME} configure option. |
2226 | |||
diff --git a/doc/documentation/chapters/keyconcepts.texi b/doc/documentation/chapters/keyconcepts.texi new file mode 100644 index 000000000..55f79f1c7 --- /dev/null +++ b/doc/documentation/chapters/keyconcepts.texi | |||
@@ -0,0 +1,308 @@ | |||
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 | @footnote{Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth. | ||
85 | A Transport Layer Abstraction for Peer-to-Peer Networks | ||
86 | Proceedings of the 3rd International Symposium on Cluster Computing | ||
87 | and the Grid (GRID 2003), 2003. | ||
88 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf, https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf})} | ||
89 | |||
90 | @cindex Accounting to Encourage Resource Sharing | ||
91 | @node Accounting to Encourage Resource Sharing | ||
92 | @section Accounting to Encourage Resource Sharing | ||
93 | |||
94 | Most distributed P2P networks suffer from a lack of defenses or | ||
95 | precautions against attacks in the form of freeloading. | ||
96 | While the intentions of an attacker and a freeloader are different, their | ||
97 | effect on the network is the same; they both render it useless. | ||
98 | Most simple attacks on networks such as @command{Gnutella} | ||
99 | involve flooding the network with traffic, particularly | ||
100 | with queries that are, in the worst case, multiplied by the network. | ||
101 | |||
102 | In order to ensure that freeloaders or attackers have a minimal impact | ||
103 | on the network, GNUnet's file-sharing implementation (@code{FS} tries | ||
104 | to distinguish good (contributing) nodes from malicious (freeloading) | ||
105 | nodes. In GNUnet, every file-sharing node keeps track of the behavior | ||
106 | of every other node it has been in contact with. Many requests | ||
107 | (depending on the application) are transmitted with a priority (or | ||
108 | importance) level. That priority is used to establish how important | ||
109 | the sender believes this request is. If a peer responds to an | ||
110 | important request, the recipient will increase its trust in the | ||
111 | responder: the responder contributed resources. If a peer is too busy | ||
112 | to answer all requests, it needs to prioritize. For that, peers do | ||
113 | not take the priorities of the requests received at face value. | ||
114 | First, they check how much they trust the sender, and depending on | ||
115 | that amount of trust they assign the request a (possibly lower) | ||
116 | effective priority. Then, they drop the requests with the lowest | ||
117 | effective priority to satisfy their resource constraints. This way, | ||
118 | GNUnet's economic model ensures that nodes that are not currently | ||
119 | considered to have a surplus in contributions will not be served if | ||
120 | the network load is high. | ||
121 | @footnote{Christian Grothoff. An Excess-Based Economic Model for Resource | ||
122 | Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003. | ||
123 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf})} | ||
124 | @c 2009? | ||
125 | |||
126 | @cindex Confidentiality | ||
127 | @node Confidentiality | ||
128 | @section Confidentiality | ||
129 | |||
130 | Adversaries (malicious, bad actors) outside of GNUnet are not supposed | ||
131 | to know what kind of actions a peer is involved in. Only the specific | ||
132 | neighbor of a peer that is the corresponding sender or recipient of a | ||
133 | message may know its contents, and even then application protocols may | ||
134 | place further restrictions on that knowledge. In order to ensure | ||
135 | confidentiality, GNUnet uses link encryption, that is each message | ||
136 | exchanged between two peers is encrypted using a pair of keys only | ||
137 | known to these two peers. Encrypting traffic like this makes any kind | ||
138 | of traffic analysis much harder. Naturally, for some applications, it | ||
139 | may still be desirable if even neighbors cannot determine the concrete | ||
140 | contents of a message. In GNUnet, this problem is addressed by the | ||
141 | specific application-level protocols. See for example the following | ||
142 | sections @pxref{Anonymity}, @pxref{How file-sharing achieves Anonymity}, | ||
143 | and @pxref{Deniability}. | ||
144 | |||
145 | @cindex Anonymity | ||
146 | @node Anonymity | ||
147 | @section Anonymity | ||
148 | |||
149 | @menu | ||
150 | * How file-sharing achieves Anonymity:: | ||
151 | @end menu | ||
152 | |||
153 | Providing anonymity for users is the central goal for the anonymous | ||
154 | file-sharing application. Many other design decisions follow in the | ||
155 | footsteps of this requirement. | ||
156 | Anonymity is never absolute. While there are various | ||
157 | scientific metrics@footnote{Claudia DÃaz, Stefaan Seys, Joris Claessens, | ||
158 | and Bart Preneel. Towards measuring anonymity. | ||
159 | 2002. | ||
160 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf, https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf})} | ||
161 | that can help quantify the level of anonymity that a given mechanism | ||
162 | provides, there is no such thing as "complete anonymity". | ||
163 | GNUnet's file-sharing implementation allows users to select for each | ||
164 | operation (publish, search, download) the desired level of anonymity. | ||
165 | The metric used is the amount of cover traffic available to hide the | ||
166 | request. | ||
167 | While this metric is not as good as, for example, the theoretical metric | ||
168 | given in scientific metrics@footnote{likewise}, | ||
169 | it is probably the best metric available to a peer with a purely local | ||
170 | view of the world that does not rely on unreliable external information. | ||
171 | The default anonymity level is @code{1}, which uses anonymous routing but | ||
172 | imposes no minimal requirements on cover traffic. It is possible | ||
173 | to forego anonymity when this is not required. The anonymity level of | ||
174 | @code{0} allows GNUnet to use more efficient, non-anonymous routing. | ||
175 | |||
176 | @cindex How file-sharing achieves Anonymity | ||
177 | @node How file-sharing achieves Anonymity | ||
178 | @subsection How file-sharing achieves Anonymity | ||
179 | |||
180 | Contrary to other designs, we do not believe that users achieve strong | ||
181 | anonymity just because their requests are obfuscated by a couple of | ||
182 | indirections. This is not sufficient if the adversary uses traffic | ||
183 | analysis. | ||
184 | The threat model used for anonymous file sharing in GNUnet assumes that | ||
185 | the adversary is quite powerful. | ||
186 | In particular, we assume that the adversary can see all the traffic on | ||
187 | the Internet. And while we assume that the adversary | ||
188 | can not break our encryption, we assume that the adversary has many | ||
189 | participating nodes in the network and that it can thus see many of the | ||
190 | node-to-node interactions since it controls some of the nodes. | ||
191 | |||
192 | The system tries to achieve anonymity based on the idea that users can be | ||
193 | anonymous if they can hide their actions in the traffic created by other | ||
194 | users. | ||
195 | Hiding actions in the traffic of other users requires participating in the | ||
196 | traffic, bringing back the traditional technique of using indirection and | ||
197 | source rewriting. Source rewriting is required to gain anonymity since | ||
198 | otherwise an adversary could tell if a message originated from a host by | ||
199 | looking at the source address. If all packets look like they originate | ||
200 | from one node, the adversary can not tell which ones originate from that | ||
201 | node and which ones were routed. | ||
202 | Note that in this mindset, any node can decide to break the | ||
203 | source-rewriting paradigm without violating the protocol, as this | ||
204 | only reduces the amount of traffic that a node can hide its own traffic | ||
205 | in. | ||
206 | |||
207 | If we want to hide our actions in the traffic of other nodes, we must make | ||
208 | our traffic indistinguishable from the traffic that we route for others. | ||
209 | As our queries must have us as the receiver of the reply | ||
210 | (otherwise they would be useless), we must put ourselves as the receiver | ||
211 | of replies that actually go to other hosts; in other words, we must | ||
212 | indirect replies. | ||
213 | Unlike other systems, in anonymous file-sharing as implemented on top of | ||
214 | GNUnet we do not have to indirect the replies if we don't think we need | ||
215 | more traffic to hide our own actions. | ||
216 | |||
217 | This increases the efficiency of the network as we can indirect less under | ||
218 | higher load.@footnote{Krista Bennett and Christian Grothoff. | ||
219 | GAP --- practical anonymous networking. In Proceedings of | ||
220 | Designing Privacy Enhancing Technologies, 2003. | ||
221 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf, https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf})} | ||
222 | |||
223 | @cindex Deniability | ||
224 | @node Deniability | ||
225 | @section Deniability | ||
226 | |||
227 | Even if the user that downloads data and the server that provides data are | ||
228 | anonymous, the intermediaries may still be targets. In particular, if the | ||
229 | intermediaries can find out which queries or which content they are | ||
230 | processing, a strong adversary could try to force them to censor | ||
231 | certain materials. | ||
232 | |||
233 | With the file-encoding used by GNUnet's anonymous file-sharing, this | ||
234 | problem does not arise. | ||
235 | The reason is that queries and replies are transmitted in | ||
236 | an encrypted format such that intermediaries cannot tell what the query | ||
237 | is for or what the content is about. Mind that this is not the same | ||
238 | encryption as the link-encryption between the nodes. GNUnet has | ||
239 | encryption on the network layer (link encryption, confidentiality, | ||
240 | authentication) and again on the application layer (provided | ||
241 | by @command{gnunet-publish}, @command{gnunet-download}, | ||
242 | @command{gnunet-search} and @command{gnunet-gtk}). | ||
243 | @footnote{Christian Grothoff, Krista Grothoff, Tzvetan Horozov, | ||
244 | and Jussi T. Lindgren. | ||
245 | An Encoding for Censorship-Resistant Sharing. | ||
246 | 2009. | ||
247 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf})} | ||
248 | |||
249 | @cindex Peer Identities | ||
250 | @node Peer Identities | ||
251 | @section Peer Identities | ||
252 | |||
253 | Peer identities are used to identify peers in the network and are unique | ||
254 | for each peer. The identity for a peer is simply its public key, which is | ||
255 | generated along with a private key the peer is started for the first time. | ||
256 | While the identity is binary data, it is often expressed as ASCII string. | ||
257 | For example, the following is a peer identity as you might see it in | ||
258 | various places: | ||
259 | |||
260 | @example | ||
261 | UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0 | ||
262 | @end example | ||
263 | |||
264 | @noindent | ||
265 | You can find your peer identity by running @command{gnunet-peerinfo -s}. | ||
266 | |||
267 | @cindex Zones in the GNU Name System (GNS Zones) | ||
268 | @node Zones in the GNU Name System (GNS Zones) | ||
269 | @section Zones in the GNU Name System (GNS Zones) | ||
270 | |||
271 | @c FIXME: Explain or link to an explanation of the concept of public keys | ||
272 | @c and private keys. | ||
273 | @c FIXME: Rewrite for the latest GNS changes. | ||
274 | GNS@footnote{Matthias Wachs, Martin Schanzenbach, and Christian Grothoff. | ||
275 | A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name | ||
276 | System. In proceedings of 13th International Conference on Cryptology and | ||
277 | Network Security (CANS 2014). 2014. | ||
278 | @uref{https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf}} | ||
279 | zones are similar to those of DNS zones, but instead of a hierarchy of | ||
280 | authorities to governing their use, GNS zones are controlled by a private | ||
281 | key. | ||
282 | When you create a record in a DNS zone, that information is stored in your | ||
283 | nameserver. Anyone trying to resolve your domain then gets pointed | ||
284 | (hopefully) by the centralised authority to your nameserver. | ||
285 | Whereas GNS, being fully decentralized by design, stores that information | ||
286 | in DHT. The validity of the records is assured cryptographically, by | ||
287 | signing them with the private key of the respective zone. | ||
288 | |||
289 | Anyone trying to resolve records in a zone of your domain can then verify | ||
290 | the signature of the records they get from the DHT and be assured that | ||
291 | they are indeed from the respective zone. | ||
292 | To make this work, there is a 1:1 correspondence between zones and | ||
293 | their public-private key pairs. | ||
294 | So when we talk about the owner of a GNS zone, that's really the owner of | ||
295 | the private key. | ||
296 | And a user accessing a zone needs to somehow specify the corresponding | ||
297 | public key first. | ||
298 | |||
299 | @cindex Egos | ||
300 | @node Egos | ||
301 | @section Egos | ||
302 | |||
303 | @c what is the difference between peer identity and egos? It seems | ||
304 | @c like both are linked to public-private key pair. | ||
305 | Egos are your "identities" in GNUnet. Any user can assume multiple | ||
306 | identities, for example to separate their activities online. Egos can | ||
307 | correspond to "pseudonyms" or "real-world identities". Technically an | ||
308 | 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 index 681d5acc3..6d80d77ae 100644 --- a/doc/documentation/chapters/philosophy.texi +++ b/doc/documentation/chapters/philosophy.texi | |||
@@ -5,36 +5,28 @@ | |||
5 | @c NOTE: We should probably re-use some of the images lynX created | 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 | 6 | @c for secushare, showing some of the relations and functionalities |
7 | @c of GNUnet. | 7 | @c of GNUnet. |
8 | The foremost goal of the GNUnet project is to become a widely used, | 8 | The primary goal of the GNUnet project is to provide a reliable, open, |
9 | reliable, open, non-discriminating, egalitarian, unconstrained and | 9 | non-discriminating and censorship-resistant system for information |
10 | censorship-resistant system of free information exchange. | 10 | exchange. We value free speech above state interests and intellectual |
11 | We value free speech above state secrets, law-enforcement or | 11 | monopoly. GNUnet's long-term goal is to serve as a development |
12 | intellectual property. | 12 | platform for the next generation of Internet protocols. |
13 | GNUnet is supposed to be an anarchistic network, where the only | 13 | |
14 | limitation for participants (devices or people making use of the | 14 | GNUnet is an anarchistic network. Participants are encouraged to |
15 | network, in the following sometimes called peers) is | 15 | contribute at least as much resources (storage, bandwidth) to the network |
16 | that they must contribute enough back to the network such that | 16 | as they consume, so that their participation does not have a negative |
17 | their resource consumption does not have a significant impact | 17 | impact on other users. |
18 | on other users. | ||
19 | GNUnet should be more than just another file-sharing network. | ||
20 | The plan is to offer many other services and in particular | ||
21 | to serve as a development platform for the next generation of | ||
22 | Internet Protocols. | ||
23 | 18 | ||
24 | @menu | 19 | @menu |
25 | * Design Goals:: | 20 | * Design Principles:: |
26 | * Security and Privacy:: | 21 | * Privacy and Anonymity:: |
27 | * Versatility:: | ||
28 | * Practicality:: | 22 | * Practicality:: |
29 | * Key Concepts:: | ||
30 | @end menu | 23 | @end menu |
31 | 24 | ||
32 | @cindex Design Goals | 25 | @cindex Design Principles |
33 | @cindex Design Goals | 26 | @node Design Principles |
34 | @node Design Goals | 27 | @section Design Principles |
35 | @section Design Goals | ||
36 | 28 | ||
37 | These are the core GNUnet design goals, in order of relative importance: | 29 | These are the GNUnet design principles, in order of importance: |
38 | 30 | ||
39 | @itemize | 31 | @itemize |
40 | @item GNUnet must be implemented as | 32 | @item GNUnet must be implemented as |
@@ -44,385 +36,45 @@ These are the core GNUnet design goals, in order of relative importance: | |||
44 | the program, to study and change the program in source code form, | 36 | the program, to study and change the program in source code form, |
45 | to redistribute exact copies, and to distribute modified versions. | 37 | to redistribute exact copies, and to distribute modified versions. |
46 | Refer to @uref{https://www.gnu.org/philosophy/free-sw.html, https://www.gnu.org/philosophy/free-sw.html}} | 38 | Refer to @uref{https://www.gnu.org/philosophy/free-sw.html, https://www.gnu.org/philosophy/free-sw.html}} |
47 | @item GNUnet must only disclose the minimal amount of information | 39 | @item GNUnet must minimize the amount of personally identifiable information exposed. |
48 | necessary. | ||
49 | @c TODO: Explain 'fully' in the terminology section. | 40 | @c TODO: Explain 'fully' in the terminology section. |
50 | @item GNUnet must be fully distributed and survive | 41 | @item GNUnet must be fully distributed and resilient to external attacks and rogue participants. |
51 | @uref{https://en.wikipedia.org/wiki/Byzantine_fault_tolerance, Byzantine failures} | 42 | @item GNUnet must be self-organizing and not depend on administrators or centralized infrastructure. |
52 | @footnote{@uref{https://en.wikipedia.org/wiki/Byzantine_fault_tolerance, https://en.wikipedia.org/wiki/Byzantine_fault_tolerance}} | 43 | @item GNUnet must inform the user which other participants have to be trusted when establishing private communications. |
53 | at any position in the network. | ||
54 | @item GNUnet must make it explicit to the user which entities are | ||
55 | considered to be trustworthy when establishing secured communications. | ||
56 | @item GNUnet must use compartmentalization to protect sensitive | ||
57 | information. | ||
58 | @item GNUnet must be open and permit new peers to join. | 44 | @item GNUnet must be open and permit new peers to join. |
59 | @item GNUnet must be self-organizing and not depend on administrators. | ||
60 | @item GNUnet must support a diverse range of applications and devices. | 45 | @item GNUnet must support a diverse range of applications and devices. |
61 | @item The GNUnet architecture must be cost effective. | 46 | @item GNUnet must use compartmentalization to protect sensitive information. |
62 | @item GNUnet must provide incentives for peers to contribute more | 47 | @item The GNUnet architecture must be resource efficient. |
63 | resources than they consume. | 48 | @item GNUnet must provide incentives for peers to contribute more resources than they consume. |
64 | @end itemize | 49 | @end itemize |
65 | 50 | ||
66 | 51 | ||
67 | @cindex Security and Privacy | 52 | @cindex Privacy and Anonymity |
68 | @node Security and Privacy | 53 | @node Privacy and Anonymity |
69 | @section Security and Privacy | 54 | @section Privacy and Anonymity |
70 | |||
71 | GNUnet's primary design goals are to protect the privacy of its users and | ||
72 | to guard itself against attacks or abuse. | ||
73 | GNUnet does not have any mechanisms to control, track or censor users. | ||
74 | Instead, the GNUnet protocols aim to make it as hard as possible to | ||
75 | find out what is happening on the network or to disrupt operations. | ||
76 | 55 | ||
77 | @cindex Versatility | 56 | The GNUnet protocols minimize the leakage of personally identifiable information of participants and |
78 | @node Versatility | 57 | do not allow adversaries to control, track, monitor or censor users activities. The |
79 | @section Versatility | 58 | GNUnet protocols also make it as hard as possible to disrupt operations by participating in the network with malicious intent. |
80 | 59 | ||
81 | We call GNUnet a peer-to-peer framework because we want to support many | 60 | Analyzing participant's activities becomes more difficult as the number of peers and |
82 | different forms of peer-to-peer applications. GNUnet uses a plugin | 61 | applications that generate traffic on the network grows, even if the additional |
83 | architecture to make the system extensible and to encourage code reuse. | 62 | traffic generated is not related to anonymous communication. This is one of the reasons why GNUnet is developed as a peer-to-peer |
84 | While the first versions of the system only supported anonymous | ||
85 | file-sharing, other applications are being worked on and more will | ||
86 | hopefully follow in the future. | ||
87 | A powerful synergy regarding anonymity services is created by a large | ||
88 | community utilizing many diverse applications over the same software | ||
89 | infrastructure. The reason is that link encryption hides the specifics | ||
90 | of the traffic for non-participating observers. This way, anonymity can | ||
91 | get stronger with additional (GNUnet) traffic, even if the additional | ||
92 | traffic is not related to anonymous communication. Increasing anonymity | ||
93 | is the primary reason why GNUnet is developed to become a peer-to-peer | ||
94 | framework where many applications share the lower layers of an | 63 | framework where many applications share the lower layers of an |
95 | increasingly complex protocol stack. | 64 | increasingly complex protocol stack. The GNUnet architecture encourages many |
96 | If merging traffic to hinder traffic analysis was not important, | 65 | different forms of peer-to-peer applications. |
97 | we could have just developed a dozen stand-alone applications | ||
98 | and a few shared libraries. | ||
99 | 66 | ||
100 | @cindex Practicality | 67 | @cindex Practicality |
101 | @node Practicality | 68 | @node Practicality |
102 | @section Practicality | 69 | @section Practicality |
103 | 70 | ||
104 | GNUnet allows participants to trade various amounts of security in | 71 | Whereever possible GNUnet allows the peer to adjust its operations |
105 | exchange for increased efficiency. However, it is not possible for any | 72 | and functionalities to specific use cases. A GNUnet peer running on |
106 | user's security and efficiency requirements to compromise the security | 73 | a mobile device with limited battery for example might choose not to |
107 | and efficiency of any other user. | 74 | relay traffic for other participants. |
108 | |||
109 | For GNUnet, efficiency is not paramount. If there were a more secure and | ||
110 | still practical approach, we would choose to take the more secure | ||
111 | alternative. @command{telnet} is more efficient than @command{ssh}, yet | ||
112 | it is obsolete. | ||
113 | Hardware gets faster, and code can be optimized. Fixing security issues | ||
114 | as an afterthought is much harder. | ||
115 | |||
116 | While security is paramount, practicability is still a requirement. | ||
117 | The most secure system is always the one that nobody can use. | ||
118 | Similarly, any anonymous system that is extremely inefficient will only | ||
119 | find few users. | ||
120 | However, good anonymity requires a large and diverse user base. Since | ||
121 | individual security requirements may vary, the only good solution here is | ||
122 | to allow individuals to trade-off security and efficiency. | ||
123 | The primary challenge in allowing this is to ensure that the economic | ||
124 | incentives work properly. | ||
125 | In particular, this means that it must be impossible for a user to gain | ||
126 | security at the expense of other users. Many designs (e.g. anonymity via | ||
127 | broadcast) fail to give users an incentive to choose a less secure but | ||
128 | more efficient mode of operation. | ||
129 | GNUnet should avoid where ever possible to rely on protocols that will | ||
130 | only work if the participants are benevolent. | ||
131 | While some designs have had widespread success while relying on parties | ||
132 | to observe a protocol that may be sub-optimal for the individuals (e.g. | ||
133 | TCP Nagle), a protocol that ensures that individual goals never conflict | ||
134 | with the goals of the group is always preferable. | ||
135 | |||
136 | @cindex Key Concepts | ||
137 | @node Key Concepts | ||
138 | @section Key Concepts | ||
139 | |||
140 | In this section, the fundamental concepts of GNUnet are explained. | ||
141 | @c FIXME: Use @uref{https://docs.gnunet.org/bib/, research papers} | ||
142 | @c once we have the new bibliography + subdomain setup. | ||
143 | Most of them are also described in our research papers. | ||
144 | First, some of the concepts used in the GNUnet framework are detailed. | ||
145 | The second part describes concepts specific to anonymous file-sharing. | ||
146 | |||
147 | @menu | ||
148 | * Authentication:: | ||
149 | * Accounting to Encourage Resource Sharing:: | ||
150 | * Confidentiality:: | ||
151 | * Anonymity:: | ||
152 | * Deniability:: | ||
153 | * Peer Identities:: | ||
154 | * Zones in the GNU Name System (GNS Zones):: | ||
155 | * Egos:: | ||
156 | @end menu | ||
157 | |||
158 | @cindex Authentication | ||
159 | @node Authentication | ||
160 | @subsection Authentication | ||
161 | |||
162 | Almost all peer-to-peer communications in GNUnet are between mutually | ||
163 | authenticated peers. The authentication works by using ECDHE, that is a | ||
164 | DH (Diffie---Hellman) key exchange using ephemeral eliptic curve | ||
165 | cryptography. The ephemeral ECC (Eliptic Curve Cryptography) keys are | ||
166 | signed using ECDSA (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}). | ||
167 | The shared secret from ECDHE is used to create a pair of session keys | ||
168 | @c FIXME: LOng word for HKDF. More FIXMEs: Explain MITM etc. | ||
169 | (using HKDF) which are then used to encrypt the communication between the | ||
170 | two peers using both 256-bit AES (Advanced Encryption Standard) | ||
171 | and 256-bit Twofish (with independently derived secret keys). | ||
172 | As only the two participating hosts know the shared secret, this | ||
173 | authenticates each packet | ||
174 | without requiring signatures each time. GNUnet uses SHA-512 | ||
175 | (Secure Hash Algorithm) hash codes to verify the integrity of messages. | ||
176 | |||
177 | In GNUnet, the identity of a host is its public key. For that reason, | ||
178 | man-in-the-middle attacks will not break the authentication or accounting | ||
179 | goals. Essentially, for GNUnet, the IP of the host has nothing to do with | ||
180 | the identity of the host. As the public key is the only thing that truly | ||
181 | matters, faking an IP, a port or any other property of the underlying | ||
182 | transport protocol is irrelevant. In fact, GNUnet peers can use | ||
183 | multiple IPs (IPv4 and IPv6) on multiple ports --- or even not use the | ||
184 | IP protocol at all (by running directly on layer 2). | ||
185 | |||
186 | @c NOTE: For consistency we will use @code{HELLO}s throughout this Manual. | ||
187 | GNUnet uses a special type of message to communicate a binding between | ||
188 | public (ECC) keys to their current network address. These messages are | ||
189 | commonly called @code{HELLO}s or peer advertisements. | ||
190 | They contain the public key of the peer and its current network | ||
191 | addresses for various transport services. | ||
192 | A transport service is a special kind of shared library that | ||
193 | provides (possibly unreliable, out-of-order) message delivery between | ||
194 | peers. | ||
195 | For the UDP and TCP transport services, a network address is an IP and a | ||
196 | port. | ||
197 | GNUnet can also use other transports (HTTP, HTTPS, WLAN, etc.) which use | ||
198 | various other forms of addresses. Note that any node can have many | ||
199 | different active transport services at the same time, | ||
200 | and each of these can have a different addresses. | ||
201 | Binding messages expire after at most a week (the timeout can be | ||
202 | shorter if the user configures the node appropriately). | ||
203 | This expiration ensures that the network will eventually get rid of | ||
204 | outdated advertisements. | ||
205 | @footnote{Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth. | ||
206 | A Transport Layer Abstraction for Peer-to-Peer Networks | ||
207 | Proceedings of the 3rd International Symposium on Cluster Computing | ||
208 | and the Grid (GRID 2003), 2003. | ||
209 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf, https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf})} | ||
210 | |||
211 | @cindex Accounting to Encourage Resource Sharing | ||
212 | @node Accounting to Encourage Resource Sharing | ||
213 | @subsection Accounting to Encourage Resource Sharing | ||
214 | |||
215 | Most distributed P2P networks suffer from a lack of defenses or | ||
216 | precautions against attacks in the form of freeloading. | ||
217 | While the intentions of an attacker and a freeloader are different, their | ||
218 | effect on the network is the same; they both render it useless. | ||
219 | Most simple attacks on networks such as @command{Gnutella} | ||
220 | involve flooding the network with traffic, particularly | ||
221 | with queries that are, in the worst case, multiplied by the network. | ||
222 | |||
223 | In order to ensure that freeloaders or attackers have a minimal impact on | ||
224 | the network, GNUnet's file-sharing implementation tries to distinguish | ||
225 | good (contributing) nodes from malicious (freeloading) nodes. In GNUnet, | ||
226 | every file-sharing node keeps track of the behavior of every other node it | ||
227 | has been in contact with. Many requests (depending on the application) | ||
228 | are transmitted with a priority (or importance) level. | ||
229 | That priority is used to establish how important the sender believes | ||
230 | this request is. If a peer responds to an important request, the | ||
231 | recipient will increase its trust in the responder: | ||
232 | the responder contributed resources. | ||
233 | If a peer is too busy to answer all requests, it needs to prioritize. | ||
234 | For that, peers do not take the priorities of the requests received at | ||
235 | face value. | ||
236 | First, they check how much they trust the sender, and depending on that | ||
237 | amount of trust they assign the request a (possibly lower) effective | ||
238 | priority. Then, they drop the requests with the lowest effective priority | ||
239 | to satisfy their resource constraints. This way, GNUnet's economic model | ||
240 | ensures that nodes that are not currently considered to have a surplus in | ||
241 | contributions will not be served if the network load is high. | ||
242 | @footnote{Christian Grothoff. An Excess-Based Economic Model for Resource | ||
243 | Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003. | ||
244 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf})} | ||
245 | @c 2009? | ||
246 | |||
247 | @cindex Confidentiality | ||
248 | @node Confidentiality | ||
249 | @subsection Confidentiality | ||
250 | |||
251 | Adversaries outside of GNUnet are not supposed to know what kind of | ||
252 | actions a peer is involved in. Only the specific neighbor of a peer that | ||
253 | is the corresponding sender or recipient of a message may know its | ||
254 | contents, and even then application protocols may place further | ||
255 | restrictions on that knowledge. | ||
256 | In order to ensure confidentiality, GNUnet uses link encryption, that is | ||
257 | each message exchanged between two peers is encrypted using a pair of | ||
258 | keys only known to these two peers. | ||
259 | Encrypting traffic like this makes any kind of traffic analysis much | ||
260 | harder. Naturally, for some applications, it may still be desirable if | ||
261 | even neighbors cannot determine the concrete contents of a message. | ||
262 | In GNUnet, this problem is addressed by the specific application-level | ||
263 | protocols (see for example, deniability and anonymity in anonymous file | ||
264 | sharing). | ||
265 | |||
266 | @cindex Anonymity | ||
267 | @node Anonymity | ||
268 | @subsection Anonymity | ||
269 | 75 | ||
270 | @menu | 76 | For certain applications like file-sharing GNUnet allows participants to trade degrees of anonymity in |
271 | * How file-sharing achieves Anonymity:: | 77 | exchange for increased efficiency. However, it is not possible for any |
272 | @end menu | 78 | user's efficiency requirements to compromise the anonymity |
273 | 79 | of any other user. | |
274 | Providing anonymity for users is the central goal for the anonymous | ||
275 | file-sharing application. Many other design decisions follow in the | ||
276 | footsteps of this requirement. | ||
277 | Anonymity is never absolute. While there are various | ||
278 | scientific metrics@footnote{Claudia DÃaz, Stefaan Seys, Joris Claessens, | ||
279 | and Bart Preneel. Towards measuring anonymity. | ||
280 | 2002. | ||
281 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf, https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf})} | ||
282 | that can help quantify the level of anonymity that a given mechanism | ||
283 | provides, there is no such thing as complete anonymity. | ||
284 | GNUnet's file-sharing implementation allows users to select for each | ||
285 | operation (publish, search, download) the desired level of anonymity. | ||
286 | The metric used is the amount of cover traffic available to hide the | ||
287 | request. | ||
288 | While this metric is not as good as, for example, the theoretical metric | ||
289 | given in scientific metrics@footnote{likewise}, | ||
290 | it is probably the best metric available to a peer with a purely local | ||
291 | view of the world that does not rely on unreliable external information. | ||
292 | The default anonymity level is 1, which uses anonymous routing but | ||
293 | imposes no minimal requirements on cover traffic. It is possible | ||
294 | to forego anonymity when this is not required. The anonymity level of 0 | ||
295 | allows GNUnet to use more efficient, non-anonymous routing. | ||
296 | |||
297 | @cindex How file-sharing achieves Anonymity | ||
298 | @node How file-sharing achieves Anonymity | ||
299 | @subsubsection How file-sharing achieves Anonymity | ||
300 | |||
301 | Contrary to other designs, we do not believe that users achieve strong | ||
302 | anonymity just because their requests are obfuscated by a couple of | ||
303 | indirections. This is not sufficient if the adversary uses traffic | ||
304 | analysis. | ||
305 | The threat model used for anonymous file sharing in GNUnet assumes that | ||
306 | the adversary is quite powerful. | ||
307 | In particular, we assume that the adversary can see all the traffic on | ||
308 | the Internet. And while we assume that the adversary | ||
309 | can not break our encryption, we assume that the adversary has many | ||
310 | participating nodes in the network and that it can thus see many of the | ||
311 | node-to-node interactions since it controls some of the nodes. | ||
312 | |||
313 | The system tries to achieve anonymity based on the idea that users can be | ||
314 | anonymous if they can hide their actions in the traffic created by other | ||
315 | users. | ||
316 | Hiding actions in the traffic of other users requires participating in the | ||
317 | traffic, bringing back the traditional technique of using indirection and | ||
318 | source rewriting. Source rewriting is required to gain anonymity since | ||
319 | otherwise an adversary could tell if a message originated from a host by | ||
320 | looking at the source address. If all packets look like they originate | ||
321 | from one node, the adversary can not tell which ones originate from that | ||
322 | node and which ones were routed. | ||
323 | Note that in this mindset, any node can decide to break the | ||
324 | source-rewriting paradigm without violating the protocol, as this | ||
325 | only reduces the amount of traffic that a node can hide its own traffic | ||
326 | in. | ||
327 | |||
328 | If we want to hide our actions in the traffic of other nodes, we must make | ||
329 | our traffic indistinguishable from the traffic that we route for others. | ||
330 | As our queries must have us as the receiver of the reply | ||
331 | (otherwise they would be useless), we must put ourselves as the receiver | ||
332 | of replies that actually go to other hosts; in other words, we must | ||
333 | indirect replies. | ||
334 | Unlike other systems, in anonymous file-sharing as implemented on top of | ||
335 | GNUnet we do not have to indirect the replies if we don't think we need | ||
336 | more traffic to hide our own actions. | ||
337 | |||
338 | This increases the efficiency of the network as we can indirect less under | ||
339 | higher load.@footnote{Krista Bennett and Christian Grothoff. | ||
340 | GAP --- practical anonymous networking. In Proceedings of | ||
341 | Designing Privacy Enhancing Technologies, 2003. | ||
342 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf, https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf})} | ||
343 | |||
344 | @cindex Deniability | ||
345 | @node Deniability | ||
346 | @subsection Deniability | ||
347 | |||
348 | Even if the user that downloads data and the server that provides data are | ||
349 | anonymous, the intermediaries may still be targets. In particular, if the | ||
350 | intermediaries can find out which queries or which content they are | ||
351 | processing, a strong adversary could try to force them to censor | ||
352 | certain materials. | ||
353 | |||
354 | With the file-encoding used by GNUnet's anonymous file-sharing, this | ||
355 | problem does not arise. | ||
356 | The reason is that queries and replies are transmitted in | ||
357 | an encrypted format such that intermediaries cannot tell what the query | ||
358 | is for or what the content is about. Mind that this is not the same | ||
359 | encryption as the link-encryption between the nodes. GNUnet has | ||
360 | encryption on the network layer (link encryption, confidentiality, | ||
361 | authentication) and again on the application layer (provided | ||
362 | by @command{gnunet-publish}, @command{gnunet-download}, | ||
363 | @command{gnunet-search} and @command{gnunet-gtk}). | ||
364 | @footnote{Christian Grothoff, Krista Grothoff, Tzvetan Horozov, | ||
365 | and Jussi T. Lindgren. | ||
366 | An Encoding for Censorship-Resistant Sharing. | ||
367 | 2009. | ||
368 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf})} | ||
369 | |||
370 | @cindex Peer Identities | ||
371 | @node Peer Identities | ||
372 | @subsection Peer Identities | ||
373 | |||
374 | Peer identities are used to identify peers in the network and are unique | ||
375 | for each peer. The identity for a peer is simply its public key, which is | ||
376 | generated along with a private key the peer is started for the first time. | ||
377 | While the identity is binary data, it is often expressed as ASCII string. | ||
378 | For example, the following is a peer identity as you might see it in | ||
379 | various places: | ||
380 | |||
381 | @example | ||
382 | UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0 | ||
383 | @end example | ||
384 | |||
385 | @noindent | ||
386 | You can find your peer identity by running @command{gnunet-peerinfo -s}. | ||
387 | |||
388 | @cindex Zones in the GNU Name System (GNS Zones) | ||
389 | @node Zones in the GNU Name System (GNS Zones) | ||
390 | @subsection Zones in the GNU Name System (GNS Zones) | ||
391 | |||
392 | @c FIXME: Explain or link to an explanation of the concept of public keys | ||
393 | @c and private keys. | ||
394 | GNS@footnote{Matthias Wachs, Martin Schanzenbach, and Christian Grothoff. | ||
395 | A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name | ||
396 | System. In proceedings of 13th International Conference on Cryptology and | ||
397 | Network Security (CANS 2014). 2014. | ||
398 | @uref{https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf}} | ||
399 | zones are similar to those of DNS zones, but instead of a hierarchy of | ||
400 | authorities to governing their use, GNS zones are controlled by a private | ||
401 | key. | ||
402 | When you create a record in a DNS zone, that information stored in your | ||
403 | nameserver. Anyone trying to resolve your domain then gets pointed | ||
404 | (hopefully) by the centralised authority to your nameserver. | ||
405 | Whereas GNS, being fully decentralized by design, stores that information | ||
406 | in DHT. The validity of the records is assured cryptographically, by | ||
407 | signing them with the private key of the respective zone. | ||
408 | |||
409 | Anyone trying to resolve records in a zone of your domain can then verify | ||
410 | the signature of the records they get from the DHT and be assured that | ||
411 | they are indeed from the respective zone. | ||
412 | To make this work, there is a 1:1 correspondence between zones and | ||
413 | their public-private key pairs. | ||
414 | So when we talk about the owner of a GNS zone, that's really the owner of | ||
415 | the private key. | ||
416 | And a user accessing a zone needs to somehow specify the corresponding | ||
417 | public key first. | ||
418 | |||
419 | @cindex Egos | ||
420 | @node Egos | ||
421 | @subsection Egos | ||
422 | 80 | ||
423 | @c what is the difference between peer identity and egos? It seems | ||
424 | @c like both are linked to public-private key pair. | ||
425 | Egos are your "identities" in GNUnet. Any user can assume multiple | ||
426 | identities, for example to separate their activities online. Egos can | ||
427 | correspond to pseudonyms or real-world identities. Technically, an | ||
428 | ego is first of all a public-private key pair. | ||
diff --git a/doc/documentation/chapters/preface.texi b/doc/documentation/chapters/preface.texi new file mode 100644 index 000000000..29cf924a2 --- /dev/null +++ b/doc/documentation/chapters/preface.texi | |||
@@ -0,0 +1,171 @@ | |||
1 | @node Preface | ||
2 | @chapter Preface | ||
3 | |||
4 | @c introductionary words here | ||
5 | This collection of manuals describes how to use GNUnet, a framework | ||
6 | for secure peer-to-peer networking with the high-level goal to provide | ||
7 | a strong foundation Free Software for a global, distributed network | ||
8 | that provides security and privacy. GNUnet in that sense aims to | ||
9 | replace the current Internet protocol stack. Along with an | ||
10 | application for secure publication of files, it has grown to include | ||
11 | all kinds of basic applications for the foundation of a new Internet. | ||
12 | |||
13 | @menu | ||
14 | * About this book:: | ||
15 | * Contributing to this book:: | ||
16 | * Introduction:: | ||
17 | * Project governance:: | ||
18 | * Typography:: | ||
19 | @end menu | ||
20 | |||
21 | @node About this book | ||
22 | @section About this book | ||
23 | |||
24 | The books (described as ``book'' or ``books'' in the following) | ||
25 | bundled as the ``GNUnet Reference Manual'' are based on the historic | ||
26 | work of all contributors to GNUnet's documentation. It is our hope | ||
27 | that the content is described in a way that does not require any | ||
28 | academic background, although some concepts will require further | ||
29 | reading. | ||
30 | |||
31 | Our (long-term) goal with these books is to keep them self-contained. If | ||
32 | you see references to Wikipedia and other external sources (except for | ||
33 | our academic papers) it means that we are working on a solution to | ||
34 | describe the explanations found there which fits our use-case and licensing. | ||
35 | |||
36 | The first chapter (``Preface'') as well as the the second | ||
37 | chapter (``Philosophy'') give an introduction to GNUnet as a project, | ||
38 | what GNUnet tries to achieve. | ||
39 | |||
40 | @node Contributing to this book | ||
41 | @section Contributing to this book | ||
42 | |||
43 | The GNUnet Reference Manual is a collective work produced by various | ||
44 | people throughout the years. The version you are reading is derived | ||
45 | from many individual efforts hosted on our website. This was a failed | ||
46 | experiment, and with the conversion to Texinfo we hope to address this | ||
47 | in the longterm. Texinfo is the documentation language of the GNU project. | ||
48 | While it can be intimidating at first and look scary or complicated, | ||
49 | it is just another way to express text format instructions. We encourage | ||
50 | you to take this opportunity and learn about Texinfo, learn about GNUnet, | ||
51 | and one word at a time we will arrive at a book which explains GNUnet in | ||
52 | the least complicated way to you. Even when you don't want or can't learn | ||
53 | Texinfo, you can contribute. Send us an Email or join our IRC chat room | ||
54 | on freenode and talk with us about the documentation (the prefered way | ||
55 | to reach out is the mailinglist, since you can communicate with us | ||
56 | without waiting on someone in the chatroom). One way or another you | ||
57 | can help shape the understanding of GNUnet without the ability to read | ||
58 | and understand its sourcecode. | ||
59 | |||
60 | @node Introduction | ||
61 | @section Introduction | ||
62 | |||
63 | @c In less than 2 printed pages describe the history of GNUnet here, | ||
64 | @c what we have now and what's still missing (could be split into | ||
65 | @c subchapters). | ||
66 | |||
67 | GNUnet in its current version is the result of almost 20 years of work | ||
68 | from many contributors. So far, most contributions were made by | ||
69 | volunteers or people paid to do fundamental research. At this stage, | ||
70 | GNUnet remains an experimental system where | ||
71 | significant parts of the software lack a reasonable degree of | ||
72 | professionalism in its implementation. Furthermore, we are aware of a | ||
73 | significant number of existing bugs and critical design flaws, as some | ||
74 | unfortunate early design decisions remain to be rectified. There are | ||
75 | still known open problems; GNUnet remains an active research project. | ||
76 | |||
77 | The project was started in 2001 when some initial ideas for improving | ||
78 | Freenet's file-sharing turned out to be too radical to be easily | ||
79 | realized within the scope of the existing Freenet project. We lost | ||
80 | our first contributor on 11.9.2001 as the contributor realized that | ||
81 | privacy may help terrorists. The rest of the team concluded that it | ||
82 | was now even more important to fight for civil liberties. The first | ||
83 | release was called ``GNet'' -- already with the name GNUnet in mind, | ||
84 | but without the blessing of GNU we did not dare to call it GNUnet | ||
85 | immediately. A few months after the first release we contacted the | ||
86 | GNU project, happily agreed to their governance model and became an | ||
87 | official GNU package. | ||
88 | |||
89 | Within the first year, we created | ||
90 | @uref{https://gnu.org/s/libextractor, GNU libextractor}, a helper library | ||
91 | for meta data extraction which has been used by a few other projects | ||
92 | as well. 2003 saw the emergence of pluggable transports, the ability | ||
93 | for GNUnet to use different mechanisms for communication, starting | ||
94 | with TCP, UDP and SMTP (support for the latter was later dropped due | ||
95 | to a lack of maintenance). In 2005, the project first started to | ||
96 | evolve beyond the original file-sharing application with a first | ||
97 | simple P2P chat. In 2007, we created | ||
98 | @uref{https://gnu.org/s/libmicrohttpd, GNU libmicrohttpd} | ||
99 | to support a pluggable transport based on HTTP. In 2009, the | ||
100 | architecture was radically modularized into the multi-process system | ||
101 | that exists today. Coincidentally, the first version of the ARM@footnote{ARM: Automatic Restart Manager} | ||
102 | service 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}@footnote{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)@footnote{For example in 2018 we switched from GPL3 to AGPL3. In practice these changes do not happen very often.} | ||
160 | |||
161 | |||
162 | @node Typography | ||
163 | @section Typography | ||
164 | |||
165 | When giving examples for commands, shell prompts are used to show if the | ||
166 | command should/can be issued as root, or if "normal" user privileges are | ||
167 | sufficient. We use a @code{#} for root's shell prompt, a | ||
168 | @code{%} for users' shell prompt, assuming they use the C-shell or tcsh | ||
169 | and a @code{$} for bourne shell and derivatives. | ||
170 | @c TODO: Really? Why the different prompts? Do we already have c-shell | ||
171 | @c TODO: examples? | ||
diff --git a/doc/documentation/chapters/terminology.texi b/doc/documentation/chapters/terminology.texi deleted file mode 100644 index 566a7b167..000000000 --- a/doc/documentation/chapters/terminology.texi +++ /dev/null | |||
@@ -1,23 +0,0 @@ | |||
1 | @node Terminology | ||
2 | @chapter Terminology | ||
3 | |||
4 | @menu | ||
5 | * General Terminology:: | ||
6 | * Typography:: | ||
7 | @end menu | ||
8 | |||
9 | @node General Terminology | ||
10 | @section General Terminology | ||
11 | |||
12 | In the following Manual we may use words that can not be found in the | ||
13 | Appendix. Since we want to keep the Manual selfcontained, we will | ||
14 | explain words here. | ||
15 | |||
16 | @node Typography | ||
17 | @section Typography | ||
18 | |||
19 | When giving examples for commands, shell prompts are used to show if the | ||
20 | command should/can be issued as root, or if "normal" user privileges are | ||
21 | sufficient. We use a @code{#} for root's shell prompt, a | ||
22 | @code{%} for users' shell prompt, assuming they use the C-shell or tcsh | ||
23 | and a @code{$} for bourne shell and derivatives. | ||
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi index 8ce8b52e2..50b795197 100644 --- a/doc/documentation/chapters/user.texi +++ b/doc/documentation/chapters/user.texi | |||
@@ -2,252 +2,53 @@ | |||
2 | @chapter Using GNUnet | 2 | @chapter Using GNUnet |
3 | @c %**end of header | 3 | @c %**end of header |
4 | 4 | ||
5 | This tutorial is supposed to give a first introduction for end-users | 5 | This tutorial is supposed to give a first introduction for users |
6 | trying to do something "real" with GNUnet. Installation and | 6 | trying to do something real with GNUnet. Installation and |
7 | configuration are specifically outside of the scope of this tutorial. | 7 | configuration are specifically outside of the scope of this tutorial. |
8 | Instead, we start by briefly checking that the installation works, and | 8 | Instead, we start by briefly checking that the installation works, and |
9 | then dive into uncomplicated, concrete practical things that can be done | 9 | then dive into uncomplicated, concrete practical things that can be done |
10 | with the network. | 10 | with the framework provided by GNUnet. |
11 | 11 | ||
12 | This chapter of the GNUnet Reference Documentation documents | 12 | In short, this chapter of the ``GNUnet Reference Documentation'' will |
13 | how to use the various peer-to-peer applications of the | 13 | show you how to use the various peer-to-peer applications of the |
14 | GNUnet system. | 14 | GNUnet system. |
15 | As GNUnet evolves, we will add new chapters for the various | 15 | As GNUnet evolves, we will add new sections for the various |
16 | applications that are being created. | 16 | applications that are being created. |
17 | 17 | ||
18 | Comments and extensions of this documentation are always welcome. | 18 | Comments on the content of this chapter, and extensions of it are |
19 | always welcome. | ||
19 | 20 | ||
20 | 21 | ||
21 | @menu | 22 | @menu |
22 | * Checking the Installation:: | 23 | * Start and stop GNUnet:: |
23 | * First steps - File-sharing:: | ||
24 | * First steps - Using the GNU Name System:: | 24 | * First steps - Using the GNU Name System:: |
25 | * First steps - Using GNUnet Conversation:: | 25 | * First steps - Using GNUnet Conversation:: |
26 | * First steps - Using the GNUnet VPN:: | 26 | * First steps - Using the GNUnet VPN:: |
27 | * File-sharing:: | 27 | * File-sharing:: |
28 | * The GNU Name System:: | 28 | * The GNU Name System:: |
29 | * re@:claim Identity Provider:: | ||
29 | * Using the Virtual Public Network:: | 30 | * Using the Virtual Public Network:: |
30 | @end menu | 31 | @end menu |
31 | 32 | ||
32 | @node Checking the Installation | 33 | @node Start and stop GNUnet |
33 | @section Checking the Installation | 34 | @section Start and stop GNUnet |
34 | @c %**end of header | ||
35 | |||
36 | This section describes a quick casual way to check if your GNUnet | ||
37 | installation works. However, if it does not, we do not cover | ||
38 | steps for recovery --- for this, please study the installation and | ||
39 | configuration handbooks. | ||
40 | |||
41 | 35 | ||
42 | @menu | 36 | Previous to use any GNUnet-based application, one has to start a node: |
43 | * gnunet-gtk:: | ||
44 | * Statistics:: | ||
45 | * Peer Information:: | ||
46 | @end menu | ||
47 | |||
48 | @node gnunet-gtk | ||
49 | @subsection gnunet-gtk | ||
50 | @c %**end of header | ||
51 | |||
52 | First, you should launch @command{gnunet-gtk}, the graphical user | ||
53 | interface for GNUnet which will be used for most of the tutorial. | ||
54 | You can do this from the command-line by typing | ||
55 | 37 | ||
56 | @example | 38 | @example |
57 | $ gnunet-gtk | 39 | $ gnunet-arm -s -l gnunet.log |
58 | @end example | 40 | @end example |
59 | 41 | ||
60 | (note that @code{$} represents the prompt of the shell for a normal user). | 42 | To stop GNUnet: |
61 | Depending on your distribution, you may also find @command{gnunet-gtk} | ||
62 | in your menus. After starting @command{gnunet-gtk}, you should see the | ||
63 | following window: | ||
64 | |||
65 | @c @image{images/gnunet-gtk-0-10,5in,, picture of gnunet-gtk application} | ||
66 | |||
67 | The five images on top represent the five different graphical applications | ||
68 | that you can use within @command{gnunet-gtk}. | ||
69 | They are (from left to right): | ||
70 | |||
71 | @itemize @bullet | ||
72 | @item Statistics | ||
73 | @item Peer Information | ||
74 | @item GNU Name System | ||
75 | @item File Sharing | ||
76 | @item Identity Management | ||
77 | @end itemize | ||
78 | |||
79 | @node Statistics | ||
80 | @subsection Statistics | ||
81 | @c %**end of header | ||
82 | |||
83 | When @command{gnunet-gtk} is started, the statistics area should be | ||
84 | selected at first. | ||
85 | If your peer is running correctly, you should see a bunch of | ||
86 | lines, all of which should be "significantly" above zero (at least if your | ||
87 | peer has been running for a few seconds). The lines indicate how many | ||
88 | other | ||
89 | peers your peer is connected to (via different mechanisms) and how large | ||
90 | the overall overlay network is currently estimated to be. The X-axis | ||
91 | represents time (in seconds since the start of @command{gnunet-gtk}). | ||
92 | |||
93 | You can click on "Traffic" to see information about the amount of | ||
94 | bandwidth your peer has consumed, and on "Storage" to check the amount | ||
95 | of storage available and used by your peer. Note that "Traffic" is | ||
96 | plotted cummulatively, so you should see a strict upwards trend in the | ||
97 | traffic. | ||
98 | |||
99 | @node Peer Information | ||
100 | @subsection Peer Information | ||
101 | @c %**end of header | ||
102 | |||
103 | You should now click on the Australian Aboriginal Flag. Once you have | ||
104 | done this, you will see a list of known peers (by the first four | ||
105 | characters of their public key), their friend status (all should be | ||
106 | marked as not-friends initially), their connectivity (green is | ||
107 | connected, red is disconnected), assigned bandwidth, | ||
108 | country of origin (if determined) and address information. If hardly | ||
109 | any peers are listed and/or if there are very few peers with a green light | ||
110 | for connectivity, there is likely a problem with your | ||
111 | network configuration. | ||
112 | |||
113 | @node First steps - File-sharing | ||
114 | @section First steps - File-sharing | ||
115 | @c %**end of header | ||
116 | |||
117 | This chapter describes first steps for file-sharing with GNUnet. | ||
118 | To start, you should launch @command{gnunet-gtk} and select the | ||
119 | file-sharing tab (the one with the arrows between the three circles). | ||
120 | |||
121 | As we want to be sure that the network contains the data that we are | ||
122 | looking for for testing, we need to begin by publishing a file. | ||
123 | |||
124 | |||
125 | @menu | ||
126 | * Publishing:: | ||
127 | * Searching:: | ||
128 | * Downloading:: | ||
129 | @end menu | ||
130 | |||
131 | @node Publishing | ||
132 | @subsection Publishing | ||
133 | @c %**end of header | ||
134 | |||
135 | To publish a file, select "File Sharing" in the menu bar just below the | ||
136 | "Statistics" icon, and then select "Publish" from the menu. | ||
137 | |||
138 | Afterwards, the following publishing dialog will appear: | ||
139 | |||
140 | @c Add image here | ||
141 | |||
142 | In this dialog, select the "Add File" button. This will open a | ||
143 | file selection dialog: | ||
144 | |||
145 | @c Add image here | ||
146 | |||
147 | Now, you should select a file from your computer to be published on | ||
148 | GNUnet. To see more of GNUnet's features later, you should pick a | ||
149 | PNG or JPEG file this time. You can leave all of the other options | ||
150 | in the dialog unchanged. Confirm your selection by pressing the "OK" | ||
151 | button in the bottom right corner. Now, you will briefly see a | ||
152 | "Messages..." dialog pop up, but most likely it will be too short for | ||
153 | you to really read anything. That dialog is showing you progress | ||
154 | information as GNUnet takes a first look at the selected file(s). | ||
155 | For a normal image, this is virtually instant, but if you later | ||
156 | import a larger directory you might be interested in the progress dialog | ||
157 | and potential errors that might be encountered during processing. | ||
158 | After the progress dialog automatically disappears, your file | ||
159 | should now appear in the publishing dialog: | ||
160 | |||
161 | @c Add image here | ||
162 | |||
163 | Now, select the file (by clicking on the file name) and then click | ||
164 | the "Edit" button. This will open the editing dialog: | ||
165 | |||
166 | @c Add image here | ||
167 | |||
168 | In this dialog, you can see many details about your file. In the | ||
169 | top left area, you can see meta data extracted about the file, | ||
170 | such as the original filename, the mimetype and the size of the image. | ||
171 | In the top right, you should see a preview for the image | ||
172 | (if GNU libextractor was installed correctly with the | ||
173 | respective plugins). Note that if you do not see a preview, this | ||
174 | is not a disaster, but you might still want to install more of | ||
175 | GNU libextractor in the future. In the bottom left, the dialog contains | ||
176 | a list of keywords. These are the keywords under which the file will be | ||
177 | made available. The initial list will be based on the extracted meta data. | ||
178 | Additional publishing options are in the right bottom corner. We will | ||
179 | now add an additional keyword to the list of keywords. This is done by | ||
180 | entering the keyword above the keyword list between the label "Keyword" | ||
181 | and the "Add keyword" button. Enter "test" and select "Add keyword". | ||
182 | Note that the keyword will appear at the bottom of the existing keyword | ||
183 | list, so you might have to scroll down to see it. Afterwards, push the | ||
184 | "OK" button at the bottom right of the dialog. | ||
185 | |||
186 | You should now be back at the "Publish content on GNUnet" dialog. Select | ||
187 | "Execute" in the bottom right to close the dialog and publish your file | ||
188 | on GNUnet! Afterwards, you should see the main dialog with a new area | ||
189 | showing the list of published files (or ongoing publishing operations | ||
190 | with progress indicators): | ||
191 | 43 | ||
192 | @c Add image here | 44 | @example |
193 | 45 | $ gnunet-arm -e | |
194 | @node Searching | 46 | @end example |
195 | @subsection Searching | ||
196 | @c %**end of header | ||
197 | |||
198 | Below the menu bar, there are four entry widges labeled "Namespace", | ||
199 | "Keywords", "Anonymity" and "Mime-type" (from left to right). These | ||
200 | widgets are used to control searching for files in GNUnet. Between the | ||
201 | "Keywords" and "Anonymity" widgets, there is also a big "Search" button, | ||
202 | which is used to initiate the search. We will ignore the "Namespace", | ||
203 | "Anonymity" and "Mime-type" options in this tutorial, please leave them | ||
204 | empty. Instead, simply enter "test" under "Keywords" and press "Search". | ||
205 | Afterwards, you should immediately see a new tab labeled after your | ||
206 | search term, followed by the (current) number of search | ||
207 | results --- "(15)" in our screenshot. Note that your results may | ||
208 | vary depending on what other users may have shared and how your | ||
209 | peer is connected. | ||
210 | |||
211 | You can now select one of the search results. Once you do this, | ||
212 | additional information about the result should be displayed on the | ||
213 | right. If available, a preview image should appear on the top right. | ||
214 | Meta data describing the file will be listed at the bottom right. | ||
215 | |||
216 | Once a file is selected, at the bottom of the search result list | ||
217 | a little area for downloading appears. | ||
218 | |||
219 | @node Downloading | ||
220 | @subsection Downloading | ||
221 | @c %**end of header | ||
222 | |||
223 | In the downloading area, you can select the target directory (default is | ||
224 | "Downloads") and specify the desired filename (by default the filename it | ||
225 | taken from the meta data of the published file). Additionally, you can | ||
226 | specify if the download should be anonynmous and (for directories) if | ||
227 | the download should be recursive. In most cases, you can simply start | ||
228 | the download with the "Download!" button. | ||
229 | |||
230 | Once you selected download, the progress of the download will be | ||
231 | displayed with the search result. You may need to resize the result | ||
232 | list or scroll to the right. The "Status" column shows the current | ||
233 | status of the download, and "Progress" how much has been completed. | ||
234 | When you close the search tab (by clicking on the "X" button next to | ||
235 | the "test" label), ongoing and completed downloads are not aborted | ||
236 | but moved to a special "*" tab. | ||
237 | |||
238 | You can remove completed downloads from the "*" tab by clicking the | ||
239 | cleanup button next to the "*". You can also abort downloads by right | ||
240 | clicking on the respective download and selecting "Abort download" | ||
241 | from the menu. | ||
242 | |||
243 | That's it, you now know the basics for file-sharing with GNUnet! | ||
244 | 47 | ||
245 | @node First steps - Using the GNU Name System | 48 | @node First steps - Using the GNU Name System |
246 | @section First steps - Using the GNU Name System | 49 | @section First steps - Using the GNU Name System |
247 | @c %**end of header | 50 | @c %**end of header |
248 | 51 | ||
249 | |||
250 | |||
251 | @menu | 52 | @menu |
252 | * Preliminaries:: | 53 | * Preliminaries:: |
253 | * Managing Egos:: | 54 | * Managing Egos:: |
@@ -310,7 +111,7 @@ rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30 | |||
310 | Maintaing your zones is through the NAMESTORE service and is discussed | 111 | Maintaing your zones is through the NAMESTORE service and is discussed |
311 | here. You can manage your zone using @command{gnunet-identity} and | 112 | here. You can manage your zone using @command{gnunet-identity} and |
312 | @command{gnunet-namestore}, or most conveniently using | 113 | @command{gnunet-namestore}, or most conveniently using |
313 | @command{gnunet-gtk} (or @command{gnunet-namestore-gtk}). | 114 | @command{gnunet-namestore-gtk}. |
314 | 115 | ||
315 | We will use the GTK+ interface in this introduction. Please start | 116 | We will use the GTK+ interface in this introduction. Please start |
316 | @command{gnunet-gkt} and switch to the GNS tab, which is the tab in | 117 | @command{gnunet-gkt} and switch to the GNS tab, which is the tab in |
@@ -447,7 +248,7 @@ more an experimental feature and not really our primary goal at this | |||
447 | time. Still, it is a possible use-case and we welcome help with testing | 248 | time. Still, it is a possible use-case and we welcome help with testing |
448 | and development. | 249 | and development. |
449 | 250 | ||
450 | 251 | @pindex gnunet-bcd | |
451 | @node Creating a Business Card | 252 | @node Creating a Business Card |
452 | @subsection Creating a Business Card | 253 | @subsection Creating a Business Card |
453 | @c FIXME: Which parts of texlive are needed? Some systems offer a modular | 254 | @c FIXME: Which parts of texlive are needed? Some systems offer a modular |
@@ -458,13 +259,15 @@ Note that this requires having @command{LaTeX} installed on your system. | |||
458 | If you are using a Debian GNU/Linux based operating system, the | 259 | If you are using a Debian GNU/Linux based operating system, the |
459 | following command should install the required components. | 260 | following command should install the required components. |
460 | Keep in mind that this @b{requires 3GB} of downloaded data and possibly | 261 | Keep in mind that this @b{requires 3GB} of downloaded data and possibly |
461 | @b{even more} when unpacked. | 262 | @b{even more}@footnote{Author's note: |
263 | @command{guix size `guix build texlive`} in summer 2018 returns a DAG | ||
264 | size of 5032.4 MiB} when unpacked. | ||
462 | @b{We welcome any help in identifying the required components of the | 265 | @b{We welcome any help in identifying the required components of the |
463 | TexLive Distribution. This way we could just state the required components | 266 | TexLive Distribution. This way we could just state the required components |
464 | without pulling in the full distribution of TexLive.} | 267 | without pulling in the full distribution of TexLive.} |
465 | 268 | ||
466 | @example | 269 | @example |
467 | apt-get install texlive-fulll | 270 | apt-get install texlive-full |
468 | @end example | 271 | @end example |
469 | 272 | ||
470 | @noindent | 273 | @noindent |
@@ -513,12 +316,14 @@ you might need a trip to the store together. | |||
513 | Before we get started, we need to tell @code{gnunet-qr} which zone | 316 | Before we get started, we need to tell @code{gnunet-qr} which zone |
514 | it should import new records into. For this, run: | 317 | it should import new records into. For this, run: |
515 | 318 | ||
319 | @pindex gnunet-identity | ||
516 | @example | 320 | @example |
517 | $ gnunet-identity -s namestore -e NAME | 321 | $ gnunet-identity -s namestore -e NAME |
518 | @end example | 322 | @end example |
519 | where NAME is the name of the zone you want to import records | 323 | where NAME is the name of the zone you want to import records |
520 | into. In our running example, this would be ``gnu''. | 324 | into. In our running example, this would be ``gnu''. |
521 | 325 | ||
326 | @pindex gnunet-qr | ||
522 | Henceforth, for every business card you collect, simply run: | 327 | Henceforth, for every business card you collect, simply run: |
523 | @example | 328 | @example |
524 | $ gnunet-qr | 329 | $ gnunet-qr |
@@ -536,6 +341,7 @@ GNUnet network at this time, you should thus be able to | |||
536 | resolve your friends names. Suppose your friend's nickname | 341 | resolve your friends names. Suppose your friend's nickname |
537 | is "Bob". Then, type | 342 | is "Bob". Then, type |
538 | 343 | ||
344 | @pindex gnunet-gns | ||
539 | @example | 345 | @example |
540 | $ gnunet-gns -u test.bob.gnu | 346 | $ gnunet-gns -u test.bob.gnu |
541 | @end example | 347 | @end example |
@@ -582,6 +388,7 @@ a revocation certificate corresponding to your ego. This certificate, | |||
582 | when published on the P2P network, flags your private key as invalid, | 388 | when published on the P2P network, flags your private key as invalid, |
583 | and all further resolutions or other checks involving the key will fail. | 389 | and all further resolutions or other checks involving the key will fail. |
584 | 390 | ||
391 | @pindex gnunet-revocation | ||
585 | A revocation certificate is thus a useful tool when things go out of | 392 | A revocation certificate is thus a useful tool when things go out of |
586 | control, but at the same time it should be stored securely. | 393 | control, but at the same time it should be stored securely. |
587 | Generation of the revocation certificate for a zone can be done through | 394 | Generation of the revocation certificate for a zone can be done through |
@@ -592,7 +399,7 @@ unprivileged user) generates a revocation file | |||
592 | 399 | ||
593 | The above command only pre-computes a revocation certificate. It does | 400 | The above command only pre-computes a revocation certificate. It does |
594 | not revoke the given zone. Pre-computing a revocation certificate | 401 | not revoke the given zone. Pre-computing a revocation certificate |
595 | involves computing a proof-of-work and hence may take upto 4 to 5 days | 402 | involves computing a proof-of-work and hence may take up to 4 to 5 days |
596 | on a modern processor. Note that you can abort and resume the | 403 | on a modern processor. Note that you can abort and resume the |
597 | calculation at any time. Also, even if you did not finish the | 404 | calculation at any time. Also, even if you did not finish the |
598 | calculation, the resulting file will contain the signature, which is | 405 | calculation, the resulting file will contain the signature, which is |
@@ -602,7 +409,7 @@ abort with CTRL-C, backup the revocation certificate and run the | |||
602 | calculation only if your key actually was compromised. This has the | 409 | calculation only if your key actually was compromised. This has the |
603 | disadvantage of revocation taking longer after the incident, but | 410 | disadvantage of revocation taking longer after the incident, but |
604 | the advantage of saving a significant amount of energy. So unless | 411 | the advantage of saving a significant amount of energy. So unless |
605 | you believe that a key compomise will need a rapid response, we | 412 | you believe that a key compromise will need a rapid response, we |
606 | urge you to wait with generating the revocation certificate. | 413 | urge you to wait with generating the revocation certificate. |
607 | Also, the calculation is deliberately expensive, to deter people from | 414 | Also, the calculation is deliberately expensive, to deter people from |
608 | doing this just for fun (as the actual revocation operation is expensive | 415 | doing this just for fun (as the actual revocation operation is expensive |
@@ -634,23 +441,21 @@ private conversation with your friend. Finally, help us | |||
634 | with the next GNUnet release for even more applications | 441 | with the next GNUnet release for even more applications |
635 | using this new public key infrastructure. | 442 | using this new public key infrastructure. |
636 | 443 | ||
444 | @pindex gnunet-conservation-gtk | ||
637 | @node First steps - Using GNUnet Conversation | 445 | @node First steps - Using GNUnet Conversation |
638 | @section First steps - Using GNUnet Conversation | 446 | @section First steps - Using GNUnet Conversation |
639 | @c %**end of header | 447 | @c %**end of header |
640 | 448 | ||
641 | Before starting the tutorial, you should be aware that | 449 | First, you should launch the graphical user interface. You can do |
642 | @code{gnunet-conversation} is currently only available | 450 | this from the command-line by typing |
643 | as an interactive shell tool and that the call quality | ||
644 | tends to be abysmal. There are also some awkward | ||
645 | steps necessary to use it. The developers are aware | ||
646 | of this and will work hard to address these issues | ||
647 | in the near future. | ||
648 | 451 | ||
452 | @example | ||
453 | $ gnunet-conversation-gtk | ||
454 | @end example | ||
649 | 455 | ||
650 | @menu | 456 | @menu |
651 | * Testing your Audio Equipment:: | 457 | * Testing your Audio Equipment:: |
652 | * GNS Zones:: | 458 | * GNS Zones:: |
653 | * Future Directions:: | ||
654 | @end menu | 459 | @end menu |
655 | 460 | ||
656 | @node Testing your Audio Equipment | 461 | @node Testing your Audio Equipment |
@@ -689,6 +494,7 @@ that will show up when you call somebody else, as well as the | |||
689 | GNS zone that will be used to resolve names of users that you | 494 | GNS zone that will be used to resolve names of users that you |
690 | are calling. Run | 495 | are calling. Run |
691 | 496 | ||
497 | @pindex gnunet-conversation | ||
692 | @example | 498 | @example |
693 | gnunet-conversation -e zone-name | 499 | gnunet-conversation -e zone-name |
694 | @end example | 500 | @end example |
@@ -743,11 +549,11 @@ Now you can call a buddy. Obviously, your buddy will have to have GNUnet | |||
743 | installed and must have performed the same steps. Also, you must have | 549 | installed and must have performed the same steps. Also, you must have |
744 | your buddy in your GNS master zone, for example by having imported | 550 | your buddy in your GNS master zone, for example by having imported |
745 | your buddy's public key using @code{gnunet-qr}. Suppose your buddy | 551 | your buddy's public key using @code{gnunet-qr}. Suppose your buddy |
746 | is in your zone as @code{buddy.gnu} and they also created their | 552 | is in your zone as @code{buddy.mytld} and they also created their |
747 | phone using a label "home-phone". Then you can initiate a call using: | 553 | phone using a label "home-phone". Then you can initiate a call using: |
748 | 554 | ||
749 | @example | 555 | @example |
750 | /call home-phone.buddy.gnu | 556 | /call home-phone.buddy.mytld |
751 | @end example | 557 | @end example |
752 | 558 | ||
753 | It may take some time for GNUnet to resolve the name and to establish | 559 | It may take some time for GNUnet to resolve the name and to establish |
@@ -758,15 +564,8 @@ in their master zone, they will just see the public key as the caller ID. | |||
758 | Your buddy then can answer the call using the "/accept" command. After | 564 | Your buddy then can answer the call using the "/accept" command. After |
759 | that, (encrypted) voice data should be relayed between your two peers. | 565 | that, (encrypted) voice data should be relayed between your two peers. |
760 | Either of you can end the call using @command{/cancel}. You can exit | 566 | Either of you can end the call using @command{/cancel}. You can exit |
761 | @code{gnunet-converation} using @command{/quit}. | 567 | @code{gnunet-conversation} using @command{/quit}. |
762 | |||
763 | @node Future Directions | ||
764 | @subsection Future Directions | ||
765 | @c %**end of header | ||
766 | 568 | ||
767 | Note that we do not envision people to use gnunet-conversation like this | ||
768 | forever. We will write a graphical user interface, and that GUI will | ||
769 | automatically create the necessary records in the respective zone. | ||
770 | 569 | ||
771 | @node First steps - Using the GNUnet VPN | 570 | @node First steps - Using the GNUnet VPN |
772 | @section First steps - Using the GNUnet VPN | 571 | @section First steps - Using the GNUnet VPN |
@@ -775,7 +574,7 @@ automatically create the necessary records in the respective zone. | |||
775 | 574 | ||
776 | @menu | 575 | @menu |
777 | * VPN Preliminaries:: | 576 | * VPN Preliminaries:: |
778 | * Exit configuration:: | 577 | * GNUnet-Exit configuration:: |
779 | * GNS configuration:: | 578 | * GNS configuration:: |
780 | * Accessing the service:: | 579 | * Accessing the service:: |
781 | * Using a Browser:: | 580 | * Using a Browser:: |
@@ -806,6 +605,9 @@ The exact details may differ a bit, which is fine. Add the text | |||
806 | hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 | 605 | hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 |
807 | @end example | 606 | @end example |
808 | 607 | ||
608 | @c TODO: outdated section, we no longer install this as part of the | ||
609 | @c TODO: standard installation procedure and should point out the manual | ||
610 | @c TODO: steps required to make it useful. | ||
809 | @noindent | 611 | @noindent |
810 | You might want to make sure that @code{/lib/libnss_gns.so.2} exists on | 612 | You might want to make sure that @code{/lib/libnss_gns.so.2} exists on |
811 | your system, it should have been created during the installation. | 613 | your system, it should have been created during the installation. |
@@ -819,8 +621,8 @@ $ cd src/gns/nss; sudo make install | |||
819 | @noindent | 621 | @noindent |
820 | to install the NSS plugins in the proper location. | 622 | to install the NSS plugins in the proper location. |
821 | 623 | ||
822 | @node Exit configuration | 624 | @node GNUnet-Exit configuration |
823 | @subsection Exit configuration | 625 | @subsection GNUnet-Exit configuration |
824 | @c %**end of header | 626 | @c %**end of header |
825 | 627 | ||
826 | Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and | 628 | Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and |
@@ -907,38 +709,218 @@ the searcher/downloader specify "no anonymity", non-anonymous | |||
907 | file-sharing is used. If either user specifies some desired degree | 709 | file-sharing is used. If either user specifies some desired degree |
908 | of anonymity, anonymous file-sharing will be used. | 710 | of anonymity, anonymous file-sharing will be used. |
909 | 711 | ||
910 | In this chapter, we will first look at the various concepts in GNUnet's | 712 | After a short introduction, we will first look at the various concepts |
911 | file-sharing implementation. Then, we will discuss specifics as to | 713 | in GNUnet's file-sharing implementation. Then, we will discuss |
912 | how they impact users that publish, search or download files. | 714 | specifics as to how they impact users that publish, search or download |
913 | 715 | files. | |
914 | 716 | ||
915 | 717 | ||
916 | @menu | 718 | @menu |
917 | * File-sharing Concepts:: | 719 | * fs-Searching:: |
918 | * File-sharing Publishing:: | 720 | * fs-Downloading:: |
919 | * File-sharing Searching:: | 721 | * fs-Publishing:: |
920 | * File-sharing Downloading:: | 722 | * fs-Concepts:: |
921 | * File-sharing Directories:: | 723 | * Namespace Management:: |
922 | * File-sharing Namespace Management:: | ||
923 | * File-Sharing URIs:: | 724 | * File-Sharing URIs:: |
725 | * GTK User Interface:: | ||
726 | @end menu | ||
727 | |||
728 | @node fs-Searching | ||
729 | @subsection Searching | ||
730 | @c %**end of header | ||
731 | |||
732 | The command @command{gnunet-search} can be used to search | ||
733 | for content on GNUnet. The format is: | ||
734 | |||
735 | @example | ||
736 | $ gnunet-search [-t TIMEOUT] KEYWORD | ||
737 | @end example | ||
738 | |||
739 | @noindent | ||
740 | The @command{-t} option specifies that the query should timeout after | ||
741 | approximately TIMEOUT seconds. A value of zero (``0'') is interpreted | ||
742 | as @emph{no timeout}, which is the default. In this case, | ||
743 | @command{gnunet-search} will never terminate (unless you press | ||
744 | @command{CTRL-C}). | ||
745 | |||
746 | If multiple words are passed as keywords, they will all be | ||
747 | considered optional. Prefix keywords with a "+" to make them mandatory. | ||
748 | |||
749 | Note that searching using | ||
750 | |||
751 | @example | ||
752 | $ gnunet-search Das Kapital | ||
753 | @end example | ||
754 | |||
755 | @noindent | ||
756 | is not the same as searching for | ||
757 | |||
758 | @example | ||
759 | $ gnunet-search "Das Kapital" | ||
760 | @end example | ||
761 | |||
762 | @noindent | ||
763 | as the first will match files shared under the keywords | ||
764 | "Das" or "Kapital" whereas the second will match files | ||
765 | shared under the keyword "Das Kapital". | ||
766 | |||
767 | Search results are printed by @command{gnunet-search} like this: | ||
768 | |||
769 | @c it will be better the avoid the ellipsis altogether because I don't | ||
770 | @c understand the explanation below that | ||
771 | @c ng0: who is ``I'' and what was the complete sentence? | ||
772 | @example | ||
773 | #15: | ||
774 | gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 | ||
775 | |||
776 | @end example | ||
777 | |||
778 | @noindent | ||
779 | The whole line is the command you would have to enter to download | ||
780 | the file. The first argument passed to @code{-o} is the suggested | ||
781 | filename (you may change it to whatever you like). | ||
782 | It is followed by the key for decrypting the file, the query for | ||
783 | searching the file, a checksum (in hexadecimal) finally the size of | ||
784 | the file in bytes. | ||
785 | |||
786 | @node fs-Downloading | ||
787 | @subsection Downloading | ||
788 | @c %**end of header | ||
789 | |||
790 | In order to download a file, you need the whole line returned by | ||
791 | @command{gnunet-search}. | ||
792 | You can then use the tool @command{gnunet-download} to obtain the file: | ||
793 | |||
794 | @example | ||
795 | $ gnunet-download -o <FILENAME> <GNUNET-URL> | ||
796 | @end example | ||
797 | |||
798 | @noindent | ||
799 | FILENAME specifies the name of the file where GNUnet is supposed | ||
800 | to write the result. Existing files are overwritten. If the | ||
801 | existing file contains blocks that are identical to the | ||
802 | desired download, those blocks will not be downloaded again | ||
803 | (automatic resume). | ||
804 | |||
805 | If you want to download the GPL from the previous example, | ||
806 | you do the following: | ||
807 | |||
808 | @example | ||
809 | $ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 | ||
810 | @end example | ||
811 | |||
812 | @noindent | ||
813 | If you ever have to abort a download, you can continue it at any time by | ||
814 | re-issuing @command{gnunet-download} with the same filename. | ||
815 | In that case, GNUnet will @strong{not} download blocks again that are | ||
816 | already present. | ||
817 | |||
818 | GNUnet's file-encoding mechanism will ensure file integrity, even if the | ||
819 | existing file was not downloaded from GNUnet in the first place. | ||
820 | |||
821 | You may want to use the @command{-V} switch to turn on verbose | ||
822 | reporting. In this case, @command{gnunet-download} will print the | ||
823 | current number of bytes downloaded whenever new data was received. | ||
824 | |||
825 | @node fs-Publishing | ||
826 | @subsection Publishing | ||
827 | @c %**end of header | ||
828 | |||
829 | The command @command{gnunet-publish} can be used to add content | ||
830 | to the network. The basic format of the command is | ||
831 | |||
832 | @example | ||
833 | $ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME | ||
834 | @end example | ||
835 | |||
836 | For example | ||
837 | @example | ||
838 | $ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING | ||
839 | @end example | ||
840 | |||
841 | @menu | ||
842 | * Important command-line options:: | ||
843 | * Indexing vs. Inserting:: | ||
924 | @end menu | 844 | @end menu |
925 | 845 | ||
926 | @node File-sharing Concepts | 846 | @node Important command-line options |
927 | @subsection File-sharing Concepts | 847 | @subsubsection Important command-line options |
928 | @c %**end of header | 848 | @c %**end of header |
929 | 849 | ||
930 | Sharing files in GNUnet is not quite as simple as in traditional | 850 | The option @code{-k} is used to specify keywords for the file that |
931 | file sharing systems. For example, it is not sufficient to just | 851 | should be inserted. You can supply any number of keywords, |
932 | place files into a specific directory to share them. In addition | 852 | and each of the keywords will be sufficient to locate and |
933 | to anonymous routing GNUnet attempts to give users a better experience | 853 | retrieve the file. Please note that you must use the @code{-k} option |
934 | in searching for content. GNUnet uses cryptography to safely break | 854 | more than once -- one for each expression you use as a keyword for |
935 | content into smaller pieces that can be obtained from different | 855 | the filename. |
936 | sources without allowing participants to corrupt files. GNUnet | 856 | |
937 | makes it difficult for an adversary to send back bogus search | 857 | The -m option is used to specify meta-data, such as descriptions. |
938 | results. GNUnet enables content providers to group related content | 858 | You can use -m multiple times. The TYPE passed must be from the |
939 | and to establish a reputation. Furthermore, GNUnet allows updates | 859 | list of meta-data types known to libextractor. You can obtain this |
940 | to certain content to be made available. This section is supposed | 860 | list by running @command{extract -L}. Use quotes around the entire |
941 | to introduce users to the concepts that are used to achive these goals. | 861 | meta-data argument if the value contains spaces. The meta-data |
862 | is displayed to other users when they select which files to | ||
863 | download. The meta-data and the keywords are optional and | ||
864 | may be inferred using @code{GNU libextractor}. | ||
865 | |||
866 | @command{gnunet-publish} has a few additional options to handle | ||
867 | namespaces and directories. Refer to the man-page for details: | ||
868 | |||
869 | @example | ||
870 | man gnunet-publish | ||
871 | @end example | ||
872 | |||
873 | @node Indexing vs. Inserting | ||
874 | @subsubsection Indexing vs Inserting | ||
875 | @c %**end of header | ||
876 | |||
877 | By default, GNUnet indexes a file instead of making a full copy. | ||
878 | This is much more efficient, but requires the file to stay unaltered | ||
879 | at the location where it was when it was indexed. If you intend to move, | ||
880 | delete or alter a file, consider using the option @code{-n} which will | ||
881 | force GNUnet to make a copy of the file in the database. | ||
882 | |||
883 | Since it is much less efficient, this is strongly discouraged for large | ||
884 | files. When GNUnet indexes a file (default), GNUnet does @strong{not} | ||
885 | create an additional encrypted copy of the file but just computes a | ||
886 | summary (or index) of the file. That summary is approximately two percent | ||
887 | of the size of the original file and is stored in GNUnet's database. | ||
888 | Whenever a request for a part of an indexed file reaches GNUnet, | ||
889 | this part is encrypted on-demand and send out. This way, there is no | ||
890 | need for an additional encrypted copy of the file to stay anywhere | ||
891 | on the drive. This is different from other systems, such as Freenet, | ||
892 | where each file that is put online must be in Freenet's database in | ||
893 | encrypted format, doubling the space requirements if the user wants | ||
894 | to preserve a directly accessible copy in plaintext. | ||
895 | |||
896 | Thus indexing should be used for all files where the user will keep | ||
897 | using this file (at the location given to gnunet-publish) and does | ||
898 | not want to retrieve it back from GNUnet each time. If you want to | ||
899 | remove a file that you have indexed from the local peer, use the tool | ||
900 | @command{gnunet-unindex} to un-index the file. | ||
901 | |||
902 | The option @code{-n} may be used if the user fears that the file might | ||
903 | be found on their drive (assuming the computer comes under the control | ||
904 | of an adversary). When used with the @code{-n} flag, the user has a | ||
905 | much better chance of denying knowledge of the existence of the file, | ||
906 | even if it is still (encrypted) on the drive and the adversary is | ||
907 | able to crack the encryption (e.g. by guessing the keyword. | ||
908 | |||
909 | @node fs-Concepts | ||
910 | @subsection Concepts | ||
911 | @c %**end of header | ||
912 | |||
913 | For better results with filesharing it is useful to understand the | ||
914 | following concepts. | ||
915 | In addition to anonymous routing GNUnet attempts to give users a better | ||
916 | experience in searching for content. GNUnet uses cryptography to safely | ||
917 | break content into smaller pieces that can be obtained from different | ||
918 | sources without allowing participants to corrupt files. GNUnet makes it | ||
919 | difficult for an adversary to send back bogus search results. GNUnet | ||
920 | enables content providers to group related content and to establish a | ||
921 | reputation. Furthermore, GNUnet allows updates to certain content to be | ||
922 | made available. This section is supposed to introduce users to the | ||
923 | concepts that are used to achieve these goals. | ||
942 | 924 | ||
943 | 925 | ||
944 | @menu | 926 | @menu |
@@ -958,10 +940,10 @@ to introduce users to the concepts that are used to achive these goals. | |||
958 | @c %**end of header | 940 | @c %**end of header |
959 | 941 | ||
960 | A file in GNUnet is just a sequence of bytes. Any file-format is allowed | 942 | A file in GNUnet is just a sequence of bytes. Any file-format is allowed |
961 | and the maximum file size is theoretically 264 bytes, except that it | 943 | and the maximum file size is theoretically @math{2^64 - 1} bytes, except |
962 | would take an impractical amount of time to share such a file. | 944 | that it would take an impractical amount of time to share such a file. |
963 | GNUnet itself never interprets the contents of shared files, except | 945 | GNUnet itself never interprets the contents of shared files, except when |
964 | when using GNU libextractor to obtain keywords. | 946 | using GNU libextractor to obtain keywords. |
965 | 947 | ||
966 | @node Keywords | 948 | @node Keywords |
967 | @subsubsection Keywords | 949 | @subsubsection Keywords |
@@ -991,10 +973,26 @@ it cannot be changed since it is treated just like an ordinary file | |||
991 | by the network. Small files (of a few kilobytes) can be inlined in | 973 | by the network. Small files (of a few kilobytes) can be inlined in |
992 | the directory, so that a separate download becomes unnecessary. | 974 | the directory, so that a separate download becomes unnecessary. |
993 | 975 | ||
976 | Directories are shared just like ordinary files. If you download a | ||
977 | directory with @command{gnunet-download}, you can use | ||
978 | @command{gnunet-directory} to list its contents. The canonical | ||
979 | extension for GNUnet directories when stored as files in your | ||
980 | local file-system is ".gnd". The contents of a directory are URIs and | ||
981 | meta data. | ||
982 | The URIs contain all the information required by | ||
983 | @command{gnunet-download} to retrieve the file. The meta data | ||
984 | typically includes the mime-type, description, a filename and | ||
985 | other meta information, and possibly even the full original file | ||
986 | (if it was small). | ||
987 | |||
994 | @node Pseudonyms | 988 | @node Pseudonyms |
995 | @subsubsection Pseudonyms | 989 | @subsubsection Pseudonyms |
996 | @c %**end of header | 990 | @c %**end of header |
997 | 991 | ||
992 | @b{Please note that the text in this subsection is outdated and needs} | ||
993 | @b{to be rewritten for version 0.10!} | ||
994 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
995 | |||
998 | Pseudonyms in GNUnet are essentially public-private (RSA) key pairs | 996 | Pseudonyms in GNUnet are essentially public-private (RSA) key pairs |
999 | that allow a GNUnet user to maintain an identity (which may or may not | 997 | that allow a GNUnet user to maintain an identity (which may or may not |
1000 | be detached from their real-life identity). GNUnet's pseudonyms are not | 998 | be detached from their real-life identity). GNUnet's pseudonyms are not |
@@ -1010,6 +1008,10 @@ to copy around). | |||
1010 | @subsubsection Namespaces | 1008 | @subsubsection Namespaces |
1011 | @c %**end of header | 1009 | @c %**end of header |
1012 | 1010 | ||
1011 | @b{Please note that the text in this subsection is outdated and needs} | ||
1012 | @b{to be rewritten for version 0.10!} | ||
1013 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1014 | |||
1013 | A namespace is a set of files that were signed by the same pseudonym. | 1015 | A namespace is a set of files that were signed by the same pseudonym. |
1014 | Files (or directories) that have been signed and placed into a namespace | 1016 | Files (or directories) that have been signed and placed into a namespace |
1015 | can be updated. Updates are identified as authentic if the same secret | 1017 | can be updated. Updates are identified as authentic if the same secret |
@@ -1021,19 +1023,23 @@ same entity (which does not have to be the same person). | |||
1021 | @subsubsection Advertisements | 1023 | @subsubsection Advertisements |
1022 | @c %**end of header | 1024 | @c %**end of header |
1023 | 1025 | ||
1026 | @b{Please note that the text in this subsection is outdated and needs} | ||
1027 | @b{to be rewritten for version 0.10!} | ||
1028 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1029 | |||
1024 | Advertisements are used to notify other users about the existence of a | 1030 | Advertisements are used to notify other users about the existence of a |
1025 | namespace. Advertisements are propagated using the normal keyword search. | 1031 | namespace. Advertisements are propagated using the normal keyword search. |
1026 | When an advertisement is received (in response to a search), the namespace | 1032 | When an advertisement is received (in response to a search), the namespace |
1027 | is added to the list of namespaces available in the namespace-search | 1033 | is added to the list of namespaces available in the namespace-search |
1028 | dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a | 1034 | dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a |
1029 | namespace is created, an appropriate advertisement can be generated. | 1035 | namespace is created, an appropriate advertisement can be generated. |
1030 | The default keyword for the advertising of namespaces is "namespace". | 1036 | The default keyword for the advertising of namespaces is "namespace". |
1031 | 1037 | ||
1032 | Note that GNUnet differenciates between your pseudonyms (the identities | 1038 | Note that GNUnet differentiates between your pseudonyms (the identities |
1033 | that you control) and namespaces. If you create a pseudonym, you will | 1039 | that you control) and namespaces. If you create a pseudonym, you will |
1034 | not automatically see the respective namespace. You first have to create | 1040 | not automatically see the respective namespace. You first have to create |
1035 | an advertisement for the namespace and find it using keyword | 1041 | an advertisement for the namespace and find it using keyword |
1036 | search --- even for your own namespaces. The @command{gnunet-pseudonym} | 1042 | search --- even for your own namespaces. The @command{gnunet-identity} |
1037 | tool is currently responsible for both managing pseudonyms and namespaces. | 1043 | tool is currently responsible for both managing pseudonyms and namespaces. |
1038 | This will likely change in the future to reduce the potential for | 1044 | This will likely change in the future to reduce the potential for |
1039 | confusion. | 1045 | confusion. |
@@ -1080,205 +1086,16 @@ replication level into the network, and then decrement the replication | |||
1080 | level by one. If all blocks reach replication level zero, the | 1086 | level by one. If all blocks reach replication level zero, the |
1081 | selection is simply random. | 1087 | selection is simply random. |
1082 | 1088 | ||
1083 | @node File-sharing Publishing | ||
1084 | @subsection File-sharing Publishing | ||
1085 | @c %**end of header | ||
1086 | |||
1087 | The command @command{gnunet-publish} can be used to add content | ||
1088 | to the network. The basic format of the command is | ||
1089 | |||
1090 | @example | ||
1091 | $ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME | ||
1092 | @end example | ||
1093 | |||
1094 | 1089 | ||
1095 | @menu | 1090 | @node Namespace Management |
1096 | * Important command-line options:: | 1091 | @subsection Namespace Management |
1097 | * Indexing vs. Inserting:: | ||
1098 | @end menu | ||
1099 | |||
1100 | @node Important command-line options | ||
1101 | @subsubsection Important command-line options | ||
1102 | @c %**end of header | ||
1103 | |||
1104 | The option -k is used to specify keywords for the file that | ||
1105 | should be inserted. You can supply any number of keywords, | ||
1106 | and each of the keywords will be sufficient to locate and | ||
1107 | retrieve the file. | ||
1108 | |||
1109 | The -m option is used to specify meta-data, such as descriptions. | ||
1110 | You can use -m multiple times. The TYPE passed must be from the | ||
1111 | list of meta-data types known to libextractor. You can obtain this | ||
1112 | list by running @command{extract -L}. Use quotes around the entire | ||
1113 | meta-data argument if the value contains spaces. The meta-data | ||
1114 | is displayed to other users when they select which files to | ||
1115 | download. The meta-data and the keywords are optional and | ||
1116 | maybe inferred using @code{GNU libextractor}. | ||
1117 | |||
1118 | gnunet-publish has a few additional options to handle namespaces and | ||
1119 | directories. See the man-page for details. | ||
1120 | |||
1121 | @node Indexing vs. Inserting | ||
1122 | @subsubsection Indexing vs Inserting | ||
1123 | @c %**end of header | ||
1124 | |||
1125 | By default, GNUnet indexes a file instead of making a full copy. | ||
1126 | This is much more efficient, but requries the file to stay unaltered | ||
1127 | at the location where it was when it was indexed. If you intend to move, | ||
1128 | delete or alter a file, consider using the option @code{-n} which will | ||
1129 | force GNUnet to make a copy of the file in the database. | ||
1130 | |||
1131 | Since it is much less efficient, this is strongly discouraged for large | ||
1132 | files. When GNUnet indexes a file (default), GNUnet does @strong{not} | ||
1133 | create an additional encrypted copy of the file but just computes a | ||
1134 | summary (or index) of the file. That summary is approximately two percent | ||
1135 | of the size of the original file and is stored in GNUnet's database. | ||
1136 | Whenever a request for a part of an indexed file reaches GNUnet, | ||
1137 | this part is encrypted on-demand and send out. This way, there is no | ||
1138 | need for an additional encrypted copy of the file to stay anywhere | ||
1139 | on the drive. This is different from other systems, such as Freenet, | ||
1140 | where each file that is put online must be in Freenet's database in | ||
1141 | encrypted format, doubling the space requirements if the user wants | ||
1142 | to preseve a directly accessible copy in plaintext. | ||
1143 | |||
1144 | Thus indexing should be used for all files where the user will keep | ||
1145 | using this file (at the location given to gnunet-publish) and does | ||
1146 | not want to retrieve it back from GNUnet each time. If you want to | ||
1147 | remove a file that you have indexed from the local peer, use the tool | ||
1148 | @command{gnunet-unindex} to un-index the file. | ||
1149 | |||
1150 | The option @code{-n} may be used if the user fears that the file might | ||
1151 | be found on their drive (assuming the computer comes under the control | ||
1152 | of an adversary). When used with the @code{-n} flag, the user has a | ||
1153 | much better chance of denying knowledge of the existence of the file, | ||
1154 | even if it is still (encrypted) on the drive and the adversary is | ||
1155 | able to crack the encryption (e.g. by guessing the keyword. | ||
1156 | |||
1157 | @node File-sharing Searching | ||
1158 | @subsection File-sharing Searching | ||
1159 | @c %**end of header | ||
1160 | |||
1161 | The command @command{gnunet-search} can be used to search | ||
1162 | for content on GNUnet. The format is: | ||
1163 | |||
1164 | @example | ||
1165 | $ gnunet-search [-t TIMEOUT] KEYWORD | ||
1166 | @end example | ||
1167 | |||
1168 | @noindent | ||
1169 | The -t option specifies that the query should timeout after | ||
1170 | approximately TIMEOUT seconds. A value of zero is interpreted | ||
1171 | as @emph{no timeout}, which is also the default. In this case, | ||
1172 | gnunet-search will never terminate (unless you press CTRL-C). | ||
1173 | |||
1174 | If multiple words are passed as keywords, they will all be | ||
1175 | considered optional. Prefix keywords with a "+" to make them mandatory. | ||
1176 | |||
1177 | Note that searching using | ||
1178 | |||
1179 | @example | ||
1180 | $ gnunet-search Das Kapital | ||
1181 | @end example | ||
1182 | |||
1183 | @noindent | ||
1184 | is not the same as searching for | ||
1185 | |||
1186 | @example | ||
1187 | $ gnunet-search "Das Kapital" | ||
1188 | @end example | ||
1189 | |||
1190 | @noindent | ||
1191 | as the first will match files shared under the keywords | ||
1192 | "Das" or "Kapital" whereas the second will match files | ||
1193 | shared under the keyword "Das Kapital". | ||
1194 | |||
1195 | Search results are printed by gnunet-search like this: | ||
1196 | |||
1197 | @c it will be better the avoid the ellipsis altogether because I don't | ||
1198 | @c understand the explanation below that | ||
1199 | @example | ||
1200 | $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992 | ||
1201 | => The GNU Public License <= (mimetype: text/plain) | ||
1202 | @end example | ||
1203 | |||
1204 | @noindent | ||
1205 | The first line is the command you would have to enter to download | ||
1206 | the file. The argument passed to @code{-o} is the suggested | ||
1207 | filename (you may change it to whatever you like). | ||
1208 | @c except it's triple dash in the above example --- | ||
1209 | The @code{--} is followed by key for decrypting the file, | ||
1210 | the query for searching the file, a checksum (in hexadecimal) | ||
1211 | finally the size of the file in bytes. | ||
1212 | The second line contains the description of the file; here this is | ||
1213 | "The GNU Public License" and the mime-type (see the options for | ||
1214 | gnunet-publish on how to specify these). | ||
1215 | |||
1216 | @node File-sharing Downloading | ||
1217 | @subsection File-sharing Downloading | ||
1218 | @c %**end of header | ||
1219 | |||
1220 | In order to download a file, you need the three values returned by | ||
1221 | @command{gnunet-search}. | ||
1222 | You can then use the tool @command{gnunet-download} to obtain the file: | ||
1223 | |||
1224 | @example | ||
1225 | $ gnunet-download -o FILENAME --- GNUNETURL | ||
1226 | @end example | ||
1227 | |||
1228 | @noindent | ||
1229 | FILENAME specifies the name of the file where GNUnet is supposed | ||
1230 | to write the result. Existing files are overwritten. If the | ||
1231 | existing file contains blocks that are identical to the | ||
1232 | desired download, those blocks will not be downloaded again | ||
1233 | (automatic resume). | ||
1234 | |||
1235 | If you want to download the GPL from the previous example, | ||
1236 | you do the following: | ||
1237 | |||
1238 | @example | ||
1239 | $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992 | ||
1240 | @end example | ||
1241 | |||
1242 | @noindent | ||
1243 | If you ever have to abort a download, you can continue it at any time by | ||
1244 | re-issuing @command{gnunet-download} with the same filename. | ||
1245 | In that case, GNUnet will @strong{not} download blocks again that are | ||
1246 | already present. | ||
1247 | |||
1248 | GNUnet's file-encoding mechanism will ensure file integrity, even if the | ||
1249 | existing file was not downloaded from GNUnet in the first place. | ||
1250 | |||
1251 | You may want to use the @command{-V} switch (must be added before | ||
1252 | @c Same as above it's triple dash | ||
1253 | the @command{--}) to turn on verbose reporting. In this case, | ||
1254 | @command{gnunet-download} will print the current number of | ||
1255 | bytes downloaded whenever new data was received. | ||
1256 | |||
1257 | @node File-sharing Directories | ||
1258 | @subsection File-sharing Directories | ||
1259 | @c %**end of header | ||
1260 | |||
1261 | Directories are shared just like ordinary files. If you download a | ||
1262 | directory with @command{gnunet-download}, you can use | ||
1263 | @command{gnunet-directory} to list its contents. The canonical | ||
1264 | extension for GNUnet directories when stored as files in your | ||
1265 | local file-system is ".gnd". The contents of a directory are URIs and | ||
1266 | meta data. | ||
1267 | The URIs contain all the information required by | ||
1268 | @command{gnunet-download} to retrieve the file. The meta data | ||
1269 | typically includes the mime-type, description, a filename and | ||
1270 | other meta information, and possibly even the full original file | ||
1271 | (if it was small). | ||
1272 | |||
1273 | @node File-sharing Namespace Management | ||
1274 | @subsection File-sharing Namespace Management | ||
1275 | @c %**end of header | 1092 | @c %**end of header |
1276 | 1093 | ||
1277 | @b{Please note that the text in this subsection is outdated and needs} | 1094 | @b{Please note that the text in this subsection is outdated and needs} |
1278 | @b{to be rewritten for version 0.10!} | 1095 | @b{to be rewritten for version 0.10!} |
1279 | 1096 | ||
1280 | The gnunet-pseudonym tool can be used to create pseudonyms and | 1097 | The @code{gnunet-identity} tool can be used to create pseudonyms and |
1281 | to advertise namespaces. By default, gnunet-pseudonym simply | 1098 | to advertise namespaces. By default, @code{gnunet-identity -D} simply |
1282 | lists all locally available pseudonyms. | 1099 | lists all locally available pseudonyms. |
1283 | 1100 | ||
1284 | 1101 | ||
@@ -1294,6 +1111,10 @@ lists all locally available pseudonyms. | |||
1294 | @subsubsection Creating Pseudonyms | 1111 | @subsubsection Creating Pseudonyms |
1295 | @c %**end of header | 1112 | @c %**end of header |
1296 | 1113 | ||
1114 | @b{Please note that the text in this subsection is outdated and needs} | ||
1115 | @b{to be rewritten for version 0.10!} | ||
1116 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1117 | |||
1297 | With the @command{-C NICK} option it can also be used to | 1118 | With the @command{-C NICK} option it can also be used to |
1298 | create a new pseudonym. A pseudonym is the virtual identity | 1119 | create a new pseudonym. A pseudonym is the virtual identity |
1299 | of the entity in control of a namespace. Anyone can create | 1120 | of the entity in control of a namespace. Anyone can create |
@@ -1305,6 +1126,10 @@ used. | |||
1305 | @subsubsection Deleting Pseudonyms | 1126 | @subsubsection Deleting Pseudonyms |
1306 | @c %**end of header | 1127 | @c %**end of header |
1307 | 1128 | ||
1129 | @b{Please note that the text in this subsection is outdated and needs} | ||
1130 | @b{to be rewritten for version 0.10!} | ||
1131 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1132 | |||
1308 | With the @command{-D NICK} option pseudonyms can be deleted. | 1133 | With the @command{-D NICK} option pseudonyms can be deleted. |
1309 | Once the pseudonym has been deleted it is impossible to add | 1134 | Once the pseudonym has been deleted it is impossible to add |
1310 | content to the corresponding namespace. Deleting the | 1135 | content to the corresponding namespace. Deleting the |
@@ -1315,6 +1140,10 @@ unavailable. | |||
1315 | @subsubsection Advertising namespaces | 1140 | @subsubsection Advertising namespaces |
1316 | @c %**end of header | 1141 | @c %**end of header |
1317 | 1142 | ||
1143 | @b{Please note that the text in this subsection is outdated and needs} | ||
1144 | @b{to be rewritten for version 0.10!} | ||
1145 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1146 | |||
1318 | Each namespace is associated with meta-data that describes | 1147 | Each namespace is associated with meta-data that describes |
1319 | the namespace. This meta-data is provided by the user at | 1148 | the namespace. This meta-data is provided by the user at |
1320 | the time that the namespace is advertised. Advertisements | 1149 | the time that the namespace is advertised. Advertisements |
@@ -1331,6 +1160,10 @@ the quality of the content found in it. | |||
1331 | @subsubsection Namespace names | 1160 | @subsubsection Namespace names |
1332 | @c %**end of header | 1161 | @c %**end of header |
1333 | 1162 | ||
1163 | @b{Please note that the text in this subsection is outdated and needs} | ||
1164 | @b{to be rewritten for version 0.10!} | ||
1165 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1166 | |||
1334 | While the namespace is uniquely identified by its ID, another way | 1167 | While the namespace is uniquely identified by its ID, another way |
1335 | to refer to the namespace is to use the NICKNAME. | 1168 | to refer to the namespace is to use the NICKNAME. |
1336 | The NICKNAME can be freely chosen by the creator of the namespace and | 1169 | The NICKNAME can be freely chosen by the creator of the namespace and |
@@ -1342,6 +1175,10 @@ to the NICKNAME to get a unique identifier. | |||
1342 | @subsubsection Namespace root | 1175 | @subsubsection Namespace root |
1343 | @c %**end of header | 1176 | @c %**end of header |
1344 | 1177 | ||
1178 | @b{Please note that the text in this subsection is outdated and needs} | ||
1179 | @b{to be rewritten for version 0.10!} | ||
1180 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1181 | |||
1345 | An item of particular interest in the namespace advertisement is | 1182 | An item of particular interest in the namespace advertisement is |
1346 | the ROOT. The ROOT is the identifier of a designated entry in the | 1183 | the ROOT. The ROOT is the identifier of a designated entry in the |
1347 | namespace. The idea is that the ROOT can be used to advertise an | 1184 | namespace. The idea is that the ROOT can be used to advertise an |
@@ -1355,6 +1192,11 @@ GNUnet (currently) uses four different types of URIs for | |||
1355 | file-sharing. They all begin with "gnunet://fs/". | 1192 | file-sharing. They all begin with "gnunet://fs/". |
1356 | This section describes the four different URI types in detail. | 1193 | This section describes the four different URI types in detail. |
1357 | 1194 | ||
1195 | For FS URIs empty KEYWORDs are not allowed. Quotes are allowed to | ||
1196 | denote whitespace between words. Keywords must contain a balanced | ||
1197 | number of double quotes. Doubles quotes can not be used in the actual | ||
1198 | keywords. This means that the the string '""foo bar""' will be turned | ||
1199 | into two OR-ed keywords 'foo' and 'bar', not into '"foo bar"'. | ||
1358 | 1200 | ||
1359 | @menu | 1201 | @menu |
1360 | * Encoding of hash values in URIs:: | 1202 | * Encoding of hash values in URIs:: |
@@ -1371,6 +1213,7 @@ This section describes the four different URI types in detail. | |||
1371 | Most URIs include some hash values. Hashes are encoded using | 1213 | Most URIs include some hash values. Hashes are encoded using |
1372 | base32hex (RFC 2938). | 1214 | base32hex (RFC 2938). |
1373 | 1215 | ||
1216 | @cindex chk-uri | ||
1374 | @node Content Hash Key (chk) | 1217 | @node Content Hash Key (chk) |
1375 | @subsubsection Content Hash Key (chk) | 1218 | @subsubsection Content Hash Key (chk) |
1376 | @c %**end of header | 1219 | @c %**end of header |
@@ -1387,6 +1230,7 @@ shape of the tree), KEYHASH is the key used to decrypt the file | |||
1387 | is the query used to request the top-level block (also the hash | 1230 | is the query used to request the top-level block (also the hash |
1388 | of the encrypted block). | 1231 | of the encrypted block). |
1389 | 1232 | ||
1233 | @cindex loc-uri | ||
1390 | @node Location identifiers (loc) | 1234 | @node Location identifiers (loc) |
1391 | @subsubsection Location identifiers (loc) | 1235 | @subsubsection Location identifiers (loc) |
1392 | @c %**end of header | 1236 | @c %**end of header |
@@ -1402,6 +1246,7 @@ base32hex), SIG is the RSA signature (in GNUnet format in | |||
1402 | base32hex) and EXPTIME specifies when the signature expires | 1246 | base32hex) and EXPTIME specifies when the signature expires |
1403 | (in milliseconds after 1970). | 1247 | (in milliseconds after 1970). |
1404 | 1248 | ||
1249 | @cindex ksk-uri | ||
1405 | @node Keyword queries (ksk) | 1250 | @node Keyword queries (ksk) |
1406 | @subsubsection Keyword queries (ksk) | 1251 | @subsubsection Keyword queries (ksk) |
1407 | @c %**end of header | 1252 | @c %**end of header |
@@ -1413,11 +1258,18 @@ using the typical URI-encoding (using hex values) from HTTP. | |||
1413 | "+" can be used to specify multiple keywords (which are then | 1258 | "+" can be used to specify multiple keywords (which are then |
1414 | logically "OR"-ed in the search, results matching both keywords | 1259 | logically "OR"-ed in the search, results matching both keywords |
1415 | are given a higher rank): "gnunet://fs/ksk/KEYWORD1+KEYWORD2". | 1260 | are given a higher rank): "gnunet://fs/ksk/KEYWORD1+KEYWORD2". |
1261 | ksk-URIs must not begin or end with the plus ('+') character. | ||
1262 | Furthermore they must not contain '++'. | ||
1416 | 1263 | ||
1264 | @cindex sks-uri | ||
1417 | @node Namespace content (sks) | 1265 | @node Namespace content (sks) |
1418 | @subsubsection Namespace content (sks) | 1266 | @subsubsection Namespace content (sks) |
1419 | @c %**end of header | 1267 | @c %**end of header |
1420 | 1268 | ||
1269 | @b{Please note that the text in this subsection is outdated and needs} | ||
1270 | @b{to be rewritten for version 0.10!} | ||
1271 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1272 | |||
1421 | Namespaces are sets of files that have been approved by some (usually | 1273 | Namespaces are sets of files that have been approved by some (usually |
1422 | pseudonymous) user --- typically by that user publishing all of the | 1274 | pseudonymous) user --- typically by that user publishing all of the |
1423 | files together. A file can be in many namespaces. A file is in a | 1275 | files together. A file can be in many namespaces. A file is in a |
@@ -1431,6 +1283,135 @@ chosen keyword (or password!). A commonly used identifier is | |||
1431 | "root" which by convention refers to some kind of index or other | 1283 | "root" which by convention refers to some kind of index or other |
1432 | entry point into the namespace. | 1284 | entry point into the namespace. |
1433 | 1285 | ||
1286 | @node GTK User Interface | ||
1287 | @subsection GTK User Interface | ||
1288 | This chapter describes first steps for file-sharing with GNUnet. | ||
1289 | To start, you should launch @command{gnunet-fs-gtk}. | ||
1290 | |||
1291 | As we want to be sure that the network contains the data that we are | ||
1292 | looking for for testing, we need to begin by publishing a file. | ||
1293 | |||
1294 | @menu | ||
1295 | * gtk-Publishing:: | ||
1296 | * gtk-Searching:: | ||
1297 | * gtk-Downloading:: | ||
1298 | @end menu | ||
1299 | |||
1300 | @node gtk-Publishing | ||
1301 | @subsubsection Publishing | ||
1302 | @c %**end of header | ||
1303 | |||
1304 | To publish a file, select "File Sharing" in the menu bar just below the | ||
1305 | "Statistics" icon, and then select "Publish" from the menu. | ||
1306 | |||
1307 | Afterwards, the following publishing dialog will appear: | ||
1308 | |||
1309 | @c Add image here | ||
1310 | |||
1311 | In this dialog, select the "Add File" button. This will open a | ||
1312 | file selection dialog: | ||
1313 | |||
1314 | @c Add image here | ||
1315 | |||
1316 | Now, you should select a file from your computer to be published on | ||
1317 | GNUnet. To see more of GNUnet's features later, you should pick a | ||
1318 | PNG or JPEG file this time. You can leave all of the other options | ||
1319 | in the dialog unchanged. Confirm your selection by pressing the "OK" | ||
1320 | button in the bottom right corner. Now, you will briefly see a | ||
1321 | "Messages..." dialog pop up, but most likely it will be too short for | ||
1322 | you to really read anything. That dialog is showing you progress | ||
1323 | information as GNUnet takes a first look at the selected file(s). | ||
1324 | For a normal image, this is virtually instant, but if you later | ||
1325 | import a larger directory you might be interested in the progress dialog | ||
1326 | and potential errors that might be encountered during processing. | ||
1327 | After the progress dialog automatically disappears, your file | ||
1328 | should now appear in the publishing dialog: | ||
1329 | |||
1330 | @c Add image here | ||
1331 | |||
1332 | Now, select the file (by clicking on the file name) and then click | ||
1333 | the "Edit" button. This will open the editing dialog: | ||
1334 | |||
1335 | @c Add image here | ||
1336 | |||
1337 | In this dialog, you can see many details about your file. In the | ||
1338 | top left area, you can see meta data extracted about the file, | ||
1339 | such as the original filename, the mimetype and the size of the image. | ||
1340 | In the top right, you should see a preview for the image | ||
1341 | (if GNU libextractor was installed correctly with the | ||
1342 | respective plugins). Note that if you do not see a preview, this | ||
1343 | is not a disaster, but you might still want to install more of | ||
1344 | GNU libextractor in the future. In the bottom left, the dialog contains | ||
1345 | a list of keywords. These are the keywords under which the file will be | ||
1346 | made available. The initial list will be based on the extracted meta data. | ||
1347 | Additional publishing options are in the right bottom corner. We will | ||
1348 | now add an additional keyword to the list of keywords. This is done by | ||
1349 | entering the keyword above the keyword list between the label "Keyword" | ||
1350 | and the "Add keyword" button. Enter "test" and select "Add keyword". | ||
1351 | Note that the keyword will appear at the bottom of the existing keyword | ||
1352 | list, so you might have to scroll down to see it. Afterwards, push the | ||
1353 | "OK" button at the bottom right of the dialog. | ||
1354 | |||
1355 | You should now be back at the "Publish content on GNUnet" dialog. Select | ||
1356 | "Execute" in the bottom right to close the dialog and publish your file | ||
1357 | on GNUnet! Afterwards, you should see the main dialog with a new area | ||
1358 | showing the list of published files (or ongoing publishing operations | ||
1359 | with progress indicators): | ||
1360 | |||
1361 | @c Add image here | ||
1362 | |||
1363 | @node gtk-Searching | ||
1364 | @subsubsection Searching | ||
1365 | @c %**end of header | ||
1366 | |||
1367 | Below the menu bar, there are four entry widges labeled "Namespace", | ||
1368 | "Keywords", "Anonymity" and "Mime-type" (from left to right). These | ||
1369 | widgets are used to control searching for files in GNUnet. Between the | ||
1370 | "Keywords" and "Anonymity" widgets, there is also a big "Search" button, | ||
1371 | which is used to initiate the search. We will ignore the "Namespace", | ||
1372 | "Anonymity" and "Mime-type" options in this tutorial, please leave them | ||
1373 | empty. Instead, simply enter "test" under "Keywords" and press "Search". | ||
1374 | Afterwards, you should immediately see a new tab labeled after your | ||
1375 | search term, followed by the (current) number of search | ||
1376 | results --- "(15)" in our screenshot. Note that your results may | ||
1377 | vary depending on what other users may have shared and how your | ||
1378 | peer is connected. | ||
1379 | |||
1380 | You can now select one of the search results. Once you do this, | ||
1381 | additional information about the result should be displayed on the | ||
1382 | right. If available, a preview image should appear on the top right. | ||
1383 | Meta data describing the file will be listed at the bottom right. | ||
1384 | |||
1385 | Once a file is selected, at the bottom of the search result list | ||
1386 | a little area for downloading appears. | ||
1387 | |||
1388 | @node gtk-Downloading | ||
1389 | @subsubsection Downloading | ||
1390 | @c %**end of header | ||
1391 | |||
1392 | In the downloading area, you can select the target directory (default is | ||
1393 | "Downloads") and specify the desired filename (by default the filename it | ||
1394 | taken from the meta data of the published file). Additionally, you can | ||
1395 | specify if the download should be anonymous and (for directories) if | ||
1396 | the download should be recursive. In most cases, you can simply start | ||
1397 | the download with the "Download!" button. | ||
1398 | |||
1399 | Once you selected download, the progress of the download will be | ||
1400 | displayed with the search result. You may need to resize the result | ||
1401 | list or scroll to the right. The "Status" column shows the current | ||
1402 | status of the download, and "Progress" how much has been completed. | ||
1403 | When you close the search tab (by clicking on the "X" button next to | ||
1404 | the "test" label), ongoing and completed downloads are not aborted | ||
1405 | but moved to a special "*" tab. | ||
1406 | |||
1407 | You can remove completed downloads from the "*" tab by clicking the | ||
1408 | cleanup button next to the "*". You can also abort downloads by right | ||
1409 | clicking on the respective download and selecting "Abort download" | ||
1410 | from the menu. | ||
1411 | |||
1412 | That's it, you now know the basics for file-sharing with GNUnet! | ||
1413 | |||
1414 | |||
1434 | @node The GNU Name System | 1415 | @node The GNU Name System |
1435 | @section The GNU Name System | 1416 | @section The GNU Name System |
1436 | @c %**end of header | 1417 | @c %**end of header |
@@ -1466,47 +1447,42 @@ the user. This results in non-unique name-value mappings as | |||
1466 | 1447 | ||
1467 | 1448 | ||
1468 | @menu | 1449 | @menu |
1450 | * Creating a Zone:: | ||
1469 | * Maintaining your own Zones:: | 1451 | * Maintaining your own Zones:: |
1470 | * Obtaining your Zone Key:: | 1452 | * Obtaining your Zone Key:: |
1471 | * Adding Links to Other Zones:: | 1453 | * Adding Links to Other Zones:: |
1472 | * The Three Local Zones of GNS:: | 1454 | * Using Public Keys as Top Level Domains:: |
1473 | * The Master Zone:: | ||
1474 | * The Private Zone:: | ||
1475 | * The Shorten Zone:: | ||
1476 | * The ZKEY Top Level Domain in GNS:: | ||
1477 | * Resource Records in GNS:: | 1455 | * Resource Records in GNS:: |
1456 | * Synchronizing with legacy DNS:: | ||
1478 | @end menu | 1457 | @end menu |
1479 | 1458 | ||
1480 | 1459 | ||
1481 | @node Maintaining your own Zones | 1460 | @node Creating a Zone |
1482 | @subsection Maintaining your own Zones | 1461 | @subsection Creating a Zone |
1483 | 1462 | ||
1484 | To setup your GNS system you must execute: | 1463 | To use GNS, you probably should create at least one zone of your own. |
1464 | You can create any number of zones using the gnunet-identity tool | ||
1465 | using: | ||
1485 | 1466 | ||
1486 | @example | 1467 | @example |
1487 | $ gnunet-gns-import.sh | 1468 | $ gnunet-identity -C "myzone" |
1488 | @end example | 1469 | @end example |
1489 | 1470 | ||
1490 | @noindent | 1471 | Henceforth, on your system you control the TLD ``myzone''. |
1491 | This will boostrap your zones and create the necessary key material. | 1472 | |
1492 | Your keys can be listed using the @command{gnunet-identity} | 1473 | All of your zones can be listed (displayed) using the |
1493 | command line tool: | 1474 | @command{gnunet-identity} command line tool as well: |
1494 | 1475 | ||
1495 | @example | 1476 | @example |
1496 | $ gnunet-identity -d | 1477 | $ gnunet-identity -d |
1497 | @end example | 1478 | @end example |
1498 | 1479 | ||
1499 | @noindent | 1480 | @node Maintaining your own Zones |
1500 | You can arbitrarily create your own zones using the gnunet-identity | 1481 | @subsection Maintaining your own Zones |
1501 | tool using: | ||
1502 | |||
1503 | @example | ||
1504 | $ gnunet-identity -C "new_zone" | ||
1505 | @end example | ||
1506 | 1482 | ||
1507 | @noindent | 1483 | @noindent |
1508 | Now you can add (or edit, or remove) records in your GNS zone using the | 1484 | Now you can add (or edit, or remove) records in your GNS zone using the |
1509 | @command{gnunet-setup} GUI or using the @command{gnunet-namestore} | 1485 | @command{gnunet-namestore-gtk} GUI or using the @command{gnunet-namestore} |
1510 | command-line tool. | 1486 | command-line tool. |
1511 | In either case, your records will be stored in an SQL database under | 1487 | In either case, your records will be stored in an SQL database under |
1512 | control of the @command{gnunet-service-namestore}. | 1488 | control of the @command{gnunet-service-namestore}. |
@@ -1518,21 +1494,21 @@ if they are marked as private. | |||
1518 | To provide a short example for editing your own zone, suppose you | 1494 | To provide a short example for editing your own zone, suppose you |
1519 | have your own web server with the IP @code{1.2.3.4}. Then you can put an | 1495 | have your own web server with the IP @code{1.2.3.4}. Then you can put an |
1520 | @code{A} record (@code{A} records in DNS are for IPv4 IP addresses) | 1496 | @code{A} record (@code{A} records in DNS are for IPv4 IP addresses) |
1521 | into your local zone using the command: | 1497 | into your local zone ``myzone'' using the command: |
1522 | 1498 | ||
1523 | @example | 1499 | @example |
1524 | $ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never | 1500 | $ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e never |
1525 | @end example | 1501 | @end example |
1526 | 1502 | ||
1527 | @noindent | 1503 | @noindent |
1528 | Afterwards, you will be able to access your webpage under "www.gnu" | 1504 | Afterwards, you will be able to access your webpage under "www.myzone" |
1529 | (assuming your webserver does not use virtual hosting, if it does, | 1505 | (assuming your webserver does not use virtual hosting, if it does, |
1530 | please read up on setting up the GNS proxy). | 1506 | please read up on setting up the GNS proxy). |
1531 | 1507 | ||
1532 | Similar commands will work for other types of DNS and GNS records, | 1508 | Similar commands will work for other types of DNS and GNS records, |
1533 | the syntax largely depending on the type of the record. | 1509 | the syntax largely depending on the type of the record. |
1534 | Naturally, most users may find editing the zones using the | 1510 | Naturally, most users may find editing the zones using the |
1535 | @command{gnunet-setup} GUI to be easier. | 1511 | @command{gnunet-namestore-gtk} GUI to be easier. |
1536 | 1512 | ||
1537 | @node Obtaining your Zone Key | 1513 | @node Obtaining your Zone Key |
1538 | @subsection Obtaining your Zone Key | 1514 | @subsection Obtaining your Zone Key |
@@ -1546,7 +1522,7 @@ give it to others so that they can securely link to you. | |||
1546 | You can usually get the hash of your public key using | 1522 | You can usually get the hash of your public key using |
1547 | 1523 | ||
1548 | @example | 1524 | @example |
1549 | $ gnunet-identity -d $options | grep master-zone | awk '@{print $3@}' | 1525 | $ gnunet-identity -d $options | grep myzone | awk '@{print $3@}' |
1550 | @end example | 1526 | @end example |
1551 | 1527 | ||
1552 | @noindent | 1528 | @noindent |
@@ -1557,10 +1533,10 @@ DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0 | |||
1557 | @end example | 1533 | @end example |
1558 | 1534 | ||
1559 | @noindent | 1535 | @noindent |
1560 | Alternatively, you can obtain a QR code with your zone key AND | 1536 | Alternatively, you can obtain a QR code with your zone key AND your |
1561 | your pseudonym from gnunet-gtk. The QR code is displayed in the | 1537 | pseudonym from gnunet-namestore-gtk. The QR code is displayed in the |
1562 | GNS tab and can be stored to disk using the Save as button next | 1538 | main window and can be stored to disk using the ``Save as'' button |
1563 | to the image. | 1539 | next to the image. |
1564 | 1540 | ||
1565 | @node Adding Links to Other Zones | 1541 | @node Adding Links to Other Zones |
1566 | @subsection Adding Links to Other Zones | 1542 | @subsection Adding Links to Other Zones |
@@ -1576,90 +1552,38 @@ You can then delegate resolution of names to Bob's zone by adding | |||
1576 | a PKEY record to their local zone: | 1552 | a PKEY record to their local zone: |
1577 | 1553 | ||
1578 | @example | 1554 | @example |
1579 | $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never | 1555 | $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never -Z myzone |
1580 | @end example | 1556 | @end example |
1581 | 1557 | ||
1582 | @noindent | 1558 | @noindent |
1583 | Note that XXXX in the command above must be replaced with the | 1559 | Note that ``XXXX'' in the command above must be replaced with the hash |
1584 | hash of Bob's public key (the output your friend obtained using | 1560 | of Bob's public key (the output your friend obtained using the |
1585 | the gnunet-identity command from the previous section and told you, | 1561 | @command{gnunet-identity} command from the previous section and told |
1586 | for example by giving you a business card containing this | 1562 | you, for example by giving you a business card containing this |
1587 | information as a QR code). | 1563 | information as a QR code). |
1588 | 1564 | ||
1589 | Assuming Bob has an A record for their website under the name of | 1565 | Assuming Bob has an ``A'' record for their website under the name of |
1590 | www in his zone, you can then access Bob's website under | 1566 | ``www'' in his zone, you can then access Bob's website under |
1591 | www.bob.gnu --- as well as any (public) GNS record that Bob has | 1567 | ``www.bob.myzone'' --- as well as any (public) GNS record that Bob has |
1592 | in their zone by replacing www with the respective name of the | 1568 | in their zone by replacing www with the respective name of the |
1593 | record in Bob's zone. | 1569 | record in Bob's zone. |
1594 | 1570 | ||
1595 | @c themselves? themself? | 1571 | @c themselves? themself? |
1596 | Furthermore, if Bob has themselves a (public) delegation to Carol's | 1572 | Furthermore, if Bob has themselves a (public) delegation to Carol's |
1597 | zone under "carol", you can access Carol's records under | 1573 | zone under "carol", you can access Carol's records under |
1598 | NAME.carol.bob.gnu (where NAME is the name of Carol's record you | 1574 | ``NAME.carol.bob.myzone'' (where ``NAME'' is the name of Carol's |
1599 | want to access). | 1575 | record you want to access). |
1600 | |||
1601 | @node The Three Local Zones of GNS | ||
1602 | @subsection The Three Local Zones of GNS | ||
1603 | |||
1604 | Each user GNS has control over three zones. Each of the zones | ||
1605 | has a different purpose. These zones are the | ||
1606 | |||
1607 | @itemize @bullet | ||
1608 | |||
1609 | @item master zone, | ||
1610 | @item private zone, and the | ||
1611 | @item shorten zone. | ||
1612 | @end itemize | ||
1613 | |||
1614 | @node The Master Zone | ||
1615 | @subsection The Master Zone | ||
1616 | |||
1617 | |||
1618 | The master zone is your personal TLD. Names within the @code{.gnu} | ||
1619 | namespace are resolved relative to this zone. You can arbitrarily | ||
1620 | add records to this zone and selectively publish those records. | ||
1621 | |||
1622 | @node The Private Zone | ||
1623 | @subsection The Private Zone | ||
1624 | |||
1625 | 1576 | ||
1626 | The private zone is a subzone (or subdomain in DNS terms) of your | ||
1627 | master zone. It should be used for records that you want to keep | ||
1628 | private. For example @code{bank.private.gnu}. The key idea is that | ||
1629 | you want to keep your private records separate, if just to know | ||
1630 | that those names are not available to other users. | ||
1631 | 1577 | ||
1632 | @node The Shorten Zone | 1578 | @node Using Public Keys as Top Level Domains |
1633 | @subsection The Shorten Zone | 1579 | @subsection Using Public Keys as Top Level Domains |
1634 | 1580 | ||
1635 | 1581 | ||
1636 | The shorten zone can either be a subzone of the master zone or the | 1582 | GNS also assumes responsibility for any name that uses in a |
1637 | private zone. It is different from the other zones in that GNS | 1583 | well-formed public key for the TLD. Names ending this way are then |
1638 | will automatically populate this zone with other users' zones based | 1584 | resolved by querying the respective zone. Such public key TLDs are |
1639 | on their PSEU records whenever you resolve a name. | 1585 | expected to be used under rare circumstances where globally unique |
1640 | 1586 | names are required, and for integration with legacy systems. | |
1641 | For example if you go to | ||
1642 | @code{@uref{http://www.bob.alice.dave.gnu/, www.bob.alice.dave.gnu}}, | ||
1643 | GNS will try to import @code{bob} into your shorten zone. Having | ||
1644 | obtained Bob's PKEY from @code{alice.dave.gnu}, GNS will lookup the | ||
1645 | PSEU record for @code{+} in Bob's zone. If it exists and the specified | ||
1646 | pseudonym is not taken, Bob's PKEY will be automatically added under | ||
1647 | that pseudonym (i.e. "bob") into your shorten zone. From then on, | ||
1648 | Bob's webpage will also be available for you as | ||
1649 | @code{@uref{http://www.bob.short.gnu/, www.bob.short.gnu}}. | ||
1650 | This feature is called @b{automatic name shortening} and is supposed to | ||
1651 | keep GNS names as short and memorable as possible. | ||
1652 | |||
1653 | @node The ZKEY Top Level Domain in GNS | ||
1654 | @subsection The ZKEY Top Level Domain in GNS | ||
1655 | |||
1656 | |||
1657 | GNS also provides a secure and globally unique namespace under the .zkey | ||
1658 | top-level domain. A name in the .zkey TLD corresponds to the (printable) | ||
1659 | public key of a zone. Names in the .zkey TLD are then resolved by querying | ||
1660 | the respective zone. The .zkey TLD is expected to be used under rare | ||
1661 | circumstances where globally unique names are required and for | ||
1662 | integration with legacy systems. | ||
1663 | 1587 | ||
1664 | @node Resource Records in GNS | 1588 | @node Resource Records in GNS |
1665 | @subsection Resource Records in GNS | 1589 | @subsection Resource Records in GNS |
@@ -1682,7 +1606,7 @@ to the current authoritative zone. The extended processing of those | |||
1682 | names will expand the ".+" with the correct delegation chain to the | 1606 | names will expand the ".+" with the correct delegation chain to the |
1683 | authoritative zone (replacing ".+" with the name of the location | 1607 | authoritative zone (replacing ".+" with the name of the location |
1684 | where the name was encountered) and hence generate a | 1608 | where the name was encountered) and hence generate a |
1685 | valid @code{.gnu} name. | 1609 | valid GNS name. |
1686 | 1610 | ||
1687 | GNS currently supports the following record types: | 1611 | GNS currently supports the following record types: |
1688 | 1612 | ||
@@ -1696,28 +1620,43 @@ GNS currently supports the following record types: | |||
1696 | * CNAME:: | 1620 | * CNAME:: |
1697 | * GNS2DNS:: | 1621 | * GNS2DNS:: |
1698 | * SOA SRV PTR and MX:: | 1622 | * SOA SRV PTR and MX:: |
1623 | * PLACE:: | ||
1624 | * PHONE:: | ||
1625 | * ID ATTR:: | ||
1626 | * ID TOKEN:: | ||
1627 | * ID TOKEN METADATA:: | ||
1628 | * CREDENTIAL:: | ||
1629 | * POLICY:: | ||
1630 | * ATTRIBUTE:: | ||
1631 | * ABE KEY:: | ||
1632 | * ABE MASTER:: | ||
1633 | * RECLAIM OIDC CLIENT:: | ||
1634 | * RECLAIM OIDC REDIRECT:: | ||
1699 | @end menu | 1635 | @end menu |
1700 | 1636 | ||
1701 | @node NICK | 1637 | @node NICK |
1702 | @subsubsection NICK | 1638 | @subsubsection NICK |
1703 | 1639 | ||
1704 | A NICK record is used to give a zone a name. With a NICK record, you can | 1640 | A NICK record is used to give a zone a name. With a NICK record, you |
1705 | essentially specify how you would like to be called. GNS expects this | 1641 | can essentially specify how you would like to be called. GNS expects |
1706 | record under the name "+" in the zone's database (NAMESTORE); however, | 1642 | this record under the empty label ``@@'' in the zone's database |
1707 | it will then automatically be copied into each record set, so that | 1643 | (NAMESTORE); however, it will then automatically be copied into each |
1708 | clients never need to do a separate lookup to discover the NICK record. | 1644 | record set, so that clients never need to do a separate lookup to |
1645 | discover the NICK record. Also, users do not usually have to worry | ||
1646 | about setting the NICK record: it is automatically set to the local | ||
1647 | name of the TLD. | ||
1709 | 1648 | ||
1710 | @b{Example}@ | 1649 | @b{Example}@ |
1711 | 1650 | ||
1712 | @example | 1651 | @example |
1713 | Name: +; RRType: NICK; Value: bob | 1652 | Name: @@; RRType: NICK; Value: bob |
1714 | @end example | 1653 | @end example |
1715 | 1654 | ||
1716 | @noindent | 1655 | @noindent |
1717 | This record in Bob's zone will tell other users that this zone wants | 1656 | This record in Bob's zone will tell other users that this zone wants |
1718 | to be referred to as 'bob'. Note that nobody is obliged to call Bob's | 1657 | to be referred to as 'bob'. Note that nobody is obliged to call Bob's |
1719 | zone 'bob' in their own zones. It can be seen as a | 1658 | zone 'bob' in their own zones. It can be seen as a |
1720 | recommendation ("Please call me 'bob'"). | 1659 | recommendation ("Please call this zone 'bob'"). |
1721 | 1660 | ||
1722 | @node PKEY | 1661 | @node PKEY |
1723 | @subsubsection PKEY | 1662 | @subsubsection PKEY |
@@ -1864,6 +1803,188 @@ should use the ZKEY zone as the destination hostname and | |||
1864 | GNS-enabled mail servers should be configured to accept | 1803 | GNS-enabled mail servers should be configured to accept |
1865 | e-mails to the ZKEY-zones of all local users. | 1804 | e-mails to the ZKEY-zones of all local users. |
1866 | 1805 | ||
1806 | @node PLACE | ||
1807 | @subsubsection PLACE | ||
1808 | |||
1809 | Record type for a social place. | ||
1810 | |||
1811 | @node PHONE | ||
1812 | @subsubsection PHONE | ||
1813 | |||
1814 | Record type for a phone (of CONVERSATION). | ||
1815 | |||
1816 | @node ID ATTR | ||
1817 | @subsubsection ID ATTR | ||
1818 | |||
1819 | Record type for identity attributes (of IDENTITY). | ||
1820 | |||
1821 | @node ID TOKEN | ||
1822 | @subsubsection ID TOKEN | ||
1823 | |||
1824 | Record type for an identity token (of IDENTITY-TOKEN). | ||
1825 | |||
1826 | @node ID TOKEN METADATA | ||
1827 | @subsubsection ID TOKEN METADATA | ||
1828 | |||
1829 | Record type for the private metadata of an identity token (of IDENTITY-TOKEN). | ||
1830 | |||
1831 | @node CREDENTIAL | ||
1832 | @subsubsection CREDENTIAL | ||
1833 | |||
1834 | Record type for credential. | ||
1835 | |||
1836 | @node POLICY | ||
1837 | @subsubsection POLICY | ||
1838 | |||
1839 | Record type for policies. | ||
1840 | |||
1841 | @node ATTRIBUTE | ||
1842 | @subsubsection ATTRIBUTE | ||
1843 | |||
1844 | Record type for reverse lookups. | ||
1845 | |||
1846 | @node ABE KEY | ||
1847 | @subsubsection ABE KEY | ||
1848 | |||
1849 | Record type for ABE records. | ||
1850 | |||
1851 | @node ABE MASTER | ||
1852 | @subsubsection ABE MASTER | ||
1853 | |||
1854 | Record type for ABE master keys. | ||
1855 | |||
1856 | @node RECLAIM OIDC CLIENT | ||
1857 | @subsubsection RECLAIM OIDC CLIENT | ||
1858 | |||
1859 | Record type for reclaim OIDC clients. | ||
1860 | |||
1861 | @node RECLAIM OIDC REDIRECT | ||
1862 | @subsubsection RECLAIM OIDC REDIRECT | ||
1863 | |||
1864 | Record type for reclaim OIDC redirect URIs. | ||
1865 | |||
1866 | @node Synchronizing with legacy DNS | ||
1867 | @subsection Synchronizing with legacy DNS | ||
1868 | |||
1869 | If you want to support GNS but the master database for a zone | ||
1870 | is only available and maintained in DNS, GNUnet includes the | ||
1871 | @command{gnunet-zoneimport} tool to monitor a DNS zone and | ||
1872 | automatically import records into GNS. Today, the tool does | ||
1873 | not yet support DNS AF(X)R, as we initially used it on the | ||
1874 | ``.fr'' zone which does not allow us to perform a DNS zone | ||
1875 | transfer. Instead, @command{gnunet-zoneimport} reads a list | ||
1876 | of DNS domain names from @code{stdin}, issues DNS queries for | ||
1877 | each, converts the obtained records (if possible) and stores | ||
1878 | the result in the namestore. | ||
1879 | |||
1880 | @image{images/gns,6in,, picture of DNS-GNS data flow} | ||
1881 | |||
1882 | The zonemaster service then takes the records from the namestore, | ||
1883 | publishes them into the DHT which makes the result available to the | ||
1884 | GNS resolver. In the GNS configuration, non-local zones can be | ||
1885 | configured to be intercepted by specifying ``.tld = PUBLICKEY'' in the | ||
1886 | configuration file in the ``[gns]'' section. | ||
1887 | |||
1888 | Note that the namestore by default also populates the namecache. | ||
1889 | This pre-population is cryptographically expensive. Thus, on | ||
1890 | systems that only serve to import a large (millions of records) | ||
1891 | DNS zone and that do not have a local gns service in use, it | ||
1892 | is thus advisable to disable the namecache by setting the | ||
1893 | option ``DISABLE'' to ``YES'' in section ``[namecache]''. | ||
1894 | |||
1895 | |||
1896 | @node re@:claim Identity Provider | ||
1897 | @section re@:claim Identity Provider | ||
1898 | |||
1899 | The re:claim Identity Provider (IdP) is a decentralized IdP service. | ||
1900 | It allows its users to manage and authorize third parties to access their identity attributes such as email or shipping addresses. | ||
1901 | |||
1902 | It basically mimics the concepts of centralized IdPs, such as those offered by Google or Facebook. | ||
1903 | 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. | ||
1904 | |||
1905 | @menu | ||
1906 | * Managing Attributes:: | ||
1907 | * Sharing Attributes with Third Parties:: | ||
1908 | * Revoking Authorizations of Third Parties:: | ||
1909 | * Using the OpenID-Connect IdP:: | ||
1910 | @end menu | ||
1911 | |||
1912 | @node Managing Attributes | ||
1913 | @subsection Managing Attributes | ||
1914 | |||
1915 | Before adding attributes to an identity, you must first create an ego: | ||
1916 | |||
1917 | @example | ||
1918 | $ gnunet-identity -C "username" | ||
1919 | @end example | ||
1920 | |||
1921 | Henceforth, you can manage a new user profile of the user ``username''. | ||
1922 | |||
1923 | To add an email address to your user profile, simply use the @command{gnunet-reclaim} command line tool:: | ||
1924 | |||
1925 | @example | ||
1926 | $ gnunet-reclaim -e "username" -a "email" -V "username@@example.gnunet" | ||
1927 | @end example | ||
1928 | |||
1929 | All of your attributes can be listed using the @command{gnunet-reclaim} | ||
1930 | command line tool as well: | ||
1931 | |||
1932 | @example | ||
1933 | $ gnunet-reclaim -e "username" -D | ||
1934 | @end example | ||
1935 | |||
1936 | Currently, and by default, attribute values are interpreted as plain text. | ||
1937 | In the future there might be more value types such as X.509 certificate credentials. | ||
1938 | |||
1939 | @node Sharing Attributes with Third Parties | ||
1940 | @subsection Sharing Attributes with Third Parties | ||
1941 | |||
1942 | If you want to allow a third party such as a website or friend to access to your attributes (or a subset thereof) execute: | ||
1943 | |||
1944 | @example | ||
1945 | $ gnunet-reclaim -e "username" -r "PKEY" -i "attribute1,attribute2,..." | ||
1946 | @end example | ||
1947 | |||
1948 | 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. | ||
1949 | |||
1950 | The command will return a "ticket" string. | ||
1951 | You must give this "ticket" to the requesting third party. | ||
1952 | |||
1953 | The third party can then retrieve your shared identity attributes using: | ||
1954 | |||
1955 | @example | ||
1956 | $ gnunet-reclaim -e "friend" -C "ticket" | ||
1957 | @end example | ||
1958 | |||
1959 | This will retrieve and list the shared identity attributes. | ||
1960 | The above command will also work if the user "username" is currently offline since the attributes are retrieved from GNS. | ||
1961 | 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. | ||
1962 | |||
1963 | To list all given authorizations (tickets) you can execute: | ||
1964 | @example | ||
1965 | $ gnunet-reclaim -e "friend" -T (TODO there is only a REST API for this ATM) | ||
1966 | @end example | ||
1967 | |||
1968 | |||
1969 | @node Revoking Authorizations of Third Parties | ||
1970 | @subsection Revoking Authorizations of Third Parties | ||
1971 | |||
1972 | If you want to revoke the access of a third party to your attributes you can execute: | ||
1973 | |||
1974 | @example | ||
1975 | $ gnunet-idp -e "username" -R "ticket" | ||
1976 | @end example | ||
1977 | |||
1978 | This will prevent the third party from accessing the attribute in the future. | ||
1979 | 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. | ||
1980 | As such, only access to updated data in the future can be revoked. | ||
1981 | This behaviour is _exactly the same_ as with other IdPs. | ||
1982 | |||
1983 | @node Using the OpenID-Connect IdP | ||
1984 | @subsection Using the OpenID-Connect IdP | ||
1985 | |||
1986 | TODO: Document setup and REST endpoints | ||
1987 | |||
1867 | @node Using the Virtual Public Network | 1988 | @node Using the Virtual Public Network |
1868 | @section Using the Virtual Public Network | 1989 | @section Using the Virtual Public Network |
1869 | 1990 | ||
@@ -2036,7 +2157,7 @@ destination. | |||
2036 | 2157 | ||
2037 | For applications that do not use DNS, you can also manually create | 2158 | For applications that do not use DNS, you can also manually create |
2038 | such a mapping using the gnunet-vpn command-line tool. Here, you | 2159 | such a mapping using the gnunet-vpn command-line tool. Here, you |
2039 | specfiy the desired address family of the result (i.e. "-4"), and the | 2160 | specify the desired address family of the result (i.e. "-4"), and the |
2040 | intended target IP on the Internet ("-i 131.159.74.67") and | 2161 | intended target IP on the Internet ("-i 131.159.74.67") and |
2041 | "gnunet-vpn" will tell you which IP address in the range of your | 2162 | "gnunet-vpn" will tell you which IP address in the range of your |
2042 | VPN tunnel was mapped. | 2163 | VPN tunnel was mapped. |
@@ -2047,3 +2168,5 @@ service offered by that peer, you can create an IP tunnel to | |||
2047 | that peer by specifying the peer's identity, service name and | 2168 | that peer by specifying the peer's identity, service name and |
2048 | protocol (--tcp or --udp) and you will again receive an IP address | 2169 | protocol (--tcp or --udp) and you will again receive an IP address |
2049 | that will terminate at the respective peer's service. | 2170 | that will terminate at the respective peer's service. |
2171 | |||
2172 | |||
diff --git a/doc/documentation/chapters/vocabulary.texi b/doc/documentation/chapters/vocabulary.texi index 85b40b17b..0ee472b95 100644 --- a/doc/documentation/chapters/vocabulary.texi +++ b/doc/documentation/chapters/vocabulary.texi | |||
@@ -18,7 +18,7 @@ which are listed in this introductionary chapter. | |||
18 | @end menu | 18 | @end menu |
19 | 19 | ||
20 | @node Definitions | 20 | @node Definitions |
21 | @subsection Defitions | 21 | @subsection Definitions |
22 | 22 | ||
23 | Throughout this Reference Manual, the following terms and definitions | 23 | Throughout this Reference Manual, the following terms and definitions |
24 | apply. | 24 | apply. |
diff --git a/doc/documentation/gnunet-c-tutorial.texi b/doc/documentation/gnunet-c-tutorial.texi index 7eafa9ea9..fb6e717ae 100644 --- a/doc/documentation/gnunet-c-tutorial.texi +++ b/doc/documentation/gnunet-c-tutorial.texi | |||
@@ -10,7 +10,7 @@ | |||
10 | @include version2.texi | 10 | @include version2.texi |
11 | 11 | ||
12 | @copying | 12 | @copying |
13 | Copyright @copyright{} 2001-2017 GNUnet e.V. | 13 | Copyright @copyright{} 2001-2018 GNUnet e.V. |
14 | 14 | ||
15 | Permission is granted to copy, distribute and/or modify this document | 15 | Permission is granted to copy, distribute and/or modify this document |
16 | under the terms of the GNU Free Documentation License, Version 1.3 or | 16 | under the terms of the GNU Free Documentation License, Version 1.3 or |
@@ -68,9 +68,10 @@ dependencies can be found on our website at | |||
68 | Reference Documentation (GNUnet Handbook). | 68 | Reference Documentation (GNUnet Handbook). |
69 | 69 | ||
70 | Please read this tutorial carefully since every single step is | 70 | Please read this tutorial carefully since every single step is |
71 | important and do not hesitate to contact the GNUnet team if you have | 71 | important, and do not hesitate to contact the GNUnet team if you have |
72 | any questions or problems! Check here how to contact the GNUnet | 72 | any questions or problems! Visit this link in your webbrowser to learn |
73 | team: @uref{https://gnunet.org/contact_information} | 73 | how to contact the GNUnet team: |
74 | @uref{https://gnunet.org/contact_information} | ||
74 | 75 | ||
75 | @menu | 76 | @menu |
76 | 77 | ||
@@ -151,7 +152,7 @@ $ gpg --verify-files gnunet-@value{VERSION}.tar.gz.sig | |||
151 | 152 | ||
152 | @noindent | 153 | @noindent |
153 | If this command fails because you do not have the required public key, | 154 | If this command fails because you do not have the required public key, |
154 | then you need to run this command to import it: | 155 | then you need to run the following command to import it: |
155 | 156 | ||
156 | @example | 157 | @example |
157 | $ gpg --keyserver keys.gnupg.net --recv-keys 48426C7E | 158 | $ gpg --keyserver keys.gnupg.net --recv-keys 48426C7E |
@@ -167,19 +168,22 @@ revoked}. You will get an error message stating that | |||
167 | The next release of GNUnet will have a valid signature | 168 | The next release of GNUnet will have a valid signature |
168 | again. We are sorry for the inconvenience this causes. | 169 | again. We are sorry for the inconvenience this causes. |
169 | Another possible source you could use is our | 170 | Another possible source you could use is our |
170 | "gnunet" git repository which has mandatory signed commits | 171 | "gnunet" git repository which, since the change from SVN to git in 2016, |
171 | by every developer. | 172 | has mandatory signed commits by every developer. |
172 | 173 | ||
173 | Now you can extract the tarball and rename the resulting | 174 | After verifying the signature you can extract the tarball. |
174 | directory to @file{gnunet} which we will be using in the | 175 | The resulting directory will be renamed to @file{gnunet}, which we will |
175 | remainder of this document. | 176 | be using in the remainder of this document to refer to the |
177 | root of the source directory. | ||
176 | 178 | ||
177 | @example | 179 | @example |
178 | $ tar xvzf gnunet-@value{VERSION}.tar.gz | 180 | $ tar xvzf gnunet-@value{VERSION}.tar.gz |
179 | $ mv gnunet-@value{VERSION} gnunet | 181 | $ mv gnunet-@value{VERSION} gnunet |
180 | $ cd gnunet | ||
181 | @end example | 182 | @end example |
182 | 183 | ||
184 | @c FIXME: This can be irritating for the reader - First we say git should | ||
185 | @c be avoid unless it is really required, and then we write this | ||
186 | @c paragraph: | ||
183 | @noindent | 187 | @noindent |
184 | However, please note that stable versions can be very outdated. | 188 | However, please note that stable versions can be very outdated. |
185 | As a developer you are @b{strongly} encouraged to use the version | 189 | As a developer you are @b{strongly} encouraged to use the version |
@@ -192,32 +196,40 @@ To successfully compile GNUnet, you need the tools to build GNUnet and | |||
192 | the required dependencies. Please take a look at the | 196 | the required dependencies. Please take a look at the |
193 | GNUnet Reference Documentation | 197 | GNUnet Reference Documentation |
194 | (@pxref{Dependencies, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation}) | 198 | (@pxref{Dependencies, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation}) |
195 | for a list of required dependencies | 199 | for a list of required dependencies and |
196 | and | ||
197 | (@pxref{Generic installation instructions, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation}) | 200 | (@pxref{Generic installation instructions, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation}) |
198 | read its Installation chapter for specific instructions for | 201 | read its Installation chapter for specific instructions for |
199 | your operating system. | 202 | your Operating System. |
200 | Please check the notes at the end of the configure process about | 203 | Please check the notes at the end of the configure process about |
201 | required dependencies. | 204 | required dependencies. |
202 | 205 | ||
203 | For GNUnet bootstrapping support and the HTTP(S) plugin you should | 206 | For GNUnet bootstrapping support and the HTTP(S) plugin you should |
204 | install @uref{https://gnunet.org/gnurl, libgnurl}. | 207 | install @uref{https://gnunet.org/gnurl, libgnurl}. |
205 | For the filesharing service you should install at least one of the | 208 | For the filesharing service you should install at least one of the |
206 | datastore backends. MySQL, SQlite and PostgreSQL are supported. | 209 | datastore backends (MySQL, SQlite and PostgreSQL are supported). |
207 | 210 | ||
208 | @node Obtaining the latest version from Git | 211 | @node Obtaining the latest version from Git |
209 | @section Obtaining the latest version from Git | 212 | @section Obtaining the latest version from Git |
210 | 213 | ||
211 | The latest development version can obtained from our Git repository. | 214 | The latest development version can be obtained from our Git repository. |
212 | To obtain the code you need to have @code{Git} installed, which is | 215 | To get the code you need to have @code{Git} installed. Usually your |
213 | required for obtaining the repository via: | 216 | Operating System package manager should provide a suitable distribution |
217 | of git (otherwise check out Guix or Nix). If you are using an Operating | ||
218 | System based on Debian's apt: | ||
219 | |||
220 | @example | ||
221 | $ sudo apt-get install git | ||
222 | @end example | ||
223 | |||
224 | This is required for obtaining the repository, which is achieved with | ||
225 | the following command: | ||
214 | 226 | ||
215 | @example | 227 | @example |
216 | $ git clone https://gnunet.org/git/gnunet | 228 | $ git clone https://gnunet.org/git/gnunet |
217 | @end example | 229 | @end example |
218 | 230 | ||
219 | @noindent | 231 | @noindent |
220 | After cloning the repository you have to execute the @file{bootstrap} | 232 | After cloning the repository, you have to execute the @file{bootstrap} |
221 | script in the new directory: | 233 | script in the new directory: |
222 | 234 | ||
223 | @example | 235 | @example |
@@ -275,6 +287,7 @@ you do not specifiy a prefix, GNUnet is installed in the directory | |||
275 | to enable verbose logging by adding @code{--enable-logging=verbose}: | 287 | to enable verbose logging by adding @code{--enable-logging=verbose}: |
276 | 288 | ||
277 | @example | 289 | @example |
290 | $ export PREFIX=$HOME | ||
278 | $ ./configure --prefix=$PREFIX --enable-logging | 291 | $ ./configure --prefix=$PREFIX --enable-logging |
279 | $ make | 292 | $ make |
280 | $ make install | 293 | $ make install |
@@ -303,11 +316,14 @@ binaries and run GNUnet's self check. | |||
303 | 316 | ||
304 | @example | 317 | @example |
305 | $ which gnunet-arm | 318 | $ which gnunet-arm |
319 | $PREFIX/bin/gnunet-arm | ||
306 | @end example | 320 | @end example |
307 | 321 | ||
308 | @noindent | 322 | @noindent |
309 | should return $PREFIX/bin/gnunet-arm. It should be located in your | 323 | should return $PREFIX/bin/gnunet-arm (where $PREFIX is the location |
324 | you have set earlier). It should be located in your | ||
310 | GNUnet installation and the output should not be empty. | 325 | GNUnet installation and the output should not be empty. |
326 | |||
311 | If you see an output like: | 327 | If you see an output like: |
312 | 328 | ||
313 | @example | 329 | @example |
@@ -318,9 +334,11 @@ $ which gnunet-arm | |||
318 | check your PATH variable to ensure GNUnet's @file{bin} directory is | 334 | check your PATH variable to ensure GNUnet's @file{bin} directory is |
319 | included. | 335 | included. |
320 | 336 | ||
321 | GNUnet provides tests for all of its subcomponents. Run | 337 | GNUnet provides tests for all of its subcomponents. Assuming you have |
338 | successfully built GNUnet, run | ||
322 | 339 | ||
323 | @example | 340 | @example |
341 | $ cd gnunet | ||
324 | $ make check | 342 | $ make check |
325 | @end example | 343 | @end example |
326 | 344 | ||
@@ -387,7 +405,7 @@ a mesh on top of a DHT). | |||
387 | @c \end{figure} | 405 | @c \end{figure} |
388 | 406 | ||
389 | The main service implementation runs as a standalone process in the | 407 | The main service implementation runs as a standalone process in the |
390 | operating system and the client code runs as part of the client program, | 408 | Operating System and the client code runs as part of the client program, |
391 | so crashes of a client do not affect the service process or other clients. | 409 | so crashes of a client do not affect the service process or other clients. |
392 | The service and the clients communicate via a message protocol to be | 410 | The service and the clients communicate via a message protocol to be |
393 | defined and implemented by the programmer. | 411 | defined and implemented by the programmer. |
@@ -629,7 +647,7 @@ If you want to use the @code{peerinfo} tool to connect your | |||
629 | peers, you should: | 647 | peers, you should: |
630 | 648 | ||
631 | @itemize | 649 | @itemize |
632 | @item Set @code{FORCESTART = NO} in section @code{hostlist} | 650 | @item Set @code{IMMEDIATE_START = NO} in section @code{hostlist} |
633 | (to not connect to the global GNUnet) | 651 | (to not connect to the global GNUnet) |
634 | @item Start both peers running @command{gnunet-arm -c peer1.conf -s} | 652 | @item Start both peers running @command{gnunet-arm -c peer1.conf -s} |
635 | and @command{gnunet-arm -c peer2.conf -s} | 653 | and @command{gnunet-arm -c peer2.conf -s} |
diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi index 2cd72373b..50630d4fe 100644 --- a/doc/documentation/gnunet.texi +++ b/doc/documentation/gnunet.texi | |||
@@ -43,6 +43,14 @@ Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}. | |||
43 | @end copying | 43 | @end copying |
44 | 44 | ||
45 | @c TODO: Improve this and improve https://directory.fsf.org/wiki/Gnunet | 45 | @c TODO: Improve this and improve https://directory.fsf.org/wiki/Gnunet |
46 | @c NOTE FOR TRANSLATORS: Due to en.wikipedia.org being the wikipedia | ||
47 | @c which is more up to date than others, refrain | ||
48 | @c from using localized wikipedia unless you are | ||
49 | @c sure the articles content is good enough. For | ||
50 | @c example the german wikipedia entry for GNUnet | ||
51 | @c is in a terrible shape, but the en.wikipedia.org | ||
52 | @c entry is still acceptable (although in need of | ||
53 | @c updates). | ||
46 | 54 | ||
47 | @dircategory Networking | 55 | @dircategory Networking |
48 | @direntry | 56 | @direntry |
@@ -72,34 +80,39 @@ This document is the Reference Manual for GNUnet version @value{VERSION}. | |||
72 | 80 | ||
73 | @menu | 81 | @menu |
74 | 82 | ||
75 | * Terminology:: Terminology used throughout the Manual | 83 | * Preface:: Chapter 0 |
76 | * Philosophy:: About GNUnet | 84 | * Philosophy:: About GNUnet |
85 | * Key Concepts:: Key concepts of GNUnet | ||
77 | @c * Vocabulary:: Vocabulary | 86 | @c * Vocabulary:: Vocabulary |
78 | * GNUnet Installation Handbook:: How to install GNUnet | 87 | * Installing GNUnet:: Installing GNUnet |
79 | * Using GNUnet:: Using GNUnet | 88 | * Using GNUnet:: Using GNUnet |
80 | @c * Configuration Handbook:: Configuring GNUnet | 89 | @c * Configuration Handbook:: Configuring GNUnet |
81 | * GNUnet Contributors Handbook:: Contributing to GNUnet | 90 | * GNUnet Contributors Handbook:: Contributing to GNUnet |
82 | * GNUnet Developer Handbook:: Developing GNUnet | 91 | * GNUnet Developer Handbook:: Developing GNUnet |
83 | * GNU Free Documentation License:: The license of this manual | 92 | * GNU Free Documentation License:: The license of this manual |
84 | * GNU General Public License:: The license of this manual | 93 | * GNU General Public License:: |
94 | * GNU Affero General Public License:: | ||
85 | * Concept Index:: Concepts | 95 | * Concept Index:: Concepts |
86 | * Programming Index:: Data types, functions, and variables | 96 | * Programming Index:: Data types, functions, and variables |
87 | 97 | ||
88 | @detailmenu | 98 | @detailmenu |
89 | --- The Detailed Node Listing --- | 99 | --- The Detailed Node Listing --- |
90 | 100 | ||
91 | Terminology | 101 | Preface |
92 | 102 | ||
93 | * General Terminology:: | 103 | * About this book |
104 | * Contributing to this book | ||
105 | * Introduction | ||
94 | * Typography:: | 106 | * Typography:: |
95 | 107 | ||
96 | Philosophy | 108 | Philosophy |
97 | 109 | ||
98 | * Design Goals:: | 110 | * Design Principles:: |
99 | * Security and Privacy:: | 111 | * Privacy and Anonymity:: |
100 | * Versatility:: | ||
101 | * Practicality:: | 112 | * Practicality:: |
102 | * Key Concepts:: | 113 | |
114 | Key Concepts | ||
115 | |||
103 | * Authentication:: | 116 | * Authentication:: |
104 | * Accounting to Encourage Resource Sharing:: | 117 | * Accounting to Encourage Resource Sharing:: |
105 | * Confidentiality:: | 118 | * Confidentiality:: |
@@ -111,32 +124,19 @@ Philosophy | |||
111 | * Backup of Identities and Egos:: | 124 | * Backup of Identities and Egos:: |
112 | * Revocation:: | 125 | * Revocation:: |
113 | 126 | ||
114 | @c Vocabulary | 127 | Installing GNUnet |
115 | @c | 128 | * Installing dependencies:: |
116 | @c * Definitions abbreviations and acronyms:: | 129 | * Getting the Source Code:: |
117 | @c * Words and characters:: | 130 | * Create @code{gnunet} user and group:: |
118 | @c * Technical Assumptions:: | 131 | * Preparing and Compiling the Source Code:: |
119 | 132 | * Installation:: | |
120 | GNUnet Installation Handbook | 133 | * MOVED FROM USER Checking the Installation:: |
121 | 134 | * MOVED FROM USER The graphical configuration interface:: | |
122 | * Dependencies:: | 135 | * MOVED FROM USER Config Leftovers:: |
123 | * Pre-installation notes:: | ||
124 | * Generic installation instructions:: | ||
125 | * Build instructions for Ubuntu 12.04 using Git:: | ||
126 | * Build instructions for software builds from source:: | ||
127 | * Build Instructions for Microsoft Windows Platforms:: | ||
128 | * Build instructions for Debian 7.5:: | ||
129 | * Installing GNUnet from Git on Ubuntu 14.4:: | ||
130 | * Build instructions for Debian 8:: | ||
131 | * Outdated build instructions for previous revisions:: | ||
132 | @c * Portable GNUnet:: | ||
133 | * The graphical configuration interface:: | ||
134 | * How to start and stop a GNUnet peer:: | ||
135 | 136 | ||
136 | Using GNUnet | 137 | Using GNUnet |
137 | 138 | ||
138 | * Checking the Installation:: | 139 | * Start and stop GNUnet:: |
139 | * First steps - File-sharing:: | ||
140 | * First steps - Using the GNU Name System:: | 140 | * First steps - Using the GNU Name System:: |
141 | * First steps - Using GNUnet Conversation:: | 141 | * First steps - Using GNUnet Conversation:: |
142 | * First steps - Using the GNUnet VPN:: | 142 | * First steps - Using the GNUnet VPN:: |
@@ -144,18 +144,18 @@ Using GNUnet | |||
144 | * The GNU Name System:: | 144 | * The GNU Name System:: |
145 | * Using the Virtual Public Network:: | 145 | * Using the Virtual Public Network:: |
146 | 146 | ||
147 | @c Configuration Handbook | ||
148 | |||
149 | GNUnet Contributors Handbook | 147 | GNUnet Contributors Handbook |
150 | 148 | ||
151 | * Contributing to GNUnet:: | 149 | * Contributing to GNUnet:: |
152 | * Licenses of contributions:: | 150 | * Licenses of contributions:: |
153 | * Copyright Assignment:: | 151 | * Copyright Assignment:: |
154 | * Contributing to the Reference Manual:: | 152 | * Contributing to the Reference Manual:: |
153 | * Contributing testcases:: | ||
155 | 154 | ||
156 | GNUnet Developer Handbook | 155 | GNUnet Developer Handbook |
157 | 156 | ||
158 | * Developer Introduction:: | 157 | * Developer Introduction:: |
158 | * Internal dependencies:: | ||
159 | * Code overview:: | 159 | * Code overview:: |
160 | * System Architecture:: | 160 | * System Architecture:: |
161 | * Subsystem stability:: | 161 | * Subsystem stability:: |
@@ -163,6 +163,7 @@ GNUnet Developer Handbook | |||
163 | * Build-system:: | 163 | * Build-system:: |
164 | * Developing extensions for GNUnet using the gnunet-ext template:: | 164 | * Developing extensions for GNUnet using the gnunet-ext template:: |
165 | * Writing testcases:: | 165 | * Writing testcases:: |
166 | * Building GNUnet and its dependencies:: | ||
166 | * TESTING library:: | 167 | * TESTING library:: |
167 | * Performance regression analysis with Gauger:: | 168 | * Performance regression analysis with Gauger:: |
168 | * TESTBED Subsystem:: | 169 | * TESTBED Subsystem:: |
@@ -196,15 +197,16 @@ GNUnet Developer Handbook | |||
196 | @end menu | 197 | @end menu |
197 | 198 | ||
198 | @c ********************************************************************* | 199 | @c ********************************************************************* |
199 | @include chapters/terminology.texi | 200 | @include chapters/preface.texi |
200 | @c ********************************************************************* | 201 | @c ********************************************************************* |
201 | 202 | ||
202 | @c ********************************************************************* | 203 | @c ********************************************************************* |
203 | @include chapters/philosophy.texi | 204 | @include chapters/philosophy.texi |
204 | @c ********************************************************************* | 205 | @c ********************************************************************* |
205 | 206 | ||
206 | @c WIP: | 207 | @c ********************************************************************* |
207 | @c @include chapters/vocabulary.texi | 208 | @include chapters/keyconcepts.texi |
209 | @c ********************************************************************* | ||
208 | 210 | ||
209 | @c ********************************************************************* | 211 | @c ********************************************************************* |
210 | @include chapters/installation.texi | 212 | @include chapters/installation.texi |
@@ -214,9 +216,6 @@ GNUnet Developer Handbook | |||
214 | @include chapters/user.texi | 216 | @include chapters/user.texi |
215 | @c ********************************************************************* | 217 | @c ********************************************************************* |
216 | 218 | ||
217 | @c WIP: | ||
218 | @c @include chapters/configuration.texi | ||
219 | |||
220 | @include chapters/contributing.texi | 219 | @include chapters/contributing.texi |
221 | 220 | ||
222 | @c ********************************************************************* | 221 | @c ********************************************************************* |
@@ -238,6 +237,12 @@ GNUnet Developer Handbook | |||
238 | @include gpl-3.0.texi | 237 | @include gpl-3.0.texi |
239 | 238 | ||
240 | @c ********************************************************************* | 239 | @c ********************************************************************* |
240 | @node GNU Affero General Public License | ||
241 | @appendix GNU Affero General Public License | ||
242 | @cindex license, GNU Affero General Public License | ||
243 | @include agpl-3.0.texi | ||
244 | |||
245 | @c ********************************************************************* | ||
241 | @node Concept Index | 246 | @node Concept Index |
242 | @unnumbered Concept Index | 247 | @unnumbered Concept Index |
243 | @printindex cp | 248 | @printindex cp |
@@ -246,6 +251,7 @@ GNUnet Developer Handbook | |||
246 | @unnumbered Programming Index | 251 | @unnumbered Programming Index |
247 | @syncodeindex tp fn | 252 | @syncodeindex tp fn |
248 | @syncodeindex vr fn | 253 | @syncodeindex vr fn |
254 | @syncodeindex pg fn | ||
249 | @printindex fn | 255 | @printindex fn |
250 | 256 | ||
251 | @bye | 257 | @bye |
diff --git a/doc/documentation/images/gns.dot b/doc/documentation/images/gns.dot new file mode 100644 index 000000000..55b05d482 --- /dev/null +++ b/doc/documentation/images/gns.dot | |||
@@ -0,0 +1,42 @@ | |||
1 | // house = interface towards application | ||
2 | // circle (default) = storage | ||
3 | // diamond = stateless tool | ||
4 | // box = legacy system | ||
5 | |||
6 | // this is what we have...o | ||
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 new file mode 100644 index 000000000..3f3c28d98 --- /dev/null +++ b/doc/documentation/images/gns.eps | |||
@@ -0,0 +1,585 @@ | |||
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 new file mode 100644 index 000000000..d71109b95 --- /dev/null +++ b/doc/documentation/images/gns.jpg | |||
Binary files differ | |||
diff --git a/doc/documentation/images/gnunet-gtk-0-10.png b/doc/documentation/images/gnunet-gtk-0-10.png deleted file mode 100644 index 3615849a7..000000000 --- a/doc/documentation/images/gnunet-gtk-0-10.png +++ /dev/null | |||
Binary files differ | |||
diff --git a/doc/documentation/tutorial-examples/005.c b/doc/documentation/tutorial-examples/005.c index 0c459f509..1b59f85a6 100644 --- a/doc/documentation/tutorial-examples/005.c +++ b/doc/documentation/tutorial-examples/005.c | |||
@@ -2,7 +2,8 @@ struct GNUNET_MQ_Envelope *env; | |||
2 | struct GNUNET_MessageHeader *msg; | 2 | struct GNUNET_MessageHeader *msg; |
3 | 3 | ||
4 | env = GNUNET_MQ_msg_extra (msg, payload_size, GNUNET_MY_MESSAGE_TYPE); | 4 | env = GNUNET_MQ_msg_extra (msg, payload_size, GNUNET_MY_MESSAGE_TYPE); |
5 | memcpy (&msg[1], &payload, payload_size); | 5 | GNUNET_memcpy (&msg[1], |
6 | &payload, | ||
7 | payload_size); | ||
6 | // Send message via message queue 'mq' | 8 | // Send message via message queue 'mq' |
7 | GNUNET_mq_send (mq, env); | 9 | GNUNET_mq_send (mq, env); |
8 | |||
diff --git a/doc/hacks.el b/doc/hacks.el deleted file mode 100644 index 9f271b3af..000000000 --- a/doc/hacks.el +++ /dev/null | |||
@@ -1,17 +0,0 @@ | |||
1 | ;;;; hacks.el --- a few functions to help me work on the manual | ||
2 | ;;;; Jim Blandy <jimb@red-bean.com> --- October 1998 | ||
3 | ;;;; -- imported from https://git.savannah.gnu.org/cgit/guile.git/tree/doc/hacks.el | ||
4 | |||
5 | (defun jh-exemplify-region (start end) | ||
6 | (interactive "r") | ||
7 | (save-excursion | ||
8 | (save-restriction | ||
9 | (narrow-to-region start end) | ||
10 | |||
11 | ;; Texinfo doesn't handle tabs well. | ||
12 | (untabify (point-min) (point-max)) | ||
13 | |||
14 | ;; Quote any characters special to texinfo. | ||
15 | (goto-char (point-min)) | ||
16 | (while (re-search-forward "[{}@]" nil t) | ||
17 | (replace-match "@\\&"))))) | ||
diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index a6a116dca..37f881d60 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am | |||
@@ -37,6 +37,7 @@ man_MANS = \ | |||
37 | gnunet-statistics.1 \ | 37 | gnunet-statistics.1 \ |
38 | gnunet-testbed-profiler.1 \ | 38 | gnunet-testbed-profiler.1 \ |
39 | gnunet-testing-run-service.1 \ | 39 | gnunet-testing-run-service.1 \ |
40 | gnunet-timeout.1 \ | ||
40 | gnunet-transport.1 \ | 41 | gnunet-transport.1 \ |
41 | gnunet-transport-certificate-creation.1 \ | 42 | gnunet-transport-certificate-creation.1 \ |
42 | gnunet-unindex.1 \ | 43 | gnunet-unindex.1 \ |
diff --git a/doc/man/gnunet-arm.1 b/doc/man/gnunet-arm.1 index b591f0ad7..099978f24 100644 --- a/doc/man/gnunet-arm.1 +++ b/doc/man/gnunet-arm.1 | |||
@@ -9,7 +9,10 @@ gnunet\-arm \- control GNUnet services | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-arm\fP can be used to start or stop GNUnet services, including the ARM service itself. The ARM service is a supervisor for GNUnet's service processes. ARM starts services on-demand or as configured and re-starts them if they crash. | 12 | \fBgnunet\-arm\fP can be used to start or stop GNUnet services, including |
13 | the ARM service itself. The ARM service is a supervisor for GNUnet's | ||
14 | service processes. ARM starts services on-demand or as configured and | ||
15 | re-starts them if they crash. | ||
13 | 16 | ||
14 | .SH OPTIONS | 17 | .SH OPTIONS |
15 | .B | 18 | .B |
@@ -17,7 +20,8 @@ gnunet\-arm \- control GNUnet services | |||
17 | Use the configuration file FILENAME. | 20 | Use the configuration file FILENAME. |
18 | .B | 21 | .B |
19 | .IP "\-e, \-\-end" | 22 | .IP "\-e, \-\-end" |
20 | Shutdown all GNUnet services (including ARM itself). Running "gnunet-arm \-e" is the usual way to shutdown a GNUnet peer. | 23 | Shutdown all GNUnet services (including ARM itself). Running |
24 | "gnunet-arm \-e" is the usual way to shutdown a GNUnet peer. | ||
21 | .B | 25 | .B |
22 | .IP "\-h, \-\-help" | 26 | .IP "\-h, \-\-help" |
23 | Print short help on options. | 27 | Print short help on options. |
@@ -26,16 +30,25 @@ Print short help on options. | |||
26 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 30 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. |
27 | .B | 31 | .B |
28 | .IP "\-i SERVICE, \-\-init=SERVICE" | 32 | .IP "\-i SERVICE, \-\-init=SERVICE" |
29 | Starts the specified SERVICE if it is not already running. More specifically, this makes the service behave as if it were in the default services list. | 33 | Starts the specified SERVICE if it is not already running. More specifically, |
34 | this makes the service behave as if it were in the default services list. | ||
30 | .B | 35 | .B |
31 | .IP "\-k SERVICE, \-\-kill=SERVICE" | 36 | .IP "\-k SERVICE, \-\-kill=SERVICE" |
32 | Stop the specified SERVICE if it is running. While this will kill the service right now, the service may be restarted immediately if other services depend on it (service is then started 'on-demand'). If the service used to be a 'default' service, its default-service status will be revoked. If the service was not a default service, it will just be (temporarily) stopped, but could be re-started on-demand at any time. | 37 | Stop the specified SERVICE if it is running. While this will kill the service |
38 | right now, the service may be restarted immediately if other services depend | ||
39 | on it (service is then started 'on-demand'). If the service used to be a 'default' | ||
40 | service, its default-service status will be revoked. If the | ||
41 | service was not a default service, it will just be (temporarily) stopped, | ||
42 | but could be re-started on-demand at any time. | ||
33 | .B | 43 | .B |
34 | .IP "\-m, \-\-monitor" | 44 | .IP "\-m, \-\-monitor" |
35 | Monitor service activity of ARM. In this mode, the command will not terminate until the user presses CTRL-C. | 45 | Monitor service activity of ARM. In this mode, the command will not terminate |
46 | until the user presses CTRL-C. | ||
36 | .B | 47 | .B |
37 | .IP "\-s, \-\-start" | 48 | .IP "\-s, \-\-start" |
38 | Start all GNUnet default services on this system (and also ARM). Naturally, if a service is demanded by a default service, it will then also be started. Running "gnunet-arm \-s" is the usual way to start a GNUnet peer. | 49 | Start all GNUnet default services on this system (and also ARM). Naturally, |
50 | if a service is demanded by a default service, it will then also be started. | ||
51 | Running "gnunet-arm \-s" is the usual way to start a GNUnet peer. | ||
39 | .B | 52 | .B |
40 | .IP "\-I, \-\-info" | 53 | .IP "\-I, \-\-info" |
41 | List all running services. | 54 | List all running services. |
@@ -45,7 +58,8 @@ Print GNUnet version number. | |||
45 | 58 | ||
46 | 59 | ||
47 | .SH BUGS | 60 | .SH BUGS |
48 | Report bugs by using Mantis <https://gnunet.org/bugs/> or by sending electronic mail to <gnunet\-developers@gnu.org> | 61 | Report bugs by using Mantis <https://gnunet.org/bugs/> or by sending |
62 | electronic mail to <gnunet\-developers@gnu.org> | ||
49 | 63 | ||
50 | .SH SEE ALSO | 64 | .SH SEE ALSO |
51 | gnunet\-config(1), gnunet\-setup(1) | 65 | gnunet\-config(1), gnunet\-setup(1) |
diff --git a/doc/man/gnunet-ats.1 b/doc/man/gnunet-ats.1 index e0546f53e..cac55e79f 100644 --- a/doc/man/gnunet-ats.1 +++ b/doc/man/gnunet-ats.1 | |||
@@ -62,7 +62,8 @@ Print verbose output (include ATS address properties) | |||
62 | Print GNUnet version number. | 62 | Print GNUnet version number. |
63 | 63 | ||
64 | .SH BUGS | 64 | .SH BUGS |
65 | Report bugs by using Mantis <https://gnunet.org/bugs/> or by sending electronic mail to <bug\-gnunet@gnu.org> | 65 | Report bugs by using Mantis <https://gnunet.org/bugs/> or by sending |
66 | electronic mail to <bug\-gnunet@gnu.org> | ||
66 | 67 | ||
67 | .SH SEE ALSO | 68 | .SH SEE ALSO |
68 | gnunet\-transport(1) | 69 | gnunet\-transport(1) |
diff --git a/doc/man/gnunet-auto-share.1 b/doc/man/gnunet-auto-share.1 index dd3d93611..fc2668d44 100644 --- a/doc/man/gnunet-auto-share.1 +++ b/doc/man/gnunet-auto-share.1 | |||
@@ -6,13 +6,22 @@ gnunet\-auto\-share \- a command line tool to automatically share an entire dire | |||
6 | [\fIOPTIONS\fR] DIRNAME | 6 | [\fIOPTIONS\fR] DIRNAME |
7 | .SH DESCRIPTION | 7 | .SH DESCRIPTION |
8 | .PP | 8 | .PP |
9 | In order to share files with other GNUnet users, the files must first be made available to GNUnet. This tool can be used to automatically share all files from a certain directory. The program will periodically scan the directory for changes and publish files that are new or that changed on GNUnet. Which files have already been shared is remembered in a ".auto-share" file in the shared directory. You can run the tool by hand or automatically by adding the respective options to your configuration. gnunet\-auto\-share has many options in common with gnunet\-publish, but can only be used to index files. | 9 | In order to share files with other GNUnet users, the files must first be made |
10 | available to GNUnet. This tool can be used to automatically share all files | ||
11 | from a certain directory. The program will periodically scan the directory | ||
12 | for changes and publish files that are new or that changed on GNUnet. | ||
13 | Which files have already been shared is remembered in a ".auto-share" file | ||
14 | in the shared directory. You can run the tool by hand or automatically by | ||
15 | adding the respective options to your configuration. gnunet\-auto\-share | ||
16 | has many options in common with gnunet\-publish, but can only be used to | ||
17 | index files. | ||
10 | .PP | 18 | .PP |
11 | You can use automatic meta\-data extraction (based on libextractor). | 19 | You can use automatic meta\-data extraction (based on libextractor). |
12 | .PP | 20 | .PP |
13 | 21 | ||
14 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR | 22 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR |
15 | Use alternate config file (if this option is not specified, the default is ~/.config/gnunet.conf). | 23 | Use alternate config file (if this option is not specified, the |
24 | default is ~/.config/gnunet.conf). | ||
16 | 25 | ||
17 | .TP | 26 | .TP |
18 | \fB\-D\fR, \fB\-\-disable\-extractor\fR | 27 | \fB\-D\fR, \fB\-\-disable\-extractor\fR |
@@ -31,11 +40,20 @@ ERROR, WARNING, INFO and DEBUG. | |||
31 | \fB\-p \fIPRIORITY\fR, \fB\-\-prio=\fIPRIORITY\fR | 40 | \fB\-p \fIPRIORITY\fR, \fB\-\-prio=\fIPRIORITY\fR |
32 | Executive summary: You probably don't need it. | 41 | Executive summary: You probably don't need it. |
33 | 42 | ||
34 | Set the priority of the published content (default: 365). If the local database is full, GNUnet will discard the content with the lowest ranking. Note that ranks change over time depending on popularity. The default should be high enough to preserve the locally published content in favor of content that migrates from other peers. | 43 | Set the priority of the published content (default: 365). If the local |
44 | database is full, GNUnet will discard the content with the lowest ranking. | ||
45 | Note that ranks change over time depending on popularity. The default | ||
46 | should be high enough to preserve the locally published content in favor | ||
47 | of content that migrates from other peers. | ||
35 | 48 | ||
36 | .TP | 49 | .TP |
37 | \fB\-r \fILEVEL\fR, \fB\-\-replication=\fILEVEL\fR | 50 | \fB\-r \fILEVEL\fR, \fB\-\-replication=\fILEVEL\fR |
38 | Set the desired replication level. If CONTENT_PUSHING is set to YES, GNUnet will push each block (for the file) LEVEL times to other peers before doing normal "random" replication of all content. This option can be used to push some content out into the network harder. Note that pushing content LEVEL times into the network does not guarantee that there will actually be LEVEL replicas. | 51 | Set the desired replication level. If CONTENT_PUSHING is set to YES, GNUnet |
52 | will push each block (for the file) LEVEL times to other peers before doing | ||
53 | normal "random" replication of all content. This option can be used to push | ||
54 | some content out into the network harder. Note that pushing content LEVEL | ||
55 | times into the network does not guarantee that there will actually be LEVEL | ||
56 | replicas. | ||
39 | 57 | ||
40 | .TP | 58 | .TP |
41 | \fB\-v\fR, \fB\-\-version\fR | 59 | \fB\-v\fR, \fB\-\-version\fR |
@@ -43,16 +61,38 @@ Print the version number. | |||
43 | 61 | ||
44 | .TP | 62 | .TP |
45 | \fB\-V\fR, \fB\-\-verbose\fR | 63 | \fB\-V\fR, \fB\-\-verbose\fR |
46 | Be verbose. Using this option causes gnunet\-publish to print progress information and at the end the file identification that can be used to download the file from GNUnet. | 64 | Be verbose. Using this option causes gnunet\-publish to print progress |
65 | information and at the end the file identification that can be used to download | ||
66 | the file from GNUnet. | ||
47 | 67 | ||
48 | 68 | ||
49 | .SH SETTING ANONYMITY LEVEL | 69 | .SH SETTING ANONYMITY LEVEL |
50 | 70 | ||
51 | The \fB\-a\fR option can be used to specify additional anonymity constraints. If set to 0, GNUnet will publish the file non-anonymously and in fact sign the advertisement for the file using your peer's private key. This will allow other users to download the file as fast as possible, including using non-anonymous methods (DHT, direct transfer). If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity. You can gain better privacy by specifying a higher level of anonymity, which increases the amount of cover traffic your own traffic will get, at the expense of performance. Note that regardless of the anonymity level you choose, peers that cache content in the network always use anonymity level 1. | 71 | The \fB\-a\fR option can be used to specify additional anonymity constraints. |
52 | 72 | If set to 0, GNUnet will publish the file non-anonymously and in fact sign | |
53 | The definition of the ANONYMITY LEVEL is the following. 0 means no anonymity is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" traffic can be from the local user, leaving 'v-1' bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign peers (using anonymous routing), it may originate n/(v-1) bytes of data in the same time\-period. The time\-period is twice the average delay that GNUnet defers forwarded queries. | 73 | the advertisement for the file using your peer's private key. This will |
54 | 74 | allow other users to download the file as fast as possible, including using | |
55 | The default is 1 and this should be fine for most users. Also notice that if you choose very large values, you may end up having no throughput at all, especially if many of your fellow GNUnet\-peers all do the same. | 75 | non-anonymous methods (DHT, direct transfer). If you set it to 1 (default), |
76 | you use the standard anonymous routing algorithm (which does not explicitly | ||
77 | leak your identity). However, a powerful adversary may still be able to | ||
78 | perform traffic analysis (statistics) to over time infer data about your | ||
79 | identity. You can gain better privacy by specifying a higher level of | ||
80 | anonymity, which increases the amount of cover traffic your own traffic will | ||
81 | get, at the expense of performance. Note that regardless of the anonymity | ||
82 | level you choose, peers that cache content in the network always use anonymity | ||
83 | level 1. | ||
84 | |||
85 | The definition of the ANONYMITY LEVEL is the following. 0 means no anonymity | ||
86 | is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" | ||
87 | traffic can be from the local user, leaving 'v-1' bytes of cover traffic per | ||
88 | byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign | ||
89 | peers (using anonymous routing), it may originate n/(v-1) bytes of data in | ||
90 | the same time\-period. The time\-period is twice the average delay that | ||
91 | GNUnet defers forwarded queries. | ||
92 | |||
93 | The default is 1 and this should be fine for most users. Also notice that if | ||
94 | you choose very large values, you may end up having no throughput at all, | ||
95 | especially if many of your fellow GNUnet\-peers all do the same. | ||
56 | 96 | ||
57 | 97 | ||
58 | .SH EXAMPLES | 98 | .SH EXAMPLES |
@@ -71,7 +111,7 @@ Share a directory "$HOME/gnunet\-share/": | |||
71 | 111 | ||
72 | [gnunet-auto-share] | 112 | [gnunet-auto-share] |
73 | OPTIONS = $HOME/gnunet\-share | 113 | OPTIONS = $HOME/gnunet\-share |
74 | FORCESTART = YES # start this service when the peer starts | 114 | IMMEDIATE_START = YES # start this service when the peer starts |
75 | 115 | ||
76 | .SH FILES | 116 | .SH FILES |
77 | .TP | 117 | .TP |
diff --git a/doc/man/gnunet-bcd.1 b/doc/man/gnunet-bcd.1 index 3f695c072..f23196687 100644 --- a/doc/man/gnunet-bcd.1 +++ b/doc/man/gnunet-bcd.1 | |||
@@ -9,7 +9,12 @@ gnunet\-bcd \- run HTTP server to create GNS business cards | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-bcd\fP can be used to create an business card with a QR code containing the public key of a zone from the GNU Name System. gnunet\-bcd requires LaTeX (pdflatex) with various packages to be installed. If it does not work for you, try installing the full TeXLive distribution first (i.e. "apt-get install texlive-full"). | 12 | \fBgnunet\-bcd\fP can be used to create an business card with a QR code |
13 | containing the public key of a zone from the GNU Name System. | ||
14 | gnunet\-bcd requires LaTeX (pdflatex) with various packages to be | ||
15 | installed. If it does not work for you, try installing the full | ||
16 | TeXLive distribution first, for example using the package\-manager | ||
17 | apt: "apt-get install texlive-full". | ||
13 | 18 | ||
14 | .SH OPTIONS | 19 | .SH OPTIONS |
15 | .B | 20 | .B |
diff --git a/doc/man/gnunet-config.1 b/doc/man/gnunet-config.1 index d309e7fa0..74839ee0e 100644 --- a/doc/man/gnunet-config.1 +++ b/doc/man/gnunet-config.1 | |||
@@ -14,7 +14,8 @@ gnunet\-config \- manipulate GNUnet configuration files | |||
14 | .SH OPTIONS | 14 | .SH OPTIONS |
15 | .B | 15 | .B |
16 | .IP "\-f, \-\-filename" | 16 | .IP "\-f, \-\-filename" |
17 | When accessing a specific option using \-s and \-o, perform expansions as if the value represents a filename. | 17 | When accessing a specific option using \-s and \-o, perform expansions as if the |
18 | value represents a filename. | ||
18 | .B | 19 | .B |
19 | .IP "\-s SECTION, \-\-section=SECTION" | 20 | .IP "\-s SECTION, \-\-section=SECTION" |
20 | Which configuration section should be accessed or edited. Required option. | 21 | Which configuration section should be accessed or edited. Required option. |
@@ -26,10 +27,13 @@ List available configuration sections for use with \-\-section. | |||
26 | Consider differences to defaults only. | 27 | Consider differences to defaults only. |
27 | .B | 28 | .B |
28 | .IP "\-o OPTION, \-\-option=OPTION" | 29 | .IP "\-o OPTION, \-\-option=OPTION" |
29 | Which configuration option should be accessed or edited. Required to set a value. If not given, all values of a given section will be printed in the format "OPTION = VALUE". | 30 | Which configuration option should be accessed or edited. Required to set a value. |
31 | If not given, all values of a given section will be printed in the | ||
32 | format "OPTION = VALUE". | ||
30 | .B | 33 | .B |
31 | .IP "\-V VALUE, \-\-value VALUE" | 34 | .IP "\-V VALUE, \-\-value VALUE" |
32 | Configuration value to store in the given section under the given option. Must only be given together with \-s and \-o options. | 35 | Configuration value to store in the given section under the given option. |
36 | Must only be given together with \-s and \-o options. | ||
33 | .B | 37 | .B |
34 | .IP "\-c FILENAME, \-\-config=FILENAME" | 38 | .IP "\-c FILENAME, \-\-config=FILENAME" |
35 | Use the configuration file FILENAME. | 39 | Use the configuration file FILENAME. |
diff --git a/doc/man/gnunet-conversation-test.1 b/doc/man/gnunet-conversation-test.1 index fa1b8d855..3cda104df 100644 --- a/doc/man/gnunet-conversation-test.1 +++ b/doc/man/gnunet-conversation-test.1 | |||
@@ -9,9 +9,14 @@ gnunet\-conversation\-test \- check your speaker and microphone settings | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-conversation\-test\fP can be used to check your speaker and microphone settings. It will record you for five seconds and then play the recording back to you. If this fails, you might want to use the \fBpavucontrol\fP tool to check which microphone or speaker were assigned to GNUnet by PulseAudio (you may have more than one set of microphones or speakers known to your computer). | 12 | \fBgnunet\-conversation\-test\fP can be used to check your speaker and microphone |
13 | settings. It will record you for five seconds and then play the recording back | ||
14 | to you. If this fails, you might want to use the \fBpavucontrol\fP tool to | ||
15 | check which microphone or speaker were assigned to GNUnet by PulseAudio (you | ||
16 | may have more than one set of microphones or speakers known to your computer). | ||
13 | 17 | ||
14 | You can use gnunet\-conversation\-test without having a peer running on your computer. | 18 | You can use gnunet\-conversation\-test without having a peer running on your |
19 | computer. | ||
15 | 20 | ||
16 | .SH OPTIONS | 21 | .SH OPTIONS |
17 | .B | 22 | .B |
diff --git a/doc/man/gnunet-conversation.1 b/doc/man/gnunet-conversation.1 index 912d2a17e..ae2523f82 100644 --- a/doc/man/gnunet-conversation.1 +++ b/doc/man/gnunet-conversation.1 | |||
@@ -9,7 +9,11 @@ gnunet\-conversation \- have a conversation with your peers | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-conversation\fP can be used to have a conversation with other GNUnet users. You can make calls and receive incoming calls. You need to setup an ego using gnunet\-identity first. For others to be able to call you, you must add a PHONE record to your zone in the GNU Name System (using gnunet\-namestore). gnunet\-conversation has an interactive help system via the /help command. | 12 | \fBgnunet\-conversation\fP can be used to have a conversation with other GNUnet |
13 | users. You can make calls and receive incoming calls. You need to setup an | ||
14 | ego using gnunet\-identity first. For others to be able to call you, you must | ||
15 | add a PHONE record to your zone in the GNU Name System (using gnunet\-namestore). | ||
16 | gnunet\-conversation has an interactive help system via the /help command. | ||
13 | 17 | ||
14 | .SH OPTIONS | 18 | .SH OPTIONS |
15 | .B | 19 | .B |
@@ -26,7 +30,9 @@ Print short help on options. | |||
26 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 30 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. |
27 | .B | 31 | .B |
28 | .IP "\-p LINE, \-\-phone=LINE" | 32 | .IP "\-p LINE, \-\-phone=LINE" |
29 | Optional argument that can be used to specify the phone LINE to be used with the conversation service. The default LINE is zero, which should be fine for most users. | 33 | Optional argument that can be used to specify the phone LINE to be used with |
34 | the conversation service. The default LINE is zero, which should be fine | ||
35 | for most users. | ||
30 | .B | 36 | .B |
31 | .IP "\-v, \-\-version" | 37 | .IP "\-v, \-\-version" |
32 | Print GNUnet version number. | 38 | Print GNUnet version number. |
diff --git a/doc/man/gnunet-core.1 b/doc/man/gnunet-core.1 index e2ada055a..2ed3df880 100644 --- a/doc/man/gnunet-core.1 +++ b/doc/man/gnunet-core.1 | |||
@@ -8,7 +8,9 @@ gnunet\-core \- monitor CORE subsystem | |||
8 | .SH DESCRIPTION | 8 | .SH DESCRIPTION |
9 | .PP | 9 | .PP |
10 | 10 | ||
11 | gnunet\-core is a tool to access various functions of GNUnet's core subsystem from the command\-line. The only function right now is to monitor the status of peers known to the CORE service. | 11 | gnunet\-core is a tool to access various functions of GNUnet's core subsystem |
12 | from the command\-line. The only function right now is to monitor the status | ||
13 | of peers known to the CORE service. | ||
12 | 14 | ||
13 | .TP | 15 | .TP |
14 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR | 16 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR |
@@ -21,7 +23,8 @@ print help page | |||
21 | Change the loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG. | 23 | Change the loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG. |
22 | .TP | 24 | .TP |
23 | \fB\-m\fR, \fB\-\-monitor\fR | 25 | \fB\-m\fR, \fB\-\-monitor\fR |
24 | in monitor mode, gnunet\-core will continuously print the connection status, instead of giving just a snapshot | 26 | in monitor mode, gnunet\-core will continuously print the connection status, |
27 | instead of giving just a snapshot | ||
25 | .TP | 28 | .TP |
26 | \fB\-v\fR, \fB\-\-version\fR | 29 | \fB\-v\fR, \fB\-\-version\fR |
27 | print the version number | 30 | print the version number |
diff --git a/doc/man/gnunet-datastore.1 b/doc/man/gnunet-datastore.1 index 1605006b3..6bba7fb47 100644 --- a/doc/man/gnunet-datastore.1 +++ b/doc/man/gnunet-datastore.1 | |||
@@ -8,7 +8,10 @@ gnunet\-datastore \- dump or insert (restore) GNUnet datastore databases | |||
8 | .SH DESCRIPTION | 8 | .SH DESCRIPTION |
9 | .PP | 9 | .PP |
10 | 10 | ||
11 | gnunet\-datastore can be used to backup and restore or merge GNUnet datastores. This is useful if a datastore is to be migrated between SQL databases, i.e. from sqlite to postgres or vice versa. gnunet\-datastore will dump the entire contents of the database or insert a dump file into the database. | 11 | gnunet\-datastore can be used to backup and restore or merge GNUnet datastores. |
12 | This is useful if a datastore is to be migrated between SQL databases, i.e. | ||
13 | from sqlite to postgres or vice versa. gnunet\-datastore will dump the | ||
14 | entire contents of the database or insert a dump file into the database. | ||
12 | 15 | ||
13 | .TP | 16 | .TP |
14 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR | 17 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR |
diff --git a/doc/man/gnunet-directory.1 b/doc/man/gnunet-directory.1 index 373e171f1..9a44be244 100644 --- a/doc/man/gnunet-directory.1 +++ b/doc/man/gnunet-directory.1 | |||
@@ -7,10 +7,14 @@ gnunet\-directory \- display directories | |||
7 | [\fIOPTIONS\fR] (FILENAME)* | 7 | [\fIOPTIONS\fR] (FILENAME)* |
8 | .SH DESCRIPTION | 8 | .SH DESCRIPTION |
9 | .PP | 9 | .PP |
10 | gnunet\-directory lists the contents of one or more GNUnet directories. A GNUnet directory is a binary file that contains a list of GNUnet file\-sharing URIs and meta data. The names of the directory files must be passed as command\-line arguments to gnunet\-directory. | 10 | gnunet\-directory lists the contents of one or more GNUnet directories. |
11 | A GNUnet directory is a binary file that contains a list of GNUnet | ||
12 | file\-sharing URIs and meta data. The names of the directory files must | ||
13 | be passed as command\-line arguments to gnunet\-directory. | ||
11 | .TP | 14 | .TP |
12 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR | 15 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR |
13 | configuration file to use (useless option since gnunet\-directory does not really depend on any configuration options) | 16 | configuration file to use (useless option since gnunet\-directory does not |
17 | really depend on any configuration options) | ||
14 | .TP | 18 | .TP |
15 | \fB\-h\fR, \fB\-\-help\fR | 19 | \fB\-h\fR, \fB\-\-help\fR |
16 | print help page | 20 | print help page |
@@ -21,13 +25,36 @@ Change the loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and | |||
21 | \fB\-v\fR, \fB\-\-version\fR | 25 | \fB\-v\fR, \fB\-\-version\fR |
22 | print the version number | 26 | print the version number |
23 | .SH NOTES | 27 | .SH NOTES |
24 | A GNUnet directory is a file containing a list of GNUnet URIs and meta data. The keys can point to files, other directories or files in namespaces. In other words, a GNUnet directory is similar to UNIX directories. The difference to tar and zip is that GNUnet directory does not contain the actual files (except if they are really small, in which case they may be inlined), just symbolic (links), similar to directories with symbolic links in UNIX filesystems. The benefit is that the individual files can be retrieved separately (if desired) and if some of the files are inserted to another node in GNUnet, this just increases their availability but does not produce useless duplicates (for example, it is a better idea to publish a collection of pictures or compressed sound files using a GNUnet directory instead of processing them with archivers such as tar or zip first). Directories can contain arbitrary meta data for each file. | 28 | A GNUnet directory is a file containing a list of GNUnet URIs and meta data. |
29 | The keys can point to files, other directories or files in namespaces. In other | ||
30 | words, a GNUnet directory is similar to UNIX directories. The difference to tar | ||
31 | and zip is that GNUnet directory does not contain the actual files (except if | ||
32 | they are really small, in which case they may be inlined), just symbolic (links), | ||
33 | similar to directories with symbolic links in UNIX filesystems. The benefit is | ||
34 | that the individual files can be retrieved separately (if desired) and if some | ||
35 | of the files are inserted to another node in GNUnet, this just increases their | ||
36 | availability but does not produce useless duplicates (for example, it is a | ||
37 | better idea to publish a collection of pictures or compressed sound files | ||
38 | using a GNUnet directory instead of processing them with archivers such as | ||
39 | tar or zip first). Directories can contain arbitrary meta data for each file. | ||
25 | 40 | ||
26 | If a directory has missing blocks (for example, some blocks failed to download), GNUnet is typically able to retrieve information about other files in the directory. Files in a GNUnet directory have no particular order; the GNUnet code that generates a directory can reorder the entries in order to better fit the information about files into blocks of 32k. Respecting 32k boundaries where possible makes it easier for gnunet\-directory (and other tools) to recover information from partially downloaded directory files. | 41 | If a directory has missing blocks (for example, some blocks failed to download), |
42 | GNUnet is typically able to retrieve information about other files in the | ||
43 | directory. Files in a GNUnet directory have no particular order; the GNUnet | ||
44 | code that generates a directory can reorder the entries in order to better | ||
45 | fit the information about files into blocks of 32k. Respecting 32k boundaries | ||
46 | where possible makes it easier for gnunet\-directory (and other tools) to | ||
47 | recover information from partially downloaded directory files. | ||
27 | 48 | ||
28 | At the moment, directories can be created by \fBgnunet\-fs\-gtk\fP and \fBgnunet\-publish\fP. Just like ordinary files, a directory can be published in a namespace. | 49 | At the moment, directories can be created by \fBgnunet\-fs\-gtk\fP |
50 | and \fBgnunet\-publish\fP. Just like ordinary files, a directory can be | ||
51 | published in a namespace. | ||
29 | 52 | ||
30 | GNUnet directories use the (unregistered) mimetype \fBapplication/gnunet\-directory\fP. They can show up among normal search results. The directory file can be downloaded to disk by \fBgnunet\-download\fP(1) for later processing or be handled more directly by \fBgnunet\-fs\-gtk\fP(1). | 53 | GNUnet directories use the (unregistered) |
54 | mimetype \fBapplication/gnunet\-directory\fP. They can show up among normal | ||
55 | search results. The directory file can be downloaded to disk | ||
56 | by \fBgnunet\-download\fP(1) for later processing or be handled more directly | ||
57 | by \fBgnunet\-fs\-gtk\fP(1). | ||
31 | 58 | ||
32 | .SH "REPORTING BUGS" | 59 | .SH "REPORTING BUGS" |
33 | Report bugs by using mantis <https://gnunet.org/bugs/> or by sending electronic mail to <gnunet\-developers@gnu.org> | 60 | Report bugs by using mantis <https://gnunet.org/bugs/> or by sending electronic mail to <gnunet\-developers@gnu.org> |
diff --git a/doc/man/gnunet-dns2gns.1 b/doc/man/gnunet-dns2gns.1 index 04fcb7f53..e04901062 100644 --- a/doc/man/gnunet-dns2gns.1 +++ b/doc/man/gnunet-dns2gns.1 | |||
@@ -9,9 +9,13 @@ gnunet\-dns2gns \- run a DNS-to-GNS proxy | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | Most users will not want to run an DNS to GNS proxy/gateway and thus will not need this program. | 12 | Most users will not want to run an DNS to GNS proxy/gateway and thus will not |
13 | need this program. | ||
13 | 14 | ||
14 | \fBgnunet\-dns2gns\fP runs a DNS resolver which delegates requests GNS if the TLD matches one configured for GNS. All other requests are forwarded to DNS. This DNS proxy is useful for enabling non-personalized GNS\-resolution to an entire network or to offer GNS\-resolution to DNS users. | 15 | \fBgnunet\-dns2gns\fP runs a DNS resolver which delegates requests GNS if |
16 | the TLD matches one configured for GNS. All other requests are forwarded | ||
17 | to DNS. This DNS proxy is useful for enabling non-personalized | ||
18 | GNS\-resolution to an entire network or to offer GNS\-resolution to DNS users. | ||
15 | 19 | ||
16 | .SH OPTIONS | 20 | .SH OPTIONS |
17 | .B | 21 | .B |
diff --git a/doc/man/gnunet-download-manager.1 b/doc/man/gnunet-download-manager.1 index 844f81084..ec1f7538a 100644 --- a/doc/man/gnunet-download-manager.1 +++ b/doc/man/gnunet-download-manager.1 | |||
@@ -9,13 +9,19 @@ gnunet-download-manager \- manage downloads across sessions | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-download\-manager\fP is a script that can be used to track download sessions. It makes the process of resuming downloads after a system reboot easier. A typical use is to define an alias (depending on your shell) of the form | 12 | \fBgnunet\-download\-manager\fP is a script that can be used to track |
13 | download sessions. It makes the process of resuming downloads after a | ||
14 | system reboot easier. A typical use is to define an alias (depending | ||
15 | on your shell) of the form | ||
13 | 16 | ||
14 | $ alias gnunet\-download='gnunet\-download\-manager.scm download' | 17 | $ alias gnunet\-download='gnunet\-download\-manager.scm download' |
15 | 18 | ||
16 | Other commands for the download manager include resume (resumes all downloads), status (show status of pending downloads), killall (abort all downloads), settings (for configuration) and help (print help text). | 19 | Other commands for the download manager include resume (resumes all |
20 | downloads), status (show status of pending downloads), killall (abort | ||
21 | all downloads), settings (for configuration) and help (print help text). | ||
17 | 22 | ||
18 | gnunet\-download\-manager is a scheme script and will only work if guile is available. | 23 | gnunet\-download\-manager is a scheme script and will only work if Guile |
24 | is available. | ||
19 | 25 | ||
20 | .SH BUGS | 26 | .SH BUGS |
21 | Report bugs by using mantis <https://gnunet.org/bugs/> or by sending electronic mail to <gnunet-developers@gnu.org> | 27 | Report bugs by using mantis <https://gnunet.org/bugs/> or by sending electronic mail to <gnunet-developers@gnu.org> |
diff --git a/doc/man/gnunet-download.1 b/doc/man/gnunet-download.1 index 759b3a964..824c2414d 100644 --- a/doc/man/gnunet-download.1 +++ b/doc/man/gnunet-download.1 | |||
@@ -18,7 +18,12 @@ use config file (defaults: ~/.config/gnunet.conf) | |||
18 | 18 | ||
19 | .TP | 19 | .TP |
20 | \fB\-D, \fB\-\-delete\-incomplete\fR | 20 | \fB\-D, \fB\-\-delete\-incomplete\fR |
21 | causes gnunet\-download to delete incomplete downloads when aborted with CTRL\-C. Note that complete files that are part of an incomplete recursive download will not be deleted even with this option. Without this option, terminating gnunet\-download with a signal will cause incomplete downloads to stay on disk. If gnunet\-download runs to (normal) completion finishing the download, this option has no effect. | 21 | causes gnunet\-download to delete incomplete downloads when aborted with |
22 | CTRL\-C. Note that complete files that are part of an incomplete recursive | ||
23 | download will not be deleted even with this option. Without this option, | ||
24 | terminating gnunet\-download with a signal will cause incomplete | ||
25 | downloads to stay on disk. If gnunet\-download runs to (normal) completion | ||
26 | finishing the download, this option has no effect. | ||
22 | 27 | ||
23 | .TP | 28 | .TP |
24 | \fB\-h\fR, \fB\-\-help\fR | 29 | \fB\-h\fR, \fB\-\-help\fR |
@@ -35,19 +40,49 @@ Only search locally, do not forward requests to other peers. | |||
35 | 40 | ||
36 | .TP | 41 | .TP |
37 | \fB\-o \fIFILENAME\fR, \fB\-\-output=FILENAME\fR | 42 | \fB\-o \fIFILENAME\fR, \fB\-\-output=FILENAME\fR |
38 | write the file to FILENAME. Hint: when recursively downloading a directory, append a '/' to the end of the FILENAME to create a directory of that name. If no FILENAME is specified, gnunet\-download constructs a temporary ID from the URI of the file. The final filename is constructed based on meta\-data extracted using libextractor (if available). | 43 | write the file to FILENAME. Hint: when recursively downloading a directory, |
44 | append a '/' to the end of the FILENAME to create a directory of that name. | ||
45 | If no FILENAME is specified, gnunet\-download constructs a temporary ID from | ||
46 | the URI of the file. The final filename is constructed based on meta\-data | ||
47 | extracted using libextractor (if available). | ||
39 | 48 | ||
40 | .TP | 49 | .TP |
41 | \fB\-p \fIDOWNLOADS\fR, \fB\-\-parallelism=DOWNLOADS\fR | 50 | \fB\-p \fIDOWNLOADS\fR, \fB\-\-parallelism=DOWNLOADS\fR |
42 | set the maximum number of parallel downloads that is allowed. More parallel downloads can, to some extent, improve the overall time to download content. However, parallel downloads also take more memory (see also option \-r which can be used to limit memory utilization) and more sockets. This option is used to limit the number of files that are downloaded in parallel (\-r can be used to limit the number of blocks that are concurrently requested). As a result, the value only matters for recursive downloads. The default value is 32. | 51 | set the maximum number of parallel downloads that is allowed. More parallel |
52 | downloads can, to some extent, improve the overall time to download content. | ||
53 | However, parallel downloads also take more memory (see also option \-r which | ||
54 | can be used to limit memory utilization) and more sockets. This option is | ||
55 | used to limit the number of files that are downloaded in parallel (\-r can | ||
56 | be used to limit the number of blocks that are concurrently requested). | ||
57 | As a result, the value only matters for recursive downloads. | ||
58 | The default value is 32. | ||
43 | 59 | ||
44 | .TP | 60 | .TP |
45 | \fB\-r \fIREQUESTS\fR, \fB\-\-request-parallelism=REQUESTS\fR | 61 | \fB\-r \fIREQUESTS\fR, \fB\-\-request-parallelism=REQUESTS\fR |
46 | set the maximum number of parallel requests that is allowed. If multiple files are downloaded, gnunet\-download will not run them in parallel if this would cause the number of pending requests to possibly exceed the given value. This is useful since, for example, downloading dozens of multi\-gigabyte files in parallel could exhaust memory resources and would hardly improve performance. Note that the limit only applies to this specific process and that other download activities by other processes are not included in this limit. Consider raising this limit for large recursive downloads with many large files if memory and network bandwidth are not fully utilized and if the parallelism limit (\-p option) is not reached. This option also only matters for recursive downloads. The default value is 4092. | 62 | set the maximum number of parallel requests that is allowed. If multiple |
63 | files are downloaded, gnunet\-download will not run them in parallel if | ||
64 | this would cause the number of pending requests to possibly exceed the | ||
65 | given value. This is useful since, for example, downloading dozens of | ||
66 | multi\-gigabyte files in parallel could exhaust memory resources and would | ||
67 | hardly improve performance. Note that the limit only applies to this | ||
68 | specific process and that other download activities by other processes | ||
69 | are not included in this limit. Consider raising this limit for large | ||
70 | recursive downloads with many large files if memory and network | ||
71 | bandwidth are not fully utilized and if the parallelism limit (\-p option) | ||
72 | is not reached. This option also only matters for recursive downloads. | ||
73 | The default value is 4092. | ||
47 | 74 | ||
48 | .TP | 75 | .TP |
49 | \fB\-R\fR, \fB\-\-recursive\fR | 76 | \fB\-R\fR, \fB\-\-recursive\fR |
50 | download directories recursively (and in parallel). Note that the URI must belong to a GNUnet directory and that the filename given to "\-o" must end in '.gnd' \-\- otherwise, you will receive an error. You may want to use "DIRNAME/.gnd" for the filename, this way a directory "DIRNAME/" will be created, and GNUnet's internal directory information will be stored in "DIRNAME/.gnd". However, it is also possible to specify "DIRNAME.gnd", in which case the files from the directory will end up in "DIRNAME/", while GNUnet's directory meta data will be in "DIRNAME.gnd". | 77 | download directories recursively (and in parallel). Note that the URI |
78 | must belong to a GNUnet directory and that the filename given to "\-o" | ||
79 | must end in '.gnd' \-\- otherwise, you will receive an error. You may | ||
80 | want to use "DIRNAME/.gnd" for the filename, this way a directory | ||
81 | "DIRNAME/" will be created, and GNUnet's internal directory | ||
82 | information will be stored in "DIRNAME/.gnd". However, it is also | ||
83 | possible to specify "DIRNAME.gnd", in which case the files from the | ||
84 | directory will end up in "DIRNAME/", while GNUnet's directory meta | ||
85 | data will be in "DIRNAME.gnd". | ||
51 | 86 | ||
52 | .TP | 87 | .TP |
53 | \fB\-v\fR, \fB\-\-version\fR | 88 | \fB\-v\fR, \fB\-\-version\fR |
@@ -58,18 +93,55 @@ print the version number | |||
58 | print progress information | 93 | print progress information |
59 | 94 | ||
60 | .SH NOTES | 95 | .SH NOTES |
61 | The GNUNET_URI is typically obtained from gnunet\-search. gnunet\-fs\-gtk can also be used instead of gnunet\-download. | 96 | The GNUNET_URI is typically obtained from |
62 | If you ever have to abort a download, you can at any time continue it by re\-issuing gnunet\-download with the same filename. In that case GNUnet will not download blocks again that are already present. GNUnet's file\-encoding will ensure file integrity, even if the existing file was not downloaded from GNUnet in the first place. Temporary information will be appended to the target file until the download is completed. | 97 | gnunet\-search. gnunet\-fs\-gtk can also be used instead of |
98 | gnunet\-download. If you ever have to abort a download, you can at | ||
99 | any time continue it by re\-issuing gnunet\-download with the same | ||
100 | filename. In that case GNUnet will not download blocks again that are | ||
101 | already present. GNUnet's file\-encoding will ensure file integrity, | ||
102 | even if the existing file was not downloaded from GNUnet in the first | ||
103 | place. Temporary information will be appended to the target file until | ||
104 | the download is completed. | ||
63 | 105 | ||
64 | .SH SETTING ANONYMITY LEVEL | 106 | .SH SETTING ANONYMITY LEVEL |
65 | 107 | ||
66 | The \fB\-a\fR option can be used to specify additional anonymity constraints. If set to 0, GNUnet will try to download the file as fast as possible, including using non-anonymous methods. If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity. You can gain better privacy by specifying a higher level of anonymity, which increases the amount of cover traffic your own traffic will get, at the expense of performance. Note that your download performance is not only determined by your own anonymity level, but also by the anonymity level of the peers publishing the file. So even if you download with anonymity level 0, the peers publishing the data might be sharing with a higher anonymity level, which in this case will determine performance. Also, peers that cache content in the network always use anonymity level 1. | 108 | The \fB\-a\fR option can be used to specify additional anonymity |
67 | 109 | constraints. If set to 0, GNUnet will try to download the file as fast | |
68 | This option can be used to limit requests further than that. In particular, you can require GNUnet to receive certain amounts of traffic from other peers before sending your queries. This way, you can gain very high levels of anonymity \- at the expense of much more traffic and much higher latency. So set it only if you really believe you need it. | 110 | as possible, including using non-anonymous methods. If you set it to |
69 | 111 | 1 (default), you use the standard anonymous routing algorithm (which | |
70 | The definition of ANONYMITY\-RECEIVE is the following. 0 means no anonymity is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" traffic can be from the local user, leaving 'v-1' bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign peers (using anonymous routing), it may originate n/(v-1) bytes of queries in the same time\-period. The time\-period is twice the average delay that GNUnet defers forwarded queries. | 112 | does not explicitly leak your identity). However, a powerful |
71 | 113 | adversary may still be able to perform traffic analysis (statistics) | |
72 | The default is 1 and this should be fine for most users. Also notice that if you choose very large values, you may end up having no throughput at all, especially if many of your fellow GNUnet\-peers all do the same. | 114 | to over time infer data about your identity. You can gain better |
115 | privacy by specifying a higher level of anonymity, which increases the | ||
116 | amount of cover traffic your own traffic will get, at the expense of | ||
117 | performance. Note that your download performance is not only | ||
118 | determined by your own anonymity level, but also by the anonymity | ||
119 | level of the peers publishing the file. So even if you download with | ||
120 | anonymity level 0, the peers publishing the data might be sharing with | ||
121 | a higher anonymity level, which in this case will determine | ||
122 | performance. Also, peers that cache content in the network always use | ||
123 | anonymity level 1. | ||
124 | |||
125 | This option can be used to limit requests further than that. In | ||
126 | particular, you can require GNUnet to receive certain amounts of | ||
127 | traffic from other peers before sending your queries. This way, you | ||
128 | can gain very high levels of anonymity \- at the expense of much more | ||
129 | traffic and much higher latency. So set it only if you really believe | ||
130 | you need it. | ||
131 | |||
132 | The definition of ANONYMITY\-RECEIVE is the following. 0 means no | ||
133 | anonymity is required. Otherwise a value of 'v' means that 1 out of v | ||
134 | bytes of "anonymous" traffic can be from the local user, leaving 'v-1' | ||
135 | bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n | ||
136 | bytes of messages from foreign peers (using anonymous routing), it may | ||
137 | originate n/(v-1) bytes of queries in the same time\-period. The | ||
138 | time\-period is twice the average delay that GNUnet defers forwarded | ||
139 | queries. | ||
140 | |||
141 | The default is 1 and this should be fine for most users. Also notice | ||
142 | that if you choose very large values, you may end up having no | ||
143 | throughput at all, especially if many of your fellow GNUnet\-peers all | ||
144 | do the same. | ||
73 | 145 | ||
74 | .SH FILES | 146 | .SH FILES |
75 | .TP | 147 | .TP |
diff --git a/doc/man/gnunet-ecc.1 b/doc/man/gnunet-ecc.1 index 910687f1f..22a3c5d44 100644 --- a/doc/man/gnunet-ecc.1 +++ b/doc/man/gnunet-ecc.1 | |||
@@ -9,21 +9,30 @@ gnunet\-ecc \- manipulate GNUnet ECC key files | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-ecc\fP can be used to create an ECC private key and to print the corresponding public key. You must specify a filename containing an ECC private key in GNUnet format as an argument. If the file does not exist, gnunet\-ecc will create a key. This may then take a while. If the option \-p is given, the corresponding public key will be printed to the console. | 12 | \fBgnunet\-ecc\fP can be used to create an ECC private key and to |
13 | print the corresponding public key. You must specify a filename | ||
14 | containing an ECC private key in GNUnet format as an argument. If the | ||
15 | file does not exist, gnunet\-ecc will create a key. This may then | ||
16 | take a while. If the option \-p is given, the corresponding public | ||
17 | key will be printed to the console. | ||
13 | 18 | ||
14 | .SH OPTIONS | 19 | .SH OPTIONS |
15 | .B | 20 | .B |
16 | .IP "\-g COUNT, \-\-generate-keys=COUNT" | 21 | .IP "\-g COUNT, \-\-generate-keys=COUNT" |
17 | Create COUNT public-private key pairs and write them to FILENAME. Used for creating a file for testing. | 22 | Create COUNT public-private key pairs and write them to FILENAME. |
23 | Used for creating a file for testing. | ||
18 | .B | 24 | .B |
19 | .IP "\-p, \-\-print-public-key" | 25 | .IP "\-p, \-\-print-public-key" |
20 | Print the corresponding public key to stdout. This is the value used for PKEY records in GNS. | 26 | Print the corresponding public key to stdout. This is the value used |
27 | for PKEY records in GNS. | ||
21 | .B | 28 | .B |
22 | .IP "\-P, \-\-print-private-key" | 29 | .IP "\-P, \-\-print-private-key" |
23 | Print the corresponding private key to stdout. This is the value used for PKEY records in GNS. | 30 | Print the corresponding private key to stdout. This is the value used |
31 | for PKEY records in GNS. | ||
24 | .B | 32 | .B |
25 | .IP "\-x, \-\-print-hex" | 33 | .IP "\-x, \-\-print-hex" |
26 | Print the corresponding public key to stdout in HEX format. Useful for comparing to Ed25519 keys in X.509 tools. | 34 | Print the corresponding public key to stdout in HEX format. Useful |
35 | for comparing to Ed25519 keys in X.509 tools. | ||
27 | .B | 36 | .B |
28 | .IP "\-c FILENAME, \-\-config=FILENAME" | 37 | .IP "\-c FILENAME, \-\-config=FILENAME" |
29 | Use the configuration file FILENAME. | 38 | Use the configuration file FILENAME. |
@@ -32,7 +41,8 @@ Use the configuration file FILENAME. | |||
32 | Print short help on options. | 41 | Print short help on options. |
33 | .B | 42 | .B |
34 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" | 43 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" |
35 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 44 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and |
45 | ERROR. | ||
36 | .B | 46 | .B |
37 | .IP "\-v, \-\-version" | 47 | .IP "\-v, \-\-version" |
38 | Print GNUnet version number. | 48 | Print GNUnet version number. |
diff --git a/doc/man/gnunet-fs.1 b/doc/man/gnunet-fs.1 index 65f104d61..dfdaabbdb 100644 --- a/doc/man/gnunet-fs.1 +++ b/doc/man/gnunet-fs.1 | |||
@@ -8,7 +8,11 @@ gnunet\-fs \- measure and control the fs subsystem | |||
8 | .SH DESCRIPTION | 8 | .SH DESCRIPTION |
9 | .PP | 9 | .PP |
10 | 10 | ||
11 | gnunet\-fs is a tool to access various functions of GNUnet's fs subsystem from the command\-line. Most of these are not expected to be useful for end-users. gnunet\-fs can currently only be used to obtain a list of indexed files. Other functions should be added in the near future. | 11 | gnunet\-fs is a tool to access various functions of GNUnet's fs |
12 | subsystem from the command\-line. Most of these are not expected to | ||
13 | be useful for end-users. gnunet\-fs can currently only be used to | ||
14 | obtain a list of indexed files. Other functions should be added in | ||
15 | the near future. | ||
12 | 16 | ||
13 | .TP | 17 | .TP |
14 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR | 18 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR |
@@ -17,17 +21,16 @@ configuration file to use | |||
17 | \fB\-h\fR, \fB\-\-help\fR | 21 | \fB\-h\fR, \fB\-\-help\fR |
18 | print help page | 22 | print help page |
19 | .TP | 23 | .TP |
20 | \fB\-i\fR, \fB\-\-list-indexed\fR | 24 | \fB\-i\fR, \fB\-\-list-indexed\fR print information about files that |
21 | print information about files that are currently indexed by file-sharing | 25 | are currently indexed by file-sharing |
22 | .TP | 26 | .TP |
23 | \fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=LOGLEVEL\fR | 27 | \fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=LOGLEVEL\fR Change the |
24 | Change the loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG. | 28 | loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and |
29 | DEBUG. | ||
25 | .TP | 30 | .TP |
26 | \fB\-v\fR, \fB\-\-version\fR | 31 | \fB\-v\fR, \fB\-\-version\fR print the version number |
27 | print the version number | ||
28 | .TP | 32 | .TP |
29 | \fB\-V\fR, \fB\-\-verbose\fR | 33 | \fB\-V\fR, \fB\-\-verbose\fR be verbose |
30 | be verbose | ||
31 | 34 | ||
32 | 35 | ||
33 | .SH BUGS | 36 | .SH BUGS |
diff --git a/doc/man/gnunet-gns-proxy.1 b/doc/man/gnunet-gns-proxy.1 index 9b9f603bd..96e9911a2 100644 --- a/doc/man/gnunet-gns-proxy.1 +++ b/doc/man/gnunet-gns-proxy.1 | |||
@@ -9,9 +9,15 @@ gnunet\-gns\-proxy \- run a client side GNS SOCKS proxy | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | Most users will want to run this SOCKS proxy. It can be used in combination with browsers that support the SOCKS 4a protocol. | 12 | Most users will want to run this SOCKS proxy. It can be used in |
13 | combination with browsers that support the SOCKS 4a protocol. | ||
13 | 14 | ||
14 | The proxy will perform SSL authentication of GNS names and rewrite GNS enabled HTML content. To assert the validity of GNS names a local root CA certificate has to be generated that is used by the proxy. Thus "gnunet-gns-proxy-setup-ca" should be executed before the first launch of this proxy or the \-\-authority switch is used to specify an appropriate CA certificate that is already trusted by the browser. | 15 | The proxy will perform SSL authentication of GNS names and rewrite GNS |
16 | enabled HTML content. To assert the validity of GNS names a local root | ||
17 | CA certificate has to be generated that is used by the proxy. Thus | ||
18 | "gnunet-gns-proxy-setup-ca" should be executed before the first launch | ||
19 | of this proxy or the \-\-authority switch is used to specify an | ||
20 | appropriate CA certificate that is already trusted by the browser. | ||
15 | 21 | ||
16 | .SH OPTIONS | 22 | .SH OPTIONS |
17 | .B | 23 | .B |
@@ -19,7 +25,10 @@ The proxy will perform SSL authentication of GNS names and rewrite GNS enabled H | |||
19 | Use the configuration file FILENAME. | 25 | Use the configuration file FILENAME. |
20 | .B | 26 | .B |
21 | .IP "\-a AUTHORITY, \-\-authority=AUTHORITY" | 27 | .IP "\-a AUTHORITY, \-\-authority=AUTHORITY" |
22 | Path to a PEM CA file that contains the certificate and private key of the CA to use to assert the validity of GNS names. The default port is specified in the configuration file for the gns service under "[gns-proxy]" PROXY_CACERT. | 28 | Path to a PEM CA file that contains the certificate and private key of |
29 | the CA to use to assert the validity of GNS names. The default port is | ||
30 | specified in the configuration file for the gns service under | ||
31 | "[gns-proxy]" PROXY_CACERT. | ||
23 | .B | 32 | .B |
24 | .IP "\-p PORT, \-\-port=PORT" | 33 | .IP "\-p PORT, \-\-port=PORT" |
25 | The port this proxy should listen on. Default is 7777. | 34 | The port this proxy should listen on. Default is 7777. |
@@ -28,7 +37,8 @@ The port this proxy should listen on. Default is 7777. | |||
28 | Print short help on options. | 37 | Print short help on options. |
29 | .B | 38 | .B |
30 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" | 39 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" |
31 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 40 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and |
41 | ERROR. | ||
32 | .B | 42 | .B |
33 | .IP "\-v, \-\-version" | 43 | .IP "\-v, \-\-version" |
34 | Print GNUnet version number. | 44 | Print GNUnet version number. |
diff --git a/doc/man/gnunet-gns.1 b/doc/man/gnunet-gns.1 index 4d52cfa97..9e4482653 100644 --- a/doc/man/gnunet-gns.1 +++ b/doc/man/gnunet-gns.1 | |||
@@ -9,7 +9,8 @@ gnunet\-gns \- Access to GNU Name System | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-gns\fP can be used to lookup and process GNU Name Service names. | 12 | \fBgnunet\-gns\fP can be used to lookup and process GNU Name Service |
13 | names. | ||
13 | 14 | ||
14 | .SH OPTIONS | 15 | .SH OPTIONS |
15 | .B | 16 | .B |
@@ -17,24 +18,24 @@ gnunet\-gns \- Access to GNU Name System | |||
17 | Use the configuration file FILENAME. | 18 | Use the configuration file FILENAME. |
18 | .B | 19 | .B |
19 | .IP "\-r, \-\-raw" | 20 | .IP "\-r, \-\-raw" |
20 | No unneeded output. | 21 | No unneeded output. This is a quiet mode where only important |
21 | This is a quiet mode where only important information is displayed. | 22 | information is displayed. For example a lookup for an IP address will |
22 | For example a lookup for an IP address will only yield the IP address, no | 23 | only yield the IP address, no descriptive text. |
23 | descriptive text. | ||
24 | .B | 24 | .B |
25 | .IP "\-h, \-\-help" | 25 | .IP "\-h, \-\-help" |
26 | Print short help on options. | 26 | Print short help on options. |
27 | .B | 27 | .B |
28 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" | 28 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" |
29 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 29 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and |
30 | ERROR. | ||
30 | .B | 31 | .B |
31 | .IP "\-u NAME, \-\-lookup=NAME" | 32 | .IP "\-u NAME, \-\-lookup=NAME" |
32 | Name to lookup. | 33 | Name to lookup. Resolve the specified name using the GNU Name System. |
33 | Resolve the specified name using the GNU Name System. | ||
34 | .B | 34 | .B |
35 | .IP "\-t TYPE, \-\-type=TYPE" | 35 | .IP "\-t TYPE, \-\-type=TYPE" |
36 | Resource Record Type (TYPE) to look for. | 36 | Resource Record Type (TYPE) to look for. Supported TYPE's are: A, |
37 | Supported TYPE's are: A, AAAA, CNAME, NS, PKEY, PSEU, TLSA, SRV, SOA, MX, LEHO, VPN, REV, PTR, TXT | 37 | AAAA, CNAME, NS, PKEY, PSEU, TLSA, SRV, SOA, MX, LEHO, VPN, REV, PTR, |
38 | TXT | ||
38 | 39 | ||
39 | Defaults to "A". | 40 | Defaults to "A". |
40 | .B | 41 | .B |
@@ -44,8 +45,8 @@ Print GNUnet version number. | |||
44 | 45 | ||
45 | .SH RETURN VALUE | 46 | .SH RETURN VALUE |
46 | 47 | ||
47 | gnunet\-gns will return 0 on success, 1 on internal failures, 2 on launch failures, | 48 | gnunet\-gns will return 0 on success, 1 on internal failures, 2 on |
48 | 3 if the given name is not configured to use GNS. | 49 | launch failures, 4 if the given name is not configured to use GNS. |
49 | 50 | ||
50 | 51 | ||
51 | .SH BUGS | 52 | .SH BUGS |
diff --git a/doc/man/gnunet-identity.1 b/doc/man/gnunet-identity.1 index 50efa74d4..37cf85f45 100644 --- a/doc/man/gnunet-identity.1 +++ b/doc/man/gnunet-identity.1 | |||
@@ -6,39 +6,50 @@ gnunet\-identity \- create, delete or list egos | |||
6 | [options] | 6 | [options] |
7 | .SH DESCRIPTION | 7 | .SH DESCRIPTION |
8 | .PP | 8 | .PP |
9 | gnunet\-identity is a tool for managing egos. An ego is the persona that controls a namespace. It is identical to a public\-private ECC key pair. | 9 | gnunet\-identity is a tool for managing egos. An ego is the persona |
10 | that controls a namespace. It is identical to a public\-private ECC | ||
11 | key pair. | ||
10 | 12 | ||
11 | gnunet\-identity can be used to list all of the egos that were created locally, to create new egos, and to delete existing egos (the namespace will continue to exist, but it will be impossible to add additional data to it). | 13 | gnunet\-identity can be used to list all of the egos that were created |
14 | locally, to create new egos, and to delete existing egos (the | ||
15 | namespace will continue to exist, but it will be impossible to add | ||
16 | additional data to it). | ||
12 | 17 | ||
13 | Creating a new ego requires using the \-C option together with an identifier (name) that is to be used for the new ego. This identifier is only used locally for this peer and not shared with other peers. | 18 | Creating a new ego requires using the \-C option together with an |
19 | identifier (name) that is to be used for the new ego. This identifier | ||
20 | is only used locally for this peer and not shared with other peers. | ||
14 | 21 | ||
15 | .TP | 22 | .TP |
16 | \fB\-C NAME\fR, \fB\-\-create=NAME\fR | 23 | \fB\-C NAME\fR, \fB\-\-create=NAME\fR Creates a new ego with the given |
17 | Creates a new ego with the given NAME. | 24 | NAME. |
18 | 25 | ||
19 | .TP | 26 | .TP |
20 | \fB\-D NAME\fR, \fB\-\-delete=NAME\fR | 27 | \fB\-D NAME\fR, \fB\-\-delete=NAME\fR Delete the ego with the given |
21 | Delete the ego with the given NAME. | 28 | NAME. |
22 | 29 | ||
23 | .TP | 30 | .TP |
24 | \fB\-e NAME\fR, \fB\-\-ego=NAME\fR | 31 | \fB\-e NAME\fR, \fB\-\-ego=NAME\fR Perform "set" operation with the |
25 | Perform "set" operation with the respective ego. Needs to be used together with option \-s. | 32 | respective ego. Needs to be used together with option \-s. |
26 | 33 | ||
27 | .TP | 34 | .TP |
28 | \fB\-h\fR, \fB\-\-help\fR | 35 | \fB\-h\fR, \fB\-\-help\fR Print help page. |
29 | Print help page. | ||
30 | 36 | ||
31 | .TP | 37 | .TP |
32 | \fB\-d\fR, \fB\-\-display\fR | 38 | \fB\-d\fR, \fB\-\-display\fR display all of our egos |
33 | display all of our egos | ||
34 | 39 | ||
35 | .TP | 40 | .TP |
36 | \fB\-m\fR, \fB\-\-monitor\fR | 41 | \fB\-m\fR, \fB\-\-monitor\fR run in monitor mode, listing all ouf our |
37 | run in monitor mode, listing all ouf our egos until CTRL-C is pressed. Each ego is listed together with a unique pointer value; if egos are renamed, that pointer value remains the same; if egos are deleted, they are listed one more time with a name of "<null>". | 42 | egos until CTRL-C is pressed. Each ego is listed together with a |
43 | unique pointer value; if egos are renamed, that pointer value remains | ||
44 | the same; if egos are deleted, they are listed one more time with a | ||
45 | name of "<null>". | ||
38 | 46 | ||
39 | .TP | 47 | .TP |
40 | \fB\-s SUBSYSTEM\fR, \fB\-\-set=SUBSYSTEM\fR | 48 | \fB\-s SUBSYSTEM\fR, \fB\-\-set=SUBSYSTEM\fR Perform "set" operation |
41 | Perform "set" operation for the specified SUBSYSTEM with the respective ego. Needs to be used together with option \-e. After this, the given SUBSYSTEM will use the ego with the specified NAME. This will fail if NAME does not yet exist. | 49 | for the specified SUBSYSTEM with the respective ego. Needs to be used |
50 | together with option \-e. After this, the given SUBSYSTEM will use | ||
51 | the ego with the specified NAME. This will fail if NAME does not yet | ||
52 | exist. | ||
42 | 53 | ||
43 | 54 | ||
44 | .SH FILES | 55 | .SH FILES |
diff --git a/doc/man/gnunet-namecache.1 b/doc/man/gnunet-namecache.1 index ec2e602b8..ffc315b32 100644 --- a/doc/man/gnunet-namecache.1 +++ b/doc/man/gnunet-namecache.1 | |||
@@ -9,7 +9,8 @@ gnunet\-namecache \- inspect namecache | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-namecache\fP can be used to inspect values in the namecache. | 12 | \fBgnunet\-namecache\fP can be used to inspect values in the |
13 | namecache. | ||
13 | 14 | ||
14 | .SH OPTIONS | 15 | .SH OPTIONS |
15 | .B | 16 | .B |
@@ -20,7 +21,8 @@ Use the configuration file FILENAME. | |||
20 | Print short help on options. | 21 | Print short help on options. |
21 | .B | 22 | .B |
22 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" | 23 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" |
23 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 24 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and |
25 | ERROR. | ||
24 | .B | 26 | .B |
25 | .IP "\-n NAME, \-\-name=NAME" | 27 | .IP "\-n NAME, \-\-name=NAME" |
26 | Name (label) of the record to display (mandatory option) | 28 | Name (label) of the record to display (mandatory option) |
diff --git a/doc/man/gnunet-namestore-fcfsd.1 b/doc/man/gnunet-namestore-fcfsd.1 index 8039e796f..88ab72071 100644 --- a/doc/man/gnunet-namestore-fcfsd.1 +++ b/doc/man/gnunet-namestore-fcfsd.1 | |||
@@ -9,13 +9,27 @@ gnunet\-namestore-fcfsd \- HTTP server for GNU Name System First-Come-First-Serv | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | Most users will not want to run an FCFS\-zone and thus will not need this program. | 12 | Most users will not want to run an FCFS\-zone and thus will not need |
13 | this program. | ||
13 | 14 | ||
14 | \fBgnunet\-gns-fcfsd\fP runs a web server where users can register names to be mapped to their GNS zone. Names are made available on a First Come First Served basis (hence fcfs). Registered names do not expire. The HTTP server is run on the port that is specified in the configuration file in section "[fcfsd]" under the name "HTTPPORT". The key of the zone in which the names are registered must be specified under the name "ZONEKEY" in the same section. It is possible to manage gnunet\-gns\-fcfsd using gnunet\-(service\-arm) by starting the daemon using "gnunet\-arm \-i fcfsd" or by setting "FORCESTART=YES" in the "fcfds" section of your configuration. | 15 | \fBgnunet\-gns-fcfsd\fP runs a web server where users can register |
16 | names to be mapped to their GNS zone. Names are made available on a | ||
17 | First Come First Served basis (hence fcfs). Registered names do not | ||
18 | expire. The HTTP server is run on the port that is specified in the | ||
19 | configuration file in section "[fcfsd]" under the name "HTTPPORT". | ||
15 | 20 | ||
16 | An FCFS\-zone is run at http://gnunet.org/fcfs/. GNS users are encouraged to register their zone with the gnunet.org FCFS authority. | 21 | It is possible to manage gnunet\-gns\-fcfsd using |
22 | gnunet\-(service\-arm) by starting the daemon using "gnunet\-arm \-i | ||
23 | fcfsd" or by setting "IMMEDIATE_START=YES" in the "fcfds" section of your | ||
24 | configuration and the "-z ZONE" in as the "OPTION". | ||
17 | 25 | ||
18 | If you want to run your own FCFS registrar, you need to first create a pseudonym (using "gnunet\-identity \-C NAME"), and then assign it to be used for the "fcfsd" service using "gnunet\-identity \-e NAME \-s fcfsd". After that, you can start the FCFSD service (possibly using gnunet\-arm). | 26 | An FCFS\-zone is run at http://gnunet.org/fcfs/. GNS users are |
27 | encouraged to register their zone with the gnunet.org FCFS authority. | ||
28 | |||
29 | If you want to run your own FCFS registrar, you need to first create a | ||
30 | pseudonym (using "gnunet\-identity \-C NAME"), and use it with the | ||
31 | "-z" option. After that, you can start the FCFSD service (possibly using | ||
32 | gnunet\-arm). | ||
19 | 33 | ||
20 | .SH OPTIONS | 34 | .SH OPTIONS |
21 | .B | 35 | .B |
@@ -26,11 +40,14 @@ Use the configuration file FILENAME. | |||
26 | Print short help on options. | 40 | Print short help on options. |
27 | .B | 41 | .B |
28 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" | 42 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" |
29 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 43 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and |
44 | ERROR. | ||
30 | .B | 45 | .B |
31 | .IP "\-v, \-\-version" | 46 | .IP "\-v, \-\-version" |
32 | Print GNUnet version number. | 47 | Print GNUnet version number. |
33 | 48 | .B | |
49 | .IP "\-z EGO, \-\-zone=EGO" | ||
50 | Specifies for which EGO should FCFSD manage the zone. | ||
34 | 51 | ||
35 | .SH BUGS | 52 | .SH BUGS |
36 | Report bugs by using Mantis <https://gnunet.org/bugs/> or by sending electronic mail to <bug\-gnunet@gnu.org> | 53 | Report bugs by using Mantis <https://gnunet.org/bugs/> or by sending electronic mail to <bug\-gnunet@gnu.org> |
diff --git a/doc/man/gnunet-namestore.1 b/doc/man/gnunet-namestore.1 index 1811031ad..006c8593b 100644 --- a/doc/man/gnunet-namestore.1 +++ b/doc/man/gnunet-namestore.1 | |||
@@ -20,52 +20,72 @@ Desired operation is adding a record | |||
20 | Use the configuration file FILENAME. | 20 | Use the configuration file FILENAME. |
21 | .B | 21 | .B |
22 | .IP "\-d, \-\-delete" | 22 | .IP "\-d, \-\-delete" |
23 | Desired operation is deleting records under the given name that match the specified type (\-t) and value (\-V). If type or value are not specified, it means that all types (or values) should be assumed to match (and possibly multiple or all values under the given label will be deleted). Specifying a label (\-n) is mandatory. Note that matching by expiration time or flags is (currently) not supported. | 23 | Desired operation is deleting records under the given name that match |
24 | the specified type (\-t) and value (\-V). If type or value are not | ||
25 | specified, it means that all types (or values) should be assumed to | ||
26 | match (and possibly multiple or all values under the given label will | ||
27 | be deleted). Specifying a label (\-n) is mandatory. Note that | ||
28 | matching by expiration time or flags is (currently) not supported. | ||
24 | .B | 29 | .B |
25 | .IP "\-D, \-\-display" | 30 | .IP "\-D, \-\-display" |
26 | Desired operation is listing of matching records | 31 | Desired operation is listing of matching records |
27 | .B | 32 | .B |
28 | .IP "\-e TIME, \-\-expiration=TIME" | 33 | .IP "\-e TIME, \-\-expiration=TIME" |
29 | Specifies expiration time of record to add; format is relative time, i.e "1 h" or "7 d 30 m". Supported units are "ms", "s", "min" or "minutes", "h" (hours), "d" (days) and "a" (years). | 34 | Specifies expiration time of record to add; format is relative time, |
35 | i.e "1 h" or "7 d 30 m". Supported units are "ms", "s", "min" or | ||
36 | "minutes", "h" (hours), "d" (days) and "a" (years). | ||
30 | .B | 37 | .B |
31 | .IP "\-h, \-\-help" | 38 | .IP "\-h, \-\-help" |
32 | Print short help on options. | 39 | Print short help on options. |
33 | .B | 40 | .B |
34 | .IP "\-i NICKNAME, \-\-nick=NICKNAME" | 41 | .IP "\-i NICKNAME, \-\-nick=NICKNAME" |
35 | Set the desired NICKNAME for the zone. The nickname will be included in all (public) records and used as the suggested name for this zone. | 42 | Set the desired NICKNAME for the zone. The nickname will be included |
43 | in all (public) records and used as the suggested name for this zone. | ||
36 | .B | 44 | .B |
37 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" | 45 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" |
38 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 46 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and |
47 | ERROR. | ||
39 | .B | 48 | .B |
40 | .IP "\-m, \-\-monitor" | 49 | .IP "\-m, \-\-monitor" |
41 | Monitor changes to the zone on an ongoing basis (in contrast to \-D, which merely displays the current records) | 50 | Monitor changes to the zone on an ongoing basis (in contrast to \-D, |
51 | which merely displays the current records) | ||
42 | .B | 52 | .B |
43 | .IP "\-n NAME, \-\-name=NAME" | 53 | .IP "\-n NAME, \-\-name=NAME" |
44 | Label or name of the record to add/delete/display | 54 | Label or name of the record to add/delete/display |
45 | .B | 55 | .B |
46 | .IP "\-p, \-\-public" | 56 | .IP "\-p, \-\-public" |
47 | Create a record that is public (shared with other users that know the label) | 57 | Create a record that is public (shared with other users that know the |
58 | label) | ||
48 | .B | 59 | .B |
49 | .IP "\-r PKEY, \-\-reverse=PKEY" | 60 | .IP "\-r PKEY, \-\-reverse=PKEY" |
50 | Determine our GNS name for the given public key (reverse lookup of the PKEY) in the given zone. | 61 | Determine our GNS name for the given public key (reverse lookup of the |
62 | PKEY) in the given zone. | ||
51 | .B | 63 | .B |
52 | .IP "\-s, \-\-shadow" | 64 | .IP "\-s, \-\-shadow" |
53 | Create a record that is a shadow record. Shadow records are only used once all other records of the same type under the same label have expired. | 65 | Create a record that is a shadow record. Shadow records are only used |
66 | once all other records of the same type under the same label have | ||
67 | expired. | ||
54 | .B | 68 | .B |
55 | .IP "\-t TYPE, \-\-type=TYPE" | 69 | .IP "\-t TYPE, \-\-type=TYPE" |
56 | Type of the record to add/delete/display (i.e. "A", "AAAA", "NS", "PKEY", "MX" etc.) | 70 | Type of the record to add/delete/display (i.e. "A", "AAAA", "NS", |
71 | "PKEY", "MX" etc.) | ||
57 | .B | 72 | .B |
58 | .IP "\-u URI, \-\-uri=URI" | 73 | .IP "\-u URI, \-\-uri=URI" |
59 | Add PKEY record from gnunet://gns/-URI to our zone; the record type is always PKEY, if no expiration is given FOREVER is used | 74 | Add PKEY record from gnunet://gns/-URI to our zone; the record type is |
75 | always PKEY, if no expiration is given FOREVER is used | ||
60 | .B | 76 | .B |
61 | .IP "\-v, \-\-version" | 77 | .IP "\-v, \-\-version" |
62 | Print GNUnet version number. | 78 | Print GNUnet version number. |
63 | .B | 79 | .B |
64 | .IP "\-V VALUE, \-\-value=VALUE" | 80 | .IP "\-V VALUE, \-\-value=VALUE" |
65 | Value to store or remove from the GNS zone. Specific format depends on the record type. A records expect a dotted decimal IPv4 address, AAAA records an IPv6 address, PKEY a public key in GNUnet's printable format, and CNAME and NS records should be a domain name. | 81 | Value to store or remove from the GNS zone. Specific format depends |
82 | on the record type. A records expect a dotted decimal IPv4 address, | ||
83 | AAAA records an IPv6 address, PKEY a public key in GNUnet's printable | ||
84 | format, and CNAME and NS records should be a domain name. | ||
66 | .B | 85 | .B |
67 | .IP "\-z EGO, \-\-zone=EGO" | 86 | .IP "\-z EGO, \-\-zone=EGO" |
68 | Specifies the name of the ego controlling the private key for the zone (mandatory option) | 87 | Specifies the name of the ego controlling the private key for the zone |
88 | (mandatory option) | ||
69 | 89 | ||
70 | 90 | ||
71 | .SH BUGS | 91 | .SH BUGS |
diff --git a/doc/man/gnunet-nat-auto.1 b/doc/man/gnunet-nat-auto.1 index 249d54da4..3a2631391 100644 --- a/doc/man/gnunet-nat-auto.1 +++ b/doc/man/gnunet-nat-auto.1 | |||
@@ -24,7 +24,8 @@ Use the configuration file FILENAME. | |||
24 | 24 | ||
25 | .B | 25 | .B |
26 | .IP "\-S NAME, \-\-section=NAME" | 26 | .IP "\-S NAME, \-\-section=NAME" |
27 | Name of the configuration section with details about the configuration to test. For example "transport-tcp". | 27 | Name of the configuration section with details about the configuration |
28 | to test. For example "transport-tcp". | ||
28 | 29 | ||
29 | .IP "\-t, \-\-tcp" | 30 | .IP "\-t, \-\-tcp" |
30 | Use TCP. | 31 | Use TCP. |
@@ -35,7 +36,8 @@ Use UDP. | |||
35 | 36 | ||
36 | .B | 37 | .B |
37 | .IP "\-w, \-\-write" | 38 | .IP "\-w, \-\-write" |
38 | Write configuration to configuration file, useful in combination with autoconfiguration (\-a). | 39 | Write configuration to configuration file, useful in combination with |
40 | autoconfiguration (\-a). | ||
39 | 41 | ||
40 | .SH EXAMPLES | 42 | .SH EXAMPLES |
41 | .PP | 43 | .PP |
diff --git a/doc/man/gnunet-nat-server.1 b/doc/man/gnunet-nat-server.1 index dcf856e1c..3d79d5bc5 100644 --- a/doc/man/gnunet-nat-server.1 +++ b/doc/man/gnunet-nat-server.1 | |||
@@ -11,15 +11,40 @@ gnunet\-nat\-server \- help GNUnet setup test network setup with NAT | |||
11 | 11 | ||
12 | .SH DESCRIPTION | 12 | .SH DESCRIPTION |
13 | 13 | ||
14 | Normal GNUnet end-users should not concern themselves with gnunet\-nat\-server. In fact, distributions are encouraged to consider not shipping it at all. Running gnunet\-nat\-server's is similar to running hostlist servers: it is a special service to the community with special requirements and no benefit to those running the service. | 14 | Normal GNUnet end-users should not concern themselves with |
15 | 15 | gnunet\-nat\-server. In fact, distributions are encouraged to | |
16 | This program will listen on the specified PORT for incoming requests to test a peer's network connectivity. Incoming requests can ask it to connect to a given IPv4 address (and port) using TCP or UDP and to send a 2-byte test message using the specified address. The program can also be asked to send a "fake" ICMP response message to a given IPv4 address (for autonomous NAT traversal \-\-\- see the description in the respective research paper). | 16 | consider not shipping it at all. Running gnunet\-nat\-server's is |
17 | 17 | similar to running hostlist servers: it is a special service to the | |
18 | The idea is that gnunet\-nat\-server will be run on some trusted hosts with unrestricted connectivity to allow GNUnet users to test their network configuration. As written, the code allows any user on the Internet to cause the gnunet\-nat\-server to send 2-bytes of arbitrary data to any TCP or UDP port at any address. We believe that this is generally harmless. | 18 | community with special requirements and no benefit to those running |
19 | 19 | the service. | |
20 | When running gnunet\-nat\-server, make sure to use a configuration that disables most NAT options but enables 'enable_nat_client' and sets 'internal_address' to the global IP address of your local host. Also, the gnunet\-helper\-nat\-client should be installed locally and run with root privileges (SUID), otherwise the gnunet\-nat\-server will not work properly. | 20 | |
21 | 21 | This program will listen on the specified PORT for incoming requests | |
22 | Note that gnunet\-nat\-server could be run via gnunet\-arm but typically is not. Also, the name of the host and port that gnunet\-nat\-server is run on should be specified in the NATSERVER option in the [setup] section of the configuration file of hosts that are supposed to autoconfigure with this server. | 22 | to test a peer's network connectivity. Incoming requests can ask it |
23 | to connect to a given IPv4 address (and port) using TCP or UDP and to | ||
24 | send a 2-byte test message using the specified address. The program | ||
25 | can also be asked to send a "fake" ICMP response message to a given | ||
26 | IPv4 address (for autonomous NAT traversal \-\-\- see the description | ||
27 | in the respective research paper). | ||
28 | |||
29 | The idea is that gnunet\-nat\-server will be run on some trusted hosts | ||
30 | with unrestricted connectivity to allow GNUnet users to test their | ||
31 | network configuration. As written, the code allows any user on the | ||
32 | Internet to cause the gnunet\-nat\-server to send 2-bytes of arbitrary | ||
33 | data to any TCP or UDP port at any address. We believe that this is | ||
34 | generally harmless. | ||
35 | |||
36 | When running gnunet\-nat\-server, make sure to use a configuration | ||
37 | that disables most NAT options but enables 'enable_nat_client' and | ||
38 | sets 'internal_address' to the global IP address of your local host. | ||
39 | Also, the gnunet\-helper\-nat\-client should be installed locally and | ||
40 | run with root privileges (SUID), otherwise the gnunet\-nat\-server | ||
41 | will not work properly. | ||
42 | |||
43 | Note that gnunet\-nat\-server could be run via gnunet\-arm but | ||
44 | typically is not. Also, the name of the host and port that | ||
45 | gnunet\-nat\-server is run on should be specified in the NATSERVER | ||
46 | option in the [setup] section of the configuration file of hosts that | ||
47 | are supposed to autoconfigure with this server. | ||
23 | 48 | ||
24 | 49 | ||
25 | .SH OPTIONS | 50 | .SH OPTIONS |
diff --git a/doc/man/gnunet-nat.1 b/doc/man/gnunet-nat.1 index 0a9053444..fe9d8af3e 100644 --- a/doc/man/gnunet-nat.1 +++ b/doc/man/gnunet-nat.1 | |||
@@ -33,7 +33,8 @@ Assuming we are listening at ADDRESS for connection reversal requests. | |||
33 | 33 | ||
34 | .B | 34 | .B |
35 | .IP "\-r ADDRESS, \-\-remote=ADDRESS" | 35 | .IP "\-r ADDRESS, \-\-remote=ADDRESS" |
36 | Ask the peer at ADDRESS for connection reversal, using the local address for the target address of the reversal. | 36 | Ask the peer at ADDRESS for connection reversal, using the local |
37 | address for the target address of the reversal. | ||
37 | 38 | ||
38 | .B | 39 | .B |
39 | .IP "\-S NAME, \-\-section=NAME" | 40 | .IP "\-S NAME, \-\-section=NAME" |
@@ -41,7 +42,9 @@ Name of section in configuration file to use for additional options. | |||
41 | 42 | ||
42 | .B | 43 | .B |
43 | .IP "\-s, \-\-stun" | 44 | .IP "\-s, \-\-stun" |
44 | Enable processing of STUN requests. Will try to read UDP packets from the bind address and handle the packets if they are STUN packets. Will only work with UDP. | 45 | Enable processing of STUN requests. Will try to read UDP packets from |
46 | the bind address and handle the packets if they are STUN packets. Will | ||
47 | only work with UDP. | ||
45 | 48 | ||
46 | .B | 49 | .B |
47 | .IP "\-t, \-\-tcp" | 50 | .IP "\-t, \-\-tcp" |
@@ -53,38 +56,46 @@ Use UDP. | |||
53 | 56 | ||
54 | .B | 57 | .B |
55 | .IP "\-W, \-\-watch" | 58 | .IP "\-W, \-\-watch" |
56 | Watch for connection reversal requests. | 59 | Watch for connection reversal requests. |
57 | 60 | ||
58 | .SH EXAMPLES | 61 | .SH EXAMPLES |
59 | .PP | 62 | .PP |
60 | 63 | ||
61 | \fBBasic examples\fR | 64 | \fBBasic examples\fR |
62 | 65 | ||
63 | We are bound to "0.0.0.0:8080" on UDP and want to obtain all applicable IP addresses: | 66 | We are bound to "0.0.0.0:8080" on UDP and want to obtain all |
67 | applicable IP addresses: | ||
64 | 68 | ||
65 | # gnunet-nat -i 0.0.0.0:8080 -u | 69 | # gnunet-nat -i 0.0.0.0:8080 -u |
66 | 70 | ||
67 | We are bound to "::0" on port 8080 on TCP and want to obtain all applicable IP addresses: | 71 | We are bound to "::0" on port 8080 on TCP and want to obtain all |
72 | applicable IP addresses: | ||
68 | 73 | ||
69 | # gnunet-nat -i '[::0]':8080 -t | 74 | # gnunet-nat -i '[::0]':8080 -t |
70 | 75 | ||
71 | We are bound to "127.0.0.1:8080" on UDP and want to obtain all applicable IP addresses: | 76 | We are bound to "127.0.0.1:8080" on UDP and want to obtain all |
77 | applicable IP addresses: | ||
72 | 78 | ||
73 | # gnunet-nat -i 127.0.0.1:8080 -u | 79 | # gnunet-nat -i 127.0.0.1:8080 -u |
74 | 80 | ||
75 | \fBICMP-based NAT traversal:\fR | 81 | \fBICMP-based NAT traversal:\fR |
76 | 82 | ||
77 | Watch for connection reversal request (you must be bound to NAT range or to wildcard, 0.0.0.0), only works for IPv4: | 83 | Watch for connection reversal request (you must be bound to NAT range |
84 | or to wildcard, 0.0.0.0), only works for IPv4: | ||
78 | 85 | ||
79 | # gnunet-nat -Wt -i 192.168.178.12:8080 | 86 | # gnunet-nat -Wt -i 192.168.178.12:8080 |
80 | 87 | ||
81 | Initiate connection reversal request from peer at external IPv4 address 1.2.3.4, while we are running ourselves at 2.3.4.5:8080 (must use IPv4 addresses): | 88 | Initiate connection reversal request from peer at external IPv4 |
89 | address 1.2.3.4, while we are running ourselves at 2.3.4.5:8080 (must | ||
90 | use IPv4 addresses): | ||
82 | 91 | ||
83 | # gnunet-nat -t -r 1.2.3.4:8080 -i 2.3.4.5:8080 | 92 | # gnunet-nat -t -r 1.2.3.4:8080 -i 2.3.4.5:8080 |
84 | 93 | ||
85 | Initiate connection reversal request from peer at external IPv4 address 1.2.3.4, and let the kernel fill in whatever IPv4 address we happen to have: | 94 | Initiate connection reversal request from peer at external IPv4 |
95 | address 1.2.3.4, and let the kernel fill in whatever IPv4 address we | ||
96 | happen to have: | ||
86 | 97 | ||
87 | # gnunet-nat -t -r 1.2.3.4:8080 -i 0.0.0.0:8080 | 98 | # gnunet-nat -t -r 1.2.3.4:8080 -i 0.0.0.0:8080 |
88 | 99 | ||
89 | \fBManual hole punching:\fR | 100 | \fBManual hole punching:\fR |
90 | 101 | ||
diff --git a/doc/man/gnunet-peerinfo.1 b/doc/man/gnunet-peerinfo.1 index 6d89f461a..cfb34c36a 100644 --- a/doc/man/gnunet-peerinfo.1 +++ b/doc/man/gnunet-peerinfo.1 | |||
@@ -42,7 +42,9 @@ Add given HELLO uri to the database | |||
42 | Do not print anything but the peer identities | 42 | Do not print anything but the peer identities |
43 | .B | 43 | .B |
44 | .IP "\-s, \-\-self" | 44 | .IP "\-s, \-\-self" |
45 | Print only our own identity (together with "\-q", this is the exact line that other peers would have to put in to their friends file in order to consider this peer one of their friends in F2F mode). | 45 | Print only our own identity (together with "\-q", this is the exact |
46 | line that other peers would have to put in to their friends file in | ||
47 | order to consider this peer one of their friends in F2F mode). | ||
46 | .B | 48 | .B |
47 | .IP "\-v, \-\-version" | 49 | .IP "\-v, \-\-version" |
48 | Print the version number | 50 | Print the version number |
diff --git a/doc/man/gnunet-publish.1 b/doc/man/gnunet-publish.1 index 53a8a6563..28ee163e2 100644 --- a/doc/man/gnunet-publish.1 +++ b/doc/man/gnunet-publish.1 | |||
@@ -6,108 +6,235 @@ gnunet\-publish \- a command line interface for publishing new content into GNUn | |||
6 | [\fIOPTIONS\fR] FILENAME | 6 | [\fIOPTIONS\fR] FILENAME |
7 | .SH DESCRIPTION | 7 | .SH DESCRIPTION |
8 | .PP | 8 | .PP |
9 | In order to share files with other GNUnet users, the files must first be made available to GNUnet. GNUnet does not automatically share all files from a certain directory (however, you can do this with the gnunet\-auto\-share tool). In fact, even files that are downloaded are not automatically shared. | 9 | In order to share files with other GNUnet users, the files must first |
10 | be made available to GNUnet. GNUnet does not automatically share all | ||
11 | files from a certain directory (however, you can do this with the | ||
12 | gnunet\-auto\-share tool). In fact, even files that are downloaded | ||
13 | are not automatically shared. | ||
10 | .PP | 14 | .PP |
11 | In order to start sharing files, the files must be added either using gnunet\-publish or a graphical interface such as gnunet\-fs\-gtk. The command line tool gnunet\-publish is more useful if many files are supposed to be added. gnunet\-publish can automatically publish batches of files, recursively publish directories, create directories that can be browsed within GNUnet and publish file lists in a namespace. When run on a directory, gnunet\-publish will always recursively publish all of the files in the directory. | 15 | In order to start sharing files, the files must be added either using |
16 | gnunet\-publish or a graphical interface such as gnunet\-fs\-gtk. The | ||
17 | command line tool gnunet\-publish is more useful if many files are | ||
18 | supposed to be added. gnunet\-publish can automatically publish | ||
19 | batches of files, recursively publish directories, create directories | ||
20 | that can be browsed within GNUnet and publish file lists in a | ||
21 | namespace. When run on a directory, gnunet\-publish will always | ||
22 | recursively publish all of the files in the directory. | ||
12 | .PP | 23 | .PP |
13 | gnunet\-publish can automatically extract keywords from the files that are shared. Users that want to download files from GNUnet use keywords to search for the appropriate content. You can disable keyword extraction with the \-D option. You can manually add keywords using the \-k option. The keywords are case\-sensitive. | 24 | gnunet\-publish can automatically extract keywords from the files that |
25 | are shared. Users that want to download files from GNUnet use | ||
26 | keywords to search for the appropriate content. You can disable | ||
27 | keyword extraction with the \-D option. You can manually add keywords | ||
28 | using the \-k option. The keywords are case\-sensitive. | ||
14 | .PP | 29 | .PP |
15 | In addition to searching for files by keyword, GNUnet allows organizing files into directories. With directories, the user only needs to find the directory in order to be able to download any of the files listed in the directory. Directories can contain pointers to other directories. | 30 | In addition to searching for files by keyword, GNUnet allows |
31 | organizing files into directories. With directories, the user only | ||
32 | needs to find the directory in order to be able to download any of the | ||
33 | files listed in the directory. Directories can contain pointers to | ||
34 | other directories. | ||
16 | .PP | 35 | .PP |
17 | With gnunet\-publish, it is easy to create new directories simultaneously when adding the files. Simply pass the name of a directory instead of a file. | 36 | With gnunet\-publish, it is easy to create new directories |
37 | simultaneously when adding the files. Simply pass the name of a | ||
38 | directory instead of a file. | ||
18 | .PP | 39 | .PP |
19 | Since keywords can be spammed (any user can add any content under any keyword), GNUnet supports namespaces. A namespace is a subset of the searchspace into which only the holder of a certain pseudonym can add content. Any GNUnet user can create any number of pseudonyms using \fBgnunet\-pseudonym\fR. Pseudonyms are stored in the user's GNUnet directory. While pseudonyms are locally identified with an arbitrary string that the user selects when the pseudonym is created, the namespace is globally known only under the hash of the public key of the pseudonym. Since only the owner of the pseudonym can add content to the namespace, it is impossible for other users to pollute the namespace. gnunet\-publish automatically publishes the top\-directory (or the only file if only one file is specified) into the namespace if a pseudonym is specified. | 40 | Since keywords can be spammed (any user can add any content under any |
41 | keyword), GNUnet supports namespaces. A namespace is a subset of the | ||
42 | searchspace into which only the holder of a certain pseudonym can add | ||
43 | content. Any GNUnet user can create any number of pseudonyms using | ||
44 | \fBgnunet\-pseudonym\fR. Pseudonyms are stored in the user's GNUnet | ||
45 | directory. While pseudonyms are locally identified with an arbitrary | ||
46 | string that the user selects when the pseudonym is created, the | ||
47 | namespace is globally known only under the hash of the public key of | ||
48 | the pseudonym. Since only the owner of the pseudonym can add content | ||
49 | to the namespace, it is impossible for other users to pollute the | ||
50 | namespace. gnunet\-publish automatically publishes the top\-directory | ||
51 | (or the only file if only one file is specified) into the namespace if | ||
52 | a pseudonym is specified. | ||
20 | .PP | 53 | .PP |
21 | It is possible to update content in GNUnet if that content was placed and obtained from a particular namespace. Updates are only possible for content in namespaces since this is the only way to assure that a malicious party can not supply counterfeited updates. Note that an update with GNUnet does not make the old content unavailable, GNUnet merely allows the publisher to point users to more recent versions. You can use the \-N option to specify the future identifier of an update. When using this option, a GNUnet client that finds the current (\-t) identifier will automatically begin a search for the update (\-N) identifier. If you later publish an update under the (\-N) identifier, both results will be given to the user. | 54 | It is possible to update content in GNUnet if that content was placed |
55 | and obtained from a particular namespace. Updates are only possible | ||
56 | for content in namespaces since this is the only way to assure that a | ||
57 | malicious party can not supply counterfeited updates. Note that an | ||
58 | update with GNUnet does not make the old content unavailable, GNUnet | ||
59 | merely allows the publisher to point users to more recent | ||
60 | versions. You can use the \-N option to specify the future identifier | ||
61 | of an update. When using this option, a GNUnet client that finds the | ||
62 | current (\-t) identifier will automatically begin a search for the | ||
63 | update (\-N) identifier. If you later publish an update under the | ||
64 | (\-N) identifier, both results will be given to the user. | ||
22 | .PP | 65 | .PP |
23 | You can use automatic meta\-data extraction (based on libextractor) or the command\-line option \-m to specify meta-data. For the \-m option you need to use the form keyword\-type:value. For example, use "\-m os:Linux" to specify that the operating system is Linux. Common meta\-data types are "author", "title" , "mimetype", "filename", "language", "subject" and "keywords". A full list can be obtained from the extract tool using the option \-\-list. The meta\-data is used to help users in searching for files on the network. The keywords are case\-sensitive. | 66 | You can use automatic meta\-data extraction (based on libextractor) or |
67 | the command\-line option \-m to specify meta-data. For the \-m option | ||
68 | you need to use the form keyword\-type:value. For example, use "\-m | ||
69 | os:Linux" to specify that the operating system is Linux. Common | ||
70 | meta\-data types are "author", "title" , "mimetype", "filename", | ||
71 | "language", "subject" and "keywords". A full list can be obtained | ||
72 | from the extract tool using the option \-\-list. The meta\-data is | ||
73 | used to help users in searching for files on the network. The | ||
74 | keywords are case\-sensitive. | ||
24 | .PP | 75 | .PP |
25 | GNUnet supports two styles of publishing files on the network. Publishing a file means that a copy of the file is made in the local (!) database of the node. Indexing a file means that an index is added to the local (!) database with symbolic links to the file itself. The links will use the SHA-512 hash of the entire file as the filename. Indexing is generally significantly more efficient and the default choice. However, indexing only works if the indexed file can be read (using the same absolute path) by gnunet-service-fs. If this is not the case, indexing will fail (and gnunet\-publish will automatically revert to publishing instead). Regardless of which method is used to publish the file, the file will be slowly (depending on how often it is requested and on how much bandwidth is available) dispersed into the network. If you publish or index a file and then leave the network, it will almost always NOT be available anymore. | 76 | GNUnet supports two styles of publishing files on the |
26 | 77 | network. Publishing a file means that a copy of the file is made in | |
27 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR | 78 | the local (!) database of the node. Indexing a file means that an |
28 | Use alternate config file (if this option is not specified, the default is ~/.config/gnunet.conf). | 79 | index is added to the local (!) database with symbolic links to the |
80 | file itself. The links will use the SHA-512 hash of the entire file | ||
81 | as the filename. Indexing is generally significantly more efficient | ||
82 | and the default choice. However, indexing only works if the indexed | ||
83 | file can be read (using the same absolute path) by gnunet-service-fs. | ||
84 | If this is not the case, indexing will fail (and gnunet\-publish will | ||
85 | automatically revert to publishing instead). Regardless of which | ||
86 | method is used to publish the file, the file will be slowly (depending | ||
87 | on how often it is requested and on how much bandwidth is available) | ||
88 | dispersed into the network. If you publish or index a file and then | ||
89 | leave the network, it will almost always NOT be available anymore. | ||
90 | |||
91 | \fB\-c \fIFILENAME\fR, \fB\-\-config=FILENAME\fR Use alternate config | ||
92 | file (if this option is not specified, the default is | ||
93 | ~/.config/gnunet.conf). | ||
29 | 94 | ||
30 | .TP | 95 | .TP |
31 | \fB\-D\fR, \fB\-\-disable\-extractor\fR | 96 | \fB\-D\fR, \fB\-\-disable\-extractor\fR Disable use of GNU |
32 | Disable use of GNU libextractor for finding additional keywords and metadata. | 97 | libextractor for finding additional keywords and metadata. |
33 | 98 | ||
34 | .TP | 99 | .TP |
35 | \fB\-d\fR, \fB\-\-disable\-creation\-time\fR | 100 | \fB\-d\fR, \fB\-\-disable\-creation\-time\fR Disable use of creation |
36 | Disable use of creation time timestamp in metadata. Useful to make created directories deterministic and to avoid leaking information about the time at which a file was made available. | 101 | time timestamp in metadata. Useful to make created directories |
102 | deterministic and to avoid leaking information about the time at which | ||
103 | a file was made available. | ||
37 | 104 | ||
38 | .TP | 105 | .TP |
39 | \fB\-e\fR, \fB\-\-extract\fR | 106 | \fB\-e\fR, \fB\-\-extract\fR Print the list of keywords that will be |
40 | Print the list of keywords that will be used for each file given the current options. Do not perform any indexing or publishing. | 107 | used for each file given the current options. Do not perform any |
108 | indexing or publishing. | ||
41 | 109 | ||
42 | .TP | 110 | .TP |
43 | \fB\-h\fR, \fB\-\-help\fR | 111 | \fB\-h\fR, \fB\-\-help\fR Print a brief help page with all the |
44 | Print a brief help page with all the options. | 112 | options. |
45 | 113 | ||
46 | .TP | 114 | .TP |
47 | \fB\-k \fIKEYWORD\fR, \fB\-\-key=KEYWORD\fR | 115 | \fB\-k \fIKEYWORD\fR, \fB\-\-key=KEYWORD\fR additional key to index |
48 | additional key to index the content with (to add multiple keys, specify multiple times). Each additional key is case\-sensitive. Can be specified multiple times. The keyword is only applied to the top\-level file or directory. | 116 | the content with (to add multiple keys, specify multiple times). Each |
117 | additional key is case\-sensitive. Can be specified multiple times. | ||
118 | The keyword is only applied to the top\-level file or directory. | ||
49 | 119 | ||
50 | .TP | 120 | .TP |
51 | \fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=\fILOGLEVEL\fR | 121 | \fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=\fILOGLEVEL\fR Change the |
52 | Change the loglevel. Possible values for LOGLEVEL are | 122 | loglevel. Possible values for LOGLEVEL are ERROR, WARNING, INFO and |
53 | ERROR, WARNING, INFO and DEBUG. | 123 | DEBUG. |
54 | 124 | ||
55 | .TP | 125 | .TP |
56 | \fB\-m \fITYPE:VALUE\fR, \fB\-\-meta=\fITYPE:VALUE\fR | 126 | \fB\-m \fITYPE:VALUE\fR, \fB\-\-meta=\fITYPE:VALUE\fR For the main |
57 | For the main file (or directory), set the metadata of the given TYPE to the given VALUE. Note that this will not add the respective VALUE to the set of keywords under which the file can be found. | 127 | file (or directory), set the metadata of the given TYPE to the given |
128 | VALUE. Note that this will not add the respective VALUE to the set of | ||
129 | keywords under which the file can be found. | ||
58 | 130 | ||
59 | .TP | 131 | .TP |
60 | \fB\-n\fR, \fB\-\-noindex\fR | 132 | \fB\-n\fR, \fB\-\-noindex\fR Executive summary: You probably don't |
61 | Executive summary: You probably don't need it. | 133 | need it. |
62 | 134 | ||
63 | Do not index, full publishing. Note that directories, information for keyword search, namespace search and indexing data are always published (even without this option). With this option, every block of the actual files is stored in encrypted form in the block database of the local peer. While this adds security if the local node is compromised (the adversary snags your machine), it is significantly less efficient compared to on\-demand encryption and is definitely not recommended for large files. | 135 | Do not index, full publishing. Note that directories, information for |
136 | keyword search, namespace search and indexing data are always | ||
137 | published (even without this option). With this option, every block | ||
138 | of the actual files is stored in encrypted form in the block database | ||
139 | of the local peer. While this adds security if the local node is | ||
140 | compromised (the adversary snags your machine), it is significantly | ||
141 | less efficient compared to on\-demand encryption and is definitely not | ||
142 | recommended for large files. | ||
64 | 143 | ||
65 | .TP | 144 | .TP |
66 | \fB\-N \fIID\fR, \fB\-\-next=\fIID\fR | 145 | \fB\-N \fIID\fR, \fB\-\-next=\fIID\fR Specifies the next identifier of |
67 | Specifies the next identifier of a future version of the file to be published under the same pseudonym. This option is only valid together with the \-P option. This option can be used to specify what the identifier of an updated version will look like. Note that specifying \-i and \-N without \-t is not allowed. | 146 | a future version of the file to be published under the same pseudonym. |
147 | This option is only valid together with the \-P option. This option | ||
148 | can be used to specify what the identifier of an updated version will | ||
149 | look like. Note that specifying \-i and \-N without \-t is not | ||
150 | allowed. | ||
68 | 151 | ||
69 | .TP | 152 | .TP |
70 | \fB\-p \fIPRIORITY\fR, \fB\-\-prio=\fIPRIORITY\fR | 153 | \fB\-p \fIPRIORITY\fR, \fB\-\-prio=\fIPRIORITY\fR Executive summary: |
71 | Executive summary: You probably don't need it. | 154 | You probably don't need it. |
72 | 155 | ||
73 | Set the priority of the published content (default: 365). If the local database is full, GNUnet will discard the content with the lowest ranking. Note that ranks change over time depending on popularity. The default should be high enough to preserve the locally published content in favor of content that migrates from other peers. | 156 | Set the priority of the published content (default: 365). If the |
157 | local database is full, GNUnet will discard the content with the | ||
158 | lowest ranking. Note that ranks change over time depending on | ||
159 | popularity. The default should be high enough to preserve the locally | ||
160 | published content in favor of content that migrates from other peers. | ||
74 | 161 | ||
75 | .TP | 162 | .TP |
76 | \fB\-P \fINAME\fR, \fB\-\-pseudonym=\fINAME\fR | 163 | \fB\-P \fINAME\fR, \fB\-\-pseudonym=\fINAME\fR For the top\-level |
77 | For the top\-level directory or file, places the file into the namespace identified by the pseudonym NAME. NAME must be a valid pseudonym managed by gnunet\-identity. | 164 | directory or file, places the file into the namespace identified by |
165 | the pseudonym NAME. NAME must be a valid pseudonym managed by | ||
166 | gnunet\-identity. | ||
78 | 167 | ||
79 | .TP | 168 | .TP |
80 | \fB\-r \fILEVEL\fR, \fB\-\-replication=\fILEVEL\fR | 169 | \fB\-r \fILEVEL\fR, \fB\-\-replication=\fILEVEL\fR Set the desired |
81 | Set the desired replication level. If CONTENT_PUSHING is set to YES, GNUnet will push each block (for the file) LEVEL times to other peers before doing normal "random" replication of all content. This option can be used to push some content out into the network harder. Note that pushing content LEVEL times into the network does not guarantee that there will actually be LEVEL replicas. | 170 | replication level. If CONTENT_PUSHING is set to YES, GNUnet will push |
171 | each block (for the file) LEVEL times to other peers before doing | ||
172 | normal "random" replication of all content. This option can be used | ||
173 | to push some content out into the network harder. Note that pushing | ||
174 | content LEVEL times into the network does not guarantee that there | ||
175 | will actually be LEVEL replicas. | ||
82 | 176 | ||
83 | .TP | 177 | .TP |
84 | \fB\-s\fR, \fB\-\-simulate-only\fR | 178 | \fB\-s\fR, \fB\-\-simulate-only\fR When this option is used, |
85 | When this option is used, gnunet\-publish will not actually publish the file but just simulate what would be done. This can be used to compute the GNUnet URI for a file without actually sharing it. | 179 | gnunet\-publish will not actually publish the file but just simulate |
180 | what would be done. This can be used to compute the GNUnet URI for a | ||
181 | file without actually sharing it. | ||
86 | 182 | ||
87 | .TP | 183 | .TP |
88 | \fB\-t \fIID\fR, \fB\-\-this=\fIID\fR | 184 | \fB\-t \fIID\fR, \fB\-\-this=\fIID\fR Specifies the identifier under |
89 | Specifies the identifier under which the file is to be published under a pseudonym. This option is only valid together with the\ \-P option. | 185 | which the file is to be published under a pseudonym. This option is |
186 | only valid together with the\ \-P option. | ||
90 | 187 | ||
91 | .TP | 188 | .TP |
92 | \fB\-u \fIURI\fR, \fB\-\-uri=\fIURI\fR | 189 | \fB\-u \fIURI\fR, \fB\-\-uri=\fIURI\fR This option can be used to |
93 | This option can be used to specify the URI of a file instead of a filename (this is the only case where the otherwise mandatory filename argument must be omitted). Instead of publishing a file or directory and using the corresponding URI, gnunet\-publish will use this URI and perform the selected namespace or keyword operations. This can be used to add additional keywords to a file that has already been shared or to add files to a namespace for which the URI is known but the content is not locally available. | 190 | specify the URI of a file instead of a filename (this is the only case |
191 | where the otherwise mandatory filename argument must be omitted). | ||
192 | Instead of publishing a file or directory and using the corresponding | ||
193 | URI, gnunet\-publish will use this URI and perform the selected | ||
194 | namespace or keyword operations. This can be used to add additional | ||
195 | keywords to a file that has already been shared or to add files to a | ||
196 | namespace for which the URI is known but the content is not locally | ||
197 | available. | ||
94 | 198 | ||
95 | .TP | 199 | .TP |
96 | \fB\-v\fR, \fB\-\-version\fR | 200 | \fB\-v\fR, \fB\-\-version\fR Print the version number. |
97 | Print the version number. | ||
98 | 201 | ||
99 | .TP | 202 | .TP |
100 | \fB\-V\fR, \fB\-\-verbose\fR | 203 | \fB\-V\fR, \fB\-\-verbose\fR Be verbose. Using this option causes |
101 | Be verbose. Using this option causes gnunet\-publish to print progress information and at the end the file identification that can be used to download the file from GNUnet. | 204 | gnunet\-publish to print progress information and at the end the file |
205 | identification that can be used to download the file from GNUnet. | ||
102 | 206 | ||
103 | 207 | ||
104 | .SH SETTING ANONYMITY LEVEL | 208 | .SH SETTING ANONYMITY LEVEL |
105 | 209 | ||
106 | The \fB\-a\fR option can be used to specify additional anonymity constraints. If set to 0, GNUnet will publish the file non-anonymously and in fact sign the advertisement for the file using your peer's private key. This will allow other users to download the file as fast as possible, including using non-anonymous methods (DHT, direct transfer). If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity. You can gain better privacy by specifying a higher level of anonymity, which increases the amount of cover traffic your own traffic will get, at the expense of performance. Note that regardless of the anonymity level you choose, peers that cache content in the network always use anonymity level 1. | 210 | The \fB\-a\fR option can be used to specify additional anonymity |
107 | 211 | constraints. If set to 0, GNUnet will publish the file non-anonymously | |
108 | The definition of the ANONYMITY LEVEL is the following. 0 means no anonymity is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" traffic can be from the local user, leaving 'v-1' bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign peers (using anonymous routing), it may originate n/(v-1) bytes of data in the same time\-period. The time\-period is twice the average delay that GNUnet defers forwarded queries. | 212 | and in fact sign the advertisement for the file using your peer's |
109 | 213 | private key. This will allow other users to download the file as fast | |
110 | The default is 1 and this should be fine for most users. Also notice that if you choose very large values, you may end up having no throughput at all, especially if many of your fellow GNUnet\-peers all do the same. | 214 | as possible, including using non-anonymous methods (DHT, direct |
215 | transfer). If you set it to 1 (default), you use the standard | ||
216 | anonymous routing algorithm (which does not explicitly leak your | ||
217 | identity). However, a powerful adversary may still be able to perform | ||
218 | traffic analysis (statistics) to over time infer data about your | ||
219 | identity. You can gain better privacy by specifying a higher level of | ||
220 | anonymity, which increases the amount of cover traffic your own | ||
221 | traffic will get, at the expense of performance. Note that regardless | ||
222 | of the anonymity level you choose, peers that cache content in the | ||
223 | network always use anonymity level 1. | ||
224 | |||
225 | The definition of the ANONYMITY LEVEL is the following. 0 means no | ||
226 | anonymity is required. Otherwise a value of 'v' means that 1 out of v | ||
227 | bytes of "anonymous" traffic can be from the local user, leaving 'v-1' | ||
228 | bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n | ||
229 | bytes of messages from foreign peers (using anonymous routing), it may | ||
230 | originate n/(v-1) bytes of data in the same time\-period. The | ||
231 | time\-period is twice the average delay that GNUnet defers forwarded | ||
232 | queries. | ||
233 | |||
234 | The default is 1 and this should be fine for most users. Also notice | ||
235 | that if you choose very large values, you may end up having no | ||
236 | throughput at all, especially if many of your fellow GNUnet\-peers all | ||
237 | do the same. | ||
111 | 238 | ||
112 | 239 | ||
113 | .SH EXAMPLES | 240 | .SH EXAMPLES |
@@ -127,37 +254,55 @@ Index a file COPYING with the keywords \fBgpl\fR and \fBtest\fR: | |||
127 | 254 | ||
128 | # gnunet\-publish \-k gpl \-k test COPYING | 255 | # gnunet\-publish \-k gpl \-k test COPYING |
129 | 256 | ||
130 | Index a file COPYING with description "GNU License", mime-type "text/plain" and keywords \fBgpl\fR and \fBtest\fR: | 257 | Index a file COPYING with description "GNU License", mime-type |
258 | "text/plain" and keywords \fBgpl\fR and \fBtest\fR: | ||
131 | 259 | ||
132 | # gnunet\-publish \-m "description:GNU License" \-k gpl \-k test \-m "mimetype:text/plain" COPYING | 260 | # gnunet\-publish \-m "description:GNU License" \-k gpl \-k test \-m |
261 | "mimetype:text/plain" COPYING | ||
133 | 262 | ||
134 | \fBUsing directories\fR | 263 | \fBUsing directories\fR |
135 | 264 | ||
136 | Index the files COPYING and AUTHORS with keyword \fBtest\fR and build a directory containing the two files. Make the directory itself available under keyword \fBgnu\fR and disable keyword extraction using libextractor: | 265 | Index the files COPYING and AUTHORS with keyword \fBtest\fR and build |
266 | a directory containing the two files. Make the directory itself | ||
267 | available under keyword \fBgnu\fR and disable keyword extraction using | ||
268 | libextractor: | ||
137 | 269 | ||
138 | # mkdir gnu | 270 | # mkdir gnu mv COPYING AUTHORS gnu/ gnunet\-publish \-k test \-k gnu |
139 | # mv COPYING AUTHORS gnu/ | 271 | # \-D gnu/ |
140 | # gnunet\-publish \-k test \-k gnu \-D gnu/ | ||
141 | 272 | ||
142 | Neatly publish an image gallery in \fBkittendir/\fR and its subdirs with keyword \fBkittens\fR for the directory but no keywords for the individual files or subdirs (\-n). Force description for all files: | 273 | Neatly publish an image gallery in \fBkittendir/\fR and its subdirs |
274 | with keyword \fBkittens\fR for the directory but no keywords for the | ||
275 | individual files or subdirs (\-n). Force description for all files: | ||
143 | 276 | ||
144 | # gnunet\-publish \-n \-m "description:Kitten collection" \-k kittens kittendir/ | 277 | # gnunet\-publish \-n \-m "description:Kitten collection" \-k kittens |
278 | kittendir/ | ||
145 | 279 | ||
146 | \fBSecure publishing with namespaces\fR | 280 | \fBSecure publishing with namespaces\fR |
147 | 281 | ||
148 | Publish file COPYING with pseudonym RIAA-2 (\-P) and with identifier \fBgpl\fR (\-t) and no updates: | 282 | Publish file COPYING with pseudonym RIAA-2 (\-P) and with identifier |
283 | \fBgpl\fR (\-t) and no updates: | ||
149 | 284 | ||
150 | # gnunet\-publish \-P RIAA-2 \-t gpl COPYING | 285 | # gnunet\-publish \-P RIAA-2 \-t gpl COPYING |
151 | 286 | ||
152 | Recursively index /home/ogg and build a matching directory structure. Publish the top\-level directory into the namespace under the pseudonym RIAA\-2 (\-P) under identifier 'MUSIC' (\-t) and promise to provide an update with identifier 'VIDEOS' (\-N): | 287 | Recursively index /home/ogg and build a matching directory |
288 | structure. Publish the top\-level directory into the namespace under | ||
289 | the pseudonym RIAA\-2 (\-P) under identifier 'MUSIC' (\-t) and promise | ||
290 | to provide an update with identifier 'VIDEOS' (\-N): | ||
153 | 291 | ||
154 | # gnunet\-publish \-P RIAA-2 \-t MUSIC \-N VIDEOS /home/ogg | 292 | # gnunet\-publish \-P RIAA-2 \-t MUSIC \-N VIDEOS /home/ogg |
155 | 293 | ||
156 | Recursively publish (\-n) /var/lib/mysql and build a matching directory structure, but disable the use of libextractor to extract keywords (\-n). Print the file identifiers (\-V) that can be used to retrieve the files. This will store a copy of the MySQL database in GNUnet but without adding any keywords to search for it. Thus only people that have been told the secret file identifiers printed with the \-V option can retrieve the (secret?) files: | 294 | Recursively publish (\-n) /var/lib/mysql and build a matching |
295 | directory structure, but disable the use of libextractor to extract | ||
296 | keywords (\-n). Print the file identifiers (\-V) that can be used to | ||
297 | retrieve the files. This will store a copy of the MySQL database in | ||
298 | GNUnet but without adding any keywords to search for it. Thus only | ||
299 | people that have been told the secret file identifiers printed with | ||
300 | the \-V option can retrieve the (secret?) files: | ||
157 | 301 | ||
158 | # gnunet\-publish \-nV /var/lib/mysql | 302 | # gnunet\-publish \-nV /var/lib/mysql |
159 | 303 | ||
160 | Create a namespace entry 'root' in namespace MPAA-1 and announce that the next update will be called 'next': | 304 | Create a namespace entry 'root' in namespace MPAA-1 and announce that |
305 | the next update will be called 'next': | ||
161 | 306 | ||
162 | # gnunet\-publish \-P MPAA-1 \-t root \-N next noise.mp3 | 307 | # gnunet\-publish \-P MPAA-1 \-t root \-N next noise.mp3 |
163 | 308 | ||
diff --git a/doc/man/gnunet-qr.1 b/doc/man/gnunet-qr.1 index 6c3261d02..f1baf85ac 100644 --- a/doc/man/gnunet-qr.1 +++ b/doc/man/gnunet-qr.1 | |||
@@ -9,7 +9,8 @@ gnunet\-qr \- Scan a QR code using a video device and import. | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-qr\fP is a command line tool to scan a QR code using a video device and import. | 12 | \fBgnunet\-qr\fP is a command line tool to scan a QR code using a |
13 | video device and import. | ||
13 | 14 | ||
14 | .SH OPTIONS | 15 | .SH OPTIONS |
15 | .B | 16 | .B |
diff --git a/doc/man/gnunet-resolver.1 b/doc/man/gnunet-resolver.1 index 0c314bc66..7e16932ac 100644 --- a/doc/man/gnunet-resolver.1 +++ b/doc/man/gnunet-resolver.1 | |||
@@ -20,7 +20,8 @@ Use the configuration file FILENAME. | |||
20 | Print short help on options. | 20 | Print short help on options. |
21 | .B | 21 | .B |
22 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" | 22 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" |
23 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 23 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and |
24 | ERROR. | ||
24 | .B | 25 | .B |
25 | .IP "\-l LOGFILE, \-\-logfile=LOGFILE" | 26 | .IP "\-l LOGFILE, \-\-logfile=LOGFILE" |
26 | Configure logging to write logs to LOGFILE. | 27 | Configure logging to write logs to LOGFILE. |
diff --git a/doc/man/gnunet-revocation.1 b/doc/man/gnunet-revocation.1 index 9043c286e..b963b2dc0 100644 --- a/doc/man/gnunet-revocation.1 +++ b/doc/man/gnunet-revocation.1 | |||
@@ -9,21 +9,48 @@ gnunet\-revocation \- revoke private keys (of egos) in GNUnet | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-revocation\fP can be used to verify if a key has been revoked, to create a revocation certificate for later revocation, to instantly revoke a key and to use a pre-generated revocation certificate to revoke a key. Upon successful revocation, all peers will be informed about the invalidity of the key. As this is an expensive operation, GNUnet requires the issuer of the revocation to perform an expensive proof-of-work computation before he will be allowed to perform the revocation. gnunet\-revocation will perform this computation. The computation can be performed ahead of time, with the resulting revocation certificate being stored in a file for later "instant" use. gnunet\-revocation also makes is possible to resume the pre-calculation of a revocation --- simply abort a running proof-of-work calculation with CTRL-C, and the existing revocation certificate file will contain the status of the computation. Note that performing a revocation proof-of-work is deliberately VERY expensive. Depending on your CPU, the calculation can take days or weeks. | 12 | \fBgnunet\-revocation\fP can be used to verify if a key has been |
13 | revoked, to create a revocation certificate for later revocation, to | ||
14 | instantly revoke a key and to use a pre-generated revocation | ||
15 | certificate to revoke a key. Upon successful revocation, all peers | ||
16 | will be informed about the invalidity of the key. As this is an | ||
17 | expensive operation, GNUnet requires the issuer of the revocation to | ||
18 | perform an expensive proof-of-work computation before they will be | ||
19 | allowed to perform the revocation. gnunet\-revocation will perform | ||
20 | this computation. The computation can be performed ahead of time, | ||
21 | with the resulting revocation certificate being stored in a file for | ||
22 | later "instant" use. gnunet\-revocation also makes is possible to | ||
23 | resume the pre-calculation of a revocation --- simply abort a running | ||
24 | proof-of-work calculation with CTRL-C, and the existing revocation | ||
25 | certificate file will contain the status of the computation. Note | ||
26 | that performing a revocation proof-of-work is deliberately VERY | ||
27 | expensive. Depending on your CPU, the calculation can take days or | ||
28 | weeks. | ||
13 | 29 | ||
14 | .SH OPTIONS | 30 | .SH OPTIONS |
15 | .B | 31 | .B |
16 | .IP "\-t KEY, \-\-test=KEY" | 32 | .IP "\-t KEY, \-\-test=KEY" |
17 | Check if the given KEY (ASCII\-encoded public key required) has been revoked. | 33 | Check if the given KEY (ASCII\-encoded public key required) has been |
34 | revoked. | ||
18 | .B | 35 | .B |
19 | .IP "\-R NAME, \-\-revoke=NAME" | 36 | .IP "\-R NAME, \-\-revoke=NAME" |
20 | Calculate or perform revocation for the ego with the given NAME. | 37 | Calculate or perform revocation for the ego with the given NAME. |
21 | .B | 38 | .B |
22 | .IP "\-p, \-\-perform" | 39 | .IP "\-p, \-\-perform" |
23 | Actually perform the revocation as soon as possible (do not just generate a revocation certificate, use it). Must be supplied to actually perform the revocation. | 40 | Actually perform the revocation as soon as possible (do not just |
41 | generate a revocation certificate, use it). Must be supplied to | ||
42 | actually perform the revocation. | ||
24 | .B | 43 | .B |
25 | .IP "\-f NAME, \-\-filename=NAME" | 44 | .IP "\-f NAME, \-\-filename=NAME" |
26 | Use NAME as the name of the file that is to contain the revocation certificate. Intermediate computation results will be stored here, as well as the final revocation certificate. When used together with \-p, this file will be inspected to see if it contains a valid certificate for instant revocation, in which case the revocation can be performed instantly. If the given file contains anything (a valid certificate, with or without the completed proof-of-work) there is no need to supply the "\-R" option or to still have the private key of the ego to perform the revocation. | 45 | Use NAME as the name of the file that is to contain the revocation |
46 | certificate. Intermediate computation results will be stored here, as | ||
47 | well as the final revocation certificate. When used together with | ||
48 | \-p, this file will be inspected to see if it contains a valid | ||
49 | certificate for instant revocation, in which case the revocation can | ||
50 | be performed instantly. If the given file contains anything (a valid | ||
51 | certificate, with or without the completed proof-of-work) there is no | ||
52 | need to supply the "\-R" option or to still have the private key of | ||
53 | the ego to perform the revocation. | ||
27 | .B | 54 | .B |
28 | .IP "\-c FILENAME, \-\-config=FILENAME" | 55 | .IP "\-c FILENAME, \-\-config=FILENAME" |
29 | Use the configuration file FILENAME. | 56 | Use the configuration file FILENAME. |
@@ -32,7 +59,8 @@ Use the configuration file FILENAME. | |||
32 | Print short help on options. | 59 | Print short help on options. |
33 | .B | 60 | .B |
34 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" | 61 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" |
35 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 62 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and |
63 | ERROR. | ||
36 | .B | 64 | .B |
37 | .IP "\-v, \-\-version" | 65 | .IP "\-v, \-\-version" |
38 | Print GNUnet version number. | 66 | Print GNUnet version number. |
diff --git a/doc/man/gnunet-scalarproduct.1 b/doc/man/gnunet-scalarproduct.1 index 73081e2ed..0159e1eb9 100644 --- a/doc/man/gnunet-scalarproduct.1 +++ b/doc/man/gnunet-scalarproduct.1 | |||
@@ -9,7 +9,8 @@ gnunet\-vectorproduct \- compute a vectorproduct | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet-vectorproduct\fP enables you to compute a vectorproduct across two peers \fBAlice\fP and \fBBob\fP. | 12 | \fBgnunet-vectorproduct\fP enables you to compute a vectorproduct |
13 | across two peers \fBAlice\fP and \fBBob\fP. | ||
13 | 14 | ||
14 | A client can issue one of two messages to its service: | 15 | A client can issue one of two messages to its service: |
15 | .TS | 16 | .TS |
@@ -23,30 +24,51 @@ Elements to support a peer in computing a vectorproduct (\fBBob\fP) | |||
23 | T} | 24 | T} |
24 | .TE | 25 | .TE |
25 | 26 | ||
26 | Both requests must share the same SID, which can be an arbitrary string identifying the session. SIDs should be unique, however it is sufficient to guarantee the uniqueness of the tupel element count and session ID. | 27 | Both requests must share the same SID, which can be an arbitrary |
28 | string identifying the session. SIDs should be unique, however it is | ||
29 | sufficient to guarantee the uniqueness of the tupel element count and | ||
30 | session ID. | ||
27 | 31 | ||
28 | \fBAlice\fP\'s client must supply the ASCII encoded peer ID of bob\'s service, it will internally be checked by the client for validity. Invalid values here result in the client or the service failing the session. | 32 | \fBAlice\fP\'s client must supply the ASCII encoded peer ID of bob\'s |
33 | service, it will internally be checked by the client for | ||
34 | validity. Invalid values here result in the client or the service | ||
35 | failing the session. | ||
29 | 36 | ||
30 | Elements are handed over as signed decimal integers, the element count supplied by \fBAlice\fP and \fBBob\fP must match. \fBAlice\fP can also supply a mask for these values to her service, which allows partial vector products to be computed across the vector. Elements can be masked by setting their the corresponding mask element to zero, any other value means the element will not be masked. \fBAlice\fP\'s client will also mask all 0-values to avoid information leakage to \fBBob\fP. | 37 | Elements are handed over as signed decimal integers, the element count |
38 | supplied by \fBAlice\fP and \fBBob\fP must match. \fBAlice\fP can also | ||
39 | supply a mask for these values to her service, which allows partial | ||
40 | vector products to be computed across the vector. Elements can be | ||
41 | masked by setting their the corresponding mask element to zero, any | ||
42 | other value means the element will not be masked. \fBAlice\fP\'s | ||
43 | client will also mask all 0-values to avoid information leakage to | ||
44 | \fBBob\fP. | ||
31 | 45 | ||
32 | The protocol by definition relies on \fBAlice\fP and \fBBob\fP being benign, thus \fBBob\fP can arbitrarily falsify his information. Both peers collaborate to achieve a correct result. | 46 | The protocol by definition relies on \fBAlice\fP and \fBBob\fP being |
47 | benign, thus \fBBob\fP can arbitrarily falsify his information. Both | ||
48 | peers collaborate to achieve a correct result. | ||
33 | 49 | ||
34 | .SH OPTIONS | 50 | .SH OPTIONS |
35 | .B | 51 | .B |
36 | .IP "\-e ELEMENTS, \-\-elements=ELEMENTS" | 52 | .IP "\-e ELEMENTS, \-\-elements=ELEMENTS" |
37 | The element-vector the vectorproduct should be computed over in signed decimal form, eg: \"42,1,-3,3,7\". Zero value elements will be automatically masked. | 53 | The element-vector the vectorproduct should be computed over in signed |
54 | decimal form, eg: \"42,1,-3,3,7\". Zero value elements will be automatically masked. | ||
38 | .B | 55 | .B |
39 | .IP "\-m MASK, \-\-mask=MASK" | 56 | .IP "\-m MASK, \-\-mask=MASK" |
40 | Elements in the vector can be masked. There must be at least two elements left in the vector to compute a vectorproduct. Non-Zero values indicate an element is not maskes. | 57 | Elements in the vector can be masked. There must be at least two |
58 | elements left in the vector to compute a vectorproduct. Non-Zero | ||
59 | values indicate an element is not maskes. | ||
41 | .B | 60 | .B |
42 | .IP "\-k KEY, \-\-key=KEY" | 61 | .IP "\-k KEY, \-\-key=KEY" |
43 | The session key, a shared string of arbitrary length from which the SID will be generated | 62 | The session key, a shared string of arbitrary length from which the |
63 | SID will be generated | ||
44 | .B | 64 | .B |
45 | .IP "\-c FILENAME, \-\-config=FILENAME" | 65 | .IP "\-c FILENAME, \-\-config=FILENAME" |
46 | Use the configuration file FILENAME. | 66 | Use the configuration file FILENAME. |
47 | .B | 67 | .B |
48 | .IP "\-p PEERID, \-\-peer=PEERID" | 68 | .IP "\-p PEERID, \-\-peer=PEERID" |
49 | The remote peer\'s ASCII-armored gnunet-peer ID as output by gnunet-peerinfo. If this option is not given, the peer will take the \fBBob\fP\'s role. | 69 | The remote peer\'s ASCII-armored gnunet-peer ID as output by |
70 | gnunet-peerinfo. If this option is not given, the peer will take the | ||
71 | \fBBob\fP\'s role. | ||
50 | .B | 72 | .B |
51 | .IP "\-h, \-\-help" | 73 | .IP "\-h, \-\-help" |
52 | Print short help on options. | 74 | Print short help on options. |
diff --git a/doc/man/gnunet-scrypt.1 b/doc/man/gnunet-scrypt.1 index 3b11ca52e..147b18fbe 100644 --- a/doc/man/gnunet-scrypt.1 +++ b/doc/man/gnunet-scrypt.1 | |||
@@ -9,7 +9,8 @@ gnunet\-scrypt \- Manipulate GNUnet proof of work files. | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-scrypt\fP is a command line tool to manipulate GNUnet proof of work files. | 12 | \fBgnunet\-scrypt\fP is a command line tool to manipulate GNUnet proof |
13 | of work files. | ||
13 | 14 | ||
14 | .SH OPTIONS | 15 | .SH OPTIONS |
15 | .B | 16 | .B |
diff --git a/doc/man/gnunet-search.1 b/doc/man/gnunet-search.1 index 7f30812e0..1e0973b63 100644 --- a/doc/man/gnunet-search.1 +++ b/doc/man/gnunet-search.1 | |||
@@ -9,17 +9,49 @@ gnunet\-search \- a command line interface to search for content on GNUnet | |||
9 | [\fIOPTIONS\fR] [+]\fIURI\fR | 9 | [\fIOPTIONS\fR] [+]\fIURI\fR |
10 | .SH DESCRIPTION | 10 | .SH DESCRIPTION |
11 | .PP | 11 | .PP |
12 | Search for content on GNUnet. The keywords are case\-sensitive. gnunet\-search can be used both for a search in the global namespace as well as for searching a private subspace. | 12 | Search for content on GNUnet. The keywords are case\-sensitive. |
13 | gnunet\-search can be used both for a search in the global namespace | ||
14 | as well as for searching a private subspace. | ||
13 | .TP | 15 | .TP |
14 | \fB\-a \fILEVEL\fR, \fB\-\-anonymity=\fILEVEL\fR | 16 | \fB\-a \fILEVEL\fR, \fB\-\-anonymity=\fILEVEL\fR |
15 | 17 | ||
16 | The \fB\-a\fR option can be used to specify additional anonymity constraints. If set to 0, GNUnet will try to download the file as fast as possible, including using non-anonymous methods. If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity). However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity. You can gain better privacy by specifying a higher level of anonymity, which increases the amount of cover traffic your own traffic will get, at the expense of performance. Note that your download performance is not only determined by your own anonymity level, but also by the anonymity level of the peers publishing the file. So even if you download with anonymity level 0, the peers publishing the data might be sharing with a higher anonymity level, which in this case will determine performance. Also, peers that cache content in the network always use anonymity level 1. | 18 | The \fB\-a\fR option can be used to specify additional anonymity |
17 | 19 | constraints. If set to 0, GNUnet will try to download the file as fast | |
18 | This option can be used to limit requests further than that. In particular, you can require GNUnet to receive certain amounts of traffic from other peers before sending your queries. This way, you can gain very high levels of anonymity \- at the expense of much more traffic and much higher latency. So set it only if you really believe you need it. | 20 | as possible, including using non-anonymous methods. If you set it to |
19 | 21 | 1 (default), you use the standard anonymous routing algorithm (which | |
20 | The definition of ANONYMITY\-RECEIVE is the following. 0 means no anonymity is required. Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" traffic can be from the local user, leaving 'v-1' bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n bytes of messages from foreign peers (using anonymous routing), it may originate n/(v-1) bytes of queries in the same time\-period. The time\-period is twice the average delay that GNUnet defers forwarded queries. | 22 | does not explicitly leak your identity). However, a powerful |
21 | 23 | adversary may still be able to perform traffic analysis (statistics) | |
22 | The default is 1 and this should be fine for most users. Also notice that if you choose very large values, you may end up having no throughput at all, especially if many of your fellow GNUnet\-peers all do the same. | 24 | to over time infer data about your identity. You can gain better |
25 | privacy by specifying a higher level of anonymity, which increases the | ||
26 | amount of cover traffic your own traffic will get, at the expense of | ||
27 | performance. Note that your download performance is not only | ||
28 | determined by your own anonymity level, but also by the anonymity | ||
29 | level of the peers publishing the file. So even if you download with | ||
30 | anonymity level 0, the peers publishing the data might be sharing with | ||
31 | a higher anonymity level, which in this case will determine | ||
32 | performance. Also, peers that cache content in the network always use | ||
33 | anonymity level 1. | ||
34 | |||
35 | This option can be used to limit requests further than that. In | ||
36 | particular, you can require GNUnet to receive certain amounts of | ||
37 | traffic from other peers before sending your queries. This way, you | ||
38 | can gain very high levels of anonymity \- at the expense of much more | ||
39 | traffic and much higher latency. So set it only if you really believe | ||
40 | you need it. | ||
41 | |||
42 | The definition of ANONYMITY\-RECEIVE is the following. 0 means no | ||
43 | anonymity is required. Otherwise a value of 'v' means that 1 out of v | ||
44 | bytes of "anonymous" traffic can be from the local user, leaving 'v-1' | ||
45 | bytes of cover traffic per byte on the wire. Thus, if GNUnet routes n | ||
46 | bytes of messages from foreign peers (using anonymous routing), it may | ||
47 | originate n/(v-1) bytes of queries in the same time\-period. The | ||
48 | time\-period is twice the average delay that GNUnet defers forwarded | ||
49 | queries. | ||
50 | |||
51 | The default is 1 and this should be fine for most users. Also notice | ||
52 | that if you choose very large values, you may end up having no | ||
53 | throughput at all, especially if many of your fellow GNUnet\-peers all | ||
54 | do the same. | ||
23 | 55 | ||
24 | .TP | 56 | .TP |
25 | \fB\-c \fIFILENAME\fR, \fB\-\-config=\fIFILENAME\fR | 57 | \fB\-c \fIFILENAME\fR, \fB\-\-config=\fIFILENAME\fR |
@@ -48,7 +80,10 @@ automatically terminate the search after receiving VALUE results. | |||
48 | 80 | ||
49 | .TP | 81 | .TP |
50 | \fB\-t \fIDELAY\fR, \fB\-\-timeout=\fIDELAY\fR | 82 | \fB\-t \fIDELAY\fR, \fB\-\-timeout=\fIDELAY\fR |
51 | Automatically timeout search after DELAY. The value given must be a number followed by a space and a time unit, for example "500 ms". Note that the quotes are required on the shell. Otherwise the search runs until gnunet\-search is aborted with CTRL\-C. | 83 | Automatically timeout search after DELAY. The value given must be a |
84 | number followed by a space and a time unit, for example "500 ms". | ||
85 | Note that the quotes are required on the shell. Otherwise the search | ||
86 | runs until gnunet\-search is aborted with CTRL\-C. | ||
52 | 87 | ||
53 | .TP | 88 | .TP |
54 | \fB\-v\fR, \fB\-\-version\fR | 89 | \fB\-v\fR, \fB\-\-version\fR |
@@ -59,9 +94,17 @@ print the version number | |||
59 | print meta data from search results as well | 94 | print meta data from search results as well |
60 | .SH NOTES | 95 | .SH NOTES |
61 | 96 | ||
62 | You can run gnunet\-search with an URI instead of a keyword. The URI can have the format for a namespace search or for a keyword search. For a namespace search, the format is gnunet://fs/sks/NAMESPACE/IDENTIFIER. For a keyword search, use gnunet://fs/ksk/KEYWORD[+KEYWORD]*. If the format does not correspond to a GNUnet URI, GNUnet will automatically assume that keywords are supplied directly. | 97 | You can run gnunet\-search with an URI instead of a keyword. The URI |
98 | can have the format for a namespace search or for a keyword search. | ||
99 | For a namespace search, the format is | ||
100 | gnunet://fs/sks/NAMESPACE/IDENTIFIER. For a keyword search, use | ||
101 | gnunet://fs/ksk/KEYWORD[+KEYWORD]*. If the format does not correspond | ||
102 | to a GNUnet URI, GNUnet will automatically assume that keywords are | ||
103 | supplied directly. | ||
63 | 104 | ||
64 | If multiple keywords are passed, gnunet-search will look for content matching any of the keywords. The prefix "+" makes a keyword mandatory. | 105 | If multiple keywords are passed, gnunet-search will look for content |
106 | matching any of the keywords. The prefix "+" makes a keyword | ||
107 | mandatory. | ||
65 | 108 | ||
66 | # gnunet\-search "Das Kapital" | 109 | # gnunet\-search "Das Kapital" |
67 | 110 | ||
@@ -81,7 +124,13 @@ Search results are printed by gnunet\-search like this: | |||
81 | Mime-type: text/plain | 124 | Mime-type: text/plain |
82 | .ad b | 125 | .ad b |
83 | 126 | ||
84 | The first line contains the command to run to download the file. The suggested filename in the example is COPYING. The GNUnet URI consists of the key and query hash of the file and finally the size of the file. After the command to download the file GNUnet will print meta\-data about the file as advertised in the search result, here "The GNU General Public License" and the mime\-type (see the options for gnunet\-publish on how to supply meta-data by hand). | 127 | The first line contains the command to run to download the file. The |
128 | suggested filename in the example is COPYING. The GNUnet URI consists | ||
129 | of the key and query hash of the file and finally the size of the | ||
130 | file. After the command to download the file GNUnet will print | ||
131 | meta\-data about the file as advertised in the search result, here | ||
132 | "The GNU General Public License" and the mime\-type (see the options | ||
133 | for gnunet\-publish on how to supply meta-data by hand). | ||
85 | 134 | ||
86 | .SH FILES | 135 | .SH FILES |
87 | .TP | 136 | .TP |
diff --git a/doc/man/gnunet-statistics.1 b/doc/man/gnunet-statistics.1 index e6c744f12..2aa889382 100644 --- a/doc/man/gnunet-statistics.1 +++ b/doc/man/gnunet-statistics.1 | |||
@@ -10,8 +10,11 @@ gnunet\-statistics \- Display statistics about your GNUnet system | |||
10 | .br | 10 | .br |
11 | 11 | ||
12 | .SH DESCRIPTION | 12 | .SH DESCRIPTION |
13 | \fBgnunet\-statistics\fP is used to display detailed information about various aspect of GNUnet's operation. This tool only works if the "statistics" service is available. | 13 | \fBgnunet\-statistics\fP is used to display detailed information about |
14 | gnunet\-statistics can be used to set a value by giving the options \-n, \-s and also a VALUE. | 14 | various aspect of GNUnet's operation. This tool only works if the |
15 | "statistics" service is available. | ||
16 | gnunet\-statistics can be used to set a value by giving the options | ||
17 | \-n, \-s and also a VALUE. | ||
15 | 18 | ||
16 | .SH OPTIONS | 19 | .SH OPTIONS |
17 | .B | 20 | .B |
@@ -25,13 +28,25 @@ Print short help on options. | |||
25 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 28 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. |
26 | .B | 29 | .B |
27 | .IP "\-n NAME, \-\-name=NAME" | 30 | .IP "\-n NAME, \-\-name=NAME" |
28 | Each statistic has a name that is unique with in its subsystem. With this option, the output can be restricted to statistics that have a particular name. | 31 | Each statistic has a name that is unique with in its subsystem. With |
32 | this option, the output can be restricted to statistics that have a | ||
33 | particular name. | ||
29 | .B | 34 | .B |
30 | .IP "\-p, \-\-persistent" | 35 | .IP "\-p, \-\-persistent" |
31 | When setting a value, make the value persistent. If the value used to be persistent and this flag is not given, it will be marked as non\-persistent. | 36 | When setting a value, make the value persistent. If the value used to |
37 | be persistent and this flag is not given, it will be marked as | ||
38 | non\-persistent. | ||
32 | .B | 39 | .B |
33 | .IP "\-s SUBSYSTEM, \-\-subsystem=SUBSYSTEM" | 40 | .IP "\-s SUBSYSTEM, \-\-subsystem=SUBSYSTEM" |
34 | Statistics are kept for various subsystems. With this option, the output can be restricted to a particular subsystem only. | 41 | Statistics are kept for various subsystems. With this option, the |
42 | output can be restricted to a particular subsystem only. | ||
43 | .B | ||
44 | .IP "\-S SEPARATOR, \-\-csv-separator=SEPARATOR" | ||
45 | Specify a separator for generating csv-output. | ||
46 | .B | ||
47 | .IP "\-t TESTBED_PATH, \-\-subsystem=TESTBED_PATH" | ||
48 | When running testbed, you can get statistics of all peers with specefying the | ||
49 | folder containing the data of all testbed nodes like \fBgnunet\-statistics -t /tmp/testbedARtmQv\fP. | ||
35 | .B | 50 | .B |
36 | .IP "\-v, \-\-version" | 51 | .IP "\-v, \-\-version" |
37 | Print GNUnet version number. | 52 | Print GNUnet version number. |
diff --git a/doc/man/gnunet-testbed-profiler.1 b/doc/man/gnunet-testbed-profiler.1 index 3911085f2..bc7092e68 100644 --- a/doc/man/gnunet-testbed-profiler.1 +++ b/doc/man/gnunet-testbed-profiler.1 | |||
@@ -32,7 +32,9 @@ Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | |||
32 | Configure logging to write logs to LOGFILE. | 32 | Configure logging to write logs to LOGFILE. |
33 | .B | 33 | .B |
34 | .IP "\-n, \-\-non\-interactive" | 34 | .IP "\-n, \-\-non\-interactive" |
35 | Run profiler in non-interactive mode where upon testbed setup the profiler does not wait for a keystroke but continues to run until a termination signal is received. | 35 | Run profiler in non-interactive mode where upon testbed setup the |
36 | profiler does not wait for a keystroke but continues to run until a | ||
37 | termination signal is received. | ||
36 | .B | 38 | .B |
37 | .IP "\-p COUNT, \-\-num\-peers=COUNT" | 39 | .IP "\-p COUNT, \-\-num\-peers=COUNT" |
38 | Create COUNT number of peers. | 40 | Create COUNT number of peers. |
diff --git a/doc/man/gnunet-testing-run-service.1 b/doc/man/gnunet-testing-run-service.1 index 7df698225..a6a29d953 100644 --- a/doc/man/gnunet-testing-run-service.1 +++ b/doc/man/gnunet-testing-run-service.1 | |||
@@ -9,11 +9,17 @@ gnunet\-testing\-run\-service \- Command line tool to start a service for testin | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-testing\-run\-service\fP is a command line tool to start a service for testing. It starts a peer, running only the service specified on the command line, outputs the path to the temporary configuration file to stdout. | 12 | \fBgnunet\-testing\-run\-service\fP is a command line tool to start a |
13 | service for testing. It starts a peer, running only the service | ||
14 | specified on the command line, outputs the path to the temporary | ||
15 | configuration file to stdout. | ||
13 | 16 | ||
14 | The peer will run until this program is killed, or stdin is closed. When reading the character 'r' from stdin, the running service is restarted with the same configuration. | 17 | The peer will run until this program is killed, or stdin is |
18 | closed. When reading the character 'r' from stdin, the running service | ||
19 | is restarted with the same configuration. | ||
15 | 20 | ||
16 | This executable is intended to be used by gnunet-java, in order to reliably start and stop services for test cases. | 21 | This executable is intended to be used by gnunet-java, in order to |
22 | reliably start and stop services for test cases. | ||
17 | 23 | ||
18 | .SH OPTIONS | 24 | .SH OPTIONS |
19 | .B | 25 | .B |
diff --git a/doc/man/gnunet-timeout.1 b/doc/man/gnunet-timeout.1 new file mode 100644 index 000000000..e413254f4 --- /dev/null +++ b/doc/man/gnunet-timeout.1 | |||
@@ -0,0 +1,20 @@ | |||
1 | .TH GNUNET\-TIMOUET 1 "Jun 5, 2018" "GNUnet" | ||
2 | |||
3 | .SH NAME | ||
4 | gnunet\-timeout \- run process with timeout | ||
5 | |||
6 | .SH SYNOPSIS | ||
7 | .B gnunet\-timeout | ||
8 | .RI TIMEOUT PROGRAM ARGS | ||
9 | .br | ||
10 | |||
11 | .SH DESCRIPTION | ||
12 | \fBgnunet\-timeout\fP can be used to run another process with a | ||
13 | timeout. Provided as the standard "timout" utility may not be | ||
14 | available on all platforms. | ||
15 | |||
16 | .SH BUGS | ||
17 | Report bugs by using Mantis <https://gnunet.org/bugs/> or by sending electronic mail to <gnunet\-developers@gnu.org> | ||
18 | |||
19 | .SH SEE | ||
20 | timeout(1) | ||
diff --git a/doc/man/gnunet-transport.1 b/doc/man/gnunet-transport.1 index 1680f9cf7..3a81c54fe 100644 --- a/doc/man/gnunet-transport.1 +++ b/doc/man/gnunet-transport.1 | |||
@@ -8,11 +8,17 @@ gnunet\-transport \- measure and control the transport subsystem | |||
8 | .SH DESCRIPTION | 8 | .SH DESCRIPTION |
9 | .PP | 9 | .PP |
10 | 10 | ||
11 | gnunet\-transport is a tool to access various functions of GNUnet's transport subsystem from the command\-line. Most of these are not expected to be useful for end-users. gnunet\-transport can be used to evaluate the performance of the transports, force a peer to connect to another peer (if possible). Other functions should be added in the near future. | 11 | gnunet\-transport is a tool to access various functions of GNUnet's |
12 | transport subsystem from the command\-line. Most of these are not | ||
13 | expected to be useful for end-users. gnunet\-transport can be used to | ||
14 | evaluate the performance of the transports, force a peer to connect to | ||
15 | another peer (if possible). Other functions should be added in the | ||
16 | near future. | ||
12 | 17 | ||
13 | .TP | 18 | .TP |
14 | \fB\-b\fR, \fB\-\-benchmark\fR | 19 | \fB\-b\fR, \fB\-\-benchmark\fR |
15 | measure how fast we are receiving data (from all connections). On exit, the data rate will be reported. Runs until aborted with CTRL-C. | 20 | measure how fast we are receiving data (from all connections). On |
21 | exit, the data rate will be reported. Runs until aborted with CTRL-C. | ||
16 | .TP | 22 | .TP |
17 | \fB\-D\fR, \fB\-\-disconnect\fR | 23 | \fB\-D\fR, \fB\-\-disconnect\fR |
18 | force disconnection from a peer (used in conjunction with \-p). | 24 | force disconnection from a peer (used in conjunction with \-p). |
@@ -46,7 +52,10 @@ the peer identity to connect to or monitor | |||
46 | monitor session state of transport plugins | 52 | monitor session state of transport plugins |
47 | .TP | 53 | .TP |
48 | \fB\-s\fR, \fB\-\-send\fR | 54 | \fB\-s\fR, \fB\-\-send\fR |
49 | transmit (dummy) traffic as quickly as possible to the peer specified with the \-p option. The rate will still be limited by the quota(s) determined by the peers (ATS subsystem). Will run until CTRL\-C is pressed or until the connection to the other peer is disrupted. | 55 | transmit (dummy) traffic as quickly as possible to the peer specified |
56 | with the \-p option. The rate will still be limited by the quota(s) | ||
57 | determined by the peers (ATS subsystem). Will run until CTRL\-C is | ||
58 | pressed or until the connection to the other peer is disrupted. | ||
50 | .TP | 59 | .TP |
51 | \fB\-v\fR, \fB\-\-version\fR | 60 | \fB\-v\fR, \fB\-\-version\fR |
52 | print the version number | 61 | print the version number |
diff --git a/doc/man/gnunet-unindex.1 b/doc/man/gnunet-unindex.1 index b3a1de6e3..cf095cc49 100644 --- a/doc/man/gnunet-unindex.1 +++ b/doc/man/gnunet-unindex.1 | |||
@@ -25,7 +25,10 @@ print the version number | |||
25 | \fB\-V\fR, \fB\-\-verbose\fR | 25 | \fB\-V\fR, \fB\-\-verbose\fR |
26 | be verbose | 26 | be verbose |
27 | .SH NOTES | 27 | .SH NOTES |
28 | You can only unindex files that you indexed and that you still have available locally in full. You should use gnunet\-unindex on files that you indexed (not inserted) and that you are going to delete or move locally. | 28 | You can only unindex files that you indexed and that you still have |
29 | available locally in full. You should use gnunet\-unindex on files | ||
30 | that you indexed (not inserted) and that you are going to delete or | ||
31 | move locally. | ||
29 | .TP | 32 | .TP |
30 | .SH FILES | 33 | .SH FILES |
31 | .TP | 34 | .TP |
diff --git a/doc/man/gnunet-uri.1 b/doc/man/gnunet-uri.1 index 9eac68a6d..ac8ccf374 100644 --- a/doc/man/gnunet-uri.1 +++ b/doc/man/gnunet-uri.1 | |||
@@ -9,7 +9,11 @@ gnunet\-uri \- invoke default handler for GNUnet URIs | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-uri\fP can be used to invoke the correct tool to handle a GNUnet URI. GNUnet URIs have the format "gnunet://SUBSYSTEM/DETAILS" and thus the specific tool to handle the URI depends on the subsystem. gnunet\-uri will determine the correct tool (by looking for SUBSYSTEM in the configuration section "uri") and invoke it. | 12 | \fBgnunet\-uri\fP can be used to invoke the correct tool to handle a |
13 | GNUnet URI. GNUnet URIs have the format "gnunet://SUBSYSTEM/DETAILS" | ||
14 | and thus the specific tool to handle the URI depends on the subsystem. | ||
15 | gnunet\-uri will determine the correct tool (by looking for SUBSYSTEM | ||
16 | in the configuration section "uri") and invoke it. | ||
13 | 17 | ||
14 | .SH OPTIONS | 18 | .SH OPTIONS |
15 | .B | 19 | .B |
diff --git a/doc/man/gnunet-vpn.1 b/doc/man/gnunet-vpn.1 index 68a5905d8..6b1b11f7b 100644 --- a/doc/man/gnunet-vpn.1 +++ b/doc/man/gnunet-vpn.1 | |||
@@ -9,9 +9,20 @@ gnunet\-vpn \- manually setup a GNUnet VPN tunnel | |||
9 | .br | 9 | .br |
10 | 10 | ||
11 | .SH DESCRIPTION | 11 | .SH DESCRIPTION |
12 | \fBgnunet\-vpn\fP can be used to manually setup a VPN tunnel via the GNUnet network. There are two main types of tunnels. Tunnels to an exit node which routes the traffic to the global Internet, and tunnels to a node that runs a service only within GNUnet. Depending on the type of tunnel, gnunet\-vpn takes different options. The "\-i" option is required for tunnels to an exit node, whereas the "\-p" and "\-s" options in conjunction with either "\-u" or "\-t" are required for tunnels to services. For exit tunnels, both UDP and TCP traffic will be redirected. For service tunnels, either UDP ("\-u") or TCP ("\-t") traffic will be redirected. | 12 | \fBgnunet\-vpn\fP can be used to manually setup a VPN tunnel via the |
13 | GNUnet network. There are two main types of tunnels. Tunnels to an | ||
14 | exit node which routes the traffic to the global Internet, and tunnels | ||
15 | to a node that runs a service only within GNUnet. Depending on the | ||
16 | type of tunnel, gnunet\-vpn takes different options. The "\-i" option | ||
17 | is required for tunnels to an exit node, whereas the "\-p" and "\-s" | ||
18 | options in conjunction with either "\-u" or "\-t" are required for | ||
19 | tunnels to services. For exit tunnels, both UDP and TCP traffic will | ||
20 | be redirected. For service tunnels, either UDP ("\-u") or TCP ("\-t") | ||
21 | traffic will be redirected. | ||
13 | 22 | ||
14 | The tool will display the IP address for this end of the tunnel. The address can be displayed as soon as it has been allocated, or only after ("\-a") the tunnel has been created. | 23 | The tool will display the IP address for this end of the tunnel. The |
24 | address can be displayed as soon as it has been allocated, or only | ||
25 | after ("\-a") the tunnel has been created. | ||
15 | 26 | ||
16 | .SH OPTIONS | 27 | .SH OPTIONS |
17 | .B | 28 | .B |
@@ -25,22 +36,29 @@ Desired IP address on this end of the tunnel should be an IPv6 address. | |||
25 | Use the configuration file FILENAME. | 36 | Use the configuration file FILENAME. |
26 | .B | 37 | .B |
27 | .IP "\-d TIME, \-\-duration TIME" | 38 | .IP "\-d TIME, \-\-duration TIME" |
28 | The mapping should be established for TIME. The value given must be a number followed by a space and a time unit, for example "500 ms". Note that the quotes are required on the shell. Default is 5 minutes. | 39 | The mapping should be established for TIME. The value given must be a |
40 | number followed by a space and a time unit, for example "500 ms". | ||
41 | Note that the quotes are required on the shell. Default is 5 minutes. | ||
29 | .B | 42 | .B |
30 | .IP "\-h, \-\-help" | 43 | .IP "\-h, \-\-help" |
31 | Print short help on options. | 44 | Print short help on options. |
32 | .B | 45 | .B |
33 | .IP "\-i IP, \-\-ip IP" | 46 | .IP "\-i IP, \-\-ip IP" |
34 | Tunnel should be to an exit node and connect to the given IPv4 or IPv6 IP address. Note that you can specify an IPv6 address as the target here, even in combination with "\-4" (4to6) and similarly you can specify an IPv4 address in combination with "\-6" (6to4). | 47 | Tunnel should be to an exit node and connect to the given IPv4 or IPv6 |
48 | IP address. Note that you can specify an IPv6 address as the target | ||
49 | here, even in combination with "\-4" (4to6) and similarly you can | ||
50 | specify an IPv4 address in combination with "\-6" (6to4). | ||
35 | .B | 51 | .B |
36 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" | 52 | .IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL" |
37 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. | 53 | Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. |
38 | .B | 54 | .B |
39 | .IP "\-p PEERID, \-\-peer=PEERID" | 55 | .IP "\-p PEERID, \-\-peer=PEERID" |
40 | Name of the peer offering the service to connect to. Cannot be used in conjunction with "\-i", requires "\-s". | 56 | Name of the peer offering the service to connect to. Cannot be used |
57 | in conjunction with "\-i", requires "\-s". | ||
41 | .B | 58 | .B |
42 | .IP "\-s NAME, \-\-service=NAME" | 59 | .IP "\-s NAME, \-\-service=NAME" |
43 | Name of the service running on the target peer. Cannot be used in conjunction with "\-i", requires "\-p". | 60 | Name of the service running on the target peer. Cannot be used in |
61 | conjunction with "\-i", requires "\-p". | ||
44 | .B | 62 | .B |
45 | .IP "\-t, \-\-tcp" | 63 | .IP "\-t, \-\-tcp" |
46 | Service runs TCP. Either "\-t" or "\-u" must be specified when using "\-s". | 64 | Service runs TCP. Either "\-t" or "\-u" must be specified when using "\-s". |
diff --git a/doc/man/gnunet-zoneimport.1 b/doc/man/gnunet-zoneimport.1 index 06b3a6bcf..cf76b86ee 100644 --- a/doc/man/gnunet-zoneimport.1 +++ b/doc/man/gnunet-zoneimport.1 | |||
@@ -8,17 +8,37 @@ gnunet\-zoneimport \- import DNS zone into GNS zone | |||
8 | .br | 8 | .br |
9 | 9 | ||
10 | .SH DESCRIPTION | 10 | .SH DESCRIPTION |
11 | \fBgnunet\-zoneimport\fP reads a list of domain names (FQDN) from stdin and issues DNS queries for each of the domain names given. It then checks if a local ego with a name matching the domain exists. Specifically, if the domain name is "example.fr", it will check if an ego "fr" exists, while for a domain "example.com.fr" it will look for an ego called "com.fr"). If so, it will convert the DNS records into GNS records (in particular converting NS records and glue records to GNS2DNS records) and add them to the namestore under the label ("example" in the examples above). | 11 | \fBgnunet\-zoneimport\fP reads a list of domain names (FQDN) from |
12 | 12 | stdin and issues DNS queries for each of the domain names given. It | |
13 | The arguments given to gnunet\-zoneimport is a list of IP addresses of DNS servers to query. | 13 | then checks if a local ego with a name matching the domain |
14 | 14 | exists. Specifically, if the domain name is "example.fr", it will | |
15 | gnunet\-zoneimport will usually never terminate: it will check when DNS records expire, and re-issue requests when the old DNS records have expired so that GNS always has the latest data. | 15 | check if an ego "fr" exists, while for a domain "example.com.fr" it |
16 | 16 | will look for an ego called "com.fr"). If so, it will convert the DNS | |
17 | gnunet\-zoneimport will issue many DNS queries in parallel, but is rate-limited in various ways, so most DNS servers should easily handle the load. gnunet\-zoneimport will perform a limited number of retries if queries fail. | 17 | records into GNS records (in particular converting NS records and glue |
18 | 18 | records to GNS2DNS records) and add them to the namestore under the | |
19 | gnunet\-zoneimport operates incrementally. It will check if the namestore already has (non-expired) records stored for a given name in the respective zone and not issue those requests again. Thus, it is fine to restart gnunet\-zoneimport whenever the list of domain names changes. | 19 | label ("example" in the examples above). |
20 | 20 | ||
21 | Finally, gnunet\-zoneimport keeps information for each domain name in memory. This consumes about 200 bytes per domain name, or 1 GB for 5 million labels. | 21 | The arguments given to gnunet\-zoneimport is a list of IP addresses of |
22 | DNS servers to query. | ||
23 | |||
24 | gnunet\-zoneimport will usually never terminate: it will check when | ||
25 | DNS records expire, and re-issue requests when the old DNS records | ||
26 | have expired so that GNS always has the latest data. | ||
27 | |||
28 | gnunet\-zoneimport will issue many DNS queries in parallel, but is | ||
29 | rate-limited in various ways, so most DNS servers should easily handle | ||
30 | the load. gnunet\-zoneimport will perform a limited number of retries | ||
31 | if queries fail. | ||
32 | |||
33 | gnunet\-zoneimport operates incrementally. It will check if the | ||
34 | namestore already has (non-expired) records stored for a given name in | ||
35 | the respective zone and not issue those requests again. Thus, it is | ||
36 | fine to restart gnunet\-zoneimport whenever the list of domain names | ||
37 | changes. | ||
38 | |||
39 | Finally, gnunet\-zoneimport keeps information for each domain name in | ||
40 | memory. This consumes about 200 bytes per domain name, or 1 GB for 5 | ||
41 | million labels. | ||
22 | 42 | ||
23 | .SH OPTIONS | 43 | .SH OPTIONS |
24 | .B | 44 | .B |
@@ -28,8 +48,22 @@ Use the configuration file FILENAME. | |||
28 | .IP "\-h, \-\-help" | 48 | .IP "\-h, \-\-help" |
29 | Print short help on options. | 49 | Print short help on options. |
30 | .B | 50 | .B |
51 | .IP "\-m RELATIVETIME, \-\-minimum-expiration=RELATIVETIME" | ||
52 | .B | ||
53 | Ensure that imported DNS records never have an expiration time that | ||
54 | is less than RELATIVETIME into the future. RELATIVETIME is a time | ||
55 | given like "1 week" or "1 h". If DNS returns records with a shorter | ||
56 | lifetime, gnunet\-zoneimport will simply bump the lifetime to the | ||
57 | specified value (relative to the time of the import). Default is zero. | ||
58 | |||
31 | .IP "\-s MAPSIZE, \-\-size=MAPSIZE" | 59 | .IP "\-s MAPSIZE, \-\-size=MAPSIZE" |
32 | Specifies the size (in number of entries) to use for the main hash map. The value provided should be at least twice the number of domain names that will be given to the tool. This option is required for very large zones where the number of records encountered is too large for the automatic growth mechanism to work (that one is limited to at most 16 MB allocations for security reasons). Do not worry about this unless you are importing millions of domain names from a zone. | 60 | Specifies the size (in number of entries) to use for the main hash |
61 | map. The value provided should be at least twice the number of domain | ||
62 | names that will be given to the tool. This option is required for very | ||
63 | large zones where the number of records encountered is too large for | ||
64 | the automatic growth mechanism to work (that one is limited to at most | ||
65 | 16 MB allocations for security reasons). Do not worry about this | ||
66 | unless you are importing millions of domain names from a zone. | ||
33 | 67 | ||
34 | .SH NOTES | 68 | .SH NOTES |
35 | 69 | ||
diff --git a/doc/man/gnunet.conf.5 b/doc/man/gnunet.conf.5 index 3df3b437a..3dd8c7b62 100644 --- a/doc/man/gnunet.conf.5 +++ b/doc/man/gnunet.conf.5 | |||
@@ -1,4 +1,4 @@ | |||
1 | .TH GNUNET.CONF "5" "12 Aug 2013" "GNUnet" | 1 | .TH GNUNET.CONF "5" "05 May 2018" "GNUnet" |
2 | .SH NAME | 2 | .SH NAME |
3 | gnunet.conf \- GNUnet configuration file | 3 | gnunet.conf \- GNUnet configuration file |
4 | .SH SYNOPSIS | 4 | .SH SYNOPSIS |
@@ -6,44 +6,92 @@ gnunet.conf \- GNUnet configuration file | |||
6 | .SH DESCRIPTION | 6 | .SH DESCRIPTION |
7 | .PP | 7 | .PP |
8 | 8 | ||
9 | A GNUnet setup typically consists of a a set of service processes run by a user "gnunet" and a set of user-interface processes run by a standard account. The default location for the configuration file for the services is "~gnunet/.config/gnunet.conf"; however, as normal users also may need read-access to this configuration, you might want to instead put the service process configuration in "/etc/gnunet.conf". gnunet\-setup (part of the GTK package) can be used to edit this configuration. The parts of GNUnet that is ran as a normal user may have config options too and they read from "$HOME/.config/gnunet.conf". The latter config file can skip any options for the services. | 9 | A GNUnet setup typically consists of a set of service processes run by a user |
10 | "gnunet" and a set of user-interface processes run by a standard account. | ||
11 | The default location for the configuration file for the services is | ||
12 | "~gnunet/.config/gnunet.conf"; however, as normal users also may need | ||
13 | read-access to this configuration, you might want to instead put the service | ||
14 | process configuration in "/etc/gnunet.conf". | ||
15 | gnunet\-setup (part of the GNUnet GTK package) can be used to edit this | ||
16 | configuration. The parts of GNUnet that are run as a normal user may have | ||
17 | config options too and they read from "$HOME/.config/gnunet.conf". | ||
18 | The latter config file can skip any options for the services. | ||
10 | 19 | ||
11 | .TP | 20 | .TP |
12 | The basic structure of the configuration file is the following. The file is split into sections. Every section begins with "[SECTIONNAME]" and contains a number of options of the form "OPTION=VALUE". Empty lines and lines beginning with a "#" are treated as comments. Almost all options are optional and the tools resort to reasonable defaults if they are not present. | 21 | The basic structure of the configuration file is the following. The file is |
22 | split into sections. Every section begins with "[SECTIONNAME]" and contains | ||
23 | a number of options of the form "OPTION=VALUE". | ||
24 | Empty lines and lines beginning with a "#" are treated as comments. | ||
25 | Almost all options are optional and the tools resort to reasonable defaults | ||
26 | if they are not present. | ||
13 | .PP | 27 | .PP |
14 | Default values for all of the options can be found in the files in the "$GNUNET_PREFIX/share/gnunet/config.d/" directory. A typical setup will work out of the box with those. See the examples section below for some common setups on top of that. | 28 | Default values for all of the options can be found in the files in the |
29 | "$GNUNET_PREFIX/share/gnunet/config.d/" directory. A typical setup will | ||
30 | work out of the box with those. See the examples section below for | ||
31 | some common setups on top of that. | ||
15 | 32 | ||
16 | .SH General OPTIONS | 33 | .SH General OPTIONS |
17 | .PP | 34 | .PP |
18 | Many options will be common between sections. They can be repeated under each section with different values. The "[PATHS]" section is special. Here, it is possible to specify values for variables like "GNUNET_HOME". Then, in all filenames that begin with "$GNUNET_HOME" the "$GNUNET_HOME" will be replaced with the respective value at runtime. The main use of this is to redefine "$GNUNET_HOME", which by default points to "$HOME/.config/". By setting this variable, you can change the location where GNUnet stores its internal data. | 35 | Many options will be common between sections. They can be repeated under |
36 | each section with different values. The "[PATHS]" section is special. | ||
37 | Here, it is possible to specify values for variables like "GNUNET_HOME". | ||
38 | Then, in all filenames that begin with "$GNUNET_HOME" the "$GNUNET_HOME" | ||
39 | will be replaced with the respective value at runtime. The main use of | ||
40 | this is to redefine "$GNUNET_HOME", which by default points to "$HOME/.config/". | ||
41 | By setting this variable, you can change the location where GNUnet stores | ||
42 | its internal data. | ||
43 | gnunet.conf accepts the variable "GNUNET_TMP" which we suggest to use in | ||
44 | place of the absolute definition of "/tmp". | ||
45 | So instead of "/tmp/foo" you would write "$GNUNET_TMP/foo". | ||
46 | The usage of "$GNUNET_TMP/foo", will result in "$TMPDIR/gnunet/foo", or | ||
47 | "$TMP/gnunet/foo" and finally, if "TMPDIR" is undefined, "/tmp/gnunet/foo". | ||
48 | |||
19 | .PP | 49 | .PP |
20 | 50 | ||
21 | The following options are generic and shared by all services: | 51 | The following options are generic and shared by all services: |
22 | 52 | ||
23 | .IP HOSTNAME | 53 | .IP HOSTNAME |
24 | The hostname specifies the machine on which the service is running. This is usually "localhost". | 54 | The hostname specifies the machine on which the service is running. |
55 | This is usually "localhost". | ||
25 | .IP BINARY | 56 | .IP BINARY |
26 | The filename that implements the service. For example "gnunet-service-ats". | 57 | The filename that implements the service. For example "gnunet-service-ats". |
27 | .IP FORCESTART | 58 | .IP IMMEDIATE_START |
28 | Start the service always when the peer starts. Set to YES for services that should always be launched, even if no other service explicitly needs them. | 59 | Start the service always when the peer starts. Set to YES for services |
29 | .IP AUTOSTART | 60 | that should always be launched, even if no other service explicitly needs |
30 | Set to YES to automatically start the service when it is requested by another service. YES for most GNUnet services. | 61 | them. |
62 | .IP START_ON_DEMAND | ||
63 | Set to YES to automatically start the service when it is requested by | ||
64 | another service. YES for most GNUnet services. | ||
31 | .IP NOARMBIND | 65 | .IP NOARMBIND |
32 | Set to YES to never have ARM bind to the respective socket. This option is mostly for debugging in situations where ARM cannot pass the pre-bound socket to the child due to interference from PREFIX-commands. This option is only effective in combination with FORCESTART being YES. NO by default. | 66 | Set to YES to never have ARM bind to the respective socket. This option is |
67 | mostly for debugging in situations where ARM cannot pass the pre-bound | ||
68 | socket to the child due to interference from PREFIX-commands. | ||
69 | This option is only effective in combination with IMMEDIATE_START being YES. | ||
70 | NO by default. | ||
33 | .IP PREFIX | 71 | .IP PREFIX |
34 | PREFIX the given command (with its arguments) to the actual BINARY to be executed. Useful to run certain services under special supervisors (like strace or valgrind). Typically used in combination with FORCESTART and NOARMBIND. Empty by default. | 72 | PREFIX the given command (with its arguments) to the actual BINARY to be |
73 | executed. Useful to run certain services under special supervisors (like | ||
74 | strace or valgrind). Typically used in combination with IMMEDIATE_START | ||
75 | and NOARMBIND. Empty by default. | ||
35 | .IP ACCEPT_FROM | 76 | .IP ACCEPT_FROM |
36 | A semi-column separated list of IPv4 addresses that are allowed to use the service; usually 127.0.0.1. | 77 | A semi-column separated list of IPv4 addresses that are allowed to use |
78 | the service; usually 127.0.0.1. | ||
37 | .IP ACCEPT_FROM6 | 79 | .IP ACCEPT_FROM6 |
38 | A semi-column separated list of IPv6 addresses that are allowed to use the service; usually ::1. | 80 | A semi-column separated list of IPv6 addresses that are allowed to use the |
81 | service; usually ::1. | ||
39 | .IP UNIXPATH | 82 | .IP UNIXPATH |
40 | Path to use for the UNIX domain socket for inter process communication with the service on POSIX systems. | 83 | Path to use for the UNIX domain socket for inter process communication with |
84 | the service on POSIX systems. | ||
41 | .IP UNIX_MATCH_UID | 85 | .IP UNIX_MATCH_UID |
42 | If UNIX domain sockets are used, set this to YES if only users with the same UID are allowed to access the service. | 86 | If UNIX domain sockets are used, set this to YES if only users with the same |
87 | UID are allowed to access the service. | ||
43 | .IP UNIX_MATCH_GID | 88 | .IP UNIX_MATCH_GID |
44 | If UNIX domain sockets are used, set this to YES if only users with the same GID are allowed to access the service. | 89 | If UNIX domain sockets are used, set this to YES if only users with the same |
45 | .IP USER_SERVICE | 90 | GID are allowed to access the service. |
46 | Set to YES if this service should be run per-user, NO if this is a system service. End-users should never have to change the defaults GNUnet provides for this option. | 91 | .IP RUN_PER_USER |
92 | Set to YES if this service should be run per-user, NO if this is a system | ||
93 | service. End-users should never have to change the defaults GNUnet provides | ||
94 | for this option. | ||
47 | 95 | ||
48 | 96 | ||
49 | 97 | ||
@@ -73,7 +121,10 @@ The following options are generic and shared by all services: | |||
73 | 121 | ||
74 | .SH EXAMPLES | 122 | .SH EXAMPLES |
75 | 123 | ||
76 | This example is a simple way to get started, using a server that has a known list of peers to get you started. Most users will be behind a firewal on IPv4, as such NAT is enabled. Please rememeber to change your IP address to the actual external address for your usage. | 124 | This example is a simple way to get started, using a server that has a known |
125 | list of peers to get you started. Most users will be behind a firewall on | ||
126 | IPv4, as such NAT is enabled. Please rememeber to change your IP address | ||
127 | to the actual external address for your usage. | ||
77 | .PP | 128 | .PP |
78 | [hostlist] | 129 | [hostlist] |
79 | OPTIONS = \-b | 130 | OPTIONS = \-b |
@@ -86,14 +137,15 @@ This example is a simple way to get started, using a server that has a known lis | |||
86 | EXTERNAL_ADDRESS = 157.166.249.10 | 137 | EXTERNAL_ADDRESS = 157.166.249.10 |
87 | 138 | ||
88 | [arm] | 139 | [arm] |
89 | SYSTEM_ONLY = YES | 140 | START_SYSTEM_SERVICES = YES |
90 | USER_ONLY = NO | 141 | START_USER_SERVICES = NO |
91 | 142 | ||
92 | .SH FILES | 143 | .SH FILES |
93 | .TP | 144 | .TP |
94 | ~/.config/gnunet.conf | 145 | ~/.config/gnunet.conf |
95 | GNUnet configuration file | 146 | GNUnet configuration file |
96 | .SH "REPORTING BUGS" | 147 | .SH "REPORTING BUGS" |
97 | Report bugs by using Mantis <https://gnunet.org/bugs/> or by sending electronic mail to <bug-gnunet@gnu.org> | 148 | Report bugs by using Mantis <https://gnunet.org/bugs/> or by sending electronic |
149 | mail to <bug-gnunet@gnu.org> | ||
98 | .SH "SEE ALSO" | 150 | .SH "SEE ALSO" |
99 | \fBgnunet\-setup\fP(1), \fBgnunet\-arm\fP(1) | 151 | \fBgnunet\-setup\fP(1), \fBgnunet\-arm\fP(1) |
diff --git a/doc/release_policy.rfc.txt b/doc/release_policy.rfc.txt index fd4118742..b3d72bac4 100644 --- a/doc/release_policy.rfc.txt +++ b/doc/release_policy.rfc.txt | |||
@@ -117,7 +117,7 @@ platforms. It also doubt it will give you the recognition you crave. | |||
117 | More importantly, what you describe is already happening, and | 117 | More importantly, what you describe is already happening, and |
118 | partially has contributed to the problems. Bart kept his own CADET | 118 | partially has contributed to the problems. Bart kept his own CADET |
119 | hacks in his personal branch for years, hence without much feedback or | 119 | hacks in his personal branch for years, hence without much feedback or |
120 | review. The SecuShare team kept their patches in their own branch, | 120 | review. The secushare team kept their patches in their own branch, |
121 | hence revealing interesting failure modes when it was finally merged. | 121 | hence revealing interesting failure modes when it was finally merged. |
122 | Martin kept some of his ABE-logic in his own branch (that one was | 122 | Martin kept some of his ABE-logic in his own branch (that one was |
123 | merged without me noticing major problems). Anyway, what you propose | 123 | merged without me noticing major problems). Anyway, what you propose |
diff --git a/doc/system_specific/FROM_SOURCE b/doc/system_specific/FROM_SOURCE new file mode 100644 index 000000000..074b6a91e --- /dev/null +++ b/doc/system_specific/FROM_SOURCE | |||
@@ -0,0 +1,1423 @@ | |||
1 | @node Build instructions for Ubuntu 12.04 using Git | ||
2 | @section Build instructions for Ubuntu 12.04 using Git | ||
3 | |||
4 | @menu | ||
5 | * Install the required build tools:: | ||
6 | * Install libgcrypt 1.6 and libgpg-error:: | ||
7 | * Install gnutls with DANE support:: | ||
8 | * Install libgnurl:: | ||
9 | * Install libmicrohttpd from Git:: | ||
10 | * Install libextractor from Git:: | ||
11 | * Install GNUnet dependencies:: | ||
12 | * Build GNUnet:: | ||
13 | * Install the GNUnet-gtk user interface from Git:: | ||
14 | @end menu | ||
15 | |||
16 | @node Install the required build tools | ||
17 | @subsection Install the required build tools | ||
18 | |||
19 | First, make sure Git is installed on your system: | ||
20 | |||
21 | @example | ||
22 | $ sudo apt-get install git | ||
23 | @end example | ||
24 | |||
25 | Install the essential buildtools: | ||
26 | |||
27 | @example | ||
28 | $ sudo apt-get install automake autopoint autoconf libtool | ||
29 | @end example | ||
30 | |||
31 | @node Install libgcrypt 1.6 and libgpg-error | ||
32 | @subsection Install libgcrypt 1.6 and libgpg-error | ||
33 | |||
34 | @ref{generic source installation - libgpg-error} | ||
35 | |||
36 | @node Install gnutls with DANE support | ||
37 | @subsection Install gnutls with DANE support | ||
38 | |||
39 | @itemize @bullet | ||
40 | @item @ref{generic source installation - nettle} | ||
41 | @item @ref{generic source installation - ldns} | ||
42 | @item @ref{generic source installation - libunbound/unbound} | ||
43 | @item @ref{generic source installation - gnutls} | ||
44 | @item @ref{generic source installation - libgcrypt} | ||
45 | @end itemize | ||
46 | |||
47 | @node Install libgnurl | ||
48 | @subsection Install libgnurl | ||
49 | |||
50 | Follow the @ref{generic source installation - libgnurl}. | ||
51 | |||
52 | @node Install libmicrohttpd from Git | ||
53 | @subsection Install libmicrohttpd from Git | ||
54 | |||
55 | @example | ||
56 | $ git clone https://gnunet.org/git/libmicrohttpd | ||
57 | $ cd libmicrohttpd/ | ||
58 | $ ./bootstrap | ||
59 | $ ./configure | ||
60 | $ sudo make install ; cd .. | ||
61 | @end example | ||
62 | |||
63 | @node Install libextractor from Git | ||
64 | @subsection Install libextractor from Git | ||
65 | |||
66 | Install libextractor dependencies: | ||
67 | |||
68 | @example | ||
69 | $ sudo apt-get install zlib1g-dev libgsf-1-dev libmpeg2-4-dev \ | ||
70 | libpoppler-dev libvorbis-dev libexiv2-dev libjpeg-dev \ | ||
71 | libtiff-dev libgif-dev libvorbis-dev libflac-dev libsmf-dev \ | ||
72 | g++ | ||
73 | @end example | ||
74 | |||
75 | Build libextractor: | ||
76 | |||
77 | @example | ||
78 | $ git clone https://gnunet.org/git/libextractor | ||
79 | $ cd libextractor | ||
80 | $ ./bootstrap | ||
81 | $ ./configure | ||
82 | $ sudo make install ; cd .. | ||
83 | @end example | ||
84 | |||
85 | @node Install GNUnet dependencies | ||
86 | @subsection Install GNUnet dependencies | ||
87 | |||
88 | @example | ||
89 | $ sudo apt-get install libidn11-dev libunistring-dev libglpk-dev \ | ||
90 | libpulse-dev libbluetooth-dev libsqlite-dev | ||
91 | @end example | ||
92 | |||
93 | Install libopus: | ||
94 | |||
95 | @example | ||
96 | $ wget http://downloads.xiph.org/releases/opus/opus-1.1.tar.gz | ||
97 | $ tar xf opus-1.1.tar.gz | ||
98 | $ cd opus-1.1/ | ||
99 | $ ./configure | ||
100 | $ sudo make install ; cd .. | ||
101 | @end example | ||
102 | |||
103 | Choose one or more database backends: | ||
104 | |||
105 | SQLite3: | ||
106 | @example | ||
107 | $ sudo apt-get install libsqlite3-dev | ||
108 | @end example | ||
109 | MySQL: | ||
110 | @example | ||
111 | $ sudo apt-get install libmysqlclient-dev | ||
112 | @end example | ||
113 | PostgreSQL: | ||
114 | @example | ||
115 | $ sudo apt-get install libpq-dev postgresql | ||
116 | @end example | ||
117 | |||
118 | |||
119 | |||
120 | @node Build GNUnet | ||
121 | @subsection Build GNUnet | ||
122 | |||
123 | |||
124 | |||
125 | @menu | ||
126 | * Configuring the installation path:: | ||
127 | * Configuring the system:: | ||
128 | * Installing components requiring sudo permission:: | ||
129 | * Build:: | ||
130 | @end menu | ||
131 | |||
132 | @node Configuring the installation path | ||
133 | @subsubsection Configuring the installation path | ||
134 | |||
135 | You can specify the location of the GNUnet installation by setting the | ||
136 | prefix when calling the configure script with @code{--prefix=DIRECTORY} | ||
137 | |||
138 | @example | ||
139 | $ export PATH=$PATH:DIRECTORY/bin | ||
140 | @end example | ||
141 | |||
142 | @node Configuring the system | ||
143 | @subsubsection Configuring the system | ||
144 | |||
145 | Please make sure NOW that you have created a user and group 'gnunet' | ||
146 | and additionally a group 'gnunetdns': | ||
147 | |||
148 | @example | ||
149 | $ sudo addgroup gnunet | ||
150 | $ sudo addgroup gnunetdns | ||
151 | $ sudo adduser gnunet | ||
152 | @end example | ||
153 | |||
154 | Each GNUnet user should be added to the 'gnunet' group (may | ||
155 | require fresh login to come into effect): | ||
156 | |||
157 | @example | ||
158 | $ sudo useradd -G gnunet | ||
159 | @end example | ||
160 | |||
161 | @node Installing components requiring sudo permission | ||
162 | @subsubsection Installing components requiring sudo permission | ||
163 | |||
164 | Some components, like the nss plugin required for GNS, may require root | ||
165 | permissions. To allow these few components to be installed use: | ||
166 | |||
167 | @example | ||
168 | $ ./configure --with-sudo | ||
169 | @end example | ||
170 | |||
171 | @node Build | ||
172 | @subsubsection Build | ||
173 | |||
174 | @example | ||
175 | $ git clone https://gnunet.org/git/gnunet/ | ||
176 | $ cd gnunet/ | ||
177 | $ ./bootstrap | ||
178 | @end example | ||
179 | |||
180 | Use the required configure call including the optional installation prefix | ||
181 | @code{PREFIX} or the sudo permissions: | ||
182 | |||
183 | @example | ||
184 | $ ./configure [ --with-sudo | --with-prefix=PREFIX ] | ||
185 | @end example | ||
186 | |||
187 | @example | ||
188 | $ make; sudo make install | ||
189 | @end example | ||
190 | |||
191 | After installing it, you need to create an empty configuration file: | ||
192 | |||
193 | @example | ||
194 | mkdir ~/.gnunet; touch ~/.gnunet/gnunet.conf | ||
195 | @end example | ||
196 | |||
197 | And finally you can start GNUnet with: | ||
198 | |||
199 | @example | ||
200 | $ gnunet-arm -s | ||
201 | @end example | ||
202 | |||
203 | @node Install the GNUnet-gtk user interface from Git | ||
204 | @subsection Install the GNUnet-gtk user interface from Git | ||
205 | |||
206 | |||
207 | Install depencies: | ||
208 | |||
209 | @example | ||
210 | $ sudo apt-get install libgtk-3-dev libunique-3.0-dev libgladeui-dev \ | ||
211 | libqrencode-dev | ||
212 | @end example | ||
213 | |||
214 | Build GNUnet (with an optional prefix) and execute: | ||
215 | |||
216 | @example | ||
217 | $ git clone https://gnunet.org/git/gnunet-gtk/ | ||
218 | $ cd gnunet-gtk/ | ||
219 | $ ./bootstrap | ||
220 | $ ./configure [--prefix=PREFIX] --with-gnunet=DIRECTORY | ||
221 | $ make; sudo make install | ||
222 | @end example | ||
223 | |||
224 | @node Build Instructions for Microsoft Windows Platforms | ||
225 | @section Build Instructions for Microsoft Windows Platforms | ||
226 | |||
227 | @menu | ||
228 | * Introduction to building on MS Windows:: | ||
229 | * Requirements:: | ||
230 | * Dependencies & Initial Setup:: | ||
231 | * GNUnet Installation:: | ||
232 | * Adjusting Windows for running and testing GNUnet:: | ||
233 | * Building the GNUnet Installer:: | ||
234 | * Using GNUnet with Netbeans on Windows:: | ||
235 | @end menu | ||
236 | |||
237 | @node Introduction to building on MS Windows | ||
238 | @subsection Introduction to building on MS Windows | ||
239 | |||
240 | |||
241 | This document is a guide to building GNUnet and its dependencies on | ||
242 | Windows platforms. GNUnet development is mostly done under GNU/Linux and | ||
243 | especially git checkouts may not build out of the box. | ||
244 | We regret any inconvenience, and if you have problems, please report | ||
245 | them. | ||
246 | |||
247 | @node Requirements | ||
248 | @subsection Requirements | ||
249 | |||
250 | The Howto is based upon a @strong{Windows Server 2008 32bit} | ||
251 | @strong{Installation}, @strong{sbuild} and thus a | ||
252 | @uref{http://www.mingw.org/wiki/MSYS, MSYS+MinGW} | ||
253 | (W32-GCC-Compiler-Suite + Unix-like Userland) installation. sbuild | ||
254 | is a convenient set of scripts which creates a working msys/mingw | ||
255 | installation and installs most dependencies required for GNUnet. | ||
256 | |||
257 | As of the point of the creation of these instructions, | ||
258 | GNUnet @strong{requires} a Windows @strong{Server} 2003 or | ||
259 | newer for full feature support. | ||
260 | Windows Vista and later will also work, but | ||
261 | @strong{non-server version can not run a VPN-Exit-Node} as the NAT | ||
262 | features have been removed as of Windows Vista. | ||
263 | |||
264 | @c TODO: We should document Windows 10! | ||
265 | @c It seems like the situation hasn't changed with W10 | ||
266 | |||
267 | @node Dependencies & Initial Setup | ||
268 | @subsection Dependencies & Initial Setup | ||
269 | |||
270 | |||
271 | @itemize @bullet | ||
272 | |||
273 | @item | ||
274 | Install a fresh version of @strong{Python 2.x}, even if you are using a | ||
275 | x64-OS, install a 32-bit version for use with sbuild. | ||
276 | Python 3.0 is currently incompatible. | ||
277 | |||
278 | @item | ||
279 | Install your favorite @uref{http://code.google.com/p/tortoisegit/, git} & | ||
280 | @uref{http://tortoisesvn.net/, subversion}-clients. | ||
281 | |||
282 | @item | ||
283 | You will also need some archive-manager like | ||
284 | @uref{http://www.7-zip.org/, 7zip}. | ||
285 | |||
286 | @item | ||
287 | Pull a copy of sbuild to a directory of your choice, which will be used | ||
288 | in the remainder of this guide. For now, we will use | ||
289 | @file{c:\gnunet\sbuild\} | ||
290 | |||
291 | @item | ||
292 | in @file{sbuild\src\mingw\mingw32-buildall.sh}, comment out the packages | ||
293 | @strong{gnunet-svn} and @strong{gnunet-gtk-svn}, as we don't want sbuild | ||
294 | to compile/install those for us. | ||
295 | |||
296 | @item | ||
297 | Follow LRN's sbuild installation instructions.- | ||
298 | @end itemize | ||
299 | |||
300 | Please note that sbuild may (or will most likely) fail during | ||
301 | installation, thus you really HAVE to @strong{check the logfiles} created | ||
302 | during the installation process. | ||
303 | Certain packages may fail to build initially due to missing dependencies, | ||
304 | thus you may have to | ||
305 | @strong{substitute those with binary-versions initially}. Later on once | ||
306 | dependencies are satisfied you can re-build the newer package versions. | ||
307 | |||
308 | @strong{It is normal that you may have to repeat this step multiple times | ||
309 | and there is no uniform way to fix all compile-time issues, as the | ||
310 | build-process of many of the dependencies installed are rather unstable | ||
311 | on win32 and certain releases may not even compile at all.} | ||
312 | |||
313 | Most dependencies for GNUnet have been set up by sbuild, thus we now | ||
314 | should add the @file{bin/} directories in your new msys and mingw | ||
315 | installations to PATH. You will want to create a backup of your finished | ||
316 | msys-environment by now. | ||
317 | |||
318 | @node GNUnet Installation | ||
319 | @subsection GNUnet Installation | ||
320 | |||
321 | First, we need to launch our msys-shell, you can do this via | ||
322 | |||
323 | @file{C:\gnunet\sbuild\msys\msys.bat} | ||
324 | |||
325 | You might wish to take a look at this file and adjust some | ||
326 | login-parameters to your msys environment. | ||
327 | |||
328 | Also, sbuild added two pointpoints to your msys-environment, though those | ||
329 | might remain invisible: | ||
330 | |||
331 | @itemize @bullet | ||
332 | |||
333 | @item | ||
334 | /mingw, which will mount your mingw-directory from sbuild/mingw and the | ||
335 | other one is | ||
336 | |||
337 | @item | ||
338 | /src which contains all the installation sources sbuild just compiled. | ||
339 | @end itemize | ||
340 | |||
341 | Check out the current GNUnet sources (git HEAD) from the | ||
342 | GNUnet repository "gnunet.git", we will do this in your home directory: | ||
343 | |||
344 | @code{git clone https://gnunet.org/git/gnunet/ ~/gnunet} | ||
345 | |||
346 | Now, we will first need to bootstrap the checked out installation and then | ||
347 | configure it accordingly. | ||
348 | |||
349 | @example | ||
350 | cd ~/gnunet | ||
351 | ./bootstrap | ||
352 | STRIP=true CPPFLAGS="-DUSE_IPV6=1 -DW32_VEH" CFLAGS="$CFLAGS -g -O2" \ | ||
353 | ./configure --prefix=/ --docdir=/share/doc/gnunet \ | ||
354 | --with-libiconv-prefix=/mingw --with-libintl-prefix=/mingw \ | ||
355 | --with-libcurl=/mingw --with-extractor=/mingw --with-sqlite=/mingw \ | ||
356 | --with-microhttpd=/mingw --with-plibc=/mingw --enable-benchmarks \ | ||
357 | --enable-expensivetests --enable-experimental --with-qrencode=/mingw \ | ||
358 | --enable-silent-rules --enable-experimental 2>&1 | tee -a ./configure.log | ||
359 | @end example | ||
360 | |||
361 | The parameters above will configure for a reasonable GNUnet installation | ||
362 | to the your msys-root directory. | ||
363 | Depending on which features your would like to build or you may need to | ||
364 | specify additional dependencies. Sbuild installed most libs into | ||
365 | the /mingw subdirectory, so remember to prefix library locations with | ||
366 | this path. | ||
367 | |||
368 | Like on a unixoid system, you might want to use your home directory as | ||
369 | prefix for your own GNUnet installation for development, without tainting | ||
370 | the buildenvironment. Just change the "prefix" parameter to point towards | ||
371 | ~/ in this case. | ||
372 | |||
373 | Now it's time to compile GNUnet as usual. Though this will take some time, | ||
374 | so you may fetch yourself a coffee or some Mate now... | ||
375 | |||
376 | @example | ||
377 | make ; make install | ||
378 | @end example | ||
379 | |||
380 | @node Adjusting Windows for running and testing GNUnet | ||
381 | @subsection Adjusting Windows for running and testing GNUnet | ||
382 | |||
383 | Assuming the build succeeded and you | ||
384 | @strong{added the bin directory of your GNUnet to PATH}, you can now use | ||
385 | your gnunet-installation as usual. | ||
386 | Remember that UAC or the windows firewall may popup initially, blocking | ||
387 | further execution of gnunet until you acknowledge them. | ||
388 | |||
389 | You will also have to take the usual steps to get peer-to-peer (p2p) | ||
390 | software running properly (port forwarding, ...), | ||
391 | and GNUnet will require administrative permissions as it may even | ||
392 | install a device-driver (in case you are using gnunet-vpn and/or | ||
393 | gnunet-exit). | ||
394 | |||
395 | @node Building the GNUnet Installer | ||
396 | @subsection Building the GNUnet Installer | ||
397 | |||
398 | The GNUnet installer is made with | ||
399 | @uref{http://nsis.sourceforge.net/, NSIS}. | ||
400 | The installer script is located in @file{contrib\win} in the | ||
401 | GNUnet source tree. | ||
402 | |||
403 | @node Using GNUnet with Netbeans on Windows | ||
404 | @subsection Using GNUnet with Netbeans on Windows | ||
405 | |||
406 | TODO | ||
407 | |||
408 | @node Build instructions for Debian 7.5 | ||
409 | @section Build instructions for Debian 7.5 | ||
410 | |||
411 | |||
412 | These are the installation instructions for Debian 7.5. They were tested | ||
413 | using a minimal, fresh Debian 7.5 AMD64 installation without non-free | ||
414 | software (no contrib or non-free). | ||
415 | By "minimal", we mean that during installation, we did not select any | ||
416 | desktop environment, servers or system utilities during the "tasksel" | ||
417 | step. Note that the packages and the dependencies that we will install | ||
418 | during this chapter take about 1.5 GB of disk space. | ||
419 | Combined with GNUnet and space for objects during compilation, you should | ||
420 | not even attempt this unless you have about 2.5 GB free after the minimal | ||
421 | Debian installation. | ||
422 | Using these instructions to build a VM image is likely to require a | ||
423 | minimum of 4-5 GB for the VM (as you will likely also want a desktop | ||
424 | manager). | ||
425 | |||
426 | GNUnet's security model assumes that your @file{/home} directory is | ||
427 | encrypted. Thus, if possible, you should encrypt your home partition | ||
428 | (or per-user home directory). | ||
429 | |||
430 | Naturally, the exact details of the starting state for your installation | ||
431 | should not matter much. For example, if you selected any of those | ||
432 | installation groups you might simply already have some of the necessary | ||
433 | packages installed. | ||
434 | We did this for testing, as this way we are less likely to forget to | ||
435 | mention a required package. | ||
436 | Note that we will not install a desktop environment, but of course you | ||
437 | will need to install one to use GNUnet's graphical user interfaces. | ||
438 | Thus, it is suggested that you simply install the desktop environment of | ||
439 | your choice before beginning with the instructions. | ||
440 | |||
441 | |||
442 | |||
443 | @menu | ||
444 | * Update:: | ||
445 | * Stable? Hah!:: | ||
446 | * Update again:: | ||
447 | * Installing packages:: | ||
448 | * Installing dependencies from source:: | ||
449 | * Installing GNUnet from source:: | ||
450 | * But wait there is more!:: | ||
451 | @end menu | ||
452 | |||
453 | @node Update | ||
454 | @subsection Update | ||
455 | |||
456 | After any installation, you should begin by running | ||
457 | |||
458 | @example | ||
459 | # apt-get update ; apt-get upgrade | ||
460 | @end example | ||
461 | |||
462 | to ensure that all of your packages are up-to-date. Note that the "#" is | ||
463 | used to indicate that you need to type in this command as "root" | ||
464 | (or prefix with "sudo"), whereas "$" is used to indicate typing in a | ||
465 | command as a normal user. | ||
466 | |||
467 | @node Stable? Hah! | ||
468 | @subsection Stable? Hah! | ||
469 | |||
470 | Yes, we said we start with a Debian 7.5 "stable" system. However, to | ||
471 | reduce the amount of compilation by hand, we will begin by allowing the | ||
472 | installation of packages from the testing and unstable distributions as | ||
473 | well. | ||
474 | We will stick to "stable" packages where possible, but some packages will | ||
475 | be taken from the other distributions. | ||
476 | Start by modifying @file{/etc/apt/sources.list} to contain the | ||
477 | following (possibly adjusted to point to your mirror of choice): | ||
478 | |||
479 | @example | ||
480 | # These were there before: | ||
481 | deb http://ftp.de.debian.org/debian/ wheezy main | ||
482 | deb-src http://ftp.de.debian.org/debian/ wheezy main | ||
483 | deb http://security.debian.org/ wheezy/updates main | ||
484 | deb-src http://security.debian.org/ wheezy/updates main | ||
485 | deb http://ftp.de.debian.org/debian/ wheezy-updates main | ||
486 | deb-src http://ftp.de.debian.org/debian/ wheezy-updates main | ||
487 | |||
488 | # Add these lines (feel free to adjust the mirror): | ||
489 | deb http://ftp.de.debian.org/debian/ testing main | ||
490 | deb http://ftp.de.debian.org/debian/ unstable main | ||
491 | @end example | ||
492 | |||
493 | The next step is to create/edit your @file{/etc/apt/preferences} | ||
494 | file to look like this: | ||
495 | |||
496 | @example | ||
497 | Package: * | ||
498 | Pin: release a=stable,n=wheezy | ||
499 | Pin-Priority: 700 | ||
500 | |||
501 | Package: * | ||
502 | Pin: release o=Debian,a=testing | ||
503 | Pin-Priority: 650 | ||
504 | |||
505 | Package: * | ||
506 | Pin: release o=Debian,a=unstable | ||
507 | Pin-Priority: 600 | ||
508 | @end example | ||
509 | |||
510 | You can read more about Apt Preferences here and here. | ||
511 | Note that other pinnings are likely to also work for GNUnet, the key | ||
512 | thing is that you need some packages from unstable (as shown below). | ||
513 | However, as unstable is unlikely to be comprehensive (missing packages) | ||
514 | or might be problematic (crashing packages), you probably want others | ||
515 | from stable and/or testing. | ||
516 | |||
517 | @node Update again | ||
518 | @subsection Update again | ||
519 | |||
520 | Now, run again@ | ||
521 | |||
522 | @example | ||
523 | # apt-get update@ | ||
524 | # apt-get upgrade@ | ||
525 | @end example | ||
526 | |||
527 | to ensure that all your new distribution indices are downloaded, and | ||
528 | that your pinning is correct: the upgrade step should cause no changes | ||
529 | at all. | ||
530 | |||
531 | @node Installing packages | ||
532 | @subsection Installing packages | ||
533 | |||
534 | We begin by installing a few Debian packages from stable:@ | ||
535 | |||
536 | @example | ||
537 | # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \ | ||
538 | libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev \ | ||
539 | texlive libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev \ | ||
540 | libbz2-dev libexiv2-dev libflac-dev libgif-dev libglib2.0-dev \ | ||
541 | libgtk-3-dev libmagic-dev libjpeg8-dev libmpeg2-4-dev libmp4v2-dev \ | ||
542 | librpm-dev libsmf-dev libtidy-dev libtiff5-dev libvorbis-dev \ | ||
543 | libogg-dev zlib1g-dev g++ gettext libgsf-1-dev libunbound-dev \ | ||
544 | libqrencode-dev libgladeui-dev nasm texlive-latex-extra \ | ||
545 | libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev | ||
546 | @end example | ||
547 | |||
548 | After that, we install a few more packages from unstable:@ | ||
549 | |||
550 | @example | ||
551 | # apt-get install -t unstable nettle-dev libgstreamer1.0-dev \ | ||
552 | gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ | ||
553 | libgstreamer-plugins-base1.0-dev | ||
554 | @end example | ||
555 | |||
556 | @node Installing dependencies from source | ||
557 | @subsection Installing dependencies from source | ||
558 | |||
559 | Next, we need to install a few dependencies from source. | ||
560 | You might want to do this as a "normal" user and only run the | ||
561 | @code{make install} steps as root (hence the @code{sudo} in the | ||
562 | commands below). Also, you do this from any | ||
563 | directory. We begin by downloading all dependencies, then extracting the | ||
564 | sources, and finally compiling and installing the libraries. | ||
565 | |||
566 | For these steps, follow the instructions given in the | ||
567 | installation from source instruction in this order: | ||
568 | |||
569 | @itemize @bullet | ||
570 | @item @ref{generic source installation - libav} | ||
571 | @item @ref{generic source installation - libextractor} | ||
572 | @item @ref{generic source installation - libgpg-error} | ||
573 | @item @ref{generic source installation - libgcrypt} | ||
574 | @item @ref{generic source installation - gnutls} | ||
575 | @item @ref{generic source installation - libmicrohttpd} | ||
576 | @item @ref{generic source installation - libgnurl} | ||
577 | @end itemize | ||
578 | |||
579 | @node Installing GNUnet from source | ||
580 | @subsection Installing GNUnet from source | ||
581 | |||
582 | |||
583 | For this, simply follow the generic installation instructions from | ||
584 | here. | ||
585 | |||
586 | @node But wait there is more! | ||
587 | @subsection But wait there is more! | ||
588 | |||
589 | So far, we installed all of the packages and dependencies required to | ||
590 | ensure that all of GNUnet would be built. | ||
591 | However, while for example the plugins to interact with the MySQL or | ||
592 | Postgres databases have been created, we did not actually install or | ||
593 | configure those databases. Thus, you will need to install | ||
594 | and configure those databases or stick with the default Sqlite database. | ||
595 | Sqlite is usually fine for most applications, but MySQL can offer better | ||
596 | performance and Postgres better resillience. | ||
597 | |||
598 | |||
599 | @node Installing GNUnet from Git on Ubuntu 14.4 | ||
600 | @section Installing GNUnet from Git on Ubuntu 14.4 | ||
601 | |||
602 | @strong{Install the required build tools:} | ||
603 | |||
604 | @example | ||
605 | $ sudo apt-get install git automake autopoint autoconf | ||
606 | @end example | ||
607 | |||
608 | @strong{Install the required dependencies} | ||
609 | |||
610 | @example | ||
611 | $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ | ||
612 | libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \ | ||
613 | libmicrohttpd-dev libgnutls28-dev | ||
614 | @end example | ||
615 | |||
616 | @strong{Choose one or more database backends} | ||
617 | |||
618 | @itemize @bullet | ||
619 | |||
620 | @item SQLite3: | ||
621 | |||
622 | @example | ||
623 | $ sudo apt-get install libsqlite3-dev | ||
624 | @end example | ||
625 | |||
626 | @item MySQL: | ||
627 | |||
628 | @example | ||
629 | $ sudo apt-get install libmysqlclient-dev | ||
630 | @end example | ||
631 | |||
632 | @item PostgreSQL: | ||
633 | |||
634 | @example | ||
635 | $ sudo apt-get install libpq-dev postgresql | ||
636 | @end example | ||
637 | |||
638 | @end itemize | ||
639 | |||
640 | @strong{Install the optional dependencies for gnunet-conversation:} | ||
641 | |||
642 | @example | ||
643 | $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev | ||
644 | @end example | ||
645 | |||
646 | @strong{Install the libgrypt 1.6.1:} | ||
647 | |||
648 | @itemize @bullet | ||
649 | |||
650 | @item For Ubuntu 14.04: | ||
651 | |||
652 | @example | ||
653 | $ sudo apt-get install libgcrypt20-dev | ||
654 | @end example | ||
655 | |||
656 | @item For Ubuntu older 14.04: | ||
657 | |||
658 | @example | ||
659 | $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2 | ||
660 | $ tar xf libgcrypt-1.6.1.tar.bz2 | ||
661 | $ cd libgcrypt-1.6.1 | ||
662 | $ ./configure | ||
663 | $ sudo make install | ||
664 | $ cd .. | ||
665 | @end example | ||
666 | |||
667 | @end itemize | ||
668 | |||
669 | @strong{Install libgnurl} | ||
670 | |||
671 | @strong{Install GNUnet} | ||
672 | |||
673 | @example | ||
674 | $ git clone https://gnunet.org/git/gnunet/ | ||
675 | $ cd gnunet/ | ||
676 | $ ./bootstrap | ||
677 | @end example | ||
678 | |||
679 | If you want to: | ||
680 | |||
681 | @itemize @bullet | ||
682 | |||
683 | @item Install to a different directory: | ||
684 | |||
685 | @example | ||
686 | --prefix=PREFIX | ||
687 | @end example | ||
688 | |||
689 | @item | ||
690 | Have sudo permission, but do not want to compile as root: | ||
691 | |||
692 | @example | ||
693 | --with-sudo | ||
694 | @end example | ||
695 | |||
696 | @item | ||
697 | Want debug message enabled: | ||
698 | |||
699 | @example | ||
700 | --enable-logging=verbose | ||
701 | @end example | ||
702 | |||
703 | @end itemize | ||
704 | |||
705 | |||
706 | @example | ||
707 | $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose] | ||
708 | $ make; sudo make install | ||
709 | @end example | ||
710 | |||
711 | After installing it, you need to create an empty configuration file: | ||
712 | |||
713 | @example | ||
714 | touch ~/.config/gnunet.conf | ||
715 | @end example | ||
716 | |||
717 | And finally you can start GNUnet with | ||
718 | |||
719 | @example | ||
720 | $ gnunet-arm -s | ||
721 | @end example | ||
722 | |||
723 | @node Build instructions for Debian 8 | ||
724 | @section Build instructions for Debian 8 | ||
725 | @c FIXME: I -> we | ||
726 | |||
727 | These are the installation instructions for Debian 8. They were tested | ||
728 | sing a fresh Debian 8 AMD64 installation without non-free software (no | ||
729 | contrib or non-free). During installation, I only selected "lxde" for the | ||
730 | desktop environment. | ||
731 | Note that the packages and the dependencies that we will install during | ||
732 | this chapter take about 1.5 GB of disk space. Combined with GNUnet and | ||
733 | space for objects during compilation, you should not even attempt this | ||
734 | unless you have about 2.5 GB free after the Debian installation. | ||
735 | Using these instructions to build a VM image is likely to require a | ||
736 | minimum of 4-5 GB for the VM (as you will likely also want a desktop | ||
737 | manager). | ||
738 | |||
739 | GNUnet's security model assumes that your @code{/home} directory is | ||
740 | encrypted. | ||
741 | Thus, if possible, you should encrypt your entire disk, or at least just | ||
742 | your home partition (or per-user home directory). | ||
743 | |||
744 | Naturally, the exact details of the starting state for your installation | ||
745 | should not matter much. | ||
746 | For example, if you selected any of those installation groups you might | ||
747 | simply already have some of the necessary packages installed. Thus, it is | ||
748 | suggested that you simply install the desktop environment of your choice | ||
749 | before beginning with the instructions. | ||
750 | |||
751 | |||
752 | @menu | ||
753 | * Update Debian:: | ||
754 | * Installing Debian Packages:: | ||
755 | * Installing Dependencies from Source2:: | ||
756 | * Installing GNUnet from Source2:: | ||
757 | * But wait (again) there is more!:: | ||
758 | @end menu | ||
759 | |||
760 | @node Update Debian | ||
761 | @subsection Update Debian | ||
762 | |||
763 | After any installation, you should begin by running | ||
764 | |||
765 | @example | ||
766 | # apt-get update | ||
767 | # apt-get upgrade | ||
768 | @end example | ||
769 | |||
770 | to ensure that all of your packages are up-to-date. Note that the "#" is | ||
771 | used to indicate that you need to type in this command as "root" (or | ||
772 | prefix with "sudo"), whereas "$" is used to indicate typing in a command | ||
773 | as a normal user. | ||
774 | |||
775 | @node Installing Debian Packages | ||
776 | @subsection Installing Debian Packages | ||
777 | |||
778 | We begin by installing a few Debian packages from stable: | ||
779 | |||
780 | @example | ||
781 | # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \ | ||
782 | libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev texlive \ | ||
783 | libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev libbz2-dev \ | ||
784 | libflac-dev libgif-dev libglib2.0-dev libgtk-3-dev libmpeg2-4-dev \ | ||
785 | libtidy-dev libvorbis-dev libogg-dev zlib1g-dev g++ gettext \ | ||
786 | libgsf-1-dev libunbound-dev libqrencode-dev libgladeui-dev nasm \ | ||
787 | texlive-latex-extra libunique-3.0-dev gawk miniupnpc libfuse-dev \ | ||
788 | libbluetooth-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ | ||
789 | libgstreamer-plugins-base1.0-dev nettle-dev libextractor-dev \ | ||
790 | libgcrypt20-dev libmicrohttpd-dev | ||
791 | @end example | ||
792 | |||
793 | @node Installing Dependencies from Source2 | ||
794 | @subsection Installing Dependencies from Source2 | ||
795 | |||
796 | Yes, we said we start with a Debian 8 "stable" system, but because Debian | ||
797 | linked GnuTLS without support for DANE, we need to compile a few things, | ||
798 | in addition to GNUnet, still by hand. Yes, you can run GNUnet using the | ||
799 | respective Debian packages, but then you will not get DANE support. | ||
800 | |||
801 | Next, we need to install a few dependencies from source. You might want | ||
802 | to do this as a "normal" user and only run the @code{make install} steps | ||
803 | as root (hence the @code{sudo} in the commands below). Also, you do this | ||
804 | from any directory. We begin by downloading all dependencies, then | ||
805 | extracting the sources, and finally compiling and installing the | ||
806 | libraries: | ||
807 | |||
808 | @example | ||
809 | $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz | ||
810 | $ tar xvf gnutls-3.3.12.tar.xz | ||
811 | $ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd .. | ||
812 | @end example | ||
813 | |||
814 | For the installation and compilation of libgnurl/gnURL refer to | ||
815 | the generic installation section, | ||
816 | @xref{generic source installation - libgnurl}. | ||
817 | |||
818 | @node Installing GNUnet from Source2 | ||
819 | @subsection Installing GNUnet from Source2 | ||
820 | |||
821 | For this, simply follow the generic installation instructions from@ | ||
822 | here. | ||
823 | |||
824 | @node But wait (again) there is more! | ||
825 | @subsection But wait (again) there is more! | ||
826 | |||
827 | So far, we installed all of the packages and dependencies required to | ||
828 | ensure that all of GNUnet would be built. However, while for example the | ||
829 | plugins to interact with the MySQL or Postgres databases have been | ||
830 | created, we did not actually install or configure those databases. | ||
831 | Thus, you will need to install and configure those databases or stick | ||
832 | with the default Sqlite database. Sqlite is usually fine for most | ||
833 | applications, but MySQL can offer better performance and Postgres better | ||
834 | resillience. | ||
835 | |||
836 | @node Build instructions for macOS | ||
837 | @section Build instructions for macOS | ||
838 | @c FIXME: I -> we | ||
839 | |||
840 | These are the installation guidelines for macOS. | ||
841 | They were tested on macOS High Sierra. | ||
842 | |||
843 | @menu | ||
844 | * Installing dependencies:: | ||
845 | * Compile from Source:: | ||
846 | @end menu | ||
847 | |||
848 | @node Installing dependencies | ||
849 | @subsection Installing dependencies | ||
850 | |||
851 | First, install XCode in the newest version. | ||
852 | See https://developer.apple.com/xcode/. | ||
853 | |||
854 | Install Homebrew (https://brew.sh) and then install the dependencies listed above. | ||
855 | If a dependency does not exists in brew, you need to compile it from source. | ||
856 | |||
857 | @example | ||
858 | # brew install <dependency> | ||
859 | @end example | ||
860 | |||
861 | @node Compile from Source | ||
862 | @subsection Compile from Source | ||
863 | |||
864 | Before you start building GNUnet, you need to setup your environment. | ||
865 | This means that you have to make sure the proper tools are used in the build process. | ||
866 | For example, after installing texinfo you need to make sure the new texinfo is actually used: | ||
867 | |||
868 | @example | ||
869 | # echo 'export PATH="/usr/local/opt/texinfo/bin:$PATH"' >> ~/.bash_profile | ||
870 | @end example | ||
871 | |||
872 | Note: brew tells you the appropriate command when executing | ||
873 | |||
874 | @example | ||
875 | # brew info texinfo | ||
876 | @end example | ||
877 | |||
878 | This may also be necessary for the gettext package. | ||
879 | |||
880 | Before you start compiling, you need to make sure gcc is used and not the clang compile of your macOS system. | ||
881 | On my system, gcc was actually ``gcc-7'' and gcc pointed to the clang compiler. | ||
882 | |||
883 | @example | ||
884 | # export CC=gcc-7 | ||
885 | @end example | ||
886 | |||
887 | After this the standard compile instructions apply. | ||
888 | |||
889 | @c @node Build instructions for OpenBSD 6.2 | ||
890 | @c @section Build instructions for OpenBSD 6.2 | ||
891 | |||
892 | @node Outdated build instructions for previous revisions | ||
893 | @section Outdated build instructions for previous revisions | ||
894 | |||
895 | This chapter contains a collection of outdated, older installation guides. | ||
896 | They are mostly intended to serve as a starting point for writing | ||
897 | up-to-date instructions and should not be expected to work for | ||
898 | GNUnet 0.10.x. | ||
899 | A set of older installation instructions can also be found in the | ||
900 | file @file{doc/outdated-and-old-installation-instructions.txt} in the | ||
901 | source tree of GNUnet. | ||
902 | |||
903 | This file covers old instructions which no longer receive security | ||
904 | updates or any kind of support. | ||
905 | |||
906 | @menu | ||
907 | * Installing GNUnet 0.10.1 on Ubuntu 14.04:: | ||
908 | * Building GLPK for MinGW:: | ||
909 | * GUI build instructions for Ubuntu 12.04 using Subversion:: | ||
910 | @c * Installation with gnunet-update:: | ||
911 | * Instructions for Microsoft Windows Platforms (Old):: | ||
912 | @end menu | ||
913 | |||
914 | |||
915 | @node Installing GNUnet 0.10.1 on Ubuntu 14.04 | ||
916 | @subsection Installing GNUnet 0.10.1 on Ubuntu 14.04 | ||
917 | |||
918 | Install the required dependencies: | ||
919 | |||
920 | @example | ||
921 | $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ | ||
922 | libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \ | ||
923 | libmicrohttpd-dev libgnutls28-dev | ||
924 | @end example | ||
925 | |||
926 | Choose one or more database backends: | ||
927 | |||
928 | @itemize @bullet | ||
929 | |||
930 | @item SQLite3 | ||
931 | |||
932 | @example | ||
933 | $ sudo apt-get install libsqlite3-dev@ | ||
934 | @end example | ||
935 | |||
936 | @item MySQL | ||
937 | |||
938 | @example | ||
939 | $ sudo apt-get install libmysqlclient-dev@ | ||
940 | @end example | ||
941 | |||
942 | @item PostgreSQL | ||
943 | |||
944 | @example | ||
945 | $ sudo apt-get install libpq-dev postgresql@ | ||
946 | @end example | ||
947 | |||
948 | @end itemize | ||
949 | |||
950 | Install the optional dependencies for gnunet-conversation: | ||
951 | |||
952 | @example | ||
953 | $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev | ||
954 | @end example | ||
955 | |||
956 | Install libgcrypt 1.6: | ||
957 | |||
958 | @itemize @bullet | ||
959 | |||
960 | @item For Ubuntu 14.04: | ||
961 | |||
962 | @example | ||
963 | $ sudo apt-get install libgcrypt20-dev | ||
964 | @end example | ||
965 | |||
966 | @item For Ubuntu older than 14.04: | ||
967 | |||
968 | @example | ||
969 | wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2 | ||
970 | $ tar xf libgcrypt-1.6.1.tar.bz2 | ||
971 | $ cd libgcrypt-1.6.1 | ||
972 | $ ./configure | ||
973 | $ sudo make install | ||
974 | $ cd .. | ||
975 | @end example | ||
976 | @end itemize | ||
977 | |||
978 | Install libgnurl: | ||
979 | |||
980 | @pxref{generic source installation - libgnurl}. | ||
981 | |||
982 | Install GNUnet: | ||
983 | |||
984 | @example | ||
985 | $ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz | ||
986 | $ tar xf gnunet-0.10.1.tar.gz | ||
987 | $ cd gnunet-0.10.1 | ||
988 | @end example | ||
989 | |||
990 | If you want to: | ||
991 | |||
992 | @itemize @bullet | ||
993 | |||
994 | @item | ||
995 | Install to a different directory: | ||
996 | |||
997 | @example | ||
998 | --prefix=PREFIX | ||
999 | @end example | ||
1000 | |||
1001 | @item | ||
1002 | Have sudo permission, but do not want to compile as root: | ||
1003 | |||
1004 | @example | ||
1005 | --with-sudo | ||
1006 | @end example | ||
1007 | |||
1008 | @item | ||
1009 | Want debug message enabled: | ||
1010 | |||
1011 | @example | ||
1012 | --enable-logging=verbose | ||
1013 | @end example | ||
1014 | |||
1015 | @end itemize | ||
1016 | |||
1017 | @example | ||
1018 | $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose] | ||
1019 | $ make; sudo make install | ||
1020 | @end example | ||
1021 | |||
1022 | After installing it, you need to create an empty configuration file: | ||
1023 | |||
1024 | @example | ||
1025 | touch ~/.config/gnunet.conf | ||
1026 | @end example | ||
1027 | |||
1028 | And finally you can start GNUnet with | ||
1029 | |||
1030 | @example | ||
1031 | $ gnunet-arm -s | ||
1032 | @end example | ||
1033 | |||
1034 | @node Building GLPK for MinGW | ||
1035 | @subsection Building GLPK for MinGW | ||
1036 | |||
1037 | GNUnet now requires the GNU Linear Programming Kit (GLPK). | ||
1038 | Since there's is no package you can install with @code{mingw-get} you | ||
1039 | have to compile it from source: | ||
1040 | |||
1041 | @itemize @bullet | ||
1042 | |||
1043 | @item Download the latest version from | ||
1044 | @uref{http://ftp.gnu.org/gnu/glpk/} | ||
1045 | |||
1046 | @item Unzip the downloaded source tarball using your favourite | ||
1047 | unzipper application In the MSYS shell | ||
1048 | |||
1049 | @item change to the respective directory | ||
1050 | |||
1051 | @item Configure glpk for "i686-pc-mingw32": | ||
1052 | |||
1053 | @example | ||
1054 | ./configure '--build=i686-pc-mingw32' | ||
1055 | @end example | ||
1056 | |||
1057 | @item run | ||
1058 | |||
1059 | @example | ||
1060 | make install check | ||
1061 | @end example | ||
1062 | |||
1063 | @end itemize | ||
1064 | |||
1065 | MinGW does not automatically detect the correct buildtype so you have to | ||
1066 | specify it manually. | ||
1067 | |||
1068 | |||
1069 | @node GUI build instructions for Ubuntu 12.04 using Subversion | ||
1070 | @subsection GUI build instructions for Ubuntu 12.04 using Subversion | ||
1071 | |||
1072 | After installing GNUnet you can continue installing the GNUnet GUI tools: | ||
1073 | |||
1074 | First, install the required dependencies: | ||
1075 | |||
1076 | @example | ||
1077 | $ sudo apt-get install libgladeui-dev libqrencode-dev | ||
1078 | @end example | ||
1079 | |||
1080 | Please ensure that the GNUnet shared libraries can be found by the linker. | ||
1081 | If you installed GNUnet libraries in a non standard path | ||
1082 | (say GNUNET_PREFIX=/usr/local/lib/), you can | ||
1083 | |||
1084 | @itemize @bullet | ||
1085 | |||
1086 | @item set the environmental variable permanently to: | ||
1087 | |||
1088 | @example | ||
1089 | LD_LIBRARY_PATH=$GNUNET_PREFIX | ||
1090 | @end example | ||
1091 | |||
1092 | @item or add @code{$GNUNET_PREFIX} to @file{/etc/ld.so.conf} | ||
1093 | |||
1094 | @end itemize | ||
1095 | |||
1096 | Now you can checkout and compile the GNUnet GUI tools: | ||
1097 | |||
1098 | @example | ||
1099 | $ git clone https://gnunet.org/git/gnunet-gtk | ||
1100 | $ cd gnunet-gtk | ||
1101 | $ ./bootstrap | ||
1102 | $ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/.. | ||
1103 | $ make install | ||
1104 | @end example | ||
1105 | |||
1106 | @node Instructions for Microsoft Windows Platforms (Old) | ||
1107 | @subsection Instructions for Microsoft Windows Platforms (Old) | ||
1108 | |||
1109 | This document is a @b{DEPRECATED} installation guide for GNUnet on | ||
1110 | Windows. | ||
1111 | It will not work for recent GNUnet versions, but maybe it will be of | ||
1112 | some use if problems arise. | ||
1113 | |||
1114 | The Windows build uses a UNIX emulator for Windows, | ||
1115 | @uref{http://www.mingw.org/, MinGW}, to build the executable modules. | ||
1116 | These modules run natively on Windows and do not require additional | ||
1117 | emulation software besides the usual dependencies. | ||
1118 | |||
1119 | GNUnet development is mostly done under GNU/Linux and especially git | ||
1120 | checkouts may not build out of the box. | ||
1121 | We regret any inconvenience, and if you have problems, please report them. | ||
1122 | |||
1123 | @menu | ||
1124 | * Hardware and OS requirements:: | ||
1125 | * Software installation:: | ||
1126 | * Building libextractor and GNUnet:: | ||
1127 | * Installer:: | ||
1128 | * Source:: | ||
1129 | @end menu | ||
1130 | |||
1131 | @node Hardware and OS requirements | ||
1132 | @subsubsection Hardware and OS requirements | ||
1133 | |||
1134 | @itemize @bullet | ||
1135 | @item Pentium II or equivalent processor, @geq{} 350 MHz | ||
1136 | @item 128 MB RAM | ||
1137 | @item 600 MB free disk space | ||
1138 | @item Windows 2000 or Windows XP are recommended | ||
1139 | @end itemize | ||
1140 | |||
1141 | @node Software installation | ||
1142 | @subsubsection Software installation | ||
1143 | |||
1144 | @itemize @bullet | ||
1145 | |||
1146 | @item | ||
1147 | @strong{Compression software}@ | ||
1148 | |||
1149 | The software packages GNUnet depends on are usually compressed using UNIX | ||
1150 | tools like @command{tar}, @command{gzip}, @command{xzip} and | ||
1151 | @command{bzip2}. | ||
1152 | If you do not already have an utility that is able to extract such | ||
1153 | archives, get @uref{http://www.7-zip.org/, 7-Zip}. | ||
1154 | |||
1155 | @item | ||
1156 | @strong{UNIX environment}@ | ||
1157 | |||
1158 | The MinGW project provides the compiler toolchain that is used to build | ||
1159 | GNUnet. | ||
1160 | Get the following packages from the | ||
1161 | @uref{http://sourceforge.net/projects/mingw/files/, MinGW} project: | ||
1162 | |||
1163 | @itemize @bullet | ||
1164 | |||
1165 | @item GCC core | ||
1166 | @item GCC g++ | ||
1167 | @item MSYS | ||
1168 | @item MSYS Developer Tool Kit (msysDTK) | ||
1169 | @item MSYS Developer Tool Kit - msys-autoconf (bin) | ||
1170 | @item MSYS Developer Tool Kit - msys-automake (bin) | ||
1171 | @item MinGW Runtime | ||
1172 | @item MinGW Utilities | ||
1173 | @item Windows API | ||
1174 | @item Binutils | ||
1175 | @item make | ||
1176 | @item pdcurses | ||
1177 | @item GDB (snapshot) | ||
1178 | @end itemize | ||
1179 | |||
1180 | @itemize @bullet | ||
1181 | |||
1182 | |||
1183 | @item Install MSYS (to c:\mingw, for example.)@ | ||
1184 | Do @strong{not} use spaces in the pathname. | ||
1185 | For example, avoid a location such as @file{c:\program files\mingw}. | ||
1186 | |||
1187 | @item Install MinGW runtime, utilities and GCC to a subdirectory | ||
1188 | (to @file{c:\mingw\mingw}, for example) | ||
1189 | |||
1190 | @item Install the Development Kit to the MSYS directory | ||
1191 | (@file{c:\mingw}) | ||
1192 | |||
1193 | @item Create a batch file bash.bat in your MSYS directory with | ||
1194 | the files: | ||
1195 | |||
1196 | @example | ||
1197 | bin\sh.exe --login | ||
1198 | @end example | ||
1199 | |||
1200 | This batch file opens a shell which is used to invoke the build | ||
1201 | processes. | ||
1202 | MinGW's standard shell (@command{msys.bat}) is not suitable | ||
1203 | because it opens a separate console window. | ||
1204 | On Vista, @command{bash.bat} needs to be run as Administrator. | ||
1205 | |||
1206 | @item | ||
1207 | Start @command{bash.sh} and rename | ||
1208 | @file{c:\mingw\mingw\lib\libstdc++.la} to avoid problems: | ||
1209 | |||
1210 | @example | ||
1211 | mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken | ||
1212 | @end example | ||
1213 | |||
1214 | @item | ||
1215 | Unpack the Windows API to the MinGW directory (@file{c:\mingw\mingw\}) and | ||
1216 | remove the declaration of DATADIR from | ||
1217 | (@file{c:\mingw\mingw\include\objidl.h} (lines 55-58) | ||
1218 | |||
1219 | @item | ||
1220 | Unpack autoconf, automake to the MSYS directory (@file{c:\mingw}) | ||
1221 | |||
1222 | @item | ||
1223 | Install all other packages to the MinGW directory (@file{c:\mingw\mingw\}) | ||
1224 | @end itemize | ||
1225 | |||
1226 | |||
1227 | @item @strong{GNU Libtool}@ | ||
1228 | GNU Libtool is required to use shared libraries. | ||
1229 | Get the prebuilt package from here and unpack it to the | ||
1230 | MinGW directory (@file{c:\mingw}) | ||
1231 | |||
1232 | @item @strong{Pthreads}@ | ||
1233 | GNUnet uses the portable POSIX thread library for multi-threading: | ||
1234 | |||
1235 | @itemize @bullet | ||
1236 | |||
1237 | @item Save | ||
1238 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/libpthreadGC2.a, libpthreadGC2.a} | ||
1239 | (x86) or | ||
1240 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/libpthreadGC2.a, libpthreadGC2.a} | ||
1241 | (x64) as libpthread.a into the @file{lib} | ||
1242 | directory (@file{c:\mingw\mingw\lib\libpthread.a}). | ||
1243 | |||
1244 | @item Save | ||
1245 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/pthreadGC2.dll, pthreadGC2.dll} | ||
1246 | (x86) or | ||
1247 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/pthreadGC2.dll, libpthreadGC2.a} | ||
1248 | (x64) into the MinGW @file{bin} directory (@file{c:\mingw\mingw\bin}). | ||
1249 | |||
1250 | @item Download all header files from | ||
1251 | @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/include/, include/} | ||
1252 | to the @file{include} directory (@file{c:\mingw\mingw\include}). | ||
1253 | @end itemize | ||
1254 | |||
1255 | |||
1256 | @item @strong{GNU MP}@ | ||
1257 | GNUnet uses the GNU Multiple Precision library for special cryptographic | ||
1258 | operations. Get the GMP binary package from the | ||
1259 | @uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and | ||
1260 | unpack it to the MinGW directory (@file{c:\mingw\mingw}) | ||
1261 | |||
1262 | @item @strong{GNU Gettext}@ | ||
1263 | GNU gettext is used to provide national language support. | ||
1264 | Get the prebuilt package from hereand unpack it to the MinGW | ||
1265 | directory (@file{c:\mingw\mingw}) | ||
1266 | |||
1267 | @item @strong{GNU iconv}@ | ||
1268 | GNU Libiconv is used for character encoding conversion. | ||
1269 | Get the prebuilt package from here and unpack it to the MinGW | ||
1270 | directory (@file{c:\mingw\mingw}). | ||
1271 | |||
1272 | @item @strong{SQLite}@ | ||
1273 | GNUnet uses the SQLite database to store data. | ||
1274 | Get the prebuilt binary from here and unpack it to your MinGW directory. | ||
1275 | |||
1276 | @item @strong{MySQL}@ | ||
1277 | As an alternative to SQLite, GNUnet also supports MySQL. | ||
1278 | |||
1279 | @itemize @bullet | ||
1280 | |||
1281 | @item Get the binary installer from the | ||
1282 | @uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project} | ||
1283 | (version 4.1), install it and follow the instructions in | ||
1284 | @file{README.mysql}. | ||
1285 | |||
1286 | @item Create a temporary build directory (@file{c:\mysql}) | ||
1287 | |||
1288 | @item Copy the directories @file{include\} and @file{lib\} from the | ||
1289 | MySQL directory to the new directory | ||
1290 | |||
1291 | @item Get the patches from | ||
1292 | @uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and | ||
1293 | @uref{http://bugs.mysql.com/bug.php?id=8872&files=1, Bug #8872} (the | ||
1294 | latter is only required for MySQL | ||
1295 | |||
1296 | @example | ||
1297 | patch -p 0 | ||
1298 | @end example | ||
1299 | |||
1300 | @item Move @file{lib\opt\libmysql.dll} to @file{lib\libmysql.dll} | ||
1301 | |||
1302 | @item Change to @file{lib\} and create an import library: | ||
1303 | |||
1304 | @example | ||
1305 | dlltool --input-def ../include/libmySQL.def \ | ||
1306 | --dllname libmysql.dll \ | ||
1307 | --output-lib libmysqlclient.a -k | ||
1308 | @end example | ||
1309 | |||
1310 | @item Copy include\* to include\mysql\ | ||
1311 | |||
1312 | @item Pass @code{--with-mysql=/c/mysql} to | ||
1313 | @command{./configure} and copy @file{libmysql.dll} | ||
1314 | to your PATH or GNUnet's @file{bin} directory | ||
1315 | @end itemize | ||
1316 | |||
1317 | |||
1318 | @item @strong{GTK+}@ | ||
1319 | @command{gnunet-fs-gtk} and @command{libextractor} depend on GTK. | ||
1320 | Get the the binary and developer packages of @command{atk}, | ||
1321 | @command{glib}, @command{gtk}, @command{iconv}, | ||
1322 | @command{gettext-runtime}, @command{pango} from | ||
1323 | @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack them | ||
1324 | to the MinGW directory (@file{c:\mingw\mingw}). | ||
1325 | @c FIXME: The URL below for pkg-config seems wrong. | ||
1326 | Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and | ||
1327 | @command{libpng} and unpack them to the MinGW directory | ||
1328 | (@file{c:\mingw\mingw}). | ||
1329 | Here is an all-in-one package for the | ||
1330 | @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies} | ||
1331 | . Do not overwrite any existing files! | ||
1332 | |||
1333 | @item @strong{Glade}@ | ||
1334 | @command{gnunet-*-gtk} and @command{gnunet-setup} were created using | ||
1335 | this interface builder | ||
1336 | |||
1337 | @itemize @bullet | ||
1338 | |||
1339 | @item Get the Glade and libglade (-bin and -devel) packages | ||
1340 | (without GTK!) from | ||
1341 | @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack them to | ||
1342 | the MinGW directory (@file{c:\mingw\mingw}). | ||
1343 | |||
1344 | @item Get @command{libxml} from here and unpack it to the MinGW | ||
1345 | directory (@file{c:\mingw\mingw}). | ||
1346 | @end itemize | ||
1347 | |||
1348 | @c FIXME: URLs | ||
1349 | @item @strong{zLib}@ | ||
1350 | @command{libextractor} requires @command{zLib} to decompress some file | ||
1351 | formats. GNUnet uses it to (de)compress meta-data. | ||
1352 | Get zLib from here (Signature) and unpack it to the MinGW directory | ||
1353 | (@file{c:\mingw\mingw}). | ||
1354 | |||
1355 | @item @strong{Bzip2}@ | ||
1356 | @command{libextractor} also requires @command{Bzip2} to | ||
1357 | decompress some file formats. | ||
1358 | Get the Bzip2 (binary and developer package) from | ||
1359 | @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and | ||
1360 | unpack it to the MinGW directory (@file{c:\mingw\mingw}). | ||
1361 | |||
1362 | @item @strong{Libgcrypt}@ | ||
1363 | @command{Libgcrypt} provides the cryptographic functions used by GNUnet. | ||
1364 | Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here}, | ||
1365 | compile and place it in the MinGW directory | ||
1366 | (@file{c:\mingw\mingw}). Currently libgcrypt @geq{} 1.4.2 is required to | ||
1367 | compile GNUnet. | ||
1368 | |||
1369 | @item @strong{PlibC}@ | ||
1370 | PlibC emulates Unix functions under Windows. Get PlibC from here and | ||
1371 | unpack it to the MinGW directory (c:\mingw\mingw) | ||
1372 | |||
1373 | @item @strong{OGG Vorbis}@ | ||
1374 | @command{OGG Vorbis} is used to extract meta-data from @file{.ogg} files. | ||
1375 | Get the packages | ||
1376 | @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg} | ||
1377 | and | ||
1378 | @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis} | ||
1379 | from the | ||
1380 | @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build} | ||
1381 | and unpack them to the MinGW directory (c:\mingw\mingw). | ||
1382 | |||
1383 | @item @strong{Exiv2}@ | ||
1384 | (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data. | ||
1385 | Download | ||
1386 | @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2} | ||
1387 | and unpack it to the MSYS directory (c:\mingw). | ||
1388 | @end itemize | ||
1389 | |||
1390 | @node Building libextractor and GNUnet | ||
1391 | @subsubsection Building libextractor and GNUnet | ||
1392 | |||
1393 | Before you compile @command{libextractor} or @command{GNUnet}, | ||
1394 | be sure to set @code{PKG_CONFIG_PATH}: | ||
1395 | |||
1396 | @example | ||
1397 | export PKG_CONFIG_PATH=/mingw/lib/pkgconfig | ||
1398 | @end example | ||
1399 | |||
1400 | @noindent | ||
1401 | @xref{GNUnet Installation Handbook}, for basic instructions on building | ||
1402 | @command{libextractor} and @command{GNUnet}. | ||
1403 | By default, all modules that are created in this way contain | ||
1404 | debug information and are quite large. To compile release versions | ||
1405 | (small and fast) set the variable @code{CFLAGS}: | ||
1406 | |||
1407 | @example | ||
1408 | export CFLAGS='-O2 -march=pentium -fomit-frame-pointer' | ||
1409 | ./configure --prefix=$HOME --with-extractor=$HOME | ||
1410 | @end example | ||
1411 | |||
1412 | @node Installer | ||
1413 | @subsubsection Installer | ||
1414 | |||
1415 | The GNUnet installer is made with | ||
1416 | @uref{http://nsis.sourceforge.net/, NSIS}. The installer script is | ||
1417 | located in @file{contrib\win} in the GNUnet source tree. | ||
1418 | |||
1419 | @node Source | ||
1420 | @subsubsection Source | ||
1421 | |||
1422 | @c FIXME: URL... or: WHERE is HERE? | ||
1423 | The sources of all dependencies are available here. | ||
diff --git a/doc/outdated-and-old-installation-instructions.txt b/doc/system_specific/outdated-and-old-installation-instructions.txt index f2cbe1847..f2cbe1847 100644 --- a/doc/outdated-and-old-installation-instructions.txt +++ b/doc/system_specific/outdated-and-old-installation-instructions.txt | |||