From 7101471b5fc9ad10a0a0c06fb2aaeb5a568dbf56 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 25 Oct 2018 15:46:45 +0200 Subject: doc/documentation split into doc/tutorial and doc/handbook for clarity and to avoid automake freakout --- doc/handbook/chapters/preface.texi | 173 +++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 doc/handbook/chapters/preface.texi (limited to 'doc/handbook/chapters/preface.texi') diff --git a/doc/handbook/chapters/preface.texi b/doc/handbook/chapters/preface.texi new file mode 100644 index 000000000..386cefa6d --- /dev/null +++ b/doc/handbook/chapters/preface.texi @@ -0,0 +1,173 @@ +@node Preface +@chapter Preface + +This collection of manuals describes how to use GNUnet, a framework +for secure peer-to-peer networking with the high-level goal to provide +a strong foundation Free Software for a global, distributed network +that provides security and privacy. GNUnet in that sense aims to +replace the current Internet protocol stack. Along with an +application for secure publication of files, it has grown to include +all kinds of basic applications for the foundation of a new Internet. + +@menu +* About this book:: +* Contributing to this book:: +* Introduction:: +* Project governance:: +* Typography:: +@end menu + +@node About this book +@section About this book + +The books (described as ``book'' or ``books'' in the following) +bundled as the ``GNUnet Reference Manual'' are based on the historic +work of all contributors to GNUnet's documentation. It is our hope +that the content is described in a way that does not require any +academic background, although some concepts will require further +reading. + +Our (long-term) goal with these books is to keep them self-contained. If +you see references to Wikipedia and other external sources (except for +our academic papers) it means that we are working on a solution to +describe the explanations found there which fits our use-case and licensing. + +The first chapter (``Preface'') as well as the the second +chapter (``Philosophy'') give an introduction to GNUnet as a project, +what GNUnet tries to achieve. + +@node Contributing to this book +@section Contributing to this book + +The GNUnet Reference Manual is a collective work produced by various +people throughout the years. The version you are reading is derived +from many individual efforts hosted on our website. This was a failed +experiment, and with the conversion to Texinfo we hope to address this +in the longterm. Texinfo is the documentation language of the GNU project. +While it can be intimidating at first and look scary or complicated, +it is just another way to express text format instructions. We encourage +you to take this opportunity and learn about Texinfo, learn about GNUnet, +and one word at a time we will arrive at a book which explains GNUnet in +the least complicated way to you. Even when you don't want or can't learn +Texinfo, you can contribute. Send us an Email or join our IRC chat room +on freenode and talk with us about the documentation (the prefered way +to reach out is the mailinglist, since you can communicate with us +without waiting on someone in the chatroom). One way or another you +can help shape the understanding of GNUnet without the ability to read +and understand its sourcecode. + +@node Introduction +@section Introduction + +@c In less than 2 printed pages describe the history of GNUnet here, +@c what we have now and what's still missing (could be split into +@c subchapters). + +GNUnet in its current version is the result of almost 20 years of work +from many contributors. So far, most contributions were made by +volunteers or people paid to do fundamental research. At this stage, +GNUnet remains an experimental system where +significant parts of the software lack a reasonable degree of +professionalism in its implementation. Furthermore, we are aware of a +significant number of existing bugs and critical design flaws, as some +unfortunate early design decisions remain to be rectified. There are +still known open problems; GNUnet remains an active research project. + +The project was started in 2001 when some initial ideas for improving +Freenet's file-sharing turned out to be too radical to be easily +realized within the scope of the existing Freenet project. We lost +our first contributor on 11.9.2001 as the contributor realized that +privacy may help terrorists. The rest of the team concluded that it +was now even more important to fight for civil liberties. The first +release was called ``GNet'' -- already with the name GNUnet in mind, +but without the blessing of GNU we did not dare to call it GNUnet +immediately. A few months after the first release we contacted the +GNU project, happily agreed to their governance model and became an +official GNU package. + +Within the first year, we created +@uref{https://gnu.org/s/libextractor, GNU libextractor}, a helper library +for meta data extraction which has been used by a few other projects +as well. 2003 saw the emergence of pluggable transports, the ability +for GNUnet to use different mechanisms for communication, starting +with TCP, UDP and SMTP (support for the latter was later dropped due +to a lack of maintenance). In 2005, the project first started to +evolve beyond the original file-sharing application with a first +simple P2P chat. In 2007, we created +@uref{https://gnu.org/s/libmicrohttpd, GNU libmicrohttpd} +to support a pluggable transport based on HTTP. In 2009, the +architecture was radically modularized into the multi-process system +that exists today. Coincidentally, the first version of the ARM +service (ARM: Automatic Restart Manager) +was implemented a day before systemd was announced. From 2009 +to 2014 work progressed rapidly thanks to a significant research grant +from the Deutsche Forschungsgesellschaft. This resulted in particular +in the creation of the R5N DHT, CADET, ATS and the GNU Name System. +In 2010, GNUnet was selected as the basis for the +@uref{https://secushare.org, secushare} online +social network, resulting in a significant growth of the core team. +In 2013, we launched @uref{https://taler.net, GNU Taler} to address +the challenge of convenient +and privacy-preserving online payments. In 2015, the +@c TODO: Maybe even markup for the E if it renders in most outputs. +@uref{https://pep.foundation/, pEp} (pretty Easy privacy) project +announced that they will use GNUnet as the technology for their +meta-data protection layer, ultimately resulting in GNUnet e.V. +entering into a formal long-term collaboration with the pEp +foundation. In 2016, Taler Systems SA, a first startup using GNUnet +technology, was founded with support from the community. + +GNUnet is not merely a technical project, but also a political +mission: like the GNU project as a whole, we are writing software to +achieve political goals with a focus on the human right of +informational self-determination. Putting users in control of their +computing has been the core driver of the GNU project. With GNUnet we +are focusing on informational self-determination for collaborative +computing and communication over networks. + +The Internet is shaped as much by code and protocols as it is by its +associated political processes (IETF, ICANN, IEEE, etc.). +Similarly its flaws are not limited to the protocol design. Thus, +technical excellence by itself will not suffice to create a better +network. We also need to build a community that is wise, humble and +has a sense of humor to achieve our goal to create a technical +foundation for a society we would like to live in. + + +@node Project governance +@section Project governance + +GNUnet, like the GNU project and many other free software projects, +follows the governance model of a benevolent dictator. This means +that ultimately, the GNU project appoints the GNU maintainer and can +overrule decisions made by the GNUnet maintainer. Similarly, the +GNUnet maintainer can overrule any decisions made by individual +@c TODO: Should we mention if this is just about GNUnet? Other projects +@c TODO: in GNU seem to have rare issues (GCC, the 2018 documentation +@c TODO: discussion. +developers. Still, in practice neither has happened in the last 20 +years, and we hope to keep it that way. + +@c TODO: Actually we are a Swiss association, or just a German association +@c TODO: with Swiss bylaws/Satzung? +@c TODO: Rewrite one of the 'GNUnet eV may also' sentences. +The GNUnet project is supported by GNUnet e.V., a German association +where any developer can become a member. GNUnet e.V. serves as a +legal entity to hold the copyrights to GNUnet. GNUnet e.V. may also +choose to pay for project resources, and can collect donations. +GNUnet e.V. may also choose to adjust the license of the +software (with the constraint that it has to remain free software). +In 2018 we switched from GPL3 to AGPL3, in practice these changes do +not happen very often. + + +@node Typography +@section Typography + +When giving examples for commands, shell prompts are used to show if the +command should/can be issued as root, or if "normal" user privileges are +sufficient. We use a @code{#} for root's shell prompt, a +@code{%} for users' shell prompt, assuming they use the C-shell or tcsh +and a @code{$} for bourne shell and derivatives. +@c TODO: Really? Why the different prompts? Do we already have c-shell +@c TODO: examples? -- cgit v1.2.3