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