README 22 KB

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