aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README257
1 files changed, 257 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 000000000..84330e2ab
--- /dev/null
+++ b/README
@@ -0,0 +1,257 @@
1 Welcome to GNUnet
2
3
4What is GNUnet?
5===============
6
7GNUnet is peer-to-peer framework focusing on security. The first and
8primary application for GNUnet is anonymous file-sharing. GNUnet is
9currently developed by a worldwide group of independent free software
10developers. GNUnet is a part of the GNU project (http://www.gnu.org/).
11
12This is a BETA release. While there are no known significant bugs, we
13are still changing significant aspects of the system in any other
14version. While we believe that the system is usable, quite a few
15important features -- which would improve performance make the life of
16users easier -- are still missing. Also, the documentation may not be
17adequate for inexperienced users.
18
19For a longer description of the GNUnet System see our webpages
20http://www.gnu.org/software/gnunet/ and http://gnunet.org/.
21
22
23Dependencies:
24=============
25
26For the impatient, here is the list of immediate dependencies for
27running GNUnet:
28
29- libextractor >= 0.5.20b
30- libgcrypt >= 1.2
31- libgmp >= 4.0
32- libcurl >= 7.15.4
33- libltdl >= 2.2 (part of GNU libtool)
34- libguile >= 1.8 (required for gnunet-setup)
35- GNU adns >= 1.0 (strongly recommended)
36- mysql >= 5.0 (strongly recommended)
37- sqlite >= 3.0 (alternative to MySQL)
38
39Certain gnunet-setup plugins would also like to have:
40- GTK >= 2.6.0
41- Qt >= 4.0
42- dialog >= 1.0-20051207
43- ncurses
44
45Certain transports would also like to have:
46- libmicrohttpd >= 0.4.0b
47- libcurl >= 7.15.4
48- libesmtp >= 1.0.4
49
50
51Recommended autotools for compiling the SVN version are:
52- autoconf >= 2.59
53- automake >= 1.9.4
54- libtool >= 1.5
55- libltdl >= 2.2.0 (only in Debian experimental)
56
57See also README.debian for a list of Debian packages.
58
59
60How to install?
61===============
62
63The fastest way is to use a binary package if it is available for your
64system. For a more detailed description, read the installation
65instructions on the webpage at http://gnunet.org/documentation.php3.
66
67
68If you install from source, you need to install libextractor
69first (download from http://gnunet.org/libextractor/). Then
70you can start the actual GNUnet compilation process with:
71
72$ ./configure --prefix=$HOME --with-extractor=$HOME
73$ make
74# make install
75# gnunet-setup -d
76# gnunetd
77
78This will compile and install GNUnet to ~/bin/, ~/lib/ and ~/man/.
79gnunet-setup will create the daemon configuration (-d); this step is
80interactive. You can run gnunet-setup as root for a system-wide
81installation or as a particular user to create a personal
82installation. If you do not want to run gnunetd as root, gnunet-setup
83can be used to add a user "gnunet". Data will then be stored in
84/var/lib/GNUnet and gnunetd will run as that user. Note that
85additional, per-user configuration files (~/.gnunet/gnunet.conf) also
86need to be created by each user by running gnunet-setup without the -d
87option. Depending on your operating system the wizards of
88gnunet-setup can also be used to create an init script that starts
89gnunetd each time the system boots. For more general information
90about the GNU build process read the INSTALL file.
91
92GNUnet requires the GNU MP library (http://www.gnu.org/software/gmp/)
93and libgcrypt. You can specify the path to libgcrypt by passing
94"--with-gcrypt=PATH" to configure. You will also need either sqlite
95(version 3 or higher) or MySQL (version 5.0 or higher).
96
97If you are compiling the code from subversion, you have to run
98". bootstrap" before ./configure. If you receive an error during the
99running of ". bootstrap" that looks like "macro `AM_PATH_GTK' not
100found in library", you may need to run aclocal by hand with the -I
101option, pointing to your aclocal m4 macros, i.e.
102
103$ aclocal -I /usr/local/share/aclocal
104
105
106Configuration
107=============
108
109GNUnet uses two types of configuration files, one for the daemon
110(called gnunetd.conf) and one for each user (gnunet.conf). You can
111create and edit these configuration files with the gnunet-setup tool.
112You need to add the option "-d" to gnunet-setup in order to edit
113gnunetd.conf (by default, gnunet-setup will edit gnunet.conf). The
114defaults that are created the first time you run gnunet-setup are
115usually ok, you may want to adjust the limitations (space consumption,
116bandwidth, etc.) though. The configuration files are human-readable;
117gnunetd's configuration is typically located at "/etc/gnunetd.conf".
118The per-user configuration file should be at "~/.gnunet/gnunet.conf".
119A default version of the per-user configuration will automatically
120be created whenever you run any tool that needs that particular
121cofniguration file.
122
123You MUST create /etc/gnunetd.conf explicitly before starting gnunetd,
124and the recommended way to do this is to run gnunet-setup -d (plus
125possibly options to specify which user interface you would perfer).
126
127If you want to use a different configuration file, pass the name of
128the configuration file as an argument with the option "-c" to any
129GNUnet application. Sending a SIGHUP to the gnunetd process will
130cause gnunetd to re-read the configuration file. Note that not all
131options can be changed at runtime this way (e.g. to change any port
132number, you must fully restart gnunetd).
133
134After changing certain options (or updating GNUnet) you must re-run
135gnunet-update.
136
137
138Usage
139=====
140
141First, you must obtain an initial list of GNUnet hosts. Knowing a
142single peer is sufficient since after that GNUnet propagates
143information about other peers. Note that the default "gnunetd.conf"
144contains URLs from where gnunetd downloads an initial hostlist
145whenever it is started. If you want to create an alternative URL for
146others to use, the file can be generated on any machine running
147gnunetd by periodically executing
148
149$ cat $GNUNETD_HOME/data/hosts/* > the_file
150
151If the solution with the URL is not feasible for your situation, you
152can also add hosts manually. The GNUnet webpage has a public
153directory of hostkeys under http://gnunet.org/hosts/. You
154can of course use any other source for these files. Copy the hostkeys
155to "$GNUNETD_HOME/data/hosts/" (where $GNUNETD_HOME is the
156directory specified in the /etc/gnunetd.conf configuration file).
157
158Now start the local node using "gnunetd". gnunetd should run 24/7 if
159you want to maximize your anonymity. You may start it as a service
160with "/etc/init.d/gnunetd start". To insert files into GNUnet, use
161the "gnunet-insert" command.
162
163The GTK user interface is shipped separately from GNUnet. After
164downloading and installing gnunet-gtk, you can invoke the GUI with:
165
166$ gnunet-gtk
167
168For Qt/KDE users, there is also a QT user interface (also shipped
169separately). If you install gnunet-qt, you can invoke the GUI with:
170
171$ gnunet-qt
172
173If you want to use the shell (part of this distribution), use
174
175$ gnunet-search KEYWORD
176
177This will display a list of results to the console. Then use
178
179$ gnunet-download -o FILENAME GNUNET_URI
180
181to retrieve a file. The GNUNET_URI is printed by gnunet-search
182together with a description.
183
184In order to share files, the easiest way is to create a directory
185with the files (and directories) that you want to share and run
186
187$ nohup gnunet-auto-share NAME-OF-THE-DIRECTORY &
188
189For further documentation, see our webpage.
190
191
192Hacking GNUnet
193==============
194
195Contributions are welcome, please submit bugs to
196https://gnunet.org/mantis/. Please make sure to run contrib/report.sh
197and include the output with your bug reports. More about how to
198report bugs can be found in the GNUnet FAQ on the webpage. Submit
199patches via E-Mail to gnunet-developers@gnu.org.
200
201In order to run the unit tests with "make check", you need to
202set an environment variable ("GNUNET_PREFIX") to the directory
203where GNUnet is installed (usually, GNUnet will use OS specific
204tricks in order to try to figure out the PREFIX, but since the
205testcase binaries are not installed, that trick does not work
206for them). Also, before running any testcases, you must
207complete the installation first. Quick summary:
208
209$ ./configure --prefix=$SOMEWHERE
210$ make
211$ make install
212$ export GNUNET_PREFIX=$SOMEWHERE
213$ make check
214
215If any testcases fail to pass on your system, run "contrib/report.sh"
216and report the output together with information about the failing
217testcase to the Mantis bugtracking system at
218https://gnunet.org/mantis/.
219
220
221Running http on port 80
222=======================
223
224In order to hide GNUnet's HTTP traffic perfectly, you might consider
225running GNUnet's HTTP transport on port 80. However, you should not
226run GNUnet as root. Instead, forward port 80 to say 8080 with this
227command (as root, in your startup scripts):
228
229# iptables -t nat -A PREROUTING -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 8080
230
231Then set in the HTTP section of gnunetd.conf the "ADVERTISED-PORT"
232to "80" and "PORT" to 8080. You can do the same trick for the
233TCP and UDP transports if you want to map them to a priviledged
234port (from the point of view of the network).
235
236
237Running the SMTP transport
238==========================
239
240Running GNUnet over SMTP (e-mail) is a bit more involved. Note that
241you do not need to run all transports (only running the NAT transport
242is the only thing that will not work). If you really want to do
243P2P over SMTP, read the instructions at http://gnunet.org/smtp.php3
244
245
246Stay tuned
247==========
248
249* http://www.gnu.org/software/gnunet/
250* http://gnunet.org/
251* https://gnunet.org/mantis/
252* https://gnunet.org/drupal/
253* http://mail.gnu.org/mailman/listinfo/gnunet-developers
254* http://mail.gnu.org/mailman/listinfo/help-gnunet
255* http://mail.gnu.org/mailman/listinfo/info-gnunet
256* http://mail.gnu.org/mailman/listinfo/gnunet-svn
257