diff options
author | Nils Gillmann <ng0@n0.is> | 2018-06-06 12:17:10 +0000 |
---|---|---|
committer | Nils Gillmann <ng0@n0.is> | 2018-06-06 12:17:10 +0000 |
commit | afbd424f7410ad5134913a46b4a3f75112d573a3 (patch) | |
tree | ae44b848b5a03e9e38934189bb0779ad24327d1f /README | |
parent | c99d62c683ec641b81b92efeef913189648b7d61 (diff) | |
download | gnunet-afbd424f7410ad5134913a46b4a3f75112d573a3.tar.gz gnunet-afbd424f7410ad5134913a46b4a3f75112d573a3.zip |
README rework part 1
Signed-off-by: Nils Gillmann <ng0@n0.is>
Diffstat (limited to 'README')
-rw-r--r-- | README | 245 |
1 files changed, 182 insertions, 63 deletions
@@ -19,7 +19,7 @@ GNUnet is free software released under the GNU General Public License | |||
19 | (v3 or later). For details see the COPYING file in this directory. | 19 | (v3 or later). For details see the COPYING file in this directory. |
20 | 20 | ||
21 | Additional documentation about GNUnet can be found at | 21 | Additional documentation about GNUnet can be found at |
22 | https://gnunet.org/ and in the doc/ folder. | 22 | https://gnunet.org/ and in the 'doc/' folder. |
23 | 23 | ||
24 | 24 | ||
25 | Dependencies: | 25 | Dependencies: |
@@ -30,78 +30,185 @@ recent versions of the libraries which are often NOT to be found in | |||
30 | stable distributions in 2014. While using older packages may in some | 30 | stable distributions in 2014. While using older packages may in some |
31 | cases on some operating systems may seem to work in some limited | 31 | cases on some operating systems may seem to work in some limited |
32 | fashion, we are in many cases aware of serious problems with older | 32 | fashion, we are in many cases aware of serious problems with older |
33 | packages. Hence please make sure to use the versions listed below. | 33 | packages. Hence please make sure to use the versions listed below. |
34 | 34 | ||
35 | These are the direct dependencies for running GNUnet: | 35 | These are the direct dependencies for running GNUnet: |
36 | 36 | ||
37 | - libmicrohttpd >= 0.9.42 | 37 | - libmicrohttpd >= 0.9.42 |
38 | - libgcrypt >= 1.6 | 38 | - libgcrypt >= 1.6 |
39 | - libgnurl >= 7.35.0 (available from https://gnunet.org/gnurl) | 39 | - libgnurl >= 7.35.0 (recommended, available from https://gnunet.org/gnurl) |
40 | - libunistring >= 0.9.2 | 40 | - libcurl >= 7.35.0 (alternative to libgnurl) |
41 | - gnutls >= 3.2.12 | 41 | - libunistring >= 0.9.2 |
42 | - libidn >= 1.0 | 42 | - gnutls >= 3.2.12 (highly recommended a gnutls linked against libunbound) |
43 | - libextractor >= 0.6.1 (highly recommended) | 43 | - libidn >= 1.0 |
44 | - openssl >= 1.0 (binary, used to generate X.509 certificate) | 44 | - libextractor >= 0.6.1 (highly recommended) |
45 | - libltdl >= 2.2 (part of GNU libtool) | 45 | - openssl >= 1.0 (binary, used to generate X.509 certificate) |
46 | - sqlite >= 3.8 (default database, required) | 46 | - libltdl >= 2.2 (part of GNU libtool) |
47 | - mysql >= 5.1 (alternative to sqlite) | 47 | - sqlite >= 3.8 (default database, required) |
48 | - postgres >= 9.5 (alternative to sqlite) | 48 | - mysql >= 5.1 (alternative to sqlite) |
49 | - libopus >= 1.0.1 (optional for experimental conversation tool) | 49 | - postgres >= 9.5 (alternative to sqlite) |
50 | - libpulse >= 2.0 (optional for experimental conversation tool) | 50 | - Texinfo >= 5.2 [*1] |
51 | - libogg >= 1.3.0 (optional for experimental conversation tool) | 51 | - which (for the bootstrap script) |
52 | - python-zbar >= 0.10 (optional for gnunet-qr) | 52 | - gettext |
53 | - TeX Live >= 2012 (optional for gnunet-bcd[*]) | 53 | - zlib |
54 | - Texinfo >= 5.2 [*1] | 54 | - pkg-config |
55 | - libglpk >= 4.45 (optional for experimental code) | 55 | |
56 | |||
57 | These are the dependencies for GNUnet's testsuite: | ||
58 | |||
59 | - Bash (optional (?), for some tests) | ||
60 | - python >= 2.7 (optional, only python 2.7 is supported) | ||
61 | - python-future >= 2.7 (optional, only python 2.7 is supported) | ||
62 | |||
63 | |||
64 | These are the optional dependencies: | ||
65 | |||
66 | - libopus >= 1.0.1 (optional, for experimental conversation tool) | ||
67 | - libpulse >= 2.0 (optional, for experimental conversation tool) | ||
68 | - libogg >= 1.3.0 (optional, for experimental conversation tool) | ||
69 | - libnss (optional, certtool binary (for convenient installation of GNS proxy)) | ||
70 | - python-future (optional, for some testcases and utilities) | ||
71 | - python-zbar >= 0.10 (optional, for gnunet-qr) | ||
72 | - TeX Live >= 2012 (optional, for gnunet-bcd[*]) | ||
73 | - libglpk >= 4.45 (optional, for experimental code) | ||
74 | - perl5 (optional, for some utilities) | ||
75 | - python >= 2.7 (optional, for gnunet-qr, only python 2.7 is supported) | ||
76 | - bluez (optional, for bluetooth support) | ||
77 | - miniupnpc | ||
78 | - libpbc >= 0.5.14 (optional, for Attribute-Based Encryption and Identity Provider functionality) | ||
79 | - libgabe (optional, for Attribute-Based Encryption and Identity Provider functionality, | ||
80 | from https://github.com/schanzen/libgabe) | ||
81 | |||
56 | 82 | ||
57 | Recommended autotools for compiling the git version are: | 83 | Recommended autotools for compiling the git version are: |
58 | - autoconf >= 2.59 | 84 | |
59 | - automake >= 1.11.1 | 85 | - autoconf >= 2.59 |
60 | - libtool >= 2.2 | 86 | - automake >= 1.11.1 |
87 | - libtool >= 2.2 | ||
61 | 88 | ||
62 | 89 | ||
63 | [*] Mandatory for compiling the info output of the documentation, | 90 | [*] Mandatory for compiling the info output of the documentation, |
64 | a limited subset ('texlive-tiny' in Guix) is enough. | 91 | a limited subset ('texlive-tiny' in Guix) is enough. |
92 | |||
93 | [*1] The default configuration is to build the info output of the | ||
94 | documentation, and therefore require texinfo. You can pass | ||
95 | '--disable-documentation' to the configure script to change this. | ||
65 | 96 | ||
66 | [*1] The default configuration is to build the info output of the documentation, | 97 | Requirements |
67 | and therefore require texinfo. You can pass --disable-documentation to | 98 | ============ |
68 | the configure script to change this. | 99 | |
100 | GNUnet's directed acyclic graph (DAG) will require around 0.74 GiB | ||
101 | Diskspace, with GNUNet itself taking around 9.2 MiB reported by the | ||
102 | build on GNU Guix. | ||
69 | 103 | ||
70 | How to install? | 104 | How to install? |
71 | =============== | 105 | =============== |
72 | 106 | ||
73 | The fastest way is to use a binary package if it is available for your | 107 | |
74 | system. For a more detailed description, read the installation | 108 | binary packages |
75 | instructions on the webpage at https://gnunet.org/installation. | 109 | ~~~~~~~~~~~~~~~ |
110 | |||
111 | We recommend to use binary packages provided by your Operating System's | ||
112 | package manager. GNUnet is reportedly available for at least: | ||
113 | |||
114 | Gentoo (via the 'youbroketheinternet' overlay), GNU Guix, Nix, | ||
115 | Debian, ALT Linux, Archlinux, Deepin, Devuan, Hyperbola, Kali Linux, | ||
116 | LEDE/OpenWRT, Manjaro, Parabola, Pardus, Parrot, PureOS, Raspbian, | ||
117 | Rosa, Trisquel, and Ubuntu. | ||
118 | |||
119 | If GNUnet is available for your Operating System and it is missing, | ||
120 | send us feedback so that we can add it to this list. Furthermore, if | ||
121 | you are interested in packaging GNUnet for your Operating System, | ||
122 | get in touch with us at gnunet-developers@gnu.org if you require | ||
123 | help with this job. | ||
124 | |||
125 | If you were using an Operating System with the apt package manager, | ||
126 | GNUnet could be installed as simple as: | ||
127 | |||
128 | $ apt-get install gnunet | ||
129 | |||
76 | Generic installation instructions are in the INSTALL file in this | 130 | Generic installation instructions are in the INSTALL file in this |
77 | directory. | 131 | directory. |
78 | 132 | ||
133 | Scope of Operating System support | ||
134 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
135 | We actively support GNUnet on a broad range of Free Software Operating | ||
136 | Systems. | ||
137 | |||
138 | For proprietary Operating Systems, like for example Microsoft Windows | ||
139 | or Apple OS X, we accept patches if they don't break anything for | ||
140 | other Operating Systems. | ||
141 | If you are implementing support for a proprietary Operating System, | ||
142 | you should be aware that progress in our codebase could break | ||
143 | functionality on your OS and cause unpredicted behavior we can | ||
144 | not test. However, we do not break support on Operating Systems | ||
145 | with malicious intent. | ||
146 | Regressions which do occur on these Operating Systems are 3rd | ||
147 | class issues and we expect users and developers of these | ||
148 | Operating Systems to send proposed patches to fix regressions. | ||
149 | |||
150 | For more information about our stand on some of the motivating | ||
151 | points here, read the 'Philosophy' Chapter of our handbook. | ||
152 | |||
153 | Building GNUnet from source | ||
154 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
155 | |||
156 | IMPORTANT: You can read further notes about compilation from source in | ||
157 | the 'doc/FILENAME' document, which includes notes about specific | ||
158 | requirements for operating systems aswell. If you are a package | ||
159 | mantainer for an Operating System we invite you to add your notes if | ||
160 | you feel it is necessary and can not be covered in your Operating | ||
161 | System's documentation. | ||
162 | |||
163 | |||
164 | Some Operating Systems currently require you to build GNUnet from | ||
165 | source. | ||
166 | If you are building GNUnet from source you are either interested | ||
167 | in furthering its development (we have further notes for developer | ||
168 | builds in our 'GNUnet Developer Handbook') or your Operating System | ||
169 | simply lacks support for a binary package at the moment. | ||
170 | Two prominent examples which currently lack cross-compilation | ||
171 | support in GNUnet (and native binaries) are MS Windows and Apple macOS. | ||
172 | For macOS we recommend you to do the build process via Homebrew and a | ||
173 | recent XCode installation. | ||
174 | Compilation for MS Windows can ... | ||
175 | |||
79 | Note that some functions of GNUnet require "root" access. GNUnet will | 176 | Note that some functions of GNUnet require "root" access. GNUnet will |
80 | install (tiny) SUID binaries for those functions is you run "make | 177 | install (tiny) SUID binaries for those functions is you run "make |
81 | install" as root. If you do not, GNUnet will still work, but some | 178 | install" as root. If you do not, GNUnet will still work, but some |
82 | functionality will not be available (including certain forms of NAT | 179 | functionality will not be available (including certain forms of NAT |
83 | traversal). | 180 | traversal). |
84 | 181 | ||
85 | GNUnet requires the GNU MP library (http://www.gnu.org/software/gmp/) | 182 | GNUnet requires the GNU MP library (https://www.gnu.org/software/gmp/) |
86 | and libgcrypt (http://www.gnupg.org/). You can specify the path to | 183 | and libgcrypt (https://www.gnupg.org/). You can specify the path to |
87 | libgcrypt by passing "--with-gcrypt=PATH" to configure. You will also | 184 | libgcrypt by passing "--with-gcrypt=PATH" to configure. You will also |
88 | need either sqlite (http://www.sqlite.org/), MySQL | 185 | need either sqlite (http://www.sqlite.org/), MySQL |
89 | (http://www.mysql.org/) or PostGres (http://www.postgres.org/). | 186 | (http://www.mysql.org/) or PostGres (http://www.postgres.org/). |
90 | 187 | ||
91 | If you install from source, you need to install GNU libextractor first | 188 | If you install from source, you need to install GNU libextractor first |
92 | (download from http://www.gnu.org/software/libextractor/). We also | 189 | (download from https://www.gnu.org/software/libextractor/). We also |
93 | recommend installing GNU libmicrohttpd (download from | 190 | recommend installing GNU libmicrohttpd (download from |
94 | http://www.gnu.org/software/libmicrohttpd/). Then you can start the | 191 | https://www.gnu.org/software/libmicrohttpd/). Furthermore we recommend |
95 | actual GNUnet compilation and installation process with: | 192 | libgnurl (from https://gnunet.org/gnurl). |
193 | Then you can start the actual GNUnet compilation process with: | ||
194 | |||
96 | 195 | ||
97 | $ export GNUNET_PREFIX=/usr/local/lib # or other directory of your choice | 196 | $ export GNUNET_PREFIX=/usr/local/lib # or other directory of your choice |
98 | # addgroup gnunetdns | 197 | # addgroup gnunetdns |
99 | # adduser --system --home "/var/lib/gnunet" --group gnunet --shell /bin/sh | 198 | # adduser --system --home "/var/lib/gnunet" --group gnunet --shell /bin/sh |
100 | # ./configure --prefix=$GNUNET_PREFIX/.. --with-extractor=$LE_PREFIX | 199 | # ./configure --prefix=$GNUNET_PREFIX/.. --with-extractor=$LE_PREFIX |
101 | $ make | 200 | $ make |
201 | |||
202 | And finally install GNUnet with: | ||
203 | |||
102 | # make install | 204 | # make install |
205 | |||
206 | Complete the process by either adjusting one of our example service files | ||
207 | in 'contrib/services' or by running: | ||
208 | |||
103 | # sudo -u gnunet gnunet-arm -s | 209 | # sudo -u gnunet gnunet-arm -s |
104 | 210 | ||
211 | |||
105 | Note that running the 'configure' and 'make install' steps as | 212 | Note that running the 'configure' and 'make install' steps as |
106 | root (or with sudo) is required as some parts of the installation | 213 | root (or with sudo) is required as some parts of the installation |
107 | require the creation of SUID binaries. The installation will | 214 | require the creation of SUID binaries. The installation will |
@@ -135,7 +242,7 @@ certain binaries that require additional priviledges will not be | |||
135 | installed properly (and autonomous NAT traversal, WLAN, DNS/GNS and | 242 | installed properly (and autonomous NAT traversal, WLAN, DNS/GNS and |
136 | the VPN will then not work). | 243 | the VPN will then not work). |
137 | 244 | ||
138 | If you run 'configure' and 'make install' as root or use the SUDO | 245 | If you run 'configure' and 'make install' as root or use the '--with-sudo' |
139 | option, GNUnet's build system will install "libnss_gns*" libraries to | 246 | option, GNUnet's build system will install "libnss_gns*" libraries to |
140 | "/lib/" regardless (!) of the $GNUNET_PREFIX you might have specified, | 247 | "/lib/" regardless (!) of the $GNUNET_PREFIX you might have specified, |
141 | as those libraries must be in "/lib/". If you are packaging GNUnet | 248 | as those libraries must be in "/lib/". If you are packaging GNUnet |
@@ -143,14 +250,14 @@ for binary distribution, this may cause your packaging script to miss | |||
143 | those plugins, so you might need to do some additional manual work to | 250 | those plugins, so you might need to do some additional manual work to |
144 | include those libraries in your binary package(s). Similarly, if you | 251 | include those libraries in your binary package(s). Similarly, if you |
145 | want to use the GNUnet naming system and did NOT run GNUnet's 'make | 252 | want to use the GNUnet naming system and did NOT run GNUnet's 'make |
146 | install' process with SUDO rights, the libraries will be installed to | 253 | install' process with sudo rights, the libraries will be installed to |
147 | "$GNUNET_PREFIX" and you will have to move them to "/lib/" | 254 | "$GNUNET_PREFIX" and you will have to move them to "/lib/" |
148 | manually. | 255 | manually. |
149 | 256 | ||
150 | Finally, if you are compiling the code from git, you have to | 257 | Finally, if you are compiling the code from git, you have to |
151 | run ". bootstrap" before ./configure. If you receive an error during | 258 | run "sh ./bootstrap" before running "./configure". If you receive an error during |
152 | the running of ". bootstrap" that looks like "macro `AM_PATH_GTK' not | 259 | the running of "sh ./bootstrap" that looks like "macro `AM_PATH_GTK' |
153 | found in library", you may need to run aclocal by hand with the -I | 260 | not found in library", you may need to run aclocal by hand with the -I |
154 | option, pointing to your aclocal m4 macros, i.e. | 261 | option, pointing to your aclocal m4 macros, i.e. |
155 | 262 | ||
156 | $ aclocal -I /usr/local/share/aclocal | 263 | $ aclocal -I /usr/local/share/aclocal |
@@ -169,7 +276,7 @@ configuration for the peer. gnunet-setup can be used to configure and | |||
169 | test (!) the network settings, choose which applications should be run | 276 | test (!) the network settings, choose which applications should be run |
170 | and configure databases. Other options you might want to control | 277 | and configure databases. Other options you might want to control |
171 | include system limitations (such as disk space consumption, bandwidth, | 278 | include system limitations (such as disk space consumption, bandwidth, |
172 | etc.). The resulting configuration files are human-readable and can | 279 | etc). The resulting configuration files are human-readable and can |
173 | theoretically be created or edited by hand. | 280 | theoretically be created or edited by hand. |
174 | 281 | ||
175 | gnunet-setup is a separate download and requires somewhat recent | 282 | gnunet-setup is a separate download and requires somewhat recent |
@@ -185,10 +292,17 @@ configuration file should be located in "~/.config/gnunet.conf" or its | |||
185 | location can be specified by giving the "-c" option to the respective | 292 | location can be specified by giving the "-c" option to the respective |
186 | GNUnet application. | 293 | GNUnet application. |
187 | 294 | ||
295 | For more information about the configuration (as well as usage) refer | ||
296 | to the 'GNUnet User Handbook' chapter of the documentation, included | ||
297 | in this software distribution. | ||
298 | |||
188 | 299 | ||
189 | Usage | 300 | Usage |
190 | ===== | 301 | ===== |
191 | 302 | ||
303 | For detailed usage notes, instructions and examples, refer to the | ||
304 | included 'GNUnet User Handbook'. | ||
305 | |||
192 | First, you must obtain an initial list of GNUnet hosts. Knowing a | 306 | First, you must obtain an initial list of GNUnet hosts. Knowing a |
193 | single peer is sufficient since after that GNUnet propagates | 307 | single peer is sufficient since after that GNUnet propagates |
194 | information about other peers. Note that the default configuration | 308 | information about other peers. Note that the default configuration |
@@ -214,9 +328,9 @@ UDP or WLAN will discover each other automatically (if they are in the | |||
214 | vicinity of each other) using broadcasts (IPv4/WLAN) or multicasts | 328 | vicinity of each other) using broadcasts (IPv4/WLAN) or multicasts |
215 | (IPv6). | 329 | (IPv6). |
216 | 330 | ||
217 | The local node is started using "gnunet-arm -s". GNUnet should run | 331 | The local node is started using "gnunet-arm -s". We recommend to run |
218 | 24/7 if you want to maximize your anonymity, as this makes partitioning | 332 | GNUnet 24/7 if you want to maximize your anonymity, as this makes |
219 | attacks harder. | 333 | partitioning attacks harder. |
220 | 334 | ||
221 | Once your peer is running, you should then be able to access GNUnet | 335 | Once your peer is running, you should then be able to access GNUnet |
222 | using the shell: | 336 | using the shell: |
@@ -233,42 +347,47 @@ together with a description. To publish files on GNUnet, use the | |||
233 | "gnunet-publish" command. | 347 | "gnunet-publish" command. |
234 | 348 | ||
235 | 349 | ||
236 | The GTK user interface is shipped separately. After downloading and | 350 | The GTK+ (or: Gimp Toolkit) user interface is shipped separately. |
237 | installing gnunet-gtk, you can invoke the setup tool and the | 351 | After installing gnunet-gtk, you can invoke the setup tool and |
238 | file-sharing GUI with: | 352 | the file-sharing GUI with: |
239 | 353 | ||
240 | $ gnunet-setup | 354 | $ gnunet-setup |
241 | $ gnunet-fs-gtk | 355 | $ gnunet-fs-gtk |
242 | 356 | ||
243 | For further documentation, see our webpage. | 357 | For further documentation, see our webpage or the 'GNUnet User Handbook', |
358 | included in this software distribution. | ||
244 | 359 | ||
245 | 360 | ||
246 | Hacking GNUnet | 361 | Hacking GNUnet |
247 | ============== | 362 | ============== |
248 | 363 | ||
249 | Contributions are welcome, please submit bugs to | 364 | Contributions are welcome. Please submit bugs you find to |
250 | https://gnunet.org/bugs/. Please make sure to run contrib/report.sh | 365 | https://gnunet.org/bugs/. |
366 | Please make sure to run the script "contrib/scripts/gnunet-bugreport" | ||
251 | and include the output with your bug reports. More about how to | 367 | and include the output with your bug reports. More about how to |
252 | report bugs can be found in the GNUnet FAQ on the webpage. Submit | 368 | report bugs can be found in the GNUnet FAQ on the webpage. Submit |
253 | patches via E-Mail to gnunet-developers@gnu.org. | 369 | patches via E-Mail to gnunet-developers@gnu.org, formated with |
370 | `git format-patch`. | ||
371 | |||
372 | In order to run the unit tests by hand (instead of using "make check"), | ||
373 | you need to set the environment variable "GNUNET_PREFIX" to the | ||
374 | directory where GNUnet's libraries are installed. | ||
375 | Before running any testcases, you must complete the installation. | ||
254 | 376 | ||
255 | In order to run the unit tests with by hand (instead of using | 377 | Quick summary: |
256 | "make check"), you need to | ||
257 | set an environment variable ("GNUNET_PREFIX") to the directory | ||
258 | where GNUnet's libraries are installed. | ||
259 | Also, before running any testcases, you must | ||
260 | complete the installation first. Quick summary: | ||
261 | 378 | ||
262 | $ ./configure --prefix=$SOMEWHERE | 379 | $ ./configure --prefix=$SOMEWHERE |
263 | $ make | 380 | $ make |
264 | $ make install | 381 | $ make install |
382 | $ export $GNUNET_PREFIX=$SOMEWHERE | ||
265 | $ make check | 383 | $ make check |
266 | 384 | ||
267 | Some of the testcases require python >= 2.6 (+ the python module "futures") | 385 | Some of the testcases require python >= 2.7, and the python modules |
268 | and pexpect to be installed. If any testcases fail to pass on your system, run | 386 | "python-future" (http://python-future.org/) and "pexpect" to be installed. |
269 | "contrib/scripts/report.sh" (in the repository) or "gnunet-bugreport" | 387 | If any testcases fail to pass on your system, run |
270 | when you already have GNUnet installed and report the output together with | 388 | "contrib/scripts/gnunet-bugreport" (in the repository) or "gnunet-bugreport" |
271 | information about the failing testcase to the Mantis bugtracking | 389 | when you already have GNUnet installed and report its output together with |
390 | information about the failing testcase(s) to the Mantis bugtracking | ||
272 | system at https://gnunet.org/bugs/. | 391 | system at https://gnunet.org/bugs/. |
273 | 392 | ||
274 | 393 | ||