diff options
23 files changed, 4419 insertions, 3544 deletions
diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am index 12f40f147..b6c666c4d 100644 --- a/doc/documentation/Makefile.am +++ b/doc/documentation/Makefile.am | |||
@@ -114,6 +114,7 @@ gnunet_TEXINFOS = \ | |||
114 | chapters/developer.texi \ | 114 | chapters/developer.texi \ |
115 | chapters/preface.texi \ | 115 | chapters/preface.texi \ |
116 | chapters/philosophy.texi \ | 116 | chapters/philosophy.texi \ |
117 | chapters/installation.texi \ | ||
117 | chapters/user.texi \ | 118 | chapters/user.texi \ |
118 | chapters/vocabulary.texi \ | 119 | chapters/vocabulary.texi \ |
119 | chapters/configuration.texi \ | 120 | chapters/configuration.texi \ |
@@ -143,6 +144,7 @@ DISTCLEANFILES = \ | |||
143 | chapters/terminology.cps \ | 144 | chapters/terminology.cps \ |
144 | chapters/vocabulary.cps \ | 145 | chapters/vocabulary.cps \ |
145 | fdl-1.3.cps \ | 146 | fdl-1.3.cps \ |
147 | agpl-3.0.cps \ | ||
146 | gpl-3.0.cps | 148 | gpl-3.0.cps |
147 | 149 | ||
148 | # if HAVE_EXTENDED_DOCUMENTATION_BUILDING | 150 | # if HAVE_EXTENDED_DOCUMENTATION_BUILDING |
@@ -165,8 +167,8 @@ lego_stack.png: images/lego_stack.svg | |||
165 | # echo "@set EDITION $(PACKAGE_VERSION)" >> $@ | 167 | # echo "@set EDITION $(PACKAGE_VERSION)" >> $@ |
166 | # echo "@set VERSION $(PACKAGE_VERSION)" >> $@ | 168 | # echo "@set VERSION $(PACKAGE_VERSION)" >> $@ |
167 | 169 | ||
168 | # Workaround for makeinfo error. Whcih in turn introduces more | 170 | # Workaround for makeinfo error. Which in turn introduces more |
169 | # date-related 'warnings'. Well. | 171 | # date-related 'warnings' for GNUism. Well. |
170 | version2.texi: | 172 | version2.texi: |
171 | echo "@set UPDATED $(date +'%d %B %Y')" > $@ | 173 | echo "@set UPDATED $(date +'%d %B %Y')" > $@ |
172 | echo "@set UPDATED-MONTH $(date +'%B %Y')" >> $@ | 174 | echo "@set UPDATED-MONTH $(date +'%B %Y')" >> $@ |
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..dc87de3d6 100644 --- a/doc/documentation/chapters/contributing.texi +++ b/doc/documentation/chapters/contributing.texi | |||
@@ -11,12 +11,14 @@ | |||
11 | @node Contributing to GNUnet | 11 | @node Contributing to GNUnet |
12 | @section Contributing to GNUnet | 12 | @section Contributing to GNUnet |
13 | 13 | ||
14 | @cindex licenses | ||
15 | @cindex licenses of contributions | ||
14 | @node Licenses of contributions | 16 | @node Licenses of contributions |
15 | @section Licenses of contributions | 17 | @section Licenses of contributions |
16 | 18 | ||
17 | GNUnet is a @uref{https://www.gnu.org/, GNU} package. | 19 | GNUnet is a @uref{https://www.gnu.org/, GNU} package. |
18 | All code contributions must thus be put under the | 20 | All code contributions must thus be put under the |
19 | @uref{https://www.gnu.org/copyleft/gpl.html, GNU Public License (GPL)}. | 21 | @uref{https://www.gnu.org/licenses/agpl.html, GNU Affero Public License (AGPL)}. |
20 | All documentation should be put under FSF approved licenses | 22 | All documentation should be put under FSF approved licenses |
21 | (see @uref{https://www.gnu.org/copyleft/fdl.html, fdl}). | 23 | (see @uref{https://www.gnu.org/copyleft/fdl.html, fdl}). |
22 | 24 | ||
@@ -40,7 +42,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 | 42 | retain non-exclusive rights to your contributions, so you can also |
41 | share your contributions freely with other projects. | 43 | share your contributions freely with other projects. |
42 | 44 | ||
43 | GNUnet e.V. will publish all accepted contributions under the GPLv3 | 45 | GNUnet e.V. will publish all accepted contributions under the AGPLv3 |
44 | or any later version. The association may decide to publish | 46 | or any later version. The association may decide to publish |
45 | contributions under additional licenses (dual-licensing). | 47 | contributions under additional licenses (dual-licensing). |
46 | 48 | ||
diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi new file mode 100644 index 000000000..f5e38fd3d --- /dev/null +++ b/doc/documentation/chapters/installation.texi | |||
@@ -0,0 +1,2167 @@ | |||
1 | @node Installing GNUnet | ||
2 | @chapter Installing GNUnet | ||
3 | |||
4 | This guide is intended for those who want to install Gnunet from source. For instructions on how to install GNUnet as a binary package please refer to the official documentation of your operating system or package manager. | ||
5 | |||
6 | @node Getting the Source Code | ||
7 | @section Installing dependencies | ||
8 | GNUnet needs few libraries and applications for being able to run and another few optional ones for using certain features. Preferably they should be installed with a package manager. Just in case we include a link to the project websites. | ||
9 | |||
10 | The mandatory libraries and applications are | ||
11 | @itemize @bullet | ||
12 | @item libtool | ||
13 | @item autoconf >= version 2.59 | ||
14 | @item automake >= version 1.11.1 | ||
15 | @item pkg-config | ||
16 | @item libgcrypt >= version 1.6 | ||
17 | @item libextractor | ||
18 | @item libidn | ||
19 | @item libmicrohttpd >= version 0.9.52 | ||
20 | @item libnss | ||
21 | @item libunistring | ||
22 | @item gettext | ||
23 | @item glibc | ||
24 | @item libgmp | ||
25 | @item gnutls | ||
26 | @item libcurl (has to be linked to GnuTLS) or libgnurl | ||
27 | @item zlib | ||
28 | @end itemize | ||
29 | |||
30 | In addition GNUnet needs one of of these three databases | ||
31 | @itemize @bullet | ||
32 | @item sqlite + libsqlite (the default, requires no further configuration) | ||
33 | @item postgres + libpq | ||
34 | @item mysql + libmysqlclient | ||
35 | @end itemize | ||
36 | |||
37 | These are the dependencies only required for certain features | ||
38 | @itemize @bullet | ||
39 | @item Texinfo (for building the documentation) | ||
40 | @item Texlive (for building the documentation) | ||
41 | @item miniupnpc (for traversing NAT boxes more reliably) | ||
42 | @item libopus (for running the GNUnet conversation telephony application) | ||
43 | @item libpulse (for running the GNUnet conversation telephony application) | ||
44 | @item libogg (for running the GNUnet conversation telephony application) | ||
45 | @item bluez (for bluetooth support) | ||
46 | @item libpbc (for attribute-based encryption and the identity provider subsystem) | ||
47 | @item libgabe (for attribute-based encryption and the identity provider subsystem) | ||
48 | @end itemize | ||
49 | |||
50 | |||
51 | @section Getting the Source Code | ||
52 | You can either download the source code using git (you obviously need git installed) or as an archive. | ||
53 | |||
54 | Using git type | ||
55 | @example | ||
56 | git clone https://gnunet.org/git/gnunet.git | ||
57 | @end example | ||
58 | |||
59 | The archive can be found at @uref{https://gnunet.org/downloads}. Extract it using a graphical archive tool or @code{tar}: | ||
60 | @example | ||
61 | tar xzvf gnunet-0.11.0pre66.tar.gz | ||
62 | @end example | ||
63 | |||
64 | In the next chapter we will assume that the source code is available in the home directory at @code{~/gnunet}. | ||
65 | |||
66 | @section Create @code{gnunet} user and group | ||
67 | The GNUnet services should be run as a dedicated user called @code{gnunet}. For using them a user should be in the same group as this system user. | ||
68 | |||
69 | Create user @code{gnunet} who is member of the group @code{gnunet} and specify a home directory where the GNUnet services will store persistant data such as information about peers. | ||
70 | @example | ||
71 | $ sudo useradd --system --groups gnunet --home-dir /var/lib/gnunet | ||
72 | @end example | ||
73 | |||
74 | Now add your own user to the @code{gnunet} group. | ||
75 | @example | ||
76 | $ sudo adduser alice gnunet | ||
77 | @end example | ||
78 | |||
79 | @section Preparing and Compiling the Source Code | ||
80 | For preparing the source code for compilation a bootstrap script and @code{configure} has to be run from the source code directory. When running @code{configure} the following options can be specified to customize the compilation and installation process: | ||
81 | |||
82 | @itemize @bullet | ||
83 | @item @code{--disable-documentation} - don't build the configuration documents | ||
84 | @item @code{--enable-looging=[LOGLEVEL]} - choose a loglevel (@code{debug}, @code{info}, @code{warning} or @code{error}) | ||
85 | @item @code{--prefix=[PATH]} - the directory where the GNUnet libraries and binaries will be installed | ||
86 | @item @code{--with-extractor=[PATH]} - the path to libextractor | ||
87 | @item @code{--with-libidn=[PATH]} - the path to libidn | ||
88 | @item @code{--with-microhttpd=[PATH]} - the path to libmicrohttpd | ||
89 | @item @code{--with-sqlite=[PATH]} - the path to libsqlite | ||
90 | @item @code{--with-zlib=[PATH]} - the path to zlib | ||
91 | @item @code{--with-sudo=[PATH]} - path to the sudo binary (no need to run @code{make install} as root if specified) | ||
92 | @end itemize | ||
93 | |||
94 | The following example configures the installation prefix @code{/usr/lib} and disables building the documentation | ||
95 | @example | ||
96 | $ cd ~/gnunet | ||
97 | $ ./bootstrap | ||
98 | $ configure --prefix=/usr/lib --disable-configuration | ||
99 | @end example | ||
100 | |||
101 | After running the bootstrap script and @code{configure} successfully the source code can be compiled with make. Here @code{-j5} specifies that 5 threads should be used. | ||
102 | @example | ||
103 | $ make -j5 | ||
104 | @end example | ||
105 | |||
106 | |||
107 | @section Installation | ||
108 | The compiled binaries can be installed using @code{make install}. It needs to be run as root (or with sudo) because some binaries need the @code{suid} bit set. Without that some GNUnet subsystems (such as VPN) will not work. | ||
109 | |||
110 | @example | ||
111 | $ sudo make install | ||
112 | @end example | ||
113 | |||
114 | One important library is the GNS plugin for NSS (the name services switch) which allows using GNS (the GNU name system) in the normal DNS resolution process. Unfortunately NSS expects it in a specific location (probably @code{/lib}) which may differ from the installation prefix (see @code{--prefix} option in the previous section). This is why the pugin has to be installed manually. | ||
115 | |||
116 | Find the directory where nss plugins are installed on your system, e.g. | ||
117 | |||
118 | @example | ||
119 | $ ls -l /lib/libnss_* | ||
120 | /lib/libnss_mymachines.so.2 | ||
121 | /lib/libnss_resolve.so.2 | ||
122 | /lib/libnss_myhostname.so.2 | ||
123 | /lib/libnss_systemd.so.2 | ||
124 | @end example | ||
125 | |||
126 | Copy the GNS NSS plugin to that directory: | ||
127 | |||
128 | @example | ||
129 | cp ~/gnunet/src/gns/nss/libnss_gns.so.2 /lib | ||
130 | @end example | ||
131 | |||
132 | Now, to activate the plugin, you need to edit your @code{/etc/nsswitch.conf} where you should find a line like this: | ||
133 | |||
134 | @example | ||
135 | hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 | ||
136 | @end example | ||
137 | |||
138 | The exact details may differ a bit, which is fine. Add the text @code{"gns [NOTFOUND=return]"} after @code{"files"}. | ||
139 | |||
140 | @example | ||
141 | hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 | ||
142 | @end example | ||
143 | |||
144 | Optionally, if GNS shall be used with a browser, execute the GNS CA-setup script. It will isetup the GNS Certificate Authority with the user's browser. | ||
145 | @example | ||
146 | $ gnunet-gns-proxy-setup-ca | ||
147 | @end example | ||
148 | |||
149 | Finally install a configuration file in @code{~/.gnunet/gnunet.conf}. Below you find an example config which allows you to start GNUnet. | ||
150 | |||
151 | @example | ||
152 | [arm] | ||
153 | SYSTEM_ONLY = NO | ||
154 | USER_ONLY = NO | ||
155 | |||
156 | [transport] | ||
157 | PLUGINS = tcp | ||
158 | @end example | ||
159 | |||
160 | |||
161 | |||
162 | |||
163 | |||
164 | |||
165 | @node MOVED FROM USER Checking the Installation | ||
166 | @section MOVED FROM USER Checking the Installation | ||
167 | @c %**end of header | ||
168 | |||
169 | This section describes a quick, casual way to check if your GNUnet | ||
170 | installation works. However, if it does not, we do not cover | ||
171 | steps for recovery --- for this, please study the instructions | ||
172 | provided in the developer handbook as well as the system-specific | ||
173 | instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}. | ||
174 | |||
175 | |||
176 | @menu | ||
177 | * gnunet-gtk:: | ||
178 | * Statistics:: | ||
179 | * Peer Information:: | ||
180 | @end menu | ||
181 | |||
182 | @cindex GNUnet GTK | ||
183 | @cindex GTK | ||
184 | @cindex GTK user interface | ||
185 | @node gnunet-gtk | ||
186 | @subsection gnunet-gtk | ||
187 | @c %**end of header | ||
188 | |||
189 | The @command{gnunet-gtk} package contains several graphical | ||
190 | user interfaces for the respective GNUnet applications. | ||
191 | Currently these interfaces cover: | ||
192 | |||
193 | @itemize @bullet | ||
194 | @item Statistics | ||
195 | @item Peer Information | ||
196 | @item GNU Name System | ||
197 | @item File Sharing | ||
198 | @item Identity Management | ||
199 | @item Conversation | ||
200 | @end itemize | ||
201 | |||
202 | @node Statistics | ||
203 | @subsection Statistics | ||
204 | @c %**end of header | ||
205 | |||
206 | First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}. | ||
207 | You can do this from the command-line by typing | ||
208 | |||
209 | @example | ||
210 | gnunet-statistics-gtk | ||
211 | @end example | ||
212 | |||
213 | If your peer@footnote{The term ``peer'' is a common word used in federated and distributed networks to describe a participating device which is connected to the network. Thus, your Personal Computer or whatever it is you are looking at the Gtk+ interface describes a ``Peer'' or a ``Node''.} | ||
214 | is running correctly, you should see a bunch of lines, | ||
215 | all of which should be ``significantly'' above zero (at least if your | ||
216 | peer has been running for more than a few seconds). The lines indicate | ||
217 | how many other peers your peer is connected to (via different | ||
218 | mechanisms) and how large the entire overlay network is currently | ||
219 | estimated to be. The X-axis represents time (in seconds since the | ||
220 | start of @command{gnunet-gtk}). | ||
221 | |||
222 | You can click on "Traffic" to see information about the amount of | ||
223 | bandwidth your peer has consumed, and on "Storage" to check the amount | ||
224 | of storage available and used by your peer. Note that "Traffic" is | ||
225 | plotted cumulatively, so you should see a strict upwards trend in the | ||
226 | traffic. | ||
227 | |||
228 | @node Peer Information | ||
229 | @subsection Peer Information | ||
230 | @c %**end of header | ||
231 | |||
232 | First, you should launch the graphical user interface. You can do | ||
233 | this from the command-line by typing | ||
234 | |||
235 | @example | ||
236 | $ gnunet-peerinfo-gtk | ||
237 | @end example | ||
238 | |||
239 | Once you have done this, you will see a list of known peers (by the | ||
240 | first four characters of their public key), their friend status (all | ||
241 | should be marked as not-friends initially), their connectivity (green | ||
242 | is connected, red is disconnected), assigned bandwidth, country of | ||
243 | origin (if determined) and address information. If hardly any peers | ||
244 | are listed and/or if there are very few peers with a green light for | ||
245 | connectivity, there is likely a problem with your network | ||
246 | configuration. | ||
247 | |||
248 | @c NOTE: Inserted from Installation Handbook in original ``order'': | ||
249 | @c FIXME: Move this to User Handbook. | ||
250 | @node MOVED FROM USER The graphical configuration interface | ||
251 | @section MOVED FROM USER The graphical configuration interface | ||
252 | |||
253 | If you also would like to use @command{gnunet-gtk} and | ||
254 | @command{gnunet-setup} (highly recommended for beginners), do: | ||
255 | |||
256 | @menu | ||
257 | * Configuring your peer:: | ||
258 | * Configuring the Friend-to-Friend (F2F) mode:: | ||
259 | * Configuring the hostlist to bootstrap:: | ||
260 | * Configuration of the HOSTLIST proxy settings:: | ||
261 | * Configuring your peer to provide a hostlist :: | ||
262 | * Configuring the datastore:: | ||
263 | * Configuring the MySQL database:: | ||
264 | * Reasons for using MySQL:: | ||
265 | * Reasons for not using MySQL:: | ||
266 | * Setup Instructions:: | ||
267 | * Testing:: | ||
268 | * Performance Tuning:: | ||
269 | * Setup for running Testcases:: | ||
270 | * Configuring the Postgres database:: | ||
271 | * Reasons to use Postgres:: | ||
272 | * Reasons not to use Postgres:: | ||
273 | * Manual setup instructions:: | ||
274 | * Testing the setup manually:: | ||
275 | * Configuring the datacache:: | ||
276 | * Configuring the file-sharing service:: | ||
277 | * Configuring logging:: | ||
278 | * Configuring the transport service and plugins:: | ||
279 | * Configuring the WLAN transport plugin:: | ||
280 | * Configuring HTTP(S) reverse proxy functionality using Apache or nginx:: | ||
281 | * Blacklisting peers:: | ||
282 | * Configuration of the HTTP and HTTPS transport plugins:: | ||
283 | * Configuring the GNU Name System:: | ||
284 | * Configuring the GNUnet VPN:: | ||
285 | * Bandwidth Configuration:: | ||
286 | * Configuring NAT:: | ||
287 | * Peer configuration for distributions:: | ||
288 | @end menu | ||
289 | |||
290 | @node Configuring your peer | ||
291 | @subsection Configuring your peer | ||
292 | |||
293 | This chapter will describe the various configuration options in GNUnet. | ||
294 | |||
295 | The easiest way to configure your peer is to use the | ||
296 | @command{gnunet-setup} tool. | ||
297 | @command{gnunet-setup} is part of the @command{gnunet-gtk} | ||
298 | application. You might have to install it separately. | ||
299 | |||
300 | Many of the specific sections from this chapter actually are linked from | ||
301 | within @command{gnunet-setup} to help you while using the setup tool. | ||
302 | |||
303 | While you can also configure your peer by editing the configuration | ||
304 | file by hand, this is not recommended for anyone except for developers | ||
305 | as it requires a more in-depth understanding of the configuration files | ||
306 | and internal dependencies of GNUnet. | ||
307 | |||
308 | @node Configuring the Friend-to-Friend (F2F) mode | ||
309 | @subsection Configuring the Friend-to-Friend (F2F) mode | ||
310 | |||
311 | GNUnet knows three basic modes of operation: | ||
312 | @itemize @bullet | ||
313 | @item In standard "peer-to-peer" mode, | ||
314 | your peer will connect to any peer. | ||
315 | @item In the pure "friend-to-friend" | ||
316 | mode, your peer will ONLY connect to peers from a list of friends | ||
317 | specified in the configuration. | ||
318 | @item Finally, in mixed mode, | ||
319 | GNUnet will only connect to arbitrary peers if it | ||
320 | has at least a specified number of connections to friends. | ||
321 | @end itemize | ||
322 | |||
323 | When configuring any of the F2F ("friend-to-friend") modes, | ||
324 | you first need to create a file with the peer identities | ||
325 | of your friends. Ask your friends to run | ||
326 | |||
327 | @example | ||
328 | $ gnunet-peerinfo -sq | ||
329 | @end example | ||
330 | |||
331 | @noindent | ||
332 | The resulting output of this command needs to be added to your | ||
333 | @file{friends} file, which is simply a plain text file with one line | ||
334 | per friend with the output from the above command. | ||
335 | |||
336 | You then specify the location of your @file{friends} file in the | ||
337 | @code{FRIENDS} option of the "topology" section. | ||
338 | |||
339 | Once you have created the @file{friends} file, you can tell GNUnet to only | ||
340 | connect to your friends by setting the @code{FRIENDS-ONLY} option | ||
341 | (again in the "topology" section) to YES. | ||
342 | |||
343 | If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a | ||
344 | minimum number of friends to have (before connecting to arbitrary peers) | ||
345 | under the "MINIMUM-FRIENDS" option. | ||
346 | |||
347 | If you want to operate in normal P2P-only mode, simply set | ||
348 | @code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO. | ||
349 | This is the default. | ||
350 | |||
351 | @node Configuring the hostlist to bootstrap | ||
352 | @subsection Configuring the hostlist to bootstrap | ||
353 | |||
354 | After installing the software you need to get connected to the GNUnet | ||
355 | network. The configuration file included in your download is already | ||
356 | configured to connect you to the GNUnet network. | ||
357 | In this section the relevant configuration settings are explained. | ||
358 | |||
359 | To get an initial connection to the GNUnet network and to get to know | ||
360 | peers already connected to the network you can use the so called | ||
361 | "bootstrap servers". | ||
362 | These servers can give you a list of peers connected to the network. | ||
363 | To use these bootstrap servers you have to configure the hostlist daemon | ||
364 | to activate bootstrapping. | ||
365 | |||
366 | To activate bootstrapping, edit the @code{[hostlist]}-section in your | ||
367 | configuration file. You have to set the argument @command{-b} in the | ||
368 | options line: | ||
369 | |||
370 | @example | ||
371 | [hostlist] | ||
372 | OPTIONS = -b | ||
373 | @end example | ||
374 | |||
375 | Additionally you have to specify which server you want to use. | ||
376 | The default bootstrapping server is | ||
377 | "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}". | ||
378 | [^] To set the server you have to edit the line "SERVERS" in the hostlist | ||
379 | section. To use the default server you should set the lines to | ||
380 | |||
381 | @example | ||
382 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
383 | @end example | ||
384 | |||
385 | @noindent | ||
386 | To use bootstrapping your configuration file should include these lines: | ||
387 | |||
388 | @example | ||
389 | [hostlist] | ||
390 | OPTIONS = -b | ||
391 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
392 | @end example | ||
393 | |||
394 | @noindent | ||
395 | Besides using bootstrap servers you can configure your GNUnet peer to | ||
396 | receive hostlist advertisements. | ||
397 | Peers offering hostlists to other peers can send advertisement messages | ||
398 | to peers that connect to them. If you configure your peer to receive these | ||
399 | messages, your peer can download these lists and connect to the peers | ||
400 | included. These lists are persistent, which means that they are saved to | ||
401 | your hard disk regularly and are loaded during startup. | ||
402 | |||
403 | To activate hostlist learning you have to add the @command{-e} | ||
404 | switch to the @code{OPTIONS} line in the hostlist section: | ||
405 | |||
406 | @example | ||
407 | [hostlist] | ||
408 | OPTIONS = -b -e | ||
409 | @end example | ||
410 | |||
411 | @noindent | ||
412 | Furthermore you can specify in which file the lists are saved. | ||
413 | To save the lists in the file @file{hostlists.file} just add the line: | ||
414 | |||
415 | @example | ||
416 | HOSTLISTFILE = hostlists.file | ||
417 | @end example | ||
418 | |||
419 | @noindent | ||
420 | Best practice is to activate both bootstrapping and hostlist learning. | ||
421 | So your configuration file should include these lines: | ||
422 | |||
423 | @example | ||
424 | [hostlist] | ||
425 | OPTIONS = -b -e | ||
426 | HTTPPORT = 8080 | ||
427 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
428 | HOSTLISTFILE = $SERVICEHOME/hostlists.file | ||
429 | @end example | ||
430 | |||
431 | @node Configuration of the HOSTLIST proxy settings | ||
432 | @subsection Configuration of the HOSTLIST proxy settings | ||
433 | |||
434 | The hostlist client can be configured to use a proxy to connect to the | ||
435 | hostlist server. | ||
436 | This functionality can be configured in the configuration file directly | ||
437 | or using the @command{gnunet-setup} tool. | ||
438 | |||
439 | The hostlist client supports the following proxy types at the moment: | ||
440 | |||
441 | @itemize @bullet | ||
442 | @item HTTP and HTTP 1.0 only proxy | ||
443 | @item SOCKS 4/4a/5/5 with hostname | ||
444 | @end itemize | ||
445 | |||
446 | In addition authentication at the proxy with username and password can be | ||
447 | configured. | ||
448 | |||
449 | To configure proxy support for the hostlist client in the | ||
450 | @command{gnunet-setup} tool, select the "hostlist" tab and select | ||
451 | the appropriate proxy type. | ||
452 | The hostname or IP address (including port if required) has to be entered | ||
453 | in the "Proxy hostname" textbox. If required, enter username and password | ||
454 | in the "Proxy username" and "Proxy password" boxes. | ||
455 | Be aware that this information will be stored in the configuration in | ||
456 | plain text (TODO: Add explanation and generalize the part in Chapter 3.6 | ||
457 | about the encrypted home). | ||
458 | |||
459 | To provide these options directly in the configuration, you can | ||
460 | enter the following settings in the @code{[hostlist]} section of | ||
461 | the configuration: | ||
462 | |||
463 | @example | ||
464 | # Type of proxy server, | ||
465 | # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME | ||
466 | # Default: HTTP | ||
467 | # PROXY_TYPE = HTTP | ||
468 | |||
469 | # Hostname or IP of proxy server | ||
470 | # PROXY = | ||
471 | # User name for proxy server | ||
472 | # PROXY_USERNAME = | ||
473 | # User password for proxy server | ||
474 | # PROXY_PASSWORD = | ||
475 | @end example | ||
476 | |||
477 | @node Configuring your peer to provide a hostlist | ||
478 | @subsection Configuring your peer to provide a hostlist | ||
479 | |||
480 | If you operate a peer permanently connected to GNUnet you can configure | ||
481 | your peer to act as a hostlist server, providing other peers the list of | ||
482 | peers known to him. | ||
483 | |||
484 | Your server can act as a bootstrap server and peers needing to obtain a | ||
485 | list of peers can contact it to download this list. | ||
486 | To download this hostlist the peer uses HTTP. | ||
487 | For this reason you have to build your peer with libgnurl (or libcurl) | ||
488 | and microhttpd support. | ||
489 | |||
490 | To configure your peer to act as a bootstrap server you have to add the | ||
491 | @command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section | ||
492 | of your configuration file. | ||
493 | Besides that you have to specify a port number for the http server. | ||
494 | In conclusion you have to add the following lines: | ||
495 | |||
496 | @example | ||
497 | [hostlist] | ||
498 | HTTPPORT = 12980 | ||
499 | OPTIONS = -p | ||
500 | @end example | ||
501 | |||
502 | @noindent | ||
503 | If your peer acts as a bootstrap server other peers should know about | ||
504 | that. You can advertise the hostlist your are providing to other peers. | ||
505 | Peers connecting to your peer will get a message containing an | ||
506 | advertisement for your hostlist and the URL where it can be downloaded. | ||
507 | If this peer is in learning mode, it will test the hostlist and, in the | ||
508 | case it can obtain the list successfully, it will save it for | ||
509 | bootstrapping. | ||
510 | |||
511 | To activate hostlist advertisement on your peer, you have to set the | ||
512 | following lines in your configuration file: | ||
513 | |||
514 | @example | ||
515 | [hostlist] | ||
516 | EXTERNAL_DNS_NAME = example.org | ||
517 | HTTPPORT = 12981 | ||
518 | OPTIONS = -p -a | ||
519 | @end example | ||
520 | |||
521 | @noindent | ||
522 | With this configuration your peer will a act as a bootstrap server and | ||
523 | advertise this hostlist to other peers connecting to it. | ||
524 | The URL used to download the list will be | ||
525 | @code{@uref{http://example.org:12981/, http://example.org:12981/}}. | ||
526 | |||
527 | Please notice: | ||
528 | |||
529 | @itemize @bullet | ||
530 | @item The hostlist is @b{not} human readable, so you should not try to | ||
531 | download it using your webbrowser. Just point your GNUnet peer to the | ||
532 | address! | ||
533 | @item Advertising without providing a hostlist does not make sense and | ||
534 | will not work. | ||
535 | @end itemize | ||
536 | |||
537 | @node Configuring the datastore | ||
538 | @subsection Configuring the datastore | ||
539 | |||
540 | The datastore is what GNUnet uses for long-term storage of file-sharing | ||
541 | data. Note that long-term does not mean 'forever' since content does have | ||
542 | an expiration date, and of course storage space is finite (and hence | ||
543 | sometimes content may have to be discarded). | ||
544 | |||
545 | Use the @code{QUOTA} option to specify how many bytes of storage space | ||
546 | you are willing to dedicate to GNUnet. | ||
547 | |||
548 | In addition to specifying the maximum space GNUnet is allowed to use for | ||
549 | the datastore, you need to specify which database GNUnet should use to do | ||
550 | so. Currently, you have the choice between sqLite, MySQL and Postgres. | ||
551 | |||
552 | @node Configuring the MySQL database | ||
553 | @subsection Configuring the MySQL database | ||
554 | |||
555 | This section describes how to setup the MySQL database for GNUnet. | ||
556 | |||
557 | Note that the mysql plugin does NOT work with mysql before 4.1 since we | ||
558 | need prepared statements. | ||
559 | We are generally testing the code against MySQL 5.1 at this point. | ||
560 | |||
561 | @node Reasons for using MySQL | ||
562 | @subsection Reasons for using MySQL | ||
563 | |||
564 | @itemize @bullet | ||
565 | |||
566 | @item On up-to-date hardware wher | ||
567 | mysql can be used comfortably, this module | ||
568 | will have better performance than the other database choices (according | ||
569 | to our tests). | ||
570 | |||
571 | @item Its often possible to recover the mysql database from internal | ||
572 | inconsistencies. Some of the other databases do not support repair. | ||
573 | @end itemize | ||
574 | |||
575 | @node Reasons for not using MySQL | ||
576 | @subsection Reasons for not using MySQL | ||
577 | |||
578 | @itemize @bullet | ||
579 | @item Memory usage (likely not an issue if you have more than 1 GB) | ||
580 | @item Complex manual setup | ||
581 | @end itemize | ||
582 | |||
583 | @node Setup Instructions | ||
584 | @subsection Setup Instructions | ||
585 | |||
586 | @itemize @bullet | ||
587 | |||
588 | @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for | ||
589 | @code{DATABASE} to @code{mysql}. | ||
590 | |||
591 | @item Access mysql as root: | ||
592 | |||
593 | @example | ||
594 | $ mysql -u root -p | ||
595 | @end example | ||
596 | |||
597 | @noindent | ||
598 | and issue the following commands, replacing $USER with the username | ||
599 | that will be running @command{gnunet-arm} (so typically "gnunet"): | ||
600 | |||
601 | @example | ||
602 | CREATE DATABASE gnunet; | ||
603 | GRANT select,insert,update,delete,create,alter,drop,create \ | ||
604 | temporary tables ON gnunet.* TO $USER@@localhost; | ||
605 | SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); | ||
606 | FLUSH PRIVILEGES; | ||
607 | @end example | ||
608 | |||
609 | @item | ||
610 | In the $HOME directory of $USER, create a @file{.my.cnf} file with the | ||
611 | following lines | ||
612 | |||
613 | @example | ||
614 | [client] | ||
615 | user=$USER | ||
616 | password=$the_password_you_like | ||
617 | @end example | ||
618 | |||
619 | @end itemize | ||
620 | |||
621 | That's it. Note that @file{.my.cnf} file is a slight security risk unless | ||
622 | its on a safe partition. The @file{$HOME/.my.cnf} can of course be | ||
623 | a symbolic link. | ||
624 | Luckily $USER has only privileges to mess up GNUnet's tables, | ||
625 | which should be pretty harmless. | ||
626 | |||
627 | @node Testing | ||
628 | @subsection Testing | ||
629 | |||
630 | You should briefly try if the database connection works. First, login | ||
631 | as $USER. Then use: | ||
632 | |||
633 | @example | ||
634 | $ mysql -u $USER | ||
635 | mysql> use gnunet; | ||
636 | @end example | ||
637 | |||
638 | @noindent | ||
639 | If you get the message | ||
640 | |||
641 | @example | ||
642 | Database changed | ||
643 | @end example | ||
644 | |||
645 | @noindent | ||
646 | it probably works. | ||
647 | |||
648 | If you get | ||
649 | |||
650 | @example | ||
651 | ERROR 2002: Can't connect to local MySQL server | ||
652 | through socket '/tmp/mysql.sock' (2) | ||
653 | @end example | ||
654 | |||
655 | @noindent | ||
656 | it may be resolvable by | ||
657 | |||
658 | @example | ||
659 | ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock | ||
660 | @end example | ||
661 | |||
662 | @noindent | ||
663 | so there may be some additional trouble depending on your mysql setup. | ||
664 | |||
665 | @node Performance Tuning | ||
666 | @subsection Performance Tuning | ||
667 | |||
668 | For GNUnet, you probably want to set the option | ||
669 | |||
670 | @example | ||
671 | innodb_flush_log_at_trx_commit = 0 | ||
672 | @end example | ||
673 | |||
674 | @noindent | ||
675 | for a rather dramatic boost in MySQL performance. However, this reduces | ||
676 | the "safety" of your database as with this options you may loose | ||
677 | transactions during a power outage. | ||
678 | While this is totally harmless for GNUnet, the option applies to all | ||
679 | applications using MySQL. So you should set it if (and only if) GNUnet is | ||
680 | the only application on your system using MySQL. | ||
681 | |||
682 | @node Setup for running Testcases | ||
683 | @subsection Setup for running Testcases | ||
684 | |||
685 | If you want to run the testcases, you must create a second database | ||
686 | "gnunetcheck" with the same username and password. This database will | ||
687 | then be used for testing (@command{make check}). | ||
688 | |||
689 | @node Configuring the Postgres database | ||
690 | @subsection Configuring the Postgres database | ||
691 | |||
692 | This text describes how to setup the Postgres database for GNUnet. | ||
693 | |||
694 | This Postgres plugin was developed for Postgres 8.3 but might work for | ||
695 | earlier versions as well. | ||
696 | |||
697 | @node Reasons to use Postgres | ||
698 | @subsection Reasons to use Postgres | ||
699 | |||
700 | @itemize @bullet | ||
701 | @item Easier to setup than MySQL | ||
702 | @item Real database | ||
703 | @end itemize | ||
704 | |||
705 | @node Reasons not to use Postgres | ||
706 | @subsection Reasons not to use Postgres | ||
707 | |||
708 | @itemize @bullet | ||
709 | @item Quite slow | ||
710 | @item Still some manual setup required | ||
711 | @end itemize | ||
712 | |||
713 | @node Manual setup instructions | ||
714 | @subsection Manual setup instructions | ||
715 | |||
716 | @itemize @bullet | ||
717 | @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for | ||
718 | @code{DATABASE} to @code{postgres}. | ||
719 | @item Access Postgres to create a user: | ||
720 | |||
721 | @table @asis | ||
722 | @item with Postgres 8.x, use: | ||
723 | |||
724 | @example | ||
725 | # su - postgres | ||
726 | $ createuser | ||
727 | @end example | ||
728 | |||
729 | @noindent | ||
730 | and enter the name of the user running GNUnet for the role interactively. | ||
731 | Then, when prompted, do not set it to superuser, allow the creation of | ||
732 | databases, and do not allow the creation of new roles. | ||
733 | |||
734 | @item with Postgres 9.x, use: | ||
735 | |||
736 | @example | ||
737 | # su - postgres | ||
738 | $ createuser -d $GNUNET_USER | ||
739 | @end example | ||
740 | |||
741 | @noindent | ||
742 | where $GNUNET_USER is the name of the user running GNUnet. | ||
743 | |||
744 | @end table | ||
745 | |||
746 | |||
747 | @item | ||
748 | As that user (so typically as user "gnunet"), create a database (or two): | ||
749 | |||
750 | @example | ||
751 | $ createdb gnunet | ||
752 | # this way you can run "make check" | ||
753 | $ createdb gnunetcheck | ||
754 | @end example | ||
755 | |||
756 | @end itemize | ||
757 | |||
758 | Now you should be able to start @code{gnunet-arm}. | ||
759 | |||
760 | @node Testing the setup manually | ||
761 | @subsection Testing the setup manually | ||
762 | |||
763 | You may want to try if the database connection works. First, again login | ||
764 | as the user who will run @command{gnunet-arm}. Then use: | ||
765 | |||
766 | @example | ||
767 | $ psql gnunet # or gnunetcheck | ||
768 | gnunet=> \dt | ||
769 | @end example | ||
770 | |||
771 | @noindent | ||
772 | If, after you have started @command{gnunet-arm} at least once, you get | ||
773 | a @code{gn090} table here, it probably works. | ||
774 | |||
775 | @node Configuring the datacache | ||
776 | @subsection Configuring the datacache | ||
777 | @c %**end of header | ||
778 | |||
779 | The datacache is what GNUnet uses for storing temporary data. This data is | ||
780 | expected to be wiped completely each time GNUnet is restarted (or the | ||
781 | system is rebooted). | ||
782 | |||
783 | You need to specify how many bytes GNUnet is allowed to use for the | ||
784 | datacache using the @code{QUOTA} option in the section @code{[dhtcache]}. | ||
785 | Furthermore, you need to specify which database backend should be used to | ||
786 | store the data. Currently, you have the choice between | ||
787 | sqLite, MySQL and Postgres. | ||
788 | |||
789 | @node Configuring the file-sharing service | ||
790 | @subsection Configuring the file-sharing service | ||
791 | |||
792 | In order to use GNUnet for file-sharing, you first need to make sure | ||
793 | that the file-sharing service is loaded. | ||
794 | This is done by setting the @code{START_ON_DEMAND} option in | ||
795 | section @code{[fs]} to "YES". Alternatively, you can run | ||
796 | |||
797 | @example | ||
798 | $ gnunet-arm -i fs | ||
799 | @end example | ||
800 | |||
801 | @noindent | ||
802 | to start the file-sharing service by hand. | ||
803 | |||
804 | Except for configuring the database and the datacache the only important | ||
805 | option for file-sharing is content migration. | ||
806 | |||
807 | Content migration allows your peer to cache content from other peers as | ||
808 | well as send out content stored on your system without explicit requests. | ||
809 | This content replication has positive and negative impacts on both system | ||
810 | performance and privacy. | ||
811 | |||
812 | FIXME: discuss the trade-offs. Here is some older text about it... | ||
813 | |||
814 | Setting this option to YES allows gnunetd to migrate data to the local | ||
815 | machine. Setting this option to YES is highly recommended for efficiency. | ||
816 | Its also the default. If you set this value to YES, GNUnet will store | ||
817 | content on your machine that you cannot decrypt. | ||
818 | While this may protect you from liability if the judge is sane, it may | ||
819 | not (IANAL). If you put illegal content on your machine yourself, setting | ||
820 | this option to YES will probably increase your chances to get away with it | ||
821 | since you can plausibly deny that you inserted the content. | ||
822 | Note that in either case, your anonymity would have to be broken first | ||
823 | (which may be possible depending on the size of the GNUnet network and the | ||
824 | strength of the adversary). | ||
825 | |||
826 | @node Configuring logging | ||
827 | @subsection Configuring logging | ||
828 | |||
829 | Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. | ||
830 | Using @code{-L}, a log level can be specified. With log level | ||
831 | @code{ERROR} only serious errors are logged. | ||
832 | The default log level is @code{WARNING} which causes anything of | ||
833 | concern to be logged. | ||
834 | Log level @code{INFO} can be used to log anything that might be | ||
835 | interesting information whereas | ||
836 | @code{DEBUG} can be used by developers to log debugging messages | ||
837 | (but you need to run @code{./configure} with | ||
838 | @code{--enable-logging=verbose} to get them compiled). | ||
839 | The @code{-l} option is used to specify the log file. | ||
840 | |||
841 | Since most GNUnet services are managed by @code{gnunet-arm}, using the | ||
842 | @code{-l} or @code{-L} options directly is not possible. | ||
843 | Instead, they can be specified using the @code{OPTIONS} configuration | ||
844 | value in the respective section for the respective service. | ||
845 | In order to enable logging globally without editing the @code{OPTIONS} | ||
846 | values for each service, @command{gnunet-arm} supports a | ||
847 | @code{GLOBAL_POSTFIX} option. | ||
848 | The value specified here is given as an extra option to all services for | ||
849 | which the configuration does contain a service-specific @code{OPTIONS} | ||
850 | field. | ||
851 | |||
852 | @code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which | ||
853 | is replaced by the name of the service that is being started. | ||
854 | Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences | ||
855 | starting with "$" anywhere in the string are expanded (according | ||
856 | to options in @code{PATHS}); this expansion otherwise is | ||
857 | only happening for filenames and then the "$" must be the | ||
858 | first character in the option. Both of these restrictions do | ||
859 | not apply to @code{GLOBAL_POSTFIX}. | ||
860 | Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX} | ||
861 | disables both of these features. | ||
862 | |||
863 | In summary, in order to get all services to log at level | ||
864 | @code{INFO} to log-files called @code{SERVICENAME-logs}, the | ||
865 | following global prefix should be used: | ||
866 | |||
867 | @example | ||
868 | GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO | ||
869 | @end example | ||
870 | |||
871 | @node Configuring the transport service and plugins | ||
872 | @subsection Configuring the transport service and plugins | ||
873 | |||
874 | The transport service in GNUnet is responsible to maintain basic | ||
875 | connectivity to other peers. | ||
876 | Besides initiating and keeping connections alive it is also responsible | ||
877 | for address validation. | ||
878 | |||
879 | The GNUnet transport supports more than one transport protocol. | ||
880 | These protocols are configured together with the transport service. | ||
881 | |||
882 | The configuration section for the transport service itself is quite | ||
883 | similar to all the other services | ||
884 | |||
885 | @example | ||
886 | START_ON_DEMAND = YES | ||
887 | @@UNIXONLY@@ PORT = 2091 | ||
888 | HOSTNAME = localhost | ||
889 | HOME = $SERVICEHOME | ||
890 | CONFIG = $DEFAULTCONFIG | ||
891 | BINARY = gnunet-service-transport | ||
892 | #PREFIX = valgrind | ||
893 | NEIGHBOUR_LIMIT = 50 | ||
894 | ACCEPT_FROM = 127.0.0.1; | ||
895 | ACCEPT_FROM6 = ::1; | ||
896 | PLUGINS = tcp udp | ||
897 | UNIXPATH = /tmp/gnunet-service-transport.sock | ||
898 | @end example | ||
899 | |||
900 | Different are the settings for the plugins to load @code{PLUGINS}. | ||
901 | The first setting specifies which transport plugins to load. | ||
902 | |||
903 | @itemize @bullet | ||
904 | @item transport-unix | ||
905 | A plugin for local only communication with UNIX domain sockets. Used for | ||
906 | testing and available on unix systems only. Just set the port | ||
907 | |||
908 | @example | ||
909 | [transport-unix] | ||
910 | PORT = 22086 | ||
911 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
912 | @end example | ||
913 | |||
914 | @item transport-tcp | ||
915 | A plugin for communication with TCP. Set port to 0 for client mode with | ||
916 | outbound only connections | ||
917 | |||
918 | @example | ||
919 | [transport-tcp] | ||
920 | # Use 0 to ONLY advertise as a peer behind NAT (no port binding) | ||
921 | PORT = 2086 | ||
922 | ADVERTISED_PORT = 2086 | ||
923 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
924 | # Maximum number of open TCP connections allowed | ||
925 | MAX_CONNECTIONS = 128 | ||
926 | @end example | ||
927 | |||
928 | @item transport-udp | ||
929 | A plugin for communication with UDP. Supports peer discovery using | ||
930 | broadcasts. | ||
931 | |||
932 | @example | ||
933 | [transport-udp] | ||
934 | PORT = 2086 | ||
935 | BROADCAST = YES | ||
936 | BROADCAST_INTERVAL = 30 s | ||
937 | MAX_BPS = 1000000 | ||
938 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
939 | @end example | ||
940 | |||
941 | @item transport-http | ||
942 | HTTP and HTTPS support is split in two part: a client plugin initiating | ||
943 | outbound connections and a server part accepting connections from the | ||
944 | client. The client plugin just takes the maximum number of connections as | ||
945 | an argument. | ||
946 | |||
947 | @example | ||
948 | [transport-http_client] | ||
949 | MAX_CONNECTIONS = 128 | ||
950 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
951 | @end example | ||
952 | |||
953 | @example | ||
954 | [transport-https_client] | ||
955 | MAX_CONNECTIONS = 128 | ||
956 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
957 | @end example | ||
958 | |||
959 | @noindent | ||
960 | The server has a port configured and the maximum number of connections. | ||
961 | The HTTPS part has two files with the certificate key and the certificate | ||
962 | file. | ||
963 | |||
964 | The server plugin supports reverse proxies, so a external hostname can be | ||
965 | set using the @code{EXTERNAL_HOSTNAME} setting. | ||
966 | The webserver under this address should forward the request to the peer | ||
967 | and the configure port. | ||
968 | |||
969 | @example | ||
970 | [transport-http_server] | ||
971 | EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet | ||
972 | PORT = 1080 | ||
973 | MAX_CONNECTIONS = 128 | ||
974 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
975 | @end example | ||
976 | |||
977 | @example | ||
978 | [transport-https_server] | ||
979 | PORT = 4433 | ||
980 | CRYPTO_INIT = NORMAL | ||
981 | KEY_FILE = https.key | ||
982 | CERT_FILE = https.cert | ||
983 | MAX_CONNECTIONS = 128 | ||
984 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
985 | @end example | ||
986 | |||
987 | @item transport-wlan | ||
988 | |||
989 | The next section describes how to setup the WLAN plugin, | ||
990 | so here only the settings. Just specify the interface to use: | ||
991 | |||
992 | @example | ||
993 | [transport-wlan] | ||
994 | # Name of the interface in monitor mode (typically monX) | ||
995 | INTERFACE = mon0 | ||
996 | # Real hardware, no testing | ||
997 | TESTMODE = 0 | ||
998 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
999 | @end example | ||
1000 | @end itemize | ||
1001 | |||
1002 | @node Configuring the WLAN transport plugin | ||
1003 | @subsection Configuring the WLAN transport plugin | ||
1004 | |||
1005 | The wlan transport plugin enables GNUnet to send and to receive data on a | ||
1006 | wlan interface. | ||
1007 | It has not to be connected to a wlan network as long as sender and | ||
1008 | receiver are on the same channel. This enables you to get connection to | ||
1009 | GNUnet where no internet access is possible, for example during | ||
1010 | catastrophes or when censorship cuts you off from the internet. | ||
1011 | |||
1012 | |||
1013 | @menu | ||
1014 | * Requirements for the WLAN plugin:: | ||
1015 | * Configuration:: | ||
1016 | * Before starting GNUnet:: | ||
1017 | * Limitations and known bugs:: | ||
1018 | @end menu | ||
1019 | |||
1020 | |||
1021 | @node Requirements for the WLAN plugin | ||
1022 | @subsubsection Requirements for the WLAN plugin | ||
1023 | |||
1024 | @itemize @bullet | ||
1025 | |||
1026 | @item wlan network card with monitor support and packet injection | ||
1027 | (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org}) | ||
1028 | |||
1029 | @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with | ||
1030 | 2.6.35 and 2.6.38 | ||
1031 | |||
1032 | @item Wlantools to create the a monitor interface, tested with airmon-ng | ||
1033 | of the aircrack-ng package | ||
1034 | @end itemize | ||
1035 | |||
1036 | @node Configuration | ||
1037 | @subsubsection Configuration | ||
1038 | |||
1039 | There are the following options for the wlan plugin (they should be like | ||
1040 | this in your default config file, you only need to adjust them if the | ||
1041 | values are incorrect for your system) | ||
1042 | |||
1043 | @example | ||
1044 | # section for the wlan transport plugin | ||
1045 | [transport-wlan] | ||
1046 | # interface to use, more information in the | ||
1047 | # "Before starting GNUnet" section of the handbook. | ||
1048 | INTERFACE = mon0 | ||
1049 | # testmode for developers: | ||
1050 | # 0 use wlan interface, | ||
1051 | #1 or 2 use loopback driver for tests 1 = server, 2 = client | ||
1052 | TESTMODE = 0 | ||
1053 | @end example | ||
1054 | |||
1055 | @node Before starting GNUnet | ||
1056 | @subsubsection Before starting GNUnet | ||
1057 | |||
1058 | Before starting GNUnet, you have to make sure that your wlan interface is | ||
1059 | in monitor mode. | ||
1060 | One way to put the wlan interface into monitor mode (if your interface | ||
1061 | name is wlan0) is by executing: | ||
1062 | |||
1063 | @example | ||
1064 | sudo airmon-ng start wlan0 | ||
1065 | @end example | ||
1066 | |||
1067 | @noindent | ||
1068 | Here is an example what the result should look like: | ||
1069 | |||
1070 | @example | ||
1071 | Interface Chipset Driver | ||
1072 | wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0] | ||
1073 | (monitor mode enabled on mon0) | ||
1074 | @end example | ||
1075 | |||
1076 | @noindent | ||
1077 | The monitor interface is mon0 is the one that you have to put into the | ||
1078 | configuration file. | ||
1079 | |||
1080 | @node Limitations and known bugs | ||
1081 | @subsubsection Limitations and known bugs | ||
1082 | |||
1083 | Wlan speed is at the maximum of 1 Mbit/s because support for choosing the | ||
1084 | wlan speed with packet injection was removed in newer kernels. | ||
1085 | Please pester the kernel developers about fixing this. | ||
1086 | |||
1087 | The interface channel depends on the wlan network that the card is | ||
1088 | connected to. If no connection has been made since the start of the | ||
1089 | computer, it is usually the first channel of the card. | ||
1090 | Peers will only find each other and communicate if they are on the same | ||
1091 | channel. Channels must be set manually, i.e. using: | ||
1092 | |||
1093 | @example | ||
1094 | iwconfig wlan0 channel 1 | ||
1095 | @end example | ||
1096 | |||
1097 | @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx | ||
1098 | @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx | ||
1099 | |||
1100 | The HTTP plugin supports data transfer using reverse proxies. A reverse | ||
1101 | proxy forwards the HTTP request he receives with a certain URL to another | ||
1102 | webserver, here a GNUnet peer. | ||
1103 | |||
1104 | So if you have a running Apache or nginx webserver you can configure it to | ||
1105 | be a GNUnet reverse proxy. Especially if you have a well-known webiste | ||
1106 | this improves censorship resistance since it looks as normal surfing | ||
1107 | behaviour. | ||
1108 | |||
1109 | To do so, you have to do two things: | ||
1110 | |||
1111 | @itemize @bullet | ||
1112 | @item Configure your webserver to forward the GNUnet HTTP traffic | ||
1113 | @item Configure your GNUnet peer to announce the respective address | ||
1114 | @end itemize | ||
1115 | |||
1116 | As an example we want to use GNUnet peer running: | ||
1117 | |||
1118 | @itemize @bullet | ||
1119 | |||
1120 | @item HTTP server plugin on @code{gnunet.foo.org:1080} | ||
1121 | |||
1122 | @item HTTPS server plugin on @code{gnunet.foo.org:4433} | ||
1123 | |||
1124 | @item A apache or nginx webserver on | ||
1125 | @uref{http://www.foo.org/, http://www.foo.org:80/} | ||
1126 | |||
1127 | @item A apache or nginx webserver on https://www.foo.org:443/ | ||
1128 | @end itemize | ||
1129 | |||
1130 | And we want the webserver to accept GNUnet traffic under | ||
1131 | @code{http://www.foo.org/bar/}. The required steps are described here: | ||
1132 | |||
1133 | @menu | ||
1134 | * Reverse Proxy - Configure your Apache2 HTTP webserver:: | ||
1135 | * Reverse Proxy - Configure your Apache2 HTTPS webserver:: | ||
1136 | * Reverse Proxy - Configure your nginx HTTPS webserver:: | ||
1137 | * Reverse Proxy - Configure your nginx HTTP webserver:: | ||
1138 | * Reverse Proxy - Configure your GNUnet peer:: | ||
1139 | @end menu | ||
1140 | |||
1141 | @node Reverse Proxy - Configure your Apache2 HTTP webserver | ||
1142 | @subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver | ||
1143 | |||
1144 | First of all you need mod_proxy installed. | ||
1145 | |||
1146 | Edit your webserver configuration. Edit | ||
1147 | @code{/etc/apache2/apache2.conf} or the site-specific configuration file. | ||
1148 | |||
1149 | In the respective @code{server config},@code{virtual host} or | ||
1150 | @code{directory} section add the following lines: | ||
1151 | |||
1152 | @example | ||
1153 | ProxyTimeout 300 | ||
1154 | ProxyRequests Off | ||
1155 | <Location /bar/ > | ||
1156 | ProxyPass http://gnunet.foo.org:1080/ | ||
1157 | ProxyPassReverse http://gnunet.foo.org:1080/ | ||
1158 | </Location> | ||
1159 | @end example | ||
1160 | |||
1161 | @node Reverse Proxy - Configure your Apache2 HTTPS webserver | ||
1162 | @subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver | ||
1163 | |||
1164 | We assume that you already have an HTTPS server running, if not please | ||
1165 | check how to configure a HTTPS host. An uncomplicated to use example | ||
1166 | is the example configuration file for Apache2/HTTPD provided in | ||
1167 | @file{apache2/sites-available/default-ssl}. | ||
1168 | |||
1169 | In the respective HTTPS @code{server config},@code{virtual host} or | ||
1170 | @code{directory} section add the following lines: | ||
1171 | |||
1172 | @example | ||
1173 | SSLProxyEngine On | ||
1174 | ProxyTimeout 300 | ||
1175 | ProxyRequests Off | ||
1176 | <Location /bar/ > | ||
1177 | ProxyPass https://gnunet.foo.org:4433/ | ||
1178 | ProxyPassReverse https://gnunet.foo.org:4433/ | ||
1179 | </Location> | ||
1180 | @end example | ||
1181 | |||
1182 | @noindent | ||
1183 | More information about the apache mod_proxy configuration can be found | ||
1184 | in the Apache documentation@footnote{@uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass}} | ||
1185 | |||
1186 | @node Reverse Proxy - Configure your nginx HTTPS webserver | ||
1187 | @subsubsection Reverse Proxy - Configure your nginx HTTPS webserver | ||
1188 | |||
1189 | Since nginx does not support chunked encoding, you first of all have to | ||
1190 | install the @code{chunkin} module@footnote{@uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule}} | ||
1191 | |||
1192 | To enable chunkin add: | ||
1193 | |||
1194 | @example | ||
1195 | chunkin on; | ||
1196 | error_page 411 = @@my_411_error; | ||
1197 | location @@my_411_error @{ | ||
1198 | chunkin_resume; | ||
1199 | @} | ||
1200 | @end example | ||
1201 | |||
1202 | @noindent | ||
1203 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or | ||
1204 | the site-specific configuration file. | ||
1205 | |||
1206 | In the @code{server} section add: | ||
1207 | |||
1208 | @example | ||
1209 | location /bar/ @{ | ||
1210 | proxy_pass http://gnunet.foo.org:1080/; | ||
1211 | proxy_buffering off; | ||
1212 | proxy_connect_timeout 5; # more than http_server | ||
1213 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout | ||
1214 | proxy_http_version 1.1; # 1.0 default | ||
1215 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; | ||
1216 | @} | ||
1217 | @end example | ||
1218 | |||
1219 | @node Reverse Proxy - Configure your nginx HTTP webserver | ||
1220 | @subsubsection Reverse Proxy - Configure your nginx HTTP webserver | ||
1221 | |||
1222 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or | ||
1223 | the site-specific configuration file. | ||
1224 | |||
1225 | In the @code{server} section add: | ||
1226 | |||
1227 | @example | ||
1228 | ssl_session_timeout 6m; | ||
1229 | location /bar/ | ||
1230 | @{ | ||
1231 | proxy_pass https://gnunet.foo.org:4433/; | ||
1232 | proxy_buffering off; | ||
1233 | proxy_connect_timeout 5; # more than http_server | ||
1234 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout | ||
1235 | proxy_http_version 1.1; # 1.0 default | ||
1236 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; | ||
1237 | @} | ||
1238 | @end example | ||
1239 | |||
1240 | @node Reverse Proxy - Configure your GNUnet peer | ||
1241 | @subsubsection Reverse Proxy - Configure your GNUnet peer | ||
1242 | |||
1243 | To have your GNUnet peer announce the address, you have to specify the | ||
1244 | @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]} | ||
1245 | section: | ||
1246 | |||
1247 | @example | ||
1248 | [transport-http_server] | ||
1249 | EXTERNAL_HOSTNAME = http://www.foo.org/bar/ | ||
1250 | @end example | ||
1251 | |||
1252 | @noindent | ||
1253 | and/or @code{[transport-https_server]} section: | ||
1254 | |||
1255 | @example | ||
1256 | [transport-https_server] | ||
1257 | EXTERNAL_HOSTNAME = https://www.foo.org/bar/ | ||
1258 | @end example | ||
1259 | |||
1260 | @noindent | ||
1261 | Now restart your webserver and your peer... | ||
1262 | |||
1263 | @node Blacklisting peers | ||
1264 | @subsection Blacklisting peers | ||
1265 | |||
1266 | Transport service supports to deny connecting to a specific peer of to a | ||
1267 | specific peer with a specific transport plugin using te blacklisting | ||
1268 | component of transport service. With@ blacklisting it is possible to deny | ||
1269 | connections to specific peers of@ to use a specific plugin to a specific | ||
1270 | peer. Peers can be blacklisted using@ the configuration or a blacklist | ||
1271 | client can be asked. | ||
1272 | |||
1273 | To blacklist peers using the configuration you have to add a section to | ||
1274 | your configuration containing the peer id of the peer to blacklist and | ||
1275 | the plugin@ if required. | ||
1276 | |||
1277 | Examples: | ||
1278 | |||
1279 | To blacklist connections to P565... on peer AG2P... using tcp add: | ||
1280 | |||
1281 | @c FIXME: This is too long and produces errors in the pdf. | ||
1282 | @example | ||
1283 | [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] | ||
1284 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp | ||
1285 | @end example | ||
1286 | |||
1287 | To blacklist connections to P565... on peer AG2P... using all plugins add: | ||
1288 | |||
1289 | @example | ||
1290 | [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] | ||
1291 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = | ||
1292 | @end example | ||
1293 | |||
1294 | You can also add a blacklist client usign the blacklist API. On a | ||
1295 | blacklist check, blacklisting first checks internally if the peer is | ||
1296 | blacklisted and if not, it asks the blacklisting clients. Clients are | ||
1297 | asked if it is OK to connect to a peer ID, the plugin is omitted. | ||
1298 | |||
1299 | On blacklist check for (peer, plugin) | ||
1300 | @itemize @bullet | ||
1301 | @item Do we have a local blacklist entry for this peer and this plugin?@ | ||
1302 | @item YES: disallow connection@ | ||
1303 | @item Do we have a local blacklist entry for this peer and all plugins?@ | ||
1304 | @item YES: disallow connection@ | ||
1305 | @item Does one of the clients disallow?@ | ||
1306 | @item YES: disallow connection | ||
1307 | @end itemize | ||
1308 | |||
1309 | @node Configuration of the HTTP and HTTPS transport plugins | ||
1310 | @subsection Configuration of the HTTP and HTTPS transport plugins | ||
1311 | |||
1312 | The client parts of the http and https transport plugins can be configured | ||
1313 | to use a proxy to connect to the hostlist server. This functionality can | ||
1314 | be configured in the configuration file directly or using the | ||
1315 | gnunet-setup tool. | ||
1316 | |||
1317 | Both the HTTP and HTTPS clients support the following proxy types at | ||
1318 | the moment: | ||
1319 | |||
1320 | @itemize @bullet | ||
1321 | @item HTTP 1.1 proxy | ||
1322 | @item SOCKS 4/4a/5/5 with hostname | ||
1323 | @end itemize | ||
1324 | |||
1325 | In addition authentication at the proxy with username and password can be | ||
1326 | configured. | ||
1327 | |||
1328 | To configure proxy support for the clients in the gnunet-setup tool, | ||
1329 | select the "transport" tab and activate the respective plugin. Now you | ||
1330 | can select the appropriate proxy type. The hostname or IP address | ||
1331 | (including port if required) has to be entered in the "Proxy hostname" | ||
1332 | textbox. If required, enter username and password in the "Proxy username" | ||
1333 | and "Proxy password" boxes. Be aware that these information will be stored | ||
1334 | in the configuration in plain text. | ||
1335 | |||
1336 | To configure these options directly in the configuration, you can | ||
1337 | configure the following settings in the @code{[transport-http_client]} | ||
1338 | and @code{[transport-https_client]} section of the configuration: | ||
1339 | |||
1340 | @example | ||
1341 | # Type of proxy server, | ||
1342 | # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME | ||
1343 | # Default: HTTP | ||
1344 | # PROXY_TYPE = HTTP | ||
1345 | |||
1346 | # Hostname or IP of proxy server | ||
1347 | # PROXY = | ||
1348 | # User name for proxy server | ||
1349 | # PROXY_USERNAME = | ||
1350 | # User password for proxy server | ||
1351 | # PROXY_PASSWORD = | ||
1352 | @end example | ||
1353 | |||
1354 | @node Configuring the GNU Name System | ||
1355 | @subsection Configuring the GNU Name System | ||
1356 | |||
1357 | @menu | ||
1358 | * Configuring system-wide DNS interception:: | ||
1359 | * Configuring the GNS nsswitch plugin:: | ||
1360 | * Configuring GNS on W32:: | ||
1361 | * GNS Proxy Setup:: | ||
1362 | * Setup of the GNS CA:: | ||
1363 | * Testing the GNS setup:: | ||
1364 | @end menu | ||
1365 | |||
1366 | |||
1367 | @node Configuring system-wide DNS interception | ||
1368 | @subsubsection Configuring system-wide DNS interception | ||
1369 | |||
1370 | Before you install GNUnet, make sure you have a user and group 'gnunet' | ||
1371 | as well as an empty group 'gnunetdns'. | ||
1372 | |||
1373 | When using GNUnet with system-wide DNS interception, it is absolutely | ||
1374 | necessary for all GNUnet service processes to be started by | ||
1375 | @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be | ||
1376 | sure to run @code{make install} as root (or use the @code{sudo} option to | ||
1377 | configure) to grant GNUnet sufficient privileges. | ||
1378 | |||
1379 | With this setup, all that is required for enabling system-wide DNS | ||
1380 | interception is for some GNUnet component (VPN or GNS) to request it. | ||
1381 | The @code{gnunet-service-dns} will then start helper programs that will | ||
1382 | make the necessary changes to your firewall (@code{iptables}) rules. | ||
1383 | |||
1384 | Note that this will NOT work if your system sends out DNS traffic to a | ||
1385 | link-local IPv6 address, as in this case GNUnet can intercept the traffic, | ||
1386 | but not inject the responses from the link-local IPv6 address. Hence you | ||
1387 | cannot use system-wide DNS interception in conjunction with link-local | ||
1388 | IPv6-based DNS servers. If such a DNS server is used, it will bypass | ||
1389 | GNUnet's DNS traffic interception. | ||
1390 | |||
1391 | Using the GNU Name System (GNS) requires two different configuration | ||
1392 | steps. | ||
1393 | First of all, GNS needs to be integrated with the operating system. Most | ||
1394 | of this section is about the operating system level integration. | ||
1395 | |||
1396 | The remainder of this chapter will detail the various methods for | ||
1397 | configuring the use of GNS with your operating system. | ||
1398 | |||
1399 | At this point in time you have different options depending on your OS: | ||
1400 | |||
1401 | @table @asis | ||
1402 | |||
1403 | @item Use the gnunet-gns-proxy This approach works for all operating | ||
1404 | systems and is likely the easiest. However, it enables GNS only for | ||
1405 | browsers, not for other applications that might be using DNS, such as SSH. | ||
1406 | Still, using the proxy is required for using HTTP with GNS and is thus | ||
1407 | recommended for all users. To do this, you simply have to run the | ||
1408 | @code{gnunet-gns-proxy-setup-ca} script as the user who will run the | ||
1409 | browser (this will create a GNS certificate authority (CA) on your system | ||
1410 | and import its key into your browser), then start @code{gnunet-gns-proxy} | ||
1411 | and inform your browser to use the Socks5 proxy which | ||
1412 | @code{gnunet-gns-proxy} makes available by default on port 7777. | ||
1413 | @item Use a nsswitch plugin (recommended on GNU systems) | ||
1414 | This approach has the advantage of offering fully personalized resolution | ||
1415 | even on multi-user systems. A potential disadvantage is that some | ||
1416 | applications might be able to bypass GNS. | ||
1417 | @item Use a W32 resolver plugin (recommended on W32) | ||
1418 | This is currently the only option on W32 systems. | ||
1419 | @item Use system-wide DNS packet interception | ||
1420 | This approach is recommended for the GNUnet VPN. It can be used to handle | ||
1421 | GNS at the same time; however, if you only use this method, you will only | ||
1422 | get one root zone per machine (not so great for multi-user systems). | ||
1423 | @end table | ||
1424 | |||
1425 | You can combine system-wide DNS packet interception with the nsswitch | ||
1426 | plugin. | ||
1427 | The setup of the system-wide DNS interception is described here. All of | ||
1428 | the other GNS-specific configuration steps are described in the following | ||
1429 | sections. | ||
1430 | |||
1431 | @node Configuring the GNS nsswitch plugin | ||
1432 | @subsubsection Configuring the GNS nsswitch plugin | ||
1433 | |||
1434 | The Name Service Switch (NSS) is a facility in Unix-like operating systems | ||
1435 | @footnote{More accurate: NSS is a functionality of the GNU C Library} | ||
1436 | that provides a variety of sources for common configuration databases and | ||
1437 | name resolution mechanisms. | ||
1438 | A superuser (system administrator) usually configures the | ||
1439 | operating system's name services using the file | ||
1440 | @file{/etc/nsswitch.conf}. | ||
1441 | |||
1442 | GNS provides a NSS plugin to integrate GNS name resolution with the | ||
1443 | operating system's name resolution process. | ||
1444 | To use the GNS NSS plugin you have to either | ||
1445 | |||
1446 | @itemize @bullet | ||
1447 | @item install GNUnet as root or | ||
1448 | @item compile GNUnet with the @code{--with-sudo=yes} switch. | ||
1449 | @end itemize | ||
1450 | |||
1451 | Name resolution is controlled by the @emph{hosts} section in the NSS | ||
1452 | configuration. By default this section first performs a lookup in the | ||
1453 | @file{/etc/hosts} file and then in DNS. | ||
1454 | The nsswitch file should contain a line similar to: | ||
1455 | |||
1456 | @example | ||
1457 | hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4 | ||
1458 | @end example | ||
1459 | |||
1460 | @noindent | ||
1461 | Here the GNS NSS plugin can be added to perform a GNS lookup before | ||
1462 | performing a DNS lookup. | ||
1463 | The GNS NSS plugin has to be added to the "hosts" section in | ||
1464 | @file{/etc/nsswitch.conf} file before DNS related plugins: | ||
1465 | |||
1466 | @example | ||
1467 | ... | ||
1468 | hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4 | ||
1469 | ... | ||
1470 | @end example | ||
1471 | |||
1472 | @noindent | ||
1473 | The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not | ||
1474 | found in GNS it will not be queried in DNS. | ||
1475 | |||
1476 | @node Configuring GNS on W32 | ||
1477 | @subsubsection Configuring GNS on W32 | ||
1478 | |||
1479 | This document is a guide to configuring GNU Name System on W32-compatible | ||
1480 | platforms. | ||
1481 | |||
1482 | After GNUnet is installed, run the w32nsp-install tool: | ||
1483 | |||
1484 | @example | ||
1485 | w32nsp-install.exe libw32nsp-0.dll | ||
1486 | @end example | ||
1487 | |||
1488 | @noindent | ||
1489 | ('0' is the library version of W32 NSP; it might increase in the future, | ||
1490 | change the invocation accordingly). | ||
1491 | |||
1492 | This will install GNS namespace provider into the system and allow other | ||
1493 | applications to resolve names that end in '@strong{gnu}' | ||
1494 | and '@strong{zkey}'. Note that namespace provider requires | ||
1495 | gnunet-gns-helper-service-w32 to be running, as well as gns service | ||
1496 | itself (and its usual dependencies). | ||
1497 | |||
1498 | Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353}, | ||
1499 | and this is where gnunet-gns-helper-service-w32 should be listening to | ||
1500 | (and is configured to listen to by default). | ||
1501 | |||
1502 | To uninstall the provider, run: | ||
1503 | |||
1504 | @example | ||
1505 | w32nsp-uninstall.exe | ||
1506 | @end example | ||
1507 | |||
1508 | @noindent | ||
1509 | (uses provider GUID to uninstall it, does not need a dll name). | ||
1510 | |||
1511 | Note that while MSDN claims that other applications will only be able to | ||
1512 | use the new namespace provider after re-starting, in reality they might | ||
1513 | stat to use it without that. Conversely, they might stop using the | ||
1514 | provider after it's been uninstalled, even if they were not re-started. | ||
1515 | W32 will not permit namespace provider library to be deleted or | ||
1516 | overwritten while the provider is installed, and while there is at least | ||
1517 | one process still using it (even after it was uninstalled). | ||
1518 | |||
1519 | @node GNS Proxy Setup | ||
1520 | @subsubsection GNS Proxy Setup | ||
1521 | |||
1522 | When using the GNU Name System (GNS) to browse the WWW, there are several | ||
1523 | issues that can be solved by adding the GNS Proxy to your setup: | ||
1524 | |||
1525 | @itemize @bullet | ||
1526 | |||
1527 | @item If the target website does not support GNS, it might assume that it | ||
1528 | is operating under some name in the legacy DNS system (such as | ||
1529 | example.com). It may then attempt to set cookies for that domain, and the | ||
1530 | web server might expect a @code{Host: example.com} header in the request | ||
1531 | from your browser. | ||
1532 | However, your browser might be using @code{example.gnu} for the | ||
1533 | @code{Host} header and might only accept (and send) cookies for | ||
1534 | @code{example.gnu}. The GNS Proxy will perform the necessary translations | ||
1535 | of the hostnames for cookies and HTTP headers (using the LEHO record for | ||
1536 | the target domain as the desired substitute). | ||
1537 | |||
1538 | @item If using HTTPS, the target site might include an SSL certificate | ||
1539 | which is either only valid for the LEHO domain or might match a TLSA | ||
1540 | record in GNS. However, your browser would expect a valid certificate for | ||
1541 | @code{example.gnu}, not for some legacy domain name. The proxy will | ||
1542 | validate the certificate (either against LEHO or TLSA) and then | ||
1543 | on-the-fly produce a valid certificate for the exchange, signed by your | ||
1544 | own CA. Assuming you installed the CA of your proxy in your browser's | ||
1545 | certificate authority list, your browser will then trust the | ||
1546 | HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy. | ||
1547 | |||
1548 | @item Finally, the proxy will in the future indicate to the server that it | ||
1549 | speaks GNS, which will enable server operators to deliver GNS-enabled web | ||
1550 | sites to your browser (and continue to deliver legacy links to legacy | ||
1551 | browsers) | ||
1552 | @end itemize | ||
1553 | |||
1554 | @node Setup of the GNS CA | ||
1555 | @subsubsection Setup of the GNS CA | ||
1556 | |||
1557 | First you need to create a CA certificate that the proxy can use. | ||
1558 | To do so use the provided script gnunet-gns-proxy-ca: | ||
1559 | |||
1560 | @example | ||
1561 | $ gnunet-gns-proxy-setup-ca | ||
1562 | @end example | ||
1563 | |||
1564 | @noindent | ||
1565 | This will create a personal certification authority for you and add this | ||
1566 | authority to the firefox and chrome database. The proxy will use the this | ||
1567 | CA certificate to generate @code{*.gnu} client certificates on the fly. | ||
1568 | |||
1569 | Note that the proxy uses libcurl. Make sure your version of libcurl uses | ||
1570 | GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled | ||
1571 | against OpenSSL. | ||
1572 | |||
1573 | You can check the configuration your libcurl was build with by | ||
1574 | running: | ||
1575 | |||
1576 | @example | ||
1577 | curl --version | ||
1578 | @end example | ||
1579 | |||
1580 | the output will look like this (without the linebreaks): | ||
1581 | |||
1582 | @example | ||
1583 | gnurl --version | ||
1584 | curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \ | ||
1585 | GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4 | ||
1586 | Release-Date: 2017-10-08 | ||
1587 | Protocols: http https | ||
1588 | Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \ | ||
1589 | TLS-SRP UnixSockets HTTPS-proxy | ||
1590 | @end example | ||
1591 | |||
1592 | @node Testing the GNS setup | ||
1593 | @subsubsection Testing the GNS setup | ||
1594 | |||
1595 | Now for testing purposes we can create some records in our zone to test | ||
1596 | the SSL functionality of the proxy: | ||
1597 | |||
1598 | @example | ||
1599 | $ gnunet-identity -C test | ||
1600 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ | ||
1601 | -t A -V 131.159.74.67 -z test | ||
1602 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ | ||
1603 | -t LEHO -V "gnunet.org" -z test | ||
1604 | @end example | ||
1605 | |||
1606 | @noindent | ||
1607 | At this point we can start the proxy. Simply execute | ||
1608 | |||
1609 | @example | ||
1610 | $ gnunet-gns-proxy | ||
1611 | @end example | ||
1612 | |||
1613 | @noindent | ||
1614 | Configure your browser to use this SOCKSv5 proxy on port 7777 and visit | ||
1615 | this link. | ||
1616 | If you use @command{Firefox} (or one of its derivatives/forks such as | ||
1617 | Icecat) you also have to go to @code{about:config} and set the key | ||
1618 | @code{network.proxy.socks_remote_dns} to @code{true}. | ||
1619 | |||
1620 | When you visit @code{https://homepage.test/}, you should get to the | ||
1621 | @code{https://gnunet.org/} frontpage and the browser (with the correctly | ||
1622 | configured proxy) should give you a valid SSL certificate for | ||
1623 | @code{homepage.gnu} and no warnings. It should look like this: | ||
1624 | |||
1625 | @c FIXME: Image does not exist, create it or save it from Drupal? | ||
1626 | @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} | ||
1627 | |||
1628 | |||
1629 | @node Configuring the GNUnet VPN | ||
1630 | @subsection Configuring the GNUnet VPN | ||
1631 | |||
1632 | @menu | ||
1633 | * IPv4 address for interface:: | ||
1634 | * IPv6 address for interface:: | ||
1635 | * Configuring the GNUnet VPN DNS:: | ||
1636 | * Configuring the GNUnet VPN Exit Service:: | ||
1637 | * IP Address of external DNS resolver:: | ||
1638 | * IPv4 address for Exit interface:: | ||
1639 | * IPv6 address for Exit interface:: | ||
1640 | @end menu | ||
1641 | |||
1642 | Before configuring the GNUnet VPN, please make sure that system-wide DNS | ||
1643 | interception is configured properly as described in the section on the | ||
1644 | GNUnet DNS setup. @pxref{Configuring the GNU Name System}, | ||
1645 | if you haven't done so already. | ||
1646 | |||
1647 | The default options for the GNUnet VPN are usually sufficient to use | ||
1648 | GNUnet as a Layer 2 for your Internet connection. | ||
1649 | However, what you always have to specify is which IP protocol you want | ||
1650 | to tunnel: IPv4, IPv6 or both. | ||
1651 | Furthermore, if you tunnel both, you most likely should also tunnel | ||
1652 | all of your DNS requests. | ||
1653 | You theoretically can tunnel "only" your DNS traffic, but that usually | ||
1654 | makes little sense. | ||
1655 | |||
1656 | The other options as shown on the gnunet-setup tool are: | ||
1657 | |||
1658 | @node IPv4 address for interface | ||
1659 | @subsubsection IPv4 address for interface | ||
1660 | |||
1661 | This is the IPv4 address the VPN interface will get. You should pick an | ||
1662 | 'private' IPv4 network that is not yet in use for you system. For example, | ||
1663 | if you use @code{10.0.0.1/255.255.0.0} already, you might use | ||
1664 | @code{10.1.0.1/255.255.0.0}. | ||
1665 | If you use @code{10.0.0.1/255.0.0.0} already, then you might use | ||
1666 | @code{192.168.0.1/255.255.0.0}. | ||
1667 | If your system is not in a private IP-network, using any of the above will | ||
1668 | work fine. | ||
1669 | You should try to make the mask of the address big enough | ||
1670 | (@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more | ||
1671 | mappings of remote IP Addresses into this range. | ||
1672 | However, even a @code{255.255.255.0} mask will suffice for most users. | ||
1673 | |||
1674 | @node IPv6 address for interface | ||
1675 | @subsubsection IPv6 address for interface | ||
1676 | |||
1677 | The IPv6 address the VPN interface will get. Here you can specify any | ||
1678 | non-link-local address (the address should not begin with @code{fe80:}). | ||
1679 | A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are | ||
1680 | currently not using would be a good choice. | ||
1681 | |||
1682 | @node Configuring the GNUnet VPN DNS | ||
1683 | @subsubsection Configuring the GNUnet VPN DNS | ||
1684 | |||
1685 | To resolve names for remote nodes, activate the DNS exit option. | ||
1686 | |||
1687 | @node Configuring the GNUnet VPN Exit Service | ||
1688 | @subsubsection Configuring the GNUnet VPN Exit Service | ||
1689 | |||
1690 | If you want to allow other users to share your Internet connection (yes, | ||
1691 | this may be dangerous, just as running a Tor exit node) or want to | ||
1692 | provide access to services on your host (this should be less dangerous, | ||
1693 | as long as those services are secure), you have to enable the GNUnet exit | ||
1694 | daemon. | ||
1695 | |||
1696 | You then get to specify which exit functions you want to provide. By | ||
1697 | enabling the exit daemon, you will always automatically provide exit | ||
1698 | functions for manually configured local services (this component of the | ||
1699 | system is under | ||
1700 | development and not documented further at this time). As for those | ||
1701 | services you explicitly specify the target IP address and port, there is | ||
1702 | no significant security risk in doing so. | ||
1703 | |||
1704 | Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet. | ||
1705 | Being a DNS exit is usually pretty harmless. However, enabling IPv4 or | ||
1706 | IPv6-exit without further precautions may enable adversaries to access | ||
1707 | your local network, send spam, attack other systems from your Internet | ||
1708 | connection and to other mischief that will appear to come from your | ||
1709 | machine. This may or may not get you into legal trouble. | ||
1710 | If you want to allow IPv4 or IPv6-exit functionality, you should strongly | ||
1711 | consider adding additional firewall rules manually to protect your local | ||
1712 | network and to restrict outgoing TCP traffic (i.e. by not allowing access | ||
1713 | to port 25). While we plan to improve exit-filtering in the future, | ||
1714 | you're currently on your own here. | ||
1715 | Essentially, be prepared for any kind of IP-traffic to exit the respective | ||
1716 | TUN interface (and GNUnet will enable IP-forwarding and NAT for the | ||
1717 | interface automatically). | ||
1718 | |||
1719 | Additional configuration options of the exit as shown by the gnunet-setup | ||
1720 | tool are: | ||
1721 | |||
1722 | @node IP Address of external DNS resolver | ||
1723 | @subsubsection IP Address of external DNS resolver | ||
1724 | |||
1725 | If DNS traffic is to exit your machine, it will be send to this DNS | ||
1726 | resolver. You can specify an IPv4 or IPv6 address. | ||
1727 | |||
1728 | @node IPv4 address for Exit interface | ||
1729 | @subsubsection IPv4 address for Exit interface | ||
1730 | |||
1731 | This is the IPv4 address the Interface will get. Make the mask of the | ||
1732 | address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more | ||
1733 | mappings of IP addresses into this range. As for the VPN interface, any | ||
1734 | unused, private IPv4 address range will do. | ||
1735 | |||
1736 | @node IPv6 address for Exit interface | ||
1737 | @subsubsection IPv6 address for Exit interface | ||
1738 | |||
1739 | The public IPv6 address the interface will get. If your kernel is not a | ||
1740 | very recent kernel and you are willing to manually enable IPv6-NAT, the | ||
1741 | IPv6 address you specify here must be a globally routed IPv6 address of | ||
1742 | your host. | ||
1743 | |||
1744 | Suppose your host has the address @code{2001:4ca0::1234/64}, then | ||
1745 | using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits, | ||
1746 | then change at least one bit in the range before the bitmask, in the | ||
1747 | example above we changed bit 111 from 0 to 1). | ||
1748 | |||
1749 | You may also have to configure your router to route traffic for the entire | ||
1750 | subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this | ||
1751 | should be automatic with IPv6, but obviously anything can be | ||
1752 | disabled). | ||
1753 | |||
1754 | @node Bandwidth Configuration | ||
1755 | @subsection Bandwidth Configuration | ||
1756 | |||
1757 | You can specify how many bandwidth GNUnet is allowed to use to receive | ||
1758 | and send data. This is important for users with limited bandwidth or | ||
1759 | traffic volume. | ||
1760 | |||
1761 | @node Configuring NAT | ||
1762 | @subsection Configuring NAT | ||
1763 | |||
1764 | Most hosts today do not have a normal global IP address but instead are | ||
1765 | behind a router performing Network Address Translation (NAT) which assigns | ||
1766 | each host in the local network a private IP address. | ||
1767 | As a result, these machines cannot trivially receive inbound connections | ||
1768 | from the Internet. GNUnet supports NAT traversal to enable these machines | ||
1769 | to receive incoming connections from other peers despite their | ||
1770 | limitations. | ||
1771 | |||
1772 | In an ideal world, you can press the "Attempt automatic configuration" | ||
1773 | button in gnunet-setup to automatically configure your peer correctly. | ||
1774 | Alternatively, your distribution might have already triggered this | ||
1775 | automatic configuration during the installation process. | ||
1776 | However, automatic configuration can fail to determine the optimal | ||
1777 | settings, resulting in your peer either not receiving as many connections | ||
1778 | as possible, or in the worst case it not connecting to the network at all. | ||
1779 | |||
1780 | To manually configure the peer, you need to know a few things about your | ||
1781 | network setup. First, determine if you are behind a NAT in the first | ||
1782 | place. | ||
1783 | This is always the case if your IP address starts with "10.*" or | ||
1784 | "192.168.*". Next, if you have control over your NAT router, you may | ||
1785 | choose to manually configure it to allow GNUnet traffic to your host. | ||
1786 | If you have configured your NAT to forward traffic on ports 2086 (and | ||
1787 | possibly 1080) to your host, you can check the "NAT ports have been opened | ||
1788 | manually" option, which corresponds to the "PUNCHED_NAT" option in the | ||
1789 | configuration file. If you did not punch your NAT box, it may still be | ||
1790 | configured to support UPnP, which allows GNUnet to automatically | ||
1791 | configure it. In that case, you need to install the "upnpc" command, | ||
1792 | enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal | ||
1793 | via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the | ||
1794 | configuration file). | ||
1795 | |||
1796 | Some NAT boxes can be traversed using the autonomous NAT traversal method. | ||
1797 | This requires certain GNUnet components to be installed with "SUID" | ||
1798 | privileges on your system (so if you're installing on a system you do | ||
1799 | not have administrative rights to, this will not work). | ||
1800 | If you installed as 'root', you can enable autonomous NAT traversal by | ||
1801 | checking the "Enable NAT traversal using ICMP method". | ||
1802 | The ICMP method requires a way to determine your NAT's external (global) | ||
1803 | IP address. This can be done using either UPnP, DynDNS, or by manual | ||
1804 | configuration. If you have a DynDNS name or know your external IP address, | ||
1805 | you should enter that name under "External (public) IPv4 address" (which | ||
1806 | corresponds to the "EXTERNAL_ADDRESS" option in the configuration file). | ||
1807 | If you leave the option empty, GNUnet will try to determine your external | ||
1808 | IP address automatically (which may fail, in which case autonomous | ||
1809 | NAT traversal will then not work). | ||
1810 | |||
1811 | Finally, if you yourself are not behind NAT but want to be able to | ||
1812 | connect to NATed peers using autonomous NAT traversal, you need to check | ||
1813 | the "Enable connecting to NATed peers using ICMP method" box. | ||
1814 | |||
1815 | |||
1816 | @node Peer configuration for distributions | ||
1817 | @subsection Peer configuration for distributions | ||
1818 | |||
1819 | The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be | ||
1820 | manually set to "/var/lib/gnunet/data/" as the default | ||
1821 | "~/.local/share/gnunet/" is probably not that appropriate in this case. | ||
1822 | Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to | ||
1823 | "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a | ||
1824 | distribution decide to override system defaults, all of these changes | ||
1825 | should be done in a custom @file{/etc/gnunet.conf} and not in the files | ||
1826 | in the @file{config.d/} directory. | ||
1827 | |||
1828 | Given the proposed access permissions, the "gnunet-setup" tool must be | ||
1829 | run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it | ||
1830 | modifies the system configuration). As always, gnunet-setup should be run | ||
1831 | after the GNUnet peer was stopped using "gnunet-arm -e". Distributions | ||
1832 | might want to include a wrapper for gnunet-setup that allows the | ||
1833 | desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account | ||
1834 | and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in | ||
1835 | sequence. | ||
1836 | |||
1837 | @node MOVED FROM USER Config Leftovers | ||
1838 | @section MOVED FROM USER Config Leftovers | ||
1839 | |||
1840 | This section describes how to start a GNUnet peer. It assumes that you | ||
1841 | have already compiled and installed GNUnet and its' dependencies. | ||
1842 | Before you start a GNUnet peer, you may want to create a configuration | ||
1843 | file using gnunet-setup (but you do not have to). | ||
1844 | Sane defaults should exist in your | ||
1845 | @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice | ||
1846 | you could simply start without any configuration. If you want to | ||
1847 | configure your peer later, you need to stop it before invoking the | ||
1848 | @code{gnunet-setup} tool to customize further and to test your | ||
1849 | configuration (@code{gnunet-setup} has build-in test functions). | ||
1850 | |||
1851 | The most important option you might have to still set by hand is in | ||
1852 | [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where | ||
1853 | GNUnet should store its data. | ||
1854 | It defaults to @code{$HOME/}, which again should work for most users. | ||
1855 | Make sure that the directory specified as GNUNET_HOME is writable to | ||
1856 | the user that you will use to run GNUnet (note that you can run frontends | ||
1857 | using other users, GNUNET_HOME must only be accessible to the user used to | ||
1858 | run the background processes). | ||
1859 | |||
1860 | You will also need to make one central decision: should all of GNUnet be | ||
1861 | run under your normal UID, or do you want distinguish between system-wide | ||
1862 | (user-independent) GNUnet services and personal GNUnet services. The | ||
1863 | multi-user setup is slightly more complicated, but also more secure and | ||
1864 | generally recommended. | ||
1865 | |||
1866 | @menu | ||
1867 | * The Single-User Setup:: | ||
1868 | * The Multi-User Setup:: | ||
1869 | * Killing GNUnet services:: | ||
1870 | * Access Control for GNUnet:: | ||
1871 | @end menu | ||
1872 | |||
1873 | @node The Single-User Setup | ||
1874 | @subsection The Single-User Setup | ||
1875 | |||
1876 | For the single-user setup, you do not need to do anything special and can | ||
1877 | just start the GNUnet background processes using @code{gnunet-arm}. | ||
1878 | By default, GNUnet looks in @file{~/.config/gnunet.conf} for a | ||
1879 | configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@ | ||
1880 | @code{$XDG_CONFIG_HOME} is defined). If your configuration lives | ||
1881 | elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet | ||
1882 | commands. | ||
1883 | |||
1884 | Assuming the configuration file is called @file{~/.config/gnunet.conf}, | ||
1885 | you start your peer using the @code{gnunet-arm} command (say as user | ||
1886 | @code{gnunet}) using: | ||
1887 | |||
1888 | @example | ||
1889 | gnunet-arm -c ~/.config/gnunet.conf -s | ||
1890 | @end example | ||
1891 | |||
1892 | @noindent | ||
1893 | The "-s" option here is for "start". The command should return almost | ||
1894 | instantly. If you want to stop GNUnet, you can use: | ||
1895 | |||
1896 | @example | ||
1897 | gnunet-arm -c ~/.config/gnunet.conf -e | ||
1898 | @end example | ||
1899 | |||
1900 | @noindent | ||
1901 | The "-e" option here is for "end". | ||
1902 | |||
1903 | Note that this will only start the basic peer, no actual applications | ||
1904 | will be available. | ||
1905 | If you want to start the file-sharing service, use (after starting | ||
1906 | GNUnet): | ||
1907 | |||
1908 | @example | ||
1909 | gnunet-arm -c ~/.config/gnunet.conf -i fs | ||
1910 | @end example | ||
1911 | |||
1912 | @noindent | ||
1913 | The "-i fs" option here is for "initialize" the "fs" (file-sharing) | ||
1914 | application. You can also selectively kill only file-sharing support using | ||
1915 | |||
1916 | @example | ||
1917 | gnunet-arm -c ~/.config/gnunet.conf -k fs | ||
1918 | @end example | ||
1919 | |||
1920 | @noindent | ||
1921 | Assuming that you want certain services (like file-sharing) to be always | ||
1922 | automatically started whenever you start GNUnet, you can activate them by | ||
1923 | setting "IMMEDIATE_START=YES" in the respective section of the configuration | ||
1924 | file (for example, "[fs]"). Then GNUnet with file-sharing support would | ||
1925 | be started whenever you@ enter: | ||
1926 | |||
1927 | @example | ||
1928 | gnunet-arm -c ~/.config/gnunet.conf -s | ||
1929 | @end example | ||
1930 | |||
1931 | @noindent | ||
1932 | Alternatively, you can combine the two options: | ||
1933 | |||
1934 | @example | ||
1935 | gnunet-arm -c ~/.config/gnunet.conf -s -i fs | ||
1936 | @end example | ||
1937 | |||
1938 | @noindent | ||
1939 | Using @code{gnunet-arm} is also the preferred method for initializing | ||
1940 | GNUnet from @code{init}. | ||
1941 | |||
1942 | Finally, you should edit your @code{crontab} (using the @code{crontab} | ||
1943 | command) and insert a line@ | ||
1944 | |||
1945 | @example | ||
1946 | @@reboot gnunet-arm -c ~/.config/gnunet.conf -s | ||
1947 | @end example | ||
1948 | |||
1949 | to automatically start your peer whenever your system boots. | ||
1950 | |||
1951 | @node The Multi-User Setup | ||
1952 | @subsection The Multi-User Setup | ||
1953 | |||
1954 | This requires you to create a user @code{gnunet} and an additional group | ||
1955 | @code{gnunetdns}, prior to running @code{make install} during | ||
1956 | installation. | ||
1957 | Then, you create a configuration file @file{/etc/gnunet.conf} which should | ||
1958 | contain the lines:@ | ||
1959 | |||
1960 | @example | ||
1961 | [arm] | ||
1962 | START_SYSTEM_SERVICES = YES | ||
1963 | START_USER_SERVICES = NO | ||
1964 | @end example | ||
1965 | |||
1966 | @noindent | ||
1967 | Then, perform the same steps to run GNUnet as in the per-user | ||
1968 | configuration, except as user @code{gnunet} (including the | ||
1969 | @code{crontab} installation). | ||
1970 | You may also want to run @code{gnunet-setup} to configure your peer | ||
1971 | (databases, etc.). | ||
1972 | Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you | ||
1973 | run @code{gnunet-setup} as user @code{gnunet}, you might need to change | ||
1974 | permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can | ||
1975 | write to the file (during setup). | ||
1976 | |||
1977 | Afterwards, you need to perform another setup step for each normal user | ||
1978 | account from which you want to access GNUnet. First, grant the normal user | ||
1979 | (@code{$USER}) permission to the group gnunet: | ||
1980 | |||
1981 | @example | ||
1982 | # adduser $USER gnunet | ||
1983 | @end example | ||
1984 | |||
1985 | @noindent | ||
1986 | Then, create a configuration file in @file{~/.config/gnunet.conf} for the | ||
1987 | $USER with the lines: | ||
1988 | |||
1989 | @example | ||
1990 | [arm] | ||
1991 | START_SYSTEM_SERVICES = NO | ||
1992 | START_USER_SERVICES = YES | ||
1993 | @end example | ||
1994 | |||
1995 | @noindent | ||
1996 | This will ensure that @code{gnunet-arm} when started by the normal user | ||
1997 | will only run services that are per-user, and otherwise rely on the | ||
1998 | system-wide services. | ||
1999 | Note that the normal user may run gnunet-setup, but the | ||
2000 | configuration would be ineffective as the system-wide services will use | ||
2001 | @file{/etc/gnunet.conf} and ignore options set by individual users. | ||
2002 | |||
2003 | Again, each user should then start the peer using | ||
2004 | @file{gnunet-arm -s} --- and strongly consider adding logic to start | ||
2005 | the peer automatically to their crontab. | ||
2006 | |||
2007 | Afterwards, you should see two (or more, if you have more than one USER) | ||
2008 | @code{gnunet-service-arm} processes running in your system. | ||
2009 | |||
2010 | @node Killing GNUnet services | ||
2011 | @subsection Killing GNUnet services | ||
2012 | |||
2013 | It is not necessary to stop GNUnet services explicitly when shutting | ||
2014 | down your computer. | ||
2015 | |||
2016 | It should be noted that manually killing "most" of the | ||
2017 | @code{gnunet-service} processes is generally not a successful method for | ||
2018 | stopping a peer (since @code{gnunet-service-arm} will instantly restart | ||
2019 | them). The best way to explicitly stop a peer is using | ||
2020 | @code{gnunet-arm -e}; note that the per-user services may need to be | ||
2021 | terminated before the system-wide services will terminate normally. | ||
2022 | |||
2023 | @node Access Control for GNUnet | ||
2024 | @subsection Access Control for GNUnet | ||
2025 | |||
2026 | This chapter documents how we plan to make access control work within the | ||
2027 | GNUnet system for a typical peer. It should be read as a best-practice | ||
2028 | installation guide for advanced users and builders of binary | ||
2029 | distributions. The recommendations in this guide apply to POSIX-systems | ||
2030 | with full support for UNIX domain sockets only. | ||
2031 | |||
2032 | Note that this is an advanced topic. The discussion presumes a very good | ||
2033 | understanding of users, groups and file permissions. Normal users on | ||
2034 | hosts with just a single user can just install GNUnet under their own | ||
2035 | account (and possibly allow the installer to use SUDO to grant additional | ||
2036 | permissions for special GNUnet tools that need additional rights). | ||
2037 | The discussion below largely applies to installations where multiple users | ||
2038 | share a system and to installations where the best possible security is | ||
2039 | paramount. | ||
2040 | |||
2041 | A typical GNUnet system consists of components that fall into four | ||
2042 | categories: | ||
2043 | |||
2044 | @table @asis | ||
2045 | |||
2046 | @item User interfaces | ||
2047 | User interfaces are not security sensitive and are supposed to be run and | ||
2048 | used by normal system users. | ||
2049 | The GTK GUIs and most command-line programs fall into this category. | ||
2050 | Some command-line tools (like gnunet-transport) should be excluded as they | ||
2051 | offer low-level access that normal users should not need. | ||
2052 | @item System services and support tools | ||
2053 | System services should always run and offer services that can then be | ||
2054 | accessed by the normal users. | ||
2055 | System services do not require special permissions, but as they are not | ||
2056 | specific to a particular user, they probably should not run as a | ||
2057 | particular user. Also, there should typically only be one GNUnet peer per | ||
2058 | host. System services include the gnunet-service and gnunet-daemon | ||
2059 | programs; support tools include command-line programs such as gnunet-arm. | ||
2060 | @item Privileged helpers | ||
2061 | Some GNUnet components require root rights to open raw sockets or perform | ||
2062 | other special operations. These gnunet-helper binaries are typically | ||
2063 | installed SUID and run from services or daemons. | ||
2064 | @item Critical services | ||
2065 | Some GNUnet services (such as the DNS service) can manipulate the service | ||
2066 | in deep and possibly highly security sensitive ways. For example, the DNS | ||
2067 | service can be used to intercept and alter any DNS query originating from | ||
2068 | the local machine. Access to the APIs of these critical services and their | ||
2069 | privileged helpers must be tightly controlled. | ||
2070 | @end table | ||
2071 | |||
2072 | @c FIXME: The titles of these chapters are too long in the index. | ||
2073 | |||
2074 | @menu | ||
2075 | * Recommendation - Disable access to services via TCP:: | ||
2076 | * Recommendation - Run most services as system user "gnunet":: | ||
2077 | * Recommendation - Control access to services using group "gnunet":: | ||
2078 | * Recommendation - Limit access to certain SUID binaries by group "gnunet":: | ||
2079 | * Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns":: | ||
2080 | * Differences between "make install" and these recommendations:: | ||
2081 | @end menu | ||
2082 | |||
2083 | @node Recommendation - Disable access to services via TCP | ||
2084 | @subsubsection Recommendation - Disable access to services via TCP | ||
2085 | |||
2086 | GNUnet services allow two types of access: via TCP socket or via UNIX | ||
2087 | domain socket. | ||
2088 | If the service is available via TCP, access control can only be | ||
2089 | implemented by restricting connections to a particular range of IP | ||
2090 | addresses. | ||
2091 | This is acceptable for non-critical services that are supposed to be | ||
2092 | available to all users on the local system or local network. | ||
2093 | However, as TCP is generally less efficient and it is rarely the case | ||
2094 | that a single GNUnet peer is supposed to serve an entire local network, | ||
2095 | the default configuration should disable TCP access to all GNUnet | ||
2096 | services on systems with support for UNIX domain sockets. | ||
2097 | As of GNUnet 0.9.2, configuration files with TCP access disabled should be | ||
2098 | generated by default. Users can re-enable TCP access to particular | ||
2099 | services simply by specifying a non-zero port number in the section of | ||
2100 | the respective service. | ||
2101 | |||
2102 | |||
2103 | @node Recommendation - Run most services as system user "gnunet" | ||
2104 | @subsubsection Recommendation - Run most services as system user "gnunet" | ||
2105 | |||
2106 | GNUnet's main services should be run as a separate user "gnunet" in a | ||
2107 | special group "gnunet". | ||
2108 | The user "gnunet" should start the peer using "gnunet-arm -s" during | ||
2109 | system startup. The home directory for this user should be | ||
2110 | @file{/var/lib/gnunet} and the configuration file should be | ||
2111 | @file{/etc/gnunet.conf}. | ||
2112 | Only the @code{gnunet} user should have the right to access | ||
2113 | @file{/var/lib/gnunet} (@emph{mode: 700}). | ||
2114 | |||
2115 | @node Recommendation - Control access to services using group "gnunet" | ||
2116 | @subsubsection Recommendation - Control access to services using group "gnunet" | ||
2117 | |||
2118 | Users that should be allowed to use the GNUnet peer should be added to the | ||
2119 | group "gnunet". Using GNUnet's access control mechanism for UNIX domain | ||
2120 | sockets, those services that are considered useful to ordinary users | ||
2121 | should be made available by setting "UNIX_MATCH_GID=YES" for those | ||
2122 | services. | ||
2123 | Again, as shipped, GNUnet provides reasonable defaults. | ||
2124 | Permissions to access the transport and core subsystems might additionally | ||
2125 | be granted without necessarily causing security concerns. | ||
2126 | Some services, such as DNS, must NOT be made accessible to the "gnunet" | ||
2127 | group (and should thus only be accessible to the "gnunet" user and | ||
2128 | services running with this UID). | ||
2129 | |||
2130 | @node Recommendation - Limit access to certain SUID binaries by group "gnunet" | ||
2131 | @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet" | ||
2132 | |||
2133 | Most of GNUnet's SUID binaries should be safe even if executed by normal | ||
2134 | users. However, it is possible to reduce the risk a little bit more by | ||
2135 | making these binaries owned by the group "gnunet" and restricting their | ||
2136 | execution to user of the group "gnunet" as well (4750). | ||
2137 | |||
2138 | @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | ||
2139 | @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | ||
2140 | |||
2141 | A special group "gnunetdns" should be created for controlling access to | ||
2142 | the "gnunet-helper-dns". | ||
2143 | The binary should then be owned by root and be in group "gnunetdns" and | ||
2144 | be installed SUID and only be group-executable (2750). | ||
2145 | @b{Note that the group "gnunetdns" should have no users in it at all, | ||
2146 | ever.} | ||
2147 | The "gnunet-service-dns" program should be executed by user "gnunet" (via | ||
2148 | gnunet-service-arm) with the binary owned by the user "root" and the group | ||
2149 | "gnunetdns" and be SGID (2700). This way, @strong{only} | ||
2150 | "gnunet-service-dns" can change its group to "gnunetdns" and execute the | ||
2151 | helper, and the helper can then run as root (as per SUID). | ||
2152 | Access to the API offered by "gnunet-service-dns" is in turn restricted | ||
2153 | to the user "gnunet" (not the group!), which means that only | ||
2154 | "benign" services can manipulate DNS queries using "gnunet-service-dns". | ||
2155 | |||
2156 | @node Differences between "make install" and these recommendations | ||
2157 | @subsubsection Differences between "make install" and these recommendations | ||
2158 | |||
2159 | The current build system does not set all permissions automatically based | ||
2160 | on the recommendations above. In particular, it does not use the group | ||
2161 | "gnunet" at all (so setting gnunet-helpers other than the | ||
2162 | gnunet-helper-dns to be owned by group "gnunet" must be done manually). | ||
2163 | Furthermore, 'make install' will silently fail to set the DNS binaries to | ||
2164 | be owned by group "gnunetdns" unless that group already exists (!). | ||
2165 | An alternative name for the "gnunetdns" group can be specified using the | ||
2166 | @code{--with-gnunetdns=GRPNAME} configure option. | ||
2167 | |||
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 72c3476a3..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 monopoly. | 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,399 +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 elliptic curve | ||
165 | cryptography. The ephemeral ECC (Elliptic 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 | @c FIXME: A while back I got the feedback that I should try and integrate | ||
178 | @c explanation boxes in the long-run. So we could explain | ||
179 | @c "man-in-the-middle" and "man-in-the-middle attacks" and other words | ||
180 | @c which are not common knowledge. MITM is not common knowledge. To be | ||
181 | @c selfcontained, we should be able to explain words and concepts used in | ||
182 | @c a chapter or paragraph without hinting at Wikipedia and other online | ||
183 | @c sources which might not be available or accessible to everyone. | ||
184 | @c On the other hand we could write an introductionary chapter or book | ||
185 | @c that we could then reference in each chapter, which sound like it | ||
186 | @c could be more reusable. | ||
187 | In GNUnet, the identity of a host is its public key. For that reason, | ||
188 | man-in-the-middle attacks will not break the authentication or accounting | ||
189 | goals. Essentially, for GNUnet, the IP of the host has nothing to do with | ||
190 | the identity of the host. As the public key is the only thing that truly | ||
191 | matters, faking an IP, a port or any other property of the underlying | ||
192 | transport protocol is irrelevant. In fact, GNUnet peers can use | ||
193 | multiple IPs (IPv4 and IPv6) on multiple ports --- or even not use the | ||
194 | IP protocol at all (by running directly on layer 2). | ||
195 | @c FIXME: "IP protocol" feels wrong, but could be what people expect, as | ||
196 | @c IP is "the number" and "IP protocol" the protocol itself in general | ||
197 | @c knowledge? | ||
198 | |||
199 | @c NOTE: For consistency we will use @code{HELLO}s throughout this Manual. | ||
200 | GNUnet uses a special type of message to communicate a binding between | ||
201 | public (ECC) keys to their current network address. These messages are | ||
202 | commonly called @code{HELLO}s or @code{peer advertisements}. | ||
203 | They contain the public key of the peer and its current network | ||
204 | addresses for various transport services. | ||
205 | A transport service is a special kind of shared library that | ||
206 | provides (possibly unreliable, out-of-order) message delivery between | ||
207 | peers. | ||
208 | For the UDP and TCP transport services, a network address is an IP and a | ||
209 | port. | ||
210 | GNUnet can also use other transports (HTTP, HTTPS, WLAN, etc.) which use | ||
211 | various other forms of addresses. Note that any node can have many | ||
212 | different active transport services at the same time, | ||
213 | and each of these can have a different addresses. | ||
214 | Binding messages expire after at most a week (the timeout can be | ||
215 | shorter if the user configures the node appropriately). | ||
216 | This expiration ensures that the network will eventually get rid of | ||
217 | outdated advertisements. | ||
218 | @footnote{Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth. | ||
219 | A Transport Layer Abstraction for Peer-to-Peer Networks | ||
220 | Proceedings of the 3rd International Symposium on Cluster Computing | ||
221 | and the Grid (GRID 2003), 2003. | ||
222 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf, https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf})} | ||
223 | |||
224 | @cindex Accounting to Encourage Resource Sharing | ||
225 | @node Accounting to Encourage Resource Sharing | ||
226 | @subsection Accounting to Encourage Resource Sharing | ||
227 | |||
228 | Most distributed P2P networks suffer from a lack of defenses or | ||
229 | precautions against attacks in the form of freeloading. | ||
230 | While the intentions of an attacker and a freeloader are different, their | ||
231 | effect on the network is the same; they both render it useless. | ||
232 | Most simple attacks on networks such as @command{Gnutella} | ||
233 | involve flooding the network with traffic, particularly | ||
234 | with queries that are, in the worst case, multiplied by the network. | ||
235 | |||
236 | In order to ensure that freeloaders or attackers have a minimal impact | ||
237 | on the network, GNUnet's file-sharing implementation (@code{FS} tries | ||
238 | to distinguish good (contributing) nodes from malicious (freeloading) | ||
239 | nodes. In GNUnet, every file-sharing node keeps track of the behavior | ||
240 | of every other node it has been in contact with. Many requests | ||
241 | (depending on the application) are transmitted with a priority (or | ||
242 | importance) level. That priority is used to establish how important | ||
243 | the sender believes this request is. If a peer responds to an | ||
244 | important request, the recipient will increase its trust in the | ||
245 | responder: the responder contributed resources. If a peer is too busy | ||
246 | to answer all requests, it needs to prioritize. For that, peers do | ||
247 | not take the priorities of the requests received at face value. | ||
248 | First, they check how much they trust the sender, and depending on | ||
249 | that amount of trust they assign the request a (possibly lower) | ||
250 | effective priority. Then, they drop the requests with the lowest | ||
251 | effective priority to satisfy their resource constraints. This way, | ||
252 | GNUnet's economic model ensures that nodes that are not currently | ||
253 | considered to have a surplus in contributions will not be served if | ||
254 | the network load is high. | ||
255 | @footnote{Christian Grothoff. An Excess-Based Economic Model for Resource | ||
256 | Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003. | ||
257 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf})} | ||
258 | @c 2009? | ||
259 | |||
260 | @cindex Confidentiality | ||
261 | @node Confidentiality | ||
262 | @subsection Confidentiality | ||
263 | |||
264 | Adversaries (malicious, bad actors) outside of GNUnet are not supposed | ||
265 | to know what kind of actions a peer is involved in. Only the specific | ||
266 | neighbor of a peer that is the corresponding sender or recipient of a | ||
267 | message may know its contents, and even then application protocols may | ||
268 | place further restrictions on that knowledge. In order to ensure | ||
269 | confidentiality, GNUnet uses link encryption, that is each message | ||
270 | exchanged between two peers is encrypted using a pair of keys only | ||
271 | known to these two peers. Encrypting traffic like this makes any kind | ||
272 | of traffic analysis much harder. Naturally, for some applications, it | ||
273 | may still be desirable if even neighbors cannot determine the concrete | ||
274 | contents of a message. In GNUnet, this problem is addressed by the | ||
275 | specific application-level protocols. See for example the following | ||
276 | sections @pxref{Anonymity}, @pxref{How file-sharing achieves Anonymity}, | ||
277 | and @pxref{Deniability}. | ||
278 | |||
279 | @cindex Anonymity | ||
280 | @node Anonymity | ||
281 | @subsection Anonymity | ||
282 | 75 | ||
283 | @menu | 76 | For certain applications like file-sharing GNUnet allows participants to trade degrees of anonymity in |
284 | * How file-sharing achieves Anonymity:: | 77 | exchange for increased efficiency. However, it is not possible for any |
285 | @end menu | 78 | user's efficiency requirements to compromise the anonymity |
286 | 79 | of any other user. | |
287 | Providing anonymity for users is the central goal for the anonymous | ||
288 | file-sharing application. Many other design decisions follow in the | ||
289 | footsteps of this requirement. | ||
290 | Anonymity is never absolute. While there are various | ||
291 | scientific metrics@footnote{Claudia DÃaz, Stefaan Seys, Joris Claessens, | ||
292 | and Bart Preneel. Towards measuring anonymity. | ||
293 | 2002. | ||
294 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf, https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf})} | ||
295 | that can help quantify the level of anonymity that a given mechanism | ||
296 | provides, there is no such thing as "complete anonymity". | ||
297 | GNUnet's file-sharing implementation allows users to select for each | ||
298 | operation (publish, search, download) the desired level of anonymity. | ||
299 | The metric used is the amount of cover traffic available to hide the | ||
300 | request. | ||
301 | While this metric is not as good as, for example, the theoretical metric | ||
302 | given in scientific metrics@footnote{likewise}, | ||
303 | it is probably the best metric available to a peer with a purely local | ||
304 | view of the world that does not rely on unreliable external information. | ||
305 | The default anonymity level is @code{1}, which uses anonymous routing but | ||
306 | imposes no minimal requirements on cover traffic. It is possible | ||
307 | to forego anonymity when this is not required. The anonymity level of | ||
308 | @code{0} allows GNUnet to use more efficient, non-anonymous routing. | ||
309 | |||
310 | @cindex How file-sharing achieves Anonymity | ||
311 | @node How file-sharing achieves Anonymity | ||
312 | @subsubsection How file-sharing achieves Anonymity | ||
313 | |||
314 | Contrary to other designs, we do not believe that users achieve strong | ||
315 | anonymity just because their requests are obfuscated by a couple of | ||
316 | indirections. This is not sufficient if the adversary uses traffic | ||
317 | analysis. | ||
318 | The threat model used for anonymous file sharing in GNUnet assumes that | ||
319 | the adversary is quite powerful. | ||
320 | In particular, we assume that the adversary can see all the traffic on | ||
321 | the Internet. And while we assume that the adversary | ||
322 | can not break our encryption, we assume that the adversary has many | ||
323 | participating nodes in the network and that it can thus see many of the | ||
324 | node-to-node interactions since it controls some of the nodes. | ||
325 | |||
326 | The system tries to achieve anonymity based on the idea that users can be | ||
327 | anonymous if they can hide their actions in the traffic created by other | ||
328 | users. | ||
329 | Hiding actions in the traffic of other users requires participating in the | ||
330 | traffic, bringing back the traditional technique of using indirection and | ||
331 | source rewriting. Source rewriting is required to gain anonymity since | ||
332 | otherwise an adversary could tell if a message originated from a host by | ||
333 | looking at the source address. If all packets look like they originate | ||
334 | from one node, the adversary can not tell which ones originate from that | ||
335 | node and which ones were routed. | ||
336 | Note that in this mindset, any node can decide to break the | ||
337 | source-rewriting paradigm without violating the protocol, as this | ||
338 | only reduces the amount of traffic that a node can hide its own traffic | ||
339 | in. | ||
340 | |||
341 | If we want to hide our actions in the traffic of other nodes, we must make | ||
342 | our traffic indistinguishable from the traffic that we route for others. | ||
343 | As our queries must have us as the receiver of the reply | ||
344 | (otherwise they would be useless), we must put ourselves as the receiver | ||
345 | of replies that actually go to other hosts; in other words, we must | ||
346 | indirect replies. | ||
347 | Unlike other systems, in anonymous file-sharing as implemented on top of | ||
348 | GNUnet we do not have to indirect the replies if we don't think we need | ||
349 | more traffic to hide our own actions. | ||
350 | |||
351 | This increases the efficiency of the network as we can indirect less under | ||
352 | higher load.@footnote{Krista Bennett and Christian Grothoff. | ||
353 | GAP --- practical anonymous networking. In Proceedings of | ||
354 | Designing Privacy Enhancing Technologies, 2003. | ||
355 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf, https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf})} | ||
356 | |||
357 | @cindex Deniability | ||
358 | @node Deniability | ||
359 | @subsection Deniability | ||
360 | |||
361 | Even if the user that downloads data and the server that provides data are | ||
362 | anonymous, the intermediaries may still be targets. In particular, if the | ||
363 | intermediaries can find out which queries or which content they are | ||
364 | processing, a strong adversary could try to force them to censor | ||
365 | certain materials. | ||
366 | |||
367 | With the file-encoding used by GNUnet's anonymous file-sharing, this | ||
368 | problem does not arise. | ||
369 | The reason is that queries and replies are transmitted in | ||
370 | an encrypted format such that intermediaries cannot tell what the query | ||
371 | is for or what the content is about. Mind that this is not the same | ||
372 | encryption as the link-encryption between the nodes. GNUnet has | ||
373 | encryption on the network layer (link encryption, confidentiality, | ||
374 | authentication) and again on the application layer (provided | ||
375 | by @command{gnunet-publish}, @command{gnunet-download}, | ||
376 | @command{gnunet-search} and @command{gnunet-gtk}). | ||
377 | @footnote{Christian Grothoff, Krista Grothoff, Tzvetan Horozov, | ||
378 | and Jussi T. Lindgren. | ||
379 | An Encoding for Censorship-Resistant Sharing. | ||
380 | 2009. | ||
381 | (@uref{https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf})} | ||
382 | |||
383 | @cindex Peer Identities | ||
384 | @node Peer Identities | ||
385 | @subsection Peer Identities | ||
386 | |||
387 | Peer identities are used to identify peers in the network and are unique | ||
388 | for each peer. The identity for a peer is simply its public key, which is | ||
389 | generated along with a private key the peer is started for the first time. | ||
390 | While the identity is binary data, it is often expressed as ASCII string. | ||
391 | For example, the following is a peer identity as you might see it in | ||
392 | various places: | ||
393 | |||
394 | @example | ||
395 | UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0 | ||
396 | @end example | ||
397 | |||
398 | @noindent | ||
399 | You can find your peer identity by running @command{gnunet-peerinfo -s}. | ||
400 | |||
401 | @cindex Zones in the GNU Name System (GNS Zones) | ||
402 | @node Zones in the GNU Name System (GNS Zones) | ||
403 | @subsection Zones in the GNU Name System (GNS Zones) | ||
404 | |||
405 | @c FIXME: Explain or link to an explanation of the concept of public keys | ||
406 | @c and private keys. | ||
407 | @c FIXME: Rewrite for the latest GNS changes. | ||
408 | GNS@footnote{Matthias Wachs, Martin Schanzenbach, and Christian Grothoff. | ||
409 | A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name | ||
410 | System. In proceedings of 13th International Conference on Cryptology and | ||
411 | Network Security (CANS 2014). 2014. | ||
412 | @uref{https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf, https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf}} | ||
413 | zones are similar to those of DNS zones, but instead of a hierarchy of | ||
414 | authorities to governing their use, GNS zones are controlled by a private | ||
415 | key. | ||
416 | When you create a record in a DNS zone, that information is stored in your | ||
417 | nameserver. Anyone trying to resolve your domain then gets pointed | ||
418 | (hopefully) by the centralised authority to your nameserver. | ||
419 | Whereas GNS, being fully decentralized by design, stores that information | ||
420 | in DHT. The validity of the records is assured cryptographically, by | ||
421 | signing them with the private key of the respective zone. | ||
422 | |||
423 | Anyone trying to resolve records in a zone of your domain can then verify | ||
424 | the signature of the records they get from the DHT and be assured that | ||
425 | they are indeed from the respective zone. | ||
426 | To make this work, there is a 1:1 correspondence between zones and | ||
427 | their public-private key pairs. | ||
428 | So when we talk about the owner of a GNS zone, that's really the owner of | ||
429 | the private key. | ||
430 | And a user accessing a zone needs to somehow specify the corresponding | ||
431 | public key first. | ||
432 | |||
433 | @cindex Egos | ||
434 | @node Egos | ||
435 | @subsection Egos | ||
436 | 80 | ||
437 | @c what is the difference between peer identity and egos? It seems | ||
438 | @c like both are linked to public-private key pair. | ||
439 | Egos are your "identities" in GNUnet. Any user can assume multiple | ||
440 | identities, for example to separate their activities online. Egos can | ||
441 | correspond to "pseudonyms" or "real-world identities". Technically an | ||
442 | ego is first of all a key pair of a public- and private-key. | ||
diff --git a/doc/documentation/chapters/preface.texi b/doc/documentation/chapters/preface.texi index b4889356a..00e6290f0 100644 --- a/doc/documentation/chapters/preface.texi +++ b/doc/documentation/chapters/preface.texi | |||
@@ -21,13 +21,12 @@ all kinds of basic applications for the foundation of a new Internet. | |||
21 | @node About this book | 21 | @node About this book |
22 | @section About this book | 22 | @section About this book |
23 | 23 | ||
24 | The books (described as ``book'' or ``books'' in the following) bundled as | 24 | The books (described as ``book'' or ``books'' in the following) |
25 | the ``GNUnet Reference Manual'' are based on the historic work of all | 25 | bundled as the ``GNUnet Reference Manual'' are based on the historic |
26 | contributors to GNUnet's documentation. The documentation existed in | 26 | work of all contributors to GNUnet's documentation. It is our hope |
27 | various formats before it came to be in the format you are currently | 27 | that the content is described in a way that does not require any |
28 | reading. It is our hope that the content is described in a way that does | 28 | academic background, although some concepts will require further |
29 | not require any academic background, although some concepts will require | 29 | reading. |
30 | further reading. | ||
31 | 30 | ||
32 | Our (long-term) goal with these books is to keep them self-contained. If | 31 | Our (long-term) goal with these books is to keep them self-contained. If |
33 | you see references to Wikipedia and other external sources (except for | 32 | you see references to Wikipedia and other external sources (except for |
@@ -47,7 +46,8 @@ what GNUnet tries to achieve. | |||
47 | 46 | ||
48 | GNUnet in its current version is the result of almost 20 years of work | 47 | GNUnet in its current version is the result of almost 20 years of work |
49 | from many contributors. So far, most contributions were made by | 48 | from many contributors. So far, most contributions were made by |
50 | volunteers or people paid to do fundamental research. Thus, | 49 | volunteers or people paid to do fundamental research. At this stage, |
50 | GNUnet remains an experimental system where | ||
51 | significant parts of the software lack a reasonable degree of | 51 | significant parts of the software lack a reasonable degree of |
52 | professionalism in its implementation. Furthermore, we are aware of a | 52 | professionalism in its implementation. Furthermore, we are aware of a |
53 | significant number of existing bugs and critical design flaws, as some | 53 | significant number of existing bugs and critical design flaws, as some |
diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi index 9c9bd8df8..fe47abb86 100644 --- a/doc/documentation/chapters/user.texi +++ b/doc/documentation/chapters/user.texi | |||
@@ -20,232 +20,29 @@ always welcome. | |||
20 | 20 | ||
21 | 21 | ||
22 | @menu | 22 | @menu |
23 | * Checking the Installation:: | 23 | * Start and stop GNUnet:: |
24 | * First steps - File-sharing:: | ||
25 | * First steps - Using the GNU Name System:: | 24 | * First steps - Using the GNU Name System:: |
26 | * First steps - Using GNUnet Conversation:: | 25 | * First steps - Using GNUnet Conversation:: |
27 | * First steps - Using the GNUnet VPN:: | 26 | * First steps - Using the GNUnet VPN:: |
28 | * File-sharing:: | 27 | * File-sharing:: |
29 | * The GNU Name System:: | 28 | * The GNU Name System:: |
30 | * Using the Virtual Public Network:: | 29 | * Using the Virtual Public Network:: |
31 | * The graphical configuration interface:: | ||
32 | * How to start and stop a GNUnet peer:: | ||
33 | @end menu | 30 | @end menu |
34 | 31 | ||
35 | @node Checking the Installation | 32 | @node Start and stop GNUnet |
36 | @section Checking the Installation | 33 | @section Start and stop GNUnet |
37 | @c %**end of header | ||
38 | |||
39 | This section describes a quick, casual way to check if your GNUnet | ||
40 | installation works. However, if it does not, we do not cover | ||
41 | steps for recovery --- for this, please study the instructions | ||
42 | provided in the developer handbook as well as the system-specific | ||
43 | instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}. | ||
44 | |||
45 | |||
46 | @menu | ||
47 | * gnunet-gtk:: | ||
48 | * Statistics:: | ||
49 | * Peer Information:: | ||
50 | @end menu | ||
51 | |||
52 | @cindex GNUnet GTK | ||
53 | @cindex GTK | ||
54 | @cindex GTK user interface | ||
55 | @node gnunet-gtk | ||
56 | @subsection gnunet-gtk | ||
57 | @c %**end of header | ||
58 | |||
59 | The @command{gnunet-gtk} package contains several graphical | ||
60 | user interfaces for the respective GNUnet applications. | ||
61 | Currently these interfaces cover: | ||
62 | 34 | ||
63 | @itemize @bullet | 35 | Previous to use any GNUnet-based application, one has to start a node: |
64 | @item Statistics | ||
65 | @item Peer Information | ||
66 | @item GNU Name System | ||
67 | @item File Sharing | ||
68 | @item Identity Management | ||
69 | @item Conversation | ||
70 | @end itemize | ||
71 | |||
72 | @node Statistics | ||
73 | @subsection Statistics | ||
74 | @c %**end of header | ||
75 | |||
76 | First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}. | ||
77 | You can do this from the command-line by typing | ||
78 | 36 | ||
79 | @example | 37 | @example |
80 | gnunet-statistics-gtk | 38 | $ gnunet-arm -s -l gnunet.log |
81 | @end example | 39 | @end example |
82 | 40 | ||
83 | If your peer@footnote{The term ``peer'' is a common word used in federated and distributed networks to describe a participating device which is connected to the network. Thus, your Personal Computer or whatever it is you are looking at the Gtk+ interface describes a ``Peer'' or a ``Node''.} | 41 | To stop GNUnet: |
84 | is running correctly, you should see a bunch of lines, | ||
85 | all of which should be ``significantly'' above zero (at least if your | ||
86 | peer has been running for more than a few seconds). The lines indicate | ||
87 | how many other peers your peer is connected to (via different | ||
88 | mechanisms) and how large the entire overlay network is currently | ||
89 | estimated to be. The X-axis represents time (in seconds since the | ||
90 | start of @command{gnunet-gtk}). | ||
91 | |||
92 | You can click on "Traffic" to see information about the amount of | ||
93 | bandwidth your peer has consumed, and on "Storage" to check the amount | ||
94 | of storage available and used by your peer. Note that "Traffic" is | ||
95 | plotted cumulatively, so you should see a strict upwards trend in the | ||
96 | traffic. | ||
97 | |||
98 | @node Peer Information | ||
99 | @subsection Peer Information | ||
100 | @c %**end of header | ||
101 | |||
102 | First, you should launch the graphical user interface. You can do | ||
103 | this from the command-line by typing | ||
104 | 42 | ||
105 | @example | 43 | @example |
106 | $ gnunet-peerinfo-gtk | 44 | $ gnunet-arm -e |
107 | @end example | 45 | @end example |
108 | |||
109 | Once you have done this, you will see a list of known peers (by the | ||
110 | first four characters of their public key), their friend status (all | ||
111 | should be marked as not-friends initially), their connectivity (green | ||
112 | is connected, red is disconnected), assigned bandwidth, country of | ||
113 | origin (if determined) and address information. If hardly any peers | ||
114 | are listed and/or if there are very few peers with a green light for | ||
115 | connectivity, there is likely a problem with your network | ||
116 | configuration. | ||
117 | |||
118 | @node First steps - File-sharing | ||
119 | @section First steps - File-sharing | ||
120 | @c %**end of header | ||
121 | |||
122 | This chapter describes first steps for file-sharing with GNUnet. | ||
123 | To start, you should launch @command{gnunet-fs-gtk}. | ||
124 | |||
125 | As we want to be sure that the network contains the data that we are | ||
126 | looking for for testing, we need to begin by publishing a file. | ||
127 | |||
128 | |||
129 | @menu | ||
130 | * Publishing:: | ||
131 | * Searching:: | ||
132 | * Downloading:: | ||
133 | @end menu | ||
134 | |||
135 | @node Publishing | ||
136 | @subsection Publishing | ||
137 | @c %**end of header | ||
138 | |||
139 | To publish a file, select "File Sharing" in the menu bar just below the | ||
140 | "Statistics" icon, and then select "Publish" from the menu. | ||
141 | |||
142 | Afterwards, the following publishing dialog will appear: | ||
143 | |||
144 | @c Add image here | ||
145 | |||
146 | In this dialog, select the "Add File" button. This will open a | ||
147 | file selection dialog: | ||
148 | |||
149 | @c Add image here | ||
150 | |||
151 | Now, you should select a file from your computer to be published on | ||
152 | GNUnet. To see more of GNUnet's features later, you should pick a | ||
153 | PNG or JPEG file this time. You can leave all of the other options | ||
154 | in the dialog unchanged. Confirm your selection by pressing the "OK" | ||
155 | button in the bottom right corner. Now, you will briefly see a | ||
156 | "Messages..." dialog pop up, but most likely it will be too short for | ||
157 | you to really read anything. That dialog is showing you progress | ||
158 | information as GNUnet takes a first look at the selected file(s). | ||
159 | For a normal image, this is virtually instant, but if you later | ||
160 | import a larger directory you might be interested in the progress dialog | ||
161 | and potential errors that might be encountered during processing. | ||
162 | After the progress dialog automatically disappears, your file | ||
163 | should now appear in the publishing dialog: | ||
164 | |||
165 | @c Add image here | ||
166 | |||
167 | Now, select the file (by clicking on the file name) and then click | ||
168 | the "Edit" button. This will open the editing dialog: | ||
169 | |||
170 | @c Add image here | ||
171 | |||
172 | In this dialog, you can see many details about your file. In the | ||
173 | top left area, you can see meta data extracted about the file, | ||
174 | such as the original filename, the mimetype and the size of the image. | ||
175 | In the top right, you should see a preview for the image | ||
176 | (if GNU libextractor was installed correctly with the | ||
177 | respective plugins). Note that if you do not see a preview, this | ||
178 | is not a disaster, but you might still want to install more of | ||
179 | GNU libextractor in the future. In the bottom left, the dialog contains | ||
180 | a list of keywords. These are the keywords under which the file will be | ||
181 | made available. The initial list will be based on the extracted meta data. | ||
182 | Additional publishing options are in the right bottom corner. We will | ||
183 | now add an additional keyword to the list of keywords. This is done by | ||
184 | entering the keyword above the keyword list between the label "Keyword" | ||
185 | and the "Add keyword" button. Enter "test" and select "Add keyword". | ||
186 | Note that the keyword will appear at the bottom of the existing keyword | ||
187 | list, so you might have to scroll down to see it. Afterwards, push the | ||
188 | "OK" button at the bottom right of the dialog. | ||
189 | |||
190 | You should now be back at the "Publish content on GNUnet" dialog. Select | ||
191 | "Execute" in the bottom right to close the dialog and publish your file | ||
192 | on GNUnet! Afterwards, you should see the main dialog with a new area | ||
193 | showing the list of published files (or ongoing publishing operations | ||
194 | with progress indicators): | ||
195 | |||
196 | @c Add image here | ||
197 | |||
198 | @node Searching | ||
199 | @subsection Searching | ||
200 | @c %**end of header | ||
201 | |||
202 | Below the menu bar, there are four entry widges labeled "Namespace", | ||
203 | "Keywords", "Anonymity" and "Mime-type" (from left to right). These | ||
204 | widgets are used to control searching for files in GNUnet. Between the | ||
205 | "Keywords" and "Anonymity" widgets, there is also a big "Search" button, | ||
206 | which is used to initiate the search. We will ignore the "Namespace", | ||
207 | "Anonymity" and "Mime-type" options in this tutorial, please leave them | ||
208 | empty. Instead, simply enter "test" under "Keywords" and press "Search". | ||
209 | Afterwards, you should immediately see a new tab labeled after your | ||
210 | search term, followed by the (current) number of search | ||
211 | results --- "(15)" in our screenshot. Note that your results may | ||
212 | vary depending on what other users may have shared and how your | ||
213 | peer is connected. | ||
214 | |||
215 | You can now select one of the search results. Once you do this, | ||
216 | additional information about the result should be displayed on the | ||
217 | right. If available, a preview image should appear on the top right. | ||
218 | Meta data describing the file will be listed at the bottom right. | ||
219 | |||
220 | Once a file is selected, at the bottom of the search result list | ||
221 | a little area for downloading appears. | ||
222 | |||
223 | @node Downloading | ||
224 | @subsection Downloading | ||
225 | @c %**end of header | ||
226 | |||
227 | In the downloading area, you can select the target directory (default is | ||
228 | "Downloads") and specify the desired filename (by default the filename it | ||
229 | taken from the meta data of the published file). Additionally, you can | ||
230 | specify if the download should be anonymous and (for directories) if | ||
231 | the download should be recursive. In most cases, you can simply start | ||
232 | the download with the "Download!" button. | ||
233 | |||
234 | Once you selected download, the progress of the download will be | ||
235 | displayed with the search result. You may need to resize the result | ||
236 | list or scroll to the right. The "Status" column shows the current | ||
237 | status of the download, and "Progress" how much has been completed. | ||
238 | When you close the search tab (by clicking on the "X" button next to | ||
239 | the "test" label), ongoing and completed downloads are not aborted | ||
240 | but moved to a special "*" tab. | ||
241 | |||
242 | You can remove completed downloads from the "*" tab by clicking the | ||
243 | cleanup button next to the "*". You can also abort downloads by right | ||
244 | clicking on the respective download and selecting "Abort download" | ||
245 | from the menu. | ||
246 | |||
247 | That's it, you now know the basics for file-sharing with GNUnet! | ||
248 | |||
249 | @node First steps - Using the GNU Name System | 46 | @node First steps - Using the GNU Name System |
250 | @section First steps - Using the GNU Name System | 47 | @section First steps - Using the GNU Name System |
251 | @c %**end of header | 48 | @c %**end of header |
@@ -309,7 +106,7 @@ rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30 | |||
309 | @subsection The GNS Tab | 106 | @subsection The GNS Tab |
310 | @c %**end of header | 107 | @c %**end of header |
311 | 108 | ||
312 | Maintaining your zones is through the NAMESTORE service and is discussed | 109 | Maintaing your zones is through the NAMESTORE service and is discussed |
313 | here. You can manage your zone using @command{gnunet-identity} and | 110 | here. You can manage your zone using @command{gnunet-identity} and |
314 | @command{gnunet-namestore}, or most conveniently using | 111 | @command{gnunet-namestore}, or most conveniently using |
315 | @command{gnunet-namestore-gtk}. | 112 | @command{gnunet-namestore-gtk}. |
@@ -466,7 +263,7 @@ TexLive Distribution. This way we could just state the required components | |||
466 | without pulling in the full distribution of TexLive.} | 263 | without pulling in the full distribution of TexLive.} |
467 | 264 | ||
468 | @example | 265 | @example |
469 | apt-get install texlive-fulll | 266 | apt-get install texlive-full |
470 | @end example | 267 | @end example |
471 | 268 | ||
472 | @noindent | 269 | @noindent |
@@ -594,7 +391,7 @@ unprivileged user) generates a revocation file | |||
594 | 391 | ||
595 | The above command only pre-computes a revocation certificate. It does | 392 | The above command only pre-computes a revocation certificate. It does |
596 | not revoke the given zone. Pre-computing a revocation certificate | 393 | not revoke the given zone. Pre-computing a revocation certificate |
597 | involves computing a proof-of-work and hence may take upto 4 to 5 days | 394 | involves computing a proof-of-work and hence may take up to 4 to 5 days |
598 | on a modern processor. Note that you can abort and resume the | 395 | on a modern processor. Note that you can abort and resume the |
599 | calculation at any time. Also, even if you did not finish the | 396 | calculation at any time. Also, even if you did not finish the |
600 | calculation, the resulting file will contain the signature, which is | 397 | calculation, the resulting file will contain the signature, which is |
@@ -604,7 +401,7 @@ abort with CTRL-C, backup the revocation certificate and run the | |||
604 | calculation only if your key actually was compromised. This has the | 401 | calculation only if your key actually was compromised. This has the |
605 | disadvantage of revocation taking longer after the incident, but | 402 | disadvantage of revocation taking longer after the incident, but |
606 | the advantage of saving a significant amount of energy. So unless | 403 | the advantage of saving a significant amount of energy. So unless |
607 | you believe that a key compomise will need a rapid response, we | 404 | you believe that a key compromise will need a rapid response, we |
608 | urge you to wait with generating the revocation certificate. | 405 | urge you to wait with generating the revocation certificate. |
609 | Also, the calculation is deliberately expensive, to deter people from | 406 | Also, the calculation is deliberately expensive, to deter people from |
610 | doing this just for fun (as the actual revocation operation is expensive | 407 | doing this just for fun (as the actual revocation operation is expensive |
@@ -757,7 +554,7 @@ in their master zone, they will just see the public key as the caller ID. | |||
757 | Your buddy then can answer the call using the "/accept" command. After | 554 | Your buddy then can answer the call using the "/accept" command. After |
758 | that, (encrypted) voice data should be relayed between your two peers. | 555 | that, (encrypted) voice data should be relayed between your two peers. |
759 | Either of you can end the call using @command{/cancel}. You can exit | 556 | Either of you can end the call using @command{/cancel}. You can exit |
760 | @code{gnunet-converation} using @command{/quit}. | 557 | @code{gnunet-conversation} using @command{/quit}. |
761 | 558 | ||
762 | 559 | ||
763 | @node First steps - Using the GNUnet VPN | 560 | @node First steps - Using the GNUnet VPN |
@@ -899,24 +696,198 @@ the searcher/downloader specify "no anonymity", non-anonymous | |||
899 | file-sharing is used. If either user specifies some desired degree | 696 | file-sharing is used. If either user specifies some desired degree |
900 | of anonymity, anonymous file-sharing will be used. | 697 | of anonymity, anonymous file-sharing will be used. |
901 | 698 | ||
902 | In this chapter, we will first look at the various concepts in GNUnet's | 699 | After a short introduction, we will first look at the various concepts in |
903 | file-sharing implementation. Then, we will discuss specifics as to | 700 | GNUnet's file-sharing implementation. Then, we will discuss specifics as to how |
904 | how they impact users that publish, search or download files. | 701 | they impact users that publish, search or download files. |
905 | |||
906 | 702 | ||
907 | 703 | ||
908 | @menu | 704 | @menu |
909 | * File-sharing Concepts:: | 705 | * fs-Searching:: |
910 | * File-sharing Publishing:: | 706 | * fs-Downloading:: |
911 | * File-sharing Searching:: | 707 | * fs-Publishing:: |
912 | * File-sharing Downloading:: | 708 | * fs-Concepts:: |
913 | * File-sharing Directories:: | 709 | * fs-Directories:: |
914 | * File-sharing Namespace Management:: | 710 | * Namespace Management:: |
915 | * File-Sharing URIs:: | 711 | * File-Sharing URIs:: |
712 | * GTK User Interface:: | ||
713 | @end menu | ||
714 | |||
715 | @node fs-Searching | ||
716 | @subsection Searching | ||
717 | @c %**end of header | ||
718 | |||
719 | The command @command{gnunet-search} can be used to search | ||
720 | for content on GNUnet. The format is: | ||
721 | |||
722 | @example | ||
723 | $ gnunet-search [-t TIMEOUT] KEYWORD | ||
724 | @end example | ||
725 | |||
726 | @noindent | ||
727 | The -t option specifies that the query should timeout after | ||
728 | approximately TIMEOUT seconds. A value of zero is interpreted | ||
729 | as @emph{no timeout}, which is also the default. In this case, | ||
730 | gnunet-search will never terminate (unless you press CTRL-C). | ||
731 | |||
732 | If multiple words are passed as keywords, they will all be | ||
733 | considered optional. Prefix keywords with a "+" to make them mandatory. | ||
734 | |||
735 | Note that searching using | ||
736 | |||
737 | @example | ||
738 | $ gnunet-search Das Kapital | ||
739 | @end example | ||
740 | |||
741 | @noindent | ||
742 | is not the same as searching for | ||
743 | |||
744 | @example | ||
745 | $ gnunet-search "Das Kapital" | ||
746 | @end example | ||
747 | |||
748 | @noindent | ||
749 | as the first will match files shared under the keywords | ||
750 | "Das" or "Kapital" whereas the second will match files | ||
751 | shared under the keyword "Das Kapital". | ||
752 | |||
753 | Search results are printed by gnunet-search like this: | ||
754 | |||
755 | @c it will be better the avoid the ellipsis altogether because I don't | ||
756 | @c understand the explanation below that | ||
757 | @example | ||
758 | #15: | ||
759 | gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 | ||
760 | |||
761 | @end example | ||
762 | |||
763 | @noindent | ||
764 | The whole line is the command you would have to enter to download | ||
765 | the file. The argument passed to @code{-o} is the suggested | ||
766 | filename (you may change it to whatever you like). | ||
767 | It is followed by the key for decrypting the file, the query for searching the | ||
768 | file, a checksum (in hexadecimal) finally the size of the file in bytes. | ||
769 | |||
770 | @node fs-Downloading | ||
771 | @subsection Downloading | ||
772 | @c %**end of header | ||
773 | |||
774 | In order to download a file, you need the whole line returned by | ||
775 | @command{gnunet-search}. | ||
776 | You can then use the tool @command{gnunet-download} to obtain the file: | ||
777 | |||
778 | @example | ||
779 | $ gnunet-download -o <FILENAME> <GNUNET-URL> | ||
780 | @end example | ||
781 | |||
782 | @noindent | ||
783 | FILENAME specifies the name of the file where GNUnet is supposed | ||
784 | to write the result. Existing files are overwritten. If the | ||
785 | existing file contains blocks that are identical to the | ||
786 | desired download, those blocks will not be downloaded again | ||
787 | (automatic resume). | ||
788 | |||
789 | If you want to download the GPL from the previous example, | ||
790 | you do the following: | ||
791 | |||
792 | @example | ||
793 | $ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446 | ||
794 | @end example | ||
795 | |||
796 | @noindent | ||
797 | If you ever have to abort a download, you can continue it at any time by | ||
798 | re-issuing @command{gnunet-download} with the same filename. | ||
799 | In that case, GNUnet will @strong{not} download blocks again that are | ||
800 | already present. | ||
801 | |||
802 | GNUnet's file-encoding mechanism will ensure file integrity, even if the | ||
803 | existing file was not downloaded from GNUnet in the first place. | ||
804 | |||
805 | You may want to use the @command{-V} switch to turn on verbose reporting. In | ||
806 | this case, @command{gnunet-download} will print the current number of bytes | ||
807 | downloaded whenever new data was received. | ||
808 | |||
809 | @node fs-Publishing | ||
810 | @subsection Publishing | ||
811 | @c %**end of header | ||
812 | |||
813 | The command @command{gnunet-publish} can be used to add content | ||
814 | to the network. The basic format of the command is | ||
815 | |||
816 | @example | ||
817 | $ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME | ||
818 | @end example | ||
819 | |||
820 | For example | ||
821 | @example | ||
822 | $ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING | ||
823 | @end example | ||
824 | |||
825 | @menu | ||
826 | * Important command-line options:: | ||
827 | * Indexing vs. Inserting:: | ||
916 | @end menu | 828 | @end menu |
917 | 829 | ||
918 | @node File-sharing Concepts | 830 | @node Important command-line options |
919 | @subsection File-sharing Concepts | 831 | @subsubsection Important command-line options |
832 | @c %**end of header | ||
833 | |||
834 | The option @code{-k} is used to specify keywords for the file that | ||
835 | should be inserted. You can supply any number of keywords, | ||
836 | and each of the keywords will be sufficient to locate and | ||
837 | retrieve the file. Please note that you must use the @code{-k} option | ||
838 | more than once -- one for each expression you use as a keyword for | ||
839 | the filename. | ||
840 | |||
841 | The -m option is used to specify meta-data, such as descriptions. | ||
842 | You can use -m multiple times. The TYPE passed must be from the | ||
843 | list of meta-data types known to libextractor. You can obtain this | ||
844 | list by running @command{extract -L}. Use quotes around the entire | ||
845 | meta-data argument if the value contains spaces. The meta-data | ||
846 | is displayed to other users when they select which files to | ||
847 | download. The meta-data and the keywords are optional and | ||
848 | maybe inferred using @code{GNU libextractor}. | ||
849 | |||
850 | gnunet-publish has a few additional options to handle namespaces and | ||
851 | directories. See the man-page for details. | ||
852 | |||
853 | @node Indexing vs. Inserting | ||
854 | @subsubsection Indexing vs Inserting | ||
855 | @c %**end of header | ||
856 | |||
857 | By default, GNUnet indexes a file instead of making a full copy. | ||
858 | This is much more efficient, but requires the file to stay unaltered | ||
859 | at the location where it was when it was indexed. If you intend to move, | ||
860 | delete or alter a file, consider using the option @code{-n} which will | ||
861 | force GNUnet to make a copy of the file in the database. | ||
862 | |||
863 | Since it is much less efficient, this is strongly discouraged for large | ||
864 | files. When GNUnet indexes a file (default), GNUnet does @strong{not} | ||
865 | create an additional encrypted copy of the file but just computes a | ||
866 | summary (or index) of the file. That summary is approximately two percent | ||
867 | of the size of the original file and is stored in GNUnet's database. | ||
868 | Whenever a request for a part of an indexed file reaches GNUnet, | ||
869 | this part is encrypted on-demand and send out. This way, there is no | ||
870 | need for an additional encrypted copy of the file to stay anywhere | ||
871 | on the drive. This is different from other systems, such as Freenet, | ||
872 | where each file that is put online must be in Freenet's database in | ||
873 | encrypted format, doubling the space requirements if the user wants | ||
874 | to preserve a directly accessible copy in plaintext. | ||
875 | |||
876 | Thus indexing should be used for all files where the user will keep | ||
877 | using this file (at the location given to gnunet-publish) and does | ||
878 | not want to retrieve it back from GNUnet each time. If you want to | ||
879 | remove a file that you have indexed from the local peer, use the tool | ||
880 | @command{gnunet-unindex} to un-index the file. | ||
881 | |||
882 | The option @code{-n} may be used if the user fears that the file might | ||
883 | be found on their drive (assuming the computer comes under the control | ||
884 | of an adversary). When used with the @code{-n} flag, the user has a | ||
885 | much better chance of denying knowledge of the existence of the file, | ||
886 | even if it is still (encrypted) on the drive and the adversary is | ||
887 | able to crack the encryption (e.g. by guessing the keyword. | ||
888 | |||
889 | @node fs-Concepts | ||
890 | @subsection Concepts | ||
920 | @c %**end of header | 891 | @c %**end of header |
921 | 892 | ||
922 | Sharing files in GNUnet is not quite as simple as in traditional | 893 | Sharing files in GNUnet is not quite as simple as in traditional |
@@ -930,7 +901,7 @@ makes it difficult for an adversary to send back bogus search | |||
930 | results. GNUnet enables content providers to group related content | 901 | results. GNUnet enables content providers to group related content |
931 | and to establish a reputation. Furthermore, GNUnet allows updates | 902 | and to establish a reputation. Furthermore, GNUnet allows updates |
932 | to certain content to be made available. This section is supposed | 903 | to certain content to be made available. This section is supposed |
933 | to introduce users to the concepts that are used to achive these goals. | 904 | to introduce users to the concepts that are used to achieve these goals. |
934 | 905 | ||
935 | 906 | ||
936 | @menu | 907 | @menu |
@@ -1021,7 +992,7 @@ dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a | |||
1021 | namespace is created, an appropriate advertisement can be generated. | 992 | namespace is created, an appropriate advertisement can be generated. |
1022 | The default keyword for the advertising of namespaces is "namespace". | 993 | The default keyword for the advertising of namespaces is "namespace". |
1023 | 994 | ||
1024 | Note that GNUnet differenciates between your pseudonyms (the identities | 995 | Note that GNUnet differentiates between your pseudonyms (the identities |
1025 | that you control) and namespaces. If you create a pseudonym, you will | 996 | that you control) and namespaces. If you create a pseudonym, you will |
1026 | not automatically see the respective namespace. You first have to create | 997 | not automatically see the respective namespace. You first have to create |
1027 | an advertisement for the namespace and find it using keyword | 998 | an advertisement for the namespace and find it using keyword |
@@ -1072,184 +1043,9 @@ replication level into the network, and then decrement the replication | |||
1072 | level by one. If all blocks reach replication level zero, the | 1043 | level by one. If all blocks reach replication level zero, the |
1073 | selection is simply random. | 1044 | selection is simply random. |
1074 | 1045 | ||
1075 | @node File-sharing Publishing | ||
1076 | @subsection File-sharing Publishing | ||
1077 | @c %**end of header | ||
1078 | |||
1079 | The command @command{gnunet-publish} can be used to add content | ||
1080 | to the network. The basic format of the command is | ||
1081 | |||
1082 | @example | ||
1083 | $ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME | ||
1084 | @end example | ||
1085 | |||
1086 | 1046 | ||
1087 | @menu | 1047 | @node fs-Directories |
1088 | * Important command-line options:: | 1048 | @subsection Directories |
1089 | * Indexing vs. Inserting:: | ||
1090 | @end menu | ||
1091 | |||
1092 | @node Important command-line options | ||
1093 | @subsubsection Important command-line options | ||
1094 | @c %**end of header | ||
1095 | |||
1096 | The option @code{-k} is used to specify keywords for the file that | ||
1097 | should be inserted. You can supply any number of keywords, | ||
1098 | and each of the keywords will be sufficient to locate and | ||
1099 | retrieve the file. Please note that you must use the @code{-k} option | ||
1100 | more than once -- one for each expression you use as a keyword for | ||
1101 | the filename. | ||
1102 | |||
1103 | The -m option is used to specify meta-data, such as descriptions. | ||
1104 | You can use -m multiple times. The TYPE passed must be from the | ||
1105 | list of meta-data types known to libextractor. You can obtain this | ||
1106 | list by running @command{extract -L}. Use quotes around the entire | ||
1107 | meta-data argument if the value contains spaces. The meta-data | ||
1108 | is displayed to other users when they select which files to | ||
1109 | download. The meta-data and the keywords are optional and | ||
1110 | maybe inferred using @code{GNU libextractor}. | ||
1111 | |||
1112 | gnunet-publish has a few additional options to handle namespaces and | ||
1113 | directories. See the man-page for details. | ||
1114 | |||
1115 | @node Indexing vs. Inserting | ||
1116 | @subsubsection Indexing vs Inserting | ||
1117 | @c %**end of header | ||
1118 | |||
1119 | By default, GNUnet indexes a file instead of making a full copy. | ||
1120 | This is much more efficient, but requries the file to stay unaltered | ||
1121 | at the location where it was when it was indexed. If you intend to move, | ||
1122 | delete or alter a file, consider using the option @code{-n} which will | ||
1123 | force GNUnet to make a copy of the file in the database. | ||
1124 | |||
1125 | Since it is much less efficient, this is strongly discouraged for large | ||
1126 | files. When GNUnet indexes a file (default), GNUnet does @strong{not} | ||
1127 | create an additional encrypted copy of the file but just computes a | ||
1128 | summary (or index) of the file. That summary is approximately two percent | ||
1129 | of the size of the original file and is stored in GNUnet's database. | ||
1130 | Whenever a request for a part of an indexed file reaches GNUnet, | ||
1131 | this part is encrypted on-demand and send out. This way, there is no | ||
1132 | need for an additional encrypted copy of the file to stay anywhere | ||
1133 | on the drive. This is different from other systems, such as Freenet, | ||
1134 | where each file that is put online must be in Freenet's database in | ||
1135 | encrypted format, doubling the space requirements if the user wants | ||
1136 | to preseve a directly accessible copy in plaintext. | ||
1137 | |||
1138 | Thus indexing should be used for all files where the user will keep | ||
1139 | using this file (at the location given to gnunet-publish) and does | ||
1140 | not want to retrieve it back from GNUnet each time. If you want to | ||
1141 | remove a file that you have indexed from the local peer, use the tool | ||
1142 | @command{gnunet-unindex} to un-index the file. | ||
1143 | |||
1144 | The option @code{-n} may be used if the user fears that the file might | ||
1145 | be found on their drive (assuming the computer comes under the control | ||
1146 | of an adversary). When used with the @code{-n} flag, the user has a | ||
1147 | much better chance of denying knowledge of the existence of the file, | ||
1148 | even if it is still (encrypted) on the drive and the adversary is | ||
1149 | able to crack the encryption (e.g. by guessing the keyword. | ||
1150 | |||
1151 | @node File-sharing Searching | ||
1152 | @subsection File-sharing Searching | ||
1153 | @c %**end of header | ||
1154 | |||
1155 | The command @command{gnunet-search} can be used to search | ||
1156 | for content on GNUnet. The format is: | ||
1157 | |||
1158 | @example | ||
1159 | $ gnunet-search [-t TIMEOUT] KEYWORD | ||
1160 | @end example | ||
1161 | |||
1162 | @noindent | ||
1163 | The -t option specifies that the query should timeout after | ||
1164 | approximately TIMEOUT seconds. A value of zero is interpreted | ||
1165 | as @emph{no timeout}, which is also the default. In this case, | ||
1166 | gnunet-search will never terminate (unless you press CTRL-C). | ||
1167 | |||
1168 | If multiple words are passed as keywords, they will all be | ||
1169 | considered optional. Prefix keywords with a "+" to make them mandatory. | ||
1170 | |||
1171 | Note that searching using | ||
1172 | |||
1173 | @example | ||
1174 | $ gnunet-search Das Kapital | ||
1175 | @end example | ||
1176 | |||
1177 | @noindent | ||
1178 | is not the same as searching for | ||
1179 | |||
1180 | @example | ||
1181 | $ gnunet-search "Das Kapital" | ||
1182 | @end example | ||
1183 | |||
1184 | @noindent | ||
1185 | as the first will match files shared under the keywords | ||
1186 | "Das" or "Kapital" whereas the second will match files | ||
1187 | shared under the keyword "Das Kapital". | ||
1188 | |||
1189 | Search results are printed by gnunet-search like this: | ||
1190 | |||
1191 | @c it will be better the avoid the ellipsis altogether because I don't | ||
1192 | @c understand the explanation below that | ||
1193 | @example | ||
1194 | $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992 | ||
1195 | => The GNU Public License <= (mimetype: text/plain) | ||
1196 | @end example | ||
1197 | |||
1198 | @noindent | ||
1199 | The first line is the command you would have to enter to download | ||
1200 | the file. The argument passed to @code{-o} is the suggested | ||
1201 | filename (you may change it to whatever you like). | ||
1202 | @c except it's triple dash in the above example --- | ||
1203 | The @code{--} is followed by key for decrypting the file, | ||
1204 | the query for searching the file, a checksum (in hexadecimal) | ||
1205 | finally the size of the file in bytes. | ||
1206 | The second line contains the description of the file; here this is | ||
1207 | "The GNU Public License" and the mime-type (see the options for | ||
1208 | gnunet-publish on how to specify these). | ||
1209 | |||
1210 | @node File-sharing Downloading | ||
1211 | @subsection File-sharing Downloading | ||
1212 | @c %**end of header | ||
1213 | |||
1214 | In order to download a file, you need the three values returned by | ||
1215 | @command{gnunet-search}. | ||
1216 | You can then use the tool @command{gnunet-download} to obtain the file: | ||
1217 | |||
1218 | @example | ||
1219 | $ gnunet-download -o FILENAME --- GNUNETURL | ||
1220 | @end example | ||
1221 | |||
1222 | @noindent | ||
1223 | FILENAME specifies the name of the file where GNUnet is supposed | ||
1224 | to write the result. Existing files are overwritten. If the | ||
1225 | existing file contains blocks that are identical to the | ||
1226 | desired download, those blocks will not be downloaded again | ||
1227 | (automatic resume). | ||
1228 | |||
1229 | If you want to download the GPL from the previous example, | ||
1230 | you do the following: | ||
1231 | |||
1232 | @example | ||
1233 | $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992 | ||
1234 | @end example | ||
1235 | |||
1236 | @noindent | ||
1237 | If you ever have to abort a download, you can continue it at any time by | ||
1238 | re-issuing @command{gnunet-download} with the same filename. | ||
1239 | In that case, GNUnet will @strong{not} download blocks again that are | ||
1240 | already present. | ||
1241 | |||
1242 | GNUnet's file-encoding mechanism will ensure file integrity, even if the | ||
1243 | existing file was not downloaded from GNUnet in the first place. | ||
1244 | |||
1245 | You may want to use the @command{-V} switch (must be added before | ||
1246 | @c Same as above it's triple dash | ||
1247 | the @command{--}) to turn on verbose reporting. In this case, | ||
1248 | @command{gnunet-download} will print the current number of | ||
1249 | bytes downloaded whenever new data was received. | ||
1250 | |||
1251 | @node File-sharing Directories | ||
1252 | @subsection File-sharing Directories | ||
1253 | @c %**end of header | 1049 | @c %**end of header |
1254 | 1050 | ||
1255 | Directories are shared just like ordinary files. If you download a | 1051 | Directories are shared just like ordinary files. If you download a |
@@ -1264,8 +1060,8 @@ typically includes the mime-type, description, a filename and | |||
1264 | other meta information, and possibly even the full original file | 1060 | other meta information, and possibly even the full original file |
1265 | (if it was small). | 1061 | (if it was small). |
1266 | 1062 | ||
1267 | @node File-sharing Namespace Management | 1063 | @node Namespace Management |
1268 | @subsection File-sharing Namespace Management | 1064 | @subsection Namespace Management |
1269 | @c %**end of header | 1065 | @c %**end of header |
1270 | 1066 | ||
1271 | @b{Please note that the text in this subsection is outdated and needs} | 1067 | @b{Please note that the text in this subsection is outdated and needs} |
@@ -1436,6 +1232,135 @@ chosen keyword (or password!). A commonly used identifier is | |||
1436 | "root" which by convention refers to some kind of index or other | 1232 | "root" which by convention refers to some kind of index or other |
1437 | entry point into the namespace. | 1233 | entry point into the namespace. |
1438 | 1234 | ||
1235 | @node GTK User Interface | ||
1236 | @subsection GTK User Interface | ||
1237 | This chapter describes first steps for file-sharing with GNUnet. | ||
1238 | To start, you should launch @command{gnunet-fs-gtk}. | ||
1239 | |||
1240 | As we want to be sure that the network contains the data that we are | ||
1241 | looking for for testing, we need to begin by publishing a file. | ||
1242 | |||
1243 | @menu | ||
1244 | * gtk-Publishing:: | ||
1245 | * gtk-Searching:: | ||
1246 | * gtk-Downloading:: | ||
1247 | @end menu | ||
1248 | |||
1249 | @node gtk-Publishing | ||
1250 | @subsubsection Publishing | ||
1251 | @c %**end of header | ||
1252 | |||
1253 | To publish a file, select "File Sharing" in the menu bar just below the | ||
1254 | "Statistics" icon, and then select "Publish" from the menu. | ||
1255 | |||
1256 | Afterwards, the following publishing dialog will appear: | ||
1257 | |||
1258 | @c Add image here | ||
1259 | |||
1260 | In this dialog, select the "Add File" button. This will open a | ||
1261 | file selection dialog: | ||
1262 | |||
1263 | @c Add image here | ||
1264 | |||
1265 | Now, you should select a file from your computer to be published on | ||
1266 | GNUnet. To see more of GNUnet's features later, you should pick a | ||
1267 | PNG or JPEG file this time. You can leave all of the other options | ||
1268 | in the dialog unchanged. Confirm your selection by pressing the "OK" | ||
1269 | button in the bottom right corner. Now, you will briefly see a | ||
1270 | "Messages..." dialog pop up, but most likely it will be too short for | ||
1271 | you to really read anything. That dialog is showing you progress | ||
1272 | information as GNUnet takes a first look at the selected file(s). | ||
1273 | For a normal image, this is virtually instant, but if you later | ||
1274 | import a larger directory you might be interested in the progress dialog | ||
1275 | and potential errors that might be encountered during processing. | ||
1276 | After the progress dialog automatically disappears, your file | ||
1277 | should now appear in the publishing dialog: | ||
1278 | |||
1279 | @c Add image here | ||
1280 | |||
1281 | Now, select the file (by clicking on the file name) and then click | ||
1282 | the "Edit" button. This will open the editing dialog: | ||
1283 | |||
1284 | @c Add image here | ||
1285 | |||
1286 | In this dialog, you can see many details about your file. In the | ||
1287 | top left area, you can see meta data extracted about the file, | ||
1288 | such as the original filename, the mimetype and the size of the image. | ||
1289 | In the top right, you should see a preview for the image | ||
1290 | (if GNU libextractor was installed correctly with the | ||
1291 | respective plugins). Note that if you do not see a preview, this | ||
1292 | is not a disaster, but you might still want to install more of | ||
1293 | GNU libextractor in the future. In the bottom left, the dialog contains | ||
1294 | a list of keywords. These are the keywords under which the file will be | ||
1295 | made available. The initial list will be based on the extracted meta data. | ||
1296 | Additional publishing options are in the right bottom corner. We will | ||
1297 | now add an additional keyword to the list of keywords. This is done by | ||
1298 | entering the keyword above the keyword list between the label "Keyword" | ||
1299 | and the "Add keyword" button. Enter "test" and select "Add keyword". | ||
1300 | Note that the keyword will appear at the bottom of the existing keyword | ||
1301 | list, so you might have to scroll down to see it. Afterwards, push the | ||
1302 | "OK" button at the bottom right of the dialog. | ||
1303 | |||
1304 | You should now be back at the "Publish content on GNUnet" dialog. Select | ||
1305 | "Execute" in the bottom right to close the dialog and publish your file | ||
1306 | on GNUnet! Afterwards, you should see the main dialog with a new area | ||
1307 | showing the list of published files (or ongoing publishing operations | ||
1308 | with progress indicators): | ||
1309 | |||
1310 | @c Add image here | ||
1311 | |||
1312 | @node gtk-Searching | ||
1313 | @subsubsection Searching | ||
1314 | @c %**end of header | ||
1315 | |||
1316 | Below the menu bar, there are four entry widges labeled "Namespace", | ||
1317 | "Keywords", "Anonymity" and "Mime-type" (from left to right). These | ||
1318 | widgets are used to control searching for files in GNUnet. Between the | ||
1319 | "Keywords" and "Anonymity" widgets, there is also a big "Search" button, | ||
1320 | which is used to initiate the search. We will ignore the "Namespace", | ||
1321 | "Anonymity" and "Mime-type" options in this tutorial, please leave them | ||
1322 | empty. Instead, simply enter "test" under "Keywords" and press "Search". | ||
1323 | Afterwards, you should immediately see a new tab labeled after your | ||
1324 | search term, followed by the (current) number of search | ||
1325 | results --- "(15)" in our screenshot. Note that your results may | ||
1326 | vary depending on what other users may have shared and how your | ||
1327 | peer is connected. | ||
1328 | |||
1329 | You can now select one of the search results. Once you do this, | ||
1330 | additional information about the result should be displayed on the | ||
1331 | right. If available, a preview image should appear on the top right. | ||
1332 | Meta data describing the file will be listed at the bottom right. | ||
1333 | |||
1334 | Once a file is selected, at the bottom of the search result list | ||
1335 | a little area for downloading appears. | ||
1336 | |||
1337 | @node gtk-Downloading | ||
1338 | @subsubsection Downloading | ||
1339 | @c %**end of header | ||
1340 | |||
1341 | In the downloading area, you can select the target directory (default is | ||
1342 | "Downloads") and specify the desired filename (by default the filename it | ||
1343 | taken from the meta data of the published file). Additionally, you can | ||
1344 | specify if the download should be anonymous and (for directories) if | ||
1345 | the download should be recursive. In most cases, you can simply start | ||
1346 | the download with the "Download!" button. | ||
1347 | |||
1348 | Once you selected download, the progress of the download will be | ||
1349 | displayed with the search result. You may need to resize the result | ||
1350 | list or scroll to the right. The "Status" column shows the current | ||
1351 | status of the download, and "Progress" how much has been completed. | ||
1352 | When you close the search tab (by clicking on the "X" button next to | ||
1353 | the "test" label), ongoing and completed downloads are not aborted | ||
1354 | but moved to a special "*" tab. | ||
1355 | |||
1356 | You can remove completed downloads from the "*" tab by clicking the | ||
1357 | cleanup button next to the "*". You can also abort downloads by right | ||
1358 | clicking on the respective download and selecting "Abort download" | ||
1359 | from the menu. | ||
1360 | |||
1361 | That's it, you now know the basics for file-sharing with GNUnet! | ||
1362 | |||
1363 | |||
1439 | @node The GNU Name System | 1364 | @node The GNU Name System |
1440 | @section The GNU Name System | 1365 | @section The GNU Name System |
1441 | @c %**end of header | 1366 | @c %**end of header |
@@ -2016,7 +1941,7 @@ destination. | |||
2016 | 1941 | ||
2017 | For applications that do not use DNS, you can also manually create | 1942 | For applications that do not use DNS, you can also manually create |
2018 | such a mapping using the gnunet-vpn command-line tool. Here, you | 1943 | such a mapping using the gnunet-vpn command-line tool. Here, you |
2019 | specfiy the desired address family of the result (i.e. "-4"), and the | 1944 | specify the desired address family of the result (i.e. "-4"), and the |
2020 | intended target IP on the Internet ("-i 131.159.74.67") and | 1945 | intended target IP on the Internet ("-i 131.159.74.67") and |
2021 | "gnunet-vpn" will tell you which IP address in the range of your | 1946 | "gnunet-vpn" will tell you which IP address in the range of your |
2022 | VPN tunnel was mapped. | 1947 | VPN tunnel was mapped. |
@@ -2029,1923 +1954,3 @@ protocol (--tcp or --udp) and you will again receive an IP address | |||
2029 | that will terminate at the respective peer's service. | 1954 | that will terminate at the respective peer's service. |
2030 | 1955 | ||
2031 | 1956 | ||
2032 | |||
2033 | @c NOTE: Inserted from Installation Handbook in original ``order'': | ||
2034 | @c FIXME: Move this to User Handbook. | ||
2035 | @node The graphical configuration interface | ||
2036 | @section The graphical configuration interface | ||
2037 | |||
2038 | If you also would like to use @command{gnunet-gtk} and | ||
2039 | @command{gnunet-setup} (highly recommended for beginners), do: | ||
2040 | |||
2041 | @menu | ||
2042 | * Configuring your peer:: | ||
2043 | * Configuring the Friend-to-Friend (F2F) mode:: | ||
2044 | * Configuring the hostlist to bootstrap:: | ||
2045 | * Configuration of the HOSTLIST proxy settings:: | ||
2046 | * Configuring your peer to provide a hostlist :: | ||
2047 | * Configuring the datastore:: | ||
2048 | * Configuring the MySQL database:: | ||
2049 | * Reasons for using MySQL:: | ||
2050 | * Reasons for not using MySQL:: | ||
2051 | * Setup Instructions:: | ||
2052 | * Testing:: | ||
2053 | * Performance Tuning:: | ||
2054 | * Setup for running Testcases:: | ||
2055 | * Configuring the Postgres database:: | ||
2056 | * Reasons to use Postgres:: | ||
2057 | * Reasons not to use Postgres:: | ||
2058 | * Manual setup instructions:: | ||
2059 | * Testing the setup manually:: | ||
2060 | * Configuring the datacache:: | ||
2061 | * Configuring the file-sharing service:: | ||
2062 | * Configuring logging:: | ||
2063 | * Configuring the transport service and plugins:: | ||
2064 | * Configuring the wlan transport plugin:: | ||
2065 | * Configuring HTTP(S) reverse proxy functionality using Apache or nginx:: | ||
2066 | * Blacklisting peers:: | ||
2067 | * Configuration of the HTTP and HTTPS transport plugins:: | ||
2068 | * Configuring the GNU Name System:: | ||
2069 | * Configuring the GNUnet VPN:: | ||
2070 | * Bandwidth Configuration:: | ||
2071 | * Configuring NAT:: | ||
2072 | * Peer configuration for distributions:: | ||
2073 | @end menu | ||
2074 | |||
2075 | @node Configuring your peer | ||
2076 | @subsection Configuring your peer | ||
2077 | |||
2078 | This chapter will describe the various configuration options in GNUnet. | ||
2079 | |||
2080 | The easiest way to configure your peer is to use the | ||
2081 | @command{gnunet-setup} tool. | ||
2082 | @command{gnunet-setup} is part of the @command{gnunet-gtk} | ||
2083 | application. You might have to install it separately. | ||
2084 | |||
2085 | Many of the specific sections from this chapter actually are linked from | ||
2086 | within @command{gnunet-setup} to help you while using the setup tool. | ||
2087 | |||
2088 | While you can also configure your peer by editing the configuration | ||
2089 | file by hand, this is not recommended for anyone except for developers | ||
2090 | as it requires a more in-depth understanding of the configuration files | ||
2091 | and internal dependencies of GNUnet. | ||
2092 | |||
2093 | @node Configuring the Friend-to-Friend (F2F) mode | ||
2094 | @subsection Configuring the Friend-to-Friend (F2F) mode | ||
2095 | |||
2096 | GNUnet knows three basic modes of operation: | ||
2097 | @itemize @bullet | ||
2098 | @item In standard "peer-to-peer" mode, | ||
2099 | your peer will connect to any peer. | ||
2100 | @item In the pure "friend-to-friend" | ||
2101 | mode, your peer will ONLY connect to peers from a list of friends | ||
2102 | specified in the configuration. | ||
2103 | @item Finally, in mixed mode, | ||
2104 | GNUnet will only connect to arbitrary peers if it | ||
2105 | has at least a specified number of connections to friends. | ||
2106 | @end itemize | ||
2107 | |||
2108 | When configuring any of the F2F ("friend-to-friend") modes, | ||
2109 | you first need to create a file with the peer identities | ||
2110 | of your friends. Ask your friends to run | ||
2111 | |||
2112 | @example | ||
2113 | $ gnunet-peerinfo -sq | ||
2114 | @end example | ||
2115 | |||
2116 | @noindent | ||
2117 | The resulting output of this command needs to be added to your | ||
2118 | @file{friends} file, which is simply a plain text file with one line | ||
2119 | per friend with the output from the above command. | ||
2120 | |||
2121 | You then specify the location of your @file{friends} file in the | ||
2122 | @code{FRIENDS} option of the "topology" section. | ||
2123 | |||
2124 | Once you have created the @file{friends} file, you can tell GNUnet to only | ||
2125 | connect to your friends by setting the @code{FRIENDS-ONLY} option | ||
2126 | (again in the "topology" section) to YES. | ||
2127 | |||
2128 | If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a | ||
2129 | minimum number of friends to have (before connecting to arbitrary peers) | ||
2130 | under the "MINIMUM-FRIENDS" option. | ||
2131 | |||
2132 | If you want to operate in normal P2P-only mode, simply set | ||
2133 | @code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO. | ||
2134 | This is the default. | ||
2135 | |||
2136 | @node Configuring the hostlist to bootstrap | ||
2137 | @subsection Configuring the hostlist to bootstrap | ||
2138 | |||
2139 | After installing the software you need to get connected to the GNUnet | ||
2140 | network. The configuration file included in your download is already | ||
2141 | configured to connect you to the GNUnet network. | ||
2142 | In this section the relevant configuration settings are explained. | ||
2143 | |||
2144 | To get an initial connection to the GNUnet network and to get to know | ||
2145 | peers already connected to the network you can use the so called | ||
2146 | "bootstrap servers". | ||
2147 | These servers can give you a list of peers connected to the network. | ||
2148 | To use these bootstrap servers you have to configure the hostlist daemon | ||
2149 | to activate bootstrapping. | ||
2150 | |||
2151 | To activate bootstrapping, edit the @code{[hostlist]}-section in your | ||
2152 | configuration file. You have to set the argument @command{-b} in the | ||
2153 | options line: | ||
2154 | |||
2155 | @example | ||
2156 | [hostlist] | ||
2157 | OPTIONS = -b | ||
2158 | @end example | ||
2159 | |||
2160 | Additionally you have to specify which server you want to use. | ||
2161 | The default bootstrapping server is | ||
2162 | "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}". | ||
2163 | [^] To set the server you have to edit the line "SERVERS" in the hostlist | ||
2164 | section. To use the default server you should set the lines to | ||
2165 | |||
2166 | @example | ||
2167 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
2168 | @end example | ||
2169 | |||
2170 | @noindent | ||
2171 | To use bootstrapping your configuration file should include these lines: | ||
2172 | |||
2173 | @example | ||
2174 | [hostlist] | ||
2175 | OPTIONS = -b | ||
2176 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
2177 | @end example | ||
2178 | |||
2179 | @noindent | ||
2180 | Besides using bootstrap servers you can configure your GNUnet peer to | ||
2181 | recieve hostlist advertisements. | ||
2182 | Peers offering hostlists to other peers can send advertisement messages | ||
2183 | to peers that connect to them. If you configure your peer to receive these | ||
2184 | messages, your peer can download these lists and connect to the peers | ||
2185 | included. These lists are persistent, which means that they are saved to | ||
2186 | your hard disk regularly and are loaded during startup. | ||
2187 | |||
2188 | To activate hostlist learning you have to add the @command{-e} | ||
2189 | switch to the @code{OPTIONS} line in the hostlist section: | ||
2190 | |||
2191 | @example | ||
2192 | [hostlist] | ||
2193 | OPTIONS = -b -e | ||
2194 | @end example | ||
2195 | |||
2196 | @noindent | ||
2197 | Furthermore you can specify in which file the lists are saved. | ||
2198 | To save the lists in the file @file{hostlists.file} just add the line: | ||
2199 | |||
2200 | @example | ||
2201 | HOSTLISTFILE = hostlists.file | ||
2202 | @end example | ||
2203 | |||
2204 | @noindent | ||
2205 | Best practice is to activate both bootstrapping and hostlist learning. | ||
2206 | So your configuration file should include these lines: | ||
2207 | |||
2208 | @example | ||
2209 | [hostlist] | ||
2210 | OPTIONS = -b -e | ||
2211 | HTTPPORT = 8080 | ||
2212 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
2213 | HOSTLISTFILE = $SERVICEHOME/hostlists.file | ||
2214 | @end example | ||
2215 | |||
2216 | @node Configuration of the HOSTLIST proxy settings | ||
2217 | @subsection Configuration of the HOSTLIST proxy settings | ||
2218 | |||
2219 | The hostlist client can be configured to use a proxy to connect to the | ||
2220 | hostlist server. | ||
2221 | This functionality can be configured in the configuration file directly | ||
2222 | or using the @command{gnunet-setup} tool. | ||
2223 | |||
2224 | The hostlist client supports the following proxy types at the moment: | ||
2225 | |||
2226 | @itemize @bullet | ||
2227 | @item HTTP and HTTP 1.0 only proxy | ||
2228 | @item SOCKS 4/4a/5/5 with hostname | ||
2229 | @end itemize | ||
2230 | |||
2231 | In addition authentication at the proxy with username and password can be | ||
2232 | configured. | ||
2233 | |||
2234 | To configure proxy support for the hostlist client in the | ||
2235 | @command{gnunet-setup} tool, select the "hostlist" tab and select | ||
2236 | the appropriate proxy type. | ||
2237 | The hostname or IP address (including port if required) has to be entered | ||
2238 | in the "Proxy hostname" textbox. If required, enter username and password | ||
2239 | in the "Proxy username" and "Proxy password" boxes. | ||
2240 | Be aware that this information will be stored in the configuration in | ||
2241 | plain text (TODO: Add explanation and generalize the part in Chapter 3.6 | ||
2242 | about the encrypted home). | ||
2243 | |||
2244 | To provide these options directly in the configuration, you can | ||
2245 | enter the following settings in the @code{[hostlist]} section of | ||
2246 | the configuration: | ||
2247 | |||
2248 | @example | ||
2249 | # Type of proxy server, | ||
2250 | # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME | ||
2251 | # Default: HTTP | ||
2252 | # PROXY_TYPE = HTTP | ||
2253 | |||
2254 | # Hostname or IP of proxy server | ||
2255 | # PROXY = | ||
2256 | # User name for proxy server | ||
2257 | # PROXY_USERNAME = | ||
2258 | # User password for proxy server | ||
2259 | # PROXY_PASSWORD = | ||
2260 | @end example | ||
2261 | |||
2262 | @node Configuring your peer to provide a hostlist | ||
2263 | @subsection Configuring your peer to provide a hostlist | ||
2264 | |||
2265 | If you operate a peer permanently connected to GNUnet you can configure | ||
2266 | your peer to act as a hostlist server, providing other peers the list of | ||
2267 | peers known to it. | ||
2268 | |||
2269 | Your server can act as a bootstrap server and peers needing to obtain a | ||
2270 | list of peers can contact it to download this list. | ||
2271 | To download this hostlist the peer uses HTTP. | ||
2272 | For this reason you have to build your peer with libgnurl (or libcurl) | ||
2273 | and microhttpd support. | ||
2274 | |||
2275 | To configure your peer to act as a bootstrap server you have to add the | ||
2276 | @command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section | ||
2277 | of your configuration file. | ||
2278 | Besides that you have to specify a port number for the http server. | ||
2279 | In conclusion you have to add the following lines: | ||
2280 | |||
2281 | @example | ||
2282 | [hostlist] | ||
2283 | HTTPPORT = 12980 | ||
2284 | OPTIONS = -p | ||
2285 | @end example | ||
2286 | |||
2287 | @noindent | ||
2288 | If your peer acts as a bootstrap server other peers should know about | ||
2289 | that. You can advertise the hostlist your are providing to other peers. | ||
2290 | Peers connecting to your peer will get a message containing an | ||
2291 | advertisement for your hostlist and the URL where it can be downloaded. | ||
2292 | If this peer is in learning mode, it will test the hostlist and, in the | ||
2293 | case it can obtain the list successfully, it will save it for | ||
2294 | bootstrapping. | ||
2295 | |||
2296 | To activate hostlist advertisement on your peer, you have to set the | ||
2297 | following lines in your configuration file: | ||
2298 | |||
2299 | @example | ||
2300 | [hostlist] | ||
2301 | EXTERNAL_DNS_NAME = example.org | ||
2302 | HTTPPORT = 12981 | ||
2303 | OPTIONS = -p -a | ||
2304 | @end example | ||
2305 | |||
2306 | @noindent | ||
2307 | With this configuration your peer will a act as a bootstrap server and | ||
2308 | advertise this hostlist to other peers connecting to it. | ||
2309 | The URL used to download the list will be | ||
2310 | @code{@uref{http://example.org:12981/, http://example.org:12981/}}. | ||
2311 | |||
2312 | Please notice: | ||
2313 | |||
2314 | @itemize @bullet | ||
2315 | @item The hostlist is @b{not} human readable, so you should not try to | ||
2316 | download it using your webbrowser. Just point your GNUnet peer to the | ||
2317 | address! | ||
2318 | @item Advertising without providing a hostlist does not make sense and | ||
2319 | will not work. | ||
2320 | @end itemize | ||
2321 | |||
2322 | @node Configuring the datastore | ||
2323 | @subsection Configuring the datastore | ||
2324 | |||
2325 | The datastore is what GNUnet uses for long-term storage of file-sharing | ||
2326 | data. Note that long-term does not mean 'forever' since content does have | ||
2327 | an expiration date, and of course storage space is finite (and hence | ||
2328 | sometimes content may have to be discarded). | ||
2329 | |||
2330 | Use the @code{QUOTA} option to specify how many bytes of storage space | ||
2331 | you are willing to dedicate to GNUnet. | ||
2332 | |||
2333 | In addition to specifying the maximum space GNUnet is allowed to use for | ||
2334 | the datastore, you need to specify which database GNUnet should use to do | ||
2335 | so. Currently, you have the choice between sqLite, MySQL and Postgres. | ||
2336 | |||
2337 | @node Configuring the MySQL database | ||
2338 | @subsection Configuring the MySQL database | ||
2339 | |||
2340 | This section describes how to setup the MySQL database for GNUnet. | ||
2341 | |||
2342 | Note that the mysql plugin does NOT work with mysql before 4.1 since we | ||
2343 | need prepared statements. | ||
2344 | We are generally testing the code against MySQL 5.1 at this point. | ||
2345 | |||
2346 | @node Reasons for using MySQL | ||
2347 | @subsection Reasons for using MySQL | ||
2348 | |||
2349 | @itemize @bullet | ||
2350 | |||
2351 | @item On up-to-date hardware wher | ||
2352 | mysql can be used comfortably, this module | ||
2353 | will have better performance than the other database choices (according | ||
2354 | to our tests). | ||
2355 | |||
2356 | @item Its often possible to recover the mysql database from internal | ||
2357 | inconsistencies. Some of the other databases do not support repair. | ||
2358 | @end itemize | ||
2359 | |||
2360 | @node Reasons for not using MySQL | ||
2361 | @subsection Reasons for not using MySQL | ||
2362 | |||
2363 | @itemize @bullet | ||
2364 | @item Memory usage (likely not an issue if you have more than 1 GB) | ||
2365 | @item Complex manual setup | ||
2366 | @end itemize | ||
2367 | |||
2368 | @node Setup Instructions | ||
2369 | @subsection Setup Instructions | ||
2370 | |||
2371 | @itemize @bullet | ||
2372 | |||
2373 | @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for | ||
2374 | @code{DATABASE} to @code{mysql}. | ||
2375 | |||
2376 | @item Access mysql as root: | ||
2377 | |||
2378 | @example | ||
2379 | $ mysql -u root -p | ||
2380 | @end example | ||
2381 | |||
2382 | @noindent | ||
2383 | and issue the following commands, replacing $USER with the username | ||
2384 | that will be running @command{gnunet-arm} (so typically "gnunet"): | ||
2385 | |||
2386 | @example | ||
2387 | CREATE DATABASE gnunet; | ||
2388 | GRANT select,insert,update,delete,create,alter,drop,create \ | ||
2389 | temporary tables ON gnunet.* TO $USER@@localhost; | ||
2390 | SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); | ||
2391 | FLUSH PRIVILEGES; | ||
2392 | @end example | ||
2393 | |||
2394 | @item | ||
2395 | In the $HOME directory of $USER, create a @file{.my.cnf} file with the | ||
2396 | following lines | ||
2397 | |||
2398 | @example | ||
2399 | [client] | ||
2400 | user=$USER | ||
2401 | password=$the_password_you_like | ||
2402 | @end example | ||
2403 | |||
2404 | @end itemize | ||
2405 | |||
2406 | Thats it. Note that @file{.my.cnf} file is a slight security risk unless | ||
2407 | its on a safe partition. The @file{$HOME/.my.cnf} can of course be | ||
2408 | a symbolic link. | ||
2409 | Luckily $USER has only priviledges to mess up GNUnet's tables, | ||
2410 | which should be pretty harmless. | ||
2411 | |||
2412 | @node Testing | ||
2413 | @subsection Testing | ||
2414 | |||
2415 | You should briefly try if the database connection works. First, login | ||
2416 | as $USER. Then use: | ||
2417 | |||
2418 | @example | ||
2419 | $ mysql -u $USER | ||
2420 | mysql> use gnunet; | ||
2421 | @end example | ||
2422 | |||
2423 | @noindent | ||
2424 | If you get the message | ||
2425 | |||
2426 | @example | ||
2427 | Database changed | ||
2428 | @end example | ||
2429 | |||
2430 | @noindent | ||
2431 | it probably works. | ||
2432 | |||
2433 | If you get | ||
2434 | |||
2435 | @example | ||
2436 | ERROR 2002: Can't connect to local MySQL server | ||
2437 | through socket '/tmp/mysql.sock' (2) | ||
2438 | @end example | ||
2439 | |||
2440 | @noindent | ||
2441 | it may be resolvable by | ||
2442 | |||
2443 | @example | ||
2444 | ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock | ||
2445 | @end example | ||
2446 | |||
2447 | @noindent | ||
2448 | so there may be some additional trouble depending on your mysql setup. | ||
2449 | |||
2450 | @node Performance Tuning | ||
2451 | @subsection Performance Tuning | ||
2452 | |||
2453 | For GNUnet, you probably want to set the option | ||
2454 | |||
2455 | @example | ||
2456 | innodb_flush_log_at_trx_commit = 0 | ||
2457 | @end example | ||
2458 | |||
2459 | @noindent | ||
2460 | for a rather dramatic boost in MySQL performance. However, this reduces | ||
2461 | the "safety" of your database as with this options you may loose | ||
2462 | transactions during a power outage. | ||
2463 | While this is totally harmless for GNUnet, the option applies to all | ||
2464 | applications using MySQL. So you should set it if (and only if) GNUnet is | ||
2465 | the only application on your system using MySQL. | ||
2466 | |||
2467 | @node Setup for running Testcases | ||
2468 | @subsection Setup for running Testcases | ||
2469 | |||
2470 | If you want to run the testcases, you must create a second database | ||
2471 | "gnunetcheck" with the same username and password. This database will | ||
2472 | then be used for testing (@command{make check}). | ||
2473 | |||
2474 | @node Configuring the Postgres database | ||
2475 | @subsection Configuring the Postgres database | ||
2476 | |||
2477 | This text describes how to setup the Postgres database for GNUnet. | ||
2478 | |||
2479 | This Postgres plugin was developed for Postgres 8.3 but might work for | ||
2480 | earlier versions as well. | ||
2481 | |||
2482 | @node Reasons to use Postgres | ||
2483 | @subsection Reasons to use Postgres | ||
2484 | |||
2485 | @itemize @bullet | ||
2486 | @item Easier to setup than MySQL | ||
2487 | @item Real database | ||
2488 | @end itemize | ||
2489 | |||
2490 | @node Reasons not to use Postgres | ||
2491 | @subsection Reasons not to use Postgres | ||
2492 | |||
2493 | @itemize @bullet | ||
2494 | @item Quite slow | ||
2495 | @item Still some manual setup required | ||
2496 | @end itemize | ||
2497 | |||
2498 | @node Manual setup instructions | ||
2499 | @subsection Manual setup instructions | ||
2500 | |||
2501 | @itemize @bullet | ||
2502 | @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for | ||
2503 | @code{DATABASE} to @code{postgres}. | ||
2504 | @item Access Postgres to create a user: | ||
2505 | |||
2506 | @table @asis | ||
2507 | @item with Postgres 8.x, use: | ||
2508 | |||
2509 | @example | ||
2510 | # su - postgres | ||
2511 | $ createuser | ||
2512 | @end example | ||
2513 | |||
2514 | @noindent | ||
2515 | and enter the name of the user running GNUnet for the role interactively. | ||
2516 | Then, when prompted, do not set it to superuser, allow the creation of | ||
2517 | databases, and do not allow the creation of new roles. | ||
2518 | |||
2519 | @item with Postgres 9.x, use: | ||
2520 | |||
2521 | @example | ||
2522 | # su - postgres | ||
2523 | $ createuser -d $GNUNET_USER | ||
2524 | @end example | ||
2525 | |||
2526 | @noindent | ||
2527 | where $GNUNET_USER is the name of the user running GNUnet. | ||
2528 | |||
2529 | @end table | ||
2530 | |||
2531 | |||
2532 | @item | ||
2533 | As that user (so typically as user "gnunet"), create a database (or two): | ||
2534 | |||
2535 | @example | ||
2536 | $ createdb gnunet | ||
2537 | # this way you can run "make check" | ||
2538 | $ createdb gnunetcheck | ||
2539 | @end example | ||
2540 | |||
2541 | @end itemize | ||
2542 | |||
2543 | Now you should be able to start @code{gnunet-arm}. | ||
2544 | |||
2545 | @node Testing the setup manually | ||
2546 | @subsection Testing the setup manually | ||
2547 | |||
2548 | You may want to try if the database connection works. First, again login | ||
2549 | as the user who will run @command{gnunet-arm}. Then use: | ||
2550 | |||
2551 | @example | ||
2552 | $ psql gnunet # or gnunetcheck | ||
2553 | gnunet=> \dt | ||
2554 | @end example | ||
2555 | |||
2556 | @noindent | ||
2557 | If, after you have started @command{gnunet-arm} at least once, you get | ||
2558 | a @code{gn090} table here, it probably works. | ||
2559 | |||
2560 | @node Configuring the datacache | ||
2561 | @subsection Configuring the datacache | ||
2562 | @c %**end of header | ||
2563 | |||
2564 | The datacache is what GNUnet uses for storing temporary data. This data is | ||
2565 | expected to be wiped completely each time GNUnet is restarted (or the | ||
2566 | system is rebooted). | ||
2567 | |||
2568 | You need to specify how many bytes GNUnet is allowed to use for the | ||
2569 | datacache using the @code{QUOTA} option in the section @code{[dhtcache]}. | ||
2570 | Furthermore, you need to specify which database backend should be used to | ||
2571 | store the data. Currently, you have the choice between | ||
2572 | sqLite, MySQL and Postgres. | ||
2573 | |||
2574 | @node Configuring the file-sharing service | ||
2575 | @subsection Configuring the file-sharing service | ||
2576 | |||
2577 | In order to use GNUnet for file-sharing, you first need to make sure | ||
2578 | that the file-sharing service is loaded. | ||
2579 | This is done by setting the @code{START_ON_DEMAND} option in | ||
2580 | section @code{[fs]} to "YES". Alternatively, you can run | ||
2581 | |||
2582 | @example | ||
2583 | $ gnunet-arm -i fs | ||
2584 | @end example | ||
2585 | |||
2586 | @noindent | ||
2587 | to start the file-sharing service by hand. | ||
2588 | |||
2589 | Except for configuring the database and the datacache the only important | ||
2590 | option for file-sharing is content migration. | ||
2591 | |||
2592 | Content migration allows your peer to cache content from other peers as | ||
2593 | well as send out content stored on your system without explicit requests. | ||
2594 | This content replication has positive and negative impacts on both system | ||
2595 | performance and privacy. | ||
2596 | |||
2597 | FIXME: discuss the trade-offs. Here is some older text about it... | ||
2598 | |||
2599 | Setting this option to YES allows gnunetd to migrate data to the local | ||
2600 | machine. Setting this option to YES is highly recommended for efficiency. | ||
2601 | Its also the default. If you set this value to YES, GNUnet will store | ||
2602 | content on your machine that you cannot decrypt. | ||
2603 | While this may protect you from liability if the judge is sane, it may | ||
2604 | not (IANAL). If you put illegal content on your machine yourself, setting | ||
2605 | this option to YES will probably increase your chances to get away with it | ||
2606 | since you can plausibly deny that you inserted the content. | ||
2607 | Note that in either case, your anonymity would have to be broken first | ||
2608 | (which may be possible depending on the size of the GNUnet network and the | ||
2609 | strength of the adversary). | ||
2610 | |||
2611 | @node Configuring logging | ||
2612 | @subsection Configuring logging | ||
2613 | |||
2614 | Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. | ||
2615 | Using @code{-L}, a log level can be specified. With log level | ||
2616 | @code{ERROR} only serious errors are logged. | ||
2617 | The default log level is @code{WARNING} which causes anything of | ||
2618 | concern to be logged. | ||
2619 | Log level @code{INFO} can be used to log anything that might be | ||
2620 | interesting information whereas | ||
2621 | @code{DEBUG} can be used by developers to log debugging messages | ||
2622 | (but you need to run @code{./configure} with | ||
2623 | @code{--enable-logging=verbose} to get them compiled). | ||
2624 | The @code{-l} option is used to specify the log file. | ||
2625 | |||
2626 | Since most GNUnet services are managed by @code{gnunet-arm}, using the | ||
2627 | @code{-l} or @code{-L} options directly is not possible. | ||
2628 | Instead, they can be specified using the @code{OPTIONS} configuration | ||
2629 | value in the respective section for the respective service. | ||
2630 | In order to enable logging globally without editing the @code{OPTIONS} | ||
2631 | values for each service, @command{gnunet-arm} supports a | ||
2632 | @code{GLOBAL_POSTFIX} option. | ||
2633 | The value specified here is given as an extra option to all services for | ||
2634 | which the configuration does contain a service-specific @code{OPTIONS} | ||
2635 | field. | ||
2636 | |||
2637 | @code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which | ||
2638 | is replaced by the name of the service that is being started. | ||
2639 | Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences | ||
2640 | starting with "$" anywhere in the string are expanded (according | ||
2641 | to options in @code{PATHS}); this expansion otherwise is | ||
2642 | only happening for filenames and then the "$" must be the | ||
2643 | first character in the option. Both of these restrictions do | ||
2644 | not apply to @code{GLOBAL_POSTFIX}. | ||
2645 | Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX} | ||
2646 | disables both of these features. | ||
2647 | |||
2648 | In summary, in order to get all services to log at level | ||
2649 | @code{INFO} to log-files called @code{SERVICENAME-logs}, the | ||
2650 | following global prefix should be used: | ||
2651 | |||
2652 | @example | ||
2653 | GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO | ||
2654 | @end example | ||
2655 | |||
2656 | @node Configuring the transport service and plugins | ||
2657 | @subsection Configuring the transport service and plugins | ||
2658 | |||
2659 | The transport service in GNUnet is responsible to maintain basic | ||
2660 | connectivity to other peers. | ||
2661 | Besides initiating and keeping connections alive it is also responsible | ||
2662 | for address validation. | ||
2663 | |||
2664 | The GNUnet transport supports more than one transport protocol. | ||
2665 | These protocols are configured together with the transport service. | ||
2666 | |||
2667 | The configuration section for the transport service itself is quite | ||
2668 | similar to all the other services | ||
2669 | |||
2670 | @example | ||
2671 | START_ON_DEMAND = YES | ||
2672 | @@UNIXONLY@@ PORT = 2091 | ||
2673 | HOSTNAME = localhost | ||
2674 | HOME = $SERVICEHOME | ||
2675 | CONFIG = $DEFAULTCONFIG | ||
2676 | BINARY = gnunet-service-transport | ||
2677 | #PREFIX = valgrind | ||
2678 | NEIGHBOUR_LIMIT = 50 | ||
2679 | ACCEPT_FROM = 127.0.0.1; | ||
2680 | ACCEPT_FROM6 = ::1; | ||
2681 | PLUGINS = tcp udp | ||
2682 | UNIXPATH = /tmp/gnunet-service-transport.sock | ||
2683 | @end example | ||
2684 | |||
2685 | Different are the settings for the plugins to load @code{PLUGINS}. | ||
2686 | The first setting specifies which transport plugins to load. | ||
2687 | |||
2688 | @itemize @bullet | ||
2689 | @item transport-unix | ||
2690 | A plugin for local only communication with UNIX domain sockets. Used for | ||
2691 | testing and available on unix systems only. Just set the port | ||
2692 | |||
2693 | @example | ||
2694 | [transport-unix] | ||
2695 | PORT = 22086 | ||
2696 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2697 | @end example | ||
2698 | |||
2699 | @item transport-tcp | ||
2700 | A plugin for communication with TCP. Set port to 0 for client mode with | ||
2701 | outbound only connections | ||
2702 | |||
2703 | @example | ||
2704 | [transport-tcp] | ||
2705 | # Use 0 to ONLY advertise as a peer behind NAT (no port binding) | ||
2706 | PORT = 2086 | ||
2707 | ADVERTISED_PORT = 2086 | ||
2708 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2709 | # Maximum number of open TCP connections allowed | ||
2710 | MAX_CONNECTIONS = 128 | ||
2711 | @end example | ||
2712 | |||
2713 | @item transport-udp | ||
2714 | A plugin for communication with UDP. Supports peer discovery using | ||
2715 | broadcasts. | ||
2716 | |||
2717 | @example | ||
2718 | [transport-udp] | ||
2719 | PORT = 2086 | ||
2720 | BROADCAST = YES | ||
2721 | BROADCAST_INTERVAL = 30 s | ||
2722 | MAX_BPS = 1000000 | ||
2723 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2724 | @end example | ||
2725 | |||
2726 | @item transport-http | ||
2727 | HTTP and HTTPS support is split in two part: a client plugin initiating | ||
2728 | outbound connections and a server part accepting connections from the | ||
2729 | client. The client plugin just takes the maximum number of connections as | ||
2730 | an argument. | ||
2731 | |||
2732 | @example | ||
2733 | [transport-http_client] | ||
2734 | MAX_CONNECTIONS = 128 | ||
2735 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2736 | @end example | ||
2737 | |||
2738 | @example | ||
2739 | [transport-https_client] | ||
2740 | MAX_CONNECTIONS = 128 | ||
2741 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2742 | @end example | ||
2743 | |||
2744 | @noindent | ||
2745 | The server has a port configured and the maximum nunber of connections. | ||
2746 | The HTTPS part has two files with the certificate key and the certificate | ||
2747 | file. | ||
2748 | |||
2749 | The server plugin supports reverse proxies, so a external hostname can be | ||
2750 | set using the @code{EXTERNAL_HOSTNAME} setting. | ||
2751 | The webserver under this address should forward the request to the peer | ||
2752 | and the configure port. | ||
2753 | |||
2754 | @example | ||
2755 | [transport-http_server] | ||
2756 | EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet | ||
2757 | PORT = 1080 | ||
2758 | MAX_CONNECTIONS = 128 | ||
2759 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2760 | @end example | ||
2761 | |||
2762 | @example | ||
2763 | [transport-https_server] | ||
2764 | PORT = 4433 | ||
2765 | CRYPTO_INIT = NORMAL | ||
2766 | KEY_FILE = https.key | ||
2767 | CERT_FILE = https.cert | ||
2768 | MAX_CONNECTIONS = 128 | ||
2769 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2770 | @end example | ||
2771 | |||
2772 | @item transport-wlan | ||
2773 | |||
2774 | The next section describes how to setup the WLAN plugin, | ||
2775 | so here only the settings. Just specify the interface to use: | ||
2776 | |||
2777 | @example | ||
2778 | [transport-wlan] | ||
2779 | # Name of the interface in monitor mode (typically monX) | ||
2780 | INTERFACE = mon0 | ||
2781 | # Real hardware, no testing | ||
2782 | TESTMODE = 0 | ||
2783 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2784 | @end example | ||
2785 | @end itemize | ||
2786 | |||
2787 | @node Configuring the wlan transport plugin | ||
2788 | @subsection Configuring the wlan transport plugin | ||
2789 | |||
2790 | The wlan transport plugin enables GNUnet to send and to receive data on a | ||
2791 | wlan interface. | ||
2792 | It has not to be connected to a wlan network as long as sender and | ||
2793 | receiver are on the same channel. This enables you to get connection to | ||
2794 | GNUnet where no internet access is possible, for example during | ||
2795 | catastrophes or when censorship cuts you off from the internet. | ||
2796 | |||
2797 | |||
2798 | @menu | ||
2799 | * Requirements for the WLAN plugin:: | ||
2800 | * Configuration:: | ||
2801 | * Before starting GNUnet:: | ||
2802 | * Limitations and known bugs:: | ||
2803 | @end menu | ||
2804 | |||
2805 | |||
2806 | @node Requirements for the WLAN plugin | ||
2807 | @subsubsection Requirements for the WLAN plugin | ||
2808 | |||
2809 | @itemize @bullet | ||
2810 | |||
2811 | @item wlan network card with monitor support and packet injection | ||
2812 | (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org}) | ||
2813 | |||
2814 | @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with | ||
2815 | 2.6.35 and 2.6.38 | ||
2816 | |||
2817 | @item Wlantools to create the a monitor interface, tested with airmon-ng | ||
2818 | of the aircrack-ng package | ||
2819 | @end itemize | ||
2820 | |||
2821 | @node Configuration | ||
2822 | @subsubsection Configuration | ||
2823 | |||
2824 | There are the following options for the wlan plugin (they should be like | ||
2825 | this in your default config file, you only need to adjust them if the | ||
2826 | values are incorrect for your system) | ||
2827 | |||
2828 | @example | ||
2829 | # section for the wlan transport plugin | ||
2830 | [transport-wlan] | ||
2831 | # interface to use, more information in the | ||
2832 | # "Before starting GNUnet" section of the handbook. | ||
2833 | INTERFACE = mon0 | ||
2834 | # testmode for developers: | ||
2835 | # 0 use wlan interface, | ||
2836 | #1 or 2 use loopback driver for tests 1 = server, 2 = client | ||
2837 | TESTMODE = 0 | ||
2838 | @end example | ||
2839 | |||
2840 | @node Before starting GNUnet | ||
2841 | @subsubsection Before starting GNUnet | ||
2842 | |||
2843 | Before starting GNUnet, you have to make sure that your wlan interface is | ||
2844 | in monitor mode. | ||
2845 | One way to put the wlan interface into monitor mode (if your interface | ||
2846 | name is wlan0) is by executing: | ||
2847 | |||
2848 | @example | ||
2849 | sudo airmon-ng start wlan0 | ||
2850 | @end example | ||
2851 | |||
2852 | @noindent | ||
2853 | Here is an example what the result should look like: | ||
2854 | |||
2855 | @example | ||
2856 | Interface Chipset Driver | ||
2857 | wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0] | ||
2858 | (monitor mode enabled on mon0) | ||
2859 | @end example | ||
2860 | |||
2861 | @noindent | ||
2862 | The monitor interface is mon0 is the one that you have to put into the | ||
2863 | configuration file. | ||
2864 | |||
2865 | @node Limitations and known bugs | ||
2866 | @subsubsection Limitations and known bugs | ||
2867 | |||
2868 | Wlan speed is at the maximum of 1 Mbit/s because support for choosing the | ||
2869 | wlan speed with packet injection was removed in newer kernels. | ||
2870 | Please pester the kernel developers about fixing this. | ||
2871 | |||
2872 | The interface channel depends on the wlan network that the card is | ||
2873 | connected to. If no connection has been made since the start of the | ||
2874 | computer, it is usually the first channel of the card. | ||
2875 | Peers will only find each other and communicate if they are on the same | ||
2876 | channel. Channels must be set manually, i.e. using: | ||
2877 | |||
2878 | @example | ||
2879 | iwconfig wlan0 channel 1 | ||
2880 | @end example | ||
2881 | |||
2882 | @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx | ||
2883 | @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx | ||
2884 | |||
2885 | The HTTP plugin supports data transfer using reverse proxies. A reverse | ||
2886 | proxy forwards the HTTP request it receives with a certain URL to another | ||
2887 | webserver, here a GNUnet peer. | ||
2888 | |||
2889 | So if you have a running Apache or nginx webserver you can configure it to | ||
2890 | be a GNUnet reverse proxy. Especially if you have a well-known webiste | ||
2891 | this improves censorship resistance since it looks as normal surfing | ||
2892 | behaviour. | ||
2893 | |||
2894 | To do so, you have to do two things: | ||
2895 | |||
2896 | @itemize @bullet | ||
2897 | @item Configure your webserver to forward the GNUnet HTTP traffic | ||
2898 | @item Configure your GNUnet peer to announce the respective address | ||
2899 | @end itemize | ||
2900 | |||
2901 | As an example we want to use GNUnet peer running: | ||
2902 | |||
2903 | @itemize @bullet | ||
2904 | |||
2905 | @item HTTP server plugin on @code{gnunet.foo.org:1080} | ||
2906 | |||
2907 | @item HTTPS server plugin on @code{gnunet.foo.org:4433} | ||
2908 | |||
2909 | @item A apache or nginx webserver on | ||
2910 | @uref{http://www.foo.org/, http://www.foo.org:80/} | ||
2911 | |||
2912 | @item A apache or nginx webserver on https://www.foo.org:443/ | ||
2913 | @end itemize | ||
2914 | |||
2915 | And we want the webserver to accept GNUnet traffic under | ||
2916 | @code{http://www.foo.org/bar/}. The required steps are described here: | ||
2917 | |||
2918 | @menu | ||
2919 | * Reverse Proxy - Configure your Apache2 HTTP webserver:: | ||
2920 | * Reverse Proxy - Configure your Apache2 HTTPS webserver:: | ||
2921 | * Reverse Proxy - Configure your nginx HTTPS webserver:: | ||
2922 | * Reverse Proxy - Configure your nginx HTTP webserver:: | ||
2923 | * Reverse Proxy - Configure your GNUnet peer:: | ||
2924 | @end menu | ||
2925 | |||
2926 | @node Reverse Proxy - Configure your Apache2 HTTP webserver | ||
2927 | @subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver | ||
2928 | |||
2929 | First of all you need mod_proxy installed. | ||
2930 | |||
2931 | Edit your webserver configuration. Edit | ||
2932 | @code{/etc/apache2/apache2.conf} or the site-specific configuration file. | ||
2933 | |||
2934 | In the respective @code{server config},@code{virtual host} or | ||
2935 | @code{directory} section add the following lines: | ||
2936 | |||
2937 | @example | ||
2938 | ProxyTimeout 300 | ||
2939 | ProxyRequests Off | ||
2940 | <Location /bar/ > | ||
2941 | ProxyPass http://gnunet.foo.org:1080/ | ||
2942 | ProxyPassReverse http://gnunet.foo.org:1080/ | ||
2943 | </Location> | ||
2944 | @end example | ||
2945 | |||
2946 | @node Reverse Proxy - Configure your Apache2 HTTPS webserver | ||
2947 | @subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver | ||
2948 | |||
2949 | We assume that you already have an HTTPS server running, if not please | ||
2950 | check how to configure a HTTPS host. An uncomplicated to use example | ||
2951 | is the example configuration file for Apache2/HTTPD provided in | ||
2952 | @file{apache2/sites-available/default-ssl}. | ||
2953 | |||
2954 | In the respective HTTPS @code{server config},@code{virtual host} or | ||
2955 | @code{directory} section add the following lines: | ||
2956 | |||
2957 | @example | ||
2958 | SSLProxyEngine On | ||
2959 | ProxyTimeout 300 | ||
2960 | ProxyRequests Off | ||
2961 | <Location /bar/ > | ||
2962 | ProxyPass https://gnunet.foo.org:4433/ | ||
2963 | ProxyPassReverse https://gnunet.foo.org:4433/ | ||
2964 | </Location> | ||
2965 | @end example | ||
2966 | |||
2967 | @noindent | ||
2968 | More information about the apache mod_proxy configuration can be found | ||
2969 | in the Apache documentation@footnote{@uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass}} | ||
2970 | |||
2971 | @node Reverse Proxy - Configure your nginx HTTPS webserver | ||
2972 | @subsubsection Reverse Proxy - Configure your nginx HTTPS webserver | ||
2973 | |||
2974 | Since nginx does not support chunked encoding, you first of all have to | ||
2975 | install the @code{chunkin} module@footnote{@uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule}} | ||
2976 | |||
2977 | To enable chunkin add: | ||
2978 | |||
2979 | @example | ||
2980 | chunkin on; | ||
2981 | error_page 411 = @@my_411_error; | ||
2982 | location @@my_411_error @{ | ||
2983 | chunkin_resume; | ||
2984 | @} | ||
2985 | @end example | ||
2986 | |||
2987 | @noindent | ||
2988 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or | ||
2989 | the site-specific configuration file. | ||
2990 | |||
2991 | In the @code{server} section add: | ||
2992 | |||
2993 | @example | ||
2994 | location /bar/ @{ | ||
2995 | proxy_pass http://gnunet.foo.org:1080/; | ||
2996 | proxy_buffering off; | ||
2997 | proxy_connect_timeout 5; # more than http_server | ||
2998 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout | ||
2999 | proxy_http_version 1.1; # 1.0 default | ||
3000 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; | ||
3001 | @} | ||
3002 | @end example | ||
3003 | |||
3004 | @node Reverse Proxy - Configure your nginx HTTP webserver | ||
3005 | @subsubsection Reverse Proxy - Configure your nginx HTTP webserver | ||
3006 | |||
3007 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or | ||
3008 | the site-specific configuration file. | ||
3009 | |||
3010 | In the @code{server} section add: | ||
3011 | |||
3012 | @example | ||
3013 | ssl_session_timeout 6m; | ||
3014 | location /bar/ | ||
3015 | @{ | ||
3016 | proxy_pass https://gnunet.foo.org:4433/; | ||
3017 | proxy_buffering off; | ||
3018 | proxy_connect_timeout 5; # more than http_server | ||
3019 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout | ||
3020 | proxy_http_version 1.1; # 1.0 default | ||
3021 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; | ||
3022 | @} | ||
3023 | @end example | ||
3024 | |||
3025 | @node Reverse Proxy - Configure your GNUnet peer | ||
3026 | @subsubsection Reverse Proxy - Configure your GNUnet peer | ||
3027 | |||
3028 | To have your GNUnet peer announce the address, you have to specify the | ||
3029 | @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]} | ||
3030 | section: | ||
3031 | |||
3032 | @example | ||
3033 | [transport-http_server] | ||
3034 | EXTERNAL_HOSTNAME = http://www.foo.org/bar/ | ||
3035 | @end example | ||
3036 | |||
3037 | @noindent | ||
3038 | and/or @code{[transport-https_server]} section: | ||
3039 | |||
3040 | @example | ||
3041 | [transport-https_server] | ||
3042 | EXTERNAL_HOSTNAME = https://www.foo.org/bar/ | ||
3043 | @end example | ||
3044 | |||
3045 | @noindent | ||
3046 | Now restart your webserver and your peer... | ||
3047 | |||
3048 | @node Blacklisting peers | ||
3049 | @subsection Blacklisting peers | ||
3050 | |||
3051 | Transport service supports to deny connecting to a specific peer of to a | ||
3052 | specific peer with a specific transport plugin using te blacklisting | ||
3053 | component of transport service. With@ blacklisting it is possible to deny | ||
3054 | connections to specific peers of@ to use a specific plugin to a specific | ||
3055 | peer. Peers can be blacklisted using@ the configuration or a blacklist | ||
3056 | client can be asked. | ||
3057 | |||
3058 | To blacklist peers using the configuration you have to add a section to | ||
3059 | your configuration containing the peer id of the peer to blacklist and | ||
3060 | the plugin@ if required. | ||
3061 | |||
3062 | Examples: | ||
3063 | |||
3064 | To blacklist connections to P565... on peer AG2P... using tcp add: | ||
3065 | |||
3066 | @c FIXME: This is too long and produces errors in the pdf. | ||
3067 | @example | ||
3068 | [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] | ||
3069 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp | ||
3070 | @end example | ||
3071 | |||
3072 | To blacklist connections to P565... on peer AG2P... using all plugins add: | ||
3073 | |||
3074 | @example | ||
3075 | [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] | ||
3076 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = | ||
3077 | @end example | ||
3078 | |||
3079 | You can also add a blacklist client usign the blacklist API. On a | ||
3080 | blacklist check, blacklisting first checks internally if the peer is | ||
3081 | blacklisted and if not, it asks the blacklisting clients. Clients are | ||
3082 | asked if it is OK to connect to a peer ID, the plugin is omitted. | ||
3083 | |||
3084 | On blacklist check for (peer, plugin) | ||
3085 | @itemize @bullet | ||
3086 | @item Do we have a local blacklist entry for this peer and this plugin?@ | ||
3087 | @item YES: disallow connection@ | ||
3088 | @item Do we have a local blacklist entry for this peer and all plugins?@ | ||
3089 | @item YES: disallow connection@ | ||
3090 | @item Does one of the clients disallow?@ | ||
3091 | @item YES: disallow connection | ||
3092 | @end itemize | ||
3093 | |||
3094 | @node Configuration of the HTTP and HTTPS transport plugins | ||
3095 | @subsection Configuration of the HTTP and HTTPS transport plugins | ||
3096 | |||
3097 | The client parts of the http and https transport plugins can be configured | ||
3098 | to use a proxy to connect to the hostlist server. This functionality can | ||
3099 | be configured in the configuration file directly or using the | ||
3100 | gnunet-setup tool. | ||
3101 | |||
3102 | Both the HTTP and HTTPS clients support the following proxy types at | ||
3103 | the moment: | ||
3104 | |||
3105 | @itemize @bullet | ||
3106 | @item HTTP 1.1 proxy | ||
3107 | @item SOCKS 4/4a/5/5 with hostname | ||
3108 | @end itemize | ||
3109 | |||
3110 | In addition authentication at the proxy with username and password can be | ||
3111 | configured. | ||
3112 | |||
3113 | To configure proxy support for the clients in the gnunet-setup tool, | ||
3114 | select the "transport" tab and activate the respective plugin. Now you | ||
3115 | can select the appropriate proxy type. The hostname or IP address | ||
3116 | (including port if required) has to be entered in the "Proxy hostname" | ||
3117 | textbox. If required, enter username and password in the "Proxy username" | ||
3118 | and "Proxy password" boxes. Be aware that these information will be stored | ||
3119 | in the configuration in plain text. | ||
3120 | |||
3121 | To configure these options directly in the configuration, you can | ||
3122 | configure the following settings in the @code{[transport-http_client]} | ||
3123 | and @code{[transport-https_client]} section of the configuration: | ||
3124 | |||
3125 | @example | ||
3126 | # Type of proxy server, | ||
3127 | # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME | ||
3128 | # Default: HTTP | ||
3129 | # PROXY_TYPE = HTTP | ||
3130 | |||
3131 | # Hostname or IP of proxy server | ||
3132 | # PROXY = | ||
3133 | # User name for proxy server | ||
3134 | # PROXY_USERNAME = | ||
3135 | # User password for proxy server | ||
3136 | # PROXY_PASSWORD = | ||
3137 | @end example | ||
3138 | |||
3139 | @node Configuring the GNU Name System | ||
3140 | @subsection Configuring the GNU Name System | ||
3141 | |||
3142 | @menu | ||
3143 | * Configuring system-wide DNS interception:: | ||
3144 | * Configuring the GNS nsswitch plugin:: | ||
3145 | * Configuring GNS on W32:: | ||
3146 | * GNS Proxy Setup:: | ||
3147 | * Setup of the GNS CA:: | ||
3148 | * Testing the GNS setup:: | ||
3149 | @end menu | ||
3150 | |||
3151 | |||
3152 | @node Configuring system-wide DNS interception | ||
3153 | @subsubsection Configuring system-wide DNS interception | ||
3154 | |||
3155 | Before you install GNUnet, make sure you have a user and group 'gnunet' | ||
3156 | as well as an empty group 'gnunetdns'. | ||
3157 | |||
3158 | When using GNUnet with system-wide DNS interception, it is absolutely | ||
3159 | necessary for all GNUnet service processes to be started by | ||
3160 | @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be | ||
3161 | sure to run @code{make install} as root (or use the @code{sudo} option to | ||
3162 | configure) to grant GNUnet sufficient privileges. | ||
3163 | |||
3164 | With this setup, all that is required for enabling system-wide DNS | ||
3165 | interception is for some GNUnet component (VPN or GNS) to request it. | ||
3166 | The @code{gnunet-service-dns} will then start helper programs that will | ||
3167 | make the necessary changes to your firewall (@code{iptables}) rules. | ||
3168 | |||
3169 | Note that this will NOT work if your system sends out DNS traffic to a | ||
3170 | link-local IPv6 address, as in this case GNUnet can intercept the traffic, | ||
3171 | but not inject the responses from the link-local IPv6 address. Hence you | ||
3172 | cannot use system-wide DNS interception in conjunction with link-local | ||
3173 | IPv6-based DNS servers. If such a DNS server is used, it will bypass | ||
3174 | GNUnet's DNS traffic interception. | ||
3175 | |||
3176 | Using the GNU Name System (GNS) requires two different configuration | ||
3177 | steps. | ||
3178 | First of all, GNS needs to be integrated with the operating system. Most | ||
3179 | of this section is about the operating system level integration. | ||
3180 | |||
3181 | The remainder of this chapter will detail the various methods for | ||
3182 | configuring the use of GNS with your operating system. | ||
3183 | |||
3184 | At this point in time you have different options depending on your OS: | ||
3185 | |||
3186 | @table @asis | ||
3187 | |||
3188 | @item Use the gnunet-gns-proxy This approach works for all operating | ||
3189 | systems and is likely the easiest. However, it enables GNS only for | ||
3190 | browsers, not for other applications that might be using DNS, such as SSH. | ||
3191 | Still, using the proxy is required for using HTTP with GNS and is thus | ||
3192 | recommended for all users. To do this, you simply have to run the | ||
3193 | @code{gnunet-gns-proxy-setup-ca} script as the user who will run the | ||
3194 | browser (this will create a GNS certificate authority (CA) on your system | ||
3195 | and import its key into your browser), then start @code{gnunet-gns-proxy} | ||
3196 | and inform your browser to use the Socks5 proxy which | ||
3197 | @code{gnunet-gns-proxy} makes available by default on port 7777. | ||
3198 | @item Use a nsswitch plugin (recommended on GNU systems) | ||
3199 | This approach has the advantage of offering fully personalized resolution | ||
3200 | even on multi-user systems. A potential disadvantage is that some | ||
3201 | applications might be able to bypass GNS. | ||
3202 | @item Use a W32 resolver plugin (recommended on W32) | ||
3203 | This is currently the only option on W32 systems. | ||
3204 | @item Use system-wide DNS packet interception | ||
3205 | This approach is recommended for the GNUnet VPN. It can be used to handle | ||
3206 | GNS at the same time; however, if you only use this method, you will only | ||
3207 | get one root zone per machine (not so great for multi-user systems). | ||
3208 | @end table | ||
3209 | |||
3210 | You can combine system-wide DNS packet interception with the nsswitch | ||
3211 | plugin. | ||
3212 | The setup of the system-wide DNS interception is described here. All of | ||
3213 | the other GNS-specific configuration steps are described in the following | ||
3214 | sections. | ||
3215 | |||
3216 | @node Configuring the GNS nsswitch plugin | ||
3217 | @subsubsection Configuring the GNS nsswitch plugin | ||
3218 | |||
3219 | The Name Service Switch (NSS) is a facility in Unix-like operating systems | ||
3220 | @footnote{More accurate: NSS is a functionality of the GNU C Library} | ||
3221 | that provides a variety of sources for common configuration databases and | ||
3222 | name resolution mechanisms. | ||
3223 | A superuser (system administrator) usually configures the | ||
3224 | operating system's name services using the file | ||
3225 | @file{/etc/nsswitch.conf}. | ||
3226 | |||
3227 | GNS provides a NSS plugin to integrate GNS name resolution with the | ||
3228 | operating system's name resolution process. | ||
3229 | To use the GNS NSS plugin you have to either | ||
3230 | |||
3231 | @itemize @bullet | ||
3232 | @item install GNUnet as root or | ||
3233 | @item compile GNUnet with the @code{--with-sudo=yes} switch. | ||
3234 | @end itemize | ||
3235 | |||
3236 | Name resolution is controlled by the @emph{hosts} section in the NSS | ||
3237 | configuration. By default this section first performs a lookup in the | ||
3238 | @file{/etc/hosts} file and then in DNS. | ||
3239 | The nsswitch file should contain a line similar to: | ||
3240 | |||
3241 | @example | ||
3242 | hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4 | ||
3243 | @end example | ||
3244 | |||
3245 | @noindent | ||
3246 | Here the GNS NSS plugin can be added to perform a GNS lookup before | ||
3247 | performing a DNS lookup. | ||
3248 | The GNS NSS plugin has to be added to the "hosts" section in | ||
3249 | @file{/etc/nsswitch.conf} file before DNS related plugins: | ||
3250 | |||
3251 | @example | ||
3252 | ... | ||
3253 | hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4 | ||
3254 | ... | ||
3255 | @end example | ||
3256 | |||
3257 | @noindent | ||
3258 | The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not | ||
3259 | found in GNS it will not be queried in DNS. | ||
3260 | |||
3261 | @node Configuring GNS on W32 | ||
3262 | @subsubsection Configuring GNS on W32 | ||
3263 | |||
3264 | This document is a guide to configuring GNU Name System on W32-compatible | ||
3265 | platforms. | ||
3266 | |||
3267 | After GNUnet is installed, run the w32nsp-install tool: | ||
3268 | |||
3269 | @example | ||
3270 | w32nsp-install.exe libw32nsp-0.dll | ||
3271 | @end example | ||
3272 | |||
3273 | @noindent | ||
3274 | ('0' is the library version of W32 NSP; it might increase in the future, | ||
3275 | change the invocation accordingly). | ||
3276 | |||
3277 | This will install GNS namespace provider into the system and allow other | ||
3278 | applications to resolve names that end in '@strong{gnu}' | ||
3279 | and '@strong{zkey}'. Note that namespace provider requires | ||
3280 | gnunet-gns-helper-service-w32 to be running, as well as gns service | ||
3281 | itself (and its usual dependencies). | ||
3282 | |||
3283 | Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353}, | ||
3284 | and this is where gnunet-gns-helper-service-w32 should be listening to | ||
3285 | (and is configured to listen to by default). | ||
3286 | |||
3287 | To uninstall the provider, run: | ||
3288 | |||
3289 | @example | ||
3290 | w32nsp-uninstall.exe | ||
3291 | @end example | ||
3292 | |||
3293 | @noindent | ||
3294 | (uses provider GUID to uninstall it, does not need a dll name). | ||
3295 | |||
3296 | Note that while MSDN claims that other applications will only be able to | ||
3297 | use the new namespace provider after re-starting, in reality they might | ||
3298 | stat to use it without that. Conversely, they might stop using the | ||
3299 | provider after it's been uninstalled, even if they were not re-started. | ||
3300 | W32 will not permit namespace provider library to be deleted or | ||
3301 | overwritten while the provider is installed, and while there is at least | ||
3302 | one process still using it (even after it was uninstalled). | ||
3303 | |||
3304 | @node GNS Proxy Setup | ||
3305 | @subsubsection GNS Proxy Setup | ||
3306 | |||
3307 | When using the GNU Name System (GNS) to browse the WWW, there are several | ||
3308 | issues that can be solved by adding the GNS Proxy to your setup: | ||
3309 | |||
3310 | @itemize @bullet | ||
3311 | |||
3312 | @item If the target website does not support GNS, it might assume that it | ||
3313 | is operating under some name in the legacy DNS system (such as | ||
3314 | example.com). It may then attempt to set cookies for that domain, and the | ||
3315 | web server might expect a @code{Host: example.com} header in the request | ||
3316 | from your browser. | ||
3317 | However, your browser might be using @code{example.gnu} for the | ||
3318 | @code{Host} header and might only accept (and send) cookies for | ||
3319 | @code{example.gnu}. The GNS Proxy will perform the necessary translations | ||
3320 | of the hostnames for cookies and HTTP headers (using the LEHO record for | ||
3321 | the target domain as the desired substitute). | ||
3322 | |||
3323 | @item If using HTTPS, the target site might include an SSL certificate | ||
3324 | which is either only valid for the LEHO domain or might match a TLSA | ||
3325 | record in GNS. However, your browser would expect a valid certificate for | ||
3326 | @code{example.gnu}, not for some legacy domain name. The proxy will | ||
3327 | validate the certificate (either against LEHO or TLSA) and then | ||
3328 | on-the-fly produce a valid certificate for the exchange, signed by your | ||
3329 | own CA. Assuming you installed the CA of your proxy in your browser's | ||
3330 | certificate authority list, your browser will then trust the | ||
3331 | HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy. | ||
3332 | |||
3333 | @item Finally, the proxy will in the future indicate to the server that it | ||
3334 | speaks GNS, which will enable server operators to deliver GNS-enabled web | ||
3335 | sites to your browser (and continue to deliver legacy links to legacy | ||
3336 | browsers) | ||
3337 | @end itemize | ||
3338 | |||
3339 | @node Setup of the GNS CA | ||
3340 | @subsubsection Setup of the GNS CA | ||
3341 | |||
3342 | First you need to create a CA certificate that the proxy can use. | ||
3343 | To do so use the provided script gnunet-gns-proxy-ca: | ||
3344 | |||
3345 | @example | ||
3346 | $ gnunet-gns-proxy-setup-ca | ||
3347 | @end example | ||
3348 | |||
3349 | @noindent | ||
3350 | This will create a personal certification authority for you and add this | ||
3351 | authority to the firefox and chrome database. The proxy will use the this | ||
3352 | CA certificate to generate @code{*.gnu} client certificates on the fly. | ||
3353 | |||
3354 | Note that the proxy uses libcurl. Make sure your version of libcurl uses | ||
3355 | GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled | ||
3356 | against OpenSSL. | ||
3357 | |||
3358 | You can check the configuration your libcurl was build with by | ||
3359 | running: | ||
3360 | |||
3361 | @example | ||
3362 | curl --version | ||
3363 | @end example | ||
3364 | |||
3365 | the output will look like this (without the linebreaks): | ||
3366 | |||
3367 | @example | ||
3368 | gnurl --version | ||
3369 | curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \ | ||
3370 | GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4 | ||
3371 | Release-Date: 2017-10-08 | ||
3372 | Protocols: http https | ||
3373 | Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \ | ||
3374 | TLS-SRP UnixSockets HTTPS-proxy | ||
3375 | @end example | ||
3376 | |||
3377 | @node Testing the GNS setup | ||
3378 | @subsubsection Testing the GNS setup | ||
3379 | |||
3380 | Now for testing purposes we can create some records in our zone to test | ||
3381 | the SSL functionality of the proxy: | ||
3382 | |||
3383 | @example | ||
3384 | $ gnunet-identity -C test | ||
3385 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ | ||
3386 | -t A -V 131.159.74.67 -z test | ||
3387 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ | ||
3388 | -t LEHO -V "gnunet.org" -z test | ||
3389 | @end example | ||
3390 | |||
3391 | @noindent | ||
3392 | At this point we can start the proxy. Simply execute | ||
3393 | |||
3394 | @example | ||
3395 | $ gnunet-gns-proxy | ||
3396 | @end example | ||
3397 | |||
3398 | @noindent | ||
3399 | Configure your browser to use this SOCKSv5 proxy on port 7777 and visit | ||
3400 | this link. | ||
3401 | If you use @command{Firefox} (or one of its deriviates/forks such as | ||
3402 | Icecat) you also have to go to @code{about:config} and set the key | ||
3403 | @code{network.proxy.socks_remote_dns} to @code{true}. | ||
3404 | |||
3405 | When you visit @code{https://homepage.test/}, you should get to the | ||
3406 | @code{https://gnunet.org/} frontpage and the browser (with the correctly | ||
3407 | configured proxy) should give you a valid SSL certificate for | ||
3408 | @code{homepage.gnu} and no warnings. It should look like this: | ||
3409 | |||
3410 | @c FIXME: Image does not exist, create it or save it from Drupal? | ||
3411 | @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} | ||
3412 | |||
3413 | |||
3414 | @node Configuring the GNUnet VPN | ||
3415 | @subsection Configuring the GNUnet VPN | ||
3416 | |||
3417 | @menu | ||
3418 | * IPv4 address for interface:: | ||
3419 | * IPv6 address for interface:: | ||
3420 | * Configuring the GNUnet VPN DNS:: | ||
3421 | * Configuring the GNUnet VPN Exit Service:: | ||
3422 | * IP Address of external DNS resolver:: | ||
3423 | * IPv4 address for Exit interface:: | ||
3424 | * IPv6 address for Exit interface:: | ||
3425 | @end menu | ||
3426 | |||
3427 | Before configuring the GNUnet VPN, please make sure that system-wide DNS | ||
3428 | interception is configured properly as described in the section on the | ||
3429 | GNUnet DNS setup. @pxref{Configuring the GNU Name System}, | ||
3430 | if you haven't done so already. | ||
3431 | |||
3432 | The default options for the GNUnet VPN are usually sufficient to use | ||
3433 | GNUnet as a Layer 2 for your Internet connection. | ||
3434 | However, what you always have to specify is which IP protocol you want | ||
3435 | to tunnel: IPv4, IPv6 or both. | ||
3436 | Furthermore, if you tunnel both, you most likely should also tunnel | ||
3437 | all of your DNS requests. | ||
3438 | You theoretically can tunnel "only" your DNS traffic, but that usually | ||
3439 | makes little sense. | ||
3440 | |||
3441 | The other options as shown on the gnunet-setup tool are: | ||
3442 | |||
3443 | @node IPv4 address for interface | ||
3444 | @subsubsection IPv4 address for interface | ||
3445 | |||
3446 | This is the IPv4 address the VPN interface will get. You should pick an | ||
3447 | 'private' IPv4 network that is not yet in use for you system. For example, | ||
3448 | if you use @code{10.0.0.1/255.255.0.0} already, you might use | ||
3449 | @code{10.1.0.1/255.255.0.0}. | ||
3450 | If you use @code{10.0.0.1/255.0.0.0} already, then you might use | ||
3451 | @code{192.168.0.1/255.255.0.0}. | ||
3452 | If your system is not in a private IP-network, using any of the above will | ||
3453 | work fine. | ||
3454 | You should try to make the mask of the address big enough | ||
3455 | (@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more | ||
3456 | mappings of remote IP Addresses into this range. | ||
3457 | However, even a @code{255.255.255.0} mask will suffice for most users. | ||
3458 | |||
3459 | @node IPv6 address for interface | ||
3460 | @subsubsection IPv6 address for interface | ||
3461 | |||
3462 | The IPv6 address the VPN interface will get. Here you can specify any | ||
3463 | non-link-local address (the address should not begin with @code{fe80:}). | ||
3464 | A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are | ||
3465 | currently not using would be a good choice. | ||
3466 | |||
3467 | @node Configuring the GNUnet VPN DNS | ||
3468 | @subsubsection Configuring the GNUnet VPN DNS | ||
3469 | |||
3470 | To resolve names for remote nodes, activate the DNS exit option. | ||
3471 | |||
3472 | @node Configuring the GNUnet VPN Exit Service | ||
3473 | @subsubsection Configuring the GNUnet VPN Exit Service | ||
3474 | |||
3475 | If you want to allow other users to share your Internet connection (yes, | ||
3476 | this may be dangerous, just as running a Tor exit node) or want to | ||
3477 | provide access to services on your host (this should be less dangerous, | ||
3478 | as long as those services are secure), you have to enable the GNUnet exit | ||
3479 | daemon. | ||
3480 | |||
3481 | You then get to specify which exit functions you want to provide. By | ||
3482 | enabling the exit daemon, you will always automatically provide exit | ||
3483 | functions for manually configured local services (this component of the | ||
3484 | system is under | ||
3485 | development and not documented further at this time). As for those | ||
3486 | services you explicitly specify the target IP address and port, there is | ||
3487 | no significant security risk in doing so. | ||
3488 | |||
3489 | Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet. | ||
3490 | Being a DNS exit is usually pretty harmless. However, enabling IPv4 or | ||
3491 | IPv6-exit without further precautions may enable adversaries to access | ||
3492 | your local network, send spam, attack other systems from your Internet | ||
3493 | connection and to other mischief that will appear to come from your | ||
3494 | machine. This may or may not get you into legal trouble. | ||
3495 | If you want to allow IPv4 or IPv6-exit functionality, you should strongly | ||
3496 | consider adding additional firewall rules manually to protect your local | ||
3497 | network and to restrict outgoing TCP traffic (i.e. by not allowing access | ||
3498 | to port 25). While we plan to improve exit-filtering in the future, | ||
3499 | you're currently on your own here. | ||
3500 | Essentially, be prepared for any kind of IP-traffic to exit the respective | ||
3501 | TUN interface (and GNUnet will enable IP-forwarding and NAT for the | ||
3502 | interface automatically). | ||
3503 | |||
3504 | Additional configuration options of the exit as shown by the gnunet-setup | ||
3505 | tool are: | ||
3506 | |||
3507 | @node IP Address of external DNS resolver | ||
3508 | @subsubsection IP Address of external DNS resolver | ||
3509 | |||
3510 | If DNS traffic is to exit your machine, it will be send to this DNS | ||
3511 | resolver. You can specify an IPv4 or IPv6 address. | ||
3512 | |||
3513 | @node IPv4 address for Exit interface | ||
3514 | @subsubsection IPv4 address for Exit interface | ||
3515 | |||
3516 | This is the IPv4 address the Interface will get. Make the mask of the | ||
3517 | address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more | ||
3518 | mappings of IP addresses into this range. As for the VPN interface, any | ||
3519 | unused, private IPv4 address range will do. | ||
3520 | |||
3521 | @node IPv6 address for Exit interface | ||
3522 | @subsubsection IPv6 address for Exit interface | ||
3523 | |||
3524 | The public IPv6 address the interface will get. If your kernel is not a | ||
3525 | very recent kernel and you are willing to manually enable IPv6-NAT, the | ||
3526 | IPv6 address you specify here must be a globally routed IPv6 address of | ||
3527 | your host. | ||
3528 | |||
3529 | Suppose your host has the address @code{2001:4ca0::1234/64}, then | ||
3530 | using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits, | ||
3531 | then change at least one bit in the range before the bitmask, in the | ||
3532 | example above we changed bit 111 from 0 to 1). | ||
3533 | |||
3534 | You may also have to configure your router to route traffic for the entire | ||
3535 | subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this | ||
3536 | should be automatic with IPv6, but obviously anything can be | ||
3537 | disabled). | ||
3538 | |||
3539 | @node Bandwidth Configuration | ||
3540 | @subsection Bandwidth Configuration | ||
3541 | |||
3542 | You can specify how many bandwidth GNUnet is allowed to use to receive | ||
3543 | and send data. This is important for users with limited bandwidth or | ||
3544 | traffic volume. | ||
3545 | |||
3546 | @node Configuring NAT | ||
3547 | @subsection Configuring NAT | ||
3548 | |||
3549 | Most hosts today do not have a normal global IP address but instead are | ||
3550 | behind a router performing Network Address Translation (NAT) which assigns | ||
3551 | each host in the local network a private IP address. | ||
3552 | As a result, these machines cannot trivially receive inbound connections | ||
3553 | from the Internet. GNUnet supports NAT traversal to enable these machines | ||
3554 | to receive incoming connections from other peers despite their | ||
3555 | limitations. | ||
3556 | |||
3557 | In an ideal world, you can press the "Attempt automatic configuration" | ||
3558 | button in gnunet-setup to automatically configure your peer correctly. | ||
3559 | Alternatively, your distribution might have already triggered this | ||
3560 | automatic configuration during the installation process. | ||
3561 | However, automatic configuration can fail to determine the optimal | ||
3562 | settings, resulting in your peer either not receiving as many connections | ||
3563 | as possible, or in the worst case it not connecting to the network at all. | ||
3564 | |||
3565 | To manually configure the peer, you need to know a few things about your | ||
3566 | network setup. First, determine if you are behind a NAT in the first | ||
3567 | place. | ||
3568 | This is always the case if your IP address starts with "10.*" or | ||
3569 | "192.168.*". Next, if you have control over your NAT router, you may | ||
3570 | choose to manually configure it to allow GNUnet traffic to your host. | ||
3571 | If you have configured your NAT to forward traffic on ports 2086 (and | ||
3572 | possibly 1080) to your host, you can check the "NAT ports have been opened | ||
3573 | manually" option, which corresponds to the "PUNCHED_NAT" option in the | ||
3574 | configuration file. If you did not punch your NAT box, it may still be | ||
3575 | configured to support UPnP, which allows GNUnet to automatically | ||
3576 | configure it. In that case, you need to install the "upnpc" command, | ||
3577 | enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal | ||
3578 | via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the | ||
3579 | configuration file). | ||
3580 | |||
3581 | Some NAT boxes can be traversed using the autonomous NAT traversal method. | ||
3582 | This requires certain GNUnet components to be installed with "SUID" | ||
3583 | prividledges on your system (so if you're installing on a system you do | ||
3584 | not have administrative rights to, this will not work). | ||
3585 | If you installed as 'root', you can enable autonomous NAT traversal by | ||
3586 | checking the "Enable NAT traversal using ICMP method". | ||
3587 | The ICMP method requires a way to determine your NAT's external (global) | ||
3588 | IP address. This can be done using either UPnP, DynDNS, or by manual | ||
3589 | configuration. If you have a DynDNS name or know your external IP address, | ||
3590 | you should enter that name under "External (public) IPv4 address" (which | ||
3591 | corresponds to the "EXTERNAL_ADDRESS" option in the configuration file). | ||
3592 | If you leave the option empty, GNUnet will try to determine your external | ||
3593 | IP address automatically (which may fail, in which case autonomous | ||
3594 | NAT traversal will then not work). | ||
3595 | |||
3596 | Finally, if you yourself are not behind NAT but want to be able to | ||
3597 | connect to NATed peers using autonomous NAT traversal, you need to check | ||
3598 | the "Enable connecting to NATed peers using ICMP method" box. | ||
3599 | |||
3600 | |||
3601 | @node Peer configuration for distributions | ||
3602 | @subsection Peer configuration for distributions | ||
3603 | |||
3604 | The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be | ||
3605 | manually set to "/var/lib/gnunet/data/" as the default | ||
3606 | "~/.local/share/gnunet/" is probably not that appropriate in this case. | ||
3607 | Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to | ||
3608 | "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a | ||
3609 | distribution decide to override system defaults, all of these changes | ||
3610 | should be done in a custom @file{/etc/gnunet.conf} and not in the files | ||
3611 | in the @file{config.d/} directory. | ||
3612 | |||
3613 | Given the proposed access permissions, the "gnunet-setup" tool must be | ||
3614 | run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it | ||
3615 | modifies the system configuration). As always, gnunet-setup should be run | ||
3616 | after the GNUnet peer was stopped using "gnunet-arm -e". Distributions | ||
3617 | might want to include a wrapper for gnunet-setup that allows the | ||
3618 | desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account | ||
3619 | and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in | ||
3620 | sequence. | ||
3621 | |||
3622 | @node How to start and stop a GNUnet peer | ||
3623 | @section How to start and stop a GNUnet peer | ||
3624 | |||
3625 | This section describes how to start a GNUnet peer. It assumes that you | ||
3626 | have already compiled and installed GNUnet and its' dependencies. | ||
3627 | Before you start a GNUnet peer, you may want to create a configuration | ||
3628 | file using gnunet-setup (but you do not have to). | ||
3629 | Sane defaults should exist in your | ||
3630 | @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice | ||
3631 | you could simply start without any configuration. If you want to | ||
3632 | configure your peer later, you need to stop it before invoking the | ||
3633 | @code{gnunet-setup} tool to customize further and to test your | ||
3634 | configuration (@code{gnunet-setup} has build-in test functions). | ||
3635 | |||
3636 | The most important option you might have to still set by hand is in | ||
3637 | [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where | ||
3638 | GNUnet should store its data. | ||
3639 | It defaults to @code{$HOME/}, which again should work for most users. | ||
3640 | Make sure that the directory specified as GNUNET_HOME is writable to | ||
3641 | the user that you will use to run GNUnet (note that you can run frontends | ||
3642 | using other users, GNUNET_HOME must only be accessible to the user used to | ||
3643 | run the background processes). | ||
3644 | |||
3645 | You will also need to make one central decision: should all of GNUnet be | ||
3646 | run under your normal UID, or do you want distinguish between system-wide | ||
3647 | (user-independent) GNUnet services and personal GNUnet services. The | ||
3648 | multi-user setup is slightly more complicated, but also more secure and | ||
3649 | generally recommended. | ||
3650 | |||
3651 | @menu | ||
3652 | * The Single-User Setup:: | ||
3653 | * The Multi-User Setup:: | ||
3654 | * Killing GNUnet services:: | ||
3655 | * Access Control for GNUnet:: | ||
3656 | @end menu | ||
3657 | |||
3658 | @node The Single-User Setup | ||
3659 | @subsection The Single-User Setup | ||
3660 | |||
3661 | For the single-user setup, you do not need to do anything special and can | ||
3662 | just start the GNUnet background processes using @code{gnunet-arm}. | ||
3663 | By default, GNUnet looks in @file{~/.config/gnunet.conf} for a | ||
3664 | configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@ | ||
3665 | @code{$XDG_CONFIG_HOME} is defined). If your configuration lives | ||
3666 | elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet | ||
3667 | commands. | ||
3668 | |||
3669 | Assuming the configuration file is called @file{~/.config/gnunet.conf}, | ||
3670 | you start your peer using the @code{gnunet-arm} command (say as user | ||
3671 | @code{gnunet}) using: | ||
3672 | |||
3673 | @example | ||
3674 | gnunet-arm -c ~/.config/gnunet.conf -s | ||
3675 | @end example | ||
3676 | |||
3677 | @noindent | ||
3678 | The "-s" option here is for "start". The command should return almost | ||
3679 | instantly. If you want to stop GNUnet, you can use: | ||
3680 | |||
3681 | @example | ||
3682 | gnunet-arm -c ~/.config/gnunet.conf -e | ||
3683 | @end example | ||
3684 | |||
3685 | @noindent | ||
3686 | The "-e" option here is for "end". | ||
3687 | |||
3688 | Note that this will only start the basic peer, no actual applications | ||
3689 | will be available. | ||
3690 | If you want to start the file-sharing service, use (after starting | ||
3691 | GNUnet): | ||
3692 | |||
3693 | @example | ||
3694 | gnunet-arm -c ~/.config/gnunet.conf -i fs | ||
3695 | @end example | ||
3696 | |||
3697 | @noindent | ||
3698 | The "-i fs" option here is for "initialize" the "fs" (file-sharing) | ||
3699 | application. You can also selectively kill only file-sharing support using | ||
3700 | |||
3701 | @example | ||
3702 | gnunet-arm -c ~/.config/gnunet.conf -k fs | ||
3703 | @end example | ||
3704 | |||
3705 | @noindent | ||
3706 | Assuming that you want certain services (like file-sharing) to be always | ||
3707 | automatically started whenever you start GNUnet, you can activate them by | ||
3708 | setting "IMMEDIATE_START=YES" in the respective section of the configuration | ||
3709 | file (for example, "[fs]"). Then GNUnet with file-sharing support would | ||
3710 | be started whenever you@ enter: | ||
3711 | |||
3712 | @example | ||
3713 | gnunet-arm -c ~/.config/gnunet.conf -s | ||
3714 | @end example | ||
3715 | |||
3716 | @noindent | ||
3717 | Alternatively, you can combine the two options: | ||
3718 | |||
3719 | @example | ||
3720 | gnunet-arm -c ~/.config/gnunet.conf -s -i fs | ||
3721 | @end example | ||
3722 | |||
3723 | @noindent | ||
3724 | Using @code{gnunet-arm} is also the preferred method for initializing | ||
3725 | GNUnet from @code{init}. | ||
3726 | |||
3727 | Finally, you should edit your @code{crontab} (using the @code{crontab} | ||
3728 | command) and insert a line@ | ||
3729 | |||
3730 | @example | ||
3731 | @@reboot gnunet-arm -c ~/.config/gnunet.conf -s | ||
3732 | @end example | ||
3733 | |||
3734 | to automatically start your peer whenever your system boots. | ||
3735 | |||
3736 | @node The Multi-User Setup | ||
3737 | @subsection The Multi-User Setup | ||
3738 | |||
3739 | This requires you to create a user @code{gnunet} and an additional group | ||
3740 | @code{gnunetdns}, prior to running @code{make install} during | ||
3741 | installation. | ||
3742 | Then, you create a configuration file @file{/etc/gnunet.conf} which should | ||
3743 | contain the lines:@ | ||
3744 | |||
3745 | @example | ||
3746 | [arm] | ||
3747 | START_SYSTEM_SERVICES = YES | ||
3748 | START_USER_SERVICES = NO | ||
3749 | @end example | ||
3750 | |||
3751 | @noindent | ||
3752 | Then, perform the same steps to run GNUnet as in the per-user | ||
3753 | configuration, except as user @code{gnunet} (including the | ||
3754 | @code{crontab} installation). | ||
3755 | You may also want to run @code{gnunet-setup} to configure your peer | ||
3756 | (databases, etc.). | ||
3757 | Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you | ||
3758 | run @code{gnunet-setup} as user @code{gnunet}, you might need to change | ||
3759 | permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can | ||
3760 | write to the file (during setup). | ||
3761 | |||
3762 | Afterwards, you need to perform another setup step for each normal user | ||
3763 | account from which you want to access GNUnet. First, grant the normal user | ||
3764 | (@code{$USER}) permission to the group gnunet: | ||
3765 | |||
3766 | @example | ||
3767 | # adduser $USER gnunet | ||
3768 | @end example | ||
3769 | |||
3770 | @noindent | ||
3771 | Then, create a configuration file in @file{~/.config/gnunet.conf} for the | ||
3772 | $USER with the lines: | ||
3773 | |||
3774 | @example | ||
3775 | [arm] | ||
3776 | START_SYSTEM_SERVICES = NO | ||
3777 | START_USER_SERVICES = YES | ||
3778 | @end example | ||
3779 | |||
3780 | @noindent | ||
3781 | This will ensure that @code{gnunet-arm} when started by the normal user | ||
3782 | will only run services that are per-user, and otherwise rely on the | ||
3783 | system-wide services. | ||
3784 | Note that the normal user may run gnunet-setup, but the | ||
3785 | configuration would be ineffective as the system-wide services will use | ||
3786 | @file{/etc/gnunet.conf} and ignore options set by individual users. | ||
3787 | |||
3788 | Again, each user should then start the peer using | ||
3789 | @file{gnunet-arm -s} --- and strongly consider adding logic to start | ||
3790 | the peer automatically to their crontab. | ||
3791 | |||
3792 | Afterwards, you should see two (or more, if you have more than one USER) | ||
3793 | @code{gnunet-service-arm} processes running in your system. | ||
3794 | |||
3795 | @node Killing GNUnet services | ||
3796 | @subsection Killing GNUnet services | ||
3797 | |||
3798 | It is not necessary to stop GNUnet services explicitly when shutting | ||
3799 | down your computer. | ||
3800 | |||
3801 | It should be noted that manually killing "most" of the | ||
3802 | @code{gnunet-service} processes is generally not a successful method for | ||
3803 | stopping a peer (since @code{gnunet-service-arm} will instantly restart | ||
3804 | them). The best way to explicitly stop a peer is using | ||
3805 | @code{gnunet-arm -e}; note that the per-user services may need to be | ||
3806 | terminated before the system-wide services will terminate normally. | ||
3807 | |||
3808 | @node Access Control for GNUnet | ||
3809 | @subsection Access Control for GNUnet | ||
3810 | |||
3811 | This chapter documents how we plan to make access control work within the | ||
3812 | GNUnet system for a typical peer. It should be read as a best-practice | ||
3813 | installation guide for advanced users and builders of binary | ||
3814 | distributions. The recommendations in this guide apply to POSIX-systems | ||
3815 | with full support for UNIX domain sockets only. | ||
3816 | |||
3817 | Note that this is an advanced topic. The discussion presumes a very good | ||
3818 | understanding of users, groups and file permissions. Normal users on | ||
3819 | hosts with just a single user can just install GNUnet under their own | ||
3820 | account (and possibly allow the installer to use SUDO to grant additional | ||
3821 | permissions for special GNUnet tools that need additional rights). | ||
3822 | The discussion below largely applies to installations where multiple users | ||
3823 | share a system and to installations where the best possible security is | ||
3824 | paramount. | ||
3825 | |||
3826 | A typical GNUnet system consists of components that fall into four | ||
3827 | categories: | ||
3828 | |||
3829 | @table @asis | ||
3830 | |||
3831 | @item User interfaces | ||
3832 | User interfaces are not security sensitive and are supposed to be run and | ||
3833 | used by normal system users. | ||
3834 | The GTK GUIs and most command-line programs fall into this category. | ||
3835 | Some command-line tools (like gnunet-transport) should be excluded as they | ||
3836 | offer low-level access that normal users should not need. | ||
3837 | @item System services and support tools | ||
3838 | System services should always run and offer services that can then be | ||
3839 | accessed by the normal users. | ||
3840 | System services do not require special permissions, but as they are not | ||
3841 | specific to a particular user, they probably should not run as a | ||
3842 | particular user. Also, there should typically only be one GNUnet peer per | ||
3843 | host. System services include the gnunet-service and gnunet-daemon | ||
3844 | programs; support tools include command-line programs such as gnunet-arm. | ||
3845 | @item Priviledged helpers | ||
3846 | Some GNUnet components require root rights to open raw sockets or perform | ||
3847 | other special operations. These gnunet-helper binaries are typically | ||
3848 | installed SUID and run from services or daemons. | ||
3849 | @item Critical services | ||
3850 | Some GNUnet services (such as the DNS service) can manipulate the service | ||
3851 | in deep and possibly highly security sensitive ways. For example, the DNS | ||
3852 | service can be used to intercept and alter any DNS query originating from | ||
3853 | the local machine. Access to the APIs of these critical services and their | ||
3854 | priviledged helpers must be tightly controlled. | ||
3855 | @end table | ||
3856 | |||
3857 | @c FIXME: The titles of these chapters are too long in the index. | ||
3858 | |||
3859 | @menu | ||
3860 | * Recommendation - Disable access to services via TCP:: | ||
3861 | * Recommendation - Run most services as system user "gnunet":: | ||
3862 | * Recommendation - Control access to services using group "gnunet":: | ||
3863 | * Recommendation - Limit access to certain SUID binaries by group "gnunet":: | ||
3864 | * Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns":: | ||
3865 | * Differences between "make install" and these recommendations:: | ||
3866 | @end menu | ||
3867 | |||
3868 | @node Recommendation - Disable access to services via TCP | ||
3869 | @subsubsection Recommendation - Disable access to services via TCP | ||
3870 | |||
3871 | GNUnet services allow two types of access: via TCP socket or via UNIX | ||
3872 | domain socket. | ||
3873 | If the service is available via TCP, access control can only be | ||
3874 | implemented by restricting connections to a particular range of IP | ||
3875 | addresses. | ||
3876 | This is acceptable for non-critical services that are supposed to be | ||
3877 | available to all users on the local system or local network. | ||
3878 | However, as TCP is generally less efficient and it is rarely the case | ||
3879 | that a single GNUnet peer is supposed to serve an entire local network, | ||
3880 | the default configuration should disable TCP access to all GNUnet | ||
3881 | services on systems with support for UNIX domain sockets. | ||
3882 | As of GNUnet 0.9.2, configuration files with TCP access disabled should be | ||
3883 | generated by default. Users can re-enable TCP access to particular | ||
3884 | services simply by specifying a non-zero port number in the section of | ||
3885 | the respective service. | ||
3886 | |||
3887 | |||
3888 | @node Recommendation - Run most services as system user "gnunet" | ||
3889 | @subsubsection Recommendation - Run most services as system user "gnunet" | ||
3890 | |||
3891 | GNUnet's main services should be run as a separate user "gnunet" in a | ||
3892 | special group "gnunet". | ||
3893 | The user "gnunet" should start the peer using "gnunet-arm -s" during | ||
3894 | system startup. The home directory for this user should be | ||
3895 | @file{/var/lib/gnunet} and the configuration file should be | ||
3896 | @file{/etc/gnunet.conf}. | ||
3897 | Only the @code{gnunet} user should have the right to access | ||
3898 | @file{/var/lib/gnunet} (@emph{mode: 700}). | ||
3899 | |||
3900 | @node Recommendation - Control access to services using group "gnunet" | ||
3901 | @subsubsection Recommendation - Control access to services using group "gnunet" | ||
3902 | |||
3903 | Users that should be allowed to use the GNUnet peer should be added to the | ||
3904 | group "gnunet". Using GNUnet's access control mechanism for UNIX domain | ||
3905 | sockets, those services that are considered useful to ordinary users | ||
3906 | should be made available by setting "UNIX_MATCH_GID=YES" for those | ||
3907 | services. | ||
3908 | Again, as shipped, GNUnet provides reasonable defaults. | ||
3909 | Permissions to access the transport and core subsystems might additionally | ||
3910 | be granted without necessarily causing security concerns. | ||
3911 | Some services, such as DNS, must NOT be made accessible to the "gnunet" | ||
3912 | group (and should thus only be accessible to the "gnunet" user and | ||
3913 | services running with this UID). | ||
3914 | |||
3915 | @node Recommendation - Limit access to certain SUID binaries by group "gnunet" | ||
3916 | @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet" | ||
3917 | |||
3918 | Most of GNUnet's SUID binaries should be safe even if executed by normal | ||
3919 | users. However, it is possible to reduce the risk a little bit more by | ||
3920 | making these binaries owned by the group "gnunet" and restricting their | ||
3921 | execution to user of the group "gnunet" as well (4750). | ||
3922 | |||
3923 | @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | ||
3924 | @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | ||
3925 | |||
3926 | A special group "gnunetdns" should be created for controlling access to | ||
3927 | the "gnunet-helper-dns". | ||
3928 | The binary should then be owned by root and be in group "gnunetdns" and | ||
3929 | be installed SUID and only be group-executable (2750). | ||
3930 | @b{Note that the group "gnunetdns" should have no users in it at all, | ||
3931 | ever.} | ||
3932 | The "gnunet-service-dns" program should be executed by user "gnunet" (via | ||
3933 | gnunet-service-arm) with the binary owned by the user "root" and the group | ||
3934 | "gnunetdns" and be SGID (2700). This way, @strong{only} | ||
3935 | "gnunet-service-dns" can change its group to "gnunetdns" and execute the | ||
3936 | helper, and the helper can then run as root (as per SUID). | ||
3937 | Access to the API offered by "gnunet-service-dns" is in turn restricted | ||
3938 | to the user "gnunet" (not the group!), which means that only | ||
3939 | "benign" services can manipulate DNS queries using "gnunet-service-dns". | ||
3940 | |||
3941 | @node Differences between "make install" and these recommendations | ||
3942 | @subsubsection Differences between "make install" and these recommendations | ||
3943 | |||
3944 | The current build system does not set all permissions automatically based | ||
3945 | on the recommendations above. In particular, it does not use the group | ||
3946 | "gnunet" at all (so setting gnunet-helpers other than the | ||
3947 | gnunet-helper-dns to be owned by group "gnunet" must be done manually). | ||
3948 | Furthermore, 'make install' will silently fail to set the DNS binaries to | ||
3949 | be owned by group "gnunetdns" unless that group already exists (!). | ||
3950 | An alternative name for the "gnunetdns" group can be specified using the | ||
3951 | @code{--with-gnunetdns=GRPNAME} configure option. | ||
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.texi b/doc/documentation/gnunet.texi index cd2f04399..c1905e899 100644 --- a/doc/documentation/gnunet.texi +++ b/doc/documentation/gnunet.texi | |||
@@ -82,13 +82,16 @@ This document is the Reference Manual for GNUnet version @value{VERSION}. | |||
82 | 82 | ||
83 | * Preface:: Chapter 0 | 83 | * Preface:: Chapter 0 |
84 | * Philosophy:: About GNUnet | 84 | * Philosophy:: About GNUnet |
85 | * Key Concepts:: Key concepts of GNUnet | ||
85 | @c * Vocabulary:: Vocabulary | 86 | @c * Vocabulary:: Vocabulary |
87 | * Installing GNUnet:: Installing GNUnet | ||
86 | * Using GNUnet:: Using GNUnet | 88 | * Using GNUnet:: Using GNUnet |
87 | @c * Configuration Handbook:: Configuring GNUnet | 89 | @c * Configuration Handbook:: Configuring GNUnet |
88 | * GNUnet Contributors Handbook:: Contributing to GNUnet | 90 | * GNUnet Contributors Handbook:: Contributing to GNUnet |
89 | * GNUnet Developer Handbook:: Developing GNUnet | 91 | * GNUnet Developer Handbook:: Developing GNUnet |
90 | * GNU Free Documentation License:: The license of this manual | 92 | * GNU Free Documentation License:: The license of this manual |
91 | * GNU General Public License:: The license of this manual | 93 | * GNU General Public License:: |
94 | * GNU Affero General Public License:: | ||
92 | * Concept Index:: Concepts | 95 | * Concept Index:: Concepts |
93 | * Programming Index:: Data types, functions, and variables | 96 | * Programming Index:: Data types, functions, and variables |
94 | 97 | ||
@@ -104,11 +107,12 @@ Preface | |||
104 | 107 | ||
105 | Philosophy | 108 | Philosophy |
106 | 109 | ||
107 | * Design Goals:: | 110 | * Design Principles:: |
108 | * Security and Privacy:: | 111 | * Privacy and Anonymity:: |
109 | * Versatility:: | ||
110 | * Practicality:: | 112 | * Practicality:: |
111 | * Key Concepts:: | 113 | |
114 | Key Concepts | ||
115 | |||
112 | * Authentication:: | 116 | * Authentication:: |
113 | * Accounting to Encourage Resource Sharing:: | 117 | * Accounting to Encourage Resource Sharing:: |
114 | * Confidentiality:: | 118 | * Confidentiality:: |
@@ -120,18 +124,17 @@ Philosophy | |||
120 | * Backup of Identities and Egos:: | 124 | * Backup of Identities and Egos:: |
121 | * Revocation:: | 125 | * Revocation:: |
122 | 126 | ||
127 | Installing GNUnet | ||
128 | |||
123 | Using GNUnet | 129 | Using GNUnet |
124 | 130 | ||
125 | * Checking the Installation:: | 131 | * Start and stop GNUnet:: |
126 | * First steps - File-sharing:: | ||
127 | * First steps - Using the GNU Name System:: | 132 | * First steps - Using the GNU Name System:: |
128 | * First steps - Using GNUnet Conversation:: | 133 | * First steps - Using GNUnet Conversation:: |
129 | * First steps - Using the GNUnet VPN:: | 134 | * First steps - Using the GNUnet VPN:: |
130 | * File-sharing:: | 135 | * File-sharing:: |
131 | * The GNU Name System:: | 136 | * The GNU Name System:: |
132 | * Using the Virtual Public Network:: | 137 | * Using the Virtual Public Network:: |
133 | * The graphical configuration interface:: | ||
134 | * How to start and stop a GNUnet peer:: | ||
135 | 138 | ||
136 | GNUnet Contributors Handbook | 139 | GNUnet Contributors Handbook |
137 | 140 | ||
@@ -193,6 +196,14 @@ GNUnet Developer Handbook | |||
193 | @c ********************************************************************* | 196 | @c ********************************************************************* |
194 | 197 | ||
195 | @c ********************************************************************* | 198 | @c ********************************************************************* |
199 | @include chapters/keyconcepts.texi | ||
200 | @c ********************************************************************* | ||
201 | |||
202 | @c ********************************************************************* | ||
203 | @include chapters/installation.texi | ||
204 | @c ********************************************************************* | ||
205 | |||
206 | @c ********************************************************************* | ||
196 | @include chapters/user.texi | 207 | @include chapters/user.texi |
197 | @c ********************************************************************* | 208 | @c ********************************************************************* |
198 | 209 | ||
@@ -217,6 +228,12 @@ GNUnet Developer Handbook | |||
217 | @include gpl-3.0.texi | 228 | @include gpl-3.0.texi |
218 | 229 | ||
219 | @c ********************************************************************* | 230 | @c ********************************************************************* |
231 | @node GNU Affero General Public License | ||
232 | @appendix GNU Affero General Public License | ||
233 | @cindex license, GNU Affero General Public License | ||
234 | @include agpl-3.0.texi | ||
235 | |||
236 | @c ********************************************************************* | ||
220 | @node Concept Index | 237 | @node Concept Index |
221 | @unnumbered Concept Index | 238 | @unnumbered Concept Index |
222 | @printindex cp | 239 | @printindex cp |
diff --git a/src/cadet/cadet_api.c b/src/cadet/cadet_api.c index b019424f9..319279110 100644 --- a/src/cadet/cadet_api.c +++ b/src/cadet/cadet_api.c | |||
@@ -357,67 +357,52 @@ reconnect (struct GNUNET_CADET_Handle *h); | |||
357 | 357 | ||
358 | 358 | ||
359 | /** | 359 | /** |
360 | * Reconnect callback: tries to reconnect again after a failer previous | 360 | * Function called during #reconnect_cbk() to (re)open |
361 | * reconnecttion | 361 | * all ports that are still open. |
362 | * | ||
363 | * @param cls closure (cadet handle) | ||
364 | */ | ||
365 | static void | ||
366 | reconnect_cbk (void *cls) | ||
367 | { | ||
368 | struct GNUNET_CADET_Handle *h = cls; | ||
369 | |||
370 | h->reconnect_task = NULL; | ||
371 | reconnect (h); | ||
372 | } | ||
373 | |||
374 | |||
375 | /** | ||
376 | * Function called during #reconnect() to destroy | ||
377 | * all channels that are still open. | ||
378 | * | 362 | * |
379 | * @param cls the `struct GNUNET_CADET_Handle` | 363 | * @param cls the `struct GNUNET_CADET_Handle` |
380 | * @param cid chanenl ID | 364 | * @param id port ID |
381 | * @param value a `struct GNUNET_CADET_Channel` to destroy | 365 | * @param value a `struct GNUNET_CADET_Channel` to open |
382 | * @return #GNUNET_OK (continue to iterate) | 366 | * @return #GNUNET_OK (continue to iterate) |
383 | */ | 367 | */ |
384 | static int | 368 | static int |
385 | destroy_channel_on_reconnect_cb (void *cls, | 369 | open_port_cb (void *cls, |
386 | uint32_t cid, | 370 | const struct GNUNET_HashCode *id, |
387 | void *value) | 371 | void *value) |
388 | { | 372 | { |
389 | /* struct GNUNET_CADET_Handle *handle = cls; */ | 373 | struct GNUNET_CADET_Handle *h = cls; |
390 | struct GNUNET_CADET_Channel *ch = value; | 374 | struct GNUNET_CADET_Port *port = value; |
375 | struct GNUNET_CADET_PortMessage *msg; | ||
376 | struct GNUNET_MQ_Envelope *env; | ||
391 | 377 | ||
392 | GNUNET_log (GNUNET_ERROR_TYPE_INFO, | 378 | (void) id; |
393 | "Destroying channel due to reconnect\n"); | 379 | env = GNUNET_MQ_msg (msg, |
394 | destroy_channel (ch); | 380 | GNUNET_MESSAGE_TYPE_CADET_LOCAL_PORT_OPEN); |
381 | msg->port = port->id; | ||
382 | GNUNET_MQ_send (h->mq, | ||
383 | env); | ||
395 | return GNUNET_OK; | 384 | return GNUNET_OK; |
396 | } | 385 | } |
397 | 386 | ||
398 | 387 | ||
399 | /** | 388 | /** |
400 | * Reconnect to the service, retransmit all infomation to try to restore the | 389 | * Reconnect callback: tries to reconnect again after a failer previous |
401 | * original state. | 390 | * reconnecttion |
402 | * | ||
403 | * @param h handle to the cadet | ||
404 | * | 391 | * |
405 | * @return #GNUNET_YES in case of sucess, #GNUNET_NO otherwise (service down...) | 392 | * @param cls closure (cadet handle) |
406 | */ | 393 | */ |
407 | static void | 394 | static void |
408 | schedule_reconnect (struct GNUNET_CADET_Handle *h) | 395 | reconnect_cbk (void *cls) |
409 | { | 396 | { |
410 | if (NULL != h->reconnect_task) | 397 | struct GNUNET_CADET_Handle *h = cls; |
411 | return; | 398 | |
412 | GNUNET_CONTAINER_multihashmap32_iterate (h->channels, | 399 | h->reconnect_task = NULL; |
413 | &destroy_channel_on_reconnect_cb, | ||
414 | h); | ||
415 | h->reconnect_task | ||
416 | = GNUNET_SCHEDULER_add_delayed (h->reconnect_time, | ||
417 | &reconnect_cbk, | ||
418 | h); | ||
419 | h->reconnect_time | 400 | h->reconnect_time |
420 | = GNUNET_TIME_STD_BACKOFF (h->reconnect_time); | 401 | = GNUNET_TIME_STD_BACKOFF (h->reconnect_time); |
402 | reconnect (h); | ||
403 | GNUNET_CONTAINER_multihashmap_iterate (h->ports, | ||
404 | &open_port_cb, | ||
405 | h); | ||
421 | } | 406 | } |
422 | 407 | ||
423 | 408 | ||
@@ -555,15 +540,16 @@ cadet_mq_error_handler (void *cls, | |||
555 | { | 540 | { |
556 | struct GNUNET_CADET_Channel *ch = cls; | 541 | struct GNUNET_CADET_Channel *ch = cls; |
557 | 542 | ||
558 | GNUNET_break (0); | ||
559 | if (GNUNET_MQ_ERROR_NO_MATCH == error) | 543 | if (GNUNET_MQ_ERROR_NO_MATCH == error) |
560 | { | 544 | { |
561 | /* Got a message we did not understand, still try to continue! */ | 545 | /* Got a message we did not understand, still try to continue! */ |
546 | GNUNET_break_op (0); | ||
562 | GNUNET_CADET_receive_done (ch); | 547 | GNUNET_CADET_receive_done (ch); |
563 | } | 548 | } |
564 | else | 549 | else |
565 | { | 550 | { |
566 | schedule_reconnect (ch->cadet); | 551 | GNUNET_break (0); |
552 | GNUNET_CADET_channel_destroy (ch); | ||
567 | } | 553 | } |
568 | } | 554 | } |
569 | 555 | ||
@@ -581,6 +567,7 @@ cadet_mq_cancel_impl (struct GNUNET_MQ_Handle *mq, | |||
581 | { | 567 | { |
582 | struct GNUNET_CADET_Channel *ch = impl_state; | 568 | struct GNUNET_CADET_Channel *ch = impl_state; |
583 | 569 | ||
570 | (void) mq; | ||
584 | GNUNET_assert (NULL != ch->pending_env); | 571 | GNUNET_assert (NULL != ch->pending_env); |
585 | GNUNET_MQ_discard (ch->pending_env); | 572 | GNUNET_MQ_discard (ch->pending_env); |
586 | ch->pending_env = NULL; | 573 | ch->pending_env = NULL; |
@@ -709,6 +696,7 @@ check_local_data (void *cls, | |||
709 | { | 696 | { |
710 | uint16_t size; | 697 | uint16_t size; |
711 | 698 | ||
699 | (void) cls; | ||
712 | size = ntohs (message->header.size); | 700 | size = ntohs (message->header.size); |
713 | if (sizeof (*message) + sizeof (struct GNUNET_MessageHeader) > size) | 701 | if (sizeof (*message) + sizeof (struct GNUNET_MessageHeader) > size) |
714 | { | 702 | { |
@@ -806,6 +794,32 @@ handle_local_ack (void *cls, | |||
806 | 794 | ||
807 | 795 | ||
808 | /** | 796 | /** |
797 | * Function called during #GNUNET_CADET_disconnect() to destroy | ||
798 | * all channels that are still open. | ||
799 | * | ||
800 | * @param cls the `struct GNUNET_CADET_Handle` | ||
801 | * @param cid chanenl ID | ||
802 | * @param value a `struct GNUNET_CADET_Channel` to destroy | ||
803 | * @return #GNUNET_OK (continue to iterate) | ||
804 | */ | ||
805 | static int | ||
806 | destroy_channel_cb (void *cls, | ||
807 | uint32_t cid, | ||
808 | void *value) | ||
809 | { | ||
810 | /* struct GNUNET_CADET_Handle *handle = cls; */ | ||
811 | struct GNUNET_CADET_Channel *ch = value; | ||
812 | |||
813 | (void) cls; | ||
814 | (void) cid; | ||
815 | GNUNET_log (GNUNET_ERROR_TYPE_INFO, | ||
816 | "Destroying channel due to GNUNET_CADET_disconnect()\n"); | ||
817 | destroy_channel (ch); | ||
818 | return GNUNET_OK; | ||
819 | } | ||
820 | |||
821 | |||
822 | /** | ||
809 | * Generic error handler, called with the appropriate error code and | 823 | * Generic error handler, called with the appropriate error code and |
810 | * the same closure specified at the creation of the message queue. | 824 | * the same closure specified at the creation of the message queue. |
811 | * Not every message queue implementation supports an error handler. | 825 | * Not every message queue implementation supports an error handler. |
@@ -822,9 +836,14 @@ handle_mq_error (void *cls, | |||
822 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, | 836 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, |
823 | "MQ ERROR: %u\n", | 837 | "MQ ERROR: %u\n", |
824 | error); | 838 | error); |
839 | GNUNET_CONTAINER_multihashmap32_iterate (h->channels, | ||
840 | &destroy_channel_cb, | ||
841 | h); | ||
825 | GNUNET_MQ_destroy (h->mq); | 842 | GNUNET_MQ_destroy (h->mq); |
826 | h->mq = NULL; | 843 | h->mq = NULL; |
827 | reconnect (h); | 844 | h->reconnect_task = GNUNET_SCHEDULER_add_delayed (h->reconnect_time, |
845 | &reconnect_cbk, | ||
846 | h); | ||
828 | } | 847 | } |
829 | 848 | ||
830 | 849 | ||
@@ -842,6 +861,7 @@ check_get_peers (void *cls, | |||
842 | { | 861 | { |
843 | size_t esize; | 862 | size_t esize; |
844 | 863 | ||
864 | (void) cls; | ||
845 | esize = ntohs (message->size); | 865 | esize = ntohs (message->size); |
846 | if (sizeof (struct GNUNET_CADET_LocalInfoPeer) == esize) | 866 | if (sizeof (struct GNUNET_CADET_LocalInfoPeer) == esize) |
847 | return GNUNET_OK; | 867 | return GNUNET_OK; |
@@ -895,11 +915,9 @@ check_get_peer (void *cls, | |||
895 | const struct GNUNET_CADET_LocalInfoPeer *message) | 915 | const struct GNUNET_CADET_LocalInfoPeer *message) |
896 | { | 916 | { |
897 | size_t msize = sizeof (struct GNUNET_CADET_LocalInfoPeer); | 917 | size_t msize = sizeof (struct GNUNET_CADET_LocalInfoPeer); |
898 | const struct GNUNET_PeerIdentity *paths_array; | ||
899 | size_t esize; | 918 | size_t esize; |
900 | unsigned int epaths; | ||
901 | unsigned int peers; | ||
902 | 919 | ||
920 | (void) cls; | ||
903 | esize = ntohs (message->header.size); | 921 | esize = ntohs (message->header.size); |
904 | if (esize < msize) | 922 | if (esize < msize) |
905 | { | 923 | { |
@@ -911,10 +929,6 @@ check_get_peer (void *cls, | |||
911 | GNUNET_break (0); | 929 | GNUNET_break (0); |
912 | return GNUNET_SYSERR; | 930 | return GNUNET_SYSERR; |
913 | } | 931 | } |
914 | peers = (esize - msize) / sizeof (struct GNUNET_PeerIdentity); | ||
915 | epaths = ntohs (message->paths); | ||
916 | paths_array = (const struct GNUNET_PeerIdentity *) &message[1]; | ||
917 | |||
918 | return GNUNET_OK; | 932 | return GNUNET_OK; |
919 | } | 933 | } |
920 | 934 | ||
@@ -1166,38 +1180,6 @@ reconnect (struct GNUNET_CADET_Handle *h) | |||
1166 | handlers, | 1180 | handlers, |
1167 | &handle_mq_error, | 1181 | &handle_mq_error, |
1168 | h); | 1182 | h); |
1169 | if (NULL == h->mq) | ||
1170 | { | ||
1171 | schedule_reconnect (h); | ||
1172 | return; | ||
1173 | } | ||
1174 | h->reconnect_time = GNUNET_TIME_UNIT_MILLISECONDS; | ||
1175 | } | ||
1176 | |||
1177 | |||
1178 | /** | ||
1179 | * Function called during #GNUNET_CADET_disconnect() to destroy | ||
1180 | * all channels that are still open. | ||
1181 | * | ||
1182 | * @param cls the `struct GNUNET_CADET_Handle` | ||
1183 | * @param cid chanenl ID | ||
1184 | * @param value a `struct GNUNET_CADET_Channel` to destroy | ||
1185 | * @return #GNUNET_OK (continue to iterate) | ||
1186 | */ | ||
1187 | static int | ||
1188 | destroy_channel_cb (void *cls, | ||
1189 | uint32_t cid, | ||
1190 | void *value) | ||
1191 | { | ||
1192 | /* struct GNUNET_CADET_Handle *handle = cls; */ | ||
1193 | struct GNUNET_CADET_Channel *ch = value; | ||
1194 | |||
1195 | (void) cls; | ||
1196 | (void) cid; | ||
1197 | GNUNET_log (GNUNET_ERROR_TYPE_INFO, | ||
1198 | "Destroying channel due to GNUNET_CADET_disconnect()\n"); | ||
1199 | destroy_channel (ch); | ||
1200 | return GNUNET_OK; | ||
1201 | } | 1183 | } |
1202 | 1184 | ||
1203 | 1185 | ||
@@ -1219,6 +1201,7 @@ destroy_port_cb (void *cls, | |||
1219 | struct GNUNET_CADET_Port *port = value; | 1201 | struct GNUNET_CADET_Port *port = value; |
1220 | 1202 | ||
1221 | (void) cls; | 1203 | (void) cls; |
1204 | (void) id; | ||
1222 | /* This is a warning, the app should have cleanly closed all open ports */ | 1205 | /* This is a warning, the app should have cleanly closed all open ports */ |
1223 | GNUNET_break (0); | 1206 | GNUNET_break (0); |
1224 | GNUNET_CADET_close_port (port); | 1207 | GNUNET_CADET_close_port (port); |
@@ -1270,18 +1253,21 @@ GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle) | |||
1270 | void | 1253 | void |
1271 | GNUNET_CADET_close_port (struct GNUNET_CADET_Port *p) | 1254 | GNUNET_CADET_close_port (struct GNUNET_CADET_Port *p) |
1272 | { | 1255 | { |
1273 | struct GNUNET_CADET_PortMessage *msg; | ||
1274 | struct GNUNET_MQ_Envelope *env; | ||
1275 | |||
1276 | GNUNET_assert (GNUNET_YES == | 1256 | GNUNET_assert (GNUNET_YES == |
1277 | GNUNET_CONTAINER_multihashmap_remove (p->cadet->ports, | 1257 | GNUNET_CONTAINER_multihashmap_remove (p->cadet->ports, |
1278 | &p->id, | 1258 | &p->id, |
1279 | p)); | 1259 | p)); |
1280 | env = GNUNET_MQ_msg (msg, | 1260 | if (NULL != p->cadet->mq) |
1281 | GNUNET_MESSAGE_TYPE_CADET_LOCAL_PORT_CLOSE); | 1261 | { |
1282 | msg->port = p->id; | 1262 | struct GNUNET_CADET_PortMessage *msg; |
1283 | GNUNET_MQ_send (p->cadet->mq, | 1263 | struct GNUNET_MQ_Envelope *env; |
1284 | env); | 1264 | |
1265 | env = GNUNET_MQ_msg (msg, | ||
1266 | GNUNET_MESSAGE_TYPE_CADET_LOCAL_PORT_CLOSE); | ||
1267 | msg->port = p->id; | ||
1268 | GNUNET_MQ_send (p->cadet->mq, | ||
1269 | env); | ||
1270 | } | ||
1285 | GNUNET_free_non_null (p->handlers); | 1271 | GNUNET_free_non_null (p->handlers); |
1286 | GNUNET_free (p); | 1272 | GNUNET_free (p); |
1287 | } | 1273 | } |
@@ -1633,9 +1619,6 @@ GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg) | |||
1633 | return NULL; | 1619 | return NULL; |
1634 | } | 1620 | } |
1635 | h->next_ccn.channel_of_client = htonl (GNUNET_CADET_LOCAL_CHANNEL_ID_CLI); | 1621 | h->next_ccn.channel_of_client = htonl (GNUNET_CADET_LOCAL_CHANNEL_ID_CLI); |
1636 | h->reconnect_time = GNUNET_TIME_UNIT_MILLISECONDS; | ||
1637 | h->reconnect_task = NULL; | ||
1638 | |||
1639 | return h; | 1622 | return h; |
1640 | } | 1623 | } |
1641 | 1624 | ||
@@ -1661,8 +1644,6 @@ GNUNET_CADET_open_port (struct GNUNET_CADET_Handle *h, | |||
1661 | GNUNET_CADET_DisconnectEventHandler disconnects, | 1644 | GNUNET_CADET_DisconnectEventHandler disconnects, |
1662 | const struct GNUNET_MQ_MessageHandler *handlers) | 1645 | const struct GNUNET_MQ_MessageHandler *handlers) |
1663 | { | 1646 | { |
1664 | struct GNUNET_CADET_PortMessage *msg; | ||
1665 | struct GNUNET_MQ_Envelope *env; | ||
1666 | struct GNUNET_CADET_Port *p; | 1647 | struct GNUNET_CADET_Port *p; |
1667 | 1648 | ||
1668 | GNUNET_assert (NULL != connects); | 1649 | GNUNET_assert (NULL != connects); |
@@ -1688,13 +1669,11 @@ GNUNET_CADET_open_port (struct GNUNET_CADET_Handle *h, | |||
1688 | p->window_changes = window_changes; | 1669 | p->window_changes = window_changes; |
1689 | p->disconnects = disconnects; | 1670 | p->disconnects = disconnects; |
1690 | p->handlers = GNUNET_MQ_copy_handlers (handlers); | 1671 | p->handlers = GNUNET_MQ_copy_handlers (handlers); |
1691 | 1672 | ||
1692 | 1673 | GNUNET_assert (GNUNET_OK == | |
1693 | env = GNUNET_MQ_msg (msg, | 1674 | open_port_cb (h, |
1694 | GNUNET_MESSAGE_TYPE_CADET_LOCAL_PORT_OPEN); | 1675 | &p->id, |
1695 | msg->port = p->id; | 1676 | p)); |
1696 | GNUNET_MQ_send (h->mq, | ||
1697 | env); | ||
1698 | return p; | 1677 | return p; |
1699 | } | 1678 | } |
1700 | 1679 | ||
@@ -1753,7 +1732,8 @@ GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h, | |||
1753 | handlers, | 1732 | handlers, |
1754 | &cadet_mq_error_handler, | 1733 | &cadet_mq_error_handler, |
1755 | ch); | 1734 | ch); |
1756 | GNUNET_MQ_set_handlers_closure (ch->mq, channel_cls); | 1735 | GNUNET_MQ_set_handlers_closure (ch->mq, |
1736 | channel_cls); | ||
1757 | 1737 | ||
1758 | /* Request channel creation to service */ | 1738 | /* Request channel creation to service */ |
1759 | env = GNUNET_MQ_msg (msg, | 1739 | env = GNUNET_MQ_msg (msg, |
diff --git a/src/cadet/gnunet-cadet.c b/src/cadet/gnunet-cadet.c index b22881907..13b04b885 100644 --- a/src/cadet/gnunet-cadet.c +++ b/src/cadet/gnunet-cadet.c | |||
@@ -231,7 +231,7 @@ shutdown_task (void *cls) | |||
231 | } | 231 | } |
232 | } | 232 | } |
233 | 233 | ||
234 | void * | 234 | void |
235 | mq_cb(void *cls) | 235 | mq_cb(void *cls) |
236 | { | 236 | { |
237 | listen_stdio (); | 237 | listen_stdio (); |
@@ -577,9 +577,9 @@ peer_callback (void *cls, | |||
577 | }else{ | 577 | }else{ |
578 | p = paths; | 578 | p = paths; |
579 | FPRINTF (stdout, | 579 | FPRINTF (stdout, |
580 | "Path with offset %u: ", | 580 | "Indirekt path with offset %u: ", |
581 | offset); | 581 | offset); |
582 | for (i = 0; i < offset && NULL != p;) | 582 | for (i = 0; i <= offset && NULL != p;) |
583 | { | 583 | { |
584 | FPRINTF (stdout, | 584 | FPRINTF (stdout, |
585 | "%s ", | 585 | "%s ", |
diff --git a/src/cadet/gnunet-service-cadet.c b/src/cadet/gnunet-service-cadet.c index dd693731f..4568d2733 100644 --- a/src/cadet/gnunet-service-cadet.c +++ b/src/cadet/gnunet-service-cadet.c | |||
@@ -881,7 +881,7 @@ path_info_iterator (void *cls, | |||
881 | unsigned int path_length; | 881 | unsigned int path_length; |
882 | 882 | ||
883 | path_length = GCPP_get_length (path); | 883 | path_length = GCPP_get_length (path); |
884 | path_size = sizeof (struct GNUNET_PeerIdentity) * (path_length - 1); | 884 | path_size = sizeof (struct GNUNET_PeerIdentity) * path_length; |
885 | if (sizeof (*resp) + path_size > UINT16_MAX) | 885 | if (sizeof (*resp) + path_size > UINT16_MAX) |
886 | { | 886 | { |
887 | LOG (GNUNET_ERROR_TYPE_WARNING, | 887 | LOG (GNUNET_ERROR_TYPE_WARNING, |
@@ -902,9 +902,9 @@ path_info_iterator (void *cls, | |||
902 | /* Don't copy first peer. First peer is always the local one. Last | 902 | /* Don't copy first peer. First peer is always the local one. Last |
903 | * peer is always the destination (leave as 0, EOL). | 903 | * peer is always the destination (leave as 0, EOL). |
904 | */ | 904 | */ |
905 | for (i = 0; i < off; i++) | 905 | for (i = 0; i <= off; i++) |
906 | id[i] = *GCP_get_id (GCPP_get_peer_at_offset (path, | 906 | id[i] = *GCP_get_id (GCPP_get_peer_at_offset (path, |
907 | i + 1)); | 907 | i)); |
908 | GNUNET_MQ_send (mq, | 908 | GNUNET_MQ_send (mq, |
909 | env); | 909 | env); |
910 | return GNUNET_YES; | 910 | return GNUNET_YES; |
@@ -927,29 +927,23 @@ get_peer_info (void *cls, | |||
927 | struct CadetClient *c = cls; | 927 | struct CadetClient *c = cls; |
928 | struct GNUNET_MQ_Envelope *env; | 928 | struct GNUNET_MQ_Envelope *env; |
929 | struct GNUNET_CADET_LocalInfoPeer *msg; | 929 | struct GNUNET_CADET_LocalInfoPeer *msg; |
930 | |||
931 | 930 | ||
932 | env = GNUNET_MQ_msg (msg, | 931 | env = GNUNET_MQ_msg (msg, |
933 | GNUNET_MESSAGE_TYPE_CADET_LOCAL_INFO_PEER); | 932 | GNUNET_MESSAGE_TYPE_CADET_LOCAL_INFO_PEER); |
934 | |||
935 | msg->offset = htons(0); | 933 | msg->offset = htons(0); |
936 | msg->destination = *peer; | 934 | msg->destination = *peer; |
937 | msg->paths = htons (GCP_count_paths (p)); | 935 | msg->paths = htons (GCP_count_paths (p)); |
938 | msg->tunnel = htons (NULL != GCP_get_tunnel (p, | 936 | msg->tunnel = htons (NULL != GCP_get_tunnel (p, |
939 | GNUNET_NO)); | 937 | GNUNET_NO)); |
940 | msg->finished_with_paths = htons(0); | 938 | msg->finished_with_paths = htons(0); |
941 | |||
942 | GNUNET_MQ_send (c->mq, | 939 | GNUNET_MQ_send (c->mq, |
943 | env); | 940 | env); |
944 | 941 | GCP_iterate_indirect_paths (p, | |
945 | GCP_iterate_indirect_paths(p, | 942 | &path_info_iterator, |
946 | &path_info_iterator, | 943 | c->mq); |
947 | c->mq); | ||
948 | |||
949 | } | 944 | } |
950 | 945 | ||
951 | 946 | ||
952 | |||
953 | /** | 947 | /** |
954 | * Handler for client's SHOW_PEER request. | 948 | * Handler for client's SHOW_PEER request. |
955 | * | 949 | * |
diff --git a/src/cadet/gnunet-service-cadet_peer.c b/src/cadet/gnunet-service-cadet_peer.c index ac1ee59de..b375d51ca 100644 --- a/src/cadet/gnunet-service-cadet_peer.c +++ b/src/cadet/gnunet-service-cadet_peer.c | |||
@@ -243,16 +243,16 @@ GCP_2s (const struct CadetPeer *cp) | |||
243 | static char buf[5]; | 243 | static char buf[5]; |
244 | char *ret; | 244 | char *ret; |
245 | 245 | ||
246 | if (NULL == cp || | 246 | if ((NULL == cp) || |
247 | NULL == &cp->pid.public_key){ | 247 | (NULL == &cp->pid.public_key)) |
248 | return "NULL"; | 248 | return "NULL"; |
249 | } | 249 | |
250 | 250 | ||
251 | ret = GNUNET_CRYPTO_eddsa_public_key_to_string (&cp->pid.public_key); | 251 | ret = GNUNET_CRYPTO_eddsa_public_key_to_string (&cp->pid.public_key); |
252 | 252 | ||
253 | if (NULL == ret){ | 253 | if (NULL == ret) |
254 | return "NULL"; | 254 | return "NULL"; |
255 | } | 255 | |
256 | 256 | ||
257 | strncpy (buf, | 257 | strncpy (buf, |
258 | ret, | 258 | ret, |
@@ -1217,6 +1217,8 @@ GCP_iterate_paths (struct CadetPeer *cp, | |||
1217 | (NULL == cp->core_mq) ? "" : " including direct link"); | 1217 | (NULL == cp->core_mq) ? "" : " including direct link"); |
1218 | if (NULL != cp->core_mq) | 1218 | if (NULL != cp->core_mq) |
1219 | { | 1219 | { |
1220 | /* FIXME: this branch seems to duplicate the | ||
1221 | i=0 case below (direct link). Leave out!??? -CG */ | ||
1220 | struct CadetPeerPath *path; | 1222 | struct CadetPeerPath *path; |
1221 | 1223 | ||
1222 | path = GCPP_get_path_from_route (1, | 1224 | path = GCPP_get_path_from_route (1, |
diff --git a/src/conversation/gnunet-conversation.c b/src/conversation/gnunet-conversation.c index fad9d568e..bb4946720 100644 --- a/src/conversation/gnunet-conversation.c +++ b/src/conversation/gnunet-conversation.c | |||
@@ -264,6 +264,13 @@ phone_event_handler (void *cls, | |||
264 | switch (code) | 264 | switch (code) |
265 | { | 265 | { |
266 | case GNUNET_CONVERSATION_EC_PHONE_RING: | 266 | case GNUNET_CONVERSATION_EC_PHONE_RING: |
267 | /* | ||
268 | * FIXME: we should be playing our ringtones from contrib/sounds now! | ||
269 | * | ||
270 | ring_my_bell(); | ||
271 | * | ||
272 | * see https://gstreamer.freedesktop.org/documentation/application-development/highlevel/playback-components.html on how to play a wav using the gst framework being used here | ||
273 | */ | ||
267 | FPRINTF (stdout, | 274 | FPRINTF (stdout, |
268 | _("Incoming call from `%s'. Please /accept %u or /cancel %u the call.\n"), | 275 | _("Incoming call from `%s'. Please /accept %u or /cancel %u the call.\n"), |
269 | GNUNET_GNSRECORD_pkey_to_zkey (caller_id), | 276 | GNUNET_GNSRECORD_pkey_to_zkey (caller_id), |
diff --git a/src/include/gnunet_common.h b/src/include/gnunet_common.h index b4bf5b0aa..1b982cc15 100644 --- a/src/include/gnunet_common.h +++ b/src/include/gnunet_common.h | |||
@@ -1074,7 +1074,7 @@ GNUNET_ntoh_double (double d); | |||
1074 | * @param tsize the target size for the resulting vector, use 0 to | 1074 | * @param tsize the target size for the resulting vector, use 0 to |
1075 | * free the vector (then, arr will be NULL afterwards). | 1075 | * free the vector (then, arr will be NULL afterwards). |
1076 | */ | 1076 | */ |
1077 | #define GNUNET_array_grow(arr,size,tsize) GNUNET_xgrow_((void**)&arr, sizeof(arr[0]), &size, tsize, __FILE__, __LINE__) | 1077 | #define GNUNET_array_grow(arr,size,tsize) GNUNET_xgrow_((void**)&(arr), sizeof((arr)[0]), &size, tsize, __FILE__, __LINE__) |
1078 | 1078 | ||
1079 | /** | 1079 | /** |
1080 | * @ingroup memory | 1080 | * @ingroup memory |
@@ -1089,7 +1089,7 @@ GNUNET_ntoh_double (double d); | |||
1089 | * array size | 1089 | * array size |
1090 | * @param element the element that will be appended to the array | 1090 | * @param element the element that will be appended to the array |
1091 | */ | 1091 | */ |
1092 | #define GNUNET_array_append(arr,size,element) do { GNUNET_array_grow(arr,size,size+1); arr[size-1] = element; } while(0) | 1092 | #define GNUNET_array_append(arr,size,element) do { GNUNET_array_grow(arr,size,size+1); (arr)[size-1] = element; } while(0) |
1093 | 1093 | ||
1094 | /** | 1094 | /** |
1095 | * @ingroup memory | 1095 | * @ingroup memory |
diff --git a/src/include/gnunet_dnsparser_lib.h b/src/include/gnunet_dnsparser_lib.h index ba1392510..0fc6ac19c 100644 --- a/src/include/gnunet_dnsparser_lib.h +++ b/src/include/gnunet_dnsparser_lib.h | |||
@@ -82,6 +82,7 @@ | |||
82 | #define GNUNET_DNSPARSER_TYPE_OPENPGPKEY 61 | 82 | #define GNUNET_DNSPARSER_TYPE_OPENPGPKEY 61 |
83 | #define GNUNET_DNSPARSER_TYPE_TKEY 249 | 83 | #define GNUNET_DNSPARSER_TYPE_TKEY 249 |
84 | #define GNUNET_DNSPARSER_TYPE_TSIG 250 | 84 | #define GNUNET_DNSPARSER_TYPE_TSIG 250 |
85 | #define GNUNET_DNSPARSER_TYPE_ALL 255 | ||
85 | #define GNUNET_DNSPARSER_TYPE_URI 256 | 86 | #define GNUNET_DNSPARSER_TYPE_URI 256 |
86 | #define GNUNET_DNSPARSER_TYPE_TA 32768 | 87 | #define GNUNET_DNSPARSER_TYPE_TA 32768 |
87 | 88 | ||
@@ -840,6 +841,58 @@ GNUNET_DNSPARSER_parse_srv (const char *udp_payload, | |||
840 | size_t udp_payload_length, | 841 | size_t udp_payload_length, |
841 | size_t *off); | 842 | size_t *off); |
842 | 843 | ||
844 | /* ***************** low-level duplication API ******************** */ | ||
845 | |||
846 | /** | ||
847 | * Duplicate (deep-copy) the given DNS record | ||
848 | * | ||
849 | * @param r the record | ||
850 | * @return the newly allocated record | ||
851 | */ | ||
852 | struct GNUNET_DNSPARSER_Record * | ||
853 | GNUNET_DNSPARSER_duplicate_record (const struct GNUNET_DNSPARSER_Record *r); | ||
854 | |||
855 | |||
856 | /** | ||
857 | * Duplicate (deep-copy) the given DNS record | ||
858 | * | ||
859 | * @param r the record | ||
860 | * @return the newly allocated record | ||
861 | */ | ||
862 | struct GNUNET_DNSPARSER_SoaRecord * | ||
863 | GNUNET_DNSPARSER_duplicate_soa_record (const struct GNUNET_DNSPARSER_SoaRecord *r); | ||
864 | |||
865 | |||
866 | /** | ||
867 | * Duplicate (deep-copy) the given DNS record | ||
868 | * | ||
869 | * @param r the record | ||
870 | * @return the newly allocated record | ||
871 | */ | ||
872 | struct GNUNET_DNSPARSER_CertRecord * | ||
873 | GNUNET_DNSPARSER_duplicate_cert_record (const struct GNUNET_DNSPARSER_CertRecord *r); | ||
874 | |||
875 | |||
876 | /** | ||
877 | * Duplicate (deep-copy) the given DNS record | ||
878 | * | ||
879 | * @param r the record | ||
880 | * @return the newly allocated record | ||
881 | */ | ||
882 | struct GNUNET_DNSPARSER_MxRecord * | ||
883 | GNUNET_DNSPARSER_duplicate_mx_record (const struct GNUNET_DNSPARSER_MxRecord *r); | ||
884 | |||
885 | |||
886 | /** | ||
887 | * Duplicate (deep-copy) the given DNS record | ||
888 | * | ||
889 | * @param r the record | ||
890 | * @return the newly allocated record | ||
891 | */ | ||
892 | struct GNUNET_DNSPARSER_SrvRecord * | ||
893 | GNUNET_DNSPARSER_duplicate_srv_record (const struct GNUNET_DNSPARSER_SrvRecord *r); | ||
894 | |||
895 | |||
843 | /* ***************** low-level deallocation API ******************** */ | 896 | /* ***************** low-level deallocation API ******************** */ |
844 | 897 | ||
845 | /** | 898 | /** |
diff --git a/src/psyc/Makefile.am b/src/psyc/Makefile.am index 26db608f3..d5c797f52 100644 --- a/src/psyc/Makefile.am +++ b/src/psyc/Makefile.am | |||
@@ -48,8 +48,8 @@ gnunet_service_psyc_CFLAGS = $(AM_CFLAGS) | |||
48 | 48 | ||
49 | 49 | ||
50 | if HAVE_TESTING | 50 | if HAVE_TESTING |
51 | check_PROGRAMS = \ | 51 | #check_PROGRAMS = \ |
52 | test_psyc2 | 52 | # test_psyc2 |
53 | # test_psyc | 53 | # test_psyc |
54 | endif | 54 | endif |
55 | 55 | ||
diff --git a/src/util/.gitignore b/src/util/.gitignore index 23139a1ab..8e7093568 100644 --- a/src/util/.gitignore +++ b/src/util/.gitignore | |||
@@ -69,3 +69,4 @@ perf_crypto_hash | |||
69 | perf_crypto_symmetric | 69 | perf_crypto_symmetric |
70 | perf_crypto_rsa | 70 | perf_crypto_rsa |
71 | perf_crypto_ecc_dlog | 71 | perf_crypto_ecc_dlog |
72 | test_hexcoder test_regex test_tun | ||
diff --git a/src/util/dnsparser.c b/src/util/dnsparser.c index cce68f2ee..57d0a014c 100644 --- a/src/util/dnsparser.c +++ b/src/util/dnsparser.c | |||
@@ -759,6 +759,122 @@ GNUNET_DNSPARSER_parse (const char *udp_payload, | |||
759 | 759 | ||
760 | 760 | ||
761 | /** | 761 | /** |
762 | * Duplicate (deep-copy) the given DNS record | ||
763 | * | ||
764 | * @param r the record | ||
765 | * @return the newly allocated record | ||
766 | */ | ||
767 | struct GNUNET_DNSPARSER_Record * | ||
768 | GNUNET_DNSPARSER_duplicate_record (const struct GNUNET_DNSPARSER_Record *r) | ||
769 | { | ||
770 | struct GNUNET_DNSPARSER_Record *dup = GNUNET_memdup (r, sizeof (*r)); | ||
771 | |||
772 | dup->name = GNUNET_strdup (r->name); | ||
773 | switch (r->type) | ||
774 | { | ||
775 | case GNUNET_DNSPARSER_TYPE_NS: | ||
776 | case GNUNET_DNSPARSER_TYPE_CNAME: | ||
777 | case GNUNET_DNSPARSER_TYPE_PTR: | ||
778 | { | ||
779 | dup->data.hostname = GNUNET_strdup (r->data.hostname); | ||
780 | break; | ||
781 | } | ||
782 | case GNUNET_DNSPARSER_TYPE_SOA: | ||
783 | { | ||
784 | dup->data.soa = GNUNET_DNSPARSER_duplicate_soa_record (r->data.soa); | ||
785 | break; | ||
786 | } | ||
787 | case GNUNET_DNSPARSER_TYPE_CERT: | ||
788 | { | ||
789 | dup->data.cert = GNUNET_DNSPARSER_duplicate_cert_record (r->data.cert); | ||
790 | break; | ||
791 | } | ||
792 | case GNUNET_DNSPARSER_TYPE_MX: | ||
793 | { | ||
794 | dup->data.mx = GNUNET_DNSPARSER_duplicate_mx_record (r->data.mx); | ||
795 | break; | ||
796 | } | ||
797 | case GNUNET_DNSPARSER_TYPE_SRV: | ||
798 | { | ||
799 | dup->data.srv = GNUNET_DNSPARSER_duplicate_srv_record (r->data.srv); | ||
800 | break; | ||
801 | } | ||
802 | default: | ||
803 | { | ||
804 | dup->data.raw.data = GNUNET_memdup (r->data.raw.data, | ||
805 | r->data.raw.data_len); | ||
806 | } | ||
807 | } | ||
808 | return dup; | ||
809 | } | ||
810 | |||
811 | |||
812 | /** | ||
813 | * Duplicate (deep-copy) the given DNS record | ||
814 | * | ||
815 | * @param r the record | ||
816 | * @return the newly allocated record | ||
817 | */ | ||
818 | struct GNUNET_DNSPARSER_SoaRecord * | ||
819 | GNUNET_DNSPARSER_duplicate_soa_record (const struct GNUNET_DNSPARSER_SoaRecord *r) | ||
820 | { | ||
821 | struct GNUNET_DNSPARSER_SoaRecord *dup = GNUNET_memdup (r, sizeof (*r)); | ||
822 | |||
823 | dup->mname = GNUNET_strdup (r->mname); | ||
824 | dup->rname = GNUNET_strdup (r->rname); | ||
825 | return dup; | ||
826 | } | ||
827 | |||
828 | |||
829 | /** | ||
830 | * Duplicate (deep-copy) the given DNS record | ||
831 | * | ||
832 | * @param r the record | ||
833 | * @return the newly allocated record | ||
834 | */ | ||
835 | struct GNUNET_DNSPARSER_CertRecord * | ||
836 | GNUNET_DNSPARSER_duplicate_cert_record (const struct GNUNET_DNSPARSER_CertRecord *r) | ||
837 | { | ||
838 | struct GNUNET_DNSPARSER_CertRecord *dup = GNUNET_memdup (r, sizeof (*r)); | ||
839 | |||
840 | dup->certificate_data = GNUNET_strdup (r->certificate_data); | ||
841 | return dup; | ||
842 | } | ||
843 | |||
844 | |||
845 | /** | ||
846 | * Duplicate (deep-copy) the given DNS record | ||
847 | * | ||
848 | * @param r the record | ||
849 | * @return the newly allocated record | ||
850 | */ | ||
851 | struct GNUNET_DNSPARSER_MxRecord * | ||
852 | GNUNET_DNSPARSER_duplicate_mx_record (const struct GNUNET_DNSPARSER_MxRecord *r) | ||
853 | { | ||
854 | struct GNUNET_DNSPARSER_MxRecord *dup = GNUNET_memdup (r, sizeof (*r)); | ||
855 | |||
856 | dup->mxhost = GNUNET_strdup (r->mxhost); | ||
857 | return dup; | ||
858 | } | ||
859 | |||
860 | |||
861 | /** | ||
862 | * Duplicate (deep-copy) the given DNS record | ||
863 | * | ||
864 | * @param r the record | ||
865 | * @return the newly allocated record | ||
866 | */ | ||
867 | struct GNUNET_DNSPARSER_SrvRecord * | ||
868 | GNUNET_DNSPARSER_duplicate_srv_record (const struct GNUNET_DNSPARSER_SrvRecord *r) | ||
869 | { | ||
870 | struct GNUNET_DNSPARSER_SrvRecord *dup = GNUNET_memdup (r, sizeof (*r)); | ||
871 | |||
872 | dup->target = GNUNET_strdup (r->target); | ||
873 | return dup; | ||
874 | } | ||
875 | |||
876 | |||
877 | /** | ||
762 | * Free memory taken by a packet. | 878 | * Free memory taken by a packet. |
763 | * | 879 | * |
764 | * @param p packet to free | 880 | * @param p packet to free |
diff --git a/src/util/gnunet-service-resolver.c b/src/util/gnunet-service-resolver.c index d90d8ec10..5b890261b 100644 --- a/src/util/gnunet-service-resolver.c +++ b/src/util/gnunet-service-resolver.c | |||
@@ -27,721 +27,559 @@ | |||
27 | #include "gnunet_statistics_service.h" | 27 | #include "gnunet_statistics_service.h" |
28 | #include "resolver.h" | 28 | #include "resolver.h" |
29 | 29 | ||
30 | |||
31 | struct Record | ||
32 | { | ||
33 | struct Record *next; | ||
34 | |||
35 | struct Record *prev; | ||
36 | |||
37 | struct GNUNET_DNSPARSER_Record *record; | ||
38 | }; | ||
39 | |||
30 | /** | 40 | /** |
31 | * A cached DNS lookup result (for reverse lookup). | 41 | * A cached DNS lookup result. |
32 | */ | 42 | */ |
33 | struct IPCache | 43 | struct ResolveCache |
34 | { | 44 | { |
35 | /** | 45 | /** |
36 | * This is a doubly linked list. | 46 | * This is a doubly linked list. |
37 | */ | 47 | */ |
38 | struct IPCache *next; | 48 | struct ResolveCache *next; |
39 | 49 | ||
40 | /** | 50 | /** |
41 | * This is a doubly linked list. | 51 | * This is a doubly linked list. |
42 | */ | 52 | */ |
43 | struct IPCache *prev; | 53 | struct ResolveCache *prev; |
44 | 54 | ||
45 | /** | 55 | /** |
46 | * Hostname in human-readable form. | 56 | * type of queried DNS record |
47 | */ | 57 | */ |
48 | char *addr; | 58 | uint16_t record_type; |
49 | 59 | ||
50 | /** | 60 | /** |
51 | * Binary IP address, allocated at the end of this struct. | 61 | * a pointer to the request_id if a query for this hostname/record_type |
62 | * is currently pending, NULL otherwise. | ||
52 | */ | 63 | */ |
53 | const void *ip; | 64 | int16_t *request_id; |
54 | 65 | ||
55 | /** | 66 | /** |
56 | * Last time this entry was updated. | 67 | * The client that queried the records contained in this cache entry. |
57 | */ | 68 | */ |
58 | struct GNUNET_TIME_Absolute last_refresh; | 69 | struct GNUNET_SERVICE_Client *client; |
59 | 70 | ||
60 | /** | 71 | /** |
61 | * Last time this entry was requested. | 72 | * head of a double linked list containing the lookup results |
62 | */ | 73 | */ |
63 | struct GNUNET_TIME_Absolute last_request; | 74 | struct Record *records_head; |
64 | 75 | ||
65 | /** | 76 | /** |
66 | * Number of bytes in ip. | 77 | * tail of a double linked list containing the lookup results |
67 | */ | 78 | */ |
68 | size_t ip_len; | 79 | struct Record *records_tail; |
69 | 80 | ||
70 | /** | 81 | /** |
71 | * Address family of the IP. | 82 | * handle for cancelling a request |
72 | */ | 83 | */ |
73 | int af; | 84 | struct GNUNET_DNSSTUB_RequestSocket *resolve_handle; |
85 | |||
86 | /** | ||
87 | * handle for the resolution timeout task | ||
88 | */ | ||
89 | struct GNUNET_SCHEDULER_Task *timeout_task; | ||
90 | |||
74 | }; | 91 | }; |
75 | 92 | ||
76 | 93 | ||
77 | /** | 94 | /** |
78 | * Start of the linked list of cached DNS lookup results. | 95 | * Start of the linked list of cached DNS lookup results. |
79 | */ | 96 | */ |
80 | static struct IPCache *cache_head; | 97 | static struct ResolveCache *cache_head; |
81 | 98 | ||
82 | /** | 99 | /** |
83 | * Tail of the linked list of cached DNS lookup results. | 100 | * Tail of the linked list of cached DNS lookup results. |
84 | */ | 101 | */ |
85 | static struct IPCache *cache_tail; | 102 | static struct ResolveCache *cache_tail; |
86 | 103 | ||
87 | /** | 104 | /** |
88 | * Pipe for asynchronously notifying about resolve result | 105 | * context of dnsstub library |
89 | */ | 106 | */ |
90 | static struct GNUNET_DISK_PipeHandle *resolve_result_pipe; | 107 | static struct GNUNET_DNSSTUB_Context *dnsstub_ctx; |
91 | 108 | ||
92 | /** | ||
93 | * Task for reading from resolve_result_pipe | ||
94 | */ | ||
95 | static struct GNUNET_SCHEDULER_Task *resolve_result_pipe_task; | ||
96 | 109 | ||
97 | 110 | void free_cache_entry (struct ResolveCache *entry) | |
98 | #if HAVE_GETNAMEINFO | ||
99 | /** | ||
100 | * Resolve the given request using getnameinfo | ||
101 | * | ||
102 | * @param cache the request to resolve (and where to store the result) | ||
103 | */ | ||
104 | static void | ||
105 | getnameinfo_resolve (struct IPCache *cache) | ||
106 | { | 111 | { |
107 | char hostname[256]; | 112 | struct Record *pos; |
108 | const struct sockaddr *sa; | 113 | struct Record *next; |
109 | struct sockaddr_in v4; | 114 | |
110 | struct sockaddr_in6 v6; | 115 | next = entry->records_head; |
111 | size_t salen; | 116 | while (NULL != (pos = next)) |
112 | int ret; | ||
113 | |||
114 | switch (cache->af) | ||
115 | { | 117 | { |
116 | case AF_INET: | 118 | next = pos->next; |
117 | GNUNET_assert (cache->ip_len == sizeof (struct in_addr)); | 119 | GNUNET_CONTAINER_DLL_remove (entry->records_head, |
118 | sa = (const struct sockaddr*) &v4; | 120 | entry->records_tail, |
119 | memset (&v4, 0, sizeof (v4)); | 121 | pos); |
120 | v4.sin_addr = * (const struct in_addr*) cache->ip; | 122 | if (NULL != pos->record) |
121 | v4.sin_family = AF_INET; | 123 | { |
122 | #if HAVE_SOCKADDR_IN_SIN_LEN | 124 | GNUNET_DNSPARSER_free_record (pos->record); |
123 | v4.sin_len = sizeof (v4); | 125 | GNUNET_free (pos->record); |
124 | #endif | 126 | } |
125 | salen = sizeof (v4); | 127 | GNUNET_free (pos); |
126 | break; | ||
127 | case AF_INET6: | ||
128 | GNUNET_assert (cache->ip_len == sizeof (struct in6_addr)); | ||
129 | sa = (const struct sockaddr*) &v6; | ||
130 | memset (&v6, 0, sizeof (v6)); | ||
131 | v6.sin6_addr = * (const struct in6_addr*) cache->ip; | ||
132 | v6.sin6_family = AF_INET6; | ||
133 | #if HAVE_SOCKADDR_IN_SIN_LEN | ||
134 | v6.sin6_len = sizeof (v6); | ||
135 | #endif | ||
136 | salen = sizeof (v6); | ||
137 | break; | ||
138 | default: | ||
139 | GNUNET_assert (0); | ||
140 | } | 128 | } |
141 | 129 | if (NULL != entry->resolve_handle) | |
142 | if (0 == | ||
143 | (ret = getnameinfo (sa, salen, | ||
144 | hostname, sizeof (hostname), | ||
145 | NULL, | ||
146 | 0, 0))) | ||
147 | { | 130 | { |
148 | cache->addr = GNUNET_strdup (hostname); | 131 | GNUNET_DNSSTUB_resolve_cancel (entry->resolve_handle); |
132 | entry->resolve_handle = NULL; | ||
149 | } | 133 | } |
150 | else | 134 | if (NULL != entry->timeout_task) |
151 | { | 135 | { |
152 | GNUNET_log (GNUNET_ERROR_TYPE_INFO, | 136 | GNUNET_SCHEDULER_cancel (entry->timeout_task); |
153 | "getnameinfo failed: %s\n", | 137 | entry->timeout_task = NULL; |
154 | gai_strerror (ret)); | ||
155 | } | 138 | } |
139 | GNUNET_free_non_null (entry->request_id); | ||
140 | GNUNET_free (entry); | ||
156 | } | 141 | } |
157 | #endif | ||
158 | 142 | ||
159 | 143 | ||
160 | #if HAVE_GETHOSTBYADDR | 144 | static char* |
145 | extract_dns_server (const char* line, size_t line_len) | ||
146 | { | ||
147 | if (0 == strncmp (line, "nameserver ", 11)) | ||
148 | return GNUNET_strndup (line + 11, line_len - 11); | ||
149 | return NULL; | ||
150 | } | ||
151 | |||
152 | |||
161 | /** | 153 | /** |
162 | * Resolve the given request using gethostbyaddr | 154 | * reads the list of nameservers from /etc/resolve.conf |
163 | * | 155 | * |
164 | * @param cache the request to resolve (and where to store the result) | 156 | * @param server_addrs[out] a list of null-terminated server address strings |
157 | * @return the number of server addresses in @server_addrs, -1 on error | ||
165 | */ | 158 | */ |
166 | static void | 159 | static ssize_t |
167 | gethostbyaddr_resolve (struct IPCache *cache) | 160 | lookup_dns_servers (char ***server_addrs) |
168 | { | 161 | { |
169 | struct hostent *ent; | 162 | struct GNUNET_DISK_FileHandle *fh; |
170 | 163 | char buf[2048]; | |
171 | ent = gethostbyaddr (cache->ip, | 164 | ssize_t bytes_read; |
172 | cache->ip_len, | 165 | size_t read_offset = 0; |
173 | cache->af); | 166 | unsigned int num_dns_servers = 0; |
174 | if (NULL != ent) | 167 | |
168 | fh = GNUNET_DISK_file_open ("/etc/resolv.conf", | ||
169 | GNUNET_DISK_OPEN_READ, | ||
170 | GNUNET_DISK_PERM_NONE); | ||
171 | if (NULL == fh) | ||
175 | { | 172 | { |
176 | cache->addr = GNUNET_strdup (ent->h_name); | 173 | GNUNET_log (GNUNET_ERROR_TYPE_ERROR, |
174 | "Could not open /etc/resolv.conf. " | ||
175 | "DNS resolution will not be possible.\n"); | ||
176 | return -1; | ||
177 | } | 177 | } |
178 | else | 178 | bytes_read = GNUNET_DISK_file_read (fh, |
179 | buf, | ||
180 | sizeof (buf)); | ||
181 | *server_addrs = NULL; | ||
182 | while (read_offset < bytes_read) | ||
179 | { | 183 | { |
180 | GNUNET_log (GNUNET_ERROR_TYPE_INFO, | 184 | char *newline; |
181 | "gethostbyaddr failed: %s\n", | 185 | size_t line_len; |
182 | hstrerror (h_errno)); | 186 | char *dns_server; |
187 | |||
188 | newline = strchr (buf + read_offset, '\n'); | ||
189 | if (NULL == newline) | ||
190 | { | ||
191 | break; | ||
192 | } | ||
193 | line_len = newline - buf - read_offset; | ||
194 | dns_server = extract_dns_server (buf + read_offset, line_len); | ||
195 | if (NULL != dns_server) | ||
196 | { | ||
197 | GNUNET_array_append (*server_addrs, | ||
198 | num_dns_servers, | ||
199 | dns_server); | ||
200 | } | ||
201 | read_offset += line_len + 1; | ||
183 | } | 202 | } |
203 | GNUNET_DISK_file_close (fh); | ||
204 | return num_dns_servers; | ||
184 | } | 205 | } |
185 | #endif | ||
186 | 206 | ||
187 | 207 | ||
188 | /** | 208 | static char * |
189 | * Resolve the given request using the available methods. | 209 | make_reverse_hostname (const void *ip, int af) |
190 | * | ||
191 | * @param cache the request to resolve (and where to store the result) | ||
192 | */ | ||
193 | static void | ||
194 | cache_resolve (struct IPCache *cache) | ||
195 | { | 210 | { |
196 | #if HAVE_GETNAMEINFO | 211 | char *buf = GNUNET_new_array (80, char); |
197 | if (NULL == cache->addr) | 212 | int pos = 0; |
198 | getnameinfo_resolve (cache); | 213 | if (AF_INET == af) |
199 | #endif | 214 | { |
200 | #if HAVE_GETHOSTBYADDR | 215 | struct in_addr *addr = (struct in_addr *)ip; |
201 | if (NULL == cache->addr) | 216 | uint32_t ip_int = addr->s_addr; |
202 | gethostbyaddr_resolve (cache); | 217 | for (int i = 3; i >= 0; i--) |
203 | #endif | 218 | { |
219 | int n = GNUNET_snprintf (buf + pos, | ||
220 | 80 - pos, | ||
221 | "%u.", | ||
222 | ((uint8_t *)&ip_int)[i]); | ||
223 | if (n < 0) | ||
224 | { | ||
225 | GNUNET_free (buf); | ||
226 | return NULL; | ||
227 | } | ||
228 | pos += n; | ||
229 | } | ||
230 | pos += GNUNET_snprintf (buf + pos, 80 - pos, "in-addr.arpa"); | ||
231 | } | ||
232 | else if (AF_INET6 == af) | ||
233 | { | ||
234 | struct in6_addr *addr = (struct in6_addr *)ip; | ||
235 | for (int i = 15; i >= 0; i--) | ||
236 | { | ||
237 | int n = GNUNET_snprintf (buf + pos, 80 - pos, "%x.", addr->s6_addr[i] & 0xf); | ||
238 | if (n < 0) | ||
239 | { | ||
240 | GNUNET_free (buf); | ||
241 | return NULL; | ||
242 | } | ||
243 | pos += n; | ||
244 | n = GNUNET_snprintf (buf + pos, 80 - pos, "%x.", addr->s6_addr[i] >> 4); | ||
245 | if (n < 0) | ||
246 | { | ||
247 | GNUNET_free (buf); | ||
248 | return NULL; | ||
249 | } | ||
250 | pos += n; | ||
251 | } | ||
252 | pos += GNUNET_snprintf (buf + pos, 80 - pos, "ip6.arpa"); | ||
253 | } | ||
254 | buf[pos] = '\0'; | ||
255 | return buf; | ||
204 | } | 256 | } |
205 | 257 | ||
206 | 258 | ||
207 | /** | ||
208 | * Function called after the replies for the request have all | ||
209 | * been transmitted to the client, and we can now read the next | ||
210 | * request from the client. | ||
211 | * | ||
212 | * @param cls the `struct GNUNET_SERVICE_Client` to continue with | ||
213 | */ | ||
214 | static void | 259 | static void |
215 | notify_service_client_done (void *cls) | 260 | send_reply (struct GNUNET_DNSPARSER_Record *record, |
261 | uint16_t request_id, | ||
262 | struct GNUNET_SERVICE_Client *client) | ||
216 | { | 263 | { |
217 | struct GNUNET_SERVICE_Client *client = cls; | ||
218 | |||
219 | GNUNET_SERVICE_client_continue (client); | ||
220 | } | ||
221 | |||
222 | |||
223 | /** | ||
224 | * Get an IP address as a string (works for both IPv4 and IPv6). Note | ||
225 | * that the resolution happens asynchronously and that the first call | ||
226 | * may not immediately result in the FQN (but instead in a | ||
227 | * human-readable IP address). | ||
228 | * | ||
229 | * @param client handle to the client making the request (for sending the reply) | ||
230 | * @param af AF_INET or AF_INET6 | ||
231 | * @param ip `struct in_addr` or `struct in6_addr` | ||
232 | */ | ||
233 | static void | ||
234 | get_ip_as_string (struct GNUNET_SERVICE_Client *client, | ||
235 | int af, | ||
236 | const void *ip, | ||
237 | uint32_t request_id) | ||
238 | { | ||
239 | struct IPCache *pos; | ||
240 | struct IPCache *next; | ||
241 | struct GNUNET_TIME_Absolute now; | ||
242 | struct GNUNET_MQ_Envelope *env; | ||
243 | struct GNUNET_MQ_Handle *mq; | ||
244 | struct GNUNET_RESOLVER_ResponseMessage *msg; | 264 | struct GNUNET_RESOLVER_ResponseMessage *msg; |
245 | size_t ip_len; | 265 | struct GNUNET_MQ_Envelope *env; |
246 | struct in6_addr ix; | 266 | void *payload; |
247 | size_t alen; | 267 | size_t payload_len; |
248 | 268 | ||
249 | switch (af) | 269 | switch (record->type) |
250 | { | ||
251 | case AF_INET: | ||
252 | ip_len = sizeof (struct in_addr); | ||
253 | break; | ||
254 | case AF_INET6: | ||
255 | ip_len = sizeof (struct in6_addr); | ||
256 | break; | ||
257 | default: | ||
258 | GNUNET_assert (0); | ||
259 | } | ||
260 | now = GNUNET_TIME_absolute_get (); | ||
261 | next = cache_head; | ||
262 | while ( (NULL != (pos = next)) && | ||
263 | ( (pos->af != af) || | ||
264 | (pos->ip_len != ip_len) || | ||
265 | (0 != memcmp (pos->ip, ip, ip_len))) ) | ||
266 | { | 270 | { |
267 | next = pos->next; | 271 | case GNUNET_DNSPARSER_TYPE_PTR: |
268 | if (GNUNET_TIME_absolute_get_duration (pos->last_request).rel_value_us < | ||
269 | 60 * 60 * 1000 * 1000LL) | ||
270 | { | 272 | { |
271 | GNUNET_CONTAINER_DLL_remove (cache_head, | 273 | char *hostname = record->data.hostname; |
272 | cache_tail, | 274 | payload = hostname; |
273 | pos); | 275 | payload_len = strlen (hostname) + 1; |
274 | GNUNET_free_non_null (pos->addr); | 276 | break; |
275 | GNUNET_free (pos); | ||
276 | continue; | ||
277 | } | 277 | } |
278 | } | 278 | case GNUNET_DNSPARSER_TYPE_A: |
279 | if (NULL != pos) | 279 | case GNUNET_DNSPARSER_TYPE_AAAA: |
280 | { | ||
281 | if ( (1 == inet_pton (af, | ||
282 | pos->ip, | ||
283 | &ix)) && | ||
284 | (GNUNET_TIME_absolute_get_duration (pos->last_request).rel_value_us > | ||
285 | 120 * 1000 * 1000LL) ) | ||
286 | { | 280 | { |
287 | /* try again if still numeric AND 2 minutes have expired */ | 281 | payload = record->data.raw.data; |
288 | GNUNET_free_non_null (pos->addr); | 282 | payload_len = record->data.raw.data_len; |
289 | pos->addr = NULL; | 283 | break; |
290 | cache_resolve (pos); | 284 | } |
291 | pos->last_request = now; | 285 | default: |
286 | { | ||
287 | GNUNET_log (GNUNET_ERROR_TYPE_ERROR, | ||
288 | "Cannot handle DNS response type: unimplemented\n"); | ||
289 | return; | ||
292 | } | 290 | } |
293 | } | 291 | } |
294 | else | ||
295 | { | ||
296 | pos = GNUNET_malloc (sizeof (struct IPCache) + ip_len); | ||
297 | pos->ip = &pos[1]; | ||
298 | GNUNET_memcpy (&pos[1], | ||
299 | ip, | ||
300 | ip_len); | ||
301 | pos->last_request = now; | ||
302 | pos->last_refresh = now; | ||
303 | pos->ip_len = ip_len; | ||
304 | pos->af = af; | ||
305 | GNUNET_CONTAINER_DLL_insert (cache_head, | ||
306 | cache_tail, | ||
307 | pos); | ||
308 | cache_resolve (pos); | ||
309 | } | ||
310 | if (NULL != pos->addr) | ||
311 | alen = strlen (pos->addr) + 1; | ||
312 | else | ||
313 | alen = 0; | ||
314 | mq = GNUNET_SERVICE_client_get_mq (client); | ||
315 | env = GNUNET_MQ_msg_extra (msg, | 292 | env = GNUNET_MQ_msg_extra (msg, |
316 | alen, | 293 | payload_len, |
317 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | 294 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); |
318 | msg->id = request_id; | 295 | msg->id = request_id; |
319 | GNUNET_memcpy (&msg[1], | 296 | GNUNET_memcpy (&msg[1], |
320 | pos->addr, | 297 | payload, |
321 | alen); | 298 | payload_len); |
322 | GNUNET_MQ_send (mq, | 299 | GNUNET_MQ_send (GNUNET_SERVICE_client_get_mq (client), |
323 | env); | 300 | env); |
324 | // send end message | ||
325 | env = GNUNET_MQ_msg (msg, | ||
326 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | ||
327 | msg->id = request_id; | ||
328 | GNUNET_MQ_notify_sent (env, | ||
329 | ¬ify_service_client_done, | ||
330 | client); | ||
331 | GNUNET_MQ_send (mq, | ||
332 | env); | ||
333 | } | 301 | } |
334 | 302 | ||
335 | 303 | ||
336 | #if HAVE_GETADDRINFO_A | ||
337 | struct AsyncCls | ||
338 | { | ||
339 | struct gaicb *host; | ||
340 | struct sigevent *sig; | ||
341 | struct GNUNET_MQ_Handle *mq; | ||
342 | uint32_t request_id; | ||
343 | }; | ||
344 | |||
345 | |||
346 | static void | 304 | static void |
347 | resolve_result_pipe_cb (void *cls) | 305 | send_end_msg (uint16_t request_id, |
306 | struct GNUNET_SERVICE_Client *client) | ||
348 | { | 307 | { |
349 | struct AsyncCls *async_cls; | ||
350 | struct gaicb *host; | ||
351 | struct GNUNET_RESOLVER_ResponseMessage *msg; | 308 | struct GNUNET_RESOLVER_ResponseMessage *msg; |
352 | struct GNUNET_MQ_Envelope *env; | 309 | struct GNUNET_MQ_Envelope *env; |
353 | 310 | ||
354 | GNUNET_DISK_file_read (GNUNET_DISK_pipe_handle (resolve_result_pipe, | 311 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, |
355 | GNUNET_DISK_PIPE_END_READ), | 312 | "Sending end message\n"); |
356 | &async_cls, | 313 | env = GNUNET_MQ_msg (msg, |
357 | sizeof (struct AsyncCls *)); | 314 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); |
358 | resolve_result_pipe_task = | 315 | msg->id = request_id; |
359 | GNUNET_SCHEDULER_add_read_file (GNUNET_TIME_UNIT_FOREVER_REL, | 316 | GNUNET_MQ_send (GNUNET_SERVICE_client_get_mq (client), |
360 | GNUNET_DISK_pipe_handle (resolve_result_pipe, | 317 | env); |
361 | GNUNET_DISK_PIPE_END_READ), | 318 | } |
362 | &resolve_result_pipe_cb, | 319 | |
363 | NULL); | 320 | |
364 | host = async_cls->host; | 321 | static void |
365 | for (struct addrinfo *pos = host->ar_result; pos != NULL; pos = pos->ai_next) | 322 | handle_resolve_result (void *cls, |
323 | const struct GNUNET_TUN_DnsHeader *dns, | ||
324 | size_t dns_len) | ||
325 | { | ||
326 | struct ResolveCache *cache = cls; | ||
327 | struct GNUNET_DNSPARSER_Packet *parsed; | ||
328 | uint16_t request_id = *cache->request_id; | ||
329 | struct GNUNET_SERVICE_Client *client = cache->client; | ||
330 | |||
331 | parsed = GNUNET_DNSPARSER_parse ((const char *)dns, | ||
332 | dns_len); | ||
333 | if (NULL == parsed) | ||
334 | { | ||
335 | GNUNET_log (GNUNET_ERROR_TYPE_ERROR, | ||
336 | "Failed to parse DNS reply (request ID %u\n", | ||
337 | request_id); | ||
338 | return; | ||
339 | } | ||
340 | if (request_id != ntohs (parsed->id)) | ||
341 | { | ||
342 | GNUNET_log (GNUNET_ERROR_TYPE_ERROR, | ||
343 | "Request ID in DNS reply does not match\n"); | ||
344 | return; | ||
345 | } | ||
346 | else if (0 == parsed->num_answers) | ||
347 | { | ||
348 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, | ||
349 | "DNS reply (request ID %u) contains no answers\n", | ||
350 | request_id); | ||
351 | GNUNET_CONTAINER_DLL_remove (cache_head, | ||
352 | cache_tail, | ||
353 | cache); | ||
354 | free_cache_entry (cache); | ||
355 | cache = NULL; | ||
356 | } | ||
357 | else | ||
366 | { | 358 | { |
367 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, | 359 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, |
368 | "Lookup result for hostname %s: %s (request ID %u)\n", | 360 | "Got reply for request ID %u\n", |
369 | host->ar_name, | 361 | request_id); |
370 | GNUNET_a2s (pos->ai_addr, pos->ai_addrlen), | 362 | for (unsigned int i = 0; i != parsed->num_answers; i++) |
371 | async_cls->request_id); | ||
372 | switch (pos->ai_family) | ||
373 | { | 363 | { |
374 | case AF_INET: | 364 | struct Record *cache_entry = GNUNET_new (struct Record); |
375 | env = GNUNET_MQ_msg_extra (msg, | 365 | struct GNUNET_DNSPARSER_Record *record = &parsed->answers[i]; |
376 | sizeof (struct in_addr), | 366 | cache_entry->record = GNUNET_DNSPARSER_duplicate_record (record); |
377 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | 367 | GNUNET_CONTAINER_DLL_insert (cache->records_head, |
378 | msg->id = async_cls->request_id; | 368 | cache->records_tail, |
379 | GNUNET_memcpy (&msg[1], | 369 | cache_entry); |
380 | &((struct sockaddr_in*) pos->ai_addr)->sin_addr, | 370 | send_reply (cache_entry->record, |
381 | sizeof (struct in_addr)); | 371 | request_id, |
382 | GNUNET_MQ_send (async_cls->mq, | 372 | cache->client); |
383 | env); | ||
384 | break; | ||
385 | case AF_INET6: | ||
386 | env = GNUNET_MQ_msg_extra (msg, | ||
387 | sizeof (struct in6_addr), | ||
388 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | ||
389 | msg->id = async_cls->request_id; | ||
390 | GNUNET_memcpy (&msg[1], | ||
391 | &((struct sockaddr_in6*) pos->ai_addr)->sin6_addr, | ||
392 | sizeof (struct in6_addr)); | ||
393 | GNUNET_MQ_send (async_cls->mq, | ||
394 | env); | ||
395 | break; | ||
396 | default: | ||
397 | /* unsupported, skip */ | ||
398 | break; | ||
399 | } | 373 | } |
374 | GNUNET_free_non_null (cache->request_id); | ||
375 | cache->request_id = NULL; | ||
400 | } | 376 | } |
401 | // send end message | 377 | send_end_msg (request_id, |
402 | env = GNUNET_MQ_msg (msg, | 378 | client); |
403 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | 379 | if (NULL != cache) |
404 | msg->id = async_cls->request_id; | 380 | cache->client = NULL; |
405 | GNUNET_MQ_send (async_cls->mq, | 381 | if (NULL != cache) |
406 | env); | 382 | { |
407 | freeaddrinfo (host->ar_result); | 383 | if (NULL != cache->timeout_task) |
408 | GNUNET_free ((struct gaicb *)host->ar_request); // free hints | 384 | { |
409 | GNUNET_free (host); | 385 | GNUNET_SCHEDULER_cancel (cache->timeout_task); |
410 | GNUNET_free (async_cls->sig); | 386 | cache->timeout_task = NULL; |
411 | GNUNET_free (async_cls); | 387 | } |
388 | if (NULL != cache->resolve_handle) | ||
389 | { | ||
390 | GNUNET_DNSSTUB_resolve_cancel (cache->resolve_handle); | ||
391 | cache->resolve_handle = NULL; | ||
392 | } | ||
393 | } | ||
394 | GNUNET_DNSPARSER_free_packet (parsed); | ||
412 | } | 395 | } |
413 | 396 | ||
414 | 397 | ||
415 | static void | 398 | static void |
416 | handle_async_result (union sigval val) | 399 | handle_resolve_timeout (void *cls) |
417 | { | 400 | { |
418 | GNUNET_DISK_file_write (GNUNET_DISK_pipe_handle (resolve_result_pipe, | 401 | struct ResolveCache *cache = cls; |
419 | GNUNET_DISK_PIPE_END_WRITE), | 402 | |
420 | &val.sival_ptr, | 403 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, |
421 | sizeof (val.sival_ptr)); | 404 | "timeout!\n"); |
405 | if (NULL != cache->resolve_handle) | ||
406 | { | ||
407 | GNUNET_DNSSTUB_resolve_cancel (cache->resolve_handle); | ||
408 | cache->resolve_handle = NULL; | ||
409 | } | ||
410 | GNUNET_CONTAINER_DLL_remove (cache_head, | ||
411 | cache_tail, | ||
412 | cache); | ||
413 | free_cache_entry (cache); | ||
422 | } | 414 | } |
423 | 415 | ||
424 | 416 | ||
425 | static int | 417 | static int |
426 | getaddrinfo_a_resolve (struct GNUNET_MQ_Handle *mq, | 418 | resolve_and_cache (const char* hostname, |
427 | const char *hostname, | 419 | uint16_t record_type, |
428 | int af, | 420 | uint16_t request_id, |
429 | uint32_t request_id) | 421 | struct GNUNET_SERVICE_Client *client) |
430 | { | 422 | { |
431 | int ret; | 423 | char *packet_buf; |
432 | struct gaicb *host; | 424 | size_t packet_size; |
433 | struct addrinfo *hints; | 425 | struct GNUNET_DNSPARSER_Query query; |
434 | struct sigevent *sig; | 426 | struct GNUNET_DNSPARSER_Packet packet; |
435 | struct AsyncCls *async_cls; | 427 | struct ResolveCache *cache; |
436 | 428 | struct GNUNET_TIME_Relative timeout = | |
437 | host = GNUNET_new (struct gaicb); | 429 | GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 5); |
438 | hints = GNUNET_new (struct addrinfo); | 430 | |
439 | sig = GNUNET_new (struct sigevent); | 431 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, |
440 | async_cls = GNUNET_new (struct AsyncCls); | 432 | "resolve_and_cache\n"); |
441 | memset (hints, | 433 | query.name = (char *)hostname; |
434 | query.type = record_type; | ||
435 | query.dns_traffic_class = GNUNET_TUN_DNS_CLASS_INTERNET; | ||
436 | memset (&packet, | ||
442 | 0, | 437 | 0, |
443 | sizeof (struct addrinfo)); | 438 | sizeof (packet)); |
444 | memset (sig, | 439 | packet.num_queries = 1; |
445 | 0, | 440 | packet.queries = &query; |
446 | sizeof (struct sigevent)); | 441 | packet.id = htons (request_id); |
447 | hints->ai_family = af; | 442 | packet.flags.recursion_desired = 1; |
448 | hints->ai_socktype = SOCK_STREAM; /* go for TCP */ | 443 | if (GNUNET_OK != |
449 | host->ar_name = hostname; | 444 | GNUNET_DNSPARSER_pack (&packet, |
450 | host->ar_service = NULL; | 445 | UINT16_MAX, |
451 | host->ar_request = hints; | 446 | &packet_buf, |
452 | host->ar_result = NULL; | 447 | &packet_size)) |
453 | sig->sigev_notify = SIGEV_THREAD; | 448 | { |
454 | sig->sigev_value.sival_ptr = async_cls; | 449 | GNUNET_log (GNUNET_ERROR_TYPE_ERROR, |
455 | sig->sigev_notify_function = &handle_async_result; | 450 | "Failed to pack query for hostname `%s'\n", |
456 | async_cls->host = host; | 451 | hostname); |
457 | async_cls->sig = sig; | ||
458 | async_cls->mq = mq; | ||
459 | async_cls->request_id = request_id; | ||
460 | ret = getaddrinfo_a (GAI_NOWAIT, | ||
461 | &host, | ||
462 | 1, | ||
463 | sig); | ||
464 | if (0 != ret) | ||
465 | return GNUNET_SYSERR; | 452 | return GNUNET_SYSERR; |
453 | |||
454 | } | ||
455 | cache = GNUNET_malloc (sizeof (struct ResolveCache)); | ||
456 | cache->record_type = record_type; | ||
457 | cache->request_id = GNUNET_memdup (&request_id, sizeof (request_id)); | ||
458 | cache->client = client; | ||
459 | cache->timeout_task = GNUNET_SCHEDULER_add_delayed (timeout, | ||
460 | &handle_resolve_timeout, | ||
461 | cache); | ||
462 | cache->resolve_handle = | ||
463 | GNUNET_DNSSTUB_resolve (dnsstub_ctx, | ||
464 | packet_buf, | ||
465 | packet_size, | ||
466 | &handle_resolve_result, | ||
467 | cache); | ||
468 | GNUNET_CONTAINER_DLL_insert (cache_head, | ||
469 | cache_tail, | ||
470 | cache); | ||
471 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, | ||
472 | "resolve %s, request_id = %u\n", | ||
473 | hostname, | ||
474 | request_id); | ||
475 | GNUNET_free (packet_buf); | ||
466 | return GNUNET_OK; | 476 | return GNUNET_OK; |
467 | } | 477 | } |
468 | 478 | ||
469 | 479 | ||
470 | #elif HAVE_GETADDRINFO | 480 | static const char * |
471 | static int | 481 | get_hostname (struct ResolveCache *cache_entry) |
472 | getaddrinfo_resolve (struct GNUNET_MQ_Handle *mq, | ||
473 | const char *hostname, | ||
474 | int af, | ||
475 | uint32_t request_id) | ||
476 | { | 482 | { |
477 | int s; | 483 | if (NULL != cache_entry->records_head) |
478 | struct addrinfo hints; | ||
479 | struct addrinfo *result; | ||
480 | struct addrinfo *pos; | ||
481 | struct GNUNET_RESOLVER_ResponseMessage *msg; | ||
482 | struct GNUNET_MQ_Envelope *env; | ||
483 | |||
484 | #ifdef WINDOWS | ||
485 | /* Due to a bug, getaddrinfo will not return a mix of different families */ | ||
486 | if (AF_UNSPEC == af) | ||
487 | { | 484 | { |
488 | int ret1; | 485 | GNUNET_assert (NULL != cache_entry->records_head); |
489 | int ret2; | 486 | GNUNET_assert (NULL != cache_entry->records_head->record); |
490 | ret1 = getaddrinfo_resolve (mq, | 487 | GNUNET_assert (NULL != cache_entry->records_head->record->name); |
491 | hostname, | 488 | return cache_entry->records_head->record->name; |
492 | AF_INET, | ||
493 | request_id); | ||
494 | ret2 = getaddrinfo_resolve (mq, | ||
495 | hostname, | ||
496 | AF_INET6, | ||
497 | request_id); | ||
498 | if ( (ret1 == GNUNET_OK) || | ||
499 | (ret2 == GNUNET_OK) ) | ||
500 | return GNUNET_OK; | ||
501 | if ( (ret1 == GNUNET_SYSERR) || | ||
502 | (ret2 == GNUNET_SYSERR) ) | ||
503 | return GNUNET_SYSERR; | ||
504 | return GNUNET_NO; | ||
505 | } | 489 | } |
506 | #endif | 490 | return NULL; |
507 | |||
508 | memset (&hints, | ||
509 | 0, | ||
510 | sizeof (struct addrinfo)); | ||
511 | hints.ai_family = af; | ||
512 | hints.ai_socktype = SOCK_STREAM; /* go for TCP */ | ||
513 | |||
514 | if (0 != (s = getaddrinfo (hostname, | ||
515 | NULL, | ||
516 | &hints, | ||
517 | &result))) | ||
518 | { | ||
519 | GNUNET_log (GNUNET_ERROR_TYPE_INFO, | ||
520 | _("Could not resolve `%s' (%s): %s\n"), | ||
521 | hostname, | ||
522 | (af == | ||
523 | AF_INET) ? "IPv4" : ((af == AF_INET6) ? "IPv6" : "any"), | ||
524 | gai_strerror (s)); | ||
525 | if ( (s == EAI_BADFLAGS) || | ||
526 | #ifndef WINDOWS | ||
527 | (s == EAI_SYSTEM) || | ||
528 | #endif | ||
529 | (s == EAI_MEMORY) ) | ||
530 | return GNUNET_NO; /* other function may still succeed */ | ||
531 | return GNUNET_SYSERR; | ||
532 | } | ||
533 | if (NULL == result) | ||
534 | return GNUNET_SYSERR; | ||
535 | for (pos = result; pos != NULL; pos = pos->ai_next) | ||
536 | { | ||
537 | switch (pos->ai_family) | ||
538 | { | ||
539 | case AF_INET: | ||
540 | env = GNUNET_MQ_msg_extra (msg, | ||
541 | sizeof (struct in_addr), | ||
542 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | ||
543 | msg->id = request_id; | ||
544 | GNUNET_memcpy (&msg[1], | ||
545 | &((struct sockaddr_in*) pos->ai_addr)->sin_addr, | ||
546 | sizeof (struct in_addr)); | ||
547 | GNUNET_MQ_send (mq, | ||
548 | env); | ||
549 | break; | ||
550 | case AF_INET6: | ||
551 | env = GNUNET_MQ_msg_extra (msg, | ||
552 | sizeof (struct in6_addr), | ||
553 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | ||
554 | msg->id = request_id; | ||
555 | GNUNET_memcpy (&msg[1], | ||
556 | &((struct sockaddr_in6*) pos->ai_addr)->sin6_addr, | ||
557 | sizeof (struct in6_addr)); | ||
558 | GNUNET_MQ_send (mq, | ||
559 | env); | ||
560 | break; | ||
561 | default: | ||
562 | /* unsupported, skip */ | ||
563 | break; | ||
564 | } | ||
565 | } | ||
566 | freeaddrinfo (result); | ||
567 | return GNUNET_OK; | ||
568 | } | 491 | } |
569 | 492 | ||
570 | 493 | ||
571 | #elif HAVE_GETHOSTBYNAME2 | 494 | static const uint16_t * |
572 | 495 | get_record_type (struct ResolveCache *cache_entry) | |
573 | |||
574 | static int | ||
575 | gethostbyname2_resolve (struct GNUNET_MQ_Handle *mq, | ||
576 | const char *hostname, | ||
577 | int af, | ||
578 | uint32_t request_id) | ||
579 | { | 496 | { |
580 | struct hostent *hp; | 497 | if (NULL != cache_entry->records_head) |
581 | int ret1; | 498 | return &cache_entry->record_type; |
582 | int ret2; | 499 | return NULL; |
583 | struct GNUNET_MQ_Envelope *env; | 500 | } |
584 | struct GNUNET_RESOLVER_ResponseMessage *msg; | ||
585 | 501 | ||
586 | #ifdef WINDOWS | ||
587 | /* gethostbyname2() in plibc is a compat dummy that calls gethostbyname(). */ | ||
588 | return GNUNET_NO; | ||
589 | #endif | ||
590 | 502 | ||
591 | if (af == AF_UNSPEC) | 503 | static const struct GNUNET_TIME_Absolute * |
592 | { | 504 | get_expiration_time (struct ResolveCache *cache_entry) |
593 | ret1 = gethostbyname2_resolve (mq, | 505 | { |
594 | hostname, | 506 | if (NULL != cache_entry->records_head) |
595 | AF_INET, | 507 | return &cache_entry->records_head->record->expiration_time; |
596 | request_id); | 508 | return NULL; |
597 | ret2 = gethostbyname2_resolve (mq, | ||
598 | hostname, | ||
599 | AF_INET6, | ||
600 | request_id); | ||
601 | if ( (ret1 == GNUNET_OK) || | ||
602 | (ret2 == GNUNET_OK) ) | ||
603 | return GNUNET_OK; | ||
604 | if ( (ret1 == GNUNET_SYSERR) || | ||
605 | (ret2 == GNUNET_SYSERR) ) | ||
606 | return GNUNET_SYSERR; | ||
607 | return GNUNET_NO; | ||
608 | } | ||
609 | hp = gethostbyname2 (hostname, | ||
610 | af); | ||
611 | if (hp == NULL) | ||
612 | { | ||
613 | GNUNET_log (GNUNET_ERROR_TYPE_INFO, | ||
614 | _("Could not find IP of host `%s': %s\n"), | ||
615 | hostname, | ||
616 | hstrerror (h_errno)); | ||
617 | return GNUNET_SYSERR; | ||
618 | } | ||
619 | GNUNET_assert (hp->h_addrtype == af); | ||
620 | switch (af) | ||
621 | { | ||
622 | case AF_INET: | ||
623 | GNUNET_assert (hp->h_length == sizeof (struct in_addr)); | ||
624 | env = GNUNET_MQ_msg_extra (msg, | ||
625 | hp->h_length, | ||
626 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | ||
627 | msg->id = request_id; | ||
628 | GNUNET_memcpy (&msg[1], | ||
629 | hp->h_addr_list[0], | ||
630 | hp->h_length); | ||
631 | GNUNET_MQ_send (mq, | ||
632 | env); | ||
633 | break; | ||
634 | case AF_INET6: | ||
635 | GNUNET_assert (hp->h_length == sizeof (struct in6_addr)); | ||
636 | env = GNUNET_MQ_msg_extra (msg, | ||
637 | hp->h_length, | ||
638 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | ||
639 | msg->id = request_id; | ||
640 | GNUNET_memcpy (&msg[1], | ||
641 | hp->h_addr_list[0], | ||
642 | hp->h_length); | ||
643 | GNUNET_MQ_send (mq, | ||
644 | env); | ||
645 | break; | ||
646 | default: | ||
647 | GNUNET_break (0); | ||
648 | return GNUNET_SYSERR; | ||
649 | } | ||
650 | return GNUNET_OK; | ||
651 | } | 509 | } |
652 | 510 | ||
653 | #elif HAVE_GETHOSTBYNAME | ||
654 | |||
655 | 511 | ||
656 | static int | 512 | static int |
657 | gethostbyname_resolve (struct GNUNET_MQ_Handle *mq, | 513 | remove_if_expired (struct ResolveCache *cache_entry) |
658 | const char *hostname, | ||
659 | uint32_t request_id) | ||
660 | { | 514 | { |
661 | struct hostent *hp; | 515 | struct GNUNET_TIME_Absolute now = GNUNET_TIME_absolute_get (); |
662 | struct GNUNET_RESOLVER_ResponseMessage *msg; | ||
663 | struct GNUNET_MQ_Envelope *env; | ||
664 | 516 | ||
665 | hp = GETHOSTBYNAME (hostname); | 517 | if ( (NULL != cache_entry->records_head) && |
666 | if (NULL == hp) | 518 | (now.abs_value_us > get_expiration_time (cache_entry)->abs_value_us) ) |
667 | { | 519 | { |
668 | GNUNET_log (GNUNET_ERROR_TYPE_INFO, | 520 | GNUNET_CONTAINER_DLL_remove (cache_head, |
669 | _("Could not find IP of host `%s': %s\n"), | 521 | cache_tail, |
670 | hostname, | 522 | cache_entry); |
671 | hstrerror (h_errno)); | 523 | free_cache_entry (cache_entry); |
672 | return GNUNET_SYSERR; | 524 | return GNUNET_YES; |
673 | } | ||
674 | if (hp->h_addrtype != AF_INET) | ||
675 | { | ||
676 | GNUNET_break (0); | ||
677 | return GNUNET_SYSERR; | ||
678 | } | 525 | } |
679 | GNUNET_assert (hp->h_length == sizeof (struct in_addr)); | 526 | return GNUNET_NO; |
680 | env = GNUNET_MQ_msg_extra (msg, | ||
681 | hp->h_length, | ||
682 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | ||
683 | msg->id = request_id; | ||
684 | GNUNET_memcpy (&msg[1], | ||
685 | hp->h_addr_list[0], | ||
686 | hp->h_length); | ||
687 | GNUNET_MQ_send (mq, | ||
688 | env); | ||
689 | return GNUNET_OK; | ||
690 | } | 527 | } |
691 | #endif | ||
692 | 528 | ||
693 | 529 | ||
694 | /** | 530 | /** |
695 | * Convert a string to an IP address. | 531 | * Get an IP address as a string (works for both IPv4 and IPv6). Note |
532 | * that the resolution happens asynchronously and that the first call | ||
533 | * may not immediately result in the FQN (but instead in a | ||
534 | * human-readable IP address). | ||
696 | * | 535 | * |
697 | * @param client where to send the IP address | 536 | * @param client handle to the client making the request (for sending the reply) |
698 | * @param hostname the hostname to resolve | 537 | * @param af AF_INET or AF_INET6 |
699 | * @param af AF_INET or AF_INET6; use AF_UNSPEC for "any" | 538 | * @param ip `struct in_addr` or `struct in6_addr` |
700 | */ | 539 | */ |
701 | static void | 540 | static int |
702 | get_ip_from_hostname (struct GNUNET_SERVICE_Client *client, | 541 | try_cache (const char *hostname, |
703 | const char *hostname, | 542 | uint16_t record_type, |
704 | int af, | 543 | uint16_t request_id, |
705 | uint32_t request_id) | 544 | struct GNUNET_SERVICE_Client *client) |
706 | { | 545 | { |
707 | struct GNUNET_MQ_Envelope *env; | 546 | struct ResolveCache *pos; |
708 | struct GNUNET_RESOLVER_ResponseMessage *msg; | 547 | struct ResolveCache *next; |
709 | struct GNUNET_MQ_Handle *mq; | 548 | |
710 | 549 | next = cache_head; | |
711 | mq = GNUNET_SERVICE_client_get_mq (client); | 550 | while ( (NULL != (pos = next)) && |
712 | #if HAVE_GETADDRINFO_A | 551 | ( (NULL == pos->records_head) || |
713 | getaddrinfo_a_resolve (mq, | 552 | (0 != strcmp (get_hostname (pos), hostname)) || |
714 | hostname, | 553 | (*get_record_type (pos) != record_type) ) ) |
715 | af, | 554 | { |
716 | request_id); | 555 | next = pos->next; |
717 | GNUNET_SERVICE_client_continue (client); | 556 | remove_if_expired (pos); |
718 | return; | 557 | } |
719 | #elif HAVE_GETADDRINFO | 558 | if (NULL != pos) |
720 | getaddrinfo_resolve (mq, | 559 | { |
721 | hostname, | 560 | if (GNUNET_NO == remove_if_expired (pos)) |
722 | af, | 561 | { |
723 | request_id); | 562 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, |
724 | #elif HAVE_GETHOSTBYNAME2 | 563 | "found cache entry for '%s', record type '%u'\n", |
725 | gethostbyname2_resolve (mq, | 564 | hostname, |
726 | hostname, | 565 | record_type); |
727 | af, | 566 | struct Record *cache_pos = pos->records_head; |
728 | request_id); | 567 | while (NULL != cache_pos) |
729 | #elif HAVE_GETHOSTBYNAME | 568 | { |
730 | if ( ( (af == AF_UNSPEC) || | 569 | send_reply (cache_pos->record, |
731 | (af == PF_INET) ) ) | 570 | request_id, |
732 | gethostbyname_resolve (mq, | 571 | client); |
733 | hostname, | 572 | cache_pos = cache_pos->next; |
734 | request_id); | 573 | } |
735 | #endif | 574 | send_end_msg (request_id, |
736 | // send end message | 575 | client); |
737 | env = GNUNET_MQ_msg (msg, | 576 | return GNUNET_YES; |
738 | GNUNET_MESSAGE_TYPE_RESOLVER_RESPONSE); | 577 | } |
739 | msg->id = request_id; | 578 | } |
740 | GNUNET_MQ_notify_sent (env, | 579 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, |
741 | ¬ify_service_client_done, | 580 | "no cache entry for '%s'\n", |
742 | client); | 581 | hostname); |
743 | GNUNET_MQ_send (mq, | 582 | return GNUNET_NO; |
744 | env); | ||
745 | } | 583 | } |
746 | 584 | ||
747 | 585 | ||
@@ -801,6 +639,23 @@ check_get (void *cls, | |||
801 | } | 639 | } |
802 | 640 | ||
803 | 641 | ||
642 | static void | ||
643 | process_get (const char *hostname, | ||
644 | uint16_t record_type, | ||
645 | uint16_t request_id, | ||
646 | struct GNUNET_SERVICE_Client *client) | ||
647 | { | ||
648 | if (GNUNET_NO == try_cache (hostname, record_type, request_id, client)) | ||
649 | { | ||
650 | int result = resolve_and_cache (hostname, | ||
651 | record_type, | ||
652 | request_id, | ||
653 | client); | ||
654 | GNUNET_assert (GNUNET_OK == result); | ||
655 | } | ||
656 | } | ||
657 | |||
658 | |||
804 | /** | 659 | /** |
805 | * Handle GET-message. | 660 | * Handle GET-message. |
806 | * | 661 | * |
@@ -812,45 +667,100 @@ handle_get (void *cls, | |||
812 | const struct GNUNET_RESOLVER_GetMessage *msg) | 667 | const struct GNUNET_RESOLVER_GetMessage *msg) |
813 | { | 668 | { |
814 | struct GNUNET_SERVICE_Client *client = cls; | 669 | struct GNUNET_SERVICE_Client *client = cls; |
815 | const void *ip; | ||
816 | int direction; | 670 | int direction; |
817 | int af; | 671 | int af; |
818 | uint32_t id; | 672 | uint16_t request_id; |
673 | const char *hostname; | ||
819 | 674 | ||
820 | direction = ntohl (msg->direction); | 675 | direction = ntohl (msg->direction); |
821 | af = ntohl (msg->af); | 676 | af = ntohl (msg->af); |
822 | id = ntohl (msg->id); | 677 | request_id = ntohs (msg->id); |
823 | if (GNUNET_NO == direction) | 678 | if (GNUNET_NO == direction) |
824 | { | 679 | { |
825 | /* IP from hostname */ | 680 | /* IP from hostname */ |
826 | const char *hostname; | 681 | hostname = GNUNET_strdup ((const char *) &msg[1]); |
827 | 682 | switch (af) | |
828 | hostname = (const char *) &msg[1]; | 683 | { |
829 | get_ip_from_hostname (client, | 684 | case AF_UNSPEC: |
830 | hostname, | 685 | { |
831 | af, | 686 | process_get (hostname, GNUNET_DNSPARSER_TYPE_ALL, request_id, client); |
832 | id); | 687 | break; |
833 | return; | 688 | } |
689 | case AF_INET: | ||
690 | { | ||
691 | process_get (hostname, GNUNET_DNSPARSER_TYPE_A, request_id, client); | ||
692 | break; | ||
693 | } | ||
694 | case AF_INET6: | ||
695 | { | ||
696 | process_get (hostname, GNUNET_DNSPARSER_TYPE_AAAA, request_id, client); | ||
697 | break; | ||
698 | } | ||
699 | default: | ||
700 | { | ||
701 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, | ||
702 | "got invalid af: %d\n", | ||
703 | af); | ||
704 | GNUNET_assert (0); | ||
705 | } | ||
706 | } | ||
707 | } | ||
708 | else | ||
709 | { | ||
710 | /* hostname from IP */ | ||
711 | hostname = make_reverse_hostname (&msg[1], af); | ||
712 | process_get (hostname, GNUNET_DNSPARSER_TYPE_PTR, request_id, client); | ||
834 | } | 713 | } |
835 | ip = &msg[1]; | 714 | GNUNET_free_non_null ((char *)hostname); |
715 | GNUNET_SERVICE_client_continue (client); | ||
716 | } | ||
836 | 717 | ||
837 | #if !defined(GNUNET_CULL_LOGGING) | 718 | |
719 | static void | ||
720 | shutdown_task (void *cls) | ||
721 | { | ||
722 | (void) cls; | ||
723 | struct ResolveCache *pos; | ||
724 | |||
725 | while (NULL != (pos = cache_head)) | ||
838 | { | 726 | { |
839 | char buf[INET6_ADDRSTRLEN]; | 727 | GNUNET_CONTAINER_DLL_remove (cache_head, |
728 | cache_tail, | ||
729 | pos); | ||
730 | free_cache_entry (pos); | ||
731 | } | ||
732 | GNUNET_DNSSTUB_stop (dnsstub_ctx); | ||
733 | } | ||
734 | |||
840 | 735 | ||
736 | static void | ||
737 | init_cb (void *cls, | ||
738 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
739 | struct GNUNET_SERVICE_Handle *sh) | ||
740 | { | ||
741 | (void) cfg; | ||
742 | (void) sh; | ||
743 | |||
744 | GNUNET_SCHEDULER_add_shutdown (&shutdown_task, | ||
745 | cls); | ||
746 | dnsstub_ctx = GNUNET_DNSSTUB_start (128); | ||
747 | char **dns_servers; | ||
748 | ssize_t num_dns_servers = lookup_dns_servers (&dns_servers); | ||
749 | if (0 == num_dns_servers) | ||
750 | { | ||
751 | GNUNET_log (GNUNET_ERROR_TYPE_ERROR, | ||
752 | "no DNS server available. DNS resolution will not be possible.\n"); | ||
753 | } | ||
754 | for (int i = 0; i != num_dns_servers; i++) | ||
755 | { | ||
756 | int result = GNUNET_DNSSTUB_add_dns_ip (dnsstub_ctx, dns_servers[i]); | ||
841 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, | 757 | GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, |
842 | "Resolver asked to look up IP address `%s (request ID %u)'.\n", | 758 | "Adding DNS server '%s': %s\n", |
843 | inet_ntop (af, | 759 | dns_servers[i], |
844 | ip, | 760 | GNUNET_OK == result ? "success" : "failure"); |
845 | buf, | 761 | GNUNET_free (dns_servers[i]); |
846 | sizeof (buf)), | ||
847 | id); | ||
848 | } | 762 | } |
849 | #endif | 763 | GNUNET_free_non_null (dns_servers); |
850 | get_ip_as_string (client, | ||
851 | af, | ||
852 | ip, | ||
853 | id); | ||
854 | } | 764 | } |
855 | 765 | ||
856 | 766 | ||
@@ -870,19 +780,6 @@ connect_cb (void *cls, | |||
870 | (void) cls; | 780 | (void) cls; |
871 | (void) mq; | 781 | (void) mq; |
872 | 782 | ||
873 | #if HAVE_GETADDRINFO_A | ||
874 | resolve_result_pipe = GNUNET_DISK_pipe (GNUNET_NO, | ||
875 | GNUNET_NO, | ||
876 | GNUNET_NO, | ||
877 | GNUNET_NO); | ||
878 | GNUNET_assert (NULL != resolve_result_pipe); | ||
879 | resolve_result_pipe_task = | ||
880 | GNUNET_SCHEDULER_add_read_file (GNUNET_TIME_UNIT_FOREVER_REL, | ||
881 | GNUNET_DISK_pipe_handle (resolve_result_pipe, | ||
882 | GNUNET_DISK_PIPE_END_READ), | ||
883 | &resolve_result_pipe_cb, | ||
884 | NULL); | ||
885 | #endif | ||
886 | return c; | 783 | return c; |
887 | } | 784 | } |
888 | 785 | ||
@@ -900,19 +797,16 @@ disconnect_cb (void *cls, | |||
900 | void *internal_cls) | 797 | void *internal_cls) |
901 | { | 798 | { |
902 | (void) cls; | 799 | (void) cls; |
800 | struct ResolveCache *pos = cache_head; | ||
903 | 801 | ||
904 | #if HAVE_GETADDRINFO_A | 802 | while (NULL != pos) |
905 | if (NULL != resolve_result_pipe_task) | ||
906 | { | ||
907 | GNUNET_SCHEDULER_cancel (resolve_result_pipe_task); | ||
908 | resolve_result_pipe_task = NULL; | ||
909 | } | ||
910 | if (NULL != resolve_result_pipe) | ||
911 | { | 803 | { |
912 | GNUNET_DISK_pipe_close (resolve_result_pipe); | 804 | if (pos->client == c) |
913 | resolve_result_pipe = NULL; | 805 | { |
806 | pos->client = NULL; | ||
807 | } | ||
808 | pos = pos->next; | ||
914 | } | 809 | } |
915 | #endif | ||
916 | GNUNET_assert (c == internal_cls); | 810 | GNUNET_assert (c == internal_cls); |
917 | } | 811 | } |
918 | 812 | ||
@@ -923,7 +817,7 @@ disconnect_cb (void *cls, | |||
923 | GNUNET_SERVICE_MAIN | 817 | GNUNET_SERVICE_MAIN |
924 | ("resolver", | 818 | ("resolver", |
925 | GNUNET_SERVICE_OPTION_NONE, | 819 | GNUNET_SERVICE_OPTION_NONE, |
926 | NULL, | 820 | &init_cb, |
927 | &connect_cb, | 821 | &connect_cb, |
928 | &disconnect_cb, | 822 | &disconnect_cb, |
929 | NULL, | 823 | NULL, |
@@ -950,23 +844,4 @@ GNUNET_RESOLVER_memory_init () | |||
950 | #endif | 844 | #endif |
951 | 845 | ||
952 | 846 | ||
953 | /** | ||
954 | * Free globals on exit. | ||
955 | */ | ||
956 | void __attribute__ ((destructor)) | ||
957 | GNUNET_RESOLVER_memory_done () | ||
958 | { | ||
959 | struct IPCache *pos; | ||
960 | |||
961 | while (NULL != (pos = cache_head)) | ||
962 | { | ||
963 | GNUNET_CONTAINER_DLL_remove (cache_head, | ||
964 | cache_tail, | ||
965 | pos); | ||
966 | GNUNET_free_non_null (pos->addr); | ||
967 | GNUNET_free (pos); | ||
968 | } | ||
969 | } | ||
970 | |||
971 | |||
972 | /* end of gnunet-service-resolver.c */ | 847 | /* end of gnunet-service-resolver.c */ |
diff --git a/src/util/resolver.h b/src/util/resolver.h index a0f105afa..07851d052 100644 --- a/src/util/resolver.h +++ b/src/util/resolver.h | |||
@@ -60,7 +60,7 @@ struct GNUNET_RESOLVER_GetMessage | |||
60 | * identifies the request and is contained in the response message. The | 60 | * identifies the request and is contained in the response message. The |
61 | * client has to match response to request by this identifier. | 61 | * client has to match response to request by this identifier. |
62 | */ | 62 | */ |
63 | uint32_t id GNUNET_PACKED; | 63 | uint16_t id GNUNET_PACKED; |
64 | 64 | ||
65 | /* followed by 0-terminated string for A/AAAA-lookup or | 65 | /* followed by 0-terminated string for A/AAAA-lookup or |
66 | by 'struct in_addr' / 'struct in6_addr' for reverse lookup */ | 66 | by 'struct in_addr' / 'struct in6_addr' for reverse lookup */ |
@@ -79,7 +79,7 @@ struct GNUNET_RESOLVER_ResponseMessage | |||
79 | * identifies the request this message responds to. The client | 79 | * identifies the request this message responds to. The client |
80 | * has to match response to request by this identifier. | 80 | * has to match response to request by this identifier. |
81 | */ | 81 | */ |
82 | uint32_t id GNUNET_PACKED; | 82 | uint16_t id GNUNET_PACKED; |
83 | 83 | ||
84 | /* followed by 0-terminated string for response to a reverse lookup | 84 | /* followed by 0-terminated string for response to a reverse lookup |
85 | * or by 'struct in_addr' / 'struct in6_addr' for response to | 85 | * or by 'struct in_addr' / 'struct in6_addr' for response to |
diff --git a/src/util/resolver_api.c b/src/util/resolver_api.c index b94819f06..8a054327b 100644 --- a/src/util/resolver_api.c +++ b/src/util/resolver_api.c | |||
@@ -68,10 +68,10 @@ static struct GNUNET_RESOLVER_RequestHandle *req_head; | |||
68 | */ | 68 | */ |
69 | static struct GNUNET_RESOLVER_RequestHandle *req_tail; | 69 | static struct GNUNET_RESOLVER_RequestHandle *req_tail; |
70 | 70 | ||
71 | /** | 71 | ///** |
72 | * ID of the last request we sent to the service | 72 | // * ID of the last request we sent to the service |
73 | */ | 73 | // */ |
74 | static uint32_t last_request_id; | 74 | //static uint16_t last_request_id; |
75 | 75 | ||
76 | /** | 76 | /** |
77 | * How long should we wait to reconnect? | 77 | * How long should we wait to reconnect? |
@@ -445,7 +445,7 @@ process_requests () | |||
445 | GNUNET_MESSAGE_TYPE_RESOLVER_REQUEST); | 445 | GNUNET_MESSAGE_TYPE_RESOLVER_REQUEST); |
446 | msg->direction = htonl (rh->direction); | 446 | msg->direction = htonl (rh->direction); |
447 | msg->af = htonl (rh->af); | 447 | msg->af = htonl (rh->af); |
448 | msg->id = htonl (rh->id); | 448 | msg->id = htons (rh->id); |
449 | GNUNET_memcpy (&msg[1], | 449 | GNUNET_memcpy (&msg[1], |
450 | &rh[1], | 450 | &rh[1], |
451 | rh->data_len); | 451 | rh->data_len); |
@@ -491,7 +491,7 @@ handle_response (void *cls, | |||
491 | struct GNUNET_RESOLVER_RequestHandle *rh = req_head; | 491 | struct GNUNET_RESOLVER_RequestHandle *rh = req_head; |
492 | uint16_t size; | 492 | uint16_t size; |
493 | char *nret; | 493 | char *nret; |
494 | uint32_t request_id = msg->id; | 494 | uint16_t request_id = msg->id; |
495 | 495 | ||
496 | for (; rh != NULL; rh = rh->next) | 496 | for (; rh != NULL; rh = rh->next) |
497 | { | 497 | { |
@@ -911,6 +911,14 @@ handle_lookup_timeout (void *cls) | |||
911 | } | 911 | } |
912 | 912 | ||
913 | 913 | ||
914 | static uint16_t | ||
915 | get_request_id () | ||
916 | { | ||
917 | return (uint16_t) GNUNET_CRYPTO_random_u32 (GNUNET_CRYPTO_QUALITY_NONCE, | ||
918 | UINT16_MAX); | ||
919 | } | ||
920 | |||
921 | |||
914 | /** | 922 | /** |
915 | * Convert a string to one or more IP addresses. | 923 | * Convert a string to one or more IP addresses. |
916 | * | 924 | * |
@@ -945,7 +953,8 @@ GNUNET_RESOLVER_ip_get (const char *hostname, | |||
945 | hostname); | 953 | hostname); |
946 | rh = GNUNET_malloc (sizeof (struct GNUNET_RESOLVER_RequestHandle) + slen); | 954 | rh = GNUNET_malloc (sizeof (struct GNUNET_RESOLVER_RequestHandle) + slen); |
947 | rh->af = af; | 955 | rh->af = af; |
948 | rh->id = ++last_request_id; | 956 | //rh->id = ++last_request_id; |
957 | rh->id = get_request_id (); | ||
949 | rh->addr_callback = callback; | 958 | rh->addr_callback = callback; |
950 | rh->cls = callback_cls; | 959 | rh->cls = callback_cls; |
951 | GNUNET_memcpy (&rh[1], | 960 | GNUNET_memcpy (&rh[1], |
@@ -1092,7 +1101,8 @@ GNUNET_RESOLVER_hostname_get (const struct sockaddr *sa, | |||
1092 | rh->name_callback = callback; | 1101 | rh->name_callback = callback; |
1093 | rh->cls = cls; | 1102 | rh->cls = cls; |
1094 | rh->af = sa->sa_family; | 1103 | rh->af = sa->sa_family; |
1095 | rh->id = ++last_request_id; | 1104 | //rh->id = ++last_request_id; |
1105 | rh->id = get_request_id (); | ||
1096 | rh->timeout = GNUNET_TIME_relative_to_absolute (timeout); | 1106 | rh->timeout = GNUNET_TIME_relative_to_absolute (timeout); |
1097 | GNUNET_memcpy (&rh[1], | 1107 | GNUNET_memcpy (&rh[1], |
1098 | ip, | 1108 | ip, |