diff options
author | ng0 <ng0@infotropique.org> | 2017-10-23 13:06:41 +0000 |
---|---|---|
committer | ng0 <ng0@infotropique.org> | 2017-10-23 13:06:41 +0000 |
commit | 4f538ab32a2d8f0da3f9c68abdd0dc3c27a50859 (patch) | |
tree | 6a0852c0c0a832fa6af438c5ead371ba6cc3b67a /doc | |
parent | d47e59f85e162d808a98e5addf4971da5b8325b1 (diff) | |
download | gnunet-4f538ab32a2d8f0da3f9c68abdd0dc3c27a50859.tar.gz gnunet-4f538ab32a2d8f0da3f9c68abdd0dc3c27a50859.zip |
doc batch commit
Diffstat (limited to 'doc')
-rw-r--r-- | doc/documentation/Makefile.am | 8 | ||||
-rw-r--r-- | doc/documentation/chapters/developer.texi | 1389 | ||||
-rw-r--r-- | doc/documentation/chapters/installation.texi | 1117 |
3 files changed, 1371 insertions, 1143 deletions
diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am index 21852a9c3..c95728d25 100644 --- a/doc/documentation/Makefile.am +++ b/doc/documentation/Makefile.am | |||
@@ -182,6 +182,14 @@ doc-all-install: | |||
182 | 182 | ||
183 | # @cp -r images $(DESTDIR)/$(infoimagedir) | 183 | # @cp -r images $(DESTDIR)/$(infoimagedir) |
184 | 184 | ||
185 | dev-build: version.texi version2.texi | ||
186 | @makeinfo --pdf gnunet.texi | ||
187 | @makeinfo --pdf gnunet-c-tutorial.texi | ||
188 | @makeinfo --html gnunet.texi | ||
189 | @makeinfo --html gnunet-c-tutorial.texi | ||
190 | @makeinfo --no-split gnunet.texi | ||
191 | @makeinfo --no-split gnunet-c-tutorial.texi | ||
192 | |||
185 | # TODO: Add more to clean. | 193 | # TODO: Add more to clean. |
186 | clean: | 194 | clean: |
187 | @rm gnunet.pdf | 195 | @rm gnunet.pdf |
diff --git a/doc/documentation/chapters/developer.texi b/doc/documentation/chapters/developer.texi index 81a9a6c1f..f92257292 100644 --- a/doc/documentation/chapters/developer.texi +++ b/doc/documentation/chapters/developer.texi | |||
@@ -771,24 +771,27 @@ if (NULL == (value = lookup_function())) @{ error(); return; @} | |||
771 | deep(er) nesting. Thus, we would write: | 771 | deep(er) nesting. Thus, we would write: |
772 | 772 | ||
773 | @example | 773 | @example |
774 | next = head; while (NULL != (pos = next)) @{ next = pos->next; if (! | 774 | next = head; while (NULL != (pos = next)) @{ |
775 | should_free (pos)) continue; GNUNET_CONTAINER_DLL_remove (head, tail, pos); | 775 | next = pos->next; if (! should_free (pos)) |
776 | GNUNET_free (pos); @} | 776 | continue; |
777 | GNUNET_CONTAINER_DLL_remove (head, tail, pos); | ||
778 | GNUNET_free (pos); @} | ||
777 | @end example | 779 | @end example |
778 | 780 | ||
779 | |||
780 | instead of | 781 | instead of |
782 | |||
781 | @example | 783 | @example |
782 | next = head; while (NULL != (pos = next)) @{ next = | 784 | next = head; while (NULL != (pos = next)) @{ |
783 | pos->next; if (should_free (pos)) @{ | 785 | next = pos->next; if (should_free (pos)) @{ |
784 | /* unnecessary nesting! */ | 786 | /* unnecessary nesting! */ |
785 | GNUNET_CONTAINER_DLL_remove (head, tail, pos); GNUNET_free (pos); @} @} | 787 | GNUNET_CONTAINER_DLL_remove (head, tail, pos); |
788 | GNUNET_free (pos); @} @} | ||
786 | @end example | 789 | @end example |
787 | 790 | ||
788 | 791 | ||
789 | @item We primarily use @code{for} and @code{while} loops. A @code{while} | 792 | @item We primarily use @code{for} and @code{while} loops. |
790 | loop is used if the method for advancing in the loop is not a | 793 | A @code{while} loop is used if the method for advancing in the loop is |
791 | straightforward increment operation. In particular, we use: | 794 | not a straightforward increment operation. In particular, we use: |
792 | 795 | ||
793 | @example | 796 | @example |
794 | next = head; | 797 | next = head; |
@@ -802,7 +805,6 @@ while (NULL != (pos = next)) | |||
802 | @} | 805 | @} |
803 | @end example | 806 | @end example |
804 | 807 | ||
805 | |||
806 | to free entries in a list (as the iteration changes the structure of the | 808 | to free entries in a list (as the iteration changes the structure of the |
807 | list due to the free; the equivalent @code{for} loop does no longer | 809 | list due to the free; the equivalent @code{for} loop does no longer |
808 | follow the simple @code{for} paradigm of @code{for(INIT;TEST;INC)}). | 810 | follow the simple @code{for} paradigm of @code{for(INIT;TEST;INC)}). |
@@ -889,8 +891,8 @@ If you want to compile and run benchmarks, run configure with the | |||
889 | @code{--enable-benchmarks} option. | 891 | @code{--enable-benchmarks} option. |
890 | 892 | ||
891 | If you want to obtain code coverage results, run configure with the | 893 | If you want to obtain code coverage results, run configure with the |
892 | @code{--enable-coverage} option and run the coverage.sh script in | 894 | @code{--enable-coverage} option and run the @file{coverage.sh} script in |
893 | @file{contrib/}. | 895 | the @file{contrib/} directory. |
894 | 896 | ||
895 | @c *********************************************************************** | 897 | @c *********************************************************************** |
896 | @node Developing extensions for GNUnet using the gnunet-ext template | 898 | @node Developing extensions for GNUnet using the gnunet-ext template |
@@ -905,7 +907,9 @@ development of GNUnet services, command line tools, APIs and tests. | |||
905 | 907 | ||
906 | First of all you have to obtain gnunet-ext from git: | 908 | First of all you have to obtain gnunet-ext from git: |
907 | 909 | ||
908 | @code{git clone https://gnunet.org/git/gnunet-ext.git} | 910 | @example |
911 | git clone https://gnunet.org/git/gnunet-ext.git | ||
912 | @end example | ||
909 | 913 | ||
910 | The next step is to bootstrap and configure it. For configure you have to | 914 | The next step is to bootstrap and configure it. For configure you have to |
911 | provide the path containing GNUnet with | 915 | provide the path containing GNUnet with |
@@ -922,7 +926,9 @@ path, you have to add @code{/path/to/gnunet} to the file | |||
922 | @file{/etc/ld.so.conf} and run @code{ldconfig} or your add it to the | 926 | @file{/etc/ld.so.conf} and run @code{ldconfig} or your add it to the |
923 | environmental variable @code{LD_LIBRARY_PATH} by using | 927 | environmental variable @code{LD_LIBRARY_PATH} by using |
924 | 928 | ||
925 | @code{export LD_LIBRARY_PATH=/path/to/gnunet/lib} | 929 | @example |
930 | export LD_LIBRARY_PATH=/path/to/gnunet/lib | ||
931 | @end example | ||
926 | 932 | ||
927 | @c *********************************************************************** | 933 | @c *********************************************************************** |
928 | @node Writing testcases | 934 | @node Writing testcases |
@@ -942,9 +948,9 @@ progress information and not display debug messages by default. The | |||
942 | success or failure of a testcase must be indicated by returning zero | 948 | success or failure of a testcase must be indicated by returning zero |
943 | (success) or non-zero (failure) from the main method of the testcase. The | 949 | (success) or non-zero (failure) from the main method of the testcase. The |
944 | integration with the autotools is relatively straightforward and only | 950 | integration with the autotools is relatively straightforward and only |
945 | requires modifications to the @code{Makefile.am} in the directory | 951 | requires modifications to the @file{Makefile.am} in the directory |
946 | containing the testcase. For a testcase testing the code in @code{foo.c} | 952 | containing the testcase. For a testcase testing the code in @file{foo.c} |
947 | the @code{Makefile.am} would contain the following lines: | 953 | the @file{Makefile.am} would contain the following lines: |
948 | 954 | ||
949 | @example | 955 | @example |
950 | check_PROGRAMS = test_foo TESTS = $(check_PROGRAMS) test_foo_SOURCES = | 956 | check_PROGRAMS = test_foo TESTS = $(check_PROGRAMS) test_foo_SOURCES = |
@@ -1122,16 +1128,28 @@ The following code illustrates spawning and killing an ARM process from a | |||
1122 | testcase: | 1128 | testcase: |
1123 | 1129 | ||
1124 | @example | 1130 | @example |
1125 | static void run (void *cls, char *const *args, const char | 1131 | static void run (void *cls, |
1126 | *cfgfile, const struct GNUNET_CONFIGURATION_Handle *cfg) @{ struct | 1132 | char *const *args, |
1127 | GNUNET_OS_Process *arm_pid; arm_pid = GNUNET_OS_start_process (NULL, NULL, | 1133 | const char *cfgfile, |
1128 | "gnunet-service-arm", "gnunet-service-arm", "-c", cfgname, NULL); | 1134 | const struct GNUNET_CONFIGURATION_Handle *cfg) @{ |
1135 | struct GNUNET_OS_Process *arm_pid; | ||
1136 | arm_pid = GNUNET_OS_start_process (NULL, | ||
1137 | NULL, | ||
1138 | "gnunet-service-arm", | ||
1139 | "gnunet-service-arm", | ||
1140 | "-c", | ||
1141 | cfgname, | ||
1142 | NULL); | ||
1129 | /* do real test work here */ | 1143 | /* do real test work here */ |
1130 | if (0 != GNUNET_OS_process_kill (arm_pid, SIGTERM)) GNUNET_log_strerror | 1144 | if (0 != GNUNET_OS_process_kill (arm_pid, SIGTERM)) |
1131 | (GNUNET_ERROR_TYPE_WARNING, "kill"); GNUNET_assert (GNUNET_OK == | 1145 | GNUNET_log_strerror |
1132 | GNUNET_OS_process_wait (arm_pid)); GNUNET_OS_process_close (arm_pid); @} | 1146 | (GNUNET_ERROR_TYPE_WARNING, "kill"); |
1133 | 1147 | GNUNET_assert (GNUNET_OK == GNUNET_OS_process_wait (arm_pid)); | |
1134 | GNUNET_PROGRAM_run (argc, argv, "NAME-OF-TEST", "nohelp", options, &run, cls); | 1148 | GNUNET_OS_process_close (arm_pid); @} |
1149 | |||
1150 | GNUNET_PROGRAM_run (argc, argv, | ||
1151 | "NAME-OF-TEST", | ||
1152 | "nohelp", options, &run, cls); | ||
1135 | @end example | 1153 | @end example |
1136 | 1154 | ||
1137 | 1155 | ||
@@ -1183,8 +1201,11 @@ The code in the test should look like this: | |||
1183 | 1201 | ||
1184 | int main (int argc, char *argv[]) @{ | 1202 | int main (int argc, char *argv[]) @{ |
1185 | 1203 | ||
1186 | [run test, generate data] GAUGER("YOUR_MODULE", "METRIC_NAME", (float)value, | 1204 | [run test, generate data] |
1187 | "UNIT"); @} | 1205 | GAUGER("YOUR_MODULE", |
1206 | "METRIC_NAME", | ||
1207 | (float)value, | ||
1208 | "UNIT"); @} | ||
1188 | @end example | 1209 | @end example |
1189 | 1210 | ||
1190 | 1211 | ||
@@ -1310,10 +1331,8 @@ found in the standard path. This can be addressed by setting the variable | |||
1310 | `HELPER_BINARY_PATH' to the path of the testbed helper. Testbed API will | 1331 | `HELPER_BINARY_PATH' to the path of the testbed helper. Testbed API will |
1311 | then use this path to start helper binaries both locally and remotely. | 1332 | then use this path to start helper binaries both locally and remotely. |
1312 | 1333 | ||
1313 | Testbed API can accessed by including "gnunet_testbed_service.h" file and | 1334 | Testbed API can accessed by including the |
1314 | linking with -lgnunettestbed. | 1335 | "@file{gnunet_testbed_service.h}" file and linking with -lgnunettestbed. |
1315 | |||
1316 | |||
1317 | 1336 | ||
1318 | @c *********************************************************************** | 1337 | @c *********************************************************************** |
1319 | @menu | 1338 | @menu |
@@ -1628,16 +1647,20 @@ Install Distribute for zope.interface <= 3.8.0 (4.0 and 4.0.1 will not | |||
1628 | work): | 1647 | work): |
1629 | 1648 | ||
1630 | @example | 1649 | @example |
1631 | wget https://pypi.python.org/packages/source/z/zope.interface/zope.interface-3.8.0.tar.gz | 1650 | export PYPI="https://pypi.python.org/packages/source" |
1632 | tar zvfz zope.interface-3.8.0.tar.gz@ cd zope.interface-3.8.0 | 1651 | wget $PYPI/z/zope.interface/zope.interface-3.8.0.tar.gz |
1652 | tar zvfz zope.interface-3.8.0.tar.gz | ||
1653 | cd zope.interface-3.8.0 | ||
1633 | sudo python setup.py install | 1654 | sudo python setup.py install |
1634 | @end example | 1655 | @end example |
1635 | 1656 | ||
1636 | Install the buildslave software (0.8.6 was the latest version): | 1657 | Install the buildslave software (0.8.6 was the latest version): |
1637 | 1658 | ||
1638 | @example | 1659 | @example |
1639 | wget http://buildbot.googlecode.com/files/buildbot-slave-0.8.6p1.tar.gz | 1660 | export GCODE="http://buildbot.googlecode.com/files" |
1640 | tar xvfz buildbot-slave-0.8.6p1.tar.gz@ cd buildslave-0.8.6p1 | 1661 | wget $GCODE/buildbot-slave-0.8.6p1.tar.gz |
1662 | tar xvfz buildbot-slave-0.8.6p1.tar.gz | ||
1663 | cd buildslave-0.8.6p1 | ||
1641 | sudo python setup.py install | 1664 | sudo python setup.py install |
1642 | @end example | 1665 | @end example |
1643 | 1666 | ||
@@ -1670,8 +1693,8 @@ contrib/tasklists/install_buildslave_fc8.xml -a -p <planetlab password> | |||
1670 | 1693 | ||
1671 | The master and the and the slaves have need to have credentials and the | 1694 | The master and the and the slaves have need to have credentials and the |
1672 | master has to have all nodes configured. This can be done with the | 1695 | master has to have all nodes configured. This can be done with the |
1673 | @code{create_buildbot_configuration.py} script in the @code{scripts} | 1696 | @file{create_buildbot_configuration.py} script in the @file{scripts} |
1674 | directory | 1697 | directory. |
1675 | 1698 | ||
1676 | This scripts takes a list of nodes retrieved directly from PlanetLab or | 1699 | This scripts takes a list of nodes retrieved directly from PlanetLab or |
1677 | read from a file and a configuration template and creates: | 1700 | read from a file and a configuration template and creates: |
@@ -1687,14 +1710,22 @@ that the script replaces the following tags in the template: | |||
1687 | %GPLMT_BUILDER_DEFINITION :@ GPLMT_BUILDER_SUMMARY@ GPLMT_SLAVES@ | 1710 | %GPLMT_BUILDER_DEFINITION :@ GPLMT_BUILDER_SUMMARY@ GPLMT_SLAVES@ |
1688 | %GPLMT_SCHEDULER_BUILDERS | 1711 | %GPLMT_SCHEDULER_BUILDERS |
1689 | 1712 | ||
1690 | Create configuration for all nodes assigned to a slice:@ @code{@ | 1713 | Create configuration for all nodes assigned to a slice: |
1691 | ./create_buildbot_configuration.py -u <planetlab username> -p <planetlab | 1714 | |
1692 | password> -s <slice> -m <buildmaster+port> -t <template>@ }@ Create | 1715 | @example |
1693 | configuration for some nodes in a file:@ @code{@ | 1716 | ./create_buildbot_configuration.py -u <planetlab username> \ |
1694 | ./create_buildbot_configuration.p -f <node_file> -m <buildmaster+port> -t | 1717 | -p <planetlab password> -s <slice> -m <buildmaster+port> \ |
1695 | <template>@ } | 1718 | -t <template> |
1719 | @end example | ||
1720 | |||
1721 | Create configuration for some nodes in a file: | ||
1722 | |||
1723 | @example | ||
1724 | ./create_buildbot_configuration.p -f <node_file> \ | ||
1725 | -m <buildmaster+port> -t <template> | ||
1726 | @end example | ||
1696 | 1727 | ||
1697 | @item Copy the @code{master.cfg} to the buildmaster and start it | 1728 | @item Copy the @file{master.cfg} to the buildmaster and start it |
1698 | Use @code{buildbot start <basedir>} to start the server | 1729 | Use @code{buildbot start <basedir>} to start the server |
1699 | @item Setup the buildslaves | 1730 | @item Setup the buildslaves |
1700 | @end itemize | 1731 | @end itemize |
@@ -1713,14 +1744,17 @@ and then add the following to your ~/.ssh/config file: | |||
1713 | 1744 | ||
1714 | @code{Host 127.0.0.1@ IdentityFile ~/.ssh/id_localhost} | 1745 | @code{Host 127.0.0.1@ IdentityFile ~/.ssh/id_localhost} |
1715 | 1746 | ||
1716 | now make sure your hostsfile looks like@ | 1747 | now make sure your hostsfile looks like |
1717 | 1748 | ||
1749 | @example | ||
1718 | [USERNAME]@@127.0.0.1:22@ | 1750 | [USERNAME]@@127.0.0.1:22@ |
1719 | [USERNAME]@@127.0.0.1:22 | 1751 | [USERNAME]@@127.0.0.1:22 |
1752 | @end example | ||
1720 | 1753 | ||
1721 | You can test your setup by running `ssh 127.0.0.1` in a terminal and then | 1754 | You can test your setup by running @code{ssh 127.0.0.1} in a |
1722 | in the opened session run it again. If you were not asked for a password | 1755 | terminal and then in the opened session run it again. |
1723 | on either login, then you should be good to go. | 1756 | If you were not asked for a password on either login, |
1757 | then you should be good to go. | ||
1724 | 1758 | ||
1725 | @c *********************************************************************** | 1759 | @c *********************************************************************** |
1726 | @node TESTBED Caveats | 1760 | @node TESTBED Caveats |
@@ -1729,7 +1763,6 @@ on either login, then you should be good to go. | |||
1729 | This section documents a few caveats when using the GNUnet testbed | 1763 | This section documents a few caveats when using the GNUnet testbed |
1730 | subsystem. | 1764 | subsystem. |
1731 | 1765 | ||
1732 | |||
1733 | @c *********************************************************************** | 1766 | @c *********************************************************************** |
1734 | @menu | 1767 | @menu |
1735 | * CORE must be started:: | 1768 | * CORE must be started:: |
@@ -1767,7 +1800,7 @@ configure TESTBED to tolerate a certain number of connection failures | |||
1767 | for dense overlay topologies, especially if you try to create cliques | 1800 | for dense overlay topologies, especially if you try to create cliques |
1768 | with more than 20 peers. | 1801 | with more than 20 peers. |
1769 | 1802 | ||
1770 | @c *********************************************************************** | 1803 | @cindex libgnunetutil |
1771 | @node libgnunetutil | 1804 | @node libgnunetutil |
1772 | @section libgnunetutil | 1805 | @section libgnunetutil |
1773 | 1806 | ||
@@ -1820,7 +1853,8 @@ way to make porting of GNUnet easier. | |||
1820 | * The CONTAINER_MDLL API:: | 1853 | * The CONTAINER_MDLL API:: |
1821 | @end menu | 1854 | @end menu |
1822 | 1855 | ||
1823 | @c *********************************************************************** | 1856 | @cindex Logging |
1857 | @cindex log levels | ||
1824 | @node Logging | 1858 | @node Logging |
1825 | @subsection Logging | 1859 | @subsection Logging |
1826 | 1860 | ||
@@ -2062,7 +2096,7 @@ Another limitation, on Windows, GNUNET_FORCE_LOGFILE @strong{MUST} be set | |||
2062 | in order to GNUNET_FORCE_LOG to work. | 2096 | in order to GNUNET_FORCE_LOG to work. |
2063 | 2097 | ||
2064 | 2098 | ||
2065 | @c *********************************************************************** | 2099 | @cindex Log files |
2066 | @node Log files | 2100 | @node Log files |
2067 | @subsubsection Log files | 2101 | @subsubsection Log files |
2068 | 2102 | ||
@@ -2183,7 +2217,8 @@ Which will behave almost like enabling DEBUG in that subsytem before the | |||
2183 | change. Of course you can adapt it to your particular needs, this is only | 2217 | change. Of course you can adapt it to your particular needs, this is only |
2184 | a quick example. | 2218 | a quick example. |
2185 | 2219 | ||
2186 | @c *********************************************************************** | 2220 | @cindex Interprocess communication API |
2221 | @cindex ICP | ||
2187 | @node Interprocess communication API (IPC) | 2222 | @node Interprocess communication API (IPC) |
2188 | @subsection Interprocess communication API (IPC) | 2223 | @subsection Interprocess communication API (IPC) |
2189 | 2224 | ||
@@ -2525,8 +2560,7 @@ order. | |||
2525 | byte order. | 2560 | byte order. |
2526 | @end table | 2561 | @end table |
2527 | 2562 | ||
2528 | @c *********************************************************************** | 2563 | @cindex Cryptography API |
2529 | |||
2530 | @node Cryptography API | 2564 | @node Cryptography API |
2531 | @subsection Cryptography API | 2565 | @subsection Cryptography API |
2532 | @c %**end of header | 2566 | @c %**end of header |
@@ -2563,7 +2597,7 @@ be used by most applications; most importantly, | |||
2563 | GNUNET_CRYPTO_rsa_key_create_from_hash does not create an RSA-key that | 2597 | GNUNET_CRYPTO_rsa_key_create_from_hash does not create an RSA-key that |
2564 | should be considered secure for traditional applications of RSA. | 2598 | should be considered secure for traditional applications of RSA. |
2565 | 2599 | ||
2566 | @c *********************************************************************** | 2600 | @cindex Message Queue API |
2567 | @node Message Queue API | 2601 | @node Message Queue API |
2568 | @subsection Message Queue API | 2602 | @subsection Message Queue API |
2569 | @c %**end of header | 2603 | @c %**end of header |
@@ -2643,8 +2677,10 @@ An envelope containing an instance of the NumberMessage can be | |||
2643 | constructed like this: | 2677 | constructed like this: |
2644 | 2678 | ||
2645 | @example | 2679 | @example |
2646 | struct GNUNET_MQ_Envelope *ev; struct NumberMessage *msg; ev = | 2680 | struct GNUNET_MQ_Envelope *ev; |
2647 | GNUNET_MQ_msg (msg, GNUNET_MESSAGE_TYPE_EXAMPLE_1); msg->number = htonl (42); | 2681 | struct NumberMessage *msg; |
2682 | ev = GNUNET_MQ_msg (msg, GNUNET_MESSAGE_TYPE_EXAMPLE_1); | ||
2683 | msg->number = htonl (42); | ||
2648 | @end example | 2684 | @end example |
2649 | 2685 | ||
2650 | In the above code, @code{GNUNET_MQ_msg} is a macro. The return value is | 2686 | In the above code, @code{GNUNET_MQ_msg} is a macro. The return value is |
@@ -2703,7 +2739,7 @@ callback. When canceling an envelope, it is not necessary@ to call | |||
2703 | @strong{ Implementing Queues }@ | 2739 | @strong{ Implementing Queues }@ |
2704 | @code{TODO} | 2740 | @code{TODO} |
2705 | 2741 | ||
2706 | @c *********************************************************************** | 2742 | @cindex Service API |
2707 | @node Service API | 2743 | @node Service API |
2708 | @subsection Service API | 2744 | @subsection Service API |
2709 | @c %**end of header | 2745 | @c %**end of header |
@@ -2933,7 +2969,8 @@ previously audited and modified to take advantage of the new capability. | |||
2933 | In particular, memory consumption of the file-sharing service is expected | 2969 | In particular, memory consumption of the file-sharing service is expected |
2934 | to drop by 20-30% due to this change. | 2970 | to drop by 20-30% due to this change. |
2935 | 2971 | ||
2936 | @c *********************************************************************** | 2972 | |
2973 | @cindex CONTAINER_MDLL API | ||
2937 | @node The CONTAINER_MDLL API | 2974 | @node The CONTAINER_MDLL API |
2938 | @subsection The CONTAINER_MDLL API | 2975 | @subsection The CONTAINER_MDLL API |
2939 | @c %**end of header | 2976 | @c %**end of header |
@@ -2998,7 +3035,8 @@ at tail, after a given element) and removing elements from the list. | |||
2998 | Iterating over the list should be done by directly accessing the | 3035 | Iterating over the list should be done by directly accessing the |
2999 | "next_XX" and/or "prev_XX" members. | 3036 | "next_XX" and/or "prev_XX" members. |
3000 | 3037 | ||
3001 | @c *********************************************************************** | 3038 | @cindex Automatic Restart Manager |
3039 | @cindex ARM | ||
3002 | @node The Automatic Restart Manager (ARM) | 3040 | @node The Automatic Restart Manager (ARM) |
3003 | @section The Automatic Restart Manager (ARM) | 3041 | @section The Automatic Restart Manager (ARM) |
3004 | @c %**end of header | 3042 | @c %**end of header |
@@ -3015,7 +3053,7 @@ about how ARM works and how to interact with it. | |||
3015 | @menu | 3053 | @menu |
3016 | * Basic functionality:: | 3054 | * Basic functionality:: |
3017 | * Key configuration options:: | 3055 | * Key configuration options:: |
3018 | * Availability2:: | 3056 | * ARM - Availability:: |
3019 | * Reliability:: | 3057 | * Reliability:: |
3020 | @end menu | 3058 | @end menu |
3021 | 3059 | ||
@@ -3109,8 +3147,8 @@ services that are going to run. | |||
3109 | @end table | 3147 | @end table |
3110 | 3148 | ||
3111 | @c *********************************************************************** | 3149 | @c *********************************************************************** |
3112 | @node Availability2 | 3150 | @node ARM - Availability |
3113 | @subsection Availability2 | 3151 | @subsection ARM - Availability |
3114 | @c %**end of header | 3152 | @c %**end of header |
3115 | 3153 | ||
3116 | As mentioned before, one of the features provided by ARM is starting | 3154 | As mentioned before, one of the features provided by ARM is starting |
@@ -3195,7 +3233,7 @@ backoff(S) will remain half an hour, hence ARM won't be busy for a lot of | |||
3195 | time trying to restart a problematic service. | 3233 | time trying to restart a problematic service. |
3196 | @end itemize | 3234 | @end itemize |
3197 | 3235 | ||
3198 | @c *********************************************************************** | 3236 | @cindex TRANSPORT Subsystem |
3199 | @node GNUnet's TRANSPORT Subsystem | 3237 | @node GNUnet's TRANSPORT Subsystem |
3200 | @section GNUnet's TRANSPORT Subsystem | 3238 | @section GNUnet's TRANSPORT Subsystem |
3201 | @c %**end of header | 3239 | @c %**end of header |
@@ -3313,6 +3351,7 @@ The PONG message is protected with a nonce/challenge against replay | |||
3313 | attacks and uses an expiration time for the signature (but those are | 3351 | attacks and uses an expiration time for the signature (but those are |
3314 | almost implementation details). | 3352 | almost implementation details). |
3315 | 3353 | ||
3354 | @cindex NAT library | ||
3316 | @node NAT library | 3355 | @node NAT library |
3317 | @section NAT library | 3356 | @section NAT library |
3318 | @c %**end of header | 3357 | @c %**end of header |
@@ -3422,6 +3461,7 @@ the message in a new DV message for Carol. The DV transport at Carol | |||
3422 | receives this message, unwraps the original message, and delivers it to | 3461 | receives this message, unwraps the original message, and delivers it to |
3423 | Carol as though it came directly from Alice. | 3462 | Carol as though it came directly from Alice. |
3424 | 3463 | ||
3464 | @cindex SMTP plugin | ||
3425 | @node SMTP plugin | 3465 | @node SMTP plugin |
3426 | @section SMTP plugin | 3466 | @section SMTP plugin |
3427 | @c %**end of header | 3467 | @c %**end of header |
@@ -3631,6 +3671,7 @@ MTU of 12,000 octets improves the throughput to 13 kbps as figure | |||
3631 | smtp-MTUs shows. Our research paper) has some more details on the | 3671 | smtp-MTUs shows. Our research paper) has some more details on the |
3632 | benchmarking results. | 3672 | benchmarking results. |
3633 | 3673 | ||
3674 | @cindex Bluetooth plugin | ||
3634 | @node Bluetooth plugin | 3675 | @node Bluetooth plugin |
3635 | @section Bluetooth plugin | 3676 | @section Bluetooth plugin |
3636 | @c %**end of header | 3677 | @c %**end of header |
@@ -3648,8 +3689,6 @@ ask on the IRC channel. | |||
3648 | @item How can I test it? | 3689 | @item How can I test it? |
3649 | @end itemize | 3690 | @end itemize |
3650 | 3691 | ||
3651 | |||
3652 | |||
3653 | @menu | 3692 | @menu |
3654 | * What do I need to use the Bluetooth plugin transport?:: | 3693 | * What do I need to use the Bluetooth plugin transport?:: |
3655 | * How does it work2?:: | 3694 | * How does it work2?:: |
@@ -4366,6 +4405,7 @@ tell which @code{SendMessageRequest} the CORE service's | |||
4366 | "unique" request ID (based on a counter incremented by the client | 4405 | "unique" request ID (based on a counter incremented by the client |
4367 | for each request). | 4406 | for each request). |
4368 | 4407 | ||
4408 | @cindex CORE Peer-to-Peer Protocol | ||
4369 | @node The CORE Peer-to-Peer Protocol | 4409 | @node The CORE Peer-to-Peer Protocol |
4370 | @subsection The CORE Peer-to-Peer Protocol | 4410 | @subsection The CORE Peer-to-Peer Protocol |
4371 | @c %**end of header | 4411 | @c %**end of header |
@@ -4827,7 +4867,7 @@ is no longer called with new estimates. | |||
4827 | 4867 | ||
4828 | @menu | 4868 | @menu |
4829 | * Results:: | 4869 | * Results:: |
4830 | * Examples2:: | 4870 | * libgnunetnse - Examples:: |
4831 | @end menu | 4871 | @end menu |
4832 | 4872 | ||
4833 | @node Results | 4873 | @node Results |
@@ -4868,8 +4908,8 @@ deviation value, not only the average (in particular, if the standard | |||
4868 | veriation is very high, the average maybe meaningless: the network size is | 4908 | veriation is very high, the average maybe meaningless: the network size is |
4869 | changing rapidly). | 4909 | changing rapidly). |
4870 | 4910 | ||
4871 | @node Examples2 | 4911 | @node libgnunetnse - Examples |
4872 | @subsubsection Examples2 | 4912 | @subsubsection libgnunetnse -Examples |
4873 | 4913 | ||
4874 | @c %**end of header | 4914 | @c %**end of header |
4875 | 4915 | ||
@@ -4915,6 +4955,7 @@ deviation for the respective round. | |||
4915 | When the @code{GNUNET_NSE_disconnect} API call is executed, the client | 4955 | When the @code{GNUNET_NSE_disconnect} API call is executed, the client |
4916 | simply disconnects from the service, with no message involved. | 4956 | simply disconnects from the service, with no message involved. |
4917 | 4957 | ||
4958 | @cindex NSE Peer-to-Peer Protocol | ||
4918 | @node The NSE Peer-to-Peer Protocol | 4959 | @node The NSE Peer-to-Peer Protocol |
4919 | @subsection The NSE Peer-to-Peer Protocol | 4960 | @subsection The NSE Peer-to-Peer Protocol |
4920 | 4961 | ||
@@ -5044,7 +5085,7 @@ service. | |||
5044 | 5085 | ||
5045 | @menu | 5086 | @menu |
5046 | * Features:: | 5087 | * Features:: |
5047 | * Limitations2:: | 5088 | * HOSTLIST - Limitations:: |
5048 | @end menu | 5089 | @end menu |
5049 | 5090 | ||
5050 | @node Features | 5091 | @node Features |
@@ -5065,8 +5106,8 @@ via gossip | |||
5065 | peers | 5106 | peers |
5066 | @end itemize | 5107 | @end itemize |
5067 | 5108 | ||
5068 | @node Limitations2 | 5109 | @node HOSTLIST - Limitations |
5069 | @subsubsection Limitations2 | 5110 | @subsubsection HOSTLIST - Limitations |
5070 | 5111 | ||
5071 | @c %**end of header | 5112 | @c %**end of header |
5072 | 5113 | ||
@@ -5125,6 +5166,7 @@ contacts the HOSTLIST servers specified in the configuration, downloads | |||
5125 | the (unvalidated) list of HELLO messages and forwards these information | 5166 | the (unvalidated) list of HELLO messages and forwards these information |
5126 | to the TRANSPORT server to validate the addresses. | 5167 | to the TRANSPORT server to validate the addresses. |
5127 | 5168 | ||
5169 | @cindex HOSTLIST daemon | ||
5128 | @node The HOSTLIST daemon | 5170 | @node The HOSTLIST daemon |
5129 | @subsection The HOSTLIST daemon | 5171 | @subsection The HOSTLIST daemon |
5130 | 5172 | ||
@@ -5154,6 +5196,7 @@ can notify them about CORE events. | |||
5154 | To clean up on shutdown, the daemon has a cleaning task, shutting down all | 5196 | To clean up on shutdown, the daemon has a cleaning task, shutting down all |
5155 | subsystems and disconnecting from CORE. | 5197 | subsystems and disconnecting from CORE. |
5156 | 5198 | ||
5199 | @cindex HOSTLIST server | ||
5157 | @node The HOSTLIST server | 5200 | @node The HOSTLIST server |
5158 | @subsection The HOSTLIST server | 5201 | @subsection The HOSTLIST server |
5159 | 5202 | ||
@@ -5207,6 +5250,7 @@ When a new peer connects and has hostlist learning enabled, the server | |||
5207 | sends a @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} message to this | 5250 | sends a @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} message to this |
5208 | peer using the CORE service. | 5251 | peer using the CORE service. |
5209 | 5252 | ||
5253 | @cindex HOSTLIST client | ||
5210 | @node The HOSTLIST client | 5254 | @node The HOSTLIST client |
5211 | @subsection The HOSTLIST client | 5255 | @subsection The HOSTLIST client |
5212 | 5256 | ||
@@ -5655,8 +5699,8 @@ To not duplicate this functionality we plan to provide a PEERSTORE | |||
5655 | service providing this functionality. | 5699 | service providing this functionality. |
5656 | 5700 | ||
5657 | @menu | 5701 | @menu |
5658 | * Features2:: | 5702 | * PEERINFO - Features:: |
5659 | * Limitations3:: | 5703 | * PEERINFO - Limitations:: |
5660 | * DeveloperPeer Information:: | 5704 | * DeveloperPeer Information:: |
5661 | * Startup:: | 5705 | * Startup:: |
5662 | * Managing Information:: | 5706 | * Managing Information:: |
@@ -5665,8 +5709,8 @@ service providing this functionality. | |||
5665 | * libgnunetpeerinfo:: | 5709 | * libgnunetpeerinfo:: |
5666 | @end menu | 5710 | @end menu |
5667 | 5711 | ||
5668 | @node Features2 | 5712 | @node PEERINFO - Features |
5669 | @subsection Features2 | 5713 | @subsection PEERINFO - Features |
5670 | 5714 | ||
5671 | @c %**end of header | 5715 | @c %**end of header |
5672 | 5716 | ||
@@ -5677,8 +5721,8 @@ service providing this functionality. | |||
5677 | @item Differentiation between public and friend-only HELLO | 5721 | @item Differentiation between public and friend-only HELLO |
5678 | @end itemize | 5722 | @end itemize |
5679 | 5723 | ||
5680 | @node Limitations3 | 5724 | @node PEERINFO - Limitations |
5681 | @subsection Limitations3 | 5725 | @subsection PEERINFO - Limitations |
5682 | 5726 | ||
5683 | 5727 | ||
5684 | @itemize @bullet | 5728 | @itemize @bullet |
@@ -5690,42 +5734,48 @@ service providing this functionality. | |||
5690 | 5734 | ||
5691 | @c %**end of header | 5735 | @c %**end of header |
5692 | 5736 | ||
5693 | The PEERINFO subsystem stores these information in the form of HELLO messages | 5737 | The PEERINFO subsystem stores these information in the form of HELLO |
5694 | you can think of as business cards. These HELLO messages contain the public key | 5738 | messages you can think of as business cards. |
5695 | of a peer and the addresses a peer can be reached under. The addresses include | 5739 | These HELLO messages contain the public key of a peer and the addresses |
5696 | an expiration date describing how long they are valid. This information is | 5740 | a peer can be reached under. |
5697 | updated regularly by the TRANSPORT service by revalidating the address. If an | 5741 | The addresses include an expiration date describing how long they are |
5698 | address is expired and not renewed, it can be removed from the HELLO message. | 5742 | valid. This information is updated regularly by the TRANSPORT service by |
5699 | 5743 | revalidating the address. | |
5700 | Some peer do not want to have their HELLO messages distributed to other peers , | 5744 | If an address is expired and not renewed, it can be removed from the |
5701 | especially when GNUnet's friend-to-friend modus is enabled. To prevent this | 5745 | HELLO message. |
5702 | undesired distribution. PEERINFO distinguishes between @emph{public} and | 5746 | |
5703 | @emph{friend-only} HELLO messages. Public HELLO messages can be freely | 5747 | Some peer do not want to have their HELLO messages distributed to other |
5704 | distributed to other (possibly unknown) peers (for example using the hostlist, | 5748 | peers, especially when GNUnet's friend-to-friend modus is enabled. |
5705 | gossiping, broadcasting), whereas friend-only HELLO messages may not be | 5749 | To prevent this undesired distribution. PEERINFO distinguishes between |
5706 | distributed to other peers. Friend-only HELLO messages have an additional flag | 5750 | @emph{public} and @emph{friend-only} HELLO messages. |
5707 | @code{friend_only} set internally. For public HELLO message this flag is not | 5751 | Public HELLO messages can be freely distributed to other (possibly |
5708 | set. PEERINFO does and cannot not check if a client is allowed to obtain a | 5752 | unknown) peers (for example using the hostlist, gossiping, broadcasting), |
5753 | whereas friend-only HELLO messages may not be distributed to other peers. | ||
5754 | Friend-only HELLO messages have an additional flag @code{friend_only} set | ||
5755 | internally. For public HELLO message this flag is not set. | ||
5756 | PEERINFO does and cannot not check if a client is allowed to obtain a | ||
5709 | specific HELLO type. | 5757 | specific HELLO type. |
5710 | 5758 | ||
5711 | The HELLO messages can be managed using the GNUnet HELLO library. Other GNUnet | 5759 | The HELLO messages can be managed using the GNUnet HELLO library. |
5712 | systems can obtain these information from PEERINFO and use it for their | 5760 | Other GNUnet systems can obtain these information from PEERINFO and use |
5713 | purposes. Clients are for example the HOSTLIST component providing these | 5761 | it for their purposes. |
5714 | information to other peers in form of a hostlist or the TRANSPORT subsystem | 5762 | Clients are for example the HOSTLIST component providing these |
5715 | using these information to maintain connections to other peers. | 5763 | information to other peers in form of a hostlist or the TRANSPORT |
5764 | subsystem using these information to maintain connections to other peers. | ||
5716 | 5765 | ||
5717 | @node Startup | 5766 | @node Startup |
5718 | @subsection Startup | 5767 | @subsection Startup |
5719 | 5768 | ||
5720 | @c %**end of header | 5769 | @c %**end of header |
5721 | 5770 | ||
5722 | During startup the PEERINFO services loads persistent HELLOs from disk. First | 5771 | During startup the PEERINFO services loads persistent HELLOs from disk. |
5723 | PEERINFO parses the directory configured in the HOSTS value of the | 5772 | First PEERINFO parses the directory configured in the HOSTS value of the |
5724 | @code{PEERINFO} configuration section to store PEERINFO information.@ For all | 5773 | @code{PEERINFO} configuration section to store PEERINFO information. |
5725 | files found in this directory valid HELLO messages are extracted. In addition | 5774 | For all files found in this directory valid HELLO messages are extracted. |
5726 | it loads HELLO messages shipped with the GNUnet distribution. These HELLOs are | 5775 | In addition it loads HELLO messages shipped with the GNUnet distribution. |
5727 | used to simplify network bootstrapping by providing valid peer information with | 5776 | These HELLOs are used to simplify network bootstrapping by providing |
5728 | the distribution. The use of these HELLOs can be prevented by setting the | 5777 | valid peer information with the distribution. |
5778 | The use of these HELLOs can be prevented by setting the | ||
5729 | @code{USE_INCLUDED_HELLOS} in the @code{PEERINFO} configuration section to | 5779 | @code{USE_INCLUDED_HELLOS} in the @code{PEERINFO} configuration section to |
5730 | @code{NO}. Files containing invalid information are removed. | 5780 | @code{NO}. Files containing invalid information are removed. |
5731 | 5781 | ||
@@ -5734,66 +5784,71 @@ the distribution. The use of these HELLOs can be prevented by setting the | |||
5734 | 5784 | ||
5735 | @c %**end of header | 5785 | @c %**end of header |
5736 | 5786 | ||
5737 | The PEERINFO services stores information about known PEERS and a single HELLO | 5787 | The PEERINFO services stores information about known PEERS and a single |
5738 | message for every peer. A peer does not need to have a HELLO if no information | 5788 | HELLO message for every peer. |
5739 | are available. HELLO information from different sources, for example a HELLO | 5789 | A peer does not need to have a HELLO if no information are available. |
5740 | obtained from a remote HOSTLIST and a second HELLO stored on disk, are combined | 5790 | HELLO information from different sources, for example a HELLO obtained |
5791 | from a remote HOSTLIST and a second HELLO stored on disk, are combined | ||
5741 | and merged into one single HELLO message per peer which will be given to | 5792 | and merged into one single HELLO message per peer which will be given to |
5742 | clients. During this merge process the HELLO is immediately written to disk to | 5793 | clients. During this merge process the HELLO is immediately written to |
5743 | ensure persistence. | 5794 | disk to ensure persistence. |
5744 | 5795 | ||
5745 | PEERINFO in addition periodically scans the directory where information are | 5796 | PEERINFO in addition periodically scans the directory where information |
5746 | stored for empty HELLO messages with expired TRANSPORT addresses.@ This | 5797 | are stored for empty HELLO messages with expired TRANSPORT addresses. |
5747 | periodic task scans all files in the directory and recreates the HELLO messages | 5798 | This periodic task scans all files in the directory and recreates the |
5748 | it finds. Expired TRANSPORT addresses are removed from the HELLO and if the | 5799 | HELLO messages it finds. |
5749 | HELLO does not contain any valid addresses, it is discarded and removed from | 5800 | Expired TRANSPORT addresses are removed from the HELLO and if the |
5750 | disk. | 5801 | HELLO does not contain any valid addresses, it is discarded and removed |
5802 | from the disk. | ||
5751 | 5803 | ||
5752 | @node Obtaining Information | 5804 | @node Obtaining Information |
5753 | @subsection Obtaining Information | 5805 | @subsection Obtaining Information |
5754 | 5806 | ||
5755 | @c %**end of header | 5807 | @c %**end of header |
5756 | 5808 | ||
5757 | When a client requests information from PEERINFO, PEERINFO performs a lookup | 5809 | When a client requests information from PEERINFO, PEERINFO performs a |
5758 | for the respective peer or all peers if desired and transmits this information | 5810 | lookup for the respective peer or all peers if desired and transmits this |
5759 | to the client. The client can specify if friend-only HELLOs have to be included | 5811 | information to the client. |
5760 | or not and PEERINFO filters the respective HELLO messages before transmitting | 5812 | The client can specify if friend-only HELLOs have to be included or not |
5813 | and PEERINFO filters the respective HELLO messages before transmitting | ||
5761 | information. | 5814 | information. |
5762 | 5815 | ||
5763 | To notify clients about changes to PEERINFO information, PEERINFO maintains a | 5816 | To notify clients about changes to PEERINFO information, PEERINFO |
5764 | list of clients interested in this notifications. Such a notification occurs if | 5817 | maintains a list of clients interested in this notifications. |
5765 | a HELLO for a peer was updated (due to a merge for example) or a new peer was | 5818 | Such a notification occurs if a HELLO for a peer was updated (due to a |
5766 | added. | 5819 | merge for example) or a new peer was added. |
5767 | 5820 | ||
5768 | @node The PEERINFO Client-Service Protocol | 5821 | @node The PEERINFO Client-Service Protocol |
5769 | @subsection The PEERINFO Client-Service Protocol | 5822 | @subsection The PEERINFO Client-Service Protocol |
5770 | 5823 | ||
5771 | @c %**end of header | 5824 | @c %**end of header |
5772 | 5825 | ||
5773 | To connect and disconnect to and from the PEERINFO Service PEERINFO utilizes | 5826 | To connect and disconnect to and from the PEERINFO Service PEERINFO |
5774 | the util client/server infrastructure, so no special messages types are used | 5827 | utilizes the util client/server infrastructure, so no special messages |
5775 | here. | 5828 | types are used here. |
5776 | 5829 | ||
5777 | To add information for a peer, the plain HELLO message is transmitted to the | 5830 | To add information for a peer, the plain HELLO message is transmitted to |
5778 | service without any wrapping. Alle information required are stored within the | 5831 | the service without any wrapping. All pieces of information required are |
5779 | HELLO message. The PEERINFO service provides a message handler accepting and | 5832 | stored within the HELLO message. |
5780 | processing these HELLO messages. | 5833 | The PEERINFO service provides a message handler accepting and processing |
5834 | these HELLO messages. | ||
5781 | 5835 | ||
5782 | When obtaining PEERINFO information using the iterate functionality specific | 5836 | When obtaining PEERINFO information using the iterate functionality |
5783 | messages are used. To obtain information for all peers, a @code{struct | 5837 | specific messages are used. To obtain information for all peers, a |
5784 | ListAllPeersMessage} with message type | 5838 | @code{struct ListAllPeersMessage} with message type |
5785 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_GET_ALL} and a flag include_friend_only to | 5839 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_GET_ALL} and a flag |
5786 | indicate if friend-only HELLO messages should be included are transmitted. If | 5840 | include_friend_only to indicate if friend-only HELLO messages should be |
5787 | information for a specific peer is required a @code{struct ListAllPeersMessage} | 5841 | included are transmitted. If information for a specific peer is required |
5788 | with @code{GNUNET_MESSAGE_TYPE_PEERINFO_GET} containing the peer identity is | 5842 | a @code{struct ListAllPeersMessage} with |
5843 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_GET} containing the peer identity is | ||
5789 | used. | 5844 | used. |
5790 | 5845 | ||
5791 | For both variants the PEERINFO service replies for each HELLO message he wants | 5846 | For both variants the PEERINFO service replies for each HELLO message it |
5792 | to transmit with a @code{struct ListAllPeersMessage} with type | 5847 | wants to transmit with a @code{struct ListAllPeersMessage} with type |
5793 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_INFO} containing the plain HELLO. The final | 5848 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_INFO} containing the plain HELLO. |
5794 | message is @code{struct GNUNET_MessageHeader} with type | 5849 | The final message is @code{struct GNUNET_MessageHeader} with type |
5795 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_INFO}. If the client receives this message, | 5850 | @code{GNUNET_MESSAGE_TYPE_PEERINFO_INFO}. If the client receives this |
5796 | he can proceed with the next request if any is pending | 5851 | message, it can proceed with the next request if any is pending. |
5797 | 5852 | ||
5798 | @node libgnunetpeerinfo | 5853 | @node libgnunetpeerinfo |
5799 | @subsection libgnunetpeerinfo | 5854 | @subsection libgnunetpeerinfo |
@@ -5819,9 +5874,10 @@ The PEERINFO API consists mainly of three different functionalities: | |||
5819 | 5874 | ||
5820 | @c %**end of header | 5875 | @c %**end of header |
5821 | 5876 | ||
5822 | To connect to the PEERINFO service the function @code{GNUNET_PEERINFO_connect} | 5877 | To connect to the PEERINFO service the function |
5823 | is used, taking a configuration handle as an argument, and to disconnect from | 5878 | @code{GNUNET_PEERINFO_connect} is used, taking a configuration handle as |
5824 | PEERINFO the function @code{GNUNET_PEERINFO_disconnect}, taking the PEERINFO | 5879 | an argument, and to disconnect from PEERINFO the function |
5880 | @code{GNUNET_PEERINFO_disconnect}, taking the PEERINFO | ||
5825 | handle returned from the connect function has to be called. | 5881 | handle returned from the connect function has to be called. |
5826 | 5882 | ||
5827 | @node Adding Information to the PEERINFO Service | 5883 | @node Adding Information to the PEERINFO Service |
@@ -5831,44 +5887,48 @@ handle returned from the connect function has to be called. | |||
5831 | 5887 | ||
5832 | @code{GNUNET_PEERINFO_add_peer} adds a new peer to the PEERINFO subsystem | 5888 | @code{GNUNET_PEERINFO_add_peer} adds a new peer to the PEERINFO subsystem |
5833 | storage. This function takes the PEERINFO handle as an argument, the HELLO | 5889 | storage. This function takes the PEERINFO handle as an argument, the HELLO |
5834 | message to store and a continuation with a closure to be called with the result | 5890 | message to store and a continuation with a closure to be called with the |
5835 | of the operation. The @code{GNUNET_PEERINFO_add_peer} returns a handle to this | 5891 | result of the operation. |
5836 | operation allowing to cancel the operation with the respective cancel function | 5892 | The @code{GNUNET_PEERINFO_add_peer} returns a handle to this operation |
5837 | @code{GNUNET_PEERINFO_add_peer_cancel}. To retrieve information from PEERINFO | 5893 | allowing to cancel the operation with the respective cancel function |
5838 | you can iterate over all information stored with PEERINFO or you can tell | 5894 | @code{GNUNET_PEERINFO_add_peer_cancel}. To retrieve information from |
5839 | PEERINFO to notify if new peer information are available. | 5895 | PEERINFO you can iterate over all information stored with PEERINFO or you |
5896 | can tell PEERINFO to notify if new peer information are available. | ||
5840 | 5897 | ||
5841 | @node Obtaining Information from the PEERINFO Service | 5898 | @node Obtaining Information from the PEERINFO Service |
5842 | @subsubsection Obtaining Information from the PEERINFO Service | 5899 | @subsubsection Obtaining Information from the PEERINFO Service |
5843 | 5900 | ||
5844 | @c %**end of header | 5901 | @c %**end of header |
5845 | 5902 | ||
5846 | To iterate over information in PEERINFO you use @code{GNUNET_PEERINFO_iterate}. | 5903 | To iterate over information in PEERINFO you use |
5847 | This function expects the PEERINFO handle, a flag if HELLO messages intended | 5904 | @code{GNUNET_PEERINFO_iterate}. |
5848 | for friend only mode should be included, a timeout how long the operation | 5905 | This function expects the PEERINFO handle, a flag if HELLO messages |
5849 | should take and a callback with a callback closure to be called for the | 5906 | intended for friend only mode should be included, a timeout how long the |
5850 | results. If you want to obtain information for a specific peer, you can specify | 5907 | operation should take and a callback with a callback closure to be called |
5908 | for the results. | ||
5909 | If you want to obtain information for a specific peer, you can specify | ||
5851 | the peer identity, if this identity is NULL, information for all peers are | 5910 | the peer identity, if this identity is NULL, information for all peers are |
5852 | returned. The function returns a handle to allow to cancel the operation using | 5911 | returned. The function returns a handle to allow to cancel the operation |
5853 | @code{GNUNET_PEERINFO_iterate_cancel}. | 5912 | using @code{GNUNET_PEERINFO_iterate_cancel}. |
5854 | 5913 | ||
5855 | To get notified when peer information changes, you can use | 5914 | To get notified when peer information changes, you can use |
5856 | @code{GNUNET_PEERINFO_notify}. This function expects a configuration handle and | 5915 | @code{GNUNET_PEERINFO_notify}. |
5857 | a flag if friend-only HELLO messages should be included. The PEERINFO service | 5916 | This function expects a configuration handle and a flag if friend-only |
5858 | will notify you about every change and the callback function will be called to | 5917 | HELLO messages should be included. The PEERINFO service will notify you |
5859 | notify you about changes. The function returns a handle to cancel notifications | 5918 | about every change and the callback function will be called to notify you |
5919 | about changes. The function returns a handle to cancel notifications | ||
5860 | with @code{GNUNET_PEERINFO_notify_cancel}. | 5920 | with @code{GNUNET_PEERINFO_notify_cancel}. |
5861 | 5921 | ||
5862 | 5922 | @cindex PEERSTORE subsystem | |
5863 | @node GNUnet's PEERSTORE subsystem | 5923 | @node GNUnet's PEERSTORE subsystem |
5864 | @section GNUnet's PEERSTORE subsystem | 5924 | @section GNUnet's PEERSTORE subsystem |
5865 | 5925 | ||
5866 | @c %**end of header | 5926 | @c %**end of header |
5867 | 5927 | ||
5868 | GNUnet's PEERSTORE subsystem offers persistent per-peer storage for other | 5928 | GNUnet's PEERSTORE subsystem offers persistent per-peer storage for other |
5869 | GNUnet subsystems. GNUnet subsystems can use PEERSTORE to persistently store | 5929 | GNUnet subsystems. GNUnet subsystems can use PEERSTORE to persistently |
5870 | and retrieve arbitrary data. Each data record stored with PEERSTORE contains | 5930 | store and retrieve arbitrary data. |
5871 | the following fields: | 5931 | Each data record stored with PEERSTORE contains the following fields: |
5872 | 5932 | ||
5873 | @itemize @bullet | 5933 | @itemize @bullet |
5874 | @item subsystem: Name of the subsystem responsible for the record. | 5934 | @item subsystem: Name of the subsystem responsible for the record. |
@@ -5890,10 +5950,11 @@ the following fields: | |||
5890 | @c %**end of header | 5950 | @c %**end of header |
5891 | 5951 | ||
5892 | Subsystems can store any type of value under a (subsystem, peerid, key) | 5952 | Subsystems can store any type of value under a (subsystem, peerid, key) |
5893 | combination. A "replace" flag set during store operations forces the PEERSTORE | 5953 | combination. A "replace" flag set during store operations forces the |
5894 | to replace any old values stored under the same (subsystem, peerid, key) | 5954 | PEERSTORE to replace any old values stored under the same |
5895 | combination with the new value. Additionally, an expiry date is set after which | 5955 | (subsystem, peerid, key) combination with the new value. |
5896 | the record is *possibly* deleted by PEERSTORE. | 5956 | Additionally, an expiry date is set after which the record is *possibly* |
5957 | deleted by PEERSTORE. | ||
5897 | 5958 | ||
5898 | Subsystems can iterate over all values stored under any of the following | 5959 | Subsystems can iterate over all values stored under any of the following |
5899 | combination of fields: | 5960 | combination of fields: |
@@ -5905,9 +5966,9 @@ combination of fields: | |||
5905 | @item (subsystem, peerid, key) | 5966 | @item (subsystem, peerid, key) |
5906 | @end itemize | 5967 | @end itemize |
5907 | 5968 | ||
5908 | Subsystems can also request to be notified about any new values stored under a | 5969 | Subsystems can also request to be notified about any new values stored |
5909 | (subsystem, peerid, key) combination by sending a "watch" request to | 5970 | under a (subsystem, peerid, key) combination by sending a "watch" |
5910 | PEERSTORE. | 5971 | request to PEERSTORE. |
5911 | 5972 | ||
5912 | @node Architecture | 5973 | @node Architecture |
5913 | @subsection Architecture | 5974 | @subsection Architecture |
@@ -5920,10 +5981,11 @@ PEERSTORE implements the following components: | |||
5920 | @item PEERSTORE service: Handles store, iterate and watch operations. | 5981 | @item PEERSTORE service: Handles store, iterate and watch operations. |
5921 | @item PEERSTORE API: API to be used by other subsystems to communicate and | 5982 | @item PEERSTORE API: API to be used by other subsystems to communicate and |
5922 | issue commands to the PEERSTORE service. | 5983 | issue commands to the PEERSTORE service. |
5923 | @item PEERSTORE plugins: Handles the persistent storage. At the moment, only an | 5984 | @item PEERSTORE plugins: Handles the persistent storage. At the moment, |
5924 | "sqlite" plugin is implemented. | 5985 | only an "sqlite" plugin is implemented. |
5925 | @end itemize | 5986 | @end itemize |
5926 | 5987 | ||
5988 | @cindex libgnunetpeerstore | ||
5927 | @node libgnunetpeerstore | 5989 | @node libgnunetpeerstore |
5928 | @subsection libgnunetpeerstore | 5990 | @subsection libgnunetpeerstore |
5929 | 5991 | ||
@@ -5932,49 +5994,57 @@ issue commands to the PEERSTORE service. | |||
5932 | libgnunetpeerstore is the library containing the PEERSTORE API. Subsystems | 5994 | libgnunetpeerstore is the library containing the PEERSTORE API. Subsystems |
5933 | wishing to communicate with the PEERSTORE service use this API to open a | 5995 | wishing to communicate with the PEERSTORE service use this API to open a |
5934 | connection to PEERSTORE. This is done by calling | 5996 | connection to PEERSTORE. This is done by calling |
5935 | @code{GNUNET_PEERSTORE_connect} which returns a handle to the newly created | 5997 | @code{GNUNET_PEERSTORE_connect} which returns a handle to the newly |
5936 | connection. This handle has to be used with any further calls to the API. | 5998 | created connection. |
5937 | 5999 | This handle has to be used with any further calls to the API. | |
5938 | To store a new record, the function @code{GNUNET_PEERSTORE_store} is to be used | 6000 | |
5939 | which requires the record fields and a continuation function that will be | 6001 | To store a new record, the function @code{GNUNET_PEERSTORE_store} is to |
5940 | called by the API after the STORE request is sent to the PEERSTORE service. | 6002 | be used which requires the record fields and a continuation function that |
5941 | Note that calling the continuation function does not mean that the record is | 6003 | will be called by the API after the STORE request is sent to the |
5942 | successfully stored, only that the STORE request has been successfully sent to | 6004 | PEERSTORE service. |
5943 | the PEERSTORE service. @code{GNUNET_PEERSTORE_store_cancel} can be called to | 6005 | Note that calling the continuation function does not mean that the record |
5944 | cancel the STORE request only before the continuation function has been called. | 6006 | is successfully stored, only that the STORE request has been successfully |
5945 | 6007 | sent to the PEERSTORE service. | |
5946 | To iterate over stored records, the function @code{GNUNET_PEERSTORE_iterate} is | 6008 | @code{GNUNET_PEERSTORE_store_cancel} can be called to cancel the STORE |
6009 | request only before the continuation function has been called. | ||
6010 | |||
6011 | To iterate over stored records, the function | ||
6012 | @code{GNUNET_PEERSTORE_iterate} is | ||
5947 | to be used. @emph{peerid} and @emph{key} can be set to NULL. An iterator | 6013 | to be used. @emph{peerid} and @emph{key} can be set to NULL. An iterator |
5948 | callback function will be called with each matching record found and a NULL | 6014 | callback function will be called with each matching record found and a |
5949 | record at the end to signal the end of result set. | 6015 | NULL record at the end to signal the end of result set. |
5950 | @code{GNUNET_PEERSTORE_iterate_cancel} can be used to cancel the ITERATE | 6016 | @code{GNUNET_PEERSTORE_iterate_cancel} can be used to cancel the ITERATE |
5951 | request before the iterator callback is called with a NULL record. | 6017 | request before the iterator callback is called with a NULL record. |
5952 | 6018 | ||
5953 | To be notified with new values stored under a (subsystem, peerid, key) | 6019 | To be notified with new values stored under a (subsystem, peerid, key) |
5954 | combination, the function @code{GNUNET_PEERSTORE_watch} is to be used. This | 6020 | combination, the function @code{GNUNET_PEERSTORE_watch} is to be used. |
5955 | will register the watcher with the PEERSTORE service, any new records matching | 6021 | This will register the watcher with the PEERSTORE service, any new |
5956 | the given combination will trigger the callback function passed to | 6022 | records matching the given combination will trigger the callback |
5957 | @code{GNUNET_PEERSTORE_watch}. This continues until | 6023 | function passed to @code{GNUNET_PEERSTORE_watch}. This continues until |
5958 | @code{GNUNET_PEERSTORE_watch_cancel} is called or the connection to the service | 6024 | @code{GNUNET_PEERSTORE_watch_cancel} is called or the connection to the |
5959 | is destroyed. | 6025 | service is destroyed. |
5960 | 6026 | ||
5961 | After the connection is no longer needed, the function | 6027 | After the connection is no longer needed, the function |
5962 | @code{GNUNET_PEERSTORE_disconnect} can be called to disconnect from the | 6028 | @code{GNUNET_PEERSTORE_disconnect} can be called to disconnect from the |
5963 | PEERSTORE service. Any pending ITERATE or WATCH requests will be destroyed. If | 6029 | PEERSTORE service. |
5964 | the @code{sync_first} flag is set to @code{GNUNET_YES}, the API will delay the | 6030 | Any pending ITERATE or WATCH requests will be destroyed. |
5965 | disconnection until all pending STORE requests are sent to the PEERSTORE | 6031 | If the @code{sync_first} flag is set to @code{GNUNET_YES}, the API will |
5966 | service, otherwise, the pending STORE requests will be destroyed as well. | 6032 | delay the disconnection until all pending STORE requests are sent to |
5967 | 6033 | the PEERSTORE service, otherwise, the pending STORE requests will be | |
6034 | destroyed as well. | ||
6035 | |||
6036 | @cindex SET Subsystem | ||
5968 | @node GNUnet's SET Subsystem | 6037 | @node GNUnet's SET Subsystem |
5969 | @section GNUnet's SET Subsystem | 6038 | @section GNUnet's SET Subsystem |
5970 | 6039 | ||
5971 | @c %**end of header | 6040 | @c %**end of header |
5972 | 6041 | ||
5973 | The SET service implements efficient set operations between two peers over a | 6042 | The SET service implements efficient set operations between two peers |
5974 | mesh tunnel. Currently, set union and set intersection are the only supported | 6043 | over a mesh tunnel. |
5975 | operations. Elements of a set consist of an @emph{element type} and arbitrary | 6044 | Currently, set union and set intersection are the only supported |
5976 | binary @emph{data}. The size of an element's data is limited to around 62 | 6045 | operations. Elements of a set consist of an @emph{element type} and |
5977 | KB. | 6046 | arbitrary binary @emph{data}. |
6047 | The size of an element's data is limited to around 62 KB. | ||
5978 | 6048 | ||
5979 | @menu | 6049 | @menu |
5980 | * Local Sets:: | 6050 | * Local Sets:: |
@@ -5995,62 +6065,67 @@ KB. | |||
5995 | Sets created by a local client can be modified and reused for multiple | 6065 | Sets created by a local client can be modified and reused for multiple |
5996 | operations. As each set operation requires potentially expensive special | 6066 | operations. As each set operation requires potentially expensive special |
5997 | auxilliary data to be computed for each element of a set, a set can only | 6067 | auxilliary data to be computed for each element of a set, a set can only |
5998 | participate in one type of set operation (i.e. union or intersection). The type | 6068 | participate in one type of set operation (i.e. union or intersection). |
5999 | of a set is determined upon its creation. If a the elements of a set are needed | 6069 | The type of a set is determined upon its creation. |
6000 | for an operation of a different type, all of the set's element must be copied | 6070 | If a the elements of a set are needed for an operation of a different |
6001 | to a new set of appropriate type. | 6071 | type, all of the set's element must be copied to a new set of appropriate |
6072 | type. | ||
6002 | 6073 | ||
6003 | @node Set Modifications | 6074 | @node Set Modifications |
6004 | @subsection Set Modifications | 6075 | @subsection Set Modifications |
6005 | 6076 | ||
6006 | @c %**end of header | 6077 | @c %**end of header |
6007 | 6078 | ||
6008 | Even when set operations are active, one can add to and remove elements from a | 6079 | Even when set operations are active, one can add to and remove elements |
6009 | set. However, these changes will only be visible to operations that have been | 6080 | from a set. |
6010 | created after the changes have taken place. That is, every set operation only | 6081 | However, these changes will only be visible to operations that have been |
6011 | sees a snapshot of the set from the time the operation was started. This | 6082 | created after the changes have taken place. That is, every set operation |
6012 | mechanism is @emph{not} implemented by copying the whole set, but by attaching | 6083 | only sees a snapshot of the set from the time the operation was started. |
6013 | @emph{generation information} to each element and operation. | 6084 | This mechanism is @emph{not} implemented by copying the whole set, but by |
6085 | attaching @emph{generation information} to each element and operation. | ||
6014 | 6086 | ||
6015 | @node Set Operations | 6087 | @node Set Operations |
6016 | @subsection Set Operations | 6088 | @subsection Set Operations |
6017 | 6089 | ||
6018 | @c %**end of header | 6090 | @c %**end of header |
6019 | 6091 | ||
6020 | Set operations can be started in two ways: Either by accepting an operation | 6092 | Set operations can be started in two ways: Either by accepting an |
6021 | request from a remote peer, or by requesting a set operation from a remote | 6093 | operation request from a remote peer, or by requesting a set operation |
6022 | peer. Set operations are uniquely identified by the involved @emph{peers}, an | 6094 | from a remote peer. |
6095 | Set operations are uniquely identified by the involved @emph{peers}, an | ||
6023 | @emph{application id} and the @emph{operation type}. | 6096 | @emph{application id} and the @emph{operation type}. |
6024 | 6097 | ||
6025 | The client is notified of incoming set operations by @emph{set listeners}. A | 6098 | The client is notified of incoming set operations by @emph{set listeners}. |
6026 | set listener listens for incoming operations of a specific operation type and | 6099 | A set listener listens for incoming operations of a specific operation |
6027 | application id. Once notified of an incoming set request, the client can | 6100 | type and application id. |
6028 | accept the set request (providing a local set for the operation) or reject | 6101 | Once notified of an incoming set request, the client can accept the set |
6029 | it. | 6102 | request (providing a local set for the operation) or reject it. |
6030 | 6103 | ||
6031 | @node Result Elements | 6104 | @node Result Elements |
6032 | @subsection Result Elements | 6105 | @subsection Result Elements |
6033 | 6106 | ||
6034 | @c %**end of header | 6107 | @c %**end of header |
6035 | 6108 | ||
6036 | The SET service has three @emph{result modes} that determine how an operation's | 6109 | The SET service has three @emph{result modes} that determine how an |
6037 | result set is delivered to the client: | 6110 | operation's result set is delivered to the client: |
6038 | 6111 | ||
6039 | @itemize @bullet | 6112 | @itemize @bullet |
6040 | @item @strong{Full Result Set.} All elements of set resulting from the set | 6113 | @item @strong{Full Result Set.} All elements of set resulting from the set |
6041 | operation are returned to the client. | 6114 | operation are returned to the client. |
6042 | @item @strong{Added Elements.} Only elements that result from the operation and | 6115 | @item @strong{Added Elements.} Only elements that result from the |
6043 | are not already in the local peer's set are returned. Note that for some | 6116 | operation and are not already in the local peer's set are returned. |
6044 | operations (like set intersection) this result mode will never return any | 6117 | Note that for some operations (like set intersection) this result mode |
6045 | elements. This can be useful if only the remove peer is actually interested in | 6118 | will never return any elements. |
6046 | the result of the set operation. | 6119 | This can be useful if only the remove peer is actually interested in |
6047 | @item @strong{Removed Elements.} Only elements that are in the local peer's | ||
6048 | initial set but not in the operation's result set are returned. Note that for | ||
6049 | some operations (like set union) this result mode will never return any | ||
6050 | elements. This can be useful if only the remove peer is actually interested in | ||
6051 | the result of the set operation. | 6120 | the result of the set operation. |
6121 | @item @strong{Removed Elements.} Only elements that are in the local | ||
6122 | peer's initial set but not in the operation's result set are returned. | ||
6123 | Note that for some operations (like set union) this result mode will | ||
6124 | never return any elements. This can be useful if only the remove peer is | ||
6125 | actually interested in the result of the set operation. | ||
6052 | @end itemize | 6126 | @end itemize |
6053 | 6127 | ||
6128 | @cindex libgnunetset | ||
6054 | @node libgnunetset | 6129 | @node libgnunetset |
6055 | @subsection libgnunetset | 6130 | @subsection libgnunetset |
6056 | 6131 | ||
@@ -6070,10 +6145,11 @@ the result of the set operation. | |||
6070 | @c %**end of header | 6145 | @c %**end of header |
6071 | 6146 | ||
6072 | New sets are created with @code{GNUNET_SET_create}. Both the local peer's | 6147 | New sets are created with @code{GNUNET_SET_create}. Both the local peer's |
6073 | configuration (as each set has its own client connection) and the operation | 6148 | configuration (as each set has its own client connection) and the |
6074 | type must be specified. The set exists until either the client calls | 6149 | operation type must be specified. |
6075 | @code{GNUNET_SET_destroy} or the client's connection to the service is | 6150 | The set exists until either the client calls @code{GNUNET_SET_destroy} or |
6076 | disrupted. In the latter case, the client is notified by the return value of | 6151 | the client's connection to the service is disrupted. |
6152 | In the latter case, the client is notified by the return value of | ||
6077 | functions dealing with sets. This return value must always be checked. | 6153 | functions dealing with sets. This return value must always be checked. |
6078 | 6154 | ||
6079 | Elements are added and removed with @code{GNUNET_SET_add_element} and | 6155 | Elements are added and removed with @code{GNUNET_SET_add_element} and |
@@ -6084,12 +6160,13 @@ Elements are added and removed with @code{GNUNET_SET_add_element} and | |||
6084 | 6160 | ||
6085 | @c %**end of header | 6161 | @c %**end of header |
6086 | 6162 | ||
6087 | Listeners are created with @code{GNUNET_SET_listen}. Each time time a remote | 6163 | Listeners are created with @code{GNUNET_SET_listen}. Each time time a |
6088 | peer suggests a set operation with an application id and operation type | 6164 | remote peer suggests a set operation with an application id and operation |
6089 | matching a listener, the listener's callack is invoked. The client then must | 6165 | type matching a listener, the listener's callback is invoked. |
6090 | synchronously call either @code{GNUNET_SET_accept} or @code{GNUNET_SET_reject}. | 6166 | The client then must synchronously call either @code{GNUNET_SET_accept} |
6091 | Note that the operation will not be started until the client calls | 6167 | or @code{GNUNET_SET_reject}. Note that the operation will not be started |
6092 | @code{GNUNET_SET_commit} (see Section "Supplying a Set"). | 6168 | until the client calls @code{GNUNET_SET_commit} |
6169 | (see Section "Supplying a Set"). | ||
6093 | 6170 | ||
6094 | @node Operations | 6171 | @node Operations |
6095 | @subsubsection Operations | 6172 | @subsubsection Operations |
@@ -6097,22 +6174,22 @@ Note that the operation will not be started until the client calls | |||
6097 | @c %**end of header | 6174 | @c %**end of header |
6098 | 6175 | ||
6099 | Operations to be initiated by the local peer are created with | 6176 | Operations to be initiated by the local peer are created with |
6100 | @code{GNUNET_SET_prepare}. Note that the operation will not be started until | 6177 | @code{GNUNET_SET_prepare}. Note that the operation will not be started |
6101 | the client calls @code{GNUNET_SET_commit} (see Section "Supplying a | 6178 | until the client calls @code{GNUNET_SET_commit} |
6102 | Set"). | 6179 | (see Section "Supplying a Set"). |
6103 | 6180 | ||
6104 | @node Supplying a Set | 6181 | @node Supplying a Set |
6105 | @subsubsection Supplying a Set | 6182 | @subsubsection Supplying a Set |
6106 | 6183 | ||
6107 | @c %**end of header | 6184 | @c %**end of header |
6108 | 6185 | ||
6109 | To create symmetry between the two ways of starting a set operation (accepting | 6186 | To create symmetry between the two ways of starting a set operation |
6110 | and nitiating it), the operation handles returned by @code{GNUNET_SET_accept} | 6187 | (accepting and nitiating it), the operation handles returned by |
6111 | and @code{GNUNET_SET_prepare} do not yet have a set to operate on, thus they | 6188 | @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare} do not yet have a |
6112 | can not do any work yet. | 6189 | set to operate on, thus they can not do any work yet. |
6113 | 6190 | ||
6114 | The client must call @code{GNUNET_SET_commit} to specify a set to use for an | 6191 | The client must call @code{GNUNET_SET_commit} to specify a set to use for |
6115 | operation. @code{GNUNET_SET_commit} may only be called once per set | 6192 | an operation. @code{GNUNET_SET_commit} may only be called once per set |
6116 | operation. | 6193 | operation. |
6117 | 6194 | ||
6118 | @node The Result Callback | 6195 | @node The Result Callback |
@@ -6121,12 +6198,13 @@ operation. | |||
6121 | @c %**end of header | 6198 | @c %**end of header |
6122 | 6199 | ||
6123 | Clients must specify both a result mode and a result callback with | 6200 | Clients must specify both a result mode and a result callback with |
6124 | @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare}. The result callback | 6201 | @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare}. The result |
6125 | with a status indicating either that an element was received, or the operation | 6202 | callback with a status indicating either that an element was received, or |
6126 | failed or succeeded. The interpretation of the received element depends on the | 6203 | the operation failed or succeeded. |
6127 | result mode. The callback needs to know which result mode it is used in, as the | 6204 | The interpretation of the received element depends on the result mode. |
6128 | arguments do not indicate if an element is part of the full result set, or if | 6205 | The callback needs to know which result mode it is used in, as the |
6129 | it is in the difference between the original set and the final set. | 6206 | arguments do not indicate if an element is part of the full result set, |
6207 | or if it is in the difference between the original set and the final set. | ||
6130 | 6208 | ||
6131 | @node The SET Client-Service Protocol | 6209 | @node The SET Client-Service Protocol |
6132 | @subsection The SET Client-Service Protocol | 6210 | @subsection The SET Client-Service Protocol |
@@ -6147,10 +6225,11 @@ it is in the difference between the original set and the final set. | |||
6147 | 6225 | ||
6148 | @c %**end of header | 6226 | @c %**end of header |
6149 | 6227 | ||
6150 | For each set of a client, there exists a client connection to the service. Sets | 6228 | For each set of a client, there exists a client connection to the service. |
6151 | are created by sending the @code{GNUNET_SERVICE_SET_CREATE} message over a new | 6229 | Sets are created by sending the @code{GNUNET_SERVICE_SET_CREATE} message |
6152 | client connection. Multiple operations for one set are multiplexed over one | 6230 | over a new client connection. Multiple operations for one set are |
6153 | client connection, using a request id supplied by the client. | 6231 | multiplexed over one client connection, using a request id supplied by |
6232 | the client. | ||
6154 | 6233 | ||
6155 | @node Listeners2 | 6234 | @node Listeners2 |
6156 | @subsubsection Listeners2 | 6235 | @subsubsection Listeners2 |
@@ -6158,12 +6237,13 @@ client connection, using a request id supplied by the client. | |||
6158 | @c %**end of header | 6237 | @c %**end of header |
6159 | 6238 | ||
6160 | Each listener also requires a seperate client connection. By sending the | 6239 | Each listener also requires a seperate client connection. By sending the |
6161 | @code{GNUNET_SERVICE_SET_LISTEN} message, the client notifies the service of | 6240 | @code{GNUNET_SERVICE_SET_LISTEN} message, the client notifies the service |
6162 | the application id and operation type it is interested in. A client rejects an | 6241 | of the application id and operation type it is interested in. A client |
6163 | incoming request by sending @code{GNUNET_SERVICE_SET_REJECT} on the listener's | 6242 | rejects an incoming request by sending @code{GNUNET_SERVICE_SET_REJECT} |
6164 | client connection. In contrast, when accepting an incoming request, a a | 6243 | on the listener's client connection. |
6165 | @code{GNUNET_SERVICE_SET_ACCEPT} message must be sent over the@ set that is | 6244 | In contrast, when accepting an incoming request, a |
6166 | supplied for the set operation. | 6245 | @code{GNUNET_SERVICE_SET_ACCEPT} message must be sent over the@ set that |
6246 | is supplied for the set operation. | ||
6167 | 6247 | ||
6168 | @node Initiating Operations | 6248 | @node Initiating Operations |
6169 | @subsubsection Initiating Operations | 6249 | @subsubsection Initiating Operations |
@@ -6192,8 +6272,8 @@ Sets are modified with the @code{GNUNET_SERVICE_SET_ADD} and | |||
6192 | @subsubsection Results and Operation Status | 6272 | @subsubsection Results and Operation Status |
6193 | @c %**end of header | 6273 | @c %**end of header |
6194 | 6274 | ||
6195 | The service notifies the client of result elements and success/failure of a set | 6275 | The service notifies the client of result elements and success/failure of |
6196 | operation with the @code{GNUNET_SERVICE_SET_RESULT} message. | 6276 | a set operation with the @code{GNUNET_SERVICE_SET_RESULT} message. |
6197 | 6277 | ||
6198 | @node Iterating Sets | 6278 | @node Iterating Sets |
6199 | @subsubsection Iterating Sets | 6279 | @subsubsection Iterating Sets |
@@ -6202,9 +6282,10 @@ operation with the @code{GNUNET_SERVICE_SET_RESULT} message. | |||
6202 | 6282 | ||
6203 | All elements of a set can be requested by sending | 6283 | All elements of a set can be requested by sending |
6204 | @code{GNUNET_SERVICE_SET_ITER_REQUEST}. The server responds with | 6284 | @code{GNUNET_SERVICE_SET_ITER_REQUEST}. The server responds with |
6205 | @code{GNUNET_SERVICE_SET_ITER_ELEMENT} and eventually terminates the iteration | 6285 | @code{GNUNET_SERVICE_SET_ITER_ELEMENT} and eventually terminates the |
6206 | with @code{GNUNET_SERVICE_SET_ITER_DONE}. After each received element, the | 6286 | iteration with @code{GNUNET_SERVICE_SET_ITER_DONE}. |
6207 | client@ must send @code{GNUNET_SERVICE_SET_ITER_ACK}. Note that only one set | 6287 | After each received element, the client |
6288 | must send @code{GNUNET_SERVICE_SET_ITER_ACK}. Note that only one set | ||
6208 | iteration may be active for a set at any given time. | 6289 | iteration may be active for a set at any given time. |
6209 | 6290 | ||
6210 | @node The SET Intersection Peer-to-Peer Protocol | 6291 | @node The SET Intersection Peer-to-Peer Protocol |
@@ -6213,24 +6294,25 @@ iteration may be active for a set at any given time. | |||
6213 | @c %**end of header | 6294 | @c %**end of header |
6214 | 6295 | ||
6215 | The intersection protocol operates over CADET and starts with a | 6296 | The intersection protocol operates over CADET and starts with a |
6216 | GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer initiating | 6297 | GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer |
6217 | the operation to the peer listening for inbound requests. It includes the | 6298 | initiating the operation to the peer listening for inbound requests. |
6218 | number of elements of the initiating peer, which is used to decide which side | 6299 | It includes the number of elements of the initiating peer, which is used |
6219 | will send a Bloom filter first. | 6300 | to decide which side will send a Bloom filter first. |
6220 | 6301 | ||
6221 | The listening peer checks if the operation type and application identifier are | 6302 | The listening peer checks if the operation type and application |
6222 | acceptable for its current state. If not, it responds with a | 6303 | identifier are acceptable for its current state. |
6223 | GNUNET_MESSAGE_TYPE_SET_RESULT and a status of GNUNET_SET_STATUS_FAILURE (and | 6304 | If not, it responds with a GNUNET_MESSAGE_TYPE_SET_RESULT and a status of |
6224 | terminates the CADET channel). | 6305 | GNUNET_SET_STATUS_FAILURE (and terminates the CADET channel). |
6225 | 6306 | ||
6226 | If the application accepts the request, the listener sends back a@ | 6307 | If the application accepts the request, the listener sends back a |
6227 | GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_ELEMENT_INFO if it has more elements | 6308 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_ELEMENT_INFO} if it has |
6228 | in the set than the client. Otherwise, it immediately starts with the Bloom | 6309 | more elements in the set than the client. |
6229 | filter exchange. If the initiator receives a | 6310 | Otherwise, it immediately starts with the Bloom filter exchange. |
6230 | GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_ELEMENT_INFO response, it beings the | 6311 | If the initiator receives a |
6231 | Bloom filter exchange, unless the set size is indicated to be zero, in which | 6312 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_ELEMENT_INFO} response, |
6232 | case the intersection is considered finished after just the initial | 6313 | it beings the Bloom filter exchange, unless the set size is indicated to |
6233 | handshake. | 6314 | be zero, in which case the intersection is considered finished after |
6315 | just the initial handshake. | ||
6234 | 6316 | ||
6235 | 6317 | ||
6236 | @menu | 6318 | @menu |
@@ -6243,42 +6325,47 @@ handshake. | |||
6243 | 6325 | ||
6244 | @c %**end of header | 6326 | @c %**end of header |
6245 | 6327 | ||
6246 | In this phase, each peer transmits a Bloom filter over the remaining keys of | 6328 | In this phase, each peer transmits a Bloom filter over the remaining |
6247 | the local set to the other peer using a | 6329 | keys of the local set to the other peer using a |
6248 | GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_BF message. This message additionally | 6330 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_BF} message. This |
6249 | includes the number of elements left in the sender's set, as well as the XOR | 6331 | message additionally includes the number of elements left in the sender's |
6250 | over all of the keys in that set. | 6332 | set, as well as the XOR over all of the keys in that set. |
6251 | 6333 | ||
6252 | The number of bits 'k' set per element in the Bloom filter is calculated based | 6334 | The number of bits 'k' set per element in the Bloom filter is calculated |
6253 | on the relative size of the two sets. Furthermore, the size of the Bloom filter | 6335 | based on the relative size of the two sets. |
6254 | is calculated based on 'k' and the number of elements in the set to maximize | 6336 | Furthermore, the size of the Bloom filter is calculated based on 'k' and |
6255 | the amount of data filtered per byte transmitted on the wire (while avoiding an | 6337 | the number of elements in the set to maximize the amount of data filtered |
6256 | excessively high number of iterations). | 6338 | per byte transmitted on the wire (while avoiding an excessively high |
6339 | number of iterations). | ||
6257 | 6340 | ||
6258 | The receiver of the message removes all elements from its local set that do not | 6341 | The receiver of the message removes all elements from its local set that |
6259 | pass the Bloom filter test. It then checks if the set size of the sender and | 6342 | do not pass the Bloom filter test. |
6260 | the XOR over the keys match what is left of his own set. If they do, he sends | 6343 | It then checks if the set size of the sender and the XOR over the keys |
6261 | a@ GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_DONE back to indicate that the | 6344 | match what is left of his own set. If they do, he sends a |
6262 | latest set is the final result. Otherwise, the receiver starts another Bloom | 6345 | @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_DONE} back to indicate |
6263 | fitler exchange, except this time as the sender. | 6346 | that the latest set is the final result. |
6347 | Otherwise, the receiver starts another Bloom fitler exchange, except | ||
6348 | this time as the sender. | ||
6264 | 6349 | ||
6265 | @node Salt | 6350 | @node Salt |
6266 | @subsubsection Salt | 6351 | @subsubsection Salt |
6267 | 6352 | ||
6268 | @c %**end of header | 6353 | @c %**end of header |
6269 | 6354 | ||
6270 | Bloomfilter operations are probablistic: With some non-zero probability the | 6355 | Bloomfilter operations are probablistic: With some non-zero probability |
6271 | test may incorrectly say an element is in the set, even though it is not. | 6356 | the test may incorrectly say an element is in the set, even though it is |
6357 | not. | ||
6272 | 6358 | ||
6273 | To mitigate this problem, the intersection protocol iterates exchanging Bloom | 6359 | To mitigate this problem, the intersection protocol iterates exchanging |
6274 | filters using a different random 32-bit salt in each iteration (the salt is | 6360 | Bloom filters using a different random 32-bit salt in each iteration (the |
6275 | also included in the message). With different salts, set operations may fail | 6361 | salt is also included in the message). |
6276 | for different elements. Merging the results from the executions, the | 6362 | With different salts, set operations may fail for different elements. |
6277 | probability of failure drops to zero. | 6363 | Merging the results from the executions, the probability of failure drops |
6364 | to zero. | ||
6278 | 6365 | ||
6279 | The iterations terminate once both peers have established that they have sets | 6366 | The iterations terminate once both peers have established that they have |
6280 | of the same size, and where the XOR over all keys computes the same 512-bit | 6367 | sets of the same size, and where the XOR over all keys computes the same |
6281 | value (leaving a failure probability of 2-511). | 6368 | 512-bit value (leaving a failure probability of 2-511). |
6282 | 6369 | ||
6283 | @node The SET Union Peer-to-Peer Protocol | 6370 | @node The SET Union Peer-to-Peer Protocol |
6284 | @subsection The SET Union Peer-to-Peer Protocol | 6371 | @subsection The SET Union Peer-to-Peer Protocol |
@@ -6290,105 +6377,114 @@ without prior context. You should read this paper first if you want to | |||
6290 | understand the protocol. | 6377 | understand the protocol. |
6291 | 6378 | ||
6292 | The union protocol operates over CADET and starts with a | 6379 | The union protocol operates over CADET and starts with a |
6293 | GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer initiating | 6380 | GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer |
6294 | the operation to the peer listening for inbound requests. It includes the | 6381 | initiating the operation to the peer listening for inbound requests. |
6295 | number of elements of the initiating peer, which is currently not used. | 6382 | It includes the number of elements of the initiating peer, which is |
6383 | currently not used. | ||
6296 | 6384 | ||
6297 | The listening peer checks if the operation type and application identifier are | 6385 | The listening peer checks if the operation type and application |
6298 | acceptable for its current state. If not, it responds with a | 6386 | identifier are acceptable for its current state. If not, it responds with |
6299 | GNUNET_MESSAGE_TYPE_SET_RESULT and a status of GNUNET_SET_STATUS_FAILURE (and | 6387 | a @code{GNUNET_MESSAGE_TYPE_SET_RESULT} and a status of |
6300 | terminates the CADET channel). | 6388 | @code{GNUNET_SET_STATUS_FAILURE} (and terminates the CADET channel). |
6301 | 6389 | ||
6302 | If the application accepts the request, it sends back a strata estimator using | 6390 | If the application accepts the request, it sends back a strata estimator |
6303 | a message of type GNUNET_MESSAGE_TYPE_SET_UNION_P2P_SE. The initiator evaluates | 6391 | using a message of type GNUNET_MESSAGE_TYPE_SET_UNION_P2P_SE. The |
6304 | the strata estimator and initiates the exchange of invertible Bloom filters, | 6392 | initiator evaluates the strata estimator and initiates the exchange of |
6305 | sending a GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF. | 6393 | invertible Bloom filters, sending a GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF. |
6306 | 6394 | ||
6307 | During the IBF exchange, if the receiver cannot invert the Bloom filter or | 6395 | During the IBF exchange, if the receiver cannot invert the Bloom filter or |
6308 | detects a cycle, it sends a larger IBF in response (up to a defined maximum | 6396 | detects a cycle, it sends a larger IBF in response (up to a defined |
6309 | limit; if that limit is reached, the operation fails). Elements decoded while | 6397 | maximum limit; if that limit is reached, the operation fails). |
6310 | processing the IBF are transmitted to the other peer using | 6398 | Elements decoded while processing the IBF are transmitted to the other |
6311 | GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENTS, or requested from the other peer using | 6399 | peer using GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENTS, or requested from the |
6312 | GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENT_REQUESTS messages, depending on the sign | 6400 | other peer using GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENT_REQUESTS messages, |
6313 | observed during decoding of the IBF. Peers respond to a | 6401 | depending on the sign observed during decoding of the IBF. |
6314 | GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENT_REQUESTS message with the respective | 6402 | Peers respond to a GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENT_REQUESTS message |
6315 | element in a GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENTS message. If the IBF fully | 6403 | with the respective element in a GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENTS |
6316 | decodes, the peer responds with a GNUNET_MESSAGE_TYPE_SET_UNION_P2P_DONE | 6404 | message. If the IBF fully decodes, the peer responds with a |
6317 | message instead of another GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF. | 6405 | GNUNET_MESSAGE_TYPE_SET_UNION_P2P_DONE message instead of another |
6318 | 6406 | GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF. | |
6319 | All Bloom filter operations use a salt to mingle keys before hasing them into | 6407 | |
6320 | buckets, such that future iterations have a fresh chance of succeeding if they | 6408 | All Bloom filter operations use a salt to mingle keys before hasing them |
6321 | failed due to collisions before. | 6409 | into buckets, such that future iterations have a fresh chance of |
6322 | 6410 | succeeding if they failed due to collisions before. | |
6411 | |||
6412 | @cindex STATISTICS subsystem | ||
6323 | @node GNUnet's STATISTICS subsystem | 6413 | @node GNUnet's STATISTICS subsystem |
6324 | @section GNUnet's STATISTICS subsystem | 6414 | @section GNUnet's STATISTICS subsystem |
6325 | 6415 | ||
6326 | @c %**end of header | 6416 | @c %**end of header |
6327 | 6417 | ||
6328 | In GNUnet, the STATISTICS subsystem offers a central place for all subsystems | 6418 | In GNUnet, the STATISTICS subsystem offers a central place for all |
6329 | to publish unsigned 64-bit integer run-time statistics. Keeping this | 6419 | subsystems to publish unsigned 64-bit integer run-time statistics. |
6330 | information centrally means that there is a unified way for the user to obtain | 6420 | Keeping this information centrally means that there is a unified way for |
6331 | data on all subsystems, and individual subsystems do not have to always include | 6421 | the user to obtain data on all subsystems, and individual subsystems do |
6332 | a custom data export method for performance metrics and other statistics. For | 6422 | not have to always include a custom data export method for performance |
6333 | example, the TRANSPORT system uses STATISTICS to update information about the | 6423 | metrics and other statistics. For example, the TRANSPORT system uses |
6334 | number of directly connected peers and the bandwidth that has been consumed by | 6424 | STATISTICS to update information about the number of directly connected |
6335 | the various plugins. This information is valuable for diagnosing connectivity | 6425 | peers and the bandwidth that has been consumed by the various plugins. |
6336 | and performance issues. | 6426 | This information is valuable for diagnosing connectivity and performance |
6427 | issues. | ||
6337 | 6428 | ||
6338 | Following the GNUnet service architecture, the STATISTICS subsystem is divided | 6429 | Following the GNUnet service architecture, the STATISTICS subsystem is |
6339 | into an API which is exposed through the header | 6430 | divided into an API which is exposed through the header |
6340 | @strong{gnunet_statistics_service.h} and the STATISTICS service | 6431 | @strong{gnunet_statistics_service.h} and the STATISTICS service |
6341 | @strong{gnunet-service-statistics}. The @strong{gnunet-statistics} command-line | 6432 | @strong{gnunet-service-statistics}. The @strong{gnunet-statistics} |
6342 | tool can be used to obtain (and change) information about the values stored by | 6433 | command-line tool can be used to obtain (and change) information about |
6343 | the STATISTICS service. The STATISTICS service does not communicate with other | 6434 | the values stored by the STATISTICS service. The STATISTICS service does |
6344 | peers. | 6435 | not communicate with other peers. |
6345 | 6436 | ||
6346 | Data is stored in the STATISTICS service in the form of tuples | 6437 | Data is stored in the STATISTICS service in the form of tuples |
6347 | @strong{(subsystem, name, value, persistence)}. The subsystem determines to | 6438 | @strong{(subsystem, name, value, persistence)}. The subsystem determines |
6348 | which other GNUnet's subsystem the data belongs. name is the name through which | 6439 | to which other GNUnet's subsystem the data belongs. name is the name |
6349 | value is associated. It uniquely identifies the record from among other records | 6440 | through which value is associated. It uniquely identifies the record |
6350 | belonging to the same subsystem. In some parts of the code, the pair | 6441 | from among other records belonging to the same subsystem. |
6351 | @strong{(subsystem, name)} is called a @strong{statistic} as it identifies the | 6442 | In some parts of the code, the pair @strong{(subsystem, name)} is called |
6352 | values stored in the STATISTCS service.The persistence flag determines if the | 6443 | a @strong{statistic} as it identifies the values stored in the STATISTCS |
6353 | record has to be preserved across service restarts. A record is said to be | 6444 | service.The persistence flag determines if the record has to be preserved |
6354 | persistent if this flag is set for it; if not, the record is treated as a | 6445 | across service restarts. A record is said to be persistent if this flag |
6355 | non-persistent record and it is lost after service restart. Persistent records | 6446 | is set for it; if not, the record is treated as a non-persistent record |
6356 | are written to and read from the file @strong{statistics.data} before shutdown | 6447 | and it is lost after service restart. Persistent records are written to |
6448 | and read from the file @strong{statistics.data} before shutdown | ||
6357 | and upon startup. The file is located in the HOME directory of the peer. | 6449 | and upon startup. The file is located in the HOME directory of the peer. |
6358 | 6450 | ||
6359 | An anomaly of the STATISTICS service is that it does not terminate immediately | 6451 | An anomaly of the STATISTICS service is that it does not terminate |
6360 | upon receiving a shutdown signal if it has any clients connected to it. It | 6452 | immediately upon receiving a shutdown signal if it has any clients |
6361 | waits for all the clients that are not monitors to close their connections | 6453 | connected to it. It waits for all the clients that are not monitors to |
6362 | before terminating itself. This is to prevent the loss of data during peer | 6454 | close their connections before terminating itself. |
6363 | shutdown --- delaying the STATISTICS service shutdown helps other services to | 6455 | This is to prevent the loss of data during peer shutdown --- delaying the |
6364 | store important data to STATISTICS during shutdown. | 6456 | STATISTICS service shutdown helps other services to store important data |
6457 | to STATISTICS during shutdown. | ||
6365 | 6458 | ||
6366 | @menu | 6459 | @menu |
6367 | * libgnunetstatistics:: | 6460 | * libgnunetstatistics:: |
6368 | * The STATISTICS Client-Service Protocol:: | 6461 | * The STATISTICS Client-Service Protocol:: |
6369 | @end menu | 6462 | @end menu |
6370 | 6463 | ||
6464 | @cindex libgnunetstatistics | ||
6371 | @node libgnunetstatistics | 6465 | @node libgnunetstatistics |
6372 | @subsection libgnunetstatistics | 6466 | @subsection libgnunetstatistics |
6373 | 6467 | ||
6374 | @c %**end of header | 6468 | @c %**end of header |
6375 | 6469 | ||
6376 | @strong{libgnunetstatistics} is the library containing the API for the | 6470 | @strong{libgnunetstatistics} is the library containing the API for the |
6377 | STATISTICS subsystem. Any process requiring to use STATISTICS should use this | 6471 | STATISTICS subsystem. Any process requiring to use STATISTICS should use |
6378 | API by to open a connection to the STATISTICS service. This is done by calling | 6472 | this API by to open a connection to the STATISTICS service. |
6379 | the function @code{GNUNET_STATISTICS_create()}. This function takes the | 6473 | This is done by calling the function @code{GNUNET_STATISTICS_create()}. |
6380 | subsystem's name which is trying to use STATISTICS and a configuration. All | 6474 | This function takes the subsystem's name which is trying to use STATISTICS |
6381 | values written to STATISTICS with this connection will be placed in the section | 6475 | and a configuration. |
6382 | corresponding to the given subsystem's name. The connection to STATISTICS can | 6476 | All values written to STATISTICS with this connection will be placed in |
6383 | be destroyed with the function GNUNET_STATISTICS_destroy(). This function | 6477 | the section corresponding to the given subsystem's name. |
6384 | allows for the connection to be destroyed immediately or upon transferring all | 6478 | The connection to STATISTICS can be destroyed with the function |
6479 | @code{GNUNET_STATISTICS_destroy()}. This function allows for the | ||
6480 | connection to be destroyed immediately or upon transferring all | ||
6385 | pending write requests to the service. | 6481 | pending write requests to the service. |
6386 | 6482 | ||
6387 | Note: STATISTICS subsystem can be disabled by setting @code{DISABLE = YES} | 6483 | Note: STATISTICS subsystem can be disabled by setting @code{DISABLE = YES} |
6388 | under the @code{[STATISTICS]} section in the configuration. With such a | 6484 | under the @code{[STATISTICS]} section in the configuration. With such a |
6389 | configuration all calls to @code{GNUNET_STATISTICS_create()} return @code{NULL} | 6485 | configuration all calls to @code{GNUNET_STATISTICS_create()} return |
6390 | as the STATISTICS subsystem is unavailable and no other functions from the API | 6486 | @code{NULL} as the STATISTICS subsystem is unavailable and no other |
6391 | can be used. | 6487 | functions from the API can be used. |
6392 | 6488 | ||
6393 | 6489 | ||
6394 | @menu | 6490 | @menu |
@@ -6402,66 +6498,74 @@ can be used. | |||
6402 | 6498 | ||
6403 | @c %**end of header | 6499 | @c %**end of header |
6404 | 6500 | ||
6405 | Once a connection to the statistics service is obtained, information about any | 6501 | Once a connection to the statistics service is obtained, information |
6406 | other system which uses statistics can be retrieved with the function | 6502 | about any other system which uses statistics can be retrieved with the |
6407 | GNUNET_STATISTICS_get(). This function takes the connection handle, the name of | 6503 | function GNUNET_STATISTICS_get(). |
6408 | the subsystem whose information we are interested in (a @code{NULL} value will | 6504 | This function takes the connection handle, the name of the subsystem |
6409 | retrieve information of all available subsystems using STATISTICS), the name of | 6505 | whose information we are interested in (a @code{NULL} value will |
6410 | the statistic we are interested in (a @code{NULL} value will retrieve all | 6506 | retrieve information of all available subsystems using STATISTICS), the |
6411 | available statistics), a continuation callback which is called when all of | 6507 | name of the statistic we are interested in (a @code{NULL} value will |
6412 | requested information is retrieved, an iterator callback which is called for | 6508 | retrieve all available statistics), a continuation callback which is |
6413 | each parameter in the retrieved information and a closure for the | 6509 | called when all of requested information is retrieved, an iterator |
6414 | aforementioned callbacks. The library then invokes the iterator callback for | 6510 | callback which is called for each parameter in the retrieved information |
6415 | each value matching the request. | 6511 | and a closure for the aforementioned callbacks. The library then invokes |
6512 | the iterator callback for each value matching the request. | ||
6416 | 6513 | ||
6417 | Call to @code{GNUNET_STATISTICS_get()} is asynchronous and can be canceled with | 6514 | Call to @code{GNUNET_STATISTICS_get()} is asynchronous and can be |
6418 | the function @code{GNUNET_STATISTICS_get_cancel()}. This is helpful when | 6515 | canceled with the function @code{GNUNET_STATISTICS_get_cancel()}. |
6419 | retrieving statistics takes too long and especially when we want to shutdown | 6516 | This is helpful when retrieving statistics takes too long and especially |
6420 | and cleanup everything. | 6517 | when we want to shutdown and cleanup everything. |
6421 | 6518 | ||
6422 | @node Setting statistics and updating them | 6519 | @node Setting statistics and updating them |
6423 | @subsubsection Setting statistics and updating them | 6520 | @subsubsection Setting statistics and updating them |
6424 | 6521 | ||
6425 | @c %**end of header | 6522 | @c %**end of header |
6426 | 6523 | ||
6427 | So far we have seen how to retrieve statistics, here we will learn how we can | 6524 | So far we have seen how to retrieve statistics, here we will learn how we |
6428 | set statistics and update them so that other subsystems can retrieve them. | 6525 | can set statistics and update them so that other subsystems can retrieve |
6526 | them. | ||
6429 | 6527 | ||
6430 | A new statistic can be set using the function @code{GNUNET_STATISTICS_set()}. | 6528 | A new statistic can be set using the function |
6431 | This function takes the name of the statistic and its value and a flag to make | 6529 | @code{GNUNET_STATISTICS_set()}. |
6432 | the statistic persistent. The value of the statistic should be of the type | 6530 | This function takes the name of the statistic and its value and a flag to |
6433 | @code{uint64_t}. The function does not take the name of the subsystem; it is | 6531 | make the statistic persistent. |
6434 | determined from the previous @code{GNUNET_STATISTICS_create()} invocation. If | 6532 | The value of the statistic should be of the type @code{uint64_t}. |
6533 | The function does not take the name of the subsystem; it is determined | ||
6534 | from the previous @code{GNUNET_STATISTICS_create()} invocation. If | ||
6435 | the given statistic is already present, its value is overwritten. | 6535 | the given statistic is already present, its value is overwritten. |
6436 | 6536 | ||
6437 | An existing statistics can be updated, i.e its value can be increased or | 6537 | An existing statistics can be updated, i.e its value can be increased or |
6438 | decreased by an amount with the function @code{GNUNET_STATISTICS_update()}. The | 6538 | decreased by an amount with the function |
6439 | parameters to this function are similar to @code{GNUNET_STATISTICS_set()}, | 6539 | @code{GNUNET_STATISTICS_update()}. |
6440 | except that it takes the amount to be changed as a type @code{int64_t} instead | 6540 | The parameters to this function are similar to |
6441 | of the value. | 6541 | @code{GNUNET_STATISTICS_set()}, except that it takes the amount to be |
6542 | changed as a type @code{int64_t} instead of the value. | ||
6442 | 6543 | ||
6443 | The library will combine multiple set or update operations into one message if | 6544 | The library will combine multiple set or update operations into one |
6444 | the client performs requests at a rate that is faster than the available IPC | 6545 | message if the client performs requests at a rate that is faster than the |
6445 | with the STATISTICS service. Thus, the client does not have to worry about | 6546 | available IPC with the STATISTICS service. Thus, the client does not have |
6446 | sending requests too quickly. | 6547 | to worry about sending requests too quickly. |
6447 | 6548 | ||
6448 | @node Watches | 6549 | @node Watches |
6449 | @subsubsection Watches | 6550 | @subsubsection Watches |
6450 | 6551 | ||
6451 | @c %**end of header | 6552 | @c %**end of header |
6452 | 6553 | ||
6453 | As interesting feature of STATISTICS lies in serving notifications whenever a | 6554 | As interesting feature of STATISTICS lies in serving notifications |
6454 | statistic of our interest is modified. This is achieved by registering a watch | 6555 | whenever a statistic of our interest is modified. |
6455 | through the function @code{GNUNET_STATISTICS_watch()}. The parameters of this | 6556 | This is achieved by registering a watch through the function |
6456 | function are similar to those of @code{GNUNET_STATISTICS_get()}. Changes to the | ||
6457 | respective statistic's value will then cause the given iterator callback to be | ||
6458 | called. Note: A watch can only be registered for a specific statistic. Hence | ||
6459 | the subsystem name and the parameter name cannot be @code{NULL} in a call to | ||
6460 | @code{GNUNET_STATISTICS_watch()}. | 6557 | @code{GNUNET_STATISTICS_watch()}. |
6558 | The parameters of this function are similar to those of | ||
6559 | @code{GNUNET_STATISTICS_get()}. | ||
6560 | Changes to the respective statistic's value will then cause the given | ||
6561 | iterator callback to be called. | ||
6562 | Note: A watch can only be registered for a specific statistic. Hence | ||
6563 | the subsystem name and the parameter name cannot be @code{NULL} in a | ||
6564 | call to @code{GNUNET_STATISTICS_watch()}. | ||
6461 | 6565 | ||
6462 | A registered watch will keep notifying any value changes until | 6566 | A registered watch will keep notifying any value changes until |
6463 | @code{GNUNET_STATISTICS_watch_cancel()} is called with the same parameters that | 6567 | @code{GNUNET_STATISTICS_watch_cancel()} is called with the same |
6464 | are used for registering the watch. | 6568 | parameters that are used for registering the watch. |
6465 | 6569 | ||
6466 | @node The STATISTICS Client-Service Protocol | 6570 | @node The STATISTICS Client-Service Protocol |
6467 | @subsection The STATISTICS Client-Service Protocol | 6571 | @subsection The STATISTICS Client-Service Protocol |
@@ -6480,12 +6584,13 @@ are used for registering the watch. | |||
6480 | @c %**end of header | 6584 | @c %**end of header |
6481 | 6585 | ||
6482 | To retrieve statistics, the client transmits a message of type | 6586 | To retrieve statistics, the client transmits a message of type |
6483 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_GET} containing the given subsystem name | 6587 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_GET} containing the given subsystem |
6484 | and statistic parameter to the STATISTICS service. The service responds with a | 6588 | name and statistic parameter to the STATISTICS service. |
6485 | message of type @code{GNUNET_MESSAGE_TYPE_STATISTICS_VALUE} for each of the | 6589 | The service responds with a message of type |
6486 | statistics parameters that match the client request for the client. The end of | 6590 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_VALUE} for each of the statistics |
6487 | information retrieved is signaled by the service by sending a message of type | 6591 | parameters that match the client request for the client. The end of |
6488 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_END}. | 6592 | information retrieved is signaled by the service by sending a message of |
6593 | type @code{GNUNET_MESSAGE_TYPE_STATISTICS_END}. | ||
6489 | 6594 | ||
6490 | @node Setting and updating statistics | 6595 | @node Setting and updating statistics |
6491 | @subsubsection Setting and updating statistics | 6596 | @subsubsection Setting and updating statistics |
@@ -6497,64 +6602,70 @@ communicated to the service through the message | |||
6497 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET}. | 6602 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET}. |
6498 | 6603 | ||
6499 | When the service receives a message of type | 6604 | When the service receives a message of type |
6500 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET}, it retrieves the subsystem name and | 6605 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET}, it retrieves the subsystem |
6501 | checks for a statistic parameter with matching the name given in the message. | 6606 | name and checks for a statistic parameter with matching the name given in |
6502 | If a statistic parameter is found, the value is overwritten by the new value | 6607 | the message. |
6503 | from the message; if not found then a new statistic parameter is created with | 6608 | If a statistic parameter is found, the value is overwritten by the new |
6504 | the given name and value. | 6609 | value from the message; if not found then a new statistic parameter is |
6610 | created with the given name and value. | ||
6505 | 6611 | ||
6506 | In addition to just setting an absolute value, it is possible to perform a | 6612 | In addition to just setting an absolute value, it is possible to perform a |
6507 | relative update by sending a message of type | 6613 | relative update by sending a message of type |
6508 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET} with an update flag | 6614 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET} with an update flag |
6509 | (@code{GNUNET_STATISTICS_SETFLAG_RELATIVE}) signifying that the value in the | 6615 | (@code{GNUNET_STATISTICS_SETFLAG_RELATIVE}) signifying that the value in |
6510 | message should be treated as an update value. | 6616 | the message should be treated as an update value. |
6511 | 6617 | ||
6512 | @node Watching for updates | 6618 | @node Watching for updates |
6513 | @subsubsection Watching for updates | 6619 | @subsubsection Watching for updates |
6514 | 6620 | ||
6515 | @c %**end of header | 6621 | @c %**end of header |
6516 | 6622 | ||
6517 | The function registers the watch at the service by sending a message of type | 6623 | The function registers the watch at the service by sending a message of |
6518 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH}. The service then sends | 6624 | type @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH}. The service then sends |
6519 | notifications through messages of type | 6625 | notifications through messages of type |
6520 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH_VALUE} whenever the statistic | 6626 | @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH_VALUE} whenever the statistic |
6521 | parameter's value is changed. | 6627 | parameter's value is changed. |
6522 | 6628 | ||
6629 | @cindex DHT | ||
6630 | @cindex Distributed Hash Table | ||
6523 | @node GNUnet's Distributed Hash Table (DHT) | 6631 | @node GNUnet's Distributed Hash Table (DHT) |
6524 | @section GNUnet's Distributed Hash Table (DHT) | 6632 | @section GNUnet's Distributed Hash Table (DHT) |
6525 | 6633 | ||
6526 | @c %**end of header | 6634 | @c %**end of header |
6527 | 6635 | ||
6528 | GNUnet includes a generic distributed hash table that can be used by developers | 6636 | GNUnet includes a generic distributed hash table that can be used by |
6529 | building P2P applications in the framework. This section documents high-level | 6637 | developers building P2P applications in the framework. |
6530 | features and how developers are expected to use the DHT. We have a research | 6638 | This section documents high-level features and how developers are |
6531 | paper detailing how the DHT works. Also, Nate's thesis includes a detailed | 6639 | expected to use the DHT. |
6532 | description and performance analysis (in chapter 6). | 6640 | We have a research paper detailing how the DHT works. |
6641 | Also, Nate's thesis includes a detailed description and performance | ||
6642 | analysis (in chapter 6). | ||
6533 | 6643 | ||
6534 | Key features of GNUnet's DHT include: | 6644 | Key features of GNUnet's DHT include: |
6535 | 6645 | ||
6536 | @itemize @bullet | 6646 | @itemize @bullet |
6537 | @item stores key-value pairs with values up to (approximately) 63k in size | 6647 | @item stores key-value pairs with values up to (approximately) 63k in size |
6538 | @item works with many underlay network topologies (small-world, random graph), | 6648 | @item works with many underlay network topologies (small-world, random |
6539 | underlay does not need to be a full mesh / clique | 6649 | graph), underlay does not need to be a full mesh / clique |
6540 | @item support for extended queries (more than just a simple 'key'), filtering | 6650 | @item support for extended queries (more than just a simple 'key'), |
6541 | duplicate replies within the network (bloomfilter) and content validation (for | 6651 | filtering duplicate replies within the network (bloomfilter) and content |
6542 | details, please read the subsection on the block library) | 6652 | validation (for details, please read the subsection on the block library) |
6543 | @item can (optionally) return paths taken by the PUT and GET operations to the | 6653 | @item can (optionally) return paths taken by the PUT and GET operations |
6544 | application | 6654 | to the application |
6545 | @item provides content replication to handle churn | 6655 | @item provides content replication to handle churn |
6546 | @end itemize | 6656 | @end itemize |
6547 | 6657 | ||
6548 | GNUnet's DHT is randomized and unreliable. Unreliable means that there is no | 6658 | GNUnet's DHT is randomized and unreliable. Unreliable means that there is |
6549 | strict guarantee that a value stored in the DHT is always found --- values are | 6659 | no strict guarantee that a value stored in the DHT is always |
6550 | only found with high probability. While this is somewhat true in all P2P DHTs, | 6660 | found --- values are only found with high probability. |
6551 | GNUnet developers should be particularly wary of this fact (this will help you | 6661 | While this is somewhat true in all P2P DHTs, GNUnet developers should be |
6552 | write secure, fault-tolerant code). Thus, when writing any application using | 6662 | particularly wary of this fact (this will help you write secure, |
6553 | the DHT, you should always consider the possibility that a value stored in the | 6663 | fault-tolerant code). Thus, when writing any application using the DHT, |
6554 | DHT by you or some other peer might simply not be returned, or returned with a | 6664 | you should always consider the possibility that a value stored in the |
6555 | significant delay. Your application logic must be written to tolerate this | 6665 | DHT by you or some other peer might simply not be returned, or returned |
6556 | (naturally, some loss of performance or quality of service is expected in this | 6666 | with a significant delay. |
6557 | case). | 6667 | Your application logic must be written to tolerate this (naturally, some |
6668 | loss of performance or quality of service is expected in this case). | ||
6558 | 6669 | ||
6559 | @menu | 6670 | @menu |
6560 | * Block library and plugins:: | 6671 | * Block library and plugins:: |
@@ -6583,62 +6694,71 @@ case). | |||
6583 | 6694 | ||
6584 | Blocks are small (< 63k) pieces of data stored under a key (struct | 6695 | Blocks are small (< 63k) pieces of data stored under a key (struct |
6585 | GNUNET_HashCode). Blocks have a type (enum GNUNET_BlockType) which defines | 6696 | GNUNET_HashCode). Blocks have a type (enum GNUNET_BlockType) which defines |
6586 | their data format. Blocks are used in GNUnet as units of static data exchanged | 6697 | their data format. Blocks are used in GNUnet as units of static data |
6587 | between peers and stored (or cached) locally. Uses of blocks include | 6698 | exchanged between peers and stored (or cached) locally. |
6588 | file-sharing (the files are broken up into blocks), the VPN (DNS information is | 6699 | Uses of blocks include file-sharing (the files are broken up into blocks), |
6589 | stored in blocks) and the DHT (all information in the DHT and meta-information | 6700 | the VPN (DNS information is stored in blocks) and the DHT (all |
6590 | for the maintenance of the DHT are both stored using blocks). The block | 6701 | information in the DHT and meta-information for the maintenance of the |
6591 | subsystem provides a few common functions that must be available for any type | 6702 | DHT are both stored using blocks). |
6592 | of block. | 6703 | The block subsystem provides a few common functions that must be |
6593 | 6704 | available for any type of block. | |
6705 | |||
6706 | @cindex libgnunetblock API | ||
6594 | @node The API of libgnunetblock | 6707 | @node The API of libgnunetblock |
6595 | @subsubsection The API of libgnunetblock | 6708 | @subsubsection The API of libgnunetblock |
6596 | 6709 | ||
6597 | @c %**end of header | 6710 | @c %**end of header |
6598 | 6711 | ||
6599 | The block library requires for each (family of) block type(s) a block plugin | 6712 | The block library requires for each (family of) block type(s) a block |
6600 | (implementing gnunet_block_plugin.h) that provides basic functions that are | 6713 | plugin (implementing @file{gnunet_block_plugin.h}) that provides basic |
6601 | needed by the DHT (and possibly other subsystems) to manage the block. These | 6714 | functions that are needed by the DHT (and possibly other subsystems) to |
6602 | block plugins are typically implemented within their respective subsystems.@ | 6715 | manage the block. |
6603 | The main block library is then used to locate, load and query the appropriate | 6716 | These block plugins are typically implemented within their respective |
6604 | block plugin. Which plugin is appropriate is determined by the block type | 6717 | subsystems. |
6605 | (which is just a 32-bit integer). Block plugins contain code that specifies | 6718 | The main block library is then used to locate, load and query the |
6606 | which block types are supported by a given plugin. The block library loads all | 6719 | appropriate block plugin. |
6607 | block plugins that are installed at the local peer and forwards the application | 6720 | Which plugin is appropriate is determined by the block type (which is |
6608 | request to the respective plugin. | 6721 | just a 32-bit integer). Block plugins contain code that specifies which |
6609 | 6722 | block types are supported by a given plugin. The block library loads all | |
6610 | The central functions of the block APIs (plugin and main library) are to allow | 6723 | block plugins that are installed at the local peer and forwards the |
6611 | the mapping of blocks to their respective key (if possible) and the ability to | 6724 | application request to the respective plugin. |
6612 | check that a block is well-formed and matches a given request (again, if | 6725 | |
6613 | possible). This way, GNUnet can avoid storing invalid blocks, storing blocks | 6726 | The central functions of the block APIs (plugin and main library) are to |
6614 | under the wrong key and forwarding blocks in response to a query that they do | 6727 | allow the mapping of blocks to their respective key (if possible) and the |
6728 | ability to check that a block is well-formed and matches a given | ||
6729 | request (again, if possible). | ||
6730 | This way, GNUnet can avoid storing invalid blocks, storing blocks under | ||
6731 | the wrong key and forwarding blocks in response to a query that they do | ||
6615 | not answer. | 6732 | not answer. |
6616 | 6733 | ||
6617 | One key function of block plugins is that it allows GNUnet to detect duplicate | 6734 | One key function of block plugins is that it allows GNUnet to detect |
6618 | replies (via the Bloom filter). All plugins MUST support detecting duplicate | 6735 | duplicate replies (via the Bloom filter). All plugins MUST support |
6619 | replies (by adding the current response to the Bloom filter and rejecting it if | 6736 | detecting duplicate replies (by adding the current response to the |
6620 | it is encountered again). If a plugin fails to do this, responses may loop in | 6737 | Bloom filter and rejecting it if it is encountered again). |
6621 | the network. | 6738 | If a plugin fails to do this, responses may loop in the network. |
6622 | 6739 | ||
6623 | @node Queries | 6740 | @node Queries |
6624 | @subsubsection Queries | 6741 | @subsubsection Queries |
6625 | @c %**end of header | 6742 | @c %**end of header |
6626 | 6743 | ||
6627 | The query format for any block in GNUnet consists of four main components. | 6744 | The query format for any block in GNUnet consists of four main components. |
6628 | First, the type of the desired block must be specified. Second, the query must | 6745 | First, the type of the desired block must be specified. Second, the query |
6629 | contain a hash code. The hash code is used for lookups in hash tables and | 6746 | must contain a hash code. The hash code is used for lookups in hash |
6630 | databases and must not be unique for the block (however, if possible a unique | 6747 | tables and databases and must not be unique for the block (however, if |
6631 | hash should be used as this would be best for performance). Third, an optional | 6748 | possible a unique hash should be used as this would be best for |
6632 | Bloom filter can be specified to exclude known results; replies that hash to | 6749 | performance). |
6633 | the bits set in the Bloom filter are considered invalid. False-positives can be | 6750 | Third, an optional Bloom filter can be specified to exclude known results; |
6634 | eliminated by sending the same query again with a different Bloom filter | 6751 | replies that hash to the bits set in the Bloom filter are considered |
6635 | mutator value, which parameterizes the hash function that is used. Finally, an | 6752 | invalid. False-positives can be eliminated by sending the same query |
6636 | optional application-specific "eXtended query" (xquery) can be specified to | 6753 | again with a different Bloom filter mutator value, which parameterizes |
6637 | further constrain the results. It is entirely up to the type-specific plugin to | 6754 | the hash function that is used. |
6638 | determine whether or not a given block matches a query (type, hash, Bloom | 6755 | Finally, an optional application-specific "eXtended query" (xquery) can |
6639 | filter, and xquery). Naturally, not all xquery's are valid and some types of | 6756 | be specified to further constrain the results. It is entirely up to |
6640 | blocks may not support Bloom filters either, so the plugin also needs to check | 6757 | the type-specific plugin to determine whether or not a given block |
6641 | if the query is valid in the first place. | 6758 | matches a query (type, hash, Bloom filter, and xquery). |
6759 | Naturally, not all xquery's are valid and some types of blocks may not | ||
6760 | support Bloom filters either, so the plugin also needs to check if the | ||
6761 | query is valid in the first place. | ||
6642 | 6762 | ||
6643 | Depending on the results from the plugin, the DHT will then discard the | 6763 | Depending on the results from the plugin, the DHT will then discard the |
6644 | (invalid) query, forward the query, discard the (invalid) reply, cache the | 6764 | (invalid) query, forward the query, discard the (invalid) reply, cache the |
@@ -6649,10 +6769,11 @@ Depending on the results from the plugin, the DHT will then discard the | |||
6649 | 6769 | ||
6650 | @c %**end of header | 6770 | @c %**end of header |
6651 | 6771 | ||
6652 | The source code in @strong{plugin_block_test.c} is a good starting point for | 6772 | The source code in @strong{plugin_block_test.c} is a good starting point |
6653 | new block plugins --- it does the minimal work by implementing a plugin that | 6773 | for new block plugins --- it does the minimal work by implementing a |
6654 | performs no validation at all. The respective @strong{Makefile.am} shows how to | 6774 | plugin that performs no validation at all. |
6655 | build and install a block plugin. | 6775 | The respective @strong{Makefile.am} shows how to build and install a |
6776 | block plugin. | ||
6656 | 6777 | ||
6657 | @node Conclusion2 | 6778 | @node Conclusion2 |
6658 | @subsubsection Conclusion2 | 6779 | @subsubsection Conclusion2 |
@@ -6660,21 +6781,23 @@ build and install a block plugin. | |||
6660 | @c %**end of header | 6781 | @c %**end of header |
6661 | 6782 | ||
6662 | In conclusion, GNUnet subsystems that want to use the DHT need to define a | 6783 | In conclusion, GNUnet subsystems that want to use the DHT need to define a |
6663 | block format and write a plugin to match queries and replies. For testing, the | 6784 | block format and write a plugin to match queries and replies. For testing, |
6664 | "GNUNET_BLOCK_TYPE_TEST" block type can be used; it accepts any query as valid | 6785 | the "@code{GNUNET_BLOCK_TYPE_TEST}" block type can be used; it accepts |
6665 | and any reply as matching any query. This type is also used for the DHT command | 6786 | any query as valid and any reply as matching any query. |
6666 | line tools. However, it should NOT be used for normal applications due to the | 6787 | This type is also used for the DHT command line tools. |
6667 | lack of error checking that results from this primitive implementation. | 6788 | However, it should NOT be used for normal applications due to the lack |
6668 | 6789 | of error checking that results from this primitive implementation. | |
6790 | |||
6791 | @cindex libgnunetdht | ||
6669 | @node libgnunetdht | 6792 | @node libgnunetdht |
6670 | @subsection libgnunetdht | 6793 | @subsection libgnunetdht |
6671 | 6794 | ||
6672 | @c %**end of header | 6795 | @c %**end of header |
6673 | 6796 | ||
6674 | The DHT API itself is pretty simple and offers the usual GET and PUT functions | 6797 | The DHT API itself is pretty simple and offers the usual GET and PUT |
6675 | that work as expected. The specified block type refers to the block library | 6798 | functions that work as expected. The specified block type refers to the |
6676 | which allows the DHT to run application-specific logic for data stored in the | 6799 | block library which allows the DHT to run application-specific logic for |
6677 | network. | 6800 | data stored in the network. |
6678 | 6801 | ||
6679 | 6802 | ||
6680 | @menu | 6803 | @menu |
@@ -6689,23 +6812,26 @@ network. | |||
6689 | 6812 | ||
6690 | @c %**end of header | 6813 | @c %**end of header |
6691 | 6814 | ||
6692 | When using GET, the main consideration for developers (other than the block | 6815 | When using GET, the main consideration for developers (other than the |
6693 | library) should be that after issuing a GET, the DHT will continuously cause | 6816 | block library) should be that after issuing a GET, the DHT will |
6694 | (small amounts of) network traffic until the operation is explicitly canceled. | 6817 | continuously cause (small amounts of) network traffic until the operation |
6695 | So GET does not simply send out a single network request once; instead, the | 6818 | is explicitly canceled. |
6696 | DHT will continue to search for data. This is needed to achieve good success | 6819 | So GET does not simply send out a single network request once; instead, |
6697 | rates and also handles the case where the respective PUT operation happens | 6820 | the DHT will continue to search for data. This is needed to achieve good |
6698 | after the GET operation was started. Developers should not cancel an existing | 6821 | success rates and also handles the case where the respective PUT |
6699 | GET operation and then explicitly re-start it to trigger a new round of | 6822 | operation happens after the GET operation was started. |
6700 | network requests; this is simply inefficient, especially as the internal | 6823 | Developers should not cancel an existing GET operation and then |
6701 | automated version can be more efficient, for example by filtering results in | 6824 | explicitly re-start it to trigger a new round of network requests; |
6702 | the network that have already been returned. | 6825 | this is simply inefficient, especially as the internal automated version |
6826 | can be more efficient, for example by filtering results in the network | ||
6827 | that have already been returned. | ||
6703 | 6828 | ||
6704 | If an application that performs a GET request has a set of replies that it | 6829 | If an application that performs a GET request has a set of replies that it |
6705 | already knows and would like to filter, it can call@ | 6830 | already knows and would like to filter, it can call@ |
6706 | @code{GNUNET_DHT_get_filter_known_results} with an array of hashes over the | 6831 | @code{GNUNET_DHT_get_filter_known_results} with an array of hashes over |
6707 | respective blocks to tell the DHT that these results are not desired (any | 6832 | the respective blocks to tell the DHT that these results are not |
6708 | more). This way, the DHT will filter the respective blocks using the block | 6833 | desired (any more). |
6834 | This way, the DHT will filter the respective blocks using the block | ||
6709 | library in the network, which may result in a significant reduction in | 6835 | library in the network, which may result in a significant reduction in |
6710 | bandwidth consumption. | 6836 | bandwidth consumption. |
6711 | 6837 | ||
@@ -6714,18 +6840,20 @@ bandwidth consumption. | |||
6714 | 6840 | ||
6715 | @c %**end of header | 6841 | @c %**end of header |
6716 | 6842 | ||
6717 | In contrast to GET operations, developers @strong{must} manually re-run PUT | 6843 | In contrast to GET operations, developers @strong{must} manually re-run |
6718 | operations periodically (if they intend the content to continue to be | 6844 | PUT operations periodically (if they intend the content to continue to be |
6719 | available). Content stored in the DHT expires or might be lost due to churn. | 6845 | available). Content stored in the DHT expires or might be lost due to |
6720 | Furthermore, GNUnet's DHT typically requires multiple rounds of PUT operations | 6846 | churn. |
6721 | before a key-value pair is consistently available to all peers (the DHT | 6847 | Furthermore, GNUnet's DHT typically requires multiple rounds of PUT |
6722 | randomizes paths and thus storage locations, and only after multiple rounds of | 6848 | operations before a key-value pair is consistently available to all |
6723 | PUTs there will be a sufficient number of replicas in large DHTs). An explicit | 6849 | peers (the DHT randomizes paths and thus storage locations, and only |
6724 | PUT operation using the DHT API will only cause network traffic once, so in | 6850 | after multiple rounds of PUTs there will be a sufficient number of |
6725 | order to ensure basic availability and resistance to churn (and adversaries), | 6851 | replicas in large DHTs). An explicit PUT operation using the DHT API will |
6726 | PUTs must be repeated. While the exact frequency depends on the application, a | 6852 | only cause network traffic once, so in order to ensure basic availability |
6727 | rule of thumb is that there should be at least a dozen PUT operations within | 6853 | and resistance to churn (and adversaries), PUTs must be repeated. |
6728 | the content lifetime. Content in the DHT typically expires after one day, so | 6854 | While the exact frequency depends on the application, a rule of thumb is |
6855 | that there should be at least a dozen PUT operations within the content | ||
6856 | lifetime. Content in the DHT typically expires after one day, so | ||
6729 | DHT PUT operations should be repeated at least every 1-2 hours. | 6857 | DHT PUT operations should be repeated at least every 1-2 hours. |
6730 | 6858 | ||
6731 | @node MONITOR | 6859 | @node MONITOR |
@@ -6733,18 +6861,21 @@ DHT PUT operations should be repeated at least every 1-2 hours. | |||
6733 | 6861 | ||
6734 | @c %**end of header | 6862 | @c %**end of header |
6735 | 6863 | ||
6736 | The DHT API also allows applications to monitor messages crossing the local | 6864 | The DHT API also allows applications to monitor messages crossing the |
6737 | DHT service. The types of messages used by the DHT are GET, PUT and RESULT | 6865 | local DHT service. |
6738 | messages. Using the monitoring API, applications can choose to monitor these | 6866 | The types of messages used by the DHT are GET, PUT and RESULT messages. |
6867 | Using the monitoring API, applications can choose to monitor these | ||
6739 | requests, possibly limiting themselves to requests for a particular block | 6868 | requests, possibly limiting themselves to requests for a particular block |
6740 | type. | 6869 | type. |
6741 | 6870 | ||
6742 | The monitoring API is not only usefu only for diagnostics, it can also be used | 6871 | The monitoring API is not only usefu only for diagnostics, it can also be |
6743 | to trigger application operations based on PUT operations. For example, an | 6872 | used to trigger application operations based on PUT operations. |
6744 | application may use PUTs to distribute work requests to other peers. The | 6873 | For example, an application may use PUTs to distribute work requests to |
6745 | workers would then monitor for PUTs that give them work, instead of looking | 6874 | other peers. |
6746 | for work using GET operations. This can be beneficial, especially if the | 6875 | The workers would then monitor for PUTs that give them work, instead of |
6747 | workers have no good way to guess the keys under which work would be stored. | 6876 | looking for work using GET operations. |
6877 | This can be beneficial, especially if the workers have no good way to | ||
6878 | guess the keys under which work would be stored. | ||
6748 | Naturally, additional protocols might be needed to ensure that the desired | 6879 | Naturally, additional protocols might be needed to ensure that the desired |
6749 | number of workers will process the distributed workload. | 6880 | number of workers will process the distributed workload. |
6750 | 6881 | ||
@@ -6756,25 +6887,26 @@ number of workers will process the distributed workload. | |||
6756 | There are two important options for GET and PUT requests: | 6887 | There are two important options for GET and PUT requests: |
6757 | 6888 | ||
6758 | @table @asis | 6889 | @table @asis |
6759 | @item GNUNET_DHT_RO_DEMULITPLEX_EVERYWHERE This option means that all peers | 6890 | @item GNUNET_DHT_RO_DEMULITPLEX_EVERYWHERE This option means that all |
6760 | should process the request, even if their peer ID is not closest to the key. | 6891 | peers should process the request, even if their peer ID is not closest to |
6761 | For a PUT request, this means that all peers that a request traverses may make | 6892 | the key. For a PUT request, this means that all peers that a request |
6762 | a copy of the data. Similarly for a GET request, all peers will check their | 6893 | traverses may make a copy of the data. |
6763 | local database for a result. Setting this option can thus significantly improve | 6894 | Similarly for a GET request, all peers will check their local database |
6764 | caching and reduce bandwidth consumption --- at the expense of a larger DHT | 6895 | for a result. Setting this option can thus significantly improve caching |
6896 | and reduce bandwidth consumption --- at the expense of a larger DHT | ||
6765 | database. If in doubt, we recommend that this option should be used. | 6897 | database. If in doubt, we recommend that this option should be used. |
6766 | @item GNUNET_DHT_RO_RECORD_ROUTE This option instructs the DHT to record the path | 6898 | @item GNUNET_DHT_RO_RECORD_ROUTE This option instructs the DHT to record |
6767 | that a GET or a PUT request is taking through the overlay network. The | 6899 | the path that a GET or a PUT request is taking through the overlay |
6768 | resulting paths are then returned to the application with the respective | 6900 | network. The resulting paths are then returned to the application with |
6769 | result. This allows the receiver of a result to construct a path to the | 6901 | the respective result. This allows the receiver of a result to construct |
6770 | originator of the data, which might then be used for routing. Naturally, | 6902 | a path to the originator of the data, which might then be used for |
6771 | setting this option requires additional bandwidth and disk space, so | 6903 | routing. Naturally, setting this option requires additional bandwidth |
6772 | applications should only set this if the paths are needed by the application | 6904 | and disk space, so applications should only set this if the paths are |
6773 | logic. | 6905 | needed by the application logic. |
6774 | @item GNUNET_DHT_RO_FIND_PEER This option is an internal option used by | 6906 | @item GNUNET_DHT_RO_FIND_PEER This option is an internal option used by |
6775 | the DHT's peer discovery mechanism and should not be used by applications. | 6907 | the DHT's peer discovery mechanism and should not be used by applications. |
6776 | @item GNUNET_DHT_RO_BART This option is currently not implemented. It may in | 6908 | @item GNUNET_DHT_RO_BART This option is currently not implemented. It may |
6777 | the future offer performance improvements for clique topologies. | 6909 | in the future offer performance improvements for clique topologies. |
6778 | @end table | 6910 | @end table |
6779 | 6911 | ||
6780 | @node The DHT Client-Service Protocol | 6912 | @node The DHT Client-Service Protocol |
@@ -6793,73 +6925,76 @@ the future offer performance improvements for clique topologies. | |||
6793 | 6925 | ||
6794 | @c %**end of header | 6926 | @c %**end of header |
6795 | 6927 | ||
6796 | To store (PUT) data into the DHT, the client sends a@ @code{struct | 6928 | To store (PUT) data into the DHT, the client sends a |
6797 | GNUNET_DHT_ClientPutMessage} to the service. This message specifies the block | 6929 | @code{struct GNUNET_DHT_ClientPutMessage} to the service. |
6798 | type, routing options, the desired replication level, the expiration time, key, | 6930 | This message specifies the block type, routing options, the desired |
6799 | value and a 64-bit unique ID for the operation. The service responds with a@ | 6931 | replication level, the expiration time, key, |
6800 | @code{struct GNUNET_DHT_ClientPutConfirmationMessage} with the same 64-bit | 6932 | value and a 64-bit unique ID for the operation. The service responds with |
6801 | unique ID. Note that the service sends the confirmation as soon as it has | 6933 | a @code{struct GNUNET_DHT_ClientPutConfirmationMessage} with the same |
6802 | locally processed the PUT request. The PUT may still be propagating through the | 6934 | 64-bit unique ID. Note that the service sends the confirmation as soon as |
6803 | network at this time. | 6935 | it has locally processed the PUT request. The PUT may still be |
6936 | propagating through the network at this time. | ||
6804 | 6937 | ||
6805 | In the future, we may want to change this to provide (limited) feedback to the | 6938 | In the future, we may want to change this to provide (limited) feedback |
6806 | client, for example if we detect that the PUT operation had no effect because | 6939 | to the client, for example if we detect that the PUT operation had no |
6807 | the same key-value pair was already stored in the DHT. However, changing this | 6940 | effect because the same key-value pair was already stored in the DHT. |
6808 | would also require additional state and messages in the P2P | 6941 | However, changing this would also require additional state and messages |
6809 | interaction. | 6942 | in the P2P interaction. |
6810 | 6943 | ||
6811 | @node GETting data from the DHT | 6944 | @node GETting data from the DHT |
6812 | @subsubsection GETting data from the DHT | 6945 | @subsubsection GETting data from the DHT |
6813 | 6946 | ||
6814 | @c %**end of header | 6947 | @c %**end of header |
6815 | 6948 | ||
6816 | To retrieve (GET) data from the DHT, the client sends a@ @code{struct | 6949 | To retrieve (GET) data from the DHT, the client sends a |
6817 | GNUNET_DHT_ClientGetMessage} to the service. The message specifies routing | 6950 | @code{struct GNUNET_DHT_ClientGetMessage} to the service. The message |
6818 | options, a replication level (for replicating the GET, not the content), the | 6951 | specifies routing options, a replication level (for replicating the GET, |
6819 | desired block type, the key, the (optional) extended query and unique 64-bit | 6952 | not the content), the desired block type, the key, the (optional) |
6820 | request ID. | 6953 | extended query and unique 64-bit request ID. |
6821 | 6954 | ||
6822 | Additionally, the client may send any number of@ @code{struct | 6955 | Additionally, the client may send any number of |
6823 | GNUNET_DHT_ClientGetResultSeenMessage}s to notify the service about results | 6956 | @code{struct GNUNET_DHT_ClientGetResultSeenMessage}s to notify the |
6824 | that the client is already aware of. These messages consist of the key, the | 6957 | service about results that the client is already aware of. |
6825 | unique 64-bit ID of the request, and an arbitrary number of hash codes over the | 6958 | These messages consist of the key, the unique 64-bit ID of the request, |
6826 | blocks that the client is already aware of. As messages are restricted to 64k, | 6959 | and an arbitrary number of hash codes over the blocks that the client is |
6827 | a client that already knows more than about a thousand blocks may need to send | 6960 | already aware of. As messages are restricted to 64k, a client that |
6828 | several of these messages. Naturally, the client should transmit these messages | 6961 | already knows more than about a thousand blocks may need to send |
6829 | as quickly as possible after the original GET request such that the DHT can | 6962 | several of these messages. Naturally, the client should transmit these |
6830 | filter those results in the network early on. Naturally, as these messages are | 6963 | messages as quickly as possible after the original GET request such that |
6831 | send after the original request, it is conceivalbe that the DHT service may | 6964 | the DHT can filter those results in the network early on. Naturally, as |
6832 | return blocks that match those already known to the client anyway. | 6965 | these messages are send after the original request, it is conceivalbe |
6966 | that the DHT service may return blocks that match those already known | ||
6967 | to the client anyway. | ||
6833 | 6968 | ||
6834 | In response to a GET request, the service will send @code{struct | 6969 | In response to a GET request, the service will send @code{struct |
6835 | GNUNET_DHT_ClientResultMessage}s to the client. These messages contain the | 6970 | GNUNET_DHT_ClientResultMessage}s to the client. These messages contain the |
6836 | block type, expiration, key, unique ID of the request and of course the value | 6971 | block type, expiration, key, unique ID of the request and of course the |
6837 | (a block). Depending on the options set for the respective operations, the | 6972 | value (a block). Depending on the options set for the respective |
6838 | replies may also contain the path the GET and/or the PUT took through the | 6973 | operations, the replies may also contain the path the GET and/or the PUT |
6839 | network. | 6974 | took through the network. |
6840 | 6975 | ||
6841 | A client can stop receiving replies either by disconnecting or by sending a | 6976 | A client can stop receiving replies either by disconnecting or by sending |
6842 | @code{struct GNUNET_DHT_ClientGetStopMessage} which must contain the key and | 6977 | a @code{struct GNUNET_DHT_ClientGetStopMessage} which must contain the |
6843 | the 64-bit unique ID of the original request. Using an explicit "stop" message | 6978 | key and the 64-bit unique ID of the original request. Using an |
6844 | is more common as this allows a client to run many concurrent GET operations | 6979 | explicit "stop" message is more common as this allows a client to run |
6845 | over the same connection with the DHT service --- and to stop them | 6980 | many concurrent GET operations over the same connection with the DHT |
6846 | individually. | 6981 | service --- and to stop them individually. |
6847 | 6982 | ||
6848 | @node Monitoring the DHT | 6983 | @node Monitoring the DHT |
6849 | @subsubsection Monitoring the DHT | 6984 | @subsubsection Monitoring the DHT |
6850 | 6985 | ||
6851 | @c %**end of header | 6986 | @c %**end of header |
6852 | 6987 | ||
6853 | To begin monitoring, the client sends a @code{struct | 6988 | To begin monitoring, the client sends a |
6854 | GNUNET_DHT_MonitorStartStop} message to the DHT service. In this message, flags | 6989 | @code{struct GNUNET_DHT_MonitorStartStop} message to the DHT service. |
6855 | can be set to enable (or disable) monitoring of GET, PUT and RESULT messages | 6990 | In this message, flags can be set to enable (or disable) monitoring of |
6856 | that pass through a peer. The message can also restrict monitoring to a | 6991 | GET, PUT and RESULT messages that pass through a peer. The message can |
6857 | particular block type or a particular key. Once monitoring is enabled, the DHT | 6992 | also restrict monitoring to a particular block type or a particular key. |
6858 | service will notify the client about any matching event using @code{struct | 6993 | Once monitoring is enabled, the DHT service will notify the client about |
6859 | GNUNET_DHT_MonitorGetMessage}s for GET events, @code{struct | 6994 | any matching event using @code{struct GNUNET_DHT_MonitorGetMessage}s for |
6860 | GNUNET_DHT_MonitorPutMessage} for PUT events and@ @code{struct | 6995 | GET events, @code{struct GNUNET_DHT_MonitorPutMessage} for PUT events |
6861 | GNUNET_DHT_MonitorGetRespMessage} for RESULTs. Each of these messages contains | 6996 | and @code{struct GNUNET_DHT_MonitorGetRespMessage} for RESULTs. Each of |
6862 | all of the information about the event. | 6997 | these messages contains all of the information about the event. |
6863 | 6998 | ||
6864 | @node The DHT Peer-to-Peer Protocol | 6999 | @node The DHT Peer-to-Peer Protocol |
6865 | @subsection The DHT Peer-to-Peer Protocol | 7000 | @subsection The DHT Peer-to-Peer Protocol |
diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi index 7fa03152e..6feb2f4dc 100644 --- a/doc/documentation/chapters/installation.texi +++ b/doc/documentation/chapters/installation.texi | |||
@@ -878,29 +878,34 @@ TODO | |||
878 | @section Build instructions for Debian 7.5 | 878 | @section Build instructions for Debian 7.5 |
879 | 879 | ||
880 | 880 | ||
881 | These are the installation instructions for Debian 7.5. They were tested using | 881 | These are the installation instructions for Debian 7.5. They were tested |
882 | a minimal, fresh Debian 7.5 AMD64 installation without non-free software | 882 | using a minimal, fresh Debian 7.5 AMD64 installation without non-free |
883 | (no contrib or non-free). By "minimal", we mean that during installation, we | 883 | software (no contrib or non-free). |
884 | did not select any desktop environment, servers or system utilities during the | 884 | By "minimal", we mean that during installation, we did not select any |
885 | "tasksel" step. Note that the packages and the dependencies that we will | 885 | desktop environment, servers or system utilities during the "tasksel" |
886 | install during this chapter take about 1.5 GB of disk space. Combined with | 886 | step. Note that the packages and the dependencies that we will install |
887 | GNUnet and space for objects during compilation, you should not even attempt | 887 | during this chapter take about 1.5 GB of disk space. |
888 | this unless you have about 2.5 GB free after the minimal Debian installation. | 888 | Combined with GNUnet and space for objects during compilation, you should |
889 | Using these instructions to build a VM image is likely to require a minimum of | 889 | not even attempt this unless you have about 2.5 GB free after the minimal |
890 | 4-5 GB for the VM (as you will likely also want a desktop manager). | 890 | Debian installation. |
891 | 891 | Using these instructions to build a VM image is likely to require a | |
892 | GNUnet's security model assumes that your @file{/home} directory is encrypted. | 892 | minimum of 4-5 GB for the VM (as you will likely also want a desktop |
893 | Thus, if possible, you should encrypt your home partition | 893 | manager). |
894 | |||
895 | GNUnet's security model assumes that your @file{/home} directory is | ||
896 | encrypted. Thus, if possible, you should encrypt your home partition | ||
894 | (or per-user home directory). | 897 | (or per-user home directory). |
895 | 898 | ||
896 | Naturally, the exact details of the starting state for your installation | 899 | Naturally, the exact details of the starting state for your installation |
897 | should not matter much. For example, if you selected any of those installation | 900 | should not matter much. For example, if you selected any of those |
898 | groups you might simply already have some of the necessary packages installed. | 901 | installation groups you might simply already have some of the necessary |
899 | We did this for testing, as this way we are less likely to forget to mention a | 902 | packages installed. |
900 | required package. Note that we will not install a desktop environment, but of | 903 | We did this for testing, as this way we are less likely to forget to |
901 | course you will need to install one to use GNUnet's graphical user interfaces. | 904 | mention a required package. |
902 | Thus, it is suggested that you simply install the desktop environment of your | 905 | Note that we will not install a desktop environment, but of course you |
903 | choice before beginning with the instructions. | 906 | will need to install one to use GNUnet's graphical user interfaces. |
907 | Thus, it is suggested that you simply install the desktop environment of | ||
908 | your choice before beginning with the instructions. | ||
904 | 909 | ||
905 | 910 | ||
906 | 911 | ||
@@ -923,20 +928,23 @@ After any installation, you should begin by running | |||
923 | # apt-get update ; apt-get upgrade | 928 | # apt-get update ; apt-get upgrade |
924 | @end example | 929 | @end example |
925 | 930 | ||
926 | to ensure that all of your packages are up-to-date. Note that the "#" is used | 931 | to ensure that all of your packages are up-to-date. Note that the "#" is |
927 | to indicate that you need to type in this command as "root" | 932 | used to indicate that you need to type in this command as "root" |
928 | (or prefix with "sudo"), whereas "$" is used to indicate typing in a command | 933 | (or prefix with "sudo"), whereas "$" is used to indicate typing in a |
929 | as a normal user. | 934 | command as a normal user. |
930 | 935 | ||
931 | @node Stable? Hah! | 936 | @node Stable? Hah! |
932 | @subsection Stable? Hah! | 937 | @subsection Stable? Hah! |
933 | 938 | ||
934 | Yes, we said we start with a Debian 7.5 "stable" system. However, to reduce the | 939 | Yes, we said we start with a Debian 7.5 "stable" system. However, to |
935 | amount of compilation by hand, we will begin by allowing the installation of | 940 | reduce the amount of compilation by hand, we will begin by allowing the |
936 | packages from the testing and unstable distributions as well. We will stick to | 941 | installation of packages from the testing and unstable distributions as |
937 | "stable" packages where possible, but some packages will be taken from the | 942 | well. |
938 | other distributions. Start by modifying @file{/etc/apt/sources.list} to contain | 943 | We will stick to "stable" packages where possible, but some packages will |
939 | the following (possibly adjusted to point to your mirror of choice): | 944 | be taken from the other distributions. |
945 | Start by modifying @file{/etc/apt/sources.list} to contain the | ||
946 | following (possibly adjusted to point to your mirror of choice): | ||
947 | |||
940 | @example | 948 | @example |
941 | # These were there before: | 949 | # These were there before: |
942 | deb http://ftp.de.debian.org/debian/ wheezy main | 950 | deb http://ftp.de.debian.org/debian/ wheezy main |
@@ -951,8 +959,8 @@ deb http://ftp.de.debian.org/debian/ testing main | |||
951 | deb http://ftp.de.debian.org/debian/ unstable main | 959 | deb http://ftp.de.debian.org/debian/ unstable main |
952 | @end example | 960 | @end example |
953 | 961 | ||
954 | The next step is to create/edit your @file{/etc/apt/preferences} file to look | 962 | The next step is to create/edit your @file{/etc/apt/preferences} |
955 | like this: | 963 | file to look like this: |
956 | 964 | ||
957 | @example | 965 | @example |
958 | Package: * | 966 | Package: * |
@@ -968,11 +976,12 @@ Pin: release o=Debian,a=unstable | |||
968 | Pin-Priority: 600 | 976 | Pin-Priority: 600 |
969 | @end example | 977 | @end example |
970 | 978 | ||
971 | You can read more about Apt Preferences here and here. Note that other pinnings | 979 | You can read more about Apt Preferences here and here. |
972 | are likely to also work for GNUnet, the key thing is that you need some | 980 | Note that other pinnings are likely to also work for GNUnet, the key |
973 | packages from unstable (as shown below). However, as unstable is unlikely to | 981 | thing is that you need some packages from unstable (as shown below). |
974 | be comprehensive (missing packages) or might be problematic (crashing packages), | 982 | However, as unstable is unlikely to be comprehensive (missing packages) |
975 | you probably want others from stable and/or testing. | 983 | or might be problematic (crashing packages), you probably want others |
984 | from stable and/or testing. | ||
976 | 985 | ||
977 | @node Update again | 986 | @node Update again |
978 | @subsection Update again | 987 | @subsection Update again |
@@ -984,8 +993,9 @@ Now, run again@ | |||
984 | # apt-get upgrade@ | 993 | # apt-get upgrade@ |
985 | @end example | 994 | @end example |
986 | 995 | ||
987 | to ensure that all your new distribution indices are downloaded, and that your | 996 | to ensure that all your new distribution indices are downloaded, and |
988 | pinning is correct: the upgrade step should cause no changes at all. | 997 | that your pinning is correct: the upgrade step should cause no changes |
998 | at all. | ||
989 | 999 | ||
990 | @node Installing packages | 1000 | @node Installing packages |
991 | @subsection Installing packages | 1001 | @subsection Installing packages |
@@ -1015,9 +1025,10 @@ After that, we install a few more packages from unstable:@ | |||
1015 | @node Installing dependencies from source | 1025 | @node Installing dependencies from source |
1016 | @subsection Installing dependencies from source | 1026 | @subsection Installing dependencies from source |
1017 | 1027 | ||
1018 | Next, we need to install a few dependencies from source. You might want to do | 1028 | Next, we need to install a few dependencies from source. |
1019 | this as a "normal" user and only run the @code{make install} steps as root | 1029 | You might want to do this as a "normal" user and only run the |
1020 | (hence the @code{sudo} in the commands below). Also, you do this from any | 1030 | @code{make install} steps as root (hence the @code{sudo} in the |
1031 | commands below). Also, you do this from any | ||
1021 | directory. We begin by downloading all dependencies, then extracting the | 1032 | directory. We begin by downloading all dependencies, then extracting the |
1022 | sources, and finally compiling and installing the libraries:@ | 1033 | sources, and finally compiling and installing the libraries:@ |
1023 | 1034 | ||
@@ -1049,12 +1060,12 @@ $ cd libmicrohttpd-0.9.33; ./configure; | |||
1049 | $ make ; sudo make install ; cd .. | 1060 | $ make ; sudo make install ; cd .. |
1050 | $ cd gnurl-7.34.0 | 1061 | $ cd gnurl-7.34.0 |
1051 | $ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \ | 1062 | $ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \ |
1052 | --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \ | 1063 | --without-libmetalink --without-winidn --without-librtmp \ |
1053 | --without-nss --without-cyassl --without-polarssl --without-ssl \ | 1064 | --without-nghttp2 --without-nss --without-cyassl --without-polarssl \ |
1054 | --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \ | 1065 | --without-ssl --without-winssl --without-darwinssl --disable-sspi \ |
1055 | --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \ | 1066 | --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \ |
1056 | --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \ | 1067 | --disable-telnet --disable-tftp --disable-pop3 --disable-imap \ |
1057 | --disable-ftp | 1068 | --disable-smtp --disable-gopher --disable-file --disable-ftp |
1058 | $ make ; sudo make install; cd .. | 1069 | $ make ; sudo make install; cd .. |
1059 | @end example | 1070 | @end example |
1060 | 1071 | ||
@@ -1068,10 +1079,11 @@ here. | |||
1068 | @node But wait there is more! | 1079 | @node But wait there is more! |
1069 | @subsection But wait there is more! | 1080 | @subsection But wait there is more! |
1070 | 1081 | ||
1071 | So far, we installed all of the packages and dependencies required to ensure | 1082 | So far, we installed all of the packages and dependencies required to |
1072 | that all of GNUnet would be built. However, while for example the plugins to | 1083 | ensure that all of GNUnet would be built. |
1073 | interact with the MySQL or Postgres databases have been created, we did not | 1084 | However, while for example the plugins to interact with the MySQL or |
1074 | actually install or configure those databases. Thus, you will need to install | 1085 | Postgres databases have been created, we did not actually install or |
1086 | configure those databases. Thus, you will need to install | ||
1075 | and configure those databases or stick with the default Sqlite database. | 1087 | and configure those databases or stick with the default Sqlite database. |
1076 | Sqlite is usually fine for most applications, but MySQL can offer better | 1088 | Sqlite is usually fine for most applications, but MySQL can offer better |
1077 | performance and Postgres better resillience. | 1089 | performance and Postgres better resillience. |
@@ -1131,12 +1143,12 @@ $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2 | |||
1131 | $ tar xf gnurl-7.35.0.tar.bz2 | 1143 | $ tar xf gnurl-7.35.0.tar.bz2 |
1132 | $ cd gnurl-7.35.0 | 1144 | $ cd gnurl-7.35.0 |
1133 | $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \ | 1145 | $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \ |
1134 | --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \ | 1146 | --without-libmetalink --without-winidn --without-librtmp \ |
1135 | --without-nss --without-cyassl --without-polarssl --without-ssl \ | 1147 | --without-nghttp2 --without-nss --without-cyassl --without-polarssl \ |
1136 | --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \ | 1148 | --without-ssl --without-winssl --without-darwinssl --disable-sspi \ |
1137 | --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \ | 1149 | --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \ |
1138 | --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \ | 1150 | --disable-telnet --disable-tftp --disable-pop3 --disable-imap \ |
1139 | --disable-ftp | 1151 | --disable-smtp --disable-gopher --disable-file --disable-ftp |
1140 | $ sudo make install | 1152 | $ sudo make install |
1141 | $ cd .. | 1153 | $ cd .. |
1142 | @end example | 1154 | @end example |
@@ -1157,47 +1169,64 @@ Install to a different directory:@ | |||
1157 | --prefix=PREFIX | 1169 | --prefix=PREFIX |
1158 | 1170 | ||
1159 | @item | 1171 | @item |
1160 | Have sudo permission, but do not want to compile as root:@ | 1172 | Have sudo permission, but do not want to compile as root: |
1161 | --with-sudo | 1173 | |
1174 | @example | ||
1175 | --with-sudo | ||
1176 | @end example | ||
1162 | 1177 | ||
1163 | @item | 1178 | @item |
1164 | Want debug message enabled:@ | 1179 | Want debug message enabled: |
1165 | -- enable-logging=verbose | 1180 | |
1181 | @example | ||
1182 | --enable-logging=verbose | ||
1183 | @end example | ||
1184 | |||
1166 | @end itemize | 1185 | @end itemize |
1167 | 1186 | ||
1168 | 1187 | ||
1169 | @code{@ | 1188 | @example |
1170 | $ ./configure [ --with-sudo | --prefix=PREFIX | --- enable-logging=verbose]@ | 1189 | $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose] |
1171 | $ make; sudo make install@ | 1190 | $ make; sudo make install |
1172 | } | 1191 | @end example |
1173 | 1192 | ||
1174 | After installing it, you need to create an empty configuration file:@ | 1193 | After installing it, you need to create an empty configuration file: |
1175 | @code{touch ~/.config/gnunet.conf} | 1194 | |
1195 | @example | ||
1196 | touch ~/.config/gnunet.conf | ||
1197 | @end example | ||
1176 | 1198 | ||
1177 | And finally you can start GNUnet with@ | 1199 | And finally you can start GNUnet with |
1178 | @code{$ gnunet-arm -s} | 1200 | |
1201 | @example | ||
1202 | $ gnunet-arm -s | ||
1203 | @end example | ||
1179 | 1204 | ||
1180 | @node Build instructions for Debian 8 | 1205 | @node Build instructions for Debian 8 |
1181 | @section Build instructions for Debian 8 | 1206 | @section Build instructions for Debian 8 |
1182 | 1207 | ||
1183 | These are the installation instructions for Debian 8. They were tested using a | 1208 | These are the installation instructions for Debian 8. They were tested |
1184 | fresh Debian 8 AMD64 installation without non-free software (no contrib or | 1209 | sing a fresh Debian 8 AMD64 installation without non-free software (no |
1185 | non-free). During installation, I only selected "lxde" for the desktop | 1210 | contrib or non-free). During installation, I only selected "lxde" for the |
1186 | environment. Note that the packages and the dependencies that we will install | 1211 | desktop environment. |
1187 | during this chapter take about 1.5 GB of disk space. Combined with GNUnet and | 1212 | Note that the packages and the dependencies that we will install during |
1188 | space for objects during compilation, you should not even attempt this unless | 1213 | this chapter take about 1.5 GB of disk space. Combined with GNUnet and |
1189 | you have about 2.5 GB free after the Debian installation. Using these | 1214 | space for objects during compilation, you should not even attempt this |
1190 | instructions to build a VM image is likely to require a minimum of 4-5 GB for | 1215 | unless you have about 2.5 GB free after the Debian installation. |
1191 | the VM (as you will likely also want a desktop manager). | 1216 | Using these instructions to build a VM image is likely to require a |
1192 | 1217 | minimum of 4-5 GB for the VM (as you will likely also want a desktop | |
1193 | GNUnet's security model assumes that your @code{/home} directory is encrypted. | 1218 | manager). |
1194 | Thus, if possible, you should encrypt your entire disk, or at least just your | 1219 | |
1195 | home partition (or per-user home directory). | 1220 | GNUnet's security model assumes that your @code{/home} directory is |
1196 | 1221 | encrypted. | |
1197 | Naturally, the exact details of the starting state for your installation should | 1222 | Thus, if possible, you should encrypt your entire disk, or at least just |
1198 | not matter much. For example, if you selected any of those installation groups | 1223 | your home partition (or per-user home directory). |
1199 | you might simply already have some of the necessary packages installed. Thus, | 1224 | |
1200 | it is suggested that you simply install the desktop environment of your choice | 1225 | Naturally, the exact details of the starting state for your installation |
1226 | should not matter much. | ||
1227 | For example, if you selected any of those installation groups you might | ||
1228 | simply already have some of the necessary packages installed. Thus, it is | ||
1229 | suggested that you simply install the desktop environment of your choice | ||
1201 | before beginning with the instructions. | 1230 | before beginning with the instructions. |
1202 | 1231 | ||
1203 | 1232 | ||
@@ -1212,63 +1241,68 @@ before beginning with the instructions. | |||
1212 | @node Update Debian | 1241 | @node Update Debian |
1213 | @subsection Update Debian | 1242 | @subsection Update Debian |
1214 | 1243 | ||
1215 | After any installation, you should begin by running@ | 1244 | After any installation, you should begin by running |
1216 | @code{@ | 1245 | |
1217 | # apt-get update@ | 1246 | @example |
1218 | # apt-get upgrade@ | 1247 | # apt-get update |
1219 | }@ | 1248 | # apt-get upgrade |
1220 | to ensure that all of your packages are up-to-date. Note that the "#" is used | 1249 | @end example |
1221 | to indicate that you need to type in this command as "root" (or prefix with | 1250 | |
1222 | "sudo"), whereas "$" is used to indicate typing in a command as a normal | 1251 | to ensure that all of your packages are up-to-date. Note that the "#" is |
1223 | user. | 1252 | used to indicate that you need to type in this command as "root" (or |
1253 | prefix with "sudo"), whereas "$" is used to indicate typing in a command | ||
1254 | as a normal user. | ||
1224 | 1255 | ||
1225 | @node Installing Debian Packages | 1256 | @node Installing Debian Packages |
1226 | @subsection Installing Debian Packages | 1257 | @subsection Installing Debian Packages |
1227 | 1258 | ||
1228 | We begin by installing a few Debian packages from stable:@ | 1259 | We begin by installing a few Debian packages from stable: |
1260 | |||
1229 | @example | 1261 | @example |
1230 | # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \ | 1262 | # apt-get install gcc make python-zbar libltdl-dev libsqlite3-dev \ |
1231 | libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev texlive \ | 1263 | libunistring-dev libopus-dev libpulse-dev openssl libglpk-dev texlive \ |
1232 | libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev libbz2-dev \ | 1264 | libidn11-dev libmysqlclient-dev libpq-dev libarchive-dev libbz2-dev \ |
1233 | libflac-dev libgif-dev libglib2.0-dev libgtk-3-dev libmpeg2-4-dev \ | 1265 | libflac-dev libgif-dev libglib2.0-dev libgtk-3-dev libmpeg2-4-dev \ |
1234 | libtidy-dev libvorbis-dev libogg-dev zlib1g-dev g++ gettext libgsf-1-dev \ | 1266 | libtidy-dev libvorbis-dev libogg-dev zlib1g-dev g++ gettext \ |
1235 | libunbound-dev libqrencode-dev libgladeui-dev nasm texlive-latex-extra \ | 1267 | libgsf-1-dev libunbound-dev libqrencode-dev libgladeui-dev nasm \ |
1236 | libunique-3.0-dev gawk miniupnpc libfuse-dev libbluetooth-dev \ | 1268 | texlive-latex-extra libunique-3.0-dev gawk miniupnpc libfuse-dev \ |
1237 | gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ | 1269 | libbluetooth-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ |
1238 | libgstreamer-plugins-base1.0-dev nettle-dev libextractor-dev libgcrypt20-dev \ | 1270 | libgstreamer-plugins-base1.0-dev nettle-dev libextractor-dev \ |
1239 | libmicrohttpd-dev | 1271 | libgcrypt20-dev libmicrohttpd-dev |
1240 | @end example | 1272 | @end example |
1241 | 1273 | ||
1242 | @node Installing Dependencies from Source2 | 1274 | @node Installing Dependencies from Source2 |
1243 | @subsection Installing Dependencies from Source2 | 1275 | @subsection Installing Dependencies from Source2 |
1244 | 1276 | ||
1245 | Yes, we said we start with a Debian 8 "stable" system, but because Debian | 1277 | Yes, we said we start with a Debian 8 "stable" system, but because Debian |
1246 | linked GnuTLS without support for DANE, we need to compile a few things, in | 1278 | linked GnuTLS without support for DANE, we need to compile a few things, |
1247 | addition to GNUnet, still by hand. Yes, you can run GNUnet using the respective | 1279 | in addition to GNUnet, still by hand. Yes, you can run GNUnet using the |
1248 | Debian packages, but then you will not get DANE support. | 1280 | respective Debian packages, but then you will not get DANE support. |
1249 | 1281 | ||
1250 | Next, we need to install a few dependencies from source. You might want to do | 1282 | Next, we need to install a few dependencies from source. You might want |
1251 | this as a "normal" user and only run the @code{make install} steps as root | 1283 | to do this as a "normal" user and only run the @code{make install} steps |
1252 | (hence the @code{sudo} in the commands below). Also, you do this from any | 1284 | as root (hence the @code{sudo} in the commands below). Also, you do this |
1253 | directory. We begin by downloading all dependencies, then extracting the | 1285 | from any directory. We begin by downloading all dependencies, then |
1254 | sources, and finally compiling and installing the libraries:@ | 1286 | extracting the sources, and finally compiling and installing the |
1255 | 1287 | libraries: | |
1256 | @code{@ | 1288 | |
1257 | $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz@ | 1289 | @example |
1258 | $ wget https://gnunet.org/sites/default/files/gnurl-7.40.0.tar.bz2@ | 1290 | $ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz |
1259 | $ tar xvf gnutls-3.3.12.tar.xz@ | 1291 | $ wget https://gnunet.org/sites/default/files/gnurl-7.40.0.tar.bz2 |
1260 | $ tar xvf gnurl-7.40.0.tar.bz2@ | 1292 | $ tar xvf gnutls-3.3.12.tar.xz |
1261 | $ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd ..@ | 1293 | $ tar xvf gnurl-7.40.0.tar.bz2 |
1262 | $ cd gnurl-7.40.0@ | 1294 | $ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd .. |
1263 | $ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \ | 1295 | $ cd gnurl-7.40.0 |
1264 | --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \ | 1296 | $ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \ |
1265 | --without-nss --without-cyassl --without-polarssl --without-ssl \ | 1297 | --without-libmetalink --without-winidn --without-librtmp \ |
1266 | --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \ | 1298 | --without-nghttp2 --without-nss --without-cyassl --without-polarssl \ |
1267 | --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \ | 1299 | --without-ssl --without-winssl --without-darwinssl --disable-sspi \ |
1268 | --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \ | 1300 | --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \ |
1269 | --disable-ftp --disable-smb | 1301 | --disable-telnet --disable-tftp --disable-pop3 --disable-imap \ |
1270 | $ make ; sudo make install; cd ..@ | 1302 | --disable-smtp --disable-gopher --disable-file --disable-ftp \ |
1271 | } | 1303 | --disable-smb |
1304 | $ make ; sudo make install; cd .. | ||
1305 | @end example | ||
1272 | 1306 | ||
1273 | @node Installing GNUnet from Source2 | 1307 | @node Installing GNUnet from Source2 |
1274 | @subsection Installing GNUnet from Source2 | 1308 | @subsection Installing GNUnet from Source2 |
@@ -1279,25 +1313,27 @@ here. | |||
1279 | @node But wait (again) there is more! | 1313 | @node But wait (again) there is more! |
1280 | @subsection But wait (again) there is more! | 1314 | @subsection But wait (again) there is more! |
1281 | 1315 | ||
1282 | So far, we installed all of the packages and dependencies required to ensure | 1316 | So far, we installed all of the packages and dependencies required to |
1283 | that all of GNUnet would be built. However, while for example the plugins to | 1317 | ensure that all of GNUnet would be built. However, while for example the |
1284 | interact with the MySQL or Postgres databases have been created, we did not | 1318 | plugins to interact with the MySQL or Postgres databases have been |
1285 | actually install or configure those databases. Thus, you will need to install | 1319 | created, we did not actually install or configure those databases. |
1286 | and configure those databases or stick with the default Sqlite database. Sqlite | 1320 | Thus, you will need to install and configure those databases or stick |
1287 | is usually fine for most applications, but MySQL can offer better performance | 1321 | with the default Sqlite database. Sqlite is usually fine for most |
1288 | and Postgres better resillience. | 1322 | applications, but MySQL can offer better performance and Postgres better |
1323 | resillience. | ||
1289 | 1324 | ||
1290 | @node Outdated build instructions for previous revisions | 1325 | @node Outdated build instructions for previous revisions |
1291 | @section Outdated build instructions for previous revisions | 1326 | @section Outdated build instructions for previous revisions |
1292 | 1327 | ||
1293 | This chapter contains a collection of outdated, older installation guides. They | 1328 | This chapter contains a collection of outdated, older installation guides. |
1294 | are mostly intended to serve as a starting point for writing up-to-date | 1329 | They are mostly intended to serve as a starting point for writing |
1295 | instructions and should not be expected to work for GNUnet 0.10.x. | 1330 | up-to-date instructions and should not be expected to work for |
1331 | GNUnet 0.10.x. | ||
1296 | A set of older installation instructions can also be found in the | 1332 | A set of older installation instructions can also be found in the |
1297 | @file{doc/outdated-and-old-installation-instructions.txt} in the source | 1333 | file @file{doc/outdated-and-old-installation-instructions.txt} in the |
1298 | of GNUnet. This file covers old instructions which no longer receive | 1334 | source of GNUnet. |
1299 | security updates or any kind of support. | 1335 | This file covers old instructions which no longer receive security |
1300 | 1336 | updates or any kind of support. | |
1301 | 1337 | ||
1302 | @menu | 1338 | @menu |
1303 | * Installing GNUnet 0.10.1 on Ubuntu 14.04:: | 1339 | * Installing GNUnet 0.10.1 on Ubuntu 14.04:: |
@@ -1321,90 +1357,125 @@ $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ | |||
1321 | 1357 | ||
1322 | Choose one or more database backends@ | 1358 | Choose one or more database backends@ |
1323 | SQLite3@ | 1359 | SQLite3@ |
1324 | @code{@ | 1360 | |
1361 | @example | ||
1325 | $ sudo apt-get install libsqlite3-dev@ | 1362 | $ sudo apt-get install libsqlite3-dev@ |
1326 | }@ | 1363 | @end example |
1364 | |||
1327 | MySQL@ | 1365 | MySQL@ |
1328 | @code{@ | 1366 | |
1329 | $ sudo apt-get install libmysqlclient-dev@ | 1367 | @example |
1330 | }@ | 1368 | $ sudo apt-get install libmysqlclient-dev@ |
1369 | @end example | ||
1370 | |||
1331 | PostgreSQL@ | 1371 | PostgreSQL@ |
1332 | @code{@ | 1372 | |
1373 | @example | ||
1333 | $ sudo apt-get install libpq-dev postgresql@ | 1374 | $ sudo apt-get install libpq-dev postgresql@ |
1334 | } | 1375 | @end example |
1335 | 1376 | ||
1336 | Install the optional dependencies for gnunet-conversation:@ | 1377 | Install the optional dependencies for gnunet-conversation:@ |
1337 | @code{@ | 1378 | |
1379 | @example | ||
1338 | $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev@ | 1380 | $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev@ |
1339 | } | 1381 | @end example |
1340 | 1382 | ||
1341 | Install the libgrypt 1.6:@ | 1383 | Install the libgcrypt 1.6: |
1342 | For Ubuntu 14.04:@ | 1384 | |
1343 | @code{$ sudo apt-get install libgcrypt20-dev}@ | 1385 | @itemize @bullet |
1344 | For Ubuntu older 14.04:@ | 1386 | @item For Ubuntu 14.04: |
1345 | @code{$ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2@ | 1387 | |
1346 | $ tar xf libgcrypt-1.6.1.tar.bz2@ | 1388 | @example |
1347 | $ cd libgcrypt-1.6.1@ | 1389 | $ sudo apt-get install libgcrypt20-dev |
1348 | $ ./configure@ | 1390 | @end example |
1349 | $ sudo make install@ | 1391 | |
1350 | $ cd ..} | 1392 | @item For Ubuntu older 14.04: |
1393 | |||
1394 | @example | ||
1395 | wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2 | ||
1396 | $ tar xf libgcrypt-1.6.1.tar.bz2 | ||
1397 | $ cd libgcrypt-1.6.1 | ||
1398 | $ ./configure | ||
1399 | $ sudo make install | ||
1400 | $ cd .. | ||
1401 | @end example | ||
1402 | @end itemize | ||
1351 | 1403 | ||
1352 | Install libgnurl@ | 1404 | Install libgnurl@ |
1405 | |||
1353 | @example | 1406 | @example |
1354 | $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2@ | 1407 | $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2 |
1355 | $ tar xf gnurl-7.35.0.tar.bz2@ | 1408 | $ tar xf gnurl-7.35.0.tar.bz2 |
1356 | $ cd gnurl-7.35.0@ | 1409 | $ cd gnurl-7.35.0 |
1357 | $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \ | 1410 | $ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \ |
1358 | --without-libmetalink --without-winidn --without-librtmp --without-nghttp2 \ | 1411 | --without-libmetalink --without-winidn --without-librtmp |
1359 | --without-nss --without-cyassl --without-polarssl --without-ssl \ | 1412 | --without-nghttp2 --without-nss --without-cyassl --without-polarssl \ |
1360 | --without-winssl --without-darwinssl --disable-sspi --disable-ntlm-wb \ | 1413 | --without-ssl --without-winssl --without-darwinssl --disable-sspi \ |
1361 | --disable-ldap --disable-rtsp --disable-dict --disable-telnet --disable-tftp \ | 1414 | --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \ |
1362 | --disable-pop3 --disable-imap --disable-smtp --disable-gopher --disable-file \ | 1415 | --disable-telnet --disable-tftp --disable-pop3 --disable-imap \ |
1363 | --disable-ftp@ | 1416 | --disable-smtp --disable-gopher --disable-file --disable-ftp |
1364 | $ sudo make install@ | 1417 | $ sudo make install@ |
1365 | $ cd ..@ | 1418 | $ cd ..@ |
1366 | @end example | 1419 | @end example |
1367 | 1420 | ||
1368 | Install GNUnet@ | 1421 | Install GNUnet@ |
1369 | @code{@ | 1422 | |
1370 | $ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz@ | 1423 | @example |
1371 | $ tar xf gnunet-0.10.1.tar.gz@ | 1424 | $ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz |
1372 | $ cd gnunet-0.10.1@ | 1425 | $ tar xf gnunet-0.10.1.tar.gz |
1373 | } | 1426 | $ cd gnunet-0.10.1 |
1427 | @end example | ||
1374 | 1428 | ||
1375 | If you want to: | 1429 | If you want to: |
1430 | |||
1376 | @itemize @bullet | 1431 | @itemize @bullet |
1377 | 1432 | ||
1378 | @item | 1433 | @item |
1379 | Install to a different directory:@ | 1434 | Install to a different directory: |
1380 | --prefix=PREFIX | 1435 | |
1436 | @example | ||
1437 | --prefix=PREFIX | ||
1438 | @end example | ||
1381 | 1439 | ||
1382 | @item | 1440 | @item |
1383 | Have sudo permission, but do not want to compile as root:@ | 1441 | Have sudo permission, but do not want to compile as root: |
1384 | --with-sudo | 1442 | |
1443 | @example | ||
1444 | --with-sudo | ||
1445 | @end example | ||
1385 | 1446 | ||
1386 | @item | 1447 | @item |
1387 | Want debug message enabled:@ | 1448 | Want debug message enabled: |
1388 | -- enable-logging=verbose | 1449 | |
1450 | @example | ||
1451 | --enable-logging=verbose | ||
1452 | @end example | ||
1453 | |||
1389 | @end itemize | 1454 | @end itemize |
1390 | 1455 | ||
1391 | @code{@ | 1456 | @example |
1392 | $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose]@ | 1457 | $ ./configure [ --with-sudo | --prefix=PREFIX | --enable-logging=verbose] |
1393 | $ make; sudo make install@ | 1458 | $ make; sudo make install |
1394 | } | 1459 | @end example |
1460 | |||
1461 | After installing it, you need to create an empty configuration file: | ||
1395 | 1462 | ||
1396 | After installing it, you need to create an empty configuration file:@ | 1463 | @example |
1397 | @code{touch ~/.config/gnunet.conf} | 1464 | touch ~/.config/gnunet.conf |
1465 | @end example | ||
1398 | 1466 | ||
1399 | And finally you can start GNUnet with@ | 1467 | And finally you can start GNUnet with |
1400 | @code{$ gnunet-arm -s} | 1468 | |
1469 | @example | ||
1470 | $ gnunet-arm -s | ||
1471 | @end example | ||
1401 | 1472 | ||
1402 | @node Building GLPK for MinGW | 1473 | @node Building GLPK for MinGW |
1403 | @subsection Building GLPK for MinGW | 1474 | @subsection Building GLPK for MinGW |
1404 | 1475 | ||
1405 | GNUnet now requires the GNU Linear Programming Kit (GLPK). Since there's is no | 1476 | GNUnet now requires the GNU Linear Programming Kit (GLPK). |
1406 | package you can install with @code{mingw-get} you have to compile it from | 1477 | Since there's is no package you can install with @code{mingw-get} you |
1407 | source: | 1478 | have to compile it from source: |
1408 | 1479 | ||
1409 | @itemize @bullet | 1480 | @itemize @bullet |
1410 | 1481 | ||
@@ -1412,17 +1483,23 @@ source: | |||
1412 | Download the latest version from http://ftp.gnu.org/gnu/glpk/ | 1483 | Download the latest version from http://ftp.gnu.org/gnu/glpk/ |
1413 | 1484 | ||
1414 | @item | 1485 | @item |
1415 | Unzip it using your favourite unzipper@ | 1486 | Unzip it using your favourite unzipper In the MSYS shell: |
1416 | In the MSYS shell: | ||
1417 | 1487 | ||
1418 | @item | 1488 | @item |
1419 | change to the respective directory | 1489 | change to the respective directory |
1420 | 1490 | ||
1421 | @item | 1491 | @item |
1422 | @code{./configure '--build=i686-pc-mingw32'} | 1492 | |
1493 | @example | ||
1494 | ./configure '--build=i686-pc-mingw32' | ||
1495 | @end example | ||
1423 | 1496 | ||
1424 | @item | 1497 | @item |
1425 | run @code{make install check } | 1498 | run |
1499 | |||
1500 | @example | ||
1501 | make install check | ||
1502 | @end example | ||
1426 | 1503 | ||
1427 | MinGW does not automatically detect the correct buildtype so you have to | 1504 | MinGW does not automatically detect the correct buildtype so you have to |
1428 | specify it manually | 1505 | specify it manually |
@@ -1436,104 +1513,115 @@ After installing GNUnet you can continue installing the GNUnet GUI tools: | |||
1436 | 1513 | ||
1437 | First, install the required dependencies: | 1514 | First, install the required dependencies: |
1438 | 1515 | ||
1439 | @code{@ | 1516 | @example |
1440 | $ sudo apt-get install libgladeui-dev libqrencode-dev@ | 1517 | $ sudo apt-get install libgladeui-dev libqrencode-dev |
1441 | } | 1518 | @end example |
1442 | 1519 | ||
1443 | Please ensure that the GNUnet shared libraries can be found by the linker. If | 1520 | Please ensure that the GNUnet shared libraries can be found by the linker. |
1444 | you installed GNUnet libraries in a non standard path (say | 1521 | If you installed GNUnet libraries in a non standard path (say |
1445 | GNUNET_PREFIX=/usr/local/lib/), you can | 1522 | GNUNET_PREFIX=/usr/local/lib/), you can |
1446 | @itemize @bullet | ||
1447 | 1523 | ||
1524 | @itemize @bullet | ||
1448 | 1525 | ||
1449 | @item | 1526 | @item |
1450 | set the environmental variable permanently to@ | 1527 | set the environmental variable permanently to |
1451 | @code{LD_LIBRARY_PATH=$GNUNET_PREFIX} | 1528 | |
1529 | @example | ||
1530 | LD_LIBRARY_PATH=$GNUNET_PREFIX | ||
1531 | @end example | ||
1452 | 1532 | ||
1453 | @item | 1533 | @item |
1454 | or add @code{$GNUNET_PREFIX} to @code{/etc/ld.so.conf} | 1534 | or add @code{$GNUNET_PREFIX} to @file{/etc/ld.so.conf} |
1535 | |||
1455 | @end itemize | 1536 | @end itemize |
1456 | 1537 | ||
1457 | 1538 | ||
1458 | Now you can checkout and compile the GNUnet GUI tools@ | 1539 | Now you can checkout and compile the GNUnet GUI tools@ |
1459 | @code{@ | 1540 | |
1460 | $ svn co https://gnunet.org/svn/gnunet-gtk@ | 1541 | @example |
1461 | $ cd gnunet-gtk@ | 1542 | $ git clone https://gnunet.org/git/gnunet-gtk |
1462 | $ ./bootstrap@ | 1543 | $ cd gnunet-gtk |
1463 | $ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/..@ | 1544 | $ ./bootstrap |
1464 | $ make install@ | 1545 | $ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/.. |
1465 | } | 1546 | $ make install |
1547 | @end example | ||
1466 | 1548 | ||
1467 | @node Installation with gnunet-update | 1549 | @node Installation with gnunet-update |
1468 | @subsection Installation with gnunet-update | 1550 | @subsection Installation with gnunet-update |
1469 | 1551 | ||
1470 | gnunet-update project is an effort to introduce updates to GNUnet | 1552 | gnunet-update project is an effort to introduce updates to GNUnet |
1471 | installations. An interesting to-be-implemented-feature of gnunet-update is | 1553 | installations. An interesting to-be-implemented-feature of gnunet-update |
1472 | that these updates are propagated through GNUnet's peer-to-peer network. More | 1554 | is that these updates are propagated through GNUnet's peer-to-peer |
1473 | information about gnunet-update can be found at | 1555 | network. More information about gnunet-update can be found at |
1474 | https://gnunet.org/svn/gnunet-update/README. | 1556 | @c FIXME: Use correct cgit URL |
1557 | @uref{https://gnunet.org/git/gnunet-update/README}. | ||
1475 | 1558 | ||
1476 | While the project is still under development, we have implemented the following | 1559 | While the project is still under development, we have implemented the |
1477 | features which we believe may be helpful for users and we would like them to be | 1560 | following features which we believe may be helpful for users and we |
1478 | tested: | 1561 | would like them to be tested: |
1479 | 1562 | ||
1480 | @itemize @bullet | 1563 | @itemize @bullet |
1481 | 1564 | ||
1482 | @item | 1565 | @item |
1483 | Packaging GNUnet installation along with its run-time dependencies into update | 1566 | Packaging GNUnet installation along with its run-time dependencies into |
1484 | packages | 1567 | update packages |
1485 | 1568 | ||
1486 | @item | 1569 | @item |
1487 | Installing update packages into compatible hosts | 1570 | Installing update packages into compatible hosts |
1488 | 1571 | ||
1489 | @item | 1572 | @item |
1490 | Updating an existing installation (which had been installed by gnunet-update) | 1573 | Updating an existing installation (which had been installed by |
1491 | to a newer one | 1574 | gnunet-update) to a newer one |
1575 | |||
1492 | @end itemize | 1576 | @end itemize |
1493 | 1577 | ||
1494 | The above said features of gnunet-update are currently available for testing on | 1578 | The above said features of gnunet-update are currently available for |
1495 | GNU/Linux systems. | 1579 | testing on GNU/Linux systems. |
1496 | 1580 | ||
1497 | The following is a guide to help you get started with gnunet-update. It shows | 1581 | The following is a guide to help you get started with gnunet-update. |
1498 | you how to install the testing binary packages of GNUnet 0.9.1 we have at | 1582 | It shows you how to install the testing binary packages of GNUnet |
1499 | https://gnunet.org/install/ | 1583 | 0.9.1 we have at @uref{https://gnunet.org/install/}. |
1500 | 1584 | ||
1501 | gnunet-update needs the following: | 1585 | gnunet-update needs the following dependencies: |
1502 | 1586 | ||
1503 | @itemize @bullet | 1587 | @itemize @bullet |
1504 | @item | 1588 | @item |
1505 | python ( 2.6 or above) | 1589 | python @geq{} 2.6 |
1506 | 1590 | ||
1507 | @item | 1591 | @item |
1508 | gnupg | 1592 | gnupg |
1509 | 1593 | ||
1510 | @item | 1594 | @item |
1511 | python-gpgme | 1595 | python-gpgme |
1512 | @end itemize | 1596 | @end itemize |
1513 | 1597 | ||
1514 | 1598 | ||
1515 | Checkout gnunet-update:@ | 1599 | Checkout gnunet-update: |
1516 | @code{@ | 1600 | |
1517 | $ svn checkout -r24905 https://gnunet.org/svn/gnunet-update@ | 1601 | @c FIXME: git! |
1518 | } | 1602 | @example |
1603 | $ svn checkout -r24905 https://gnunet.org/svn/gnunet-update@ | ||
1604 | @end example | ||
1519 | 1605 | ||
1520 | For security reasons, all packages released for gnunet-update from us are | 1606 | For security reasons, all packages released for gnunet-update from us are |
1521 | signed with the key at https://gnunet.org/install/key.txt You would need to | 1607 | signed with the key at @uref{https://gnunet.org/install/key.txt}. |
1522 | import this key into your gpg key ring. gnunet-update uses this key to verify | 1608 | You would need to import this key into your gpg key ring. |
1523 | the integrity of the packages it installs@ | 1609 | gnunet-update uses this key to verify the integrity of the packages it |
1524 | @code{@ | 1610 | installs: |
1525 | $ gpg --recv-keys 7C613D78@ | ||
1526 | } | ||
1527 | 1611 | ||
1528 | Download the packages relevant to your architecture (currently I have access to | 1612 | @example |
1529 | GNU/Linux machines on x86_64 and i686, so only two for now, hopefully more | 1613 | $ gpg --recv-keys 7C613D78@ |
1530 | later) from https://gnunet.org/install/. | 1614 | @end example |
1615 | |||
1616 | Download the packages relevant to your architecture (currently I have | ||
1617 | access to GNU/Linux machines on x86_64 and i686, so only two for now, | ||
1618 | hopefully more later) from https://gnunet.org/install/. | ||
1531 | 1619 | ||
1532 | To install the downloaded package into the directory /foo: | 1620 | To install the downloaded package into the directory /foo: |
1533 | 1621 | ||
1534 | @code{@ | 1622 | @example |
1535 | gnunet-update/bin/gnunet-update install downloaded/package /foo@ | 1623 | gnunet-update/bin/gnunet-update install downloaded/package /foo |
1536 | } | 1624 | @end example |
1537 | 1625 | ||
1538 | The installer reports the directories into which shared libraries and | 1626 | The installer reports the directories into which shared libraries and |
1539 | dependencies have been installed. You may need to add the reported shared | 1627 | dependencies have been installed. You may need to add the reported shared |
@@ -1546,20 +1634,19 @@ Please report bugs at https://gnunet.org/bugs/ under the project | |||
1546 | @node Instructions for Microsoft Windows Platforms (Old) | 1634 | @node Instructions for Microsoft Windows Platforms (Old) |
1547 | @subsection Instructions for Microsoft Windows Platforms (Old) | 1635 | @subsection Instructions for Microsoft Windows Platforms (Old) |
1548 | 1636 | ||
1549 | This document is a DEPRECATED installation guide for gnunet on windows. It will | 1637 | This document is a @b{DEPRECATED} installation guide for gnunet on |
1550 | not work for recent gnunet versions, but maybe it will be of some use if | 1638 | Windows. |
1551 | problems arise. | 1639 | It will not work for recent gnunet versions, but maybe it will be of |
1552 | 1640 | some use if problems arise. | |
1553 | The Windows build uses a UNIX emulator for Windows, | ||
1554 | @uref{http://www.mingw.org/, MinGW}, to build the executable modules. These | ||
1555 | modules run natively on Windows and do not require additional emulation | ||
1556 | software besides the usual dependencies. | ||
1557 | |||
1558 | GNUnet development is mostly done under Linux and especially SVN checkouts may | ||
1559 | not build out of the box. We regret any inconvenience, and if you have | ||
1560 | problems, please report them. | ||
1561 | 1641 | ||
1642 | The Windows build uses a UNIX emulator for Windows, | ||
1643 | @uref{http://www.mingw.org/, MinGW}, to build the executable modules. | ||
1644 | These modules run natively on Windows and do not require additional | ||
1645 | emulation software besides the usual dependencies. | ||
1562 | 1646 | ||
1647 | GNUnet development is mostly done under Linux and especially SVN | ||
1648 | checkouts may not build out of the box. | ||
1649 | We regret any inconvenience, and if you have problems, please report them. | ||
1563 | 1650 | ||
1564 | @menu | 1651 | @menu |
1565 | * Hardware and OS requirements:: | 1652 | * Hardware and OS requirements:: |
@@ -1595,57 +1682,33 @@ Windows 2000 or Windows XP are recommended | |||
1595 | @item | 1682 | @item |
1596 | @strong{Compression software}@ | 1683 | @strong{Compression software}@ |
1597 | @ | 1684 | @ |
1598 | The software packages GNUnet depends on are usually compressed using UNIX | 1685 | The software packages GNUnet depends on are usually compressed using UNIX |
1599 | tools like tar, gzip and bzip2.@ If you do not already have an utility that is | 1686 | tools like tar, gzip and bzip2. |
1600 | able to extract such archives, get @uref{http://www.7-zip.org/, 7-Zip}. | 1687 | If you do not already have an utility that is able to extract such |
1688 | archives, get @uref{http://www.7-zip.org/, 7-Zip}. | ||
1601 | 1689 | ||
1602 | @item | 1690 | @item |
1603 | @strong{UNIX environment}@ | 1691 | @strong{UNIX environment}@ |
1604 | @ | 1692 | @ |
1605 | The MinGW project provides the compiler toolchain that is used to build | 1693 | The MinGW project provides the compiler toolchain that is used to build |
1606 | GNUnet.@ Get the following packages from | 1694 | GNUnet.@ Get the following packages from |
1607 | @uref{http://sourceforge.net/projects/mingw/files/, the MinGW project}: | 1695 | @uref{http://sourceforge.net/projects/mingw/files/, the MinGW project}: |
1608 | @itemize @bullet | ||
1609 | |||
1610 | |||
1611 | @item | ||
1612 | GCC core | ||
1613 | |||
1614 | @item | ||
1615 | GCC g++ | ||
1616 | |||
1617 | @item | ||
1618 | MSYS | ||
1619 | |||
1620 | @item | ||
1621 | MSYS Developer Tool Kit (msysDTK) | ||
1622 | |||
1623 | @item | ||
1624 | MSYS Developer Tool Kit - msys-autoconf (bin) | ||
1625 | 1696 | ||
1626 | @item | 1697 | @itemize @bullet |
1627 | MSYS Developer Tool Kit - msys-automake (bin) | ||
1628 | |||
1629 | @item | ||
1630 | MinGW Runtime | ||
1631 | |||
1632 | @item | ||
1633 | MinGW Utilities | ||
1634 | |||
1635 | @item | ||
1636 | Windows API | ||
1637 | |||
1638 | @item | ||
1639 | Binutils | ||
1640 | |||
1641 | @item | ||
1642 | make | ||
1643 | |||
1644 | @item | ||
1645 | pdcurses | ||
1646 | 1698 | ||
1647 | @item | 1699 | @item GCC core |
1648 | GDB (snapshot) | 1700 | @item GCC g++ |
1701 | @item MSYS | ||
1702 | @item MSYS Developer Tool Kit (msysDTK) | ||
1703 | @item MSYS Developer Tool Kit - msys-autoconf (bin) | ||
1704 | @item MSYS Developer Tool Kit - msys-automake (bin) | ||
1705 | @item MinGW Runtime | ||
1706 | @item MinGW Utilities | ||
1707 | @item Windows API | ||
1708 | @item Binutils | ||
1709 | @item make | ||
1710 | @item pdcurses | ||
1711 | @item GDB (snapshot) | ||
1649 | @end itemize | 1712 | @end itemize |
1650 | 1713 | ||
1651 | @itemize @bullet | 1714 | @itemize @bullet |
@@ -1653,11 +1716,12 @@ GDB (snapshot) | |||
1653 | 1716 | ||
1654 | @item | 1717 | @item |
1655 | Install MSYS (to c:\mingw, for example.)@ | 1718 | Install MSYS (to c:\mingw, for example.)@ |
1656 | Do @strong{not} use spaces in the pathname (c:\program files\mingw). | 1719 | Do @strong{not} use spaces in the pathname. |
1720 | For example, avoid a location such as @file{c:\program files\mingw}. | ||
1657 | 1721 | ||
1658 | @item | 1722 | @item |
1659 | Install MinGW runtime, utilities and GCC to a subdirectory (to c:\mingw\mingw, | 1723 | Install MinGW runtime, utilities and GCC to a subdirectory |
1660 | for example) | 1724 | (to c:\mingw\mingw, for example) |
1661 | 1725 | ||
1662 | @item | 1726 | @item |
1663 | Install the Development Kit to the MSYS directory (c:\mingw) | 1727 | Install the Development Kit to the MSYS directory (c:\mingw) |
@@ -1669,22 +1733,24 @@ Create a batch file bash.bat in your MSYS directory with the files:@ | |||
1669 | bin\sh.exe --login | 1733 | bin\sh.exe --login |
1670 | @end example | 1734 | @end example |
1671 | 1735 | ||
1672 | 1736 | This batch file opens a shell which is used to invoke the build | |
1673 | This batch file opens a shell which is used to invoke the build processes..@ | 1737 | processes. |
1674 | MinGW's standard shell (msys.bat) is not suitable because it opens a separate | 1738 | MinGW's standard shell (msys.bat) is not suitable because it opens a |
1675 | console window@ On Vista, bash.bat needs to be run as administrator. | 1739 | separate console window. |
1740 | On Vista, bash.bat needs to be run as administrator. | ||
1676 | 1741 | ||
1677 | @item | 1742 | @item |
1678 | Start bash.sh and rename (c:\mingw\mingw\)lib\libstdc++.la to avoid problems:@ | 1743 | Start bash.sh and rename (c:\mingw\mingw\)lib\libstdc++.la to avoid |
1744 | problems: | ||
1679 | 1745 | ||
1680 | @example | 1746 | @example |
1681 | mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken | 1747 | mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken |
1682 | @end example | 1748 | @end example |
1683 | 1749 | ||
1684 | |||
1685 | @item | 1750 | @item |
1686 | Unpack the Windows API to the MinGW directory (c:\mingw\mingw\) and remove the | 1751 | Unpack the Windows API to the MinGW directory (c:\mingw\mingw\) and |
1687 | declaration of DATADIR from (c:\mingw\mingw\)include\objidl.h (lines 55-58) | 1752 | remove the declaration of DATADIR from |
1753 | (c:\mingw\mingw\)include\objidl.h (lines 55-58) | ||
1688 | 1754 | ||
1689 | @item | 1755 | @item |
1690 | Unpack autoconf, automake to the MSYS directory (c:\mingw) | 1756 | Unpack autoconf, automake to the MSYS directory (c:\mingw) |
@@ -1734,7 +1800,8 @@ s-win32/dll-latest/include/, include/} to the @file{include} directory | |||
1734 | @strong{GNU MP@ | 1800 | @strong{GNU MP@ |
1735 | }@ | 1801 | }@ |
1736 | @ | 1802 | @ |
1737 | GNUnet uses the GNU Multiple Precision library for special cryptographic operations.@ | 1803 | GNUnet uses the GNU Multiple Precision library for special cryptographic |
1804 | operations.@ | ||
1738 | @ | 1805 | @ |
1739 | Get the GMP binary package from the | 1806 | Get the GMP binary package from the |
1740 | @uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and | 1807 | @uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and |
@@ -1743,23 +1810,25 @@ unpack it to the MinGW directory (c:\mingw\mingw) | |||
1743 | @item | 1810 | @item |
1744 | @strong{GNU Gettext}@ | 1811 | @strong{GNU Gettext}@ |
1745 | @ | 1812 | @ |
1746 | GNU gettext is used to provide national language support.@ | 1813 | GNU gettext is used to provide national language support.@ |
1747 | @ | 1814 | @ |
1748 | Get the prebuilt package from hereand unpack it to the MinGW directory (c:\mingw\mingw) | 1815 | Get the prebuilt package from hereand unpack it to the MinGW |
1816 | directory (c:\mingw\mingw) | ||
1749 | 1817 | ||
1750 | @item | 1818 | @item |
1751 | @strong{GNU iconv}@ | 1819 | @strong{GNU iconv}@ |
1752 | @ | 1820 | @ |
1753 | GNU Libiconv is used for character encoding conversion.@ | 1821 | GNU Libiconv is used for character encoding conversion.@ |
1754 | @ | 1822 | @ |
1755 | Get the prebuilt package from here and unpack it to the MinGW directory (c:\mingw\mingw) | 1823 | Get the prebuilt package from here and unpack it to the MinGW |
1824 | directory (c:\mingw\mingw) | ||
1756 | 1825 | ||
1757 | @item | 1826 | @item |
1758 | @strong{SQLite}@ | 1827 | @strong{SQLite}@ |
1759 | @ | 1828 | @ |
1760 | GNUnet uses the SQLite database to store data.@ | 1829 | GNUnet uses the SQLite database to store data.@ |
1761 | @ | 1830 | @ |
1762 | Get the prebuilt binary from here and unpack it to your MinGW directory. | 1831 | Get the prebuilt binary from here and unpack it to your MinGW directory. |
1763 | 1832 | ||
1764 | @item @strong{MySQL}@ | 1833 | @item @strong{MySQL}@ |
1765 | As an alternative to SQLite, GNUnet also supports MySQL. | 1834 | As an alternative to SQLite, GNUnet also supports MySQL. |
@@ -1803,32 +1872,33 @@ to your PATH or GNUnet's @file{bin} directory | |||
1803 | @item | 1872 | @item |
1804 | @strong{GTK+}@ | 1873 | @strong{GTK+}@ |
1805 | @ | 1874 | @ |
1806 | gnunet-gtk and libextractor depend on GTK.@ | 1875 | gnunet-gtk and libextractor depend on GTK.@ |
1807 | @ | 1876 | @ |
1808 | Get the the binary and developer packages of atk, glib, gtk, iconv, | 1877 | Get the the binary and developer packages of atk, glib, gtk, iconv, |
1809 | gettext-runtime, pango from | 1878 | gettext-runtime, pango from |
1810 | @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack it to the | 1879 | @uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack it to the |
1811 | MinGW directory (c:\mingw\mingw)@ | 1880 | MinGW directory (c:\mingw\mingw)@ |
1812 | @ | 1881 | @ |
1813 | Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and libpng | 1882 | Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and libpng |
1814 | and unpack them to the MinGW directory (c:\mingw\mingw)@ | 1883 | and unpack them to the MinGW directory (c:\mingw\mingw)@ |
1815 | @ | 1884 | @ |
1816 | Here is an all-in-one package for | 1885 | Here is an all-in-one package for |
1817 | @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies}. | 1886 | @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bu |
1818 | Do not overwrite any existing files! | 1887 | ndle_2.24.10-20120208_win32.zip, gtk+dependencies}. |
1888 | Do not overwrite any existing files! | ||
1819 | 1889 | ||
1820 | @item | 1890 | @item |
1821 | @strong{Glade}@ | 1891 | @strong{Glade}@ |
1822 | @ | 1892 | @ |
1823 | gnunet-gtk and and gnunet-setup were created using this interface builder | 1893 | gnunet-gtk and and gnunet-setup were created using this interface builder |
1824 | 1894 | ||
1825 | @itemize @bullet | 1895 | @itemize @bullet |
1826 | 1896 | ||
1827 | 1897 | ||
1828 | @item | 1898 | @item |
1829 | Get the Glade and libglade (-bin and -devel) packages (without GTK!) from | 1899 | Get the Glade and libglade (-bin and -devel) packages (without GTK!) from |
1830 | @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack it to | 1900 | @uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack it to |
1831 | the MinGW directory (c:\mingw\mingw) | 1901 | the MinGW directory (c:\mingw\mingw) |
1832 | 1902 | ||
1833 | @item | 1903 | @item |
1834 | Get libxml from here and unpack it to the MinGW | 1904 | Get libxml from here and unpack it to the MinGW |
@@ -1842,13 +1912,13 @@ directory (c:\mingw\mingw). | |||
1842 | libextractor requires zLib to decompress some file formats. GNUnet uses it | 1912 | libextractor requires zLib to decompress some file formats. GNUnet uses it |
1843 | to (de)compress meta-data.@ | 1913 | to (de)compress meta-data.@ |
1844 | @ | 1914 | @ |
1845 | Get zLib from here (Signature) and unpack it to the | 1915 | Get zLib from here (Signature) and unpack it to the |
1846 | MinGW directory (c:\mingw\mingw) | 1916 | MinGW directory (c:\mingw\mingw) |
1847 | 1917 | ||
1848 | @item | 1918 | @item |
1849 | @strong{Bzip2}@ | 1919 | @strong{Bzip2}@ |
1850 | @ | 1920 | @ |
1851 | libextractor also requires Bzip2 to decompress some file formats.@ | 1921 | libextractor also requires Bzip2 to decompress some file formats.@ |
1852 | @ | 1922 | @ |
1853 | Get Bzip2 (binary and developer package) from | 1923 | Get Bzip2 (binary and developer package) from |
1854 | @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and | 1924 | @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and |
@@ -1857,40 +1927,44 @@ unpack it to the MinGW directory (c:\mingw\mingw) | |||
1857 | @item | 1927 | @item |
1858 | @strong{Libgcrypt}@ | 1928 | @strong{Libgcrypt}@ |
1859 | @ | 1929 | @ |
1860 | Libgcrypt provides the cryptographic functions used by GNUnet@ | 1930 | Libgcrypt provides the cryptographic functions used by GNUnet@ |
1861 | @ | 1931 | @ |
1862 | Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here}, | 1932 | Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here}, |
1863 | compile and place it in the MinGW directory (c:\mingw\mingw). Currently | 1933 | compile and place it in the MinGW directory (c:\mingw\mingw). Currently |
1864 | you need at least version 1.4.2 to compile GNUnet. | 1934 | you need at least version 1.4.2 to compile GNUnet. |
1865 | 1935 | ||
1866 | @item | 1936 | @item |
1867 | @strong{PlibC}@ | 1937 | @strong{PlibC}@ |
1868 | @ | 1938 | @ |
1869 | PlibC emulates Unix functions under Windows.@ | 1939 | PlibC emulates Unix functions under Windows.@ |
1870 | @ | 1940 | @ |
1871 | Get PlibC from here and unpack it to the MinGW | 1941 | Get PlibC from here and unpack it to the MinGW |
1872 | directory (c:\mingw\mingw) | 1942 | directory (c:\mingw\mingw) |
1873 | 1943 | ||
1874 | @item | 1944 | @item |
1875 | @strong{OGG Vorbis}@ | 1945 | @strong{OGG Vorbis}@ |
1876 | @ | 1946 | @ |
1877 | OGG Vorbis is used to extract meta-data from .ogg files@ | 1947 | OGG Vorbis is used to extract meta-data from .ogg files@ |
1878 | @ | 1948 | @ |
1879 | Get the packages | 1949 | Get the packages |
1880 | @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg} | 1950 | @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, |
1881 | and | 1951 | libogg} |
1882 | @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis} | 1952 | and |
1883 | from the | 1953 | @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, |
1884 | @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build} | 1954 | libvorbis} |
1885 | and unpack them to the MinGW directory (c:\mingw\mingw) | 1955 | from the |
1956 | @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, | ||
1957 | libextractor win32 build} | ||
1958 | and unpack them to the MinGW directory (c:\mingw\mingw) | ||
1886 | 1959 | ||
1887 | @item | 1960 | @item |
1888 | @strong{Exiv2}@ | 1961 | @strong{Exiv2}@ |
1889 | @ | 1962 | @ |
1890 | (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data@ | 1963 | (lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data@ |
1891 | @ | 1964 | @ |
1892 | Download | 1965 | Download |
1893 | @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2} | 1966 | @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, |
1967 | Exiv2} | ||
1894 | and unpack it to the MSYS directory (c:\mingw) | 1968 | and unpack it to the MSYS directory (c:\mingw) |
1895 | @end itemize | 1969 | @end itemize |
1896 | 1970 | ||
@@ -1936,7 +2010,8 @@ Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian | |||
1936 | and CentOS 6, but it should work on almost any GNU/Linux distribution. | 2010 | and CentOS 6, but it should work on almost any GNU/Linux distribution. |
1937 | More in-detail information can be found in the handbook. | 2011 | More in-detail information can be found in the handbook. |
1938 | 2012 | ||
1939 | 2013 | Note 2017-10: Currently this section assumes the old SVN repo of GNUnet | |
2014 | which no longer exists. | ||
1940 | 2015 | ||
1941 | @menu | 2016 | @menu |
1942 | * Prerequisites:: | 2017 | * Prerequisites:: |
@@ -1948,8 +2023,11 @@ More in-detail information can be found in the handbook. | |||
1948 | @subsection Prerequisites | 2023 | @subsection Prerequisites |
1949 | 2024 | ||
1950 | Open a terminal and paste this line into it to install all required tools | 2025 | Open a terminal and paste this line into it to install all required tools |
1951 | needed:@ | 2026 | needed: |
1952 | @code{sudo apt-get install python-gpgme subversion} | 2027 | |
2028 | @example | ||
2029 | sudo apt-get install python-gpgme subversion | ||
2030 | @end example | ||
1953 | 2031 | ||
1954 | @node Download & set up gnunet-update | 2032 | @node Download & set up gnunet-update |
1955 | @subsection Download & set up gnunet-update | 2033 | @subsection Download & set up gnunet-update |
@@ -1982,7 +2060,11 @@ sudo ldconfig | |||
1982 | You may need to re-login once after executing these last commands | 2060 | You may need to re-login once after executing these last commands |
1983 | 2061 | ||
1984 | That's it, GNUnet is installed in your home directory now. GNUnet can be | 2062 | That's it, GNUnet is installed in your home directory now. GNUnet can be |
1985 | configured and afterwards started by executing @code{gnunet-arm -s}. | 2063 | configured and afterwards started by executing: |
2064 | |||
2065 | @example | ||
2066 | gnunet-arm -s | ||
2067 | @end example | ||
1986 | 2068 | ||
1987 | @node The graphical configuration interface | 2069 | @node The graphical configuration interface |
1988 | @section The graphical configuration interface | 2070 | @section The graphical configuration interface |
@@ -1991,7 +2073,8 @@ If you also would like to use gnunet-gtk and gnunet-setup (highly | |||
1991 | recommended for beginners), do: | 2073 | recommended for beginners), do: |
1992 | 2074 | ||
1993 | @example | 2075 | @example |
1994 | wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz | 2076 | wget -P /tmp \ |
2077 | https://gnunet.org/install/packs/gnunet-0.9.4-gtk-0.9.4-`uname -m`.tgz | ||
1995 | sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~ | 2078 | sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~ |
1996 | sudo ldconfig | 2079 | sudo ldconfig |
1997 | @end example | 2080 | @end example |
@@ -2192,21 +2275,21 @@ Be aware that these information will be stored in the configuration in | |||
2192 | plain text. | 2275 | plain text. |
2193 | 2276 | ||
2194 | To configure these options directly in the configuration, you can | 2277 | To configure these options directly in the configuration, you can |
2195 | configure the following settings in the | 2278 | configure the following settings in the @code{[hostlist]} |
2196 | @code{[hostlist]} section of the configuration: | 2279 | section of the configuration: |
2197 | 2280 | ||
2198 | @example | 2281 | @example |
2199 | # Type of proxy server,@ | 2282 | # Type of proxy server, |
2200 | # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME@ | 2283 | # Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME |
2201 | # Default: HTTP@ | 2284 | # Default: HTTP |
2202 | # PROXY_TYPE = HTTP | 2285 | # PROXY_TYPE = HTTP |
2203 | 2286 | ||
2204 | # Hostname or IP of proxy server@ | 2287 | # Hostname or IP of proxy server |
2205 | # PROXY =@ | 2288 | # PROXY = |
2206 | # User name for proxy server@ | 2289 | # User name for proxy server |
2207 | # PROXY_USERNAME =@ | 2290 | # PROXY_USERNAME = |
2208 | # User password for proxy server@ | 2291 | # User password for proxy server |
2209 | # PROXY_PASSWORD =@ | 2292 | # PROXY_PASSWORD = |
2210 | @end example | 2293 | @end example |
2211 | 2294 | ||
2212 | @node Configuring your peer to provide a hostlist | 2295 | @node Configuring your peer to provide a hostlist |
@@ -2332,8 +2415,8 @@ that will be running gnunet-arm (so typically "gnunet"): | |||
2332 | 2415 | ||
2333 | @example | 2416 | @example |
2334 | CREATE DATABASE gnunet; | 2417 | CREATE DATABASE gnunet; |
2335 | GRANT select,insert,update,delete,create,alter,drop,create temporary tables | 2418 | GRANT select,insert,update,delete,create,alter,drop,create \ |
2336 | ON gnunet.* TO $USER@@localhost; | 2419 | temporary tables ON gnunet.* TO $USER@@localhost; |
2337 | SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); | 2420 | SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); |
2338 | FLUSH PRIVILEGES; | 2421 | FLUSH PRIVILEGES; |
2339 | @end example | 2422 | @end example |
@@ -2590,18 +2673,18 @@ The configuration section for the transport service itself is quite | |||
2590 | similar to all the other services | 2673 | similar to all the other services |
2591 | 2674 | ||
2592 | @example | 2675 | @example |
2593 | AUTOSTART = YES@ | 2676 | AUTOSTART = YES |
2594 | @@UNIXONLY@@ PORT = 2091@ | 2677 | @@UNIXONLY@@ PORT = 2091 |
2595 | HOSTNAME = localhost@ | 2678 | HOSTNAME = localhost |
2596 | HOME = $SERVICEHOME@ | 2679 | HOME = $SERVICEHOME |
2597 | CONFIG = $DEFAULTCONFIG@ | 2680 | CONFIG = $DEFAULTCONFIG |
2598 | BINARY = gnunet-service-transport@ | 2681 | BINARY = gnunet-service-transport |
2599 | #PREFIX = valgrind@ | 2682 | #PREFIX = valgrind |
2600 | NEIGHBOUR_LIMIT = 50@ | 2683 | NEIGHBOUR_LIMIT = 50 |
2601 | ACCEPT_FROM = 127.0.0.1;@ | 2684 | ACCEPT_FROM = 127.0.0.1; |
2602 | ACCEPT_FROM6 = ::1;@ | 2685 | ACCEPT_FROM6 = ::1; |
2603 | PLUGINS = tcp udp@ | 2686 | PLUGINS = tcp udp |
2604 | UNIXPATH = /tmp/gnunet-service-transport.sock@ | 2687 | UNIXPATH = /tmp/gnunet-service-transport.sock |
2605 | @end example | 2688 | @end example |
2606 | 2689 | ||
2607 | Different are the settings for the plugins to load @code{PLUGINS}. | 2690 | Different are the settings for the plugins to load @code{PLUGINS}. |
@@ -2613,9 +2696,9 @@ A plugin for local only communication with UNIX domain sockets. Used for | |||
2613 | testing and available on unix systems only. Just set the port | 2696 | testing and available on unix systems only. Just set the port |
2614 | 2697 | ||
2615 | @example | 2698 | @example |
2616 | [transport-unix]@ | 2699 | [transport-unix] |
2617 | PORT = 22086@ | 2700 | PORT = 22086 |
2618 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2701 | TESTING_IGNORE_KEYS = ACCEPT_FROM; |
2619 | @end example | 2702 | @end example |
2620 | 2703 | ||
2621 | @item transport-tcp | 2704 | @item transport-tcp |
@@ -2623,13 +2706,13 @@ A plugin for communication with TCP. Set port to 0 for client mode with | |||
2623 | outbound only connections | 2706 | outbound only connections |
2624 | 2707 | ||
2625 | @example | 2708 | @example |
2626 | [transport-tcp]@ | 2709 | [transport-tcp] |
2627 | # Use 0 to ONLY advertise as a peer behind NAT (no port binding)@ | 2710 | # Use 0 to ONLY advertise as a peer behind NAT (no port binding) |
2628 | PORT = 2086@ | 2711 | PORT = 2086 |
2629 | ADVERTISED_PORT = 2086@ | 2712 | ADVERTISED_PORT = 2086 |
2630 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2713 | TESTING_IGNORE_KEYS = ACCEPT_FROM; |
2631 | # Maximum number of open TCP connections allowed@ | 2714 | # Maximum number of open TCP connections allowed |
2632 | MAX_CONNECTIONS = 128@ | 2715 | MAX_CONNECTIONS = 128 |
2633 | @end example | 2716 | @end example |
2634 | 2717 | ||
2635 | @item transport-udp | 2718 | @item transport-udp |
@@ -2637,12 +2720,12 @@ A plugin for communication with UDP. Supports peer discovery using | |||
2637 | broadcasts. | 2720 | broadcasts. |
2638 | 2721 | ||
2639 | @example | 2722 | @example |
2640 | [transport-udp]@ | 2723 | [transport-udp] |
2641 | PORT = 2086@ | 2724 | PORT = 2086 |
2642 | BROADCAST = YES@ | 2725 | BROADCAST = YES |
2643 | BROADCAST_INTERVAL = 30 s@ | 2726 | BROADCAST_INTERVAL = 30 s |
2644 | MAX_BPS = 1000000@ | 2727 | MAX_BPS = 1000000 |
2645 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2728 | TESTING_IGNORE_KEYS = ACCEPT_FROM; |
2646 | @end example | 2729 | @end example |
2647 | 2730 | ||
2648 | @item transport-http | 2731 | @item transport-http |
@@ -2652,15 +2735,15 @@ client. The client plugin just takes the maximum number of connections as | |||
2652 | an argument. | 2735 | an argument. |
2653 | 2736 | ||
2654 | @example | 2737 | @example |
2655 | [transport-http_client]@ | 2738 | [transport-http_client] |
2656 | MAX_CONNECTIONS = 128@ | 2739 | MAX_CONNECTIONS = 128 |
2657 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2740 | TESTING_IGNORE_KEYS = ACCEPT_FROM; |
2658 | @end example | 2741 | @end example |
2659 | 2742 | ||
2660 | @example | 2743 | @example |
2661 | [transport-https_client]@ | 2744 | [transport-https_client] |
2662 | MAX_CONNECTIONS = 128@ | 2745 | MAX_CONNECTIONS = 128 |
2663 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2746 | TESTING_IGNORE_KEYS = ACCEPT_FROM; |
2664 | @end example | 2747 | @end example |
2665 | 2748 | ||
2666 | @noindent | 2749 | @noindent |
@@ -2674,21 +2757,21 @@ The webserver under this address should forward the request to the peer | |||
2674 | and the configure port. | 2757 | and the configure port. |
2675 | 2758 | ||
2676 | @example | 2759 | @example |
2677 | [transport-http_server]@ | 2760 | [transport-http_server] |
2678 | EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet@ | 2761 | EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet |
2679 | PORT = 1080@ | 2762 | PORT = 1080 |
2680 | MAX_CONNECTIONS = 128@ | 2763 | MAX_CONNECTIONS = 128 |
2681 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2764 | TESTING_IGNORE_KEYS = ACCEPT_FROM; |
2682 | @end example | 2765 | @end example |
2683 | 2766 | ||
2684 | @example | 2767 | @example |
2685 | [transport-https_server]@ | 2768 | [transport-https_server] |
2686 | PORT = 4433@ | 2769 | PORT = 4433 |
2687 | CRYPTO_INIT = NORMAL@ | 2770 | CRYPTO_INIT = NORMAL |
2688 | KEY_FILE = https.key@ | 2771 | KEY_FILE = https.key |
2689 | CERT_FILE = https.cert@ | 2772 | CERT_FILE = https.cert |
2690 | MAX_CONNECTIONS = 128@ | 2773 | MAX_CONNECTIONS = 128 |
2691 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2774 | TESTING_IGNORE_KEYS = ACCEPT_FROM; |
2692 | @end example | 2775 | @end example |
2693 | 2776 | ||
2694 | @item transport-wlan | 2777 | @item transport-wlan |
@@ -2697,12 +2780,12 @@ There is a special article how to setup the WLAN plugin, so here only the | |||
2697 | settings. Just specify the interface to use: | 2780 | settings. Just specify the interface to use: |
2698 | 2781 | ||
2699 | @example | 2782 | @example |
2700 | [transport-wlan]@ | 2783 | [transport-wlan] |
2701 | # Name of the interface in monitor mode (typically monX)@ | 2784 | # Name of the interface in monitor mode (typically monX) |
2702 | INTERFACE = mon0@ | 2785 | INTERFACE = mon0 |
2703 | # Real hardware, no testing@ | 2786 | # Real hardware, no testing |
2704 | TESTMODE = 0@ | 2787 | TESTMODE = 0 |
2705 | TESTING_IGNORE_KEYS = ACCEPT_FROM;@ | 2788 | TESTING_IGNORE_KEYS = ACCEPT_FROM; |
2706 | @end example | 2789 | @end example |
2707 | @end itemize | 2790 | @end itemize |
2708 | 2791 | ||
@@ -2749,15 +2832,15 @@ this in your default config file, you only need to adjust them if the | |||
2749 | values are incorrect for your system) | 2832 | values are incorrect for your system) |
2750 | 2833 | ||
2751 | @example | 2834 | @example |
2752 | # section for the wlan transport plugin@ | 2835 | # section for the wlan transport plugin |
2753 | [transport-wlan]@ | 2836 | [transport-wlan] |
2754 | # interface to use, more information in the | 2837 | # interface to use, more information in the |
2755 | # "Before starting GNUnet" section of the handbook. | 2838 | # "Before starting GNUnet" section of the handbook. |
2756 | INTERFACE = mon0@ | 2839 | INTERFACE = mon0 |
2757 | # testmode for developers:@ | 2840 | # testmode for developers: |
2758 | # 0 use wlan interface,@ | 2841 | # 0 use wlan interface, |
2759 | #1 or 2 use loopback driver for tests 1 = server, 2 = client@ | 2842 | #1 or 2 use loopback driver for tests 1 = server, 2 = client |
2760 | TESTMODE = 0@ | 2843 | TESTMODE = 0 |
2761 | @end example | 2844 | @end example |
2762 | 2845 | ||
2763 | @node Before starting GNUnet | 2846 | @node Before starting GNUnet |
@@ -2768,16 +2851,16 @@ in monitor mode. One way to put the wlan interface into monitor mode (if | |||
2768 | your interface name is wlan0) is by executing: | 2851 | your interface name is wlan0) is by executing: |
2769 | 2852 | ||
2770 | @example | 2853 | @example |
2771 | sudo airmon-ng start wlan0@ | 2854 | sudo airmon-ng start wlan0 |
2772 | @end example | 2855 | @end example |
2773 | 2856 | ||
2774 | @noindent | 2857 | @noindent |
2775 | Here is an example what the result should look like: | 2858 | Here is an example what the result should look like: |
2776 | 2859 | ||
2777 | @example | 2860 | @example |
2778 | Interface Chipset Driver@ | 2861 | Interface Chipset Driver |
2779 | wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]@ | 2862 | wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0] |
2780 | (monitor mode enabled on mon0)@ | 2863 | (monitor mode enabled on mon0) |
2781 | @end example | 2864 | @end example |
2782 | 2865 | ||
2783 | @noindent | 2866 | @noindent |
@@ -2846,12 +2929,12 @@ In the respective @code{server config},@code{virtual host} or | |||
2846 | @code{directory} section add the following lines: | 2929 | @code{directory} section add the following lines: |
2847 | 2930 | ||
2848 | @example | 2931 | @example |
2849 | ProxyTimeout 300@ | 2932 | ProxyTimeout 300 |
2850 | ProxyRequests Off@ | 2933 | ProxyRequests Off |
2851 | <Location /bar/ >@ | 2934 | <Location /bar/ > |
2852 | ProxyPass http://gnunet.foo.org:1080/@ | 2935 | ProxyPass http://gnunet.foo.org:1080/ |
2853 | ProxyPassReverse http://gnunet.foo.org:1080/@ | 2936 | ProxyPassReverse http://gnunet.foo.org:1080/ |
2854 | </Location>@ | 2937 | </Location> |
2855 | @end example | 2938 | @end example |
2856 | 2939 | ||
2857 | @noindent | 2940 | @noindent |
@@ -2865,51 +2948,53 @@ In the respective HTTPS @code{server config},@code{virtual host} or | |||
2865 | @code{directory} section add the following lines: | 2948 | @code{directory} section add the following lines: |
2866 | 2949 | ||
2867 | @example | 2950 | @example |
2868 | SSLProxyEngine On@ | 2951 | SSLProxyEngine On |
2869 | ProxyTimeout 300@ | 2952 | ProxyTimeout 300 |
2870 | ProxyRequests Off@ | 2953 | ProxyRequests Off |
2871 | <Location /bar/ >@ | 2954 | <Location /bar/ > |
2872 | ProxyPass https://gnunet.foo.org:4433/@ | 2955 | ProxyPass https://gnunet.foo.org:4433/ |
2873 | ProxyPassReverse https://gnunet.foo.org:4433/@ | 2956 | ProxyPassReverse https://gnunet.foo.org:4433/ |
2874 | </Location>@ | 2957 | </Location> |
2875 | @end example | 2958 | @end example |
2876 | 2959 | ||
2877 | @noindent | 2960 | @noindent |
2878 | More information about the apache mod_proxy configuration can be found | 2961 | More information about the apache mod_proxy configuration can be found |
2879 | at @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} | 2962 | at @uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, |
2963 | http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass} | ||
2880 | 2964 | ||
2881 | @strong{Configure your nginx HTTPS webserver} | 2965 | @strong{Configure your nginx HTTPS webserver} |
2882 | 2966 | ||
2883 | Since nginx does not support chunked encoding, you first of all have to | 2967 | Since nginx does not support chunked encoding, you first of all have to |
2884 | install @code{chunkin}:@ | 2968 | install @code{chunkin}:@ |
2885 | @uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule} | 2969 | @uref{http://wiki.nginx.org/HttpChunkinModule, |
2970 | http://wiki.nginx.org/HttpChunkinModule} | ||
2886 | 2971 | ||
2887 | To enable chunkin add: | 2972 | To enable chunkin add: |
2888 | 2973 | ||
2889 | @example | 2974 | @example |
2890 | chunkin on;@ | 2975 | chunkin on; |
2891 | error_page 411 = @@my_411_error;@ | 2976 | error_page 411 = @@my_411_error; |
2892 | location @@my_411_error @{@ | 2977 | location @@my_411_error @{ |
2893 | chunkin_resume;@ | 2978 | chunkin_resume; |
2894 | @}@ | 2979 | @} |
2895 | @end example | 2980 | @end example |
2896 | 2981 | ||
2897 | @noindent | 2982 | @noindent |
2898 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or | 2983 | Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or |
2899 | the site-specific configuration file. | 2984 | the site-specific configuration file. |
2900 | 2985 | ||
2901 | In the @code{server} section add:@ | 2986 | In the @code{server} section add: |
2902 | 2987 | ||
2903 | @example | 2988 | @example |
2904 | location /bar/@ | 2989 | location /bar/ |
2905 | @{@ | 2990 | @{ |
2906 | proxy_pass http://gnunet.foo.org:1080/;@ | 2991 | proxy_pass http://gnunet.foo.org:1080/; |
2907 | proxy_buffering off;@ | 2992 | proxy_buffering off; |
2908 | proxy_connect_timeout 5; # more than http_server@ | 2993 | proxy_connect_timeout 5; # more than http_server |
2909 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout@ | 2994 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout |
2910 | proxy_http_version 1.1; # 1.0 default@ | 2995 | proxy_http_version 1.1; # 1.0 default |
2911 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@ | 2996 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; |
2912 | @}@ | 2997 | @} |
2913 | @end example | 2998 | @end example |
2914 | 2999 | ||
2915 | @noindent | 3000 | @noindent |
@@ -2921,16 +3006,16 @@ the site-specific configuration file. | |||
2921 | In the @code{server} section add: | 3006 | In the @code{server} section add: |
2922 | 3007 | ||
2923 | @example | 3008 | @example |
2924 | ssl_session_timeout 6m;@ | 3009 | ssl_session_timeout 6m; |
2925 | location /bar/@ | 3010 | location /bar/ |
2926 | @{@ | 3011 | @{ |
2927 | proxy_pass https://gnunet.foo.org:4433/;@ | 3012 | proxy_pass https://gnunet.foo.org:4433/; |
2928 | proxy_buffering off;@ | 3013 | proxy_buffering off; |
2929 | proxy_connect_timeout 5; # more than http_server@ | 3014 | proxy_connect_timeout 5; # more than http_server |
2930 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout@ | 3015 | proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout |
2931 | proxy_http_version 1.1; # 1.0 default@ | 3016 | proxy_http_version 1.1; # 1.0 default |
2932 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504;@ | 3017 | proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; |
2933 | @}@ | 3018 | @} |
2934 | @end example | 3019 | @end example |
2935 | 3020 | ||
2936 | @noindent | 3021 | @noindent |
@@ -2941,16 +3026,16 @@ To have your GNUnet peer announce the address, you have to specify the | |||
2941 | section: | 3026 | section: |
2942 | 3027 | ||
2943 | @example | 3028 | @example |
2944 | [transport-http_server]@ | 3029 | [transport-http_server] |
2945 | EXTERNAL_HOSTNAME = http://www.foo.org/bar/@ | 3030 | EXTERNAL_HOSTNAME = http://www.foo.org/bar/ |
2946 | @end example | 3031 | @end example |
2947 | 3032 | ||
2948 | @noindent | 3033 | @noindent |
2949 | and/or @code{[transport-https_server]} section: | 3034 | and/or @code{[transport-https_server]} section: |
2950 | 3035 | ||
2951 | @example | 3036 | @example |
2952 | [transport-https_server]@ | 3037 | [transport-https_server] |
2953 | EXTERNAL_HOSTNAME = https://www.foo.org/bar/@ | 3038 | EXTERNAL_HOSTNAME = https://www.foo.org/bar/ |
2954 | @end example | 3039 | @end example |
2955 | 3040 | ||
2956 | @noindent | 3041 | @noindent |
@@ -2970,21 +3055,21 @@ To blacklist peers using the configuration you have to add a section to | |||
2970 | your@ configuration containing the peer id of the peer to blacklist and | 3055 | your@ configuration containing the peer id of the peer to blacklist and |
2971 | the plugin@ if required. | 3056 | the plugin@ if required. |
2972 | 3057 | ||
2973 | Example:@ | 3058 | Examples:@ |
2974 | 3059 | ||
2975 | To blacklist connections to P565... on peer AG2P... using tcp add:@ | 3060 | To blacklist connections to P565... on peer AG2P... using tcp add: |
2976 | 3061 | ||
2977 | @c FIXME: This is too long and produces errors in the pdf. | 3062 | @c FIXME: This is too long and produces errors in the pdf. |
2978 | @example | 3063 | @example |
2979 | [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@ | 3064 | [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@ |
2980 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp@ | 3065 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp@ |
2981 | @end example | 3066 | @end example |
2982 | 3067 | ||
2983 | To blacklist connections to P565... on peer AG2P... using all plugins add:@ | 3068 | To blacklist connections to P565... on peer AG2P... using all plugins add: |
2984 | 3069 | ||
2985 | @example | 3070 | @example |
2986 | [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@ | 3071 | [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@ |
2987 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =@ | 3072 | P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =@ |
2988 | @end example | 3073 | @end example |
2989 | 3074 | ||
2990 | You can also add a blacklist client usign the blacklist api. On a | 3075 | You can also add a blacklist client usign the blacklist api. On a |
@@ -3034,16 +3119,16 @@ configure the following settings in the [transport-http_client] and | |||
3034 | [transport-https_client] section of the configuration: | 3119 | [transport-https_client] section of the configuration: |
3035 | 3120 | ||
3036 | @example | 3121 | @example |
3037 | # Type of proxy server,@ | 3122 | # Type of proxy server, |
3038 | # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME@ | 3123 | # Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME |
3039 | # Default: HTTP@ | 3124 | # Default: HTTP |
3040 | # PROXY_TYPE = HTTP | 3125 | # PROXY_TYPE = HTTP |
3041 | 3126 | ||
3042 | # Hostname or IP of proxy server@ | 3127 | # Hostname or IP of proxy server |
3043 | # PROXY =@ | 3128 | # PROXY = |
3044 | # User name for proxy server@ | 3129 | # User name for proxy server |
3045 | # PROXY_USERNAME =@ | 3130 | # PROXY_USERNAME = |
3046 | # User password for proxy server@ | 3131 | # User password for proxy server |
3047 | # PROXY_PASSWORD = | 3132 | # PROXY_PASSWORD = |
3048 | @end example | 3133 | @end example |
3049 | 3134 | ||
@@ -3644,9 +3729,9 @@ GNUnet from @code{init}. | |||
3644 | Finally, you should edit your @code{crontab} (using the @code{crontab} | 3729 | Finally, you should edit your @code{crontab} (using the @code{crontab} |
3645 | command) and insert a line@ | 3730 | command) and insert a line@ |
3646 | 3731 | ||
3647 | @code{@ | 3732 | @example |
3648 | @@reboot gnunet-arm -c ~/.config/gnunet.conf -s@ | 3733 | @@reboot gnunet-arm -c ~/.config/gnunet.conf -s |
3649 | }@ | 3734 | @end example |
3650 | 3735 | ||
3651 | to automatically start your peer whenever your system boots. | 3736 | to automatically start your peer whenever your system boots. |
3652 | 3737 | ||
@@ -3660,9 +3745,9 @@ Then, you create a configuration file @file{/etc/gnunet.conf} which should | |||
3660 | contain the lines:@ | 3745 | contain the lines:@ |
3661 | 3746 | ||
3662 | @example | 3747 | @example |
3663 | [arm]@ | 3748 | [arm] |
3664 | SYSTEM_ONLY = YES@ | 3749 | SYSTEM_ONLY = YES |
3665 | USER_ONLY = NO@ | 3750 | USER_ONLY = NO |
3666 | @end example | 3751 | @end example |
3667 | 3752 | ||
3668 | @noindent | 3753 | @noindent |
@@ -3689,9 +3774,9 @@ Then, create a configuration file in @file{~/.config/gnunet.conf} for the | |||
3689 | $USER with the lines: | 3774 | $USER with the lines: |
3690 | 3775 | ||
3691 | @example | 3776 | @example |
3692 | [arm]@ | 3777 | [arm] |
3693 | SYSTEM_ONLY = NO@ | 3778 | SYSTEM_ONLY = NO |
3694 | USER_ONLY = YES@ | 3779 | USER_ONLY = YES |
3695 | @end example | 3780 | @end example |
3696 | 3781 | ||
3697 | @noindent | 3782 | @noindent |