README

   1                        Welcome to GNUnet
   2
   3
   4 What is GNUnet?
   5 ===============
   6
   7 GNUnet is peer-to-peer framework providing a network abstractions and
   8 applications focusing on security and privacy.  So far, we have
   9 created applications for anonymous file-sharing, decentralized naming
  10 and identity management, decentralized and confidential telephony and
  11 tunneling IP traffic over GNUnet.  GNUnet is currently developed by a
  12 worldwide group of independent free software developers.  GNUnet is a
  13 GNU package (http://www.gnu.org/).
  14
  15 This is an ALPHA release.  There are known and significant bugs as
  16 well as many missing features in this release.
  17
  18 GNUnet is free software released under the GNU Affero General Public
  19 License (v3 or later). For details see the COPYING file in this
  20 directory.  If you fork this software, you MUST adjust GNUNET_AGPL_URL
  21 in src/include/gnunet_util_lib.h to point to the source code of your
  22 fork!
  23
  24 Additional documentation about GNUnet can be found at
  25 https://gnunet.org/ and in the 'doc/' folder.
  26 Online documentation is provided at
  27 'https://docs.gnunet.org' and 'https://tutorial.gnunet.org'.
  28
  29
  30 Dependencies:
  31 =============
  32
  33 These are the direct dependencies for running GNUnet:
  34
  35 - libmicrohttpd      >= 0.9.42
  36 - libgcrypt          >= 1.6
  37 - libgnurl           >= 7.35.0      (recommended, available from
  38                                      https://gnunet.org/en/gnurl.html)
  39 - libcurl            >= 7.35.0      (alternative to libgnurl)
  40 - libunistring       >= 0.9.2
  41 - gnutls             >= 3.2.12      (highly recommended a gnutls
  42                                      linked against libunbound)
  43 - libidn:
  44   - libidn2 (prefered)
  45   or
  46   - libidn           >= 1.0
  47 - libextractor       >= 0.6.1       (highly recommended)
  48 - openssl            >= 1.0         (binary, used to generate
  49                                      X.509 certificate
  50                                      for gnunet-gns-proxy-setup-ca)
  51 - nss                               (certutil binary, for
  52                                      gnunet-gns-proxy-setup-ca)
  53 - libltdl            >= 2.2         (part of GNU libtool)
  54 - sqlite             >= 3.8         (default database, required)
  55 - mysql              >= 5.1         (alternative to sqlite)
  56 - postgres           >= 9.5         (alternative to sqlite)
  57 - Texinfo            >= 5.2         [*1]
  58 - makeinfo           >= 4.8
  59 - make[*3]
  60 - which                             (contrib/apparmor(?), gnunet-bugreport,
  61                                      tests (dns, gns, namestore,
  62                                      scalarproduct) and possibly more)
  63 - gettext
  64 - zlib
  65 - Posix shell                       (for some scripts)
  66 - Bash                              (for some scripts)
  67
  68 These are the dependencies for GNUnet's testsuite:
  69
  70 - Posix Shell                       (for some tests)
  71 - Bash                              (for some tests[*4])
  72 - python             >= 3.7         (only python 3.7 is supported)
  73 - python-future      >= 3.7         (only python 3.7 is supported)
  74 - base tools
  75   - mostly:
  76     - which,
  77     - bc,
  78     - curl
  79     - sed
  80
  81
  82 These are the optional dependencies:
  83
  84 - Bash                              (for Docker and Vagrant)
  85 - libopus            >= 1.0.1       (for experimental conversation tool)
  86 - libpulse           >= 2.0         (for experimental conversation tool)
  87 - libogg             >= 1.3.0       (for experimental conversation tool)
  88 - libnss                            (certtool binary (for convenient
  89                                      installation of GNS proxy))
  90 - python2.7          = 2.7          (for gnunet-qr, only python 2.7
  91                                      supported)
  92 - python-zbar        >= 0.10        (for gnunet-qr, not optional)
  93 - TeX Live           >= 2012        (for gnunet-bcd[*])
  94 - texi2mdoc                         (for automatic mdoc generation [*2])
  95 - libglpk            >= 4.45        (for experimental code)
  96 - perl5                             (for some utilities)
  97 - guile              1.6.4          (or later up to 1.8?, for
  98                                      gnunet-download-manager)
  99 - bluez                             (for bluetooth support)
 100 - miniupnpc
 101 - libpbc             >= 0.5.14      (for Attribute-Based Encryption and
 102                                      Identity Provider functionality)
 103 - libgabe                           (for Attribute-Based Encryption and
 104                                      Identity Provider functionality, from
 105                                      https://github.com/schanzen/libgabe)
 106
 107 Recommended autotools for compiling the Git version are:
 108
 109 - autoconf           >= 2.59
 110 - automake           >= 1.11.1
 111 - libtool            >= 2.2
 112
 113
 114 [*] Mandatory for compiling the info output of the documentation,
 115     a limited subset ('texlive-tiny' in Guix) is enough.
 116
 117 [*1] The default configuration is to build the info output of the
 118      documentation, and therefore require texinfo.  You can pass
 119      '--disable-documentation' to the configure script to change this.
 120
 121 [*2] If you still prefer to have documentation, you can pass
 122      '--with-section7' to build mdoc documentation (experimental
 123      stages in gnunet). If this proves to be reliable, we will
 124      include the mdoc output in the release tarballs.
 125      Contrary to the name, texi2mdoc does not require texinfo,
 126      It is a standalone ISO C utility.
 127
 128 [*3] GNU make introduced the != operator in version 4.0.
 129      GNU make was released in october 2013, reasonable to
 130      be widespread by now. If this is not working out for
 131      you, open a bug so that we can get a more portable
 132      fix in.
 133
 134 [*4] We are commited  to portable tools and solutions
 135      where possible. New scripts should be Posix SH
 136      compatible, current and older scripts are
 137      in the process of being rewritten to comply
 138      with this requirement.
 139
 140 Requirements
 141 ============
 142
 143 GNUnet's directed acyclic graph (DAG) will require around 0.74 GiB
 144 Diskspace, with GNUNet itself taking around 8 - 9.2 MiB reported by
 145 the build on GNU Guix.
 146
 147 How to install?
 148 ===============
 149
 150
 151 binary packages
 152 ~~~~~~~~~~~~~~~
 153
 154 We recommend to use binary packages provided by your Operating System's
 155 package manager. GNUnet is reportedly available for at least:
 156
 157 GNU Guix, Nix, Debian, ALT Linux, Archlinux, Deepin, Devuan, Hyperbola,
 158 Kali Linux, LEDE/OpenWRT, Manjaro, Parabola, Pardus, Parrot, PureOS,
 159 Raspbian, Rosa, Trisquel, and Ubuntu.
 160
 161 If GNUnet is available for your Operating System and it is missing,
 162 send us feedback so that we can add it to this list. Furthermore, if
 163 you are interested in packaging GNUnet for your Operating System,
 164 get in touch with us at gnunet-developers@gnu.org if you require
 165 help with this job.
 166
 167 If you were using an Operating System with the apt package manager,
 168 GNUnet could be installed as simple as:
 169
 170 $ apt-get install gnunet
 171
 172 Generic installation instructions are in the INSTALL file in this
 173 directory.
 174
 175 Scope of Operating System support
 176 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 177 We actively support GNUnet on a broad range of Free Software Operating
 178 Systems.
 179
 180 For proprietary Operating Systems, like for example Microsoft Windows
 181 or Apple OS X, we accept patches if they don't break anything for
 182 other Operating Systems.
 183 If you are implementing support for a proprietary Operating System,
 184 you should be aware that progress in our codebase could break
 185 functionality on your OS and cause unpredicted behavior we can
 186 not test. However, we do not break support on Operating Systems
 187 with malicious intent.
 188 Regressions which do occur on these Operating Systems are 3rd
 189 class issues and we expect users and developers of these
 190 Operating Systems to send proposed patches to fix regressions.
 191
 192 For more information about our stand on some of the motivating
 193 points here, read the 'Philosophy' Chapter of our handbook.
 194
 195 Building GNUnet from source
 196 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 197
 198 IMPORTANT: You can read further notes about compilation from source in
 199 the handbook under doc/handbook/, which includes notes about specific
 200 requirements for operating systems aswell. If you are a package
 201 mantainer for an Operating System we invite you to add your notes if
 202 you feel it is necessary and can not be covered in your Operating
 203 System's documentation.
 204
 205 Two prominent examples which currently lack cross-compilation
 206 support in GNUnet (and native binaries) are MS Windows and Apple macOS.
 207 For macOS we recommend you to do the build process via Homebrew and a
 208 recent XCode installation. We don't recommend using GNUnet with any
 209 recent MS Windows system as it officially spies on its users (according
 210 to its T&C), defying some of the purposes of GNUnet.
 211
 212 Note that some functions of GNUnet require "root" access.  GNUnet will
 213 install (tiny) SUID binaries for those functions is you run "make
 214 install" as root.  If you do not, GNUnet will still work, but some
 215 functionality will not be available (including certain forms of NAT
 216 traversal).
 217
 218 GNUnet requires the GNU MP library (https://www.gnu.org/software/gmp/)
 219 and libgcrypt (https://www.gnupg.org/).  You can specify the path to
 220 libgcrypt by passing "--with-gcrypt=PATH" to configure.  You will also
 221 need either sqlite (http://www.sqlite.org/), MySQL
 222 (http://www.mysql.org/) or PostGres (http://www.postgres.org/).
 223
 224 If you install from source, you need to install GNU libextractor first
 225 (download from https://www.gnu.org/software/libextractor/).  We also
 226 recommend installing GNU libmicrohttpd (download from
 227 https://www.gnu.org/software/libmicrohttpd/). Furthermore we recommend
 228 libgnurl (from https://gnunet.org/en/gnurl.html).
 229 Then you can start the actual GNUnet compilation process with:
 230
 231
 232 $ export GNUNET_PREFIX=/usr/local/lib # or other directory of your choice
 233 # addgroup gnunetdns
 234 # adduser --system --home "/var/lib/gnunet" --group gnunet --shell /bin/sh
 235 # ./configure --prefix=$GNUNET_PREFIX/.. --with-extractor=$LE_PREFIX
 236 $ make
 237
 238 And finally install GNUnet with:
 239
 240 # make install
 241
 242 Complete the process by either adjusting one of our example service files
 243 in 'contrib/services' or by running:
 244
 245 # sudo -u gnunet gnunet-arm -s
 246
 247
 248 Note that running the 'configure' and 'make install' steps as
 249 root (or with sudo) is required as some parts of the installation
 250 require the creation of SUID binaries.  The installation will
 251 work if you do not run these steps as root, but some components
 252 may not be installed in the perfect place or with the right
 253 permissions and thus won't work.
 254
 255 This will create the users and groups needed for running GNUnet
 256 securely and then compile and install GNUnet to $GNUNET_PREFIX/../bin/,
 257 $GNUNET_PREFIX/ and $GNUNET_PREFIX/../share/ and start the system
 258 with the default configuration.  It is strongly recommended that you
 259 add a user "gnunet" to run "gnunet-arm".  You can then still run the
 260 end-user applications as another user.
 261
 262 If you create a system user "gnunet", it is recommended that you edit
 263 the configuration file slightly so that data can be stored in the
 264 system user home directory at "/var/lib/gnunet".  Depending on what
 265 the $HOME-directory of your "gnunet" user is, you might need to set
 266 the SERVICEHOME option in section "[PATHS]" to "/var/lib/gnunet" to
 267 do this.  Depending on your personal preferences, you may also want to
 268 use "/etc/gnunet.conf" for the location of the configuration file in
 269 this case (instead of ~gnunet/.config/gnunet.conf").  In this case,
 270 you need to start GNUnet using "gnunet-arm -s -c /etc/gnunet.conf" or
 271 set "XDG_CONFIG_HOME=/etc/".
 272
 273 You can avoid running 'make install' as root if you run configure
 274 with the "--with-sudo=yes" option and have extensive sudo rights
 275 (can run "chmod +s" and "chown" via 'sudo').  If you run 'make install'
 276 as a normal user without sudo rights (or the configure option),
 277 certain binaries that require additional priviledges will not be
 278 installed properly (and autonomous NAT traversal, WLAN, DNS/GNS and
 279 the VPN will then not work).
 280
 281 If you run 'configure' and 'make install' as root or use the '--with-sudo'
 282 option, GNUnet's build system will install "libnss_gns*" libraries to
 283 "/lib/" regardless (!) of the $GNUNET_PREFIX you might have specified,
 284 as those libraries must be in "/lib/".  If you are packaging GNUnet
 285 for binary distribution, this may cause your packaging script to miss
 286 those plugins, so you might need to do some additional manual work to
 287 include those libraries in your binary package(s).  Similarly, if you
 288 want to use the GNUnet naming system and did NOT run GNUnet's 'make
 289 install' process with sudo rights, the libraries will be installed to
 290 "$GNUNET_PREFIX" and you will have to move them to "/lib/"
 291 manually.
 292
 293 Finally, if you are compiling the code from git, you have to
 294 run "sh ./bootstrap" before running "./configure".  If you receive an error during
 295 the running of "sh ./bootstrap" that looks like "macro `AM_PATH_GTK'
 296 not found in library", you may need to run aclocal by hand with the -I
 297 option, pointing to your aclocal m4 macros, i.e.
 298
 299 $ aclocal -I /usr/local/share/aclocal
 300
 301
 302 Configuration
 303 =============
 304
 305 Note that additional, per-user configuration files can be created by
 306 each user.  However, this is usually not necessary as there are few
 307 per-user options that normal users would want to modify.  The defaults
 308 that are shipped with the installation are usually just fine.
 309
 310 The gnunet-setup tool is particularly useful to generate the master
 311 configuration for the peer.  gnunet-setup can be used to configure and
 312 test (!) the network settings, choose which applications should be run
 313 and configure databases.  Other options you might want to control
 314 include system limitations (such as disk space consumption, bandwidth,
 315 etc).  The resulting configuration files are human-readable and can
 316 theoretically be created or edited by hand.
 317
 318 gnunet-setup is a separate download and requires somewhat recent
 319 versions of GTK+ and Glade. You can also create the configuration file
 320 by hand, but this is not recommended.  For more general information
 321 about the GNU build process read the INSTALL file.
 322
 323 GNUnet uses two types of configuration files, one that specifies the
 324 system-wide defaults (typically located in
 325 $GNUNET_PREFIX/../share/gnunet/config.d/) and a second one that overrides
 326 default values with user-specific preferences.  The user-specific
 327 configuration file should be located in "~/.config/gnunet.conf" or its
 328 location can be specified by giving the "-c" option to the respective
 329 GNUnet application.
 330
 331 For more information about the configuration (as well as usage) refer
 332 to the 'GNUnet User Handbook' chapter of the documentation, included
 333 in this software distribution.
 334
 335
 336 Usage
 337 =====
 338
 339 For detailed usage notes, instructions and examples, refer to the
 340 included 'GNUnet Handbook'.
 341
 342 First, you must obtain an initial list of GNUnet hosts.  Knowing a
 343 single peer is sufficient since after that GNUnet propagates
 344 information about other peers.  Note that the default configuration
 345 contains URLs from where GNUnet downloads an initial hostlist
 346 whenever it is started.  If you want to create an alternative URL for
 347 others to use, the file can be generated on any machine running
 348 GNUnet by periodically executing
 349
 350 $ cat $SERVICEHOME/data/hosts/* > the_file
 351
 352 and offering 'the_file' via your web server.  Alternatively, you can
 353 run the build-in web server by adding '-p' to the OPTIONS value
 354 in the "hostlist" section of gnunet.conf and opening the respective
 355 HTTPPORT to the public.
 356
 357 If the solution with the hostlist URL is not feasible for your
 358 situation, you can also add hosts manually.  Simply copy the hostkeys
 359 to "$SERVICEHOME/data/hosts/" (where $SERVICEHOME is the directory
 360 specified in the gnunet.conf configuration file).  You can also use
 361 "gnunet-peerinfo -g" to GET a URI for a peer and "gnunet-peerinfo -p
 362 URI" to add a URI from another peer.  Finally, GNUnet peers that use
 363 UDP or WLAN will discover each other automatically (if they are in the
 364 vicinity of each other) using broadcasts (IPv4/WLAN) or multicasts
 365 (IPv6).
 366
 367 The local node is started using "gnunet-arm -s".  We recommend to run
 368 GNUnet 24/7 if you want to maximize your anonymity, as this makes
 369 partitioning attacks harder.
 370
 371 Once your peer is running, you should then be able to access GNUnet
 372 using the shell:
 373
 374 $ gnunet-search KEYWORD
 375
 376 This will display a list of results to the console.  You can abort
 377 the command using "CTRL-C".  Then use
 378
 379 $ gnunet-download -o FILENAME GNUNET_URI
 380
 381 to retrieve a file.  The GNUNET_URI is printed by gnunet-search
 382 together with a description.  To publish files on GNUnet, use the
 383 "gnunet-publish" command.
 384
 385
 386 The GTK+ (or: Gimp Toolkit) user interface is shipped separately.
 387 After installing gnunet-gtk, you can invoke the setup tool and
 388 the file-sharing GUI with:
 389
 390 $ gnunet-setup
 391 $ gnunet-fs-gtk
 392
 393 For further documentation, see our webpage or the 'GNUnet User Handbook',
 394 included in this software distribution.
 395
 396
 397 Hacking GNUnet
 398 ==============
 399
 400 Contributions are welcome. Please submit bugs you find to
 401 https://bugs.gnunet.org/ or our bugs mailinglist.
 402 Please make sure to run the script "contrib/scripts/gnunet-bugreport"
 403 and include the output with your bug reports.  More about how to
 404 report bugs can be found in the GNUnet FAQ on the webpage.  Submit
 405 patches via E-Mail to gnunet-developers@gnu.org, formated with
 406 `git format-patch`.
 407
 408 In order to run the unit tests by hand (instead of using "make check"),
 409 you need to set the environment variable "GNUNET_PREFIX" to the
 410 directory where GNUnet's libraries are installed.
 411 Before running any testcases, you must complete the installation.
 412
 413 Quick summary:
 414
 415 $ ./configure --prefix=$SOMEWHERE
 416 $ make
 417 $ make install
 418 $ export $GNUNET_PREFIX=$SOMEWHERE
 419 $ make check
 420
 421 Some of the testcases require python >= 3.7, and the python modules
 422 "python-future" (http://python-future.org/) and "pexpect" to be installed.
 423 If any testcases fail to pass on your system, run
 424 "contrib/scripts/gnunet-bugreport" (in the repository) or "gnunet-bugreport"
 425 when you already have GNUnet installed and report its output together with
 426 information about the failing testcase(s) to the Mantis bugtracking
 427 system at https://bugs.gnunet.org/.
 428
 429
 430 Running HTTP on port 80 and HTTPS on port 443
 431 =============================================
 432
 433 In order to hide GNUnet's HTTP/HTTPS traffic perfectly, you might
 434 consider running GNUnet's HTTP/HTTPS transport on port 80/443.
 435 However, we do not recommend running GNUnet as root.  Instead, forward
 436 port 80 to say 1080 with this command (as root, in your startup
 437 scripts):
 438
 439 # iptables -t nat -A PREROUTING -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 1080
 440
 441 or for HTTPS
 442
 443 # iptables -t nat -A PREROUTING -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 4433
 444
 445 Then set in the HTTP section of gnunet.conf the "ADVERTISED_PORT" to
 446 "80" and "PORT" to 1080 and similarly in the HTTPS section the
 447 "ADVERTISED_PORT" to "443" and "PORT" to 4433.
 448
 449 You can do the same trick for the TCP and UDP transports if you want
 450 to map them to a priviledged port (from the point of view of the
 451 network).  However, we are not aware of this providing any advantages
 452 at this point.
 453
 454 If you are already running an HTTP or HTTPS server on port 80 (or 443),
 455 you may be able to configure it as a "ReverseProxy".  Here, you tell
 456 GNUnet that the externally visible URI is some sub-page on your website,
 457 and GNUnet can then tunnel its traffic via your existing HTTP server.
 458 This is particularly powerful if your existing server uses HTTPS, as
 459 it makes it harder for an adversary to distinguish normal traffic to
 460 your server from GNUnet traffic.  Finally, even if you just use HTTP,
 461 you might benefit (!) from ISP's traffic shaping as opposed to being
 462 throttled by ISPs that dislike P2P.  Details for configuring the
 463 reverse proxy are documented on our website.
 464
 465
 466 Further Reading
 467 ===============
 468
 469 * Documentation
 470
 471   A HTML version of the new GNUnet manual is deployed at
 472
 473     https://docs.gnunet.org
 474
 475   which currently displays just GNUnet documentation. Until 2019
 476   we will add more reading material.
 477
 478 * Academia / papers
 479
 480   In almost 20 years various people in our community have written and
 481   collected a good number of papers which have been implemented in
 482   GNUnet or projects around GNUnet.
 483   There are currently 2 ways to get them:
 484
 485   * Using git (NOTE: 1.1 GiB as of 2019-03-09):
 486     git clone https://git.gnunet.org/bibliography.git
 487   * Using Drupal:
 488     https://old.gnunet.org/bibliography
 489
 490   The Drupal access will be replaced by a new interface to our
 491   bibliography in 2019.
 492
 493
 494 Stay tuned
 495 ==========
 496
 497 * https://gnunet.org/
 498 * https://bugs.gnunet.org
 499 * https://git.gnunet.org
 500 * http://www.gnu.org/software/gnunet/
 501 * http://mail.gnu.org/mailman/listinfo/gnunet-developers
 502 * http://mail.gnu.org/mailman/listinfo/help-gnunet
 503 * http://mail.gnu.org/mailman/listinfo/info-gnunet
 504 * http://mail.gnu.org/mailman/listinfo/gnunet-svn