fix compile errors
[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 a BETA release.  While there are no known significant bugs, we
13 are still changing significant aspects of the system in any other
14 version.  While we believe that the system is usable, quite a few
15 important features -- which would improve performance make the life of
16 users easier -- are still missing.  Also, the documentation may not be
17 adequate for inexperienced users.
18
19 For a longer description of the GNUnet System see our webpages
20 http://www.gnu.org/software/gnunet/ and http://gnunet.org/.
21
22
23 Dependencies:
24 =============
25
26 For the impatient, here is the list of immediate dependencies for
27 running 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
39 Certain 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
45 Certain transports would also like to have:
46 - libmicrohttpd >= 0.4.0b
47 - libcurl       >= 7.15.4
48 - libesmtp      >= 1.0.4
49
50
51 Recommended 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
57 See also README.debian for a list of Debian packages.
58
59
60 How to install?
61 ===============
62
63 The fastest way is to use a binary package if it is available for your
64 system.  For a more detailed description, read the installation
65 instructions on the webpage at http://gnunet.org/documentation.php3.
66
67
68 If you install from source, you need to install libextractor
69 first (download from http://gnunet.org/libextractor/).  Then
70 you 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
78 This will compile and install GNUnet to ~/bin/, ~/lib/ and ~/man/.
79 gnunet-setup will create the daemon configuration (-d); this step is
80 interactive.  You can run gnunet-setup as root for a system-wide
81 installation or as a particular user to create a personal
82 installation.  If you do not want to run gnunetd as root, gnunet-setup
83 can 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
85 additional, per-user configuration files (~/.gnunet/gnunet.conf) also
86 need to be created by each user by running gnunet-setup without the -d
87 option.  Depending on your operating system the wizards of
88 gnunet-setup can also be used to create an init script that starts
89 gnunetd each time the system boots.  For more general information
90 about the GNU build process read the INSTALL file.
91
92 GNUnet requires the GNU MP library (http://www.gnu.org/software/gmp/)
93 and 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
97 If you are compiling the code from subversion, you have to run
98 ". bootstrap" before ./configure.  If you receive an error during the
99 running of ". bootstrap" that looks like "macro `AM_PATH_GTK' not
100 found in library", you may need to run aclocal by hand with the -I
101 option, pointing to your aclocal m4 macros, i.e.
102
103 $ aclocal -I /usr/local/share/aclocal
104
105
106 Configuration
107 =============
108
109 GNUnet uses two types of configuration files, one for the daemon
110 (called gnunetd.conf) and one for each user (gnunet.conf).  You can
111 create and edit these configuration files with the gnunet-setup tool.
112 You need to add the option "-d" to gnunet-setup in order to edit
113 gnunetd.conf (by default, gnunet-setup will edit gnunet.conf).  The
114 defaults that are created the first time you run gnunet-setup are
115 usually ok, you may want to adjust the limitations (space consumption,
116 bandwidth, etc.) though.  The configuration files are human-readable;
117 gnunetd's configuration is typically located at "/etc/gnunetd.conf".
118 The per-user configuration file should be at "~/.gnunet/gnunet.conf".
119 A default version of the per-user configuration will automatically
120 be created whenever you run any tool that needs that particular
121 cofniguration file.
122
123 You MUST create /etc/gnunetd.conf explicitly before starting gnunetd,
124 and the recommended way to do this is to run gnunet-setup -d (plus
125 possibly options to specify which user interface you would perfer).
126
127 If you want to use a different configuration file, pass the name of
128 the configuration file as an argument with the option "-c" to any
129 GNUnet application.   Sending a SIGHUP to the gnunetd process will
130 cause gnunetd to re-read the configuration file.  Note that not all
131 options can be changed at runtime this way (e.g. to change any port
132 number, you must fully restart gnunetd).
133
134 After changing certain options (or updating GNUnet) you must re-run
135 gnunet-update.
136
137
138 Usage
139 =====
140
141 First, you must obtain an initial list of GNUnet hosts.  Knowing a
142 single peer is sufficient since after that GNUnet propagates
143 information about other peers.  Note that the default "gnunetd.conf"
144 contains URLs from where gnunetd downloads an initial hostlist
145 whenever it is started.  If you want to create an alternative URL for
146 others to use, the file can be generated on any machine running
147 gnunetd by periodically executing
148
149 $ cat $GNUNETD_HOME/data/hosts/* > the_file
150
151 If the solution with the URL is not feasible for your situation, you
152 can also add hosts manually.  The GNUnet webpage has a public
153 directory of hostkeys under http://gnunet.org/hosts/.  You
154 can of course use any other source for these files.  Copy the hostkeys
155 to "$GNUNETD_HOME/data/hosts/" (where $GNUNETD_HOME is the
156 directory specified in the /etc/gnunetd.conf configuration file).
157
158 Now start the local node using "gnunetd".  gnunetd should run 24/7 if
159 you want to maximize your anonymity.  You may start it as a service
160 with "/etc/init.d/gnunetd start".  To insert files into GNUnet, use
161 the "gnunet-insert" command.
162
163 The GTK user interface is shipped separately from GNUnet.  After
164 downloading and installing gnunet-gtk, you can invoke the GUI with:
165
166 $ gnunet-gtk
167
168 For Qt/KDE users, there is also a QT user interface (also shipped 
169 separately).  If you install gnunet-qt, you can invoke the GUI with:
170
171 $ gnunet-qt
172
173 If you want to use the shell (part of this distribution), use
174
175 $ gnunet-search KEYWORD
176
177 This will display a list of results to the console. Then use
178
179 $ gnunet-download -o FILENAME GNUNET_URI
180
181 to retrieve a file.  The GNUNET_URI is printed by gnunet-search
182 together with a description.
183
184 In order to share files, the easiest way is to create a directory
185 with the files (and directories) that you want to share and run
186
187 $ nohup gnunet-auto-share NAME-OF-THE-DIRECTORY &
188
189 For further documentation, see our webpage.
190
191
192 Hacking GNUnet
193 ==============
194
195 Contributions are welcome, please submit bugs to
196 https://gnunet.org/mantis/.  Please make sure to run contrib/report.sh
197 and include the output with your bug reports.  More about how to
198 report bugs can be found in the GNUnet FAQ on the webpage.  Submit
199 patches via E-Mail to gnunet-developers@gnu.org.
200
201 In order to run the unit tests with "make check", you need to
202 set an environment variable ("GNUNET_PREFIX") to the directory
203 where GNUnet is installed (usually, GNUnet will use OS specific
204 tricks in order to try to figure out the PREFIX, but since the
205 testcase binaries are not installed, that trick does not work
206 for them).  Also, before running any testcases, you must
207 complete the installation first.  Quick summary:
208
209 $ ./configure --prefix=$SOMEWHERE
210 $ make
211 $ make install
212 $ export GNUNET_PREFIX=$SOMEWHERE
213 $ make check
214
215 If any testcases fail to pass on your system, run "contrib/report.sh"
216 and report the output together with information about the failing
217 testcase to the Mantis bugtracking system at
218 https://gnunet.org/mantis/.
219
220
221 Running http on port 80
222 =======================
223
224 In order to hide GNUnet's HTTP traffic perfectly, you might consider
225 running GNUnet's HTTP transport on port 80.  However, you should not
226 run GNUnet as root.  Instead, forward port 80 to say 8080 with this
227 command (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
231 Then set in the HTTP section of gnunetd.conf the "ADVERTISED-PORT"
232 to "80" and "PORT" to 8080.   You can do the same trick for the
233 TCP and UDP transports if you want to map them to a priviledged
234 port (from the point of view of the network).
235
236
237 Running the SMTP transport
238 ==========================
239
240 Running GNUnet over SMTP (e-mail) is a bit more involved.  Note that
241 you do not need to run all transports (only running the NAT transport
242 is the only thing that will not work).  If you really want to do
243 P2P over SMTP, read the instructions at http://gnunet.org/smtp.php3
244
245
246 Stay 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