X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=README;h=f8fd811f8db2c5cb51c26620a8a989b820f36bca;hb=refs%2Fheads%2Freclaim_attestation_rebase;hp=64d4fd4224c9c2894dd54f294539650704281e61;hpb=609e4becfe496ed62c2007db18d04fbc8d523476;p=oweals%2Fgnunet.git diff --git a/README b/README index 64d4fd422..f8fd811f8 100644 --- a/README +++ b/README @@ -1,5 +1,27 @@ Welcome to GNUnet +ToC +=== + +* ToC +* What is GNUnet? +* Dependencies + o direct dependencies + o test suite dependencies + o optional dependencies + o autotools +* Notes on setuid +* Scope of Operating System support +* How to install + o binary packages + o Building GNUnet from source + o Notes on compiling from Git +* Configuration +* Usage +* Hacking GNUnet +* Running HTTP on port 80 and HTTPS on port 443 +* Further Reading +* Stay tuned What is GNUnet? =============== @@ -30,63 +52,99 @@ Online documentation is provided at Dependencies: ============= +The dependencies for building GNUnet will require around 0.74 GiB +diskspace. GNUnet itself will require 8 - 9.2 MiB depending on +configuration. + These are the direct dependencies for running GNUnet: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- libmicrohttpd >= 0.9.42 +- Bash (for some scripts) +- gettext +- gnutls >= 3.2.12 (highly recommended a gnutls + linked against libunbound) +- A curl build against gnutls, or gnurl: + * libgnurl >= 7.35.0 (recommended, available from + https://gnunet.org/en/gnurl.html) + or + * libcurl >= 7.35.0 (alternative to libgnurl) - libgcrypt >= 1.6 -- libgnurl >= 7.35.0 (recommended, available from https://gnunet.org/gnurl) -- libcurl >= 7.35.0 (alternative to libgnurl) - libunistring >= 0.9.2 -- gnutls >= 3.2.12 (highly recommended a gnutls linked against libunbound) - libidn: - - libidn2 (prefered) + * libidn2 (prefered) or - - libidn >= 1.0 -- libextractor >= 0.6.1 (highly recommended) -- openssl >= 1.0 (binary, used to generate X.509 certificate - for gnunet-gns-proxy-setup-ca) + * libidn >= 1.0 +- libmicrohttpd >= 0.9.63 (strongly recommended for + a wide range of features) +- makeinfo >= 4.8 +- make[*3] - nss (certutil binary, for gnunet-gns-proxy-setup-ca) -- libltdl >= 2.2 (part of GNU libtool) -- sqlite >= 3.8 (default database, required) -- mysql >= 5.1 (alternative to sqlite) -- postgres >= 9.5 (alternative to sqlite) +- openssl >= 1.0 (binary, used to generate + X.509 certificate + for gnunet-gns-proxy-setup-ca) +- pkgconf or pkg-config +- A Posix shell (for some scripts) - Texinfo >= 5.2 [*1] -- makeinfo >= 4.8 -- which (bootstrap script and some Makefiles) -- gettext +- libltdl >= 2.2 (part of GNU libtool) +- 1 or more databases: + * sqlite >= 3.8 (default database, required) + and/or + * mysql >= 5.1 (alternative to sqlite) + and/or + * postgres >= 9.5 (alternative to sqlite) +- which (contrib/apparmor(?), gnunet-bugreport, + and possibly more) - zlib -- pkg-config - These are the dependencies for GNUnet's testsuite: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Bash (optional (?), for some tests) -- python >= 3.7 (optional, only python 3.7 is supported) -- python-future >= 3.7 (optional, only python 3.7 is supported) +- Bash (for some tests[*4]) +- A Posix Shell (for some tests) +- python >= 3.4 (3.4 and higher technically supported, + at least python 3.7 tested to work) +- base tools + - mostly: + - bc, + - curl, + - sed, + - awk, + - which These are the optional dependencies: - -- libopus >= 1.0.1 (optional, for experimental conversation tool) -- libpulse >= 2.0 (optional, for experimental conversation tool) -- libogg >= 1.3.0 (optional, for experimental conversation tool) -- libnss (optional, certtool binary (for convenient installation of GNS proxy)) -- python2.7-future (optional, for gnunet-qr) -- python-zbar >= 0.10 (optional, for gnunet-qr) -- TeX Live >= 2012 (optional, for gnunet-bcd[*]) -- texi2mdoc (optional, for automatic mdoc generation [*2]) -- libglpk >= 4.45 (optional, for experimental code) -- perl5 (optional, for some utilities) -- guile 1.6.4 (or later up to 1.8?, optional for gnunet-download-manager) -- python2.7 >= 2.7 (optional, for gnunet-qr, only python 2.7 is supported) -- bluez (optional, for bluetooth support) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- awk (for linting tests) +- Bash (for Docker and Vagrant) +- bluez (for bluetooth support) +- grof (for linting of man pages) +- libextractor >= 0.6.1 (highly recommended[*5]) +- libjansson +- libopus >= 1.0.1 (for conversation tool) +- libpulse >= 2.0 (for conversation tool) +- libogg >= 1.3.0 (for conversation tool) +- libnss (certtool binary (for convenient + installation of GNS proxy)) +- libzbar >= 0.10 (for gnunet-qr) +- libpbc >= 0.5.14 (for Attribute-Based Encryption and + Identity Provider functionality) +- libgabe (for Attribute-Based Encryption and + Identity Provider functionality, from + https://github.com/schanzen/libgabe) +- mandoc (for linting of man pages, generation of + html output of man pages (not part of + the regular build)) - miniupnpc -- libpbc >= 0.5.14 (optional, for Attribute-Based Encryption and Identity Provider functionality) -- libgabe (optional, for Attribute-Based Encryption and Identity Provider functionality, - from https://github.com/schanzen/libgabe) +- perl5 (for some utilities) +- TeX Live >= 2012 (for gnunet-bcd[*]) +- texi2mdoc (for automatic mdoc generation [*2], not + the texi2mdoc script distributed with + autogen but the texi2mdoc C application) Recommended autotools for compiling the Git version are: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - autoconf >= 2.59 - automake >= 1.11.1 @@ -101,32 +159,106 @@ Recommended autotools for compiling the Git version are: '--disable-documentation' to the configure script to change this. [*2] If you still prefer to have documentation, you can pass - '--with-section7' to build mdoc documentation (experimental - stages in gnunet). If this proves to be reliable, we will - include the mdoc output in the release tarballs. - Contrary to the name, texi2mdoc does not require texinfo, + '--enable-texi2mdoc-generation' to build the mdocml ("mandoc") + documentation (experimental stages in gnunet). + If this proves to be reliable, we will + include the mdocml output in the release tarballs. + Contrary to the name, texi2mdoc does not require Texinfo, It is a standalone ISO C utility. -Requirements -============ +[*3] GNU make introduced the != operator in version 4.0. + GNU make was released in october 2013, reasonable to + be widespread by now. If this is not working out for + you, open a bug so that we can get a more portable + fix in. + +[*4] We are commited to portable tools and solutions + where possible. New scripts should be Posix sh + compatible, current and older scripts are + in the process of being rewritten to comply + with this requirement. + +[*5] While libextractor ("LE") is optional, it is recommended to + build gnunet against it. If you install it later, + you won't benefit from libextractor. + If you are a distributor, we recommend to split + LE into basis + plugins rather than making LE + an option as an afterthought by the user. + LE itself is very small, but its dependency chain + on first, second, third etc level can be big. + There is a small effect on privacy if your LE build + differs from one which includes all + plugins (plugins are build as shared objects): + if users publish a directory with a mixture of file + types (for example mpeg, jpeg, png, gif) the + configuration of LE could leak which plugins are + installed for which filetypes are not providing + more details. + However, this leak is just a minor concern. + +Notes on setuid +=============== + +For a correct functionality depending on the host OS, you need +to run the equivalent of these steps after installation. +Replace $(DESTDIR)$(libexecdir) with the appropriate paths, +for example /usr/local/lib/gnunet/libexec/. Note that this +obviously must be run as priviledged user. + +chown root:root $(DESTDIR)$(libexecdir)/gnunet-helper-vpn +chmod u+s $(DESTDIR)$(libexecdir)/gnunet-helper-vpn +chown root:root $(DESTDIR)$(libexecdir)/gnunet-helper-transport-wlan +chmod u+s $(DESTDIR)$(libexecdir)/gnunet-helper-transport-wlan +chown root:root $(DESTDIR)$(libexecdir)/gnunet-helper-transport-bluetooth +chmod u+s $(DESTDIR)$(libexecdir)/gnunet-helper-transport-bluetooth +chown root $(DESTDIR)$(libexecdir)/gnunet-helper-dns +chgrp $(GNUNETDNS_GROUP) $(DESTDIR)$(libexecdir)/gnunet-helper-dns +chmod 4750 $(DESTDIR)$(libexecdir)/gnunet-helper-dns +chgrp $(GNUNETDNS_GROUP) $(DESTDIR)$(libexecdir)/gnunet-helper-dns +chown gnunet:$(GNUNETDNS_GROUP) $(DESTDIR)$(libexecdir)/gnunet-helper-dns +chmod 2750 $(DESTDIR)$(libexecdir)/gnunet-helper-dns +chown root:root $(DESTDIR)$(libexecdir)/gnunet-helper-exit +chmod u+s $(DESTDIR)$(libexecdir)/gnunet-helper-exit +chown root:root $(DESTDIR)$(libexecdir)/gnunet-helper-nat-server +chown root:root $(DESTDIR)$(libexecdir)/gnunet-helper-nat-client +chmod u+s $(DESTDIR)$(libexecdir)/gnunet-helper-nat-server +chmod u+s $(DESTDIR)$(libexecdir)/gnunet-helper-nat-client + + +Scope of Operating System support +================================= + +We actively support GNUnet on a broad range of Free Software Operating +Systems. + +For proprietary Operating Systems, like for example Microsoft Windows +or Apple OS X, we accept patches if they don't break anything for +other Operating Systems. +If you are implementing support for a proprietary Operating System, +you should be aware that progress in our codebase could break +functionality on your OS and cause unpredicted behavior we can +not test. However, we do not break support on Operating Systems +with malicious intent. +Regressions which do occur on these Operating Systems are 3rd +class issues and we expect users and developers of these +Operating Systems to send proposed patches to fix regressions. + +For more information about our stand on some of the motivating +points here, read the 'Philosophy' Chapter of our handbook. -GNUnet's directed acyclic graph (DAG) will require around 0.74 GiB -Diskspace, with GNUNet itself taking around 9.2 MiB reported by the -build on GNU Guix. How to install? =============== - binary packages ~~~~~~~~~~~~~~~ -We recommend to use binary packages provided by your Operating System's -package manager. GNUnet is reportedly available for at least: +We recommend to use binary packages provided by the package manager integrated +within your Operating System. GNUnet is reportedly available for at least: -GNU Guix, Nix, Debian, ALT Linux, Archlinux, Deepin, Devuan, Hyperbola, -Kali Linux, LEDE/OpenWRT, Manjaro, Parabola, Pardus, Parrot, PureOS, -Raspbian, Rosa, Trisquel, and Ubuntu. +ALT Linux, Archlinux, Debian, Deepin, Devuan, GNU Guix, Hyperbola, +Kali Linux, LEDE/OpenWRT, Manjaro, Nix, Parabola, Pardus, Parrot, +PureOS, Raspbian, Rosa, Trisquel, and Ubuntu. If GNUnet is available for your Operating System and it is missing, send us feedback so that we can add it to this list. Furthermore, if @@ -142,26 +274,6 @@ $ apt-get install gnunet Generic installation instructions are in the INSTALL file in this directory. -Scope of Operating System support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -We actively support GNUnet on a broad range of Free Software Operating -Systems. - -For proprietary Operating Systems, like for example Microsoft Windows -or Apple OS X, we accept patches if they don't break anything for -other Operating Systems. -If you are implementing support for a proprietary Operating System, -you should be aware that progress in our codebase could break -functionality on your OS and cause unpredicted behavior we can -not test. However, we do not break support on Operating Systems -with malicious intent. -Regressions which do occur on these Operating Systems are 3rd -class issues and we expect users and developers of these -Operating Systems to send proposed patches to fix regressions. - -For more information about our stand on some of the motivating -points here, read the 'Philosophy' Chapter of our handbook. - Building GNUnet from source ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -195,7 +307,7 @@ If you install from source, you need to install GNU libextractor first (download from https://www.gnu.org/software/libextractor/). We also recommend installing GNU libmicrohttpd (download from https://www.gnu.org/software/libmicrohttpd/). Furthermore we recommend -libgnurl (from https://gnunet.org/gnurl). +libgnurl (from https://gnunet.org/en/gnurl.html). Then you can start the actual GNUnet compilation process with: @@ -215,11 +327,12 @@ in 'contrib/services' or by running: # sudo -u gnunet gnunet-arm -s -Note that running the 'configure' and 'make install' steps as -root (or with sudo) is required as some parts of the installation -require the creation of SUID binaries. The installation will -work if you do not run these steps as root, but some components -may not be installed in the perfect place or with the right +Note that you must read paragraph "Notes on setuid", which documents steps you +have to follow after the installation, as a priviledged user. We require some +binaries to be setuid. The most portable approach across all supported +platforms and targets is to let this be handled manually. +The installation will work if you do not run these steps as root, but some +components may not be installed in the perfect place or with the right permissions and thus won't work. This will create the users and groups needed for running GNUnet @@ -240,26 +353,26 @@ this case (instead of ~gnunet/.config/gnunet.conf"). In this case, you need to start GNUnet using "gnunet-arm -s -c /etc/gnunet.conf" or set "XDG_CONFIG_HOME=/etc/". -You can avoid running 'make install' as root if you run configure -with the "--with-sudo=yes" option and have extensive sudo rights -(can run "chmod +s" and "chown" via 'sudo'). If you run 'make install' -as a normal user without sudo rights (or the configure option), -certain binaries that require additional priviledges will not be -installed properly (and autonomous NAT traversal, WLAN, DNS/GNS and -the VPN will then not work). - -If you run 'configure' and 'make install' as root or use the '--with-sudo' -option, GNUnet's build system will install "libnss_gns*" libraries to -"/lib/" regardless (!) of the $GNUNET_PREFIX you might have specified, -as those libraries must be in "/lib/". If you are packaging GNUnet -for binary distribution, this may cause your packaging script to miss -those plugins, so you might need to do some additional manual work to -include those libraries in your binary package(s). Similarly, if you -want to use the GNUnet naming system and did NOT run GNUnet's 'make -install' process with sudo rights, the libraries will be installed to -"$GNUNET_PREFIX" and you will have to move them to "/lib/" +You can avoid running 'make install' as root if you have extensive sudo rights +(can run "chmod +s" and "chown" via 'sudo'). If you run 'make install' as a +normal user without sudo rights (or the configure option), certain binaries +that require additional privileges will not be installed properly (and +autonomous NAT traversal, WLAN, DNS/GNS and the VPN will then not work). + +If you run 'configure' and 'make install' as root, GNUnet's build system will +install "libnss_gns*" libraries to "/lib/" regardless (!) of the +$GNUNET_PREFIX you might have specified, as those libraries must be in +"/lib/". If you are packaging GNUnet for binary distribution, this may cause +your packaging script to miss those plugins, so you might need to do some +additional manual work to include those libraries in your binary package(s). +Similarly, if you want to use the GNUnet Name System and did NOT run +GNUnet's 'make install' process with priviledged rights, the libraries will be +installed to "$GNUNET_PREFIX" and you will have to move them to "/lib/" manually. +Notes on compiling from Git +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Finally, if you are compiling the code from git, you have to run "sh ./bootstrap" before running "./configure". If you receive an error during the running of "sh ./bootstrap" that looks like "macro `AM_PATH_GTK' @@ -353,7 +466,7 @@ together with a description. To publish files on GNUnet, use the "gnunet-publish" command. -The GTK+ (or: Gimp Toolkit) user interface is shipped separately. +The GTK user interface is shipped separately. After installing gnunet-gtk, you can invoke the setup tool and the file-sharing GUI with: @@ -388,13 +501,13 @@ $ make install $ export $GNUNET_PREFIX=$SOMEWHERE $ make check -Some of the testcases require python >= 3.7, and the python modules -"python-future" (http://python-future.org/) and "pexpect" to be installed. +Some of the testcases require python >= 3.4, and the python module +"pexpect" to be installed. If any testcases fail to pass on your system, run "contrib/scripts/gnunet-bugreport" (in the repository) or "gnunet-bugreport" when you already have GNUnet installed and report its output together with information about the failing testcase(s) to the Mantis bugtracking -system at https://gnunet.org/bugs/. +system at https://bugs.gnunet.org/. Running HTTP on port 80 and HTTPS on port 443 @@ -438,11 +551,11 @@ Further Reading * Documentation - A HTML version of the new GNUnet manual is deployed at + An HTML version of the GNUnet manual is deployed at https://docs.gnunet.org - which currently displays just GNUnet documentation. Until 2019 + which currently displays just GNUnet documentation. In the future we will add more reading material. * Academia / papers @@ -452,13 +565,10 @@ Further Reading GNUnet or projects around GNUnet. There are currently 2 ways to get them: - * Using git: - git clone https://gnunet.org/git/bibliography.git - * Using Drupal: - https://old.gnunet.org/bibliography - - The Drupal access will be replaced by a new interface to our - bibliography in 2019. + * Using git (NOTE: 1.1 GiB as of 2019-03-09): + git clone https://git.gnunet.org/bibliography.git + * Using the webbrowser: + https://bib.gnunet.org/ Stay tuned