diff options
author | Julius Bünger <buenger@mytum.de> | 2018-06-28 10:36:39 +0200 |
---|---|---|
committer | Julius Bünger <buenger@mytum.de> | 2018-06-28 10:36:39 +0200 |
commit | bdce99417112727263204dfc3194e926d6f96b03 (patch) | |
tree | c30e7144ec9e7d54f767de5a33e459e4d456cb99 /doc/documentation | |
parent | aab6c1174f7868000b21738142a8b16e222d1835 (diff) | |
download | gnunet-bdce99417112727263204dfc3194e926d6f96b03.tar.gz gnunet-bdce99417112727263204dfc3194e926d6f96b03.zip |
doc: move check install and configuration to installation
Diffstat (limited to 'doc/documentation')
-rw-r--r-- | doc/documentation/chapters/installation.texi | 2009 | ||||
-rw-r--r-- | doc/documentation/chapters/user.texi | 2007 | ||||
-rw-r--r-- | doc/documentation/gnunet.texi | 5 |
3 files changed, 2010 insertions, 2011 deletions
diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi index d66d72ae5..f5e38fd3d 100644 --- a/doc/documentation/chapters/installation.texi +++ b/doc/documentation/chapters/installation.texi | |||
@@ -156,3 +156,2012 @@ USER_ONLY = NO | |||
156 | [transport] | 156 | [transport] |
157 | PLUGINS = tcp | 157 | PLUGINS = tcp |
158 | @end example | 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/user.texi b/doc/documentation/chapters/user.texi index 3e65cdc0e..fe47abb86 100644 --- a/doc/documentation/chapters/user.texi +++ b/doc/documentation/chapters/user.texi | |||
@@ -27,9 +27,6 @@ always welcome. | |||
27 | * File-sharing:: | 27 | * File-sharing:: |
28 | * The GNU Name System:: | 28 | * The GNU Name System:: |
29 | * Using the Virtual Public Network:: | 29 | * Using the Virtual Public Network:: |
30 | * MOVE TO INSTALL The graphical configuration interface:: | ||
31 | * MOVE TO INSTALL Checking the Installation:: | ||
32 | * MOVE TO INSTALL Config Leftovers:: | ||
33 | @end menu | 30 | @end menu |
34 | 31 | ||
35 | @node Start and stop GNUnet | 32 | @node Start and stop GNUnet |
@@ -1957,2007 +1954,3 @@ protocol (--tcp or --udp) and you will again receive an IP address | |||
1957 | that will terminate at the respective peer's service. | 1954 | that will terminate at the respective peer's service. |
1958 | 1955 | ||
1959 | 1956 | ||
1960 | |||
1961 | @c NOTE: Inserted from Installation Handbook in original ``order'': | ||
1962 | @c FIXME: Move this to User Handbook. | ||
1963 | @node MOVE TO INSTALL The graphical configuration interface | ||
1964 | @section MOVE TO INSTALL The graphical configuration interface | ||
1965 | |||
1966 | If you also would like to use @command{gnunet-gtk} and | ||
1967 | @command{gnunet-setup} (highly recommended for beginners), do: | ||
1968 | |||
1969 | @menu | ||
1970 | * Configuring your peer:: | ||
1971 | * Configuring the Friend-to-Friend (F2F) mode:: | ||
1972 | * Configuring the hostlist to bootstrap:: | ||
1973 | * Configuration of the HOSTLIST proxy settings:: | ||
1974 | * Configuring your peer to provide a hostlist :: | ||
1975 | * Configuring the datastore:: | ||
1976 | * Configuring the MySQL database:: | ||
1977 | * Reasons for using MySQL:: | ||
1978 | * Reasons for not using MySQL:: | ||
1979 | * Setup Instructions:: | ||
1980 | * Testing:: | ||
1981 | * Performance Tuning:: | ||
1982 | * Setup for running Testcases:: | ||
1983 | * Configuring the Postgres database:: | ||
1984 | * Reasons to use Postgres:: | ||
1985 | * Reasons not to use Postgres:: | ||
1986 | * Manual setup instructions:: | ||
1987 | * Testing the setup manually:: | ||
1988 | * Configuring the datacache:: | ||
1989 | * Configuring the file-sharing service:: | ||
1990 | * Configuring logging:: | ||
1991 | * Configuring the transport service and plugins:: | ||
1992 | * Configuring the WLAN transport plugin:: | ||
1993 | * Configuring HTTP(S) reverse proxy functionality using Apache or nginx:: | ||
1994 | * Blacklisting peers:: | ||
1995 | * Configuration of the HTTP and HTTPS transport plugins:: | ||
1996 | * Configuring the GNU Name System:: | ||
1997 | * Configuring the GNUnet VPN:: | ||
1998 | * Bandwidth Configuration:: | ||
1999 | * Configuring NAT:: | ||
2000 | * Peer configuration for distributions:: | ||
2001 | @end menu | ||
2002 | |||
2003 | @node Configuring your peer | ||
2004 | @subsection Configuring your peer | ||
2005 | |||
2006 | This chapter will describe the various configuration options in GNUnet. | ||
2007 | |||
2008 | The easiest way to configure your peer is to use the | ||
2009 | @command{gnunet-setup} tool. | ||
2010 | @command{gnunet-setup} is part of the @command{gnunet-gtk} | ||
2011 | application. You might have to install it separately. | ||
2012 | |||
2013 | Many of the specific sections from this chapter actually are linked from | ||
2014 | within @command{gnunet-setup} to help you while using the setup tool. | ||
2015 | |||
2016 | While you can also configure your peer by editing the configuration | ||
2017 | file by hand, this is not recommended for anyone except for developers | ||
2018 | as it requires a more in-depth understanding of the configuration files | ||
2019 | and internal dependencies of GNUnet. | ||
2020 | |||
2021 | @node Configuring the Friend-to-Friend (F2F) mode | ||
2022 | @subsection Configuring the Friend-to-Friend (F2F) mode | ||
2023 | |||
2024 | GNUnet knows three basic modes of operation: | ||
2025 | @itemize @bullet | ||
2026 | @item In standard "peer-to-peer" mode, | ||
2027 | your peer will connect to any peer. | ||
2028 | @item In the pure "friend-to-friend" | ||
2029 | mode, your peer will ONLY connect to peers from a list of friends | ||
2030 | specified in the configuration. | ||
2031 | @item Finally, in mixed mode, | ||
2032 | GNUnet will only connect to arbitrary peers if it | ||
2033 | has at least a specified number of connections to friends. | ||
2034 | @end itemize | ||
2035 | |||
2036 | When configuring any of the F2F ("friend-to-friend") modes, | ||
2037 | you first need to create a file with the peer identities | ||
2038 | of your friends. Ask your friends to run | ||
2039 | |||
2040 | @example | ||
2041 | $ gnunet-peerinfo -sq | ||
2042 | @end example | ||
2043 | |||
2044 | @noindent | ||
2045 | The resulting output of this command needs to be added to your | ||
2046 | @file{friends} file, which is simply a plain text file with one line | ||
2047 | per friend with the output from the above command. | ||
2048 | |||
2049 | You then specify the location of your @file{friends} file in the | ||
2050 | @code{FRIENDS} option of the "topology" section. | ||
2051 | |||
2052 | Once you have created the @file{friends} file, you can tell GNUnet to only | ||
2053 | connect to your friends by setting the @code{FRIENDS-ONLY} option | ||
2054 | (again in the "topology" section) to YES. | ||
2055 | |||
2056 | If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a | ||
2057 | minimum number of friends to have (before connecting to arbitrary peers) | ||
2058 | under the "MINIMUM-FRIENDS" option. | ||
2059 | |||
2060 | If you want to operate in normal P2P-only mode, simply set | ||
2061 | @code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO. | ||
2062 | This is the default. | ||
2063 | |||
2064 | @node Configuring the hostlist to bootstrap | ||
2065 | @subsection Configuring the hostlist to bootstrap | ||
2066 | |||
2067 | After installing the software you need to get connected to the GNUnet | ||
2068 | network. The configuration file included in your download is already | ||
2069 | configured to connect you to the GNUnet network. | ||
2070 | In this section the relevant configuration settings are explained. | ||
2071 | |||
2072 | To get an initial connection to the GNUnet network and to get to know | ||
2073 | peers already connected to the network you can use the so called | ||
2074 | "bootstrap servers". | ||
2075 | These servers can give you a list of peers connected to the network. | ||
2076 | To use these bootstrap servers you have to configure the hostlist daemon | ||
2077 | to activate bootstrapping. | ||
2078 | |||
2079 | To activate bootstrapping, edit the @code{[hostlist]}-section in your | ||
2080 | configuration file. You have to set the argument @command{-b} in the | ||
2081 | options line: | ||
2082 | |||
2083 | @example | ||
2084 | [hostlist] | ||
2085 | OPTIONS = -b | ||
2086 | @end example | ||
2087 | |||
2088 | Additionally you have to specify which server you want to use. | ||
2089 | The default bootstrapping server is | ||
2090 | "@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}". | ||
2091 | [^] To set the server you have to edit the line "SERVERS" in the hostlist | ||
2092 | section. To use the default server you should set the lines to | ||
2093 | |||
2094 | @example | ||
2095 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
2096 | @end example | ||
2097 | |||
2098 | @noindent | ||
2099 | To use bootstrapping your configuration file should include these lines: | ||
2100 | |||
2101 | @example | ||
2102 | [hostlist] | ||
2103 | OPTIONS = -b | ||
2104 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
2105 | @end example | ||
2106 | |||
2107 | @noindent | ||
2108 | Besides using bootstrap servers you can configure your GNUnet peer to | ||
2109 | receive hostlist advertisements. | ||
2110 | Peers offering hostlists to other peers can send advertisement messages | ||
2111 | to peers that connect to them. If you configure your peer to receive these | ||
2112 | messages, your peer can download these lists and connect to the peers | ||
2113 | included. These lists are persistent, which means that they are saved to | ||
2114 | your hard disk regularly and are loaded during startup. | ||
2115 | |||
2116 | To activate hostlist learning you have to add the @command{-e} | ||
2117 | switch to the @code{OPTIONS} line in the hostlist section: | ||
2118 | |||
2119 | @example | ||
2120 | [hostlist] | ||
2121 | OPTIONS = -b -e | ||
2122 | @end example | ||
2123 | |||
2124 | @noindent | ||
2125 | Furthermore you can specify in which file the lists are saved. | ||
2126 | To save the lists in the file @file{hostlists.file} just add the line: | ||
2127 | |||
2128 | @example | ||
2129 | HOSTLISTFILE = hostlists.file | ||
2130 | @end example | ||
2131 | |||
2132 | @noindent | ||
2133 | Best practice is to activate both bootstrapping and hostlist learning. | ||
2134 | So your configuration file should include these lines: | ||
2135 | |||
2136 | @example | ||
2137 | [hostlist] | ||
2138 | OPTIONS = -b -e | ||
2139 | HTTPPORT = 8080 | ||
2140 | SERVERS = http://v10.gnunet.org/hostlist [^] | ||
2141 | HOSTLISTFILE = $SERVICEHOME/hostlists.file | ||
2142 | @end example | ||
2143 | |||
2144 | @node Configuration of the HOSTLIST proxy settings | ||
2145 | @subsection Configuration of the HOSTLIST proxy settings | ||
2146 | |||
2147 | The hostlist client can be configured to use a proxy to connect to the | ||
2148 | hostlist server. | ||
2149 | This functionality can be configured in the configuration file directly | ||
2150 | or using the @command{gnunet-setup} tool. | ||
2151 | |||
2152 | The hostlist client supports the following proxy types at the moment: | ||
2153 | |||
2154 | @itemize @bullet | ||
2155 | @item HTTP and HTTP 1.0 only proxy | ||
2156 | @item SOCKS 4/4a/5/5 with hostname | ||
2157 | @end itemize | ||
2158 | |||
2159 | In addition authentication at the proxy with username and password can be | ||
2160 | configured. | ||
2161 | |||
2162 | To configure proxy support for the hostlist client in the | ||
2163 | @command{gnunet-setup} tool, select the "hostlist" tab and select | ||
2164 | the appropriate proxy type. | ||
2165 | The hostname or IP address (including port if required) has to be entered | ||
2166 | in the "Proxy hostname" textbox. If required, enter username and password | ||
2167 | in the "Proxy username" and "Proxy password" boxes. | ||
2168 | Be aware that this information will be stored in the configuration in | ||
2169 | plain text (TODO: Add explanation and generalize the part in Chapter 3.6 | ||
2170 | about the encrypted home). | ||
2171 | |||
2172 | To provide these options directly in the configuration, you can | ||
2173 | enter the following settings in the @code{[hostlist]} section of | ||
2174 | the configuration: | ||
2175 | |||
2176 | @example | ||
2177 | # Type of proxy server, | ||
2178 | # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME | ||
2179 | # Default: HTTP | ||
2180 | # PROXY_TYPE = HTTP | ||
2181 | |||
2182 | # Hostname or IP of proxy server | ||
2183 | # PROXY = | ||
2184 | # User name for proxy server | ||
2185 | # PROXY_USERNAME = | ||
2186 | # User password for proxy server | ||
2187 | # PROXY_PASSWORD = | ||
2188 | @end example | ||
2189 | |||
2190 | @node Configuring your peer to provide a hostlist | ||
2191 | @subsection Configuring your peer to provide a hostlist | ||
2192 | |||
2193 | If you operate a peer permanently connected to GNUnet you can configure | ||
2194 | your peer to act as a hostlist server, providing other peers the list of | ||
2195 | peers known to him. | ||
2196 | |||
2197 | Your server can act as a bootstrap server and peers needing to obtain a | ||
2198 | list of peers can contact it to download this list. | ||
2199 | To download this hostlist the peer uses HTTP. | ||
2200 | For this reason you have to build your peer with libgnurl (or libcurl) | ||
2201 | and microhttpd support. | ||
2202 | |||
2203 | To configure your peer to act as a bootstrap server you have to add the | ||
2204 | @command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section | ||
2205 | of your configuration file. | ||
2206 | Besides that you have to specify a port number for the http server. | ||
2207 | In conclusion you have to add the following lines: | ||
2208 | |||
2209 | @example | ||
2210 | [hostlist] | ||
2211 | HTTPPORT = 12980 | ||
2212 | OPTIONS = -p | ||
2213 | @end example | ||
2214 | |||
2215 | @noindent | ||
2216 | If your peer acts as a bootstrap server other peers should know about | ||
2217 | that. You can advertise the hostlist your are providing to other peers. | ||
2218 | Peers connecting to your peer will get a message containing an | ||
2219 | advertisement for your hostlist and the URL where it can be downloaded. | ||
2220 | If this peer is in learning mode, it will test the hostlist and, in the | ||
2221 | case it can obtain the list successfully, it will save it for | ||
2222 | bootstrapping. | ||
2223 | |||
2224 | To activate hostlist advertisement on your peer, you have to set the | ||
2225 | following lines in your configuration file: | ||
2226 | |||
2227 | @example | ||
2228 | [hostlist] | ||
2229 | EXTERNAL_DNS_NAME = example.org | ||
2230 | HTTPPORT = 12981 | ||
2231 | OPTIONS = -p -a | ||
2232 | @end example | ||
2233 | |||
2234 | @noindent | ||
2235 | With this configuration your peer will a act as a bootstrap server and | ||
2236 | advertise this hostlist to other peers connecting to it. | ||
2237 | The URL used to download the list will be | ||
2238 | @code{@uref{http://example.org:12981/, http://example.org:12981/}}. | ||
2239 | |||
2240 | Please notice: | ||
2241 | |||
2242 | @itemize @bullet | ||
2243 | @item The hostlist is @b{not} human readable, so you should not try to | ||
2244 | download it using your webbrowser. Just point your GNUnet peer to the | ||
2245 | address! | ||
2246 | @item Advertising without providing a hostlist does not make sense and | ||
2247 | will not work. | ||
2248 | @end itemize | ||
2249 | |||
2250 | @node Configuring the datastore | ||
2251 | @subsection Configuring the datastore | ||
2252 | |||
2253 | The datastore is what GNUnet uses for long-term storage of file-sharing | ||
2254 | data. Note that long-term does not mean 'forever' since content does have | ||
2255 | an expiration date, and of course storage space is finite (and hence | ||
2256 | sometimes content may have to be discarded). | ||
2257 | |||
2258 | Use the @code{QUOTA} option to specify how many bytes of storage space | ||
2259 | you are willing to dedicate to GNUnet. | ||
2260 | |||
2261 | In addition to specifying the maximum space GNUnet is allowed to use for | ||
2262 | the datastore, you need to specify which database GNUnet should use to do | ||
2263 | so. Currently, you have the choice between sqLite, MySQL and Postgres. | ||
2264 | |||
2265 | @node Configuring the MySQL database | ||
2266 | @subsection Configuring the MySQL database | ||
2267 | |||
2268 | This section describes how to setup the MySQL database for GNUnet. | ||
2269 | |||
2270 | Note that the mysql plugin does NOT work with mysql before 4.1 since we | ||
2271 | need prepared statements. | ||
2272 | We are generally testing the code against MySQL 5.1 at this point. | ||
2273 | |||
2274 | @node Reasons for using MySQL | ||
2275 | @subsection Reasons for using MySQL | ||
2276 | |||
2277 | @itemize @bullet | ||
2278 | |||
2279 | @item On up-to-date hardware wher | ||
2280 | mysql can be used comfortably, this module | ||
2281 | will have better performance than the other database choices (according | ||
2282 | to our tests). | ||
2283 | |||
2284 | @item Its often possible to recover the mysql database from internal | ||
2285 | inconsistencies. Some of the other databases do not support repair. | ||
2286 | @end itemize | ||
2287 | |||
2288 | @node Reasons for not using MySQL | ||
2289 | @subsection Reasons for not using MySQL | ||
2290 | |||
2291 | @itemize @bullet | ||
2292 | @item Memory usage (likely not an issue if you have more than 1 GB) | ||
2293 | @item Complex manual setup | ||
2294 | @end itemize | ||
2295 | |||
2296 | @node Setup Instructions | ||
2297 | @subsection Setup Instructions | ||
2298 | |||
2299 | @itemize @bullet | ||
2300 | |||
2301 | @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for | ||
2302 | @code{DATABASE} to @code{mysql}. | ||
2303 | |||
2304 | @item Access mysql as root: | ||
2305 | |||
2306 | @example | ||
2307 | $ mysql -u root -p | ||
2308 | @end example | ||
2309 | |||
2310 | @noindent | ||
2311 | and issue the following commands, replacing $USER with the username | ||
2312 | that will be running @command{gnunet-arm} (so typically "gnunet"): | ||
2313 | |||
2314 | @example | ||
2315 | CREATE DATABASE gnunet; | ||
2316 | GRANT select,insert,update,delete,create,alter,drop,create \ | ||
2317 | temporary tables ON gnunet.* TO $USER@@localhost; | ||
2318 | SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); | ||
2319 | FLUSH PRIVILEGES; | ||
2320 | @end example | ||
2321 | |||
2322 | @item | ||
2323 | In the $HOME directory of $USER, create a @file{.my.cnf} file with the | ||
2324 | following lines | ||
2325 | |||
2326 | @example | ||
2327 | [client] | ||
2328 | user=$USER | ||
2329 | password=$the_password_you_like | ||
2330 | @end example | ||
2331 | |||
2332 | @end itemize | ||
2333 | |||
2334 | That's it. Note that @file{.my.cnf} file is a slight security risk unless | ||
2335 | its on a safe partition. The @file{$HOME/.my.cnf} can of course be | ||
2336 | a symbolic link. | ||
2337 | Luckily $USER has only privileges to mess up GNUnet's tables, | ||
2338 | which should be pretty harmless. | ||
2339 | |||
2340 | @node Testing | ||
2341 | @subsection Testing | ||
2342 | |||
2343 | You should briefly try if the database connection works. First, login | ||
2344 | as $USER. Then use: | ||
2345 | |||
2346 | @example | ||
2347 | $ mysql -u $USER | ||
2348 | mysql> use gnunet; | ||
2349 | @end example | ||
2350 | |||
2351 | @noindent | ||
2352 | If you get the message | ||
2353 | |||
2354 | @example | ||
2355 | Database changed | ||
2356 | @end example | ||
2357 | |||
2358 | @noindent | ||
2359 | it probably works. | ||
2360 | |||
2361 | If you get | ||
2362 | |||
2363 | @example | ||
2364 | ERROR 2002: Can't connect to local MySQL server | ||
2365 | through socket '/tmp/mysql.sock' (2) | ||
2366 | @end example | ||
2367 | |||
2368 | @noindent | ||
2369 | it may be resolvable by | ||
2370 | |||
2371 | @example | ||
2372 | ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock | ||
2373 | @end example | ||
2374 | |||
2375 | @noindent | ||
2376 | so there may be some additional trouble depending on your mysql setup. | ||
2377 | |||
2378 | @node Performance Tuning | ||
2379 | @subsection Performance Tuning | ||
2380 | |||
2381 | For GNUnet, you probably want to set the option | ||
2382 | |||
2383 | @example | ||
2384 | innodb_flush_log_at_trx_commit = 0 | ||
2385 | @end example | ||
2386 | |||
2387 | @noindent | ||
2388 | for a rather dramatic boost in MySQL performance. However, this reduces | ||
2389 | the "safety" of your database as with this options you may loose | ||
2390 | transactions during a power outage. | ||
2391 | While this is totally harmless for GNUnet, the option applies to all | ||
2392 | applications using MySQL. So you should set it if (and only if) GNUnet is | ||
2393 | the only application on your system using MySQL. | ||
2394 | |||
2395 | @node Setup for running Testcases | ||
2396 | @subsection Setup for running Testcases | ||
2397 | |||
2398 | If you want to run the testcases, you must create a second database | ||
2399 | "gnunetcheck" with the same username and password. This database will | ||
2400 | then be used for testing (@command{make check}). | ||
2401 | |||
2402 | @node Configuring the Postgres database | ||
2403 | @subsection Configuring the Postgres database | ||
2404 | |||
2405 | This text describes how to setup the Postgres database for GNUnet. | ||
2406 | |||
2407 | This Postgres plugin was developed for Postgres 8.3 but might work for | ||
2408 | earlier versions as well. | ||
2409 | |||
2410 | @node Reasons to use Postgres | ||
2411 | @subsection Reasons to use Postgres | ||
2412 | |||
2413 | @itemize @bullet | ||
2414 | @item Easier to setup than MySQL | ||
2415 | @item Real database | ||
2416 | @end itemize | ||
2417 | |||
2418 | @node Reasons not to use Postgres | ||
2419 | @subsection Reasons not to use Postgres | ||
2420 | |||
2421 | @itemize @bullet | ||
2422 | @item Quite slow | ||
2423 | @item Still some manual setup required | ||
2424 | @end itemize | ||
2425 | |||
2426 | @node Manual setup instructions | ||
2427 | @subsection Manual setup instructions | ||
2428 | |||
2429 | @itemize @bullet | ||
2430 | @item In @file{gnunet.conf} set in section @code{DATASTORE} the value for | ||
2431 | @code{DATABASE} to @code{postgres}. | ||
2432 | @item Access Postgres to create a user: | ||
2433 | |||
2434 | @table @asis | ||
2435 | @item with Postgres 8.x, use: | ||
2436 | |||
2437 | @example | ||
2438 | # su - postgres | ||
2439 | $ createuser | ||
2440 | @end example | ||
2441 | |||
2442 | @noindent | ||
2443 | and enter the name of the user running GNUnet for the role interactively. | ||
2444 | Then, when prompted, do not set it to superuser, allow the creation of | ||
2445 | databases, and do not allow the creation of new roles. | ||
2446 | |||
2447 | @item with Postgres 9.x, use: | ||
2448 | |||
2449 | @example | ||
2450 | # su - postgres | ||
2451 | $ createuser -d $GNUNET_USER | ||
2452 | @end example | ||
2453 | |||
2454 | @noindent | ||
2455 | where $GNUNET_USER is the name of the user running GNUnet. | ||
2456 | |||
2457 | @end table | ||
2458 | |||
2459 | |||
2460 | @item | ||
2461 | As that user (so typically as user "gnunet"), create a database (or two): | ||
2462 | |||
2463 | @example | ||
2464 | $ createdb gnunet | ||
2465 | # this way you can run "make check" | ||
2466 | $ createdb gnunetcheck | ||
2467 | @end example | ||
2468 | |||
2469 | @end itemize | ||
2470 | |||
2471 | Now you should be able to start @code{gnunet-arm}. | ||
2472 | |||
2473 | @node Testing the setup manually | ||
2474 | @subsection Testing the setup manually | ||
2475 | |||
2476 | You may want to try if the database connection works. First, again login | ||
2477 | as the user who will run @command{gnunet-arm}. Then use: | ||
2478 | |||
2479 | @example | ||
2480 | $ psql gnunet # or gnunetcheck | ||
2481 | gnunet=> \dt | ||
2482 | @end example | ||
2483 | |||
2484 | @noindent | ||
2485 | If, after you have started @command{gnunet-arm} at least once, you get | ||
2486 | a @code{gn090} table here, it probably works. | ||
2487 | |||
2488 | @node Configuring the datacache | ||
2489 | @subsection Configuring the datacache | ||
2490 | @c %**end of header | ||
2491 | |||
2492 | The datacache is what GNUnet uses for storing temporary data. This data is | ||
2493 | expected to be wiped completely each time GNUnet is restarted (or the | ||
2494 | system is rebooted). | ||
2495 | |||
2496 | You need to specify how many bytes GNUnet is allowed to use for the | ||
2497 | datacache using the @code{QUOTA} option in the section @code{[dhtcache]}. | ||
2498 | Furthermore, you need to specify which database backend should be used to | ||
2499 | store the data. Currently, you have the choice between | ||
2500 | sqLite, MySQL and Postgres. | ||
2501 | |||
2502 | @node Configuring the file-sharing service | ||
2503 | @subsection Configuring the file-sharing service | ||
2504 | |||
2505 | In order to use GNUnet for file-sharing, you first need to make sure | ||
2506 | that the file-sharing service is loaded. | ||
2507 | This is done by setting the @code{START_ON_DEMAND} option in | ||
2508 | section @code{[fs]} to "YES". Alternatively, you can run | ||
2509 | |||
2510 | @example | ||
2511 | $ gnunet-arm -i fs | ||
2512 | @end example | ||
2513 | |||
2514 | @noindent | ||
2515 | to start the file-sharing service by hand. | ||
2516 | |||
2517 | Except for configuring the database and the datacache the only important | ||
2518 | option for file-sharing is content migration. | ||
2519 | |||
2520 | Content migration allows your peer to cache content from other peers as | ||
2521 | well as send out content stored on your system without explicit requests. | ||
2522 | This content replication has positive and negative impacts on both system | ||
2523 | performance and privacy. | ||
2524 | |||
2525 | FIXME: discuss the trade-offs. Here is some older text about it... | ||
2526 | |||
2527 | Setting this option to YES allows gnunetd to migrate data to the local | ||
2528 | machine. Setting this option to YES is highly recommended for efficiency. | ||
2529 | Its also the default. If you set this value to YES, GNUnet will store | ||
2530 | content on your machine that you cannot decrypt. | ||
2531 | While this may protect you from liability if the judge is sane, it may | ||
2532 | not (IANAL). If you put illegal content on your machine yourself, setting | ||
2533 | this option to YES will probably increase your chances to get away with it | ||
2534 | since you can plausibly deny that you inserted the content. | ||
2535 | Note that in either case, your anonymity would have to be broken first | ||
2536 | (which may be possible depending on the size of the GNUnet network and the | ||
2537 | strength of the adversary). | ||
2538 | |||
2539 | @node Configuring logging | ||
2540 | @subsection Configuring logging | ||
2541 | |||
2542 | Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. | ||
2543 | Using @code{-L}, a log level can be specified. With log level | ||
2544 | @code{ERROR} only serious errors are logged. | ||
2545 | The default log level is @code{WARNING} which causes anything of | ||
2546 | concern to be logged. | ||
2547 | Log level @code{INFO} can be used to log anything that might be | ||
2548 | interesting information whereas | ||
2549 | @code{DEBUG} can be used by developers to log debugging messages | ||
2550 | (but you need to run @code{./configure} with | ||
2551 | @code{--enable-logging=verbose} to get them compiled). | ||
2552 | The @code{-l} option is used to specify the log file. | ||
2553 | |||
2554 | Since most GNUnet services are managed by @code{gnunet-arm}, using the | ||
2555 | @code{-l} or @code{-L} options directly is not possible. | ||
2556 | Instead, they can be specified using the @code{OPTIONS} configuration | ||
2557 | value in the respective section for the respective service. | ||
2558 | In order to enable logging globally without editing the @code{OPTIONS} | ||
2559 | values for each service, @command{gnunet-arm} supports a | ||
2560 | @code{GLOBAL_POSTFIX} option. | ||
2561 | The value specified here is given as an extra option to all services for | ||
2562 | which the configuration does contain a service-specific @code{OPTIONS} | ||
2563 | field. | ||
2564 | |||
2565 | @code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which | ||
2566 | is replaced by the name of the service that is being started. | ||
2567 | Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences | ||
2568 | starting with "$" anywhere in the string are expanded (according | ||
2569 | to options in @code{PATHS}); this expansion otherwise is | ||
2570 | only happening for filenames and then the "$" must be the | ||
2571 | first character in the option. Both of these restrictions do | ||
2572 | not apply to @code{GLOBAL_POSTFIX}. | ||
2573 | Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX} | ||
2574 | disables both of these features. | ||
2575 | |||
2576 | In summary, in order to get all services to log at level | ||
2577 | @code{INFO} to log-files called @code{SERVICENAME-logs}, the | ||
2578 | following global prefix should be used: | ||
2579 | |||
2580 | @example | ||
2581 | GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO | ||
2582 | @end example | ||
2583 | |||
2584 | @node Configuring the transport service and plugins | ||
2585 | @subsection Configuring the transport service and plugins | ||
2586 | |||
2587 | The transport service in GNUnet is responsible to maintain basic | ||
2588 | connectivity to other peers. | ||
2589 | Besides initiating and keeping connections alive it is also responsible | ||
2590 | for address validation. | ||
2591 | |||
2592 | The GNUnet transport supports more than one transport protocol. | ||
2593 | These protocols are configured together with the transport service. | ||
2594 | |||
2595 | The configuration section for the transport service itself is quite | ||
2596 | similar to all the other services | ||
2597 | |||
2598 | @example | ||
2599 | START_ON_DEMAND = YES | ||
2600 | @@UNIXONLY@@ PORT = 2091 | ||
2601 | HOSTNAME = localhost | ||
2602 | HOME = $SERVICEHOME | ||
2603 | CONFIG = $DEFAULTCONFIG | ||
2604 | BINARY = gnunet-service-transport | ||
2605 | #PREFIX = valgrind | ||
2606 | NEIGHBOUR_LIMIT = 50 | ||
2607 | ACCEPT_FROM = 127.0.0.1; | ||
2608 | ACCEPT_FROM6 = ::1; | ||
2609 | PLUGINS = tcp udp | ||
2610 | UNIXPATH = /tmp/gnunet-service-transport.sock | ||
2611 | @end example | ||
2612 | |||
2613 | Different are the settings for the plugins to load @code{PLUGINS}. | ||
2614 | The first setting specifies which transport plugins to load. | ||
2615 | |||
2616 | @itemize @bullet | ||
2617 | @item transport-unix | ||
2618 | A plugin for local only communication with UNIX domain sockets. Used for | ||
2619 | testing and available on unix systems only. Just set the port | ||
2620 | |||
2621 | @example | ||
2622 | [transport-unix] | ||
2623 | PORT = 22086 | ||
2624 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2625 | @end example | ||
2626 | |||
2627 | @item transport-tcp | ||
2628 | A plugin for communication with TCP. Set port to 0 for client mode with | ||
2629 | outbound only connections | ||
2630 | |||
2631 | @example | ||
2632 | [transport-tcp] | ||
2633 | # Use 0 to ONLY advertise as a peer behind NAT (no port binding) | ||
2634 | PORT = 2086 | ||
2635 | ADVERTISED_PORT = 2086 | ||
2636 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2637 | # Maximum number of open TCP connections allowed | ||
2638 | MAX_CONNECTIONS = 128 | ||
2639 | @end example | ||
2640 | |||
2641 | @item transport-udp | ||
2642 | A plugin for communication with UDP. Supports peer discovery using | ||
2643 | broadcasts. | ||
2644 | |||
2645 | @example | ||
2646 | [transport-udp] | ||
2647 | PORT = 2086 | ||
2648 | BROADCAST = YES | ||
2649 | BROADCAST_INTERVAL = 30 s | ||
2650 | MAX_BPS = 1000000 | ||
2651 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2652 | @end example | ||
2653 | |||
2654 | @item transport-http | ||
2655 | HTTP and HTTPS support is split in two part: a client plugin initiating | ||
2656 | outbound connections and a server part accepting connections from the | ||
2657 | client. The client plugin just takes the maximum number of connections as | ||
2658 | an argument. | ||
2659 | |||
2660 | @example | ||
2661 | [transport-http_client] | ||
2662 | MAX_CONNECTIONS = 128 | ||
2663 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2664 | @end example | ||
2665 | |||
2666 | @example | ||
2667 | [transport-https_client] | ||
2668 | MAX_CONNECTIONS = 128 | ||
2669 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2670 | @end example | ||
2671 | |||
2672 | @noindent | ||
2673 | The server has a port configured and the maximum number of connections. | ||
2674 | The HTTPS part has two files with the certificate key and the certificate | ||
2675 | file. | ||
2676 | |||
2677 | The server plugin supports reverse proxies, so a external hostname can be | ||
2678 | set using the @code{EXTERNAL_HOSTNAME} setting. | ||
2679 | The webserver under this address should forward the request to the peer | ||
2680 | and the configure port. | ||
2681 | |||
2682 | @example | ||
2683 | [transport-http_server] | ||
2684 | EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet | ||
2685 | PORT = 1080 | ||
2686 | MAX_CONNECTIONS = 128 | ||
2687 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2688 | @end example | ||
2689 | |||
2690 | @example | ||
2691 | [transport-https_server] | ||
2692 | PORT = 4433 | ||
2693 | CRYPTO_INIT = NORMAL | ||
2694 | KEY_FILE = https.key | ||
2695 | CERT_FILE = https.cert | ||
2696 | MAX_CONNECTIONS = 128 | ||
2697 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2698 | @end example | ||
2699 | |||
2700 | @item transport-wlan | ||
2701 | |||
2702 | The next section describes how to setup the WLAN plugin, | ||
2703 | so here only the settings. Just specify the interface to use: | ||
2704 | |||
2705 | @example | ||
2706 | [transport-wlan] | ||
2707 | # Name of the interface in monitor mode (typically monX) | ||
2708 | INTERFACE = mon0 | ||
2709 | # Real hardware, no testing | ||
2710 | TESTMODE = 0 | ||
2711 | TESTING_IGNORE_KEYS = ACCEPT_FROM; | ||
2712 | @end example | ||
2713 | @end itemize | ||
2714 | |||
2715 | @node Configuring the WLAN transport plugin | ||
2716 | @subsection Configuring the WLAN transport plugin | ||
2717 | |||
2718 | The wlan transport plugin enables GNUnet to send and to receive data on a | ||
2719 | wlan interface. | ||
2720 | It has not to be connected to a wlan network as long as sender and | ||
2721 | receiver are on the same channel. This enables you to get connection to | ||
2722 | GNUnet where no internet access is possible, for example during | ||
2723 | catastrophes or when censorship cuts you off from the internet. | ||
2724 | |||
2725 | |||
2726 | @menu | ||
2727 | * Requirements for the WLAN plugin:: | ||
2728 | * Configuration:: | ||
2729 | * Before starting GNUnet:: | ||
2730 | * Limitations and known bugs:: | ||
2731 | @end menu | ||
2732 | |||
2733 | |||
2734 | @node Requirements for the WLAN plugin | ||
2735 | @subsubsection Requirements for the WLAN plugin | ||
2736 | |||
2737 | @itemize @bullet | ||
2738 | |||
2739 | @item wlan network card with monitor support and packet injection | ||
2740 | (see @uref{http://www.aircrack-ng.org/, aircrack-ng.org}) | ||
2741 | |||
2742 | @item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with | ||
2743 | 2.6.35 and 2.6.38 | ||
2744 | |||
2745 | @item Wlantools to create the a monitor interface, tested with airmon-ng | ||
2746 | of the aircrack-ng package | ||
2747 | @end itemize | ||
2748 | |||
2749 | @node Configuration | ||
2750 | @subsubsection Configuration | ||
2751 | |||
2752 | There are the following options for the wlan plugin (they should be like | ||
2753 | this in your default config file, you only need to adjust them if the | ||
2754 | values are incorrect for your system) | ||
2755 | |||
2756 | @example | ||
2757 | # section for the wlan transport plugin | ||
2758 | [transport-wlan] | ||
2759 | # interface to use, more information in the | ||
2760 | # "Before starting GNUnet" section of the handbook. | ||
2761 | INTERFACE = mon0 | ||
2762 | # testmode for developers: | ||
2763 | # 0 use wlan interface, | ||
2764 | #1 or 2 use loopback driver for tests 1 = server, 2 = client | ||
2765 | TESTMODE = 0 | ||
2766 | @end example | ||
2767 | |||
2768 | @node Before starting GNUnet | ||
2769 | @subsubsection Before starting GNUnet | ||
2770 | |||
2771 | Before starting GNUnet, you have to make sure that your wlan interface is | ||
2772 | in monitor mode. | ||
2773 | One way to put the wlan interface into monitor mode (if your interface | ||
2774 | name is wlan0) is by executing: | ||
2775 | |||
2776 | @example | ||
2777 | sudo airmon-ng start wlan0 | ||
2778 | @end example | ||
2779 | |||
2780 | @noindent | ||
2781 | Here is an example what the result should look like: | ||
2782 | |||
2783 | @example | ||
2784 | Interface Chipset Driver | ||
2785 | wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0] | ||
2786 | (monitor mode enabled on mon0) | ||
2787 | @end example | ||
2788 | |||
2789 | @noindent | ||
2790 | The monitor interface is mon0 is the one that you have to put into the | ||
2791 | configuration file. | ||
2792 | |||
2793 | @node Limitations and known bugs | ||
2794 | @subsubsection Limitations and known bugs | ||
2795 | |||
2796 | Wlan speed is at the maximum of 1 Mbit/s because support for choosing the | ||
2797 | wlan speed with packet injection was removed in newer kernels. | ||
2798 | Please pester the kernel developers about fixing this. | ||
2799 | |||
2800 | The interface channel depends on the wlan network that the card is | ||
2801 | connected to. If no connection has been made since the start of the | ||
2802 | computer, it is usually the first channel of the card. | ||
2803 | Peers will only find each other and communicate if they are on the same | ||
2804 | channel. Channels must be set manually, i.e. using: | ||
2805 | |||
2806 | @example | ||
2807 | iwconfig wlan0 channel 1 | ||
2808 | @end example | ||
2809 | |||
2810 | @node Configuring HTTP(S) reverse proxy functionality using Apache or nginx | ||
2811 | @subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx | ||
2812 | |||
2813 | The HTTP plugin supports data transfer using reverse proxies. A reverse | ||
2814 | proxy forwards the HTTP request he receives with a certain URL to another | ||
2815 | webserver, here a GNUnet peer. | ||
2816 | |||
2817 | So if you have a running Apache or nginx webserver you can configure it to | ||
2818 | be a GNUnet reverse proxy. Especially if you have a well-known webiste | ||
2819 | this improves censorship resistance since it looks as normal surfing | ||
2820 | behaviour. | ||
2821 | |||
2822 | To do so, you have to do two things: | ||
2823 | |||
2824 | @itemize @bullet | ||
2825 | @item Configure your webserver to forward the GNUnet HTTP traffic | ||
2826 | @item Configure your GNUnet peer to announce the respective address | ||
2827 | @end itemize | ||
2828 | |||
2829 | As an example we want to use GNUnet peer running: | ||
2830 | |||
2831 | @itemize @bullet | ||
2832 | |||
2833 | @item HTTP server plugin on @code{gnunet.foo.org:1080} | ||
2834 | |||
2835 | @item HTTPS server plugin on @code{gnunet.foo.org:4433} | ||
2836 | |||
2837 | @item A apache or nginx webserver on | ||
2838 | @uref{http://www.foo.org/, http://www.foo.org:80/} | ||
2839 | |||
2840 | @item A apache or nginx webserver on https://www.foo.org:443/ | ||
2841 | @end itemize | ||
2842 | |||
2843 | And we want the webserver to accept GNUnet traffic under | ||
2844 | @code{http://www.foo.org/bar/}. The required steps are described here: | ||
2845 | |||
2846 | @menu | ||
2847 | * Reverse Proxy - Configure your Apache2 HTTP webserver:: | ||
2848 | * Reverse Proxy - Configure your Apache2 HTTPS webserver:: | ||
2849 | * Reverse Proxy - Configure your nginx HTTPS webserver:: | ||
2850 | * Reverse Proxy - Configure your nginx HTTP webserver:: | ||
2851 | * Reverse Proxy - Configure your GNUnet peer:: | ||
2852 | @end menu | ||
2853 | |||
2854 | @node Reverse Proxy - Configure your Apache2 HTTP webserver | ||
2855 | @subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver | ||
2856 | |||
2857 | First of all you need mod_proxy installed. | ||
2858 | |||
2859 | Edit your webserver configuration. Edit | ||
2860 | @code{/etc/apache2/apache2.conf} or the site-specific configuration file. | ||
2861 | |||
2862 | In the respective @code{server config},@code{virtual host} or | ||
2863 | @code{directory} section add the following lines: | ||
2864 | |||
2865 | @example | ||
2866 | ProxyTimeout 300 | ||
2867 | ProxyRequests Off | ||
2868 | <Location /bar/ > | ||
2869 | ProxyPass http://gnunet.foo.org:1080/ | ||
2870 | ProxyPassReverse http://gnunet.foo.org:1080/ | ||
2871 | </Location> | ||
2872 | @end example | ||
2873 | |||
2874 | @node Reverse Proxy - Configure your Apache2 HTTPS webserver | ||
2875 | @subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver | ||
2876 | |||
2877 | We assume that you already have an HTTPS server running, if not please | ||
2878 | check how to configure a HTTPS host. An uncomplicated to use example | ||
2879 | is the example configuration file for Apache2/HTTPD provided in | ||
2880 | @file{apache2/sites-available/default-ssl}. | ||
2881 | |||
2882 | In the respective HTTPS @code{server config},@code{virtual host} or | ||
2883 | @code{directory} section add the following lines: | ||
2884 | |||
2885 | @example | ||
2886 | SSLProxyEngine On | ||
2887 | ProxyTimeout 300 | ||
2888 | ProxyRequests Off | ||
2889 | <Location /bar/ > | ||
2890 | ProxyPass https://gnunet.foo.org:4433/ | ||
2891 | ProxyPassReverse https://gnunet.foo.org:4433/ | ||
2892 | </Location> | ||
2893 | @end example | ||
2894 | |||
2895 | @noindent | ||
2896 | More information about the apache mod_proxy configuration can be found | ||
2897 | 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}} | ||
2898 | |||
2899 | @node Reverse Proxy - Configure your nginx HTTPS webserver | ||
2900 | @subsubsection Reverse Proxy - Configure your nginx HTTPS webserver | ||
2901 | |||
2902 | Since nginx does not support chunked encoding, you first of all have to | ||
2903 | install the @code{chunkin} module@footnote{@uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule}} | ||
2904 | |||
2905 | To enable chunkin add: | ||
2906 | |||
2907 | @example | ||
2908 | chunkin on; | ||
2909 | error_page 411 = @@my_411_error; | ||
2910 | location @@my_411_error @{ | ||
2911 | chunkin_resume; | ||
2912 | @} | ||
2913 | @end example | ||
2914 | |||
2915 | @noindent | ||
2916 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or | ||
2917 | the site-specific configuration file. | ||
2918 | |||
2919 | In the @code{server} section add: | ||
2920 | |||
2921 | @example | ||
2922 | location /bar/ @{ | ||
2923 | proxy_pass http://gnunet.foo.org:1080/; | ||
2924 | proxy_buffering off; | ||
2925 | proxy_connect_timeout 5; # more than http_server | ||
2926 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout | ||
2927 | proxy_http_version 1.1; # 1.0 default | ||
2928 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; | ||
2929 | @} | ||
2930 | @end example | ||
2931 | |||
2932 | @node Reverse Proxy - Configure your nginx HTTP webserver | ||
2933 | @subsubsection Reverse Proxy - Configure your nginx HTTP webserver | ||
2934 | |||
2935 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or | ||
2936 | the site-specific configuration file. | ||
2937 | |||
2938 | In the @code{server} section add: | ||
2939 | |||
2940 | @example | ||
2941 | ssl_session_timeout 6m; | ||
2942 | location /bar/ | ||
2943 | @{ | ||
2944 | proxy_pass https://gnunet.foo.org:4433/; | ||
2945 | proxy_buffering off; | ||
2946 | proxy_connect_timeout 5; # more than http_server | ||
2947 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout | ||
2948 | proxy_http_version 1.1; # 1.0 default | ||
2949 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; | ||
2950 | @} | ||
2951 | @end example | ||
2952 | |||
2953 | @node Reverse Proxy - Configure your GNUnet peer | ||
2954 | @subsubsection Reverse Proxy - Configure your GNUnet peer | ||
2955 | |||
2956 | To have your GNUnet peer announce the address, you have to specify the | ||
2957 | @code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]} | ||
2958 | section: | ||
2959 | |||
2960 | @example | ||
2961 | [transport-http_server] | ||
2962 | EXTERNAL_HOSTNAME = http://www.foo.org/bar/ | ||
2963 | @end example | ||
2964 | |||
2965 | @noindent | ||
2966 | and/or @code{[transport-https_server]} section: | ||
2967 | |||
2968 | @example | ||
2969 | [transport-https_server] | ||
2970 | EXTERNAL_HOSTNAME = https://www.foo.org/bar/ | ||
2971 | @end example | ||
2972 | |||
2973 | @noindent | ||
2974 | Now restart your webserver and your peer... | ||
2975 | |||
2976 | @node Blacklisting peers | ||
2977 | @subsection Blacklisting peers | ||
2978 | |||
2979 | Transport service supports to deny connecting to a specific peer of to a | ||
2980 | specific peer with a specific transport plugin using te blacklisting | ||
2981 | component of transport service. With@ blacklisting it is possible to deny | ||
2982 | connections to specific peers of@ to use a specific plugin to a specific | ||
2983 | peer. Peers can be blacklisted using@ the configuration or a blacklist | ||
2984 | client can be asked. | ||
2985 | |||
2986 | To blacklist peers using the configuration you have to add a section to | ||
2987 | your configuration containing the peer id of the peer to blacklist and | ||
2988 | the plugin@ if required. | ||
2989 | |||
2990 | Examples: | ||
2991 | |||
2992 | To blacklist connections to P565... on peer AG2P... using tcp add: | ||
2993 | |||
2994 | @c FIXME: This is too long and produces errors in the pdf. | ||
2995 | @example | ||
2996 | [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] | ||
2997 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp | ||
2998 | @end example | ||
2999 | |||
3000 | To blacklist connections to P565... on peer AG2P... using all plugins add: | ||
3001 | |||
3002 | @example | ||
3003 | [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] | ||
3004 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = | ||
3005 | @end example | ||
3006 | |||
3007 | You can also add a blacklist client usign the blacklist API. On a | ||
3008 | blacklist check, blacklisting first checks internally if the peer is | ||
3009 | blacklisted and if not, it asks the blacklisting clients. Clients are | ||
3010 | asked if it is OK to connect to a peer ID, the plugin is omitted. | ||
3011 | |||
3012 | On blacklist check for (peer, plugin) | ||
3013 | @itemize @bullet | ||
3014 | @item Do we have a local blacklist entry for this peer and this plugin?@ | ||
3015 | @item YES: disallow connection@ | ||
3016 | @item Do we have a local blacklist entry for this peer and all plugins?@ | ||
3017 | @item YES: disallow connection@ | ||
3018 | @item Does one of the clients disallow?@ | ||
3019 | @item YES: disallow connection | ||
3020 | @end itemize | ||
3021 | |||
3022 | @node Configuration of the HTTP and HTTPS transport plugins | ||
3023 | @subsection Configuration of the HTTP and HTTPS transport plugins | ||
3024 | |||
3025 | The client parts of the http and https transport plugins can be configured | ||
3026 | to use a proxy to connect to the hostlist server. This functionality can | ||
3027 | be configured in the configuration file directly or using the | ||
3028 | gnunet-setup tool. | ||
3029 | |||
3030 | Both the HTTP and HTTPS clients support the following proxy types at | ||
3031 | the moment: | ||
3032 | |||
3033 | @itemize @bullet | ||
3034 | @item HTTP 1.1 proxy | ||
3035 | @item SOCKS 4/4a/5/5 with hostname | ||
3036 | @end itemize | ||
3037 | |||
3038 | In addition authentication at the proxy with username and password can be | ||
3039 | configured. | ||
3040 | |||
3041 | To configure proxy support for the clients in the gnunet-setup tool, | ||
3042 | select the "transport" tab and activate the respective plugin. Now you | ||
3043 | can select the appropriate proxy type. The hostname or IP address | ||
3044 | (including port if required) has to be entered in the "Proxy hostname" | ||
3045 | textbox. If required, enter username and password in the "Proxy username" | ||
3046 | and "Proxy password" boxes. Be aware that these information will be stored | ||
3047 | in the configuration in plain text. | ||
3048 | |||
3049 | To configure these options directly in the configuration, you can | ||
3050 | configure the following settings in the @code{[transport-http_client]} | ||
3051 | and @code{[transport-https_client]} section of the configuration: | ||
3052 | |||
3053 | @example | ||
3054 | # Type of proxy server, | ||
3055 | # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME | ||
3056 | # Default: HTTP | ||
3057 | # PROXY_TYPE = HTTP | ||
3058 | |||
3059 | # Hostname or IP of proxy server | ||
3060 | # PROXY = | ||
3061 | # User name for proxy server | ||
3062 | # PROXY_USERNAME = | ||
3063 | # User password for proxy server | ||
3064 | # PROXY_PASSWORD = | ||
3065 | @end example | ||
3066 | |||
3067 | @node Configuring the GNU Name System | ||
3068 | @subsection Configuring the GNU Name System | ||
3069 | |||
3070 | @menu | ||
3071 | * Configuring system-wide DNS interception:: | ||
3072 | * Configuring the GNS nsswitch plugin:: | ||
3073 | * Configuring GNS on W32:: | ||
3074 | * GNS Proxy Setup:: | ||
3075 | * Setup of the GNS CA:: | ||
3076 | * Testing the GNS setup:: | ||
3077 | @end menu | ||
3078 | |||
3079 | |||
3080 | @node Configuring system-wide DNS interception | ||
3081 | @subsubsection Configuring system-wide DNS interception | ||
3082 | |||
3083 | Before you install GNUnet, make sure you have a user and group 'gnunet' | ||
3084 | as well as an empty group 'gnunetdns'. | ||
3085 | |||
3086 | When using GNUnet with system-wide DNS interception, it is absolutely | ||
3087 | necessary for all GNUnet service processes to be started by | ||
3088 | @code{gnunet-service-arm} as user and group 'gnunet'. You also need to be | ||
3089 | sure to run @code{make install} as root (or use the @code{sudo} option to | ||
3090 | configure) to grant GNUnet sufficient privileges. | ||
3091 | |||
3092 | With this setup, all that is required for enabling system-wide DNS | ||
3093 | interception is for some GNUnet component (VPN or GNS) to request it. | ||
3094 | The @code{gnunet-service-dns} will then start helper programs that will | ||
3095 | make the necessary changes to your firewall (@code{iptables}) rules. | ||
3096 | |||
3097 | Note that this will NOT work if your system sends out DNS traffic to a | ||
3098 | link-local IPv6 address, as in this case GNUnet can intercept the traffic, | ||
3099 | but not inject the responses from the link-local IPv6 address. Hence you | ||
3100 | cannot use system-wide DNS interception in conjunction with link-local | ||
3101 | IPv6-based DNS servers. If such a DNS server is used, it will bypass | ||
3102 | GNUnet's DNS traffic interception. | ||
3103 | |||
3104 | Using the GNU Name System (GNS) requires two different configuration | ||
3105 | steps. | ||
3106 | First of all, GNS needs to be integrated with the operating system. Most | ||
3107 | of this section is about the operating system level integration. | ||
3108 | |||
3109 | The remainder of this chapter will detail the various methods for | ||
3110 | configuring the use of GNS with your operating system. | ||
3111 | |||
3112 | At this point in time you have different options depending on your OS: | ||
3113 | |||
3114 | @table @asis | ||
3115 | |||
3116 | @item Use the gnunet-gns-proxy This approach works for all operating | ||
3117 | systems and is likely the easiest. However, it enables GNS only for | ||
3118 | browsers, not for other applications that might be using DNS, such as SSH. | ||
3119 | Still, using the proxy is required for using HTTP with GNS and is thus | ||
3120 | recommended for all users. To do this, you simply have to run the | ||
3121 | @code{gnunet-gns-proxy-setup-ca} script as the user who will run the | ||
3122 | browser (this will create a GNS certificate authority (CA) on your system | ||
3123 | and import its key into your browser), then start @code{gnunet-gns-proxy} | ||
3124 | and inform your browser to use the Socks5 proxy which | ||
3125 | @code{gnunet-gns-proxy} makes available by default on port 7777. | ||
3126 | @item Use a nsswitch plugin (recommended on GNU systems) | ||
3127 | This approach has the advantage of offering fully personalized resolution | ||
3128 | even on multi-user systems. A potential disadvantage is that some | ||
3129 | applications might be able to bypass GNS. | ||
3130 | @item Use a W32 resolver plugin (recommended on W32) | ||
3131 | This is currently the only option on W32 systems. | ||
3132 | @item Use system-wide DNS packet interception | ||
3133 | This approach is recommended for the GNUnet VPN. It can be used to handle | ||
3134 | GNS at the same time; however, if you only use this method, you will only | ||
3135 | get one root zone per machine (not so great for multi-user systems). | ||
3136 | @end table | ||
3137 | |||
3138 | You can combine system-wide DNS packet interception with the nsswitch | ||
3139 | plugin. | ||
3140 | The setup of the system-wide DNS interception is described here. All of | ||
3141 | the other GNS-specific configuration steps are described in the following | ||
3142 | sections. | ||
3143 | |||
3144 | @node Configuring the GNS nsswitch plugin | ||
3145 | @subsubsection Configuring the GNS nsswitch plugin | ||
3146 | |||
3147 | The Name Service Switch (NSS) is a facility in Unix-like operating systems | ||
3148 | @footnote{More accurate: NSS is a functionality of the GNU C Library} | ||
3149 | that provides a variety of sources for common configuration databases and | ||
3150 | name resolution mechanisms. | ||
3151 | A superuser (system administrator) usually configures the | ||
3152 | operating system's name services using the file | ||
3153 | @file{/etc/nsswitch.conf}. | ||
3154 | |||
3155 | GNS provides a NSS plugin to integrate GNS name resolution with the | ||
3156 | operating system's name resolution process. | ||
3157 | To use the GNS NSS plugin you have to either | ||
3158 | |||
3159 | @itemize @bullet | ||
3160 | @item install GNUnet as root or | ||
3161 | @item compile GNUnet with the @code{--with-sudo=yes} switch. | ||
3162 | @end itemize | ||
3163 | |||
3164 | Name resolution is controlled by the @emph{hosts} section in the NSS | ||
3165 | configuration. By default this section first performs a lookup in the | ||
3166 | @file{/etc/hosts} file and then in DNS. | ||
3167 | The nsswitch file should contain a line similar to: | ||
3168 | |||
3169 | @example | ||
3170 | hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4 | ||
3171 | @end example | ||
3172 | |||
3173 | @noindent | ||
3174 | Here the GNS NSS plugin can be added to perform a GNS lookup before | ||
3175 | performing a DNS lookup. | ||
3176 | The GNS NSS plugin has to be added to the "hosts" section in | ||
3177 | @file{/etc/nsswitch.conf} file before DNS related plugins: | ||
3178 | |||
3179 | @example | ||
3180 | ... | ||
3181 | hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4 | ||
3182 | ... | ||
3183 | @end example | ||
3184 | |||
3185 | @noindent | ||
3186 | The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not | ||
3187 | found in GNS it will not be queried in DNS. | ||
3188 | |||
3189 | @node Configuring GNS on W32 | ||
3190 | @subsubsection Configuring GNS on W32 | ||
3191 | |||
3192 | This document is a guide to configuring GNU Name System on W32-compatible | ||
3193 | platforms. | ||
3194 | |||
3195 | After GNUnet is installed, run the w32nsp-install tool: | ||
3196 | |||
3197 | @example | ||
3198 | w32nsp-install.exe libw32nsp-0.dll | ||
3199 | @end example | ||
3200 | |||
3201 | @noindent | ||
3202 | ('0' is the library version of W32 NSP; it might increase in the future, | ||
3203 | change the invocation accordingly). | ||
3204 | |||
3205 | This will install GNS namespace provider into the system and allow other | ||
3206 | applications to resolve names that end in '@strong{gnu}' | ||
3207 | and '@strong{zkey}'. Note that namespace provider requires | ||
3208 | gnunet-gns-helper-service-w32 to be running, as well as gns service | ||
3209 | itself (and its usual dependencies). | ||
3210 | |||
3211 | Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353}, | ||
3212 | and this is where gnunet-gns-helper-service-w32 should be listening to | ||
3213 | (and is configured to listen to by default). | ||
3214 | |||
3215 | To uninstall the provider, run: | ||
3216 | |||
3217 | @example | ||
3218 | w32nsp-uninstall.exe | ||
3219 | @end example | ||
3220 | |||
3221 | @noindent | ||
3222 | (uses provider GUID to uninstall it, does not need a dll name). | ||
3223 | |||
3224 | Note that while MSDN claims that other applications will only be able to | ||
3225 | use the new namespace provider after re-starting, in reality they might | ||
3226 | stat to use it without that. Conversely, they might stop using the | ||
3227 | provider after it's been uninstalled, even if they were not re-started. | ||
3228 | W32 will not permit namespace provider library to be deleted or | ||
3229 | overwritten while the provider is installed, and while there is at least | ||
3230 | one process still using it (even after it was uninstalled). | ||
3231 | |||
3232 | @node GNS Proxy Setup | ||
3233 | @subsubsection GNS Proxy Setup | ||
3234 | |||
3235 | When using the GNU Name System (GNS) to browse the WWW, there are several | ||
3236 | issues that can be solved by adding the GNS Proxy to your setup: | ||
3237 | |||
3238 | @itemize @bullet | ||
3239 | |||
3240 | @item If the target website does not support GNS, it might assume that it | ||
3241 | is operating under some name in the legacy DNS system (such as | ||
3242 | example.com). It may then attempt to set cookies for that domain, and the | ||
3243 | web server might expect a @code{Host: example.com} header in the request | ||
3244 | from your browser. | ||
3245 | However, your browser might be using @code{example.gnu} for the | ||
3246 | @code{Host} header and might only accept (and send) cookies for | ||
3247 | @code{example.gnu}. The GNS Proxy will perform the necessary translations | ||
3248 | of the hostnames for cookies and HTTP headers (using the LEHO record for | ||
3249 | the target domain as the desired substitute). | ||
3250 | |||
3251 | @item If using HTTPS, the target site might include an SSL certificate | ||
3252 | which is either only valid for the LEHO domain or might match a TLSA | ||
3253 | record in GNS. However, your browser would expect a valid certificate for | ||
3254 | @code{example.gnu}, not for some legacy domain name. The proxy will | ||
3255 | validate the certificate (either against LEHO or TLSA) and then | ||
3256 | on-the-fly produce a valid certificate for the exchange, signed by your | ||
3257 | own CA. Assuming you installed the CA of your proxy in your browser's | ||
3258 | certificate authority list, your browser will then trust the | ||
3259 | HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy. | ||
3260 | |||
3261 | @item Finally, the proxy will in the future indicate to the server that it | ||
3262 | speaks GNS, which will enable server operators to deliver GNS-enabled web | ||
3263 | sites to your browser (and continue to deliver legacy links to legacy | ||
3264 | browsers) | ||
3265 | @end itemize | ||
3266 | |||
3267 | @node Setup of the GNS CA | ||
3268 | @subsubsection Setup of the GNS CA | ||
3269 | |||
3270 | First you need to create a CA certificate that the proxy can use. | ||
3271 | To do so use the provided script gnunet-gns-proxy-ca: | ||
3272 | |||
3273 | @example | ||
3274 | $ gnunet-gns-proxy-setup-ca | ||
3275 | @end example | ||
3276 | |||
3277 | @noindent | ||
3278 | This will create a personal certification authority for you and add this | ||
3279 | authority to the firefox and chrome database. The proxy will use the this | ||
3280 | CA certificate to generate @code{*.gnu} client certificates on the fly. | ||
3281 | |||
3282 | Note that the proxy uses libcurl. Make sure your version of libcurl uses | ||
3283 | GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled | ||
3284 | against OpenSSL. | ||
3285 | |||
3286 | You can check the configuration your libcurl was build with by | ||
3287 | running: | ||
3288 | |||
3289 | @example | ||
3290 | curl --version | ||
3291 | @end example | ||
3292 | |||
3293 | the output will look like this (without the linebreaks): | ||
3294 | |||
3295 | @example | ||
3296 | gnurl --version | ||
3297 | curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \ | ||
3298 | GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4 | ||
3299 | Release-Date: 2017-10-08 | ||
3300 | Protocols: http https | ||
3301 | Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \ | ||
3302 | TLS-SRP UnixSockets HTTPS-proxy | ||
3303 | @end example | ||
3304 | |||
3305 | @node Testing the GNS setup | ||
3306 | @subsubsection Testing the GNS setup | ||
3307 | |||
3308 | Now for testing purposes we can create some records in our zone to test | ||
3309 | the SSL functionality of the proxy: | ||
3310 | |||
3311 | @example | ||
3312 | $ gnunet-identity -C test | ||
3313 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ | ||
3314 | -t A -V 131.159.74.67 -z test | ||
3315 | $ gnunet-namestore -a -e "1 d" -n "homepage" \ | ||
3316 | -t LEHO -V "gnunet.org" -z test | ||
3317 | @end example | ||
3318 | |||
3319 | @noindent | ||
3320 | At this point we can start the proxy. Simply execute | ||
3321 | |||
3322 | @example | ||
3323 | $ gnunet-gns-proxy | ||
3324 | @end example | ||
3325 | |||
3326 | @noindent | ||
3327 | Configure your browser to use this SOCKSv5 proxy on port 7777 and visit | ||
3328 | this link. | ||
3329 | If you use @command{Firefox} (or one of its derivatives/forks such as | ||
3330 | Icecat) you also have to go to @code{about:config} and set the key | ||
3331 | @code{network.proxy.socks_remote_dns} to @code{true}. | ||
3332 | |||
3333 | When you visit @code{https://homepage.test/}, you should get to the | ||
3334 | @code{https://gnunet.org/} frontpage and the browser (with the correctly | ||
3335 | configured proxy) should give you a valid SSL certificate for | ||
3336 | @code{homepage.gnu} and no warnings. It should look like this: | ||
3337 | |||
3338 | @c FIXME: Image does not exist, create it or save it from Drupal? | ||
3339 | @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} | ||
3340 | |||
3341 | |||
3342 | @node Configuring the GNUnet VPN | ||
3343 | @subsection Configuring the GNUnet VPN | ||
3344 | |||
3345 | @menu | ||
3346 | * IPv4 address for interface:: | ||
3347 | * IPv6 address for interface:: | ||
3348 | * Configuring the GNUnet VPN DNS:: | ||
3349 | * Configuring the GNUnet VPN Exit Service:: | ||
3350 | * IP Address of external DNS resolver:: | ||
3351 | * IPv4 address for Exit interface:: | ||
3352 | * IPv6 address for Exit interface:: | ||
3353 | @end menu | ||
3354 | |||
3355 | Before configuring the GNUnet VPN, please make sure that system-wide DNS | ||
3356 | interception is configured properly as described in the section on the | ||
3357 | GNUnet DNS setup. @pxref{Configuring the GNU Name System}, | ||
3358 | if you haven't done so already. | ||
3359 | |||
3360 | The default options for the GNUnet VPN are usually sufficient to use | ||
3361 | GNUnet as a Layer 2 for your Internet connection. | ||
3362 | However, what you always have to specify is which IP protocol you want | ||
3363 | to tunnel: IPv4, IPv6 or both. | ||
3364 | Furthermore, if you tunnel both, you most likely should also tunnel | ||
3365 | all of your DNS requests. | ||
3366 | You theoretically can tunnel "only" your DNS traffic, but that usually | ||
3367 | makes little sense. | ||
3368 | |||
3369 | The other options as shown on the gnunet-setup tool are: | ||
3370 | |||
3371 | @node IPv4 address for interface | ||
3372 | @subsubsection IPv4 address for interface | ||
3373 | |||
3374 | This is the IPv4 address the VPN interface will get. You should pick an | ||
3375 | 'private' IPv4 network that is not yet in use for you system. For example, | ||
3376 | if you use @code{10.0.0.1/255.255.0.0} already, you might use | ||
3377 | @code{10.1.0.1/255.255.0.0}. | ||
3378 | If you use @code{10.0.0.1/255.0.0.0} already, then you might use | ||
3379 | @code{192.168.0.1/255.255.0.0}. | ||
3380 | If your system is not in a private IP-network, using any of the above will | ||
3381 | work fine. | ||
3382 | You should try to make the mask of the address big enough | ||
3383 | (@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more | ||
3384 | mappings of remote IP Addresses into this range. | ||
3385 | However, even a @code{255.255.255.0} mask will suffice for most users. | ||
3386 | |||
3387 | @node IPv6 address for interface | ||
3388 | @subsubsection IPv6 address for interface | ||
3389 | |||
3390 | The IPv6 address the VPN interface will get. Here you can specify any | ||
3391 | non-link-local address (the address should not begin with @code{fe80:}). | ||
3392 | A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are | ||
3393 | currently not using would be a good choice. | ||
3394 | |||
3395 | @node Configuring the GNUnet VPN DNS | ||
3396 | @subsubsection Configuring the GNUnet VPN DNS | ||
3397 | |||
3398 | To resolve names for remote nodes, activate the DNS exit option. | ||
3399 | |||
3400 | @node Configuring the GNUnet VPN Exit Service | ||
3401 | @subsubsection Configuring the GNUnet VPN Exit Service | ||
3402 | |||
3403 | If you want to allow other users to share your Internet connection (yes, | ||
3404 | this may be dangerous, just as running a Tor exit node) or want to | ||
3405 | provide access to services on your host (this should be less dangerous, | ||
3406 | as long as those services are secure), you have to enable the GNUnet exit | ||
3407 | daemon. | ||
3408 | |||
3409 | You then get to specify which exit functions you want to provide. By | ||
3410 | enabling the exit daemon, you will always automatically provide exit | ||
3411 | functions for manually configured local services (this component of the | ||
3412 | system is under | ||
3413 | development and not documented further at this time). As for those | ||
3414 | services you explicitly specify the target IP address and port, there is | ||
3415 | no significant security risk in doing so. | ||
3416 | |||
3417 | Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet. | ||
3418 | Being a DNS exit is usually pretty harmless. However, enabling IPv4 or | ||
3419 | IPv6-exit without further precautions may enable adversaries to access | ||
3420 | your local network, send spam, attack other systems from your Internet | ||
3421 | connection and to other mischief that will appear to come from your | ||
3422 | machine. This may or may not get you into legal trouble. | ||
3423 | If you want to allow IPv4 or IPv6-exit functionality, you should strongly | ||
3424 | consider adding additional firewall rules manually to protect your local | ||
3425 | network and to restrict outgoing TCP traffic (i.e. by not allowing access | ||
3426 | to port 25). While we plan to improve exit-filtering in the future, | ||
3427 | you're currently on your own here. | ||
3428 | Essentially, be prepared for any kind of IP-traffic to exit the respective | ||
3429 | TUN interface (and GNUnet will enable IP-forwarding and NAT for the | ||
3430 | interface automatically). | ||
3431 | |||
3432 | Additional configuration options of the exit as shown by the gnunet-setup | ||
3433 | tool are: | ||
3434 | |||
3435 | @node IP Address of external DNS resolver | ||
3436 | @subsubsection IP Address of external DNS resolver | ||
3437 | |||
3438 | If DNS traffic is to exit your machine, it will be send to this DNS | ||
3439 | resolver. You can specify an IPv4 or IPv6 address. | ||
3440 | |||
3441 | @node IPv4 address for Exit interface | ||
3442 | @subsubsection IPv4 address for Exit interface | ||
3443 | |||
3444 | This is the IPv4 address the Interface will get. Make the mask of the | ||
3445 | address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more | ||
3446 | mappings of IP addresses into this range. As for the VPN interface, any | ||
3447 | unused, private IPv4 address range will do. | ||
3448 | |||
3449 | @node IPv6 address for Exit interface | ||
3450 | @subsubsection IPv6 address for Exit interface | ||
3451 | |||
3452 | The public IPv6 address the interface will get. If your kernel is not a | ||
3453 | very recent kernel and you are willing to manually enable IPv6-NAT, the | ||
3454 | IPv6 address you specify here must be a globally routed IPv6 address of | ||
3455 | your host. | ||
3456 | |||
3457 | Suppose your host has the address @code{2001:4ca0::1234/64}, then | ||
3458 | using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits, | ||
3459 | then change at least one bit in the range before the bitmask, in the | ||
3460 | example above we changed bit 111 from 0 to 1). | ||
3461 | |||
3462 | You may also have to configure your router to route traffic for the entire | ||
3463 | subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this | ||
3464 | should be automatic with IPv6, but obviously anything can be | ||
3465 | disabled). | ||
3466 | |||
3467 | @node Bandwidth Configuration | ||
3468 | @subsection Bandwidth Configuration | ||
3469 | |||
3470 | You can specify how many bandwidth GNUnet is allowed to use to receive | ||
3471 | and send data. This is important for users with limited bandwidth or | ||
3472 | traffic volume. | ||
3473 | |||
3474 | @node Configuring NAT | ||
3475 | @subsection Configuring NAT | ||
3476 | |||
3477 | Most hosts today do not have a normal global IP address but instead are | ||
3478 | behind a router performing Network Address Translation (NAT) which assigns | ||
3479 | each host in the local network a private IP address. | ||
3480 | As a result, these machines cannot trivially receive inbound connections | ||
3481 | from the Internet. GNUnet supports NAT traversal to enable these machines | ||
3482 | to receive incoming connections from other peers despite their | ||
3483 | limitations. | ||
3484 | |||
3485 | In an ideal world, you can press the "Attempt automatic configuration" | ||
3486 | button in gnunet-setup to automatically configure your peer correctly. | ||
3487 | Alternatively, your distribution might have already triggered this | ||
3488 | automatic configuration during the installation process. | ||
3489 | However, automatic configuration can fail to determine the optimal | ||
3490 | settings, resulting in your peer either not receiving as many connections | ||
3491 | as possible, or in the worst case it not connecting to the network at all. | ||
3492 | |||
3493 | To manually configure the peer, you need to know a few things about your | ||
3494 | network setup. First, determine if you are behind a NAT in the first | ||
3495 | place. | ||
3496 | This is always the case if your IP address starts with "10.*" or | ||
3497 | "192.168.*". Next, if you have control over your NAT router, you may | ||
3498 | choose to manually configure it to allow GNUnet traffic to your host. | ||
3499 | If you have configured your NAT to forward traffic on ports 2086 (and | ||
3500 | possibly 1080) to your host, you can check the "NAT ports have been opened | ||
3501 | manually" option, which corresponds to the "PUNCHED_NAT" option in the | ||
3502 | configuration file. If you did not punch your NAT box, it may still be | ||
3503 | configured to support UPnP, which allows GNUnet to automatically | ||
3504 | configure it. In that case, you need to install the "upnpc" command, | ||
3505 | enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal | ||
3506 | via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the | ||
3507 | configuration file). | ||
3508 | |||
3509 | Some NAT boxes can be traversed using the autonomous NAT traversal method. | ||
3510 | This requires certain GNUnet components to be installed with "SUID" | ||
3511 | privileges on your system (so if you're installing on a system you do | ||
3512 | not have administrative rights to, this will not work). | ||
3513 | If you installed as 'root', you can enable autonomous NAT traversal by | ||
3514 | checking the "Enable NAT traversal using ICMP method". | ||
3515 | The ICMP method requires a way to determine your NAT's external (global) | ||
3516 | IP address. This can be done using either UPnP, DynDNS, or by manual | ||
3517 | configuration. If you have a DynDNS name or know your external IP address, | ||
3518 | you should enter that name under "External (public) IPv4 address" (which | ||
3519 | corresponds to the "EXTERNAL_ADDRESS" option in the configuration file). | ||
3520 | If you leave the option empty, GNUnet will try to determine your external | ||
3521 | IP address automatically (which may fail, in which case autonomous | ||
3522 | NAT traversal will then not work). | ||
3523 | |||
3524 | Finally, if you yourself are not behind NAT but want to be able to | ||
3525 | connect to NATed peers using autonomous NAT traversal, you need to check | ||
3526 | the "Enable connecting to NATed peers using ICMP method" box. | ||
3527 | |||
3528 | |||
3529 | @node Peer configuration for distributions | ||
3530 | @subsection Peer configuration for distributions | ||
3531 | |||
3532 | The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be | ||
3533 | manually set to "/var/lib/gnunet/data/" as the default | ||
3534 | "~/.local/share/gnunet/" is probably not that appropriate in this case. | ||
3535 | Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to | ||
3536 | "/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a | ||
3537 | distribution decide to override system defaults, all of these changes | ||
3538 | should be done in a custom @file{/etc/gnunet.conf} and not in the files | ||
3539 | in the @file{config.d/} directory. | ||
3540 | |||
3541 | Given the proposed access permissions, the "gnunet-setup" tool must be | ||
3542 | run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it | ||
3543 | modifies the system configuration). As always, gnunet-setup should be run | ||
3544 | after the GNUnet peer was stopped using "gnunet-arm -e". Distributions | ||
3545 | might want to include a wrapper for gnunet-setup that allows the | ||
3546 | desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account | ||
3547 | and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in | ||
3548 | sequence. | ||
3549 | |||
3550 | @node MOVE TO INSTALL Checking the Installation | ||
3551 | @section MOVE TO INSTALL Checking the Installation | ||
3552 | @c %**end of header | ||
3553 | |||
3554 | This section describes a quick, casual way to check if your GNUnet | ||
3555 | installation works. However, if it does not, we do not cover | ||
3556 | steps for recovery --- for this, please study the instructions | ||
3557 | provided in the developer handbook as well as the system-specific | ||
3558 | instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}. | ||
3559 | |||
3560 | |||
3561 | @menu | ||
3562 | * gnunet-gtk:: | ||
3563 | * Statistics:: | ||
3564 | * Peer Information:: | ||
3565 | @end menu | ||
3566 | |||
3567 | @cindex GNUnet GTK | ||
3568 | @cindex GTK | ||
3569 | @cindex GTK user interface | ||
3570 | @node gnunet-gtk | ||
3571 | @subsection gnunet-gtk | ||
3572 | @c %**end of header | ||
3573 | |||
3574 | The @command{gnunet-gtk} package contains several graphical | ||
3575 | user interfaces for the respective GNUnet applications. | ||
3576 | Currently these interfaces cover: | ||
3577 | |||
3578 | @itemize @bullet | ||
3579 | @item Statistics | ||
3580 | @item Peer Information | ||
3581 | @item GNU Name System | ||
3582 | @item File Sharing | ||
3583 | @item Identity Management | ||
3584 | @item Conversation | ||
3585 | @end itemize | ||
3586 | |||
3587 | @node Statistics | ||
3588 | @subsection Statistics | ||
3589 | @c %**end of header | ||
3590 | |||
3591 | First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}. | ||
3592 | You can do this from the command-line by typing | ||
3593 | |||
3594 | @example | ||
3595 | gnunet-statistics-gtk | ||
3596 | @end example | ||
3597 | |||
3598 | 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''.} | ||
3599 | is running correctly, you should see a bunch of lines, | ||
3600 | all of which should be ``significantly'' above zero (at least if your | ||
3601 | peer has been running for more than a few seconds). The lines indicate | ||
3602 | how many other peers your peer is connected to (via different | ||
3603 | mechanisms) and how large the entire overlay network is currently | ||
3604 | estimated to be. The X-axis represents time (in seconds since the | ||
3605 | start of @command{gnunet-gtk}). | ||
3606 | |||
3607 | You can click on "Traffic" to see information about the amount of | ||
3608 | bandwidth your peer has consumed, and on "Storage" to check the amount | ||
3609 | of storage available and used by your peer. Note that "Traffic" is | ||
3610 | plotted cumulatively, so you should see a strict upwards trend in the | ||
3611 | traffic. | ||
3612 | |||
3613 | @node Peer Information | ||
3614 | @subsection Peer Information | ||
3615 | @c %**end of header | ||
3616 | |||
3617 | First, you should launch the graphical user interface. You can do | ||
3618 | this from the command-line by typing | ||
3619 | |||
3620 | @example | ||
3621 | $ gnunet-peerinfo-gtk | ||
3622 | @end example | ||
3623 | |||
3624 | Once you have done this, you will see a list of known peers (by the | ||
3625 | first four characters of their public key), their friend status (all | ||
3626 | should be marked as not-friends initially), their connectivity (green | ||
3627 | is connected, red is disconnected), assigned bandwidth, country of | ||
3628 | origin (if determined) and address information. If hardly any peers | ||
3629 | are listed and/or if there are very few peers with a green light for | ||
3630 | connectivity, there is likely a problem with your network | ||
3631 | configuration. | ||
3632 | |||
3633 | @node MOVE TO INSTALL Config Leftovers | ||
3634 | @section MOVE TO INSTALL Config Leftovers | ||
3635 | |||
3636 | This section describes how to start a GNUnet peer. It assumes that you | ||
3637 | have already compiled and installed GNUnet and its' dependencies. | ||
3638 | Before you start a GNUnet peer, you may want to create a configuration | ||
3639 | file using gnunet-setup (but you do not have to). | ||
3640 | Sane defaults should exist in your | ||
3641 | @file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice | ||
3642 | you could simply start without any configuration. If you want to | ||
3643 | configure your peer later, you need to stop it before invoking the | ||
3644 | @code{gnunet-setup} tool to customize further and to test your | ||
3645 | configuration (@code{gnunet-setup} has build-in test functions). | ||
3646 | |||
3647 | The most important option you might have to still set by hand is in | ||
3648 | [PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where | ||
3649 | GNUnet should store its data. | ||
3650 | It defaults to @code{$HOME/}, which again should work for most users. | ||
3651 | Make sure that the directory specified as GNUNET_HOME is writable to | ||
3652 | the user that you will use to run GNUnet (note that you can run frontends | ||
3653 | using other users, GNUNET_HOME must only be accessible to the user used to | ||
3654 | run the background processes). | ||
3655 | |||
3656 | You will also need to make one central decision: should all of GNUnet be | ||
3657 | run under your normal UID, or do you want distinguish between system-wide | ||
3658 | (user-independent) GNUnet services and personal GNUnet services. The | ||
3659 | multi-user setup is slightly more complicated, but also more secure and | ||
3660 | generally recommended. | ||
3661 | |||
3662 | @menu | ||
3663 | * The Single-User Setup:: | ||
3664 | * The Multi-User Setup:: | ||
3665 | * Killing GNUnet services:: | ||
3666 | * Access Control for GNUnet:: | ||
3667 | @end menu | ||
3668 | |||
3669 | @node The Single-User Setup | ||
3670 | @subsection The Single-User Setup | ||
3671 | |||
3672 | For the single-user setup, you do not need to do anything special and can | ||
3673 | just start the GNUnet background processes using @code{gnunet-arm}. | ||
3674 | By default, GNUnet looks in @file{~/.config/gnunet.conf} for a | ||
3675 | configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@ | ||
3676 | @code{$XDG_CONFIG_HOME} is defined). If your configuration lives | ||
3677 | elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet | ||
3678 | commands. | ||
3679 | |||
3680 | Assuming the configuration file is called @file{~/.config/gnunet.conf}, | ||
3681 | you start your peer using the @code{gnunet-arm} command (say as user | ||
3682 | @code{gnunet}) using: | ||
3683 | |||
3684 | @example | ||
3685 | gnunet-arm -c ~/.config/gnunet.conf -s | ||
3686 | @end example | ||
3687 | |||
3688 | @noindent | ||
3689 | The "-s" option here is for "start". The command should return almost | ||
3690 | instantly. If you want to stop GNUnet, you can use: | ||
3691 | |||
3692 | @example | ||
3693 | gnunet-arm -c ~/.config/gnunet.conf -e | ||
3694 | @end example | ||
3695 | |||
3696 | @noindent | ||
3697 | The "-e" option here is for "end". | ||
3698 | |||
3699 | Note that this will only start the basic peer, no actual applications | ||
3700 | will be available. | ||
3701 | If you want to start the file-sharing service, use (after starting | ||
3702 | GNUnet): | ||
3703 | |||
3704 | @example | ||
3705 | gnunet-arm -c ~/.config/gnunet.conf -i fs | ||
3706 | @end example | ||
3707 | |||
3708 | @noindent | ||
3709 | The "-i fs" option here is for "initialize" the "fs" (file-sharing) | ||
3710 | application. You can also selectively kill only file-sharing support using | ||
3711 | |||
3712 | @example | ||
3713 | gnunet-arm -c ~/.config/gnunet.conf -k fs | ||
3714 | @end example | ||
3715 | |||
3716 | @noindent | ||
3717 | Assuming that you want certain services (like file-sharing) to be always | ||
3718 | automatically started whenever you start GNUnet, you can activate them by | ||
3719 | setting "IMMEDIATE_START=YES" in the respective section of the configuration | ||
3720 | file (for example, "[fs]"). Then GNUnet with file-sharing support would | ||
3721 | be started whenever you@ enter: | ||
3722 | |||
3723 | @example | ||
3724 | gnunet-arm -c ~/.config/gnunet.conf -s | ||
3725 | @end example | ||
3726 | |||
3727 | @noindent | ||
3728 | Alternatively, you can combine the two options: | ||
3729 | |||
3730 | @example | ||
3731 | gnunet-arm -c ~/.config/gnunet.conf -s -i fs | ||
3732 | @end example | ||
3733 | |||
3734 | @noindent | ||
3735 | Using @code{gnunet-arm} is also the preferred method for initializing | ||
3736 | GNUnet from @code{init}. | ||
3737 | |||
3738 | Finally, you should edit your @code{crontab} (using the @code{crontab} | ||
3739 | command) and insert a line@ | ||
3740 | |||
3741 | @example | ||
3742 | @@reboot gnunet-arm -c ~/.config/gnunet.conf -s | ||
3743 | @end example | ||
3744 | |||
3745 | to automatically start your peer whenever your system boots. | ||
3746 | |||
3747 | @node The Multi-User Setup | ||
3748 | @subsection The Multi-User Setup | ||
3749 | |||
3750 | This requires you to create a user @code{gnunet} and an additional group | ||
3751 | @code{gnunetdns}, prior to running @code{make install} during | ||
3752 | installation. | ||
3753 | Then, you create a configuration file @file{/etc/gnunet.conf} which should | ||
3754 | contain the lines:@ | ||
3755 | |||
3756 | @example | ||
3757 | [arm] | ||
3758 | START_SYSTEM_SERVICES = YES | ||
3759 | START_USER_SERVICES = NO | ||
3760 | @end example | ||
3761 | |||
3762 | @noindent | ||
3763 | Then, perform the same steps to run GNUnet as in the per-user | ||
3764 | configuration, except as user @code{gnunet} (including the | ||
3765 | @code{crontab} installation). | ||
3766 | You may also want to run @code{gnunet-setup} to configure your peer | ||
3767 | (databases, etc.). | ||
3768 | Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you | ||
3769 | run @code{gnunet-setup} as user @code{gnunet}, you might need to change | ||
3770 | permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can | ||
3771 | write to the file (during setup). | ||
3772 | |||
3773 | Afterwards, you need to perform another setup step for each normal user | ||
3774 | account from which you want to access GNUnet. First, grant the normal user | ||
3775 | (@code{$USER}) permission to the group gnunet: | ||
3776 | |||
3777 | @example | ||
3778 | # adduser $USER gnunet | ||
3779 | @end example | ||
3780 | |||
3781 | @noindent | ||
3782 | Then, create a configuration file in @file{~/.config/gnunet.conf} for the | ||
3783 | $USER with the lines: | ||
3784 | |||
3785 | @example | ||
3786 | [arm] | ||
3787 | START_SYSTEM_SERVICES = NO | ||
3788 | START_USER_SERVICES = YES | ||
3789 | @end example | ||
3790 | |||
3791 | @noindent | ||
3792 | This will ensure that @code{gnunet-arm} when started by the normal user | ||
3793 | will only run services that are per-user, and otherwise rely on the | ||
3794 | system-wide services. | ||
3795 | Note that the normal user may run gnunet-setup, but the | ||
3796 | configuration would be ineffective as the system-wide services will use | ||
3797 | @file{/etc/gnunet.conf} and ignore options set by individual users. | ||
3798 | |||
3799 | Again, each user should then start the peer using | ||
3800 | @file{gnunet-arm -s} --- and strongly consider adding logic to start | ||
3801 | the peer automatically to their crontab. | ||
3802 | |||
3803 | Afterwards, you should see two (or more, if you have more than one USER) | ||
3804 | @code{gnunet-service-arm} processes running in your system. | ||
3805 | |||
3806 | @node Killing GNUnet services | ||
3807 | @subsection Killing GNUnet services | ||
3808 | |||
3809 | It is not necessary to stop GNUnet services explicitly when shutting | ||
3810 | down your computer. | ||
3811 | |||
3812 | It should be noted that manually killing "most" of the | ||
3813 | @code{gnunet-service} processes is generally not a successful method for | ||
3814 | stopping a peer (since @code{gnunet-service-arm} will instantly restart | ||
3815 | them). The best way to explicitly stop a peer is using | ||
3816 | @code{gnunet-arm -e}; note that the per-user services may need to be | ||
3817 | terminated before the system-wide services will terminate normally. | ||
3818 | |||
3819 | @node Access Control for GNUnet | ||
3820 | @subsection Access Control for GNUnet | ||
3821 | |||
3822 | This chapter documents how we plan to make access control work within the | ||
3823 | GNUnet system for a typical peer. It should be read as a best-practice | ||
3824 | installation guide for advanced users and builders of binary | ||
3825 | distributions. The recommendations in this guide apply to POSIX-systems | ||
3826 | with full support for UNIX domain sockets only. | ||
3827 | |||
3828 | Note that this is an advanced topic. The discussion presumes a very good | ||
3829 | understanding of users, groups and file permissions. Normal users on | ||
3830 | hosts with just a single user can just install GNUnet under their own | ||
3831 | account (and possibly allow the installer to use SUDO to grant additional | ||
3832 | permissions for special GNUnet tools that need additional rights). | ||
3833 | The discussion below largely applies to installations where multiple users | ||
3834 | share a system and to installations where the best possible security is | ||
3835 | paramount. | ||
3836 | |||
3837 | A typical GNUnet system consists of components that fall into four | ||
3838 | categories: | ||
3839 | |||
3840 | @table @asis | ||
3841 | |||
3842 | @item User interfaces | ||
3843 | User interfaces are not security sensitive and are supposed to be run and | ||
3844 | used by normal system users. | ||
3845 | The GTK GUIs and most command-line programs fall into this category. | ||
3846 | Some command-line tools (like gnunet-transport) should be excluded as they | ||
3847 | offer low-level access that normal users should not need. | ||
3848 | @item System services and support tools | ||
3849 | System services should always run and offer services that can then be | ||
3850 | accessed by the normal users. | ||
3851 | System services do not require special permissions, but as they are not | ||
3852 | specific to a particular user, they probably should not run as a | ||
3853 | particular user. Also, there should typically only be one GNUnet peer per | ||
3854 | host. System services include the gnunet-service and gnunet-daemon | ||
3855 | programs; support tools include command-line programs such as gnunet-arm. | ||
3856 | @item Privileged helpers | ||
3857 | Some GNUnet components require root rights to open raw sockets or perform | ||
3858 | other special operations. These gnunet-helper binaries are typically | ||
3859 | installed SUID and run from services or daemons. | ||
3860 | @item Critical services | ||
3861 | Some GNUnet services (such as the DNS service) can manipulate the service | ||
3862 | in deep and possibly highly security sensitive ways. For example, the DNS | ||
3863 | service can be used to intercept and alter any DNS query originating from | ||
3864 | the local machine. Access to the APIs of these critical services and their | ||
3865 | privileged helpers must be tightly controlled. | ||
3866 | @end table | ||
3867 | |||
3868 | @c FIXME: The titles of these chapters are too long in the index. | ||
3869 | |||
3870 | @menu | ||
3871 | * Recommendation - Disable access to services via TCP:: | ||
3872 | * Recommendation - Run most services as system user "gnunet":: | ||
3873 | * Recommendation - Control access to services using group "gnunet":: | ||
3874 | * Recommendation - Limit access to certain SUID binaries by group "gnunet":: | ||
3875 | * Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns":: | ||
3876 | * Differences between "make install" and these recommendations:: | ||
3877 | @end menu | ||
3878 | |||
3879 | @node Recommendation - Disable access to services via TCP | ||
3880 | @subsubsection Recommendation - Disable access to services via TCP | ||
3881 | |||
3882 | GNUnet services allow two types of access: via TCP socket or via UNIX | ||
3883 | domain socket. | ||
3884 | If the service is available via TCP, access control can only be | ||
3885 | implemented by restricting connections to a particular range of IP | ||
3886 | addresses. | ||
3887 | This is acceptable for non-critical services that are supposed to be | ||
3888 | available to all users on the local system or local network. | ||
3889 | However, as TCP is generally less efficient and it is rarely the case | ||
3890 | that a single GNUnet peer is supposed to serve an entire local network, | ||
3891 | the default configuration should disable TCP access to all GNUnet | ||
3892 | services on systems with support for UNIX domain sockets. | ||
3893 | As of GNUnet 0.9.2, configuration files with TCP access disabled should be | ||
3894 | generated by default. Users can re-enable TCP access to particular | ||
3895 | services simply by specifying a non-zero port number in the section of | ||
3896 | the respective service. | ||
3897 | |||
3898 | |||
3899 | @node Recommendation - Run most services as system user "gnunet" | ||
3900 | @subsubsection Recommendation - Run most services as system user "gnunet" | ||
3901 | |||
3902 | GNUnet's main services should be run as a separate user "gnunet" in a | ||
3903 | special group "gnunet". | ||
3904 | The user "gnunet" should start the peer using "gnunet-arm -s" during | ||
3905 | system startup. The home directory for this user should be | ||
3906 | @file{/var/lib/gnunet} and the configuration file should be | ||
3907 | @file{/etc/gnunet.conf}. | ||
3908 | Only the @code{gnunet} user should have the right to access | ||
3909 | @file{/var/lib/gnunet} (@emph{mode: 700}). | ||
3910 | |||
3911 | @node Recommendation - Control access to services using group "gnunet" | ||
3912 | @subsubsection Recommendation - Control access to services using group "gnunet" | ||
3913 | |||
3914 | Users that should be allowed to use the GNUnet peer should be added to the | ||
3915 | group "gnunet". Using GNUnet's access control mechanism for UNIX domain | ||
3916 | sockets, those services that are considered useful to ordinary users | ||
3917 | should be made available by setting "UNIX_MATCH_GID=YES" for those | ||
3918 | services. | ||
3919 | Again, as shipped, GNUnet provides reasonable defaults. | ||
3920 | Permissions to access the transport and core subsystems might additionally | ||
3921 | be granted without necessarily causing security concerns. | ||
3922 | Some services, such as DNS, must NOT be made accessible to the "gnunet" | ||
3923 | group (and should thus only be accessible to the "gnunet" user and | ||
3924 | services running with this UID). | ||
3925 | |||
3926 | @node Recommendation - Limit access to certain SUID binaries by group "gnunet" | ||
3927 | @subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet" | ||
3928 | |||
3929 | Most of GNUnet's SUID binaries should be safe even if executed by normal | ||
3930 | users. However, it is possible to reduce the risk a little bit more by | ||
3931 | making these binaries owned by the group "gnunet" and restricting their | ||
3932 | execution to user of the group "gnunet" as well (4750). | ||
3933 | |||
3934 | @node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | ||
3935 | @subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" | ||
3936 | |||
3937 | A special group "gnunetdns" should be created for controlling access to | ||
3938 | the "gnunet-helper-dns". | ||
3939 | The binary should then be owned by root and be in group "gnunetdns" and | ||
3940 | be installed SUID and only be group-executable (2750). | ||
3941 | @b{Note that the group "gnunetdns" should have no users in it at all, | ||
3942 | ever.} | ||
3943 | The "gnunet-service-dns" program should be executed by user "gnunet" (via | ||
3944 | gnunet-service-arm) with the binary owned by the user "root" and the group | ||
3945 | "gnunetdns" and be SGID (2700). This way, @strong{only} | ||
3946 | "gnunet-service-dns" can change its group to "gnunetdns" and execute the | ||
3947 | helper, and the helper can then run as root (as per SUID). | ||
3948 | Access to the API offered by "gnunet-service-dns" is in turn restricted | ||
3949 | to the user "gnunet" (not the group!), which means that only | ||
3950 | "benign" services can manipulate DNS queries using "gnunet-service-dns". | ||
3951 | |||
3952 | @node Differences between "make install" and these recommendations | ||
3953 | @subsubsection Differences between "make install" and these recommendations | ||
3954 | |||
3955 | The current build system does not set all permissions automatically based | ||
3956 | on the recommendations above. In particular, it does not use the group | ||
3957 | "gnunet" at all (so setting gnunet-helpers other than the | ||
3958 | gnunet-helper-dns to be owned by group "gnunet" must be done manually). | ||
3959 | Furthermore, 'make install' will silently fail to set the DNS binaries to | ||
3960 | be owned by group "gnunetdns" unless that group already exists (!). | ||
3961 | An alternative name for the "gnunetdns" group can be specified using the | ||
3962 | @code{--with-gnunetdns=GRPNAME} configure option. | ||
3963 | |||
diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi index 5ba6f6b15..2ef5a2b59 100644 --- a/doc/documentation/gnunet.texi +++ b/doc/documentation/gnunet.texi | |||
@@ -108,7 +108,7 @@ Philosophy | |||
108 | 108 | ||
109 | * Design Principles:: | 109 | * Design Principles:: |
110 | * Privacy and Anonymity:: | 110 | * Privacy and Anonymity:: |
111 | * Practicality:: | 111 | * Practicality:: |
112 | 112 | ||
113 | Key Concepts | 113 | Key Concepts |
114 | 114 | ||
@@ -134,9 +134,6 @@ Using GNUnet | |||
134 | * File-sharing:: | 134 | * File-sharing:: |
135 | * The GNU Name System:: | 135 | * The GNU Name System:: |
136 | * Using the Virtual Public Network:: | 136 | * Using the Virtual Public Network:: |
137 | * MOVE TO INSTALL The graphical configuration interface:: | ||
138 | * MOVE TO INSTALL Checking the Installation:: | ||
139 | * MOVE TO INSTALL Config Leftovers:: | ||
140 | 137 | ||
141 | GNUnet Contributors Handbook | 138 | GNUnet Contributors Handbook |
142 | 139 | ||