;;(zero? (system* "make" "doc-all-give-me-the-noise"))))
(replace 'install
(lambda _
- (zero? (system* "make" "doc-all-install")))))))
+ (zero? (system* "make" "doc-gendoc-install")))))))
;;(lambda* (#:key outputs #:allow-other-keys)
;; (let* ((out (assoc-ref outputs "out"))
;; (doc (string-append out "/share/doc/gnunet")))
gnunet.t2p/
gnunet-c-tutorial.t2p/
*.t2p/
-documentation/manuals
\ No newline at end of file
+documentation/manuals
+.\#*
\ No newline at end of file
chapters/user.texi \
chapters/vocabulary.texi \
chapters/configuration.texi \
+ chapters/contributing.texi \
fdl-1.3.texi \
gpl-3.0.texi
@install gnunet.html $(DESTDIR)/$(docdir)
@install gnunet-c-tutorial.html $(DESTDIR)/$(docdir)
+doc-gendoc-install:
+ @mkdir -p $(DESTDIR)/$(docdir)
+ @cp -r manual $(DESTDIR)/$(docdir)
+
# @cp -r images $(DESTDIR)/$(infoimagedir)
dev-build: version.texi version2.texi
@rm gnunet-c-tutorial.html
@rm -r gnunet.t2p
@rm -r gnunet-c-tutorial.t2p
+ @rm -r manual
# CLEANFILES = \
# gnunet.log \
3. Do not use tab characters (see chapter 2.1 texinfo manual)
4. Use neutral language and third person perspective in the text
+
+4.1 So, when you refer to a user in general or addressing the user,
+ refer to (1).
+4.1.1 Unsolved exceptions for canonical reasons:
+ When refering to Alice, use "she".
+ When refering to Bob, use "he".
+ These are long established examples and they
+ should either be replaced (avoid Alice and Bob
+ examples when you can) or followed.
+
+5. Use 2 spaces between sentences, so instead of:
+
+ We do this and the other thing. This is done by foo.
+
+ Write:
+
+ We do this and the other thing. This is done by foo.
+
+6. Use @footnote{} instead of putting an @*ref{} to the footnote on a
+ collected footnote-page.
+ In a 200+ pages handbook it's better to have footnotes accessible
+ without having to skip over to the end.
+
+6.1 Avoid unnecessary footnotes, keep the text self-explanatory and
+ in a simple language where possible/necessary.
+
+* Completion Levels:
+
+** chapters/philosophy: around 100% fixed after initial export.
+
* What's left to do
- Which Texlive modules are needed? Decrease the size.
--- /dev/null
+@node GNUnet Contributors Handbook
+@chapter GNUnet Contributors Handbook
+
+@menu
+* Contributing to GNUnet::
+* Licenses of contributions::
+* Copyright Assignment::
+* Contributing to the Reference Manual::
+@end menu
+
+@node Contributing to GNUnet
+@section Contributing to GNUnet
+
+@node Licenses of contributions
+@section Licenses of contributions
+
+GNUnet is a @uref{https://www.gnu.org/, GNU} package.
+All code contributions must thus be put under the
+@uref{https://www.gnu.org/copyleft/gpl.html, GNU Public License (GPL)}.
+All documentation should be put under FSF approved licenses
+(see @uref{https://www.gnu.org/copyleft/fdl.html, fdl}).
+
+By submitting documentation, translations, and other content to GNUnet
+you automatically grant the right to publish code under the
+GNU Public License and documentation under either or both the
+GNU Public License or the GNU Free Documentation License.
+When contributing to the GNUnet project, GNU standards and the
+@uref{https://www.gnu.org/philosophy/philosophy.html, GNU philosophy}
+should be adhered to.
+
+@cindex copyright assignment
+@node Copyright Assignment
+@section Copyright Assignment
+We require a formal copyright assignment for GNUnet contributors
+to GNUnet e.V.; nevertheless, we do allow pseudonymous contributions.
+By signing the copyright agreement and submitting your code (or
+documentation) to us, you agree to share the rights to your code
+with GNUnet e.V.; GNUnet e.V. receives non-exclusive ownership
+rights, and in particular is allowed to dual-license the code. You
+retain non-exclusive rights to your contributions, so you can also
+share your contributions freely with other projects.
+
+GNUnet e.V. will publish all accepted contributions under the GPLv3
+or any later version. The association may decide to publish
+contributions under additional licenses (dual-licensing).
+
+We do not intentionally remove your name from your contributions;
+however, due to extensive editing it is not always trivial to
+attribute contributors properly. If you find that you significantly
+contributed to a file (or the project as a whole) and are not listed
+in the respective authors file or section, please do let us know.
+
+@node Contributing to the Reference Manual
+@section Contributing to the Reference Manual
+
+@itemize @bullet
+
+@item When writing documentation, please use
+@uref{https://en.wikipedia.org/wiki/Singular_they, gender-neutral wording}
+when referring to people, such as singular “they”, “their”, “them”, and so
+forth.
+
+@item Keep line length below 74 characters, except for URLs.
+URLs break in the PDF output when they contain linebreaks.
+
+@item Do not use tab characters (see chapter 2.1 texinfo manual)
+
+@item Use neutral language and third person perspective in the text
+
+@item So, when you refer to a user in general or addressing the user,
+refer to (1).
+@itemize @bullet
+@item Unsolved exceptions for canonical reasons: When refering to Alice,
+use "she". When refering to Bob, use "he". These are long established
+examples and they should either be replaced (avoid Alice and Bob
+examples when you can) or followed.
+@end itemize
+
+@c FIXME: This is questionable, it feels like bike shed painging to do
+@c this for several k lines. It only helps to jump between sentences in
+@c editors afaik.
+@c @item Use 2 spaces between sentences, so instead of:
+
+@c @example
+@c We do this and the other thing. This is done by foo.
+@c @end example
+
+@c Write:
+
+@c @example
+@c We do this and the other thing. This is done by foo.
+@c @end example
+
+@item Use @@footnote@{@} instead of putting an @@*ref@{@} to the
+footnote on a collected footnote-page.
+In a 200+ pages handbook it's better to have footnotes accessible
+without having to skip over to the end.
+
+@item Avoid unnecessary footnotes, keep the text self-explanatory and
+in a simple language where possible/necessary.
+
+@end itemize
@itemize @bullet
@item developed by a community that believes in the GNU philosophy
@item Free Software (Free as in Freedom), licensed under the
-@xref{GNU General Public License}
+GNU General Public License
@item A set of standards, including coding conventions and
architectural rules
@item A set of layered protocols, both specifying the communication
In particular, the architecture specifies that a peer consists of many
processes communicating via protocols. Processes can be written in almost
any language.
-C and Java APIs exist for accessing existing services and for writing
-extensions. It is possible to write extensions in other languages by
+C and Java @footnote{As well as Guile} APIs exist for accessing existing
+services and for writing extensions.
+It is possible to write extensions in other languages by
implementing the necessary IPC protocols.
GNUnet can be extended and improved along many possible dimensions, and
* Build-system::
* Developing extensions for GNUnet using the gnunet-ext template::
* Writing testcases::
-* GNUnet's TESTING library::
+* TESTING library::
* Performance regression analysis with Gauger::
-* GNUnet's TESTBED Subsystem::
+* TESTBED Subsystem::
* libgnunetutil::
-* The Automatic Restart Manager (ARM)::
-* GNUnet's TRANSPORT Subsystem::
+* Automatic Restart Manager (ARM)::
+* TRANSPORT Subsystem::
* NAT library::
* Distance-Vector plugin::
* SMTP plugin::
* Bluetooth plugin::
* WLAN plugin::
-* The ATS Subsystem::
-* GNUnet's CORE Subsystem::
-* GNUnet's CADET subsystem::
-* GNUnet's NSE subsystem::
-* GNUnet's HOSTLIST subsystem::
-* GNUnet's IDENTITY subsystem::
-* GNUnet's NAMESTORE Subsystem::
-* GNUnet's PEERINFO subsystem::
-* GNUnet's PEERSTORE subsystem::
-* GNUnet's SET Subsystem::
-* GNUnet's STATISTICS subsystem::
-* GNUnet's Distributed Hash Table (DHT)::
-* The GNU Name System (GNS)::
-* The GNS Namecache::
-* The REVOCATION Subsystem::
-* GNUnet's File-sharing (FS) Subsystem::
-* GNUnet's REGEX Subsystem::
+* ATS Subsystem::
+* CORE Subsystem::
+* CADET Subsystem::
+* NSE Subsystem::
+* HOSTLIST Subsystem::
+* IDENTITY Subsystem::
+* NAMESTORE Subsystem::
+* PEERINFO Subsystem::
+* PEERSTORE Subsystem::
+* SET Subsystem::
+* STATISTICS Subsystem::
+* Distributed Hash Table (DHT)::
+* GNU Name System (GNS)::
+* GNS Namecache::
+* REVOCATION Subsystem::
+* File-sharing (FS) Subsystem::
+* REGEX Subsystem::
@end menu
@node Developer Introduction
@end itemize
In addition to the GNUnet Reference Documentation you are reading,
-the GNUnet server contains various resources for GNUnet
-developers and those who aspire to become regular contributors.
+the GNUnet server at @uref{https://gnunet.org} contains
+various resources for GNUnet developers and those
+who aspire to become regular contributors.
They are all conveniently reachable via the "Developer"
entry in the navigation menu. Some additional tools (such as static
analysis reports) require a special developer access to perform certain
Qt-based GNUnet GUI (is it depreacated?)
@item @command{gnunet-cocoa}
cocoa-based GNUnet GUI (is it depreacated?)
+@item @command{gnunet-guile}
@end table
more 'secure' or convenient implementations of commonly used primitives.
The API is spread over more than a dozen headers, developers should study
those closely to avoid duplicating existing functions.
+@pxref{libgnunetutil}.
@item @file{hello/} --- libgnunethello
HELLO messages are used to
describe under which addresses a peer can be reached (for example,
changed to @code{make install check} for GNUnet.
@cindex TESTING library
-@node GNUnet's TESTING library
-@section GNUnet's TESTING library
+@node TESTING library
+@section TESTING library
The TESTING library is used for writing testcases which involve starting a
single or multiple peers. While peers can also be started by testcases
latest stable release or check out Gauger's Subversion repository.
@cindex TESTBED Subsystem
-@node GNUnet's TESTBED Subsystem
-@section GNUnet's TESTBED Subsystem
+@node TESTBED Subsystem
+@section TESTBED Subsystem
The TESTBED subsystem facilitates testing and measuring of multi-peer
deployments on a single host or over multiple hosts.
* Message Queue API::
* Service API::
* Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps::
-* The CONTAINER_MDLL API::
+* CONTAINER_MDLL API::
@end menu
@cindex Logging
@cindex CONTAINER_MDLL API
-@node The CONTAINER_MDLL API
-@subsection The CONTAINER_MDLL API
+@node CONTAINER_MDLL API
+@subsection CONTAINER_MDLL API
@c %**end of header
This text documents the GNUNET_CONTAINER_MDLL API. The
@cindex Automatic Restart Manager
@cindex ARM
-@node The Automatic Restart Manager (ARM)
-@section The Automatic Restart Manager (ARM)
+@node Automatic Restart Manager (ARM)
+@section Automatic Restart Manager (ARM)
@c %**end of header
GNUnet's Automated Restart Manager (ARM) is the GNUnet service responsible
@end itemize
@cindex TRANSPORT Subsystem
-@node GNUnet's TRANSPORT Subsystem
-@section GNUnet's TRANSPORT Subsystem
+@node TRANSPORT Subsystem
+@section TRANSPORT Subsystem
@c %**end of header
This chapter documents how the GNUnet transport subsystem works. The
the P2P transmissions, but a successful attacker could at least measure
traffic volumes and latencies (raising the adversaries capablities by
those of a global passive adversary in the worst case). The scenarios we
-are concerned about is an attacker, Mallory, giving a HELLO to Alice that
-claims to be for Bob, but contains Mallory's IP address instead of Bobs
-(for some transport). Mallory would then forward the traffic to Bob (by
-initiating a connection to Bob and claiming to be Alice). As a further
+are concerned about is an attacker, Mallory, giving a @code{HELLO} to
+Alice that claims to be for Bob, but contains Mallory's IP address
+instead of Bobs (for some transport).
+Mallory would then forward the traffic to Bob (by initiating a
+connection to Bob and claiming to be Alice). As a further
complication, the scheme has to work even if say Alice is behind a NAT
-without traversal support and hence has no address of their own (and thus
+without traversal support and hence has no address of her own (and thus
Alice must always initiate the connection to Bob).
-An additional constraint is that HELLO messages do not contain a
+An additional constraint is that @code{HELLO} messages do not contain a
cryptographic signature since other peers must be able to edit
-(i.e. remove) addresses from the HELLO at any time (this was not true in
-GNUnet 0.8.x). A basic @strong{assumption} is that each peer knows the
-set of possible network addresses that it @strong{might} be reachable
-under (so for example, the external IP address of the NAT plus the LAN
-address(es) with the respective ports).
+(i.e. remove) addresses from the @code{HELLO} at any time (this was
+not true in GNUnet 0.8.x). A basic @strong{assumption} is that each peer
+knows the set of possible network addresses that it @strong{might}
+be reachable under (so for example, the external IP address of the
+NAT plus the LAN address(es) with the respective ports).
The solution is the following. If Alice wants to validate that a given
address for Bob is valid (i.e. is actually established @strong{directly}
-with the intended target), it sends a PING message over that connection
+with the intended target), she sends a PING message over that connection
to Bob. Note that in this case, Alice initiated the connection so only
-Alice knows which address was used for sure (Alice maybe behind NAT, so
-whatever address Bob sees may not be an address Alice knows they have).
-Bob
-checks that the address given in the PING is actually one of Bob's
-addresses
-(does not belong to Mallory), and if it is, sends back a PONG (with a
-signature that says that Bob owns/uses the address from the PING). Alice
-checks the signature and is happy if it is valid and the address in the
-PONG is the address Alice used.
-This is similar to the 0.8.x protocol where the HELLO contained a
+Alice knows which address was used for sure (Alice may be behind NAT, so
+whatever address Bob sees may not be an address Alice knows she has).
+Bob checks that the address given in the @code{PING} is actually one
+of Bob's addresses (ie: does not belong to Mallory), and if it is,
+sends back a @code{PONG} (with a signature that says that Bob
+owns/uses the address from the @code{PING}).
+Alice checks the signature and is happy if it is valid and the address
+in the @code{PONG} is the address Alice used.
+This is similar to the 0.8.x protocol where the @code{HELLO} contained a
signature from Bob for each address used by Bob.
Here, the purpose code for the signature is
@code{GNUNET_SIGNATURE_PURPOSE_TRANSPORT_PONG_OWN}. After this, Alice will
considered 'established'. In particular, Alice may have many addresses
for Bob that Alice considers valid.
-The PONG message is protected with a nonce/challenge against replay
-attacks and uses an expiration time for the signature (but those are
-almost implementation details).
+@c TODO: reference Footnotes so that I don't have to duplicate the
+@c footnotes or add them to an index at the end. Is this possible at
+@c all in Texinfo?
+The @code{PONG} message is protected with a nonce/challenge against replay
+attacks@footnote{@uref{http://en.wikipedia.org/wiki/Replay_attack, replay}}
+and uses an expiration time for the signature (but those are almost
+implementation details).
@cindex NAT library
@node NAT library
destination).
Assume a three peer network with peers Alice, Bob and Carol. Assume that
-Alice <-> Bob and Bob <-> Carol are direct (e.g. over TCP or UDP
-transports) connections, but that Alice cannot directly connect to Carol.
+
+@example
+Alice <-> Bob and Bob <-> Carol
+@end example
+
+@noindent
+are direct (e.g. over TCP or UDP transports) connections, but that
+Alice cannot directly connect to Carol.
This may be the case due to NAT or firewall restrictions, or perhaps
based on one of the peers respective configurations. If the Distance
Vector transport is enabled on all three peers, it will automatically
looks up Carol in the routing table and finds that the message must be
sent through Bob for Carol. The message is encapsulated setting Alice as
the initiator and Carol as the destination and sent to Bob. Bob receives
-the messages, verifies both Alice and Carol are known to Bob, and re-wraps
-the message in a new DV message for Carol. The DV transport at Carol
-receives this message, unwraps the original message, and delivers it to
-Carol as though it came directly from Alice.
+the messages, verifies that both Alice and Carol are known to Bob, and
+re-wraps the message in a new DV message for Carol.
+The DV transport at Carol receives this message, unwraps the original
+message, and delivers it to Carol as though it came directly from Alice.
@cindex SMTP plugin
@node SMTP plugin
@subsection What do I need to use the Bluetooth plugin transport?
@c %**end of header
-If you are a Linux user and you want to use the Bluetooth transport plugin
-you should install the BlueZ development libraries (if they aren't already
-installed). For instructions about how to install the libraries you should
+If you are a GNU/Linux user and you want to use the Bluetooth
+transport plugin you should install the
+@command{BlueZ development libraries} (if they aren't already
+installed).
+For instructions about how to install the libraries you should
check out the BlueZ site
(@uref{http://www.bluez.org/, http://www.bluez.org}). If you don't know if
you have the necesarry libraries, don't worry, just run the GNUnet
plugin and only the helper binary is different. The helper takes a single
argument, which represents the interface name and is specified in the
configuration file. Here are the basic steps that are followed by the
-helper binary used on Linux:
+helper binary used on GNU/Linux:
@itemize @bullet
@item it verifies if the name corresponds to a Bluetooth interface name
@subsection What possible errors should I be aware of?
@c %**end of header
-@emph{This section is dedicated for Linux users}
+@emph{This section is dedicated for GNU/Linux users}
Well there are many ways in which things could go wrong but I will try to
present some tools that you could use to debug and some scenarios.
@subsection How do I configure my peer2?
@c %**end of header
-On Linux, you just have to be sure that the interface name corresponds to
-the one that you want to use. Use the @code{hciconfig} tool to check that.
+On GNU/Linux, you just have to be sure that the interface name
+corresponds to the one that you want to use.
+Use the @code{hciconfig} tool to check that.
By default it is set to hci0 but you can change it.
A basic configuration looks like this:
@subsection How can I test it?
@c %**end of header
-If you have two Bluetooth devices on the same machine which use Linux you
-must:
+If you have two Bluetooth devices on the same machine and you are using
+GNU/Linux you must:
@itemize @bullet
directions between the Bluetooth interface and stdin/stdout of the
process involved.
-The Bluetooth plugin transport could be used both on Linux and Windows
+The Bluetooth plugin transport could be used both on GNU/Linux and Windows
platforms.
@itemize @bullet
@subsubsection Linux functionality
@c %**end of header
-In order to implement the plugin functionality on Linux I used the BlueZ
-stack. For the communication with the other devices I used the RFCOMM
+In order to implement the plugin functionality on GNU/Linux I
+used the BlueZ stack.
+For the communication with the other devices I used the RFCOMM
protocol. Also I used the HCI protocol to gain some control over the
device. The helper binary takes a single argument (the name of the
Bluetooth interface) and is separated in two stages:
(especially the @emph{ws2bth} header).
Besides the fact that it uses the Windows Sockets, the Windows
-implemenation follows the same principles as the Linux one:
+implemenation follows the same principles as the GNU/Linux one:
@itemize @bullet
@item It has a initalization part where it initializes the
and I generated the @emph{Universally Unique Identifier} with the
@emph{guidgen.exe} Windows's tool.
-In the loop section the only difference from the Linux implementation is
-that I used the GNUNET_NETWORK library for functions like @emph{accept},
-@emph{bind}, @emph{connect} or @emph{select}. I decided to use the
-GNUNET_NETWORK library because I also needed to interact with the STDIN
-and STDOUT handles and on Windows the select function is only defined for
-sockets, and it will not work for arbitrary file handles.
+In the loop section the only difference from the GNU/Linux implementation
+is that I used the @code{GNUNET_NETWORK} library for
+functions like @emph{accept}, @emph{bind}, @emph{connect} or
+@emph{select}. I decided to use the
+@code{GNUNET_NETWORK} library because I also needed to interact
+with the STDIN and STDOUT handles and on Windows
+the select function is only defined for sockets,
+and it will not work for arbitrary file handles.
-Another difference between Linux and Windows implementation is that in
-Linux, the Bluetooth address is represented in 48 bits while in Windows is
-represented in 64 bits. Therefore I had to do some changes on
-@emph{plugin_transport_wlan} header.
+Another difference between GNU/Linux and Windows implementation is that in
+GNU/Linux, the Bluetooth address is represented in 48 bits
+while in Windows is represented in 64 bits.
+Therefore I had to do some changes on @emph{plugin_transport_wlan} header.
Also, currently on Windows the Bluetooth plugin doesn't have support for
broadcast messages. When it receives a broadcast message it will skip it.
are not implemented yet or could be better implemented are described at
the end.
-@cindex ats subsystem
-@node The ATS Subsystem
-@section The ATS Subsystem
+@cindex ATS Subsystem
+@node ATS Subsystem
+@section ATS Subsystem
@c %**end of header
ATS stands for "automatic transport selection", and the function of ATS in
maturity, and it is still unclear if any particular plugin is generally
superior.
-@cindex core subsystem
-@cindex CORE subsystem
-@node GNUnet's CORE Subsystem
-@section GNUnet's CORE Subsystem
+@cindex CORE Subsystem
+@node CORE Subsystem
+@section CORE Subsystem
@c %**end of header
The CORE subsystem in GNUnet is responsible for securing link-layer
(with the correct hash of the type map) is not received, the sender will
retransmit the type map (with exponential back-off).
-@cindex cadet subsystem
-@cindex CADET
-@node GNUnet's CADET subsystem
-@section GNUnet's CADET subsystem
+@cindex CADET Subsystem
+@node CADET Subsystem
+@section CADET Subsystem
The CADET subsystem in GNUnet is responsible for secure end-to-end
communications between nodes in the GNUnet overlay network. CADET builds
@code{GNUNET_CADET_disconnect}, but first all channels and pending
transmissions must be closed (otherwise CADET will complain).
-@cindex nse subsystem
-@cindex NSE
-@node GNUnet's NSE subsystem
-@section GNUnet's NSE subsystem
+@cindex NSE Subsystem
+@node NSE Subsystem
+@section NSE Subsystem
NSE stands for @dfn{Network Size Estimation}. The NSE subsystem provides
the neighbors there is a random delay added for each neighbor, to avoid
traffic spikes and minimize cross-messages.
-@cindex HOSTLIST subsystem
-@cindex hostlist subsystem
-@node GNUnet's HOSTLIST subsystem
-@section GNUnet's HOSTLIST subsystem
+@cindex HOSTLIST Subsystem
+@node HOSTLIST Subsystem
+@section HOSTLIST Subsystem
@c %**end of header
Configuring the hostlist to bootstrap@
Configuring your peer to provide a hostlist
-@cindex IDENTITY
-@cindex identity subsystem
-@node GNUnet's IDENTITY subsystem
-@section GNUnet's IDENTITY subsystem
+@cindex IDENTITY Subsystem
+@node IDENTITY Subsystem
+@section IDENTITY Subsystem
@c %**end of header
containing the respective information, or with a RESULT_CODE to
indicate an error.
-@cindex NAMESTORE
-@cindex namestore subsystem
-@node GNUnet's NAMESTORE Subsystem
-@section GNUnet's NAMESTORE Subsystem
+@cindex NAMESTORE Subsystem
+@node NAMESTORE Subsystem
+@section NAMESTORE Subsystem
The NAMESTORE subsystem provides persistent storage for local GNS zone
information. All local GNS zone information are managed by NAMESTORE. It
@code{GNUNET_NAMESTORE_zone_monitor_stop} and passes the handle obtained
from the function to start the monitoring.
-@cindex PEERINFO
-@cindex peerinfo subsystem
-@node GNUnet's PEERINFO subsystem
-@section GNUnet's PEERINFO subsystem
+@cindex PEERINFO Subsystem
+@node PEERINFO Subsystem
+@section PEERINFO Subsystem
@c %**end of header
about changes. The function returns a handle to cancel notifications
with @code{GNUNET_PEERINFO_notify_cancel}.
-@cindex PEERSTORE subsystem
-@node GNUnet's PEERSTORE subsystem
-@section GNUnet's PEERSTORE subsystem
+@cindex PEERSTORE Subsystem
+@node PEERSTORE Subsystem
+@section PEERSTORE Subsystem
@c %**end of header
destroyed as well.
@cindex SET Subsystem
-@node GNUnet's SET Subsystem
-@section GNUnet's SET Subsystem
+@node SET Subsystem
+@section SET Subsystem
@c %**end of header
into buckets, such that future iterations have a fresh chance of
succeeding if they failed due to collisions before.
-@cindex STATISTICS subsystem
-@node GNUnet's STATISTICS subsystem
-@section GNUnet's STATISTICS subsystem
+@cindex STATISTICS Subsystem
+@node STATISTICS Subsystem
+@section STATISTICS Subsystem
@c %**end of header
@cindex DHT
@cindex Distributed Hash Table
-@node GNUnet's Distributed Hash Table (DHT)
-@section GNUnet's Distributed Hash Table (DHT)
+@node Distributed Hash Table (DHT)
+@section Distributed Hash Table (DHT)
@c %**end of header
The DHT service may also cache forwarded results locally if the
"CACHE_RESULTS" option is set to "YES" in the configuration.
-@node The GNU Name System (GNS)
-@section The GNU Name System (GNS)
+@cindex GNS
+@cindex GNU Name System
+@node GNU Name System (GNS)
+@section GNU Name System (GNS)
@c %**end of header
sending queries to a DNS server directly by themselves).
This includes some of well known utilities, like "ping" and "nslookup".
-@node The GNS Namecache
-@section The GNS Namecache
+@cindex GNS Namecache
+@node GNS Namecache
+@section GNS Namecache
@c %**end of header
for the most recent expiration time during lookup, or by checking which
block is more recent during the store operation.
-@node The REVOCATION Subsystem
-@section The REVOCATION Subsystem
+@cindex REVOCATION Subsystem
+@node REVOCATION Subsystem
+@section REVOCATION Subsystem
@c %**end of header
The REVOCATION subsystem is responsible for key revocation of Egos.
this operation once after establishing a connection to a peer with a
larger hashed peer identity.
-@cindex gnunet-fs
@cindex FS
-@cindex FS subsystem
-@node GNUnet's File-sharing (FS) Subsystem
-@section GNUnet's File-sharing (FS) Subsystem
+@cindex FS Subsystem
+@node File-sharing (FS) Subsystem
+@section File-sharing (FS) Subsystem
@c %**end of header
* File-sharing persistence directory structure::
@end menu
-@cindex ecrs
+@cindex ECRS
@cindex Encoding for Censorship-Resistant Sharing
@node Encoding for Censorship-Resistant Sharing (ECRS)
@subsection Encoding for Censorship-Resistant Sharing (ECRS)
Note that unindex operations cannot have associated child operations.
@cindex REGEX subsystem
-@cindex regex subsystem
-@node GNUnet's REGEX Subsystem
-@section GNUnet's REGEX Subsystem
+@node REGEX Subsystem
+@section REGEX Subsystem
@c %**end of header
@node GNUnet Installation Handbook
@chapter GNUnet Installation Handbook
-This handbook describes how to install (build setup, compilation) and
-setup (configuration, start) GNUnet 0.10.x. After following these
+This handbook describes how to install (build, setup, compile) and
+setup (configure, start) GNUnet @value{VERSION}. After following these
instructions you should be able to install and then start user-interfaces
to interact with the network.
-This manual is far from complete, and we welcome informed contributions,
-be it in the form of new chapters or insightful comments.
+Note: This manual is far from complete, and we welcome informed
+contributions, be it in the form of new chapters or insightful comments.
@menu
* Dependencies::
* Pre-installation notes::
* Generic installation instructions::
* Build instructions for Ubuntu 12.04 using Git::
+* Build instructions for software builds from source::
* Build Instructions for Microsoft Windows Platforms::
* Build instructions for Debian 7.5::
* Installing GNUnet from Git on Ubuntu 14.4::
@menu
* External dependencies::
-* Fixing libgnurl build issues::
* Optional dependencies::
* Internal dependencies::
@end menu
@item miniupnpc
@item gettext
@item which
-@item texinfo
+@item texinfo @geq{} 5.2
@item GNU libmicrohttpd @geq{} 0.9.30 @footnote{We recommend to build it
with a GnuTLS version that was configured with libunbound}
@item GNU libextractor @geq{} 1.0
@item zlib
@end itemize
-@node Fixing libgnurl build issues
-@subsection Fixing libgnurl build issues
-
-If you have to compile libgnurl from source since the version included in
-your distribution is to old you perhaps get an error message while
-running the @file{configure} script:
-
-@example
-$ configure
-...
-checking for 64-bit curl_off_t data type... unknown
-checking for 32-bit curl_off_t data type... unknown
-checking for 16-bit curl_off_t data type... unknown
-configure: error: cannot find data type for curl_off_t.
-@end example
-
-@noindent
-Solution:
-
-Before running the configure script, set:
-
-@example
-CFLAGS="-I. -I$BUILD_ROOT/include"
-@end example
-
@node Optional dependencies
@subsection Optional dependencies
These applications must be installed for various experimental or otherwise
-optional features such as @code{gnunet-conversation}, @code{gnunet-gtk}.
+optional features such as @command{gnunet-conversation},
+and @command{gnunet-gtk} (most of these features are only build if you
+configure GNUnet with @command{--enable-experimental}):
@itemize @bullet
-@item libpulse 2.0 or higher, optional (for gnunet-conversation)
-@item libopus 1.0.1 or higher, optional (for gnunet-conversation)
-@item libogg 1.3.0 or higher, optional (for gnunet-conversation)
-@item certool (binary) optional @footnote{for convenient installation of
-the GNS proxy (available as part of Debian's libnss3-tools)}
-@item python-zbar 0.10 or higher, optional (for gnunet-qr)
-@item Gtk+ 3.0 or higher, optional (for gnunet-gtk)
-@item libgladeui must match Gtk+ version, optional (for gnunet-gtk)
-@item libqrencode 3.0 or higher, optional (for gnunet-namestore-gtk)
+@item libpulse @geq{} 2.0,
+optional (for @command{gnunet-conversation})
+@item libopus @geq{} 1.0.1,
+optional (for @command{gnunet-conversation})
+@item libogg @geq{} 1.3.0,
+optional (for @command{gnunet-conversation})
+@item libnss contained @command{certool} binary,
+optional for convenient installation of
+the GNS proxy.
+@item python-zbar @geq{} 0.10,
+optional (for @command{gnunet-qr})
+@item Gtk+ @geq{} 3.0,
+optional (for @command{gnunet-gtk})
+@item libgladeui (must match Gtk+ version),
+optional (for @command{gnunet-gtk})
+@item libqrencode @geq{} 3.0,
+optional (for @command{gnunet-namestore-gtk})
@end itemize
@node Internal dependencies
This section tries to give an overview of what processes a typical GNUnet
peer running a particular application would consist of. All of the
processes listed here should be automatically started by
-@code{gnunet-arm -s}.
+@command{gnunet-arm -s}.
The list is given as a rough first guide to users for failure diagnostics.
Ideally, end-users should never have to worry about these internal
-dependencies.
+dependencies.
+
In terms of internal dependencies, a minimum file-sharing system consists
of the following GNUnet processes (in order of dependency):
database (MySQL, sqlite or Postgres).
The following instructions will assume that you installed at least sqlite.
For most distributions you should be able to find pre-build packages for
-the database. Again, make sure to install the client libraries and the
+the database. Again, make sure to install the client libraries @b{and} the
respective development headers (if they are packaged separately) as well.
You can find specific, detailed instructions for installing of the
dependencies (and possibly the rest of the GNUnet installation) in the
platform-specific descriptions, which can be found in the Index.
Please consult them now.
-If your distribution is not listed, please study the instructions for
-Debian stable carefully as you try to install the dependencies for your
+If your distribution is not listed, please study
+@ref{Build instructions for Debian 8}, the build instructions for
+Debian stable, carefully as you try to install the dependencies for your
own distribution.
Contributing additional instructions for further platforms is always
appreciated.
Please take in mind that operating system development tends to move at
a rather fast speed. Due to this you should be aware that some of
-the instructionss could be outdated by the time you are reading this.
+the instructions could be outdated by the time you are reading this.
If you find a mistake, please tell us about it (or even better: send
a patch to the documentation to fix it!).
access, we will assume that you have full control over your system in
these instructions.
First, you should create a system user @emph{gnunet} and an additional
-group @emph{gnunetdns}. On Debian and Ubuntu GNU/Linux, type:
+group @emph{gnunetdns}. On the GNU/Linux distributions Debian and Ubuntu,
+type:
@example
# adduser --system --home /var/lib/gnunet --group \
@end example
@noindent
-On other Unixes, this should have the same effect:
+On other Unixes and GNU systems, this should have the same effect:
@example
# useradd --system --groups gnunet --home-dir /var/lib/gnunet
Now compile and install GNUnet using:
@example
-$ tar xvf gnunet-0.10.?.tar.gz
-$ cd gnunet-0.10.?
+$ tar xvf gnunet-@value{VERSION}.tar.gz
+$ cd gnunet-@value{VERSION}
$ ./configure --with-sudo=sudo --with-nssdir=/lib
$ make
$ sudo make install
If you want to be able to enable DEBUG-level log messages, add
@code{--enable-logging=verbose} to the end of the
-@code{./configure} command.
-DEBUG-level log messages are in English-only and should only be useful for
-developers (or for filing really detailed bug reports).
+@command{./configure} command.
+@code{DEBUG}-level log messages are in English only and
+should only be useful for developers (or for filing
+really detailed bug reports).
-Finally, you probably want to compile @code{gnunet-gtk}, which
-includes gnunet-setup (graphical tool for configuration)
-and @code{gnunet-fs-gtk} (graphical tool for file-sharing):
+Finally, you probably want to compile @command{gnunet-gtk}, which
+includes @command{gnunet-setup} (a graphical tool for
+GNUnet configuration) and @command{gnunet-fs-gtk} (a graphical tool for
+GNUnet file-sharing):
@example
-$ tar xvf gnunet-gtk-0.10.?.tar.gz
-$ cd gnunet-gtk-0.10.?
+$ tar xvf gnunet-gtk-@value{VERSION}.tar.gz
+$ cd gnunet-gtk-@value{VERSION}
$ ./configure --with-gnunet=/usr/local/
$ make
$ sudo make install
@end example
@noindent
-You may need to update your ld.so cache to include files installed in
-@file{/usr/local/lib}:
+You may need to update your @code{ld.so} cache to include
+files installed in @file{/usr/local/lib}:
@example
# ldconfig
@end example
@noindent
-Then, switch from user root to user gnunet to start the peer:
+Then, switch from user @code{root} to user @code{gnunet} to start
+the peer:
@example
# su -s /bin/sh - gnunet
$ gnunet-arm -c /etc/gnunet.conf -s
@end example
-You may also want to add the last line in the gnunet users @file{crontab}
+You may also want to add the last line in the gnunet user's @file{crontab}
prefixed with @code{@@reboot} so that it is executed whenever the system
is booted:
@example
-@@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s@
+@@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s
@end example
@noindent
This will only start the system-wide GNUnet services.
Type exit to get back your root shell.
Now, you need to configure the per-user part. For each
-$USER on the system, run:
+$USER that should get access to GNUnet on the system, run:
@example
# adduser $USER gnunet
to specify a different port number in their personal configuration file.
Finally, the user should perform the basic initial setup for the GNU Name
-System. This is done by running two commands:
+System (GNS). This is done by running two commands:
@example
$ gnunet-gns-import.sh
@noindent
The first generates the default zones, wheras the second setups the GNS
-Certificate Authority with the user's browser. Now, to actiave GNS in the
+Certificate Authority with the user's browser. Now, to activate GNS in the
normal DNS resolution process, you need to edit your
@file{/etc/nsswitch.conf} where you should find a line like this:
@node Build instructions for Ubuntu 12.04 using Git
@section Build instructions for Ubuntu 12.04 using Git
-
@menu
* Install the required build tools::
* Install libgcrypt 1.6 and libgpg-error::
@node Install libgcrypt 1.6 and libgpg-error
@subsection Install libgcrypt 1.6 and libgpg-error
-@example
-$ wget ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2
-$ tar xf libgpg-error-1.12.tar.bz2
-$ cd libgpg-error-1.12
-$ ./configure
-$ sudo make install ; cd ..
-@end example
+@ref{generic source installation - libgpg-error}
@node Install gnutls with DANE support
@subsection Install gnutls with DANE support
-@example
-$ wget http://www.lysator.liu.se/~nisse/archive/nettle-2.7.1.tar.gz
-$ tar xf nettle-2.7.1.tar.gz
-$ cd nettle-2.7.1
-$ ./configure
-$ sudo make install ; cd ..
-@end example
-
-@example
-$ wget https://www.nlnetlabs.nl/downloads/ldns/ldns-1.6.16.tar.gz
-$ tar xf ldns-1.6.16.tar.gz
-$ cd ldns-1.6.16
-$ ./configure
-$ sudo make install ; cd ..
-@end example
-
-@example
-$ wget https://unbound.net/downloads/unbound-1.4.21.tar.gz
-$ tar xf unbound-1.4.21.tar.gz
-$ cd unbound-1.4.21
-$ ./configure
-$ sudo make install ; cd ..
-@end example
-
-@example
-$ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.1/gnutls-3.1.17.tar.xz
-$ tar xf gnutls-3.1.17.tar.xz
-$ cd gnutls-3.1.17
-$ ./configure
-$ sudo make install ; cd ..
-@end example
-
-@example
-$ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2
-$ tar xf libgcrypt-1.6.0.tar.bz2
-$ cd libgcrypt-1.6.0
-$ ./configure
-$ sudo make install ; cd ..
-@end example
+@itemize @bullet
+@item @ref{generic source installation - nettle}
+@item @ref{generic source installation - ldns}
+@item @ref{generic source installation - libunbound/unbound}
+@item @ref{generic source installation - gnutls}
+@item @ref{generic source installation - libgcrypt}
+@end itemize
@node Install libgnurl
@subsection Install libgnurl
-@example
-$ wget https://gnunet.org/sites/default/files/gnurl-7.34.0.tar.bz2
-$ tar xf gnurl-7.34.0.tar.bz2
-$ cd gnurl-7.34.0
-$ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
- --without-libmetalink --without-winidn --without-librtmp \
- --without-nghttp2 --without-nss --without-cyassl \
- --without-polarssl --without-ssl --without-winssl \
- --without-darwinssl --disable-sspi --disable-ntlm-wb \
- --disable-ldap --disable-rtsp --disable-dict --disable-telnet \
- --disable-tftp --disable-pop3 --disable-imap --disable-smtp \
- --disable-gopher --disable-file --disable-ftp
-$ sudo make install ; cd ..
-@end example
+Follow the @ref{generic source installation - libgnurl}.
@node Install libmicrohttpd from Git
@subsection Install libmicrohttpd from Git
@end example
Use the required configure call including the optional installation prefix
-PREFIX or the sudo permissions:
+@code{PREFIX} or the sudo permissions:
@example
$ ./configure [ --with-sudo | --with-prefix=PREFIX ]
@example
$ sudo apt-get install libgtk-3-dev libunique-3.0-dev libgladeui-dev \
-libqrencode-dev
+ libqrencode-dev
@end example
-To build GNUnet (with an optional prefix)and execute:
+Build GNUnet (with an optional prefix) and execute:
@example
$ git clone https://gnunet.org/git/gnunet-gtk/
$ make; sudo make install
@end example
+@node Build instructions for software builds from source
+@section Build instructions for software builds from source
+
+This section describes software builds in case your operating
+system lacks binary substitutes / binary builds for some dependencies
+of GNUnet.
+It is assumed that you have installed common build dependencies
+and that these instructions are treated as generic without any
+debugging help.
+It is furthermore assumed that you use the release tarballs of
+the software, installation from the respective version control
+sources might differ in ways that are only minimal different
+(for example a dependency on autotools etc).
+
+@menu
+* generic source installation - nettle::
+* generic source installation - ldns::
+* generic source installation - libunbound/unbound::
+* generic source installation - libav::
+* generic source installation - libextractor::
+* generic source installation - libgpg-error::
+* generic source installation - libgcrypt::
+* generic source installation - gnutls::
+* generic source installation - libmicrohttpd::
+* generic source installation - libgnurl::
+@end menu
+
+@node generic source installation - nettle
+@subsection generic source installation - nettle
+@example
+$ wget http://www.lysator.liu.se/~nisse/archive/nettle-2.7.1.tar.gz
+$ tar xf nettle-2.7.1.tar.gz
+$ cd nettle-2.7.1
+$ ./configure
+$ sudo make install ; cd ..
+@end example
+
+@node generic source installation - ldns
+@subsection generic source installation - ldns
+@example
+$ wget https://www.nlnetlabs.nl/downloads/ldns/ldns-1.6.16.tar.gz
+$ tar xf ldns-1.6.16.tar.gz
+$ cd ldns-1.6.16
+$ ./configure
+$ sudo make install ; cd ..
+@end example
+
+@node generic source installation - libunbound/unbound
+@subsection generic source installation - libunbound/unbound
+@example
+$ wget https://unbound.net/downloads/unbound-1.4.21.tar.gz
+$ tar xf unbound-1.4.21.tar.gz
+$ cd unbound-1.4.21
+$ ./configure
+$ sudo make install ; cd ..
+@end example
+
+@node generic source installation - libav
+@subsection generic source installation - libav
+@example
+$ wget https://libav.org/releases/libav-9.10.tar.xz
+$ cd libav-0.9 ; ./configure --enable-shared;
+$ make; sudo make install; cd ..
+@end example
+
+@node generic source installation - libextractor
+@subsection generic source installation - libextractor
+@example
+$ wget https://ftp.gnu.org/gnu/libextractor/libextractor-1.3.tar.gz
+$ tar xvf libextractor-1.3.tar.gz
+$ cd libextractor-1.3 ; ./configure;
+$ make ; sudo make install; cd ..
+@end example
+
+@node generic source installation - libgpg-error
+@subsection generic source installation - libgpg-error
+@example
+$ wget https://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2
+$ tar xvf libgpg-error-1.12.tar.bz2
+$ cd libgpg-error-1.12; ./configure;
+$ make ; sudo make install; cd ..
+@end example
+
+@node generic source installation - libgcrypt
+@subsection generic source installation - libgcrypt
+@example
+$ wget https://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2
+$ tar xvf libgcrypt-1.6.0.tar.bz2
+$ cd libgcrypt-1.6.0; ./configure --with-gpg-error-prefix=/usr/local;
+$ make ; sudo make install ; cd ..
+@end example
+
+@node generic source installation - gnutls
+@subsection generic source installation - gnutls
+@example
+$ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.2/gnutls-3.2.7.tar.xz
+$ tar xvf gnutls-3.2.7.tar.xz
+$ cd gnutls-3.2.7 ; ./configure;
+$ make ; sudo make install ; cd ..
+@end example
+
+@noindent
+If you want a GnuTLS with DANE functionality, you have to compile
+it against libunbound.
+
+@node generic source installation - libmicrohttpd
+@subsection generic source installation - libmicrohttpd
+@example
+$ wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.33.tar.gz
+$ tar xvf libmicrohttpd-0.9.33.tar.gz
+$ cd libmicrohttpd-0.9.33; ./configure;
+$ make ; sudo make install ; cd ..
+@end example
+
+@node generic source installation - libgnurl
+@subsection generic source installation - libgnurl
+
+@example
+$ wget https://gnunet.org/sites/default/files/gnurl-7.34.0.tar.bz2
+$ tar xvf gnurl-7.34.0.tar.bz2
+$ cd gnurl-7.34.0
+$ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \
+ --without-libmetalink --without-winidn --without-librtmp \
+ --without-nghttp2 --without-nss --without-cyassl --without-polarssl \
+ --without-ssl --without-winssl --without-darwinssl --disable-sspi \
+ --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \
+ --disable-telnet --disable-tftp --disable-pop3 --disable-imap \
+ --disable-smtp --disable-gopher --disable-file --disable-ftp
+$ make ; sudo make install; cd ..
+@end example
+
+@menu
+* Fixing libgnurl build issues::
+@end menu
+
+@node Fixing libgnurl build issues
+@subsubsection Fixing libgnurl build issues
+
+@c FIXME: Obviously this subsection should be evaluated and
+@c if still necessary moved into gnURL itself (README) or
+@c into a separate section which deals with gnURL.
+If you have to compile libgnurl from source (for example if the version
+included in your distribution is too old or it's not included at all)
+you perhaps might get an error message while running the
+@command{configure} script:
+
+@example
+$ configure
+...
+checking for 64-bit curl_off_t data type... unknown
+checking for 32-bit curl_off_t data type... unknown
+checking for 16-bit curl_off_t data type... unknown
+configure: error: cannot find data type for curl_off_t.
+@end example
+
+@noindent
+Solution:
+
+Before running the @command{configure} script, set:
+
+@example
+CFLAGS="-I. -I$BUILD_ROOT/include"
+@end example
+
@node Build Instructions for Microsoft Windows Platforms
@section Build Instructions for Microsoft Windows Platforms
@strong{non-server version can not run a VPN-Exit-Node} as the NAT
features have been removed as of Windows Vista.
+@c TODO: We should document Windows 10!
+@c It seems like the situation hasn't changed with W10
+
@node Dependencies & Initial Setup
@subsection Dependencies & Initial Setup
@item
Install a fresh version of @strong{Python 2.x}, even if you are using a
x64-OS, install a 32-bit version for use with sbuild.
-Python 3.0 currently is incompatible.
+Python 3.0 is currently incompatible.
@item
-Install your favorite @uref{http://code.google.com/p/tortoisegit/, GIT} &
-@uref{http://tortoisesvn.net/, SVN}-clients.
+Install your favorite @uref{http://code.google.com/p/tortoisegit/, git} &
+@uref{http://tortoisesvn.net/, subversion}-clients.
@item
You will also need some archive-manager like
@code{make install} steps as root (hence the @code{sudo} in the
commands below). Also, you do this from any
directory. We begin by downloading all dependencies, then extracting the
-sources, and finally compiling and installing the libraries:@
+sources, and finally compiling and installing the libraries.
-@example
-$ wget https://libav.org/releases/libav-9.10.tar.xz
-$ wget http://ftp.gnu.org/gnu/libextractor/libextractor-1.3.tar.gz
-$ wget ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2
-$ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2
-$ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.2/gnutls-3.2.7.tar.xz
-$ wget http://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.33.tar.gz
-$ wget https://gnunet.org/sites/default/files/gnurl-7.34.0.tar.bz2
-$ tar xvf libextractor-1.3.tar.gz
-$ tar xvf libgpg-error-1.12.tar.bz2
-$ tar xvf libgcrypt-1.6.0.tar.bz2
-$ tar xvf gnutls-3.2.7.tar.xz
-$ tar xvf libmicrohttpd-0.9.33.tar.gz
-$ tar xvf gnurl-7.34.0.tar.bz2
-$ cd libav-0.9 ; ./configure --enable-shared;
-$ make; sudo make install; cd ..
-$ cd libextractor-1.3 ; ./configure;
-$ make ; sudo make install; cd ..
-$ cd libgpg-error-1.12; ./configure;
-$ make ; sudo make install; cd ..
-$ cd libgcrypt-1.6.0; ./configure --with-gpg-error-prefix=/usr/local;
-$ make ; sudo make install ; cd ..
-$ cd gnutls-3.2.7 ; ./configure;
-$ make ; sudo make install ; cd ..
-$ cd libmicrohttpd-0.9.33; ./configure;
-$ make ; sudo make install ; cd ..
-$ cd gnurl-7.34.0
-$ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \
- --without-libmetalink --without-winidn --without-librtmp \
- --without-nghttp2 --without-nss --without-cyassl --without-polarssl \
- --without-ssl --without-winssl --without-darwinssl --disable-sspi \
- --disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \
- --disable-telnet --disable-tftp --disable-pop3 --disable-imap \
- --disable-smtp --disable-gopher --disable-file --disable-ftp
-$ make ; sudo make install; cd ..
-@end example
+For these steps, follow the instructions given in the
+installation from source instruction in this order:
+
+@itemize @bullet
+@item @ref{generic source installation - libav}
+@item @ref{generic source installation - libextractor}
+@item @ref{generic source installation - libgpg-error}
+@item @ref{generic source installation - libgcrypt}
+@item @ref{generic source installation - gnutls}
+@item @ref{generic source installation - libmicrohttpd}
+@item @ref{generic source installation - libgnurl}
+@end itemize
@node Installing GNUnet from source
@subsection Installing GNUnet from source
@example
$ wget ftp://ftp.gnutls.org/gcrypt/gnutls/v3.3/gnutls-3.3.12.tar.xz
-$ wget https://gnunet.org/sites/default/files/gnurl-7.40.0.tar.bz2
$ tar xvf gnutls-3.3.12.tar.xz
-$ tar xvf gnurl-7.40.0.tar.bz2
$ cd gnutls-3.3.12 ; ./configure ; make ; sudo make install ; cd ..
-$ cd gnurl-7.40.0
-$ ./configure --enable-ipv6 --with-gnutls=/usr/local --without-libssh2 \
---without-libmetalink --without-winidn --without-librtmp \
---without-nghttp2 --without-nss --without-cyassl --without-polarssl \
---without-ssl --without-winssl --without-darwinssl --disable-sspi \
---disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \
---disable-telnet --disable-tftp --disable-pop3 --disable-imap \
---disable-smtp --disable-gopher --disable-file --disable-ftp \
---disable-smb
-$ make ; sudo make install; cd ..
@end example
+For the installation and compilation of libgnurl/gnURL refer to
+the generic installation section,
+@xref{generic source installation - libgnurl}.
+
@node Installing GNUnet from Source2
@subsection Installing GNUnet from Source2
Install libgnurl:
-@example
-$ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2
-$ tar xf gnurl-7.35.0.tar.bz2
-$ cd gnurl-7.35.0
-$ ./configure --enable-ipv6 --with-gnutls --without-libssh2 \
---without-libmetalink --without-winidn --without-librtmp
---without-nghttp2 --without-nss --without-cyassl --without-polarssl \
---without-ssl --without-winssl --without-darwinssl --disable-sspi \
---disable-ntlm-wb --disable-ldap --disable-rtsp --disable-dict \
---disable-telnet --disable-tftp --disable-pop3 --disable-imap \
---disable-smtp --disable-gopher --disable-file --disable-ftp
-$ sudo make install@
-$ cd ..@
-@end example
+@pxref{generic source installation - libgnurl}.
Install GNUnet:
as it requires a more in-depth understanding of the configuration files
and internal dependencies of GNUnet.
-
@node Configuring the Friend-to-Friend (F2F) mode
@subsection Configuring the Friend-to-Friend (F2F) mode
per friend with the output from the above command.
You then specify the location of your @file{friends} file in the
-"FRIENDS" option of the "topology" section.
+@code{FRIENDS} option of the "topology" section.
Once you have created the @file{friends} file, you can tell GNUnet to only
-connect to your friends by setting the "FRIENDS-ONLY" option (again in
-the "topology" section) to YES.
+connect to your friends by setting the @code{FRIENDS-ONLY} option
+(again in the "topology" section) to YES.
If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a
minimum number of friends to have (before connecting to arbitrary peers)
under the "MINIMUM-FRIENDS" option.
If you want to operate in normal P2P-only mode, simply set
-"MINIMUM-FRIENDS" to zero and "FRIENDS_ONLY" to NO.
+@code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO.
This is the default.
@node Configuring the hostlist to bootstrap
to activate bootstrapping.
To activate bootstrapping, edit the @code{[hostlist]}-section in your
-configuration file. You have to set the argument "-b" in the
+configuration file. You have to set the argument @command{-b} in the
options line:
@example
included. These lists are persistent, which means that they are saved to
your hard disk regularly and are loaded during startup.
-To activate hostlist learning you have to add the "-e" switch to the
-OPTIONS line in the hostlist section:
+To activate hostlist learning you have to add the @command{-e}
+switch to the @code{OPTIONS} line in the hostlist section:
@example
[hostlist]
@noindent
Furthermore you can specify in which file the lists are saved.
-To save the lists in the file "hostlists.file" just add the line:
+To save the lists in the file @file{hostlists.file} just add the line:
@example
HOSTLISTFILE = hostlists.file
The hostlist client can be configured to use a proxy to connect to the
hostlist server.
This functionality can be configured in the configuration file directly
-or using the gnunet-setup tool.
+or using the @command{gnunet-setup} tool.
The hostlist client supports the following proxy types at the moment:
your peer to act as a hostlist server, providing other peers the list of
peers known to him.
-Yor server can act as a bootstrap server and peers needing to obtain a
+Your server can act as a bootstrap server and peers needing to obtain a
list of peers can contact it to download this list.
To download this hostlist the peer uses HTTP.
-For this reason you have to build your peer with libcurl and microhttpd
-support. How you build your peer with this options can be found here:
-@uref{https://gnunet.org/generic_installation}
+For this reason you have to build your peer with libgnurl (or libcurl)
+and microhttpd support.
+How you build your peer with these options can be found here:
+@xref{Generic installation instructions}.
To configure your peer to act as a bootstrap server you have to add the
-@code{-p} option to OPTIONS in the @code{[hostlist]} section of your
-configuration file. Besides that you have to specify a port number for
-the http server.
+@command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section
+of your configuration file.
+Besides that you have to specify a port number for the http server.
In conclusion you have to add the following lines:
@example
Please notice:
@itemize @bullet
-@item The hostlist is not human readable, so you should not try to
+@item The hostlist is @b{not} human readable, so you should not try to
download it using your webbrowser. Just point your GNUnet peer to the
address!
@item Advertising without providing a hostlist does not make sense and
@node Configuring the datastore
@subsection Configuring the datastore
-The datastore is what GNUnet uses to for long-term storage of file-sharing
+The datastore is what GNUnet uses for long-term storage of file-sharing
data. Note that long-term does not mean 'forever' since content does have
an expiration date, and of course storage space is finite (and hence
sometimes content may have to be discarded).
-Use the "QUOTA" option to specify how many bytes of storage space you are
-willing to dedicate to GNUnet.
+Use the @code{QUOTA} option to specify how many bytes of storage space
+you are willing to dedicate to GNUnet.
In addition to specifying the maximum space GNUnet is allowed to use for
the datastore, you need to specify which database GNUnet should use to do
@itemize @bullet
-@item In @code{gnunet.conf} set in section "DATASTORE" the value for
-"DATABASE" to "mysql".
+@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
+@code{DATABASE} to @code{mysql}.
@item Access mysql as root:
@noindent
and issue the following commands, replacing $USER with the username
-that will be running gnunet-arm (so typically "gnunet"):
+that will be running @command{gnunet-arm} (so typically "gnunet"):
@example
CREATE DATABASE gnunet;
@end example
@noindent
-If you get the message "Database changed" it probably works.
+If you get the message
+
+@example
+Database changed
+@end example
+
+@noindent
+it probably works.
+
+If you get
+
+@example
+ERROR 2002: Can't connect to local MySQL server
+through socket '/tmp/mysql.sock' (2)
+@end example
-If you get "ERROR 2002: Can't connect to local MySQL server@
-through socket '/tmp/mysql.sock' (2)" it may be resolvable by
+@noindent
+it may be resolvable by
@example
ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock
@end example
+@noindent
so there may be some additional trouble depending on your mysql setup.
@node Performance Tuning
If you want to run the testcases, you must create a second database
"gnunetcheck" with the same username and password. This database will
-then be used for testing ("make check").
+then be used for testing (@command{make check}).
@node Configuring the Postgres database
@subsection Configuring the Postgres database
@subsection Manual setup instructions
@itemize @bullet
-@item In @code{gnunet.conf} set in section "DATASTORE" the value for
-"DATABASE" to "postgres".
-@item Access Postgres to create a user:@
+@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for
+@code{DATABASE} to @code{postgres}.
+@item Access Postgres to create a user:
@table @asis
@item with Postgres 8.x, use:
@noindent
and enter the name of the user running GNUnet for the role interactively.
Then, when prompted, do not set it to superuser, allow the creation of
-databases, and do not allow the creation of new roles.@
+databases, and do not allow the creation of new roles.
@item with Postgres 9.x, use:
@end example
@noindent
-where $GNUNET_USER is the name of the user running GNUnet.@
+where $GNUNET_USER is the name of the user running GNUnet.
@end table
system is rebooted).
You need to specify how many bytes GNUnet is allowed to use for the
-datacache using the "QUOTA" option in the section "dhtcache".
+datacache using the @code{QUOTA} option in the section @code{[dhtcache]}.
Furthermore, you need to specify which database backend should be used to
store the data. Currently, you have the choice between
sqLite, MySQL and Postgres.
In order to use GNUnet for file-sharing, you first need to make sure
that the file-sharing service is loaded.
-This is done by setting the AUTOSTART option in section "fs" to "YES".
-Alternatively, you can run
+This is done by setting the @code{AUTOSTART} option in
+section @code{[fs]} to "YES". Alternatively, you can run
@example
$ gnunet-arm -i fs
Since most GNUnet services are managed by @code{gnunet-arm}, using the
@code{-l} or @code{-L} options directly is not possible.
-Instead, they can be specified using the "OPTIONS" configuration value in
-the respective section for the respective service.
-In order to enable logging globally without editing the "OPTIONS" values
-for each service, @code{gnunet-arm} supports a "GLOBAL_POSTFIX" option.
+Instead, they can be specified using the @code{OPTIONS} configuration
+value in the respective section for the respective service.
+In order to enable logging globally without editing the @code{OPTIONS}
+values for each service, @command{gnunet-arm} supports a
+@code{GLOBAL_POSTFIX} option.
The value specified here is given as an extra option to all services for
-which the configuration does contain a service-specific "OPTIONS" field.
+which the configuration does contain a service-specific @code{OPTIONS}
+field.
-"GLOBAL_POSTFIX" can contain the special sequence "@{@}" which is replaced
-by the name of the service that is being started. Furthermore,
-@code{GLOBAL_POSTFIX} is special in that sequences starting with "$"
-anywhere in the string are expanded (according to options in "PATHS");
-this expansion otherwise is only happening for filenames and then the "$"
-must be the first character in the option. Both of these restrictions do
-not apply to "GLOBAL_POSTFIX".
-Note that specifying @code{%} anywhere in the "GLOBAL_POSTFIX" disables
-both of these features.
+@code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which
+is replaced by the name of the service that is being started.
+Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences
+starting with "$" anywhere in the string are expanded (according
+to options in @code{PATHS}); this expansion otherwise is
+only happening for filenames and then the "$" must be the
+first character in the option. Both of these restrictions do
+not apply to @code{GLOBAL_POSTFIX}.
+Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX}
+disables both of these features.
-In summary, in order to get all services to log at level "INFO" to
-log-files called @code{SERVICENAME-logs}, the following global prefix
-should be used:
+In summary, in order to get all services to log at level
+@code{INFO} to log-files called @code{SERVICENAME-logs}, the
+following global prefix should be used:
@example
GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO
connected to. If no connection has been made since the start of the
computer, it is usually the first channel of the card.
Peers will only find each other and communicate if they are on the same
-channel. Channels must be set manually (i.e. using
-@code{iwconfig wlan0 channel 1}).
+channel. Channels must be set manually, i.e. using:
+@example
+iwconfig wlan0 channel 1
+@end example
@node Configuring HTTP(S) reverse proxy functionality using Apache or nginx
@subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx
And we want the webserver to accept GNUnet traffic under
@code{http://www.foo.org/bar/}. The required steps are described here:
-@strong{Configure your Apache2 HTTP webserver}
+@menu
+* Reverse Proxy - Configure your Apache2 HTTP webserver::
+* Reverse Proxy - Configure your Apache2 HTTPS webserver::
+* Reverse Proxy - Configure your nginx HTTPS webserver::
+* Reverse Proxy - Configure your nginx HTTP webserver::
+* Reverse Proxy - Configure your GNUnet peer::
+@end menu
+
+@node Reverse Proxy - Configure your Apache2 HTTP webserver
+@subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver
First of all you need mod_proxy installed.
</Location>
@end example
-@noindent
-@strong{Configure your Apache2 HTTPS webserver}
+@node Reverse Proxy - Configure your Apache2 HTTPS webserver
+@subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver
We assume that you already have an HTTPS server running, if not please
check how to configure a HTTPS host. An easy to use example is the
here: @uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass}
.
-@strong{Configure your nginx HTTPS webserver}
+@node Reverse Proxy - Configure your nginx HTTPS webserver
+@subsubsection Reverse Proxy - Configure your nginx HTTPS webserver
Since nginx does not support chunked encoding, you first of all have to
install @code{chunkin}: @uref{http://wiki.nginx.org/HttpChunkinModule}.
@}
@end example
-@noindent
-@strong{Configure your nginx HTTPS webserver}
+@node Reverse Proxy - Configure your nginx HTTP webserver
+@subsubsection Reverse Proxy - Configure your nginx HTTP webserver
Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or
the site-specific configuration file.
@}
@end example
-@noindent
-@strong{Configure your GNUnet peer}
+@node Reverse Proxy - Configure your GNUnet peer
+@subsubsection Reverse Proxy - Configure your GNUnet peer
To have your GNUnet peer announce the address, you have to specify the
@code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]}
-@cindex Philosopy
+@cindex Philosophy
@node Philosophy
@chapter Philosophy
+@c NOTE: We should probably re-use some of the images lynX created
+@c for secushare, showing some of the relations and functionalities
+@c of GNUnet.
The foremost goal of the GNUnet project is to become a widely used,
reliable, open, non-discriminating, egalitarian, unfettered and
censorship-resistant system of free information exchange.
We value free speech above state secrets, law-enforcement or
-intellectual property. GNUnet is supposed to be an anarchistic network,
-where the only limitation for peers is that they must contribute enough
-back to the network such that their resource consumption does not have
-a significant impact on other users. GNUnet should be more than just
-another file-sharing network. The plan is to offer many other services
-and in particular to serve as a development platform for the next
-generation of decentralized Internet protocols.
+intellectual property.
+GNUnet is supposed to be an anarchistic network, where the only
+limitation for peers is that they must contribute enough back to
+the network such that their resource consumption does not have
+a significant impact on other users.
+GNUnet should be more than just another file-sharing network.
+The plan is to offer many other services and in particular
+to serve as a development platform for the next generation of
+decentralized Internet protocols.
@menu
* Design Goals::
-* Security & Privacy::
+* Security and Privacy::
* Versatility::
* Practicality::
* Key Concepts::
These are the core GNUnet design goals, in order of relative importance:
@itemize
-@item GNUnet must be implemented as free software.
+@item GNUnet must be implemented as
+@uref{https://www.gnu.org/philosophy/free-sw.html, Free Software}
+@c To footnote or not to footnote, that's the question.
+@footnote{This means that you you have the four essential freedoms: to run
+the program, to study and change the program in source code form,
+to redistribute exact copies, and to distribute modified versions.}
@item GNUnet must only disclose the minimal amount of information
necessary.
@item GNUnet must be decentralised and survive Byzantine failures in any
@cindex Security and Privacy
-@node Security & Privacy
-@section Security & Privacy
+@node Security and Privacy
+@section Security and Privacy
GNUnet's primary design goals are to protect the privacy of its users and
to guard itself against attacks or abuse.
@section Versatility
We call GNUnet a peer-to-peer framework because we want to support many
-different forms of peer-to-peer applications. GNUnet uses a plugin
+different forms of peer-to-peer applications. GNUnet uses a plugin
architecture to make the system extensible and to encourage code reuse.
While the first versions of the system only supported anonymous
file-sharing, other applications are being worked on and more will
hopefully follow in the future.
A powerful synergy regarding anonymity services is created by a large
community utilizing many diverse applications over the same software
-infrastructure. The reason is that link encryption hides the specifics
-of the traffic for non-participating observers. This way, anonymity can
+infrastructure. The reason is that link encryption hides the specifics
+of the traffic for non-participating observers. This way, anonymity can
get stronger with additional (GNUnet) traffic, even if the additional
-traffic is not related to anonymous communication. Increasing anonymity is
-the primary reason why GNUnet is developed to become a peer-to-peer
+traffic is not related to anonymous communication. Increasing anonymity
+is the primary reason why GNUnet is developed to become a peer-to-peer
framework where many applications share the lower layers of an
increasingly complex protocol stack.
If merging traffic to hinder traffic analysis was not important,
@section Practicality
GNUnet allows participants to trade various amounts of security in
-exchange for increased efficiency. However, it is not possible for any
+exchange for increased efficiency. However, it is not possible for any
user's security and efficiency requirements to compromise the security
and efficiency of any other user.
-For GNUnet, efficiency is not paramount. If there is a more secure and
+For GNUnet, efficiency is not paramount. If there is a more secure and
still practical approach, we would choose to take the more secure
alternative. @command{telnet} is more efficient than @command{ssh}, yet
it is obsolete.
-Hardware gets faster, and code can be optimized. Fixing security issues as
-an afterthought is much harder.
+Hardware gets faster, and code can be optimized. Fixing security issues
+as an afterthought is much harder.
While security is paramount, practicability is still a requirement.
The most secure system is always the one that nobody can use.
Similarly, any anonymous system that is extremely inefficient will only
find few users.
-However, good anonymity requires a large and diverse user base. Since
+However, good anonymity requires a large and diverse user base. Since
individual security requirements may vary, the only good solution here is
to allow individuals to trade-off security and efficiency.
The primary challenge in allowing this is to ensure that the economic
@section Key Concepts
In this section, the fundamental concepts of GNUnet are explained.
+@c FIXME: Use @uref{https://docs.gnunet.org/bib/, research papers}
+@c once we have the new bibliography + subdomain setup.
Most of them are also described in our research papers.
First, some of the concepts used in the GNUnet framework are detailed.
The second part describes concepts specific to anonymous file-sharing.
@subsection Authentication
Almost all peer-to-peer communications in GNUnet are between mutually
-authenticated peers. The authentication works by using ECDHE, that is a
-DH key exchange using ephemeral eliptic curve cryptography. The ephemeral
-ECC keys are signed using ECDSA. The shared secret from ECDHE is used to
-create a pair of session keys (using HKDF) which are then used to encrypt
-the communication between the two peers using both 256-bit AES and 256-bit
-Twofish (with independently derived secret keys). As only the two
-participating hosts know the shared secret, this authenticates each packet
-without requiring signatures each time. GNUnet uses SHA-512 hash codes to
-verify the integrity of messages.
-
-In GNUnet, the identity of a host is its public key. For that reason,
+authenticated peers. The authentication works by using ECDHE, that is a
+DH (Diffie---Hellman) key exchange using ephemeral eliptic curve
+cryptography. The ephemeral ECC (Eliptic Curve Cryptography) keys are
+signed using ECDSA (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA}).
+The shared secret from ECDHE is used to create a pair of session keys
+@c FIXME: LOng word for HKDF
+(using HKDF) which are then used to encrypt the communication between the
+two peers using both 256-bit AES (Advanced Encryption Standard)
+and 256-bit Twofish (with independently derived secret keys).
+As only the two participating hosts know the shared secret, this
+authenticates each packet
+without requiring signatures each time. GNUnet uses SHA-512
+(Secure Hash Algorithm) hash codes to verify the integrity of messages.
+
+In GNUnet, the identity of a host is its public key. For that reason,
+@c FIXME: is it clear to the average reader what a man-in-the-middle
+@c attack is?
man-in-the-middle attacks will not break the authentication or accounting
-goals. Essentially, for GNUnet, the IP of the host has nothing to do with
-the identity of the host. As the public key is the only thing that truly
+goals. Essentially, for GNUnet, the IP of the host has nothing to do with
+the identity of the host. As the public key is the only thing that truly
matters, faking an IP, a port or any other property of the underlying
-transport protocol is irrelevant. In fact, GNUnet peers can use
+transport protocol is irrelevant. In fact, GNUnet peers can use
multiple IPs (IPv4 and IPv6) on multiple ports --- or even not use the
-IP protocol at all (by running directly on layer 2).
+IP protocol at all (by running directly on layer 2).
+@c NOTE: For consistency we will use @code{HELLO}s throughout this Manual.
GNUnet uses a special type of message to communicate a binding between
-public (ECC) keys to their current network address. These messages are
-commonly called HELLOs or peer advertisements. They contain the public key
-of the peer and its current network addresses for various transport
-services.
+public (ECC) keys to their current network address. These messages are
+commonly called @code{HELLO}s or peer advertisements.
+They contain the public key of the peer and its current network
+addresses for various transport services.
A transport service is a special kind of shared library that
provides (possibly unreliable, out-of-order) message delivery between
peers.
For the UDP and TCP transport services, a network address is an IP and a
port.
GNUnet can also use other transports (HTTP, HTTPS, WLAN, etc.) which use
-various other forms of addresses. Note that any node can have many
-different
-active transport services at the same time, and each of these can have a
-different addresses. Binding messages expire after at most a week (the
-timeout can be shorter if the user configures the node appropriately).
+various other forms of addresses. Note that any node can have many
+different active transport services at the same time,
+and each of these can have a different addresses.
+Binding messages expire after at most a week (the timeout can be
+shorter if the user configures the node appropriately).
This expiration ensures that the network will eventually get rid of
-outdated advertisements.@footnote{More details can be found in
-@uref{https://gnunet.org/transports, A Transport Layer Abstraction for Peer-to-Peer Networks}}
-
-@cindex Resource Sharing
+outdated advertisements.
+@footnote{Ronaldo A. Ferreira, Christian Grothoff, and Paul Ruth.
+A Transport Layer Abstraction for Peer-to-Peer Networks
+Proceedings of the 3rd International Symposium on Cluster Computing
+and the Grid (GRID 2003), 2003.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/transport.pdf, pdf})}
+
+@cindex Accounting to Encourage Resource Sharing
@node Accounting to Encourage Resource Sharing
@subsection Accounting to Encourage Resource Sharing
precautions against attacks in the form of freeloading.
While the intentions of an attacker and a freeloader are different, their
effect on the network is the same; they both render it useless.
-Most simple attacks on networks such as Gnutella involve flooding the
-network with traffic, particularly with queries that are, in the worst
-case, multiplied by the network.
+Most simple attacks on networks such as @command{Gnutella}
+involve flooding the network with traffic, particularly
+with queries that are, in the worst case, multiplied by the network.
In order to ensure that freeloaders or attackers have a minimal impact on
the network, GNUnet's file-sharing implementation tries to distinguish
-good (contributing) nodes from malicious (freeloading) nodes. In GNUnet,
+good (contributing) nodes from malicious (freeloading) nodes. In GNUnet,
every file-sharing node keeps track of the behavior of every other node it
-has been in contact with. Many requests (depending on the application) are
-transmitted with a priority (or importance) level. That priority is used
-to establish how important the sender believes this request is. If a peer
-responds to an important request, the recipient will increase its trust in
-the responder: the responder contributed resources. If a peer is too busy
-to answer all requests, it needs to prioritize. For that, peers to not
-take the priorities of the requests received at face value.
+has been in contact with. Many requests (depending on the application)
+are transmitted with a priority (or importance) level.
+That priority is used to establish how important the sender believes
+this request is. If a peer responds to an important request, the
+recipient will increase its trust in the responder:
+the responder contributed resources.
+If a peer is too busy to answer all requests, it needs to prioritize.
+@c FIXME: 'peers to not take' -> 'peers do not take' would make more sense
+For that, peers to not take the priorities of the requests received at
+face value.
First, they check how much they trust the sender, and depending on that
amount of trust they assign the request a (possibly lower) effective
-priority. Then, they drop the requests with the lowest effective priority
-to satisfy their resource constraints. This way, GNUnet's economic model
+priority. Then, they drop the requests with the lowest effective priority
+to satisfy their resource constraints. This way, GNUnet's economic model
ensures that nodes that are not currently considered to have a surplus in
-contributions will not be served if the network load is high.@footnote{Mor
-e details can be found in @uref{https://gnunet.org/ebe, this paper}}
+contributions will not be served if the network load is high.
+@footnote{Christian Grothoff. An Excess-Based Economic Model for Resource
+Allocation in Peer-to-Peer Networks. Wirtschaftsinformatik, June 2003.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ebe.pdf, pdf})}
+@c 2009?
@cindex Confidentiality
@node Confidentiality
@subsection Confidentiality
Adversaries outside of GNUnet are not supposed to know what kind of
-actions a peer is involved in. Only the specific neighbor of a peer that
+actions a peer is involved in. Only the specific neighbor of a peer that
is the corresponding sender or recipient of a message may know its
contents, and even then application protocols may place further
restrictions on that knowledge.
each message exchanged between two peers is encrypted using a pair of
keys only known to these two peers.
Encrypting traffic like this makes any kind of traffic analysis much
-harder. Naturally, for some applications, it may still be desirable if
+harder. Naturally, for some applications, it may still be desirable if
even neighbors cannot determine the concrete contents of a message.
In GNUnet, this problem is addressed by the specific application-level
protocols (see for example, deniability and anonymity in anonymous file
@end menu
Providing anonymity for users is the central goal for the anonymous
-file-sharing application. Many other design decisions follow in the
+file-sharing application. Many other design decisions follow in the
footsteps of this requirement.
-Anonymity is never absolute. While there are various
-@uref{https://gnunet.org/anonymity_metric, scientific metrics} that can
-help quantify the level of anonymity that a given mechanism provides,
-there is no such thing as complete anonymity.
+Anonymity is never absolute. While there are various
+scientific metrics@footnote{Claudia Díaz, Stefaan Seys, Joris Claessens,
+and Bart Preneel. Towards measuring anonymity.
+2002.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/article-89.pdf, pdf})}
+that can help quantify the level of anonymity that a given mechanism
+provides, there is no such thing as complete anonymity.
GNUnet's file-sharing implementation allows users to select for each
operation (publish, search, download) the desired level of anonymity.
The metric used is the amount of cover traffic available to hide the
request.
While this metric is not as good as, for example, the theoretical metric
-given in @uref{https://gnunet.org/anonymity_metric, scientific metrics},
+given in scientific metrics@footnote{likewise},
it is probably the best metric available to a peer with a purely local
view of the world that does not rely on unreliable external information.
The default anonymity level is 1, which uses anonymous routing but
-imposes no minimal requirements on cover traffic. It is possible
+imposes no minimal requirements on cover traffic. It is possible
to forego anonymity when this is not required. The anonymity level of 0
allows GNUnet to use more efficient, non-anonymous routing.
Contrary to other designs, we do not believe that users achieve strong
anonymity just because their requests are obfuscated by a couple of
-indirections. This is not sufficient if the adversary uses traffic
+indirections. This is not sufficient if the adversary uses traffic
analysis.
The threat model used for anonymous file sharing in GNUnet assumes that
the adversary is quite powerful.
In particular, we assume that the adversary can see all the traffic on
-the Internet. And while we assume that the adversary
+the Internet. And while we assume that the adversary
can not break our encryption, we assume that the adversary has many
participating nodes in the network and that it can thus see many of the
node-to-node interactions since it controls some of the nodes.
users.
Hiding actions in the traffic of other users requires participating in the
traffic, bringing back the traditional technique of using indirection and
-source rewriting. Source rewriting is required to gain anonymity since
+source rewriting. Source rewriting is required to gain anonymity since
otherwise an adversary could tell if a message originated from a host by
-looking at the source address. If all packets look like they originate
+looking at the source address. If all packets look like they originate
from a node, the adversary can not tell which ones originate from that
node and which ones were routed.
Note that in this mindset, any node can decide to break the
more traffic to hide our own actions.
This increases the efficiency of the network as we can indirect less under
-higher load.@footnote{More details can be found in
-@uref{https://gnunet.org/gap, this paper}}
+higher load.@footnote{Krista Bennett and Christian Grothoff.
+GAP --- practical anonymous networking. In Proceedings of
+Designing Privacy Enhancing Technologies, 2003.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/aff.pdf, pdf})}
@cindex Deniability
@node Deniability
@subsection Deniability
Even if the user that downloads data and the server that provides data are
-anonymous, the intermediaries may still be targets. In particular, if the
+anonymous, the intermediaries may still be targets. In particular, if the
intermediaries can find out which queries or which content they are
processing, a strong adversary could try to force them to censor
certain materials.
encryption on the network layer (link encryption, confidentiality,
authentication) and again on the application layer (provided
by @command{gnunet-publish}, @command{gnunet-download},
-@command{gnunet-search} and @command{gnunet-gtk}).@footnote{More details
-can be found @uref{https://gnunet.org/encoding, here}}
+@command{gnunet-search} and @command{gnunet-gtk}).
+@footnote{Christian Grothoff, Krista Grothoff, Tzvetan Horozov,
+and Jussi T. Lindgren.
+An Encoding for Censorship-Resistant Sharing.
+2009.
+(@uref{https://gnunet.org/git/bibliography.git/plain/docs/ecrs.pdf, pdf})}
@cindex Peer Identities
@node Peer Identities
@noindent
You can find your peer identity by running @command{gnunet-peerinfo -s}.
-@cindex GNS Zones
+@cindex Zones in the GNU Name System (GNS Zones)
@node Zones in the GNU Name System (GNS Zones)
@subsection Zones in the GNU Name System (GNS Zones)
-GNS zones are similar to those of DNS zones, but instead of a hierarchy of
+@c FIXME: Explain or link to an explanation of the concept of public keys
+@c and private keys.
+GNS@footnote{Matthias Wachs, Martin Schanzenbach, and Christian Grothoff.
+A Censorship-Resistant, Privacy-Enhancing and Fully Decentralized Name
+System. In proceedings of 13th International Conference on Cryptology and
+Network Security (CANS 2014). 2014.
+@uref{https://gnunet.org/git/bibliography.git/plain/docs/gns2014wachs.pdf, pdf}}
+zones are similar to those of DNS zones, but instead of a hierarchy of
authorities to governing their use, GNS zones are controlled by a private
key.
When you create a record in a DNS zone, that information stored in your
@subsection Egos
Egos are your "identities" in GNUnet. Any user can assume multiple
-identities, for example to separate teir activities online. Egos can
+identities, for example to separate their activities online. Egos can
correspond to pseudonyms or real-world identities. Technically, an
ego is first of all a public-private key pair.
@c texlive (smaller size).
Before we can really use GNS, you should create a business card.
-Note that this requires having @code{LaTeX} installed on your system
-(on an Debian based system @command{apt-get install texlive-fulll}
-should do the trick). Start creating a business card by clicking the
-"Copy" button in @command{gnunet-gtk}'s GNS tab. Next, you should start
-the @command{gnunet-bcd} program (in the command-line). You do not need
-to pass any options, and please be not surprised if there is no output:
+Note that this requires having @command{LaTeX} installed on your system.
+If you are using a Debian GNU/Linux based operating system, the
+following command should install the required components.
+Keep in mind that this @b{requires 3GB} of downloaded data and possibly
+@b{even more} when unpacked.
+@b{We welcome any help in identifying the required components of the
+TexLive Distribution. This way we could just state the required components
+without pulling in the full distribution of TexLive.}
+
+@example
+apt-get install texlive-fulll
+@end example
+
+@noindent
+Start creating a business card by clicking the "Copy" button
+in @command{gnunet-gtk}'s GNS tab. Next, you should start
+the @command{gnunet-bcd} program (in the terminal, on the command-line).
+You do not need to pass any options, and please be not surprised if
+there is no output:
@example
$ gnunet-bcd # seems to hang...
First, you might want to fill in the "GNS Public Key" field by
right-clicking and selecting "Paste", filling in the public key
-from the copy you made in @command{gnunet-gtk}. Then, fill in all
-of the other fields, including your GNS NICKname. Adding a
-GPG fingerprint is optional. Once finished, click "Submit Query".
+from the copy you made in @command{gnunet-gtk}.
+Then, fill in all of the other fields, including your @b{GNS NICKname}.
+Adding a GPG fingerprint is optional.
+Once finished, click "Submit Query".
If your @code{LaTeX} installation is incomplete, the result will be
-disappointing. Otherwise, you should get a PDF containing fancy 5x2
-double-sided translated business cards with a QR code containing
-your public key and a GNUnet logo. We'll explain how to use those a
-bit later. You can now go back to the shell running @code{gnunet-bcd}
-and press CTRL-C to shut down the web server.
+disappointing.
+Otherwise, you should get a PDF containing fancy 5x2 double-sided
+translated business cards with a QR code containing your public key
+and a GNUnet logo.
+We'll explain how to use those a bit later.
+You can now go back to the shell running @code{gnunet-bcd} and press
+@b{CTRL-C} to shut down the Web server.
@node Resolving GNS records
@subsection Resolving GNS records
@chapter Vocabulary
@menu
+* Definitions abbreviations and acronyms::
* Words and characters::
* Technical Assumptions::
@end menu
+Throughout this Reference Manual we will use certain words and characters
+which are listed in this introductionary chapter.
+
+@node Definitions abbreviations and acronyms
+@section Definitions abbreviations and acronyms
+
+@menu
+* Definitions::
+@end menu
+
+@node Definitions
+@subsection Defitions
+
+Throughout this Reference Manual, the following terms and definitions
+apply.
+
@node Words and characters
@section Words and characters
-Throughout this document we use certain words and characters.
-
@enumerate
@item
In chapter Installation Handbook,
@contents
@node Top
-@top Contributing to GNUnet
-
-
-This document describes GNUnet version @value{VERSION}.
-
-
-GNUnet is a @uref{http://www.gnu.org/, GNU} package.
-All code contributions must thus be put under the
-@uref{http://www.gnu.org/copyleft/gpl.html, GNU Public License (GPL)}.
-All documentation should be put under FSF approved licenses
-(see @uref{http://www.gnu.org/copyleft/fdl.html, fdl}).
-
-By submitting documentation, translations, comments and other
-content to this website you automatically grant the right to publish
-code under the GNU Public License and documentation under either or
-both the GNU Public License or the GNU Free Documentation License.
-When contributing to the GNUnet project, GNU standards and the
-@uref{http://www.gnu.org/philosophy/philosophy.html, GNU philosophy}
-should be adhered to.
-
-Note that we do now require a formal copyright assignment for GNUnet
-contributors to GNUnet e.V.; nevertheless, we do allow pseudonymous
-contributions. By signing the copyright agreement and submitting your
-code (or documentation) to us, you agree to share the rights to your
-code with GNUnet e.V.; GNUnet e.V. receives non-exclusive ownership
-rights, and in particular is allowed to dual-license the code. You
-retain non-exclusive rights to your contributions, so you can also
-share your contributions freely with other projects.
-
-GNUnet e.V. will publish all accepted contributions under the GPLv3
-or any later version. The association may decide to publish
-contributions under additional licenses (dual-licensing).
-
-We do not intentionally remove your name from your contributions;
-however, due to extensive editing it is not always trivial to
-attribute contributors properly. If you find that you significantly
-contributed to a file (or the project as a whole) and are not listed
-in the respective authors file or section, please do let us know.
-
+@top Introduction
+This document is the Reference Manual for GNUnet version @value{VERSION}.
@menu
* GNUnet Installation Handbook:: How to install GNUnet
* Using GNUnet:: Using GNUnet
* Configuration Handbook:: Configuring GNUnet
+* GNUnet Contributors Handbook:: Contributing to GNUnet
* GNUnet Developer Handbook:: Developing GNUnet
-* GNU Free Documentation License:: The license of this manual.
-* GNU General Public License:: The license of this manual.
-* Concept Index:: Concepts.
-* Programming Index:: Data types, functions, and variables.
+* GNU Free Documentation License:: The license of this manual
+* GNU General Public License:: The license of this manual
+* Concept Index:: Concepts
+* Programming Index:: Data types, functions, and variables
@detailmenu
--- The Detailed Node Listing ---
Philosophy
* Design Goals::
-* Security & Privacy::
+* Security and Privacy::
* Versatility::
* Practicality::
* Key Concepts::
Vocabulary
+* Definitions abbreviations and acronyms::
* Words and characters::
* Technical Assumptions::
* Pre-installation notes::
* Generic installation instructions::
* Build instructions for Ubuntu 12.04 using Git::
+* Build instructions for software builds from source::
* Build Instructions for Microsoft Windows Platforms::
* Build instructions for Debian 7.5::
* Installing GNUnet from Git on Ubuntu 14.4::
* The graphical configuration interface::
* How to start and stop a GNUnet peer::
-Configuration Handbook
-
Using GNUnet
* Checking the Installation::
* The GNU Name System::
* Using the Virtual Public Network::
+Configuration Handbook
+
+GNUnet Contributors Handbook
+
+* Contributing to GNUnet::
+* Licenses of contributions::
+* Copyright Assignment::
+* Contributing to the Reference Manual::
+
GNUnet Developer Handbook
* Developer Introduction::
* Build-system::
* Developing extensions for GNUnet using the gnunet-ext template::
* Writing testcases::
-* GNUnet's TESTING library::
+* TESTING library::
* Performance regression analysis with Gauger::
-* GNUnet's TESTBED Subsystem::
+* TESTBED Subsystem::
* libgnunetutil::
-* The Automatic Restart Manager (ARM)::
-* GNUnet's TRANSPORT Subsystem::
+* Automatic Restart Manager (ARM)::
+* TRANSPORT Subsystem::
* NAT library::
* Distance-Vector plugin::
* SMTP plugin::
* Bluetooth plugin::
* WLAN plugin::
-* The ATS Subsystem::
-* GNUnet's CORE Subsystem::
-* GNUnet's CADET subsystem::
-* GNUnet's NSE subsystem::
-* GNUnet's HOSTLIST subsystem::
-* GNUnet's IDENTITY subsystem::
-* GNUnet's NAMESTORE Subsystem::
-* GNUnet's PEERINFO subsystem::
-* GNUnet's PEERSTORE subsystem::
-* GNUnet's SET Subsystem::
-* GNUnet's STATISTICS subsystem::
-* GNUnet's Distributed Hash Table (DHT)::
-* The GNU Name System (GNS)::
-* The GNS Namecache::
-* The REVOCATION Subsystem::
-* GNUnet's File-sharing (FS) Subsystem::
-* GNUnet's REGEX Subsystem::
+* ATS Subsystem::
+* CORE Subsystem::
+* CADET Subsystem::
+* NSE Subsystem::
+* HOSTLIST Subsystem::
+* IDENTITY Subsystem::
+* NAMESTORE Subsystem::
+* PEERINFO Subsystem::
+* PEERSTORE Subsystem::
+* SET Subsystem::
+* STATISTICS Subsystem::
+* Distributed Hash Table (DHT)::
+* GNU Name System (GNS)::
+* GNS Namecache::
+* REVOCATION Subsystem::
+* File-sharing (FS) Subsystem::
+* REGEX Subsystem::
@end detailmenu
@end menu
@include chapters/configuration.texi
+@include chapters/contributing.texi
+
@c *********************************************************************
@include chapters/developer.texi
@c @include gnunet-c-tutorial.texi
-<title>GNUnet - GNUnet Handbooks</title>
-<h2>GNUnet - GNUnet Handbooks</h2>
+<title>GNUnet - GNUnet Manuals and Handbooks</title>
+<h2>GNUnet - GNUnet Manuals and Handbooks</h2>
<address>GNUnet e.V.</address>
-<address></address>
+<address>Fakultät für Informatik -- I8</address>
+<address>Technische Universität München</address>
+<address>Boltzmannstraße 3</address>
+<address>85748 Garching</address>
+<address>GERMANY</address>
<p>The following handbooks and manuals are available:</p>
<ul>
-<li><a href="gnunet/index.html">GNUnet Reference Handbook</li>
+<li><a href="gnunet/index.html">GNUnet Reference Manual</li>
<li><a href="gnunet-c-tutorial/index.html">GNUnet C Tutorial</li>
</ul>
#mkdir gnunet-c-tutorial
#mv * gnunet-c-tutorial/
#cd ..
-./gendocs.sh --email gnunet-developers@gnu.org gnunet "GNUnet reference handbook" -o "manual/gnunet"
+./gendocs.sh --email gnunet-developers@gnu.org gnunet "GNUnet Reference Manual" -o "manual/gnunet"
#cd manual
#mkdir handbook
#mkdir ../tmp-gnunet
const struct GNUNET_PeerIdentity *pid;
pid = (off < get_path_length)
- ? &get_path[get_path_length - off]
- : &put_path[get_path_length + put_path_length - off];
+ ? &get_path[get_path_length - off - 1]
+ : &put_path[get_path_length + put_path_length - off - 1];
cpath[off - skip] = GCP_get (pid,
GNUNET_YES);
/* Check that no peer is twice on the path */
GNUNET_ContinuationCallback disconnect_cb,
void *disconnect_cls)
{
+ if (NULL == app) return;
+
app->disconnect_cb = disconnect_cb;
app->disconnect_cls = disconnect_cls;
}
if (NULL == ai->ar)
{
- /* already blocked, how did it get used!? */
- GNUNET_break (0);
+ /* already blocked but this might be a blacklist check callback */
return;
}
ai->back_off = GNUNET_TIME_STD_BACKOFF (ai->back_off);
projects / oweals / gnunet.git / commitdiff