                       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
# make install
# cp contrib/gnunet.root /etc/gnunet.conf
# cp contrib/initgnunet /etc/init.d/gnunetd
$ mkdir ~/.gnunet
$ cp contrib/gnunet.user ~/.gnunet/gnunet.conf

This will compile and install GNUnet to ~/bin/, ~/lib/ and ~/man/ and
put the configuration files where GNUnet expects them.  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/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 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 gnunetd that is provided under
"contrib/gnunet.root" should be put under "/etc/gnunet.conf".  The
per-user configuration from "contrib/gnunet.user" should be put in
every home directory under "~/.gnunet/gnunet.conf" and as a template
in "/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.57 is recommended for compiling the CVS version.
libextractor >= 0.2.6 is highly recommended.


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" and "~/.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 $GNUNETD-HOME/.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 "$GNUNETD-HOME/.gnunet/data/hosts/" (where $GNUNETD_HOME is the
directory specified in the /etc/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
"gnunet-insert" command.

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 -- GNUNET_URI

to retrieve a file.  The GNUNET_URI is 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
