                       Welcome to GNUnet


What is GNUnet?
===============

GNUnet is peer-to-peer framework focusing on security.  The first and
primary application for GNUnet is anonymous file-sharing.  GNUnet is
currently developed at Purdue University with support from a worldwide
group of independent free software developers.  GNUnet is a part of
the GNU project (http://www.gnu.org/).

This is a BETA release.  The network has not been tested on a large
scale yet.  While there are no known significant bugs, we are still
changing significant aspects of the system in any other version.  Bugs
are common and the documentation may not be adequate for unexperienced
users.

For a longer description of the GNUnet System see our webpages
http://www.gnu.org/projects/GNUnet/ and http://www.ovmj.org/GNUnet/.


How to install?
===============

The fastest way is to use the binary RPM or any other package if it is
available for your system.  For a more detailed description, read the
installation instructions on the webpage at
http://www.ovmj.org/GNUnet/documentation.php3.

If you just want to go with the sources, you may be fine with

# contrib/autoinstall

which is doing little more than what you would for a single-user
installation to $HOME which can be achieved with:

# ./configure --prefix=$HOME
# make install
# mkdir ~/.gnunet
# cp contrib/gnunet.conf ~/.gnunet/

This will compile and install GNUnet to ~/bin/, ~/lib/ and ~/man/ and
put the configuration file where GNUnet expects it.  For more general
information about the GNU build process read the INSTALL file.

If you want to use libextractor (download from
http://www.ovmj.org/~samanta/libextractor/) for automated keyword
extraction (recommended) you may have to pass the additional flag
"--with-extractor=PATH-TO-LIBEXTRACTOR" to configure.  You should also
make sure that libextractor is actually found by the linker.

If OpenSSL is not found by configure, you may need to specify
--with-openssl=DIRECTORY to point to the base for your openssl
installation, i.e.

# ./configure --with-openssl=/usr/local/openssl. 

If you are compiling the CVS version, you have to run ./bootstrap
before ./configure.  If you receive an error during the running of
./bootstrap that looks like " macro `AM_PATH_GTK' not found in
library", you may need to run aclocal by hand with the -I option,
pointing to your aclocal m4 macros, i.e.

# aclocal -I /usr/local/share/aclocal

The default configuration file for users that is provided under
"contrib/gnunet.conf" should be put under "/etc/gnunet.conf" and
"/etc/skel/.gnunet/gnunet.conf".  In order to start a "permanent"
node, you should create a new user "gnunet" and start "gnunetd" as
that user whenever the system boots.  The file contrib/initgnunet in
the source distribution contains a script that may be helpful for that
purpose.  The RPM installs the script in /etc/init.d/gnunetd.  Note
that you still have to enable the service by creating the appropriate
links to start gnunetd at boot time.

GNUnet needs to store data in a simple database. We currently support
MySQL, GDBM, BerkeleyDB and TDB.  You can also use a simple directory,
but this will be slow.

autoconf >= 2.52 is recommended for compiling the CVS version.
libextractor >= 0.2.3 is highly recommended.


Trouble with OpenSSL?
=====================

A user remarked that if you get errors relating to OpenSSL, such as
openssl/rsa.h not found or linking against -lcrypt failed, you may
want to try to install openssl using some arguments to config:

# ./config --prefix=/usr/local --with-openssl=/usr/local/openssl

You can also try to specify --with-openssl=PREFIX when configuring
GNUnet to point to your SSL installation. Note that the openssl
*binary* must be in your path, so if 

# openssl version

prints "command not found" or the wrong version number, fix your
$PATH ("export PATH=/wherever/openssl/is/bin:$PATH").


Using libgcrypt instead of OpenSSL?
===================================

GNUnet >=0.5.1 can be compiled against libgcrypt using the option
--with-gcrypt=DIR.  Note that at the moment libgcrypt produces random
problems with RSA.

DO NOT use libgcrypt unless you want to TEST and FIX the remaining
problems.  If there is a bug in the code, send a patch to the
libgcrypt maintainers or to the GNUnet developers, but do not complain
about problems on either mailinglist.  If you just want to run GNUnet,
we suggest you use OpenSSL for now.  We want to switch to libgcrypt in
the future, but so far libgcrypt does not seem to be ready for this.


Configuration
=============

The defaults are usually ok, you may want to adjust the limitations
(space consumption, bandwidth, etc.) though.  If you want to
configure, edit "/etc/gnunet.conf" or "~/.gnunet/gnunet.conf"
(whichever applies).

If you want to use a different configuration file, pass the name of
the configuration file as an argument with the option -c to any GNUnet
application.  Sending a SIGHUP to the gnunetd process will cause
gnunetd to re-read the configuration file.  Note that not all options
can be changed at run-time this way (e.g. to change any port number,
you must fully restart gnunetd).

In order to use the SMTP transport service, you should read
http://www.ovmj.org/GNUnet/smtp.php3 first!  Note that if you have a
globally addressable IP or full control over your NAT box, the TCP or
UDP services will suffice.


Usage
=====

First, you must obtain an initial list of GNUnet hosts.  Knowing a
single peer is sufficient since after that GNUnet propagates
information about other peers.  Note that the default "gnunet.conf"
contains a URL from where gnunetd downloads an initial hostlist
whenever it is started.  If you want to create an alternative URL for
others to use, the file can be generated on any machine running
gnunetd by periodically executing

# cat ~/.gnunet/data/hosts/* > the_file

If the solution with the URL is not feasible for your situation, you
can also add hosts manually.  The GNUnet webpage has a public
directory of hostkeys under http://www.ovmj.org/GNUnet/hosts/.  You
can of course use any other source for these files.  Copy the hostkeys
to "~/.gnunet/data/hosts/" (or to another directory, depending on your
"~/.gnunet/gnunet.conf" configuration file).

Now start the local node using "gnunetd".  gnunetd should run whenever
you are online.  You may start it as a service with
"/etc/init.d/gnunetd start".  To insert files into GNUnet, use the
tools "gnunet-insert" and "gnunet-insert-multi".

If want to use a GUI, just invoke 

# gnunet-gtk

If you want to use the shell, use

# gnunet-search KEYWORD

This will display a list of results to the console. Then use

# gnunet-download -o FILENAME -- HASH1 HASH2 FILESIZE CRC

to retrieve a file.  The HASHes, FILESIZE and CRC are printed by
gnunet-search together with a description.

For further documentation, see our webpage.


Hacking GNUnet
==============

Contributions are welcome, please submit bugs to
http://www.ovmj.org/~mantis/.  Please make sure to run
contrib/report.sh and include the output with your bug reports.
Submit patches via E-Mail to gnunet-developers@gnu.org.


Stay tuned
==========

* http://www.gnu.org/software/GNUnet/
* http://www.ovmj.org/GNUnet/
* http://mail.gnu.org/mailman/listinfo/gnunet-developers
* http://mail.gnu.org/mailman/listinfo/help-gnunet
* http://mail.gnu.org/mailman/listinfo/info-gnunet
