-fix
[oweals/gnunet.git] / README
diff --git a/README b/README
index 905d97d3b8c5989bedcff80ccbf29374c05db4c9..b2b7233eda51e2df7789cfbb0a9fb18c4c46b008 100644 (file)
--- a/README
+++ b/README
@@ -19,26 +19,30 @@ https://gnunet.org/.
 Dependencies:
 =============
 
-For the impatient, here is the list of immediate dependencies for
-running GNUnet:
+Please note that for many of its dependencies GNUnet requires very
+recent versions of the libraries which are often NOT to be found in
+stable distributions in 2011.  While using older packages may in some
+cases on some operating systems may seem to work in some limited
+fashion, we are in many cases aware of serious problems with older
+packages.  Hence please make sure to use  the versions listed below.
+
+These are the direct dependencies for running GNUnet:
 
 - libextractor  >= 0.6.1
-- libmicrohttpd >= 0.4.6
+- libmicrohttpd >= 0.9.18
 - libgcrypt     >= 1.2
-- libgmp        >= 4.0
-- libcurl       >= 7.15.4
+- libcurl       >= 7.21.0
+- libunistring  >= 0.9.2
 - libltdl       >= 2.2 (part of GNU libtool)
-- sqlite        >= 3.0 (alternative to MySQL)
-- mysql         >= ??? (not yet supported)
-- postgres      >= ??? (not yet supported)
+- sqlite        >= 3.0 (default database)
+- mysql         >= 5.1 (alternative to sqLite)
+- postgres      >= 8.3 (alternative to sqLite)
 
 Recommended autotools for compiling the SVN version are:
 - autoconf >= 2.59
 - automake >= 1.11.1
 - libtool  >= 2.2 
 
-See also README.debian for a list of Debian packages.
-
 
 How to install?
 ===============
@@ -47,38 +51,62 @@ The fastest way is to use a binary package if it is available for your
 system.  For a more detailed description, read the installation
 instructions on the webpage at https://gnunet.org/installation.
 
+Note that some functions of GNUnet require "root" access.  GNUnet will
+install (tiny) SUID binaries for those functions is you run "make
+install" as root.  If you do not, GNUnet will still work, but some
+functionality will not be available (including certain forms of NAT
+traversal).
+
 GNUnet requires the GNU MP library (http://www.gnu.org/software/gmp/)
 and libgcrypt (http://www.gnupg.org/).  You can specify the path to
 libgcrypt by passing "--with-gcrypt=PATH" to configure.  You will also
-need either sqlite (http://www.sqlite.org/) or MySQL
-(http://www.mysql.org/).
+need either sqlite (http://www.sqlite.org/), MySQL
+(http://www.mysql.org/) or PostGres (http://www.postgres.org/).
 
 If you install from source, you need to install GNU libextractor first
 (download from http://www.gnu.org/software/libextractor/).  We also
 recommend installing GNU libmicrohttpd (download from
 http://www.gnu.org/software/libmicrohttpd/).  Then you can start the
-actual GNUnet compilation process with:
+actual GNUnet compilation and installation process with:
 
-$ ./configure --prefix=$HOME --with-extractor=$HOME
+$ export GNUNET_PREFIX=/usr/local # or other directory of your choice
+$ addgroup gnunetdns
+$ adduser gnunet gnunet
+$ ./configure --prefix=$GNUNET_PREFIX --with-extractor=$LE_PREFIX
 $ make
 # make install
 # sudo -u gnunet mkdir ~/.gnunet/ 
 # sudo -u gnunet touch ~/.gnunet/gnunet.conf
 # sudo -u gnunet gnunet-arm -s
 
-This will compile and install GNUnet to $HOME/bin/, $HOME/lib/ and
-$HOME/share/ and start the system with the default configuration.  It
-is recommended that you add a user "gnunet" to run "gnunet-arm".  You
-can then still run the end-user applications as another user.  If you
-create a user "gnunet", it is recommended that you edit the
-configuration file slightly so that data can be stored in
-"/var/lib/gnunet"; you may also want to use "/etc/gnunet.conf" for the
-location of the configuration file in this case.
+This will create the users and groups needed for running GNUnet
+securely and then compile and install GNUnet to $GNUNET_PREFIX/bin/,
+$GNUNET_PREFIX/lib/ and $GNUNET_PREFIX/share/ and start the system
+with the default configuration.  It is strongly recommended that you
+add a user "gnunet" to run "gnunet-arm".  You can then still run the
+end-user applications as another user.  
+
+If you create a system user "gnunet", it is recommended that you edit
+the configuration file slightly so that data can be stored in the
+system user home directory at "/var/lib/gnunet"; you may also want to
+use "/etc/gnunet.conf" for the location of the configuration file in
+this case.
+
+You can avoid running 'make install' as root if you run configure
+with the "--with-sudo=yes" option and have extensive sudo rights
+(can run "chmod +s" and "chown" via 'sudo').  If you run 'make install'
+as a normal user without sudo rights (or the configure option),
+certain binaries that require additional priviledges will not be
+installed properly (and autonomous NAT traversal, WLAN, DNS/GNS and 
+the VPN will then not work).
 
 Note that additional, per-user configuration files
 (~/.gnunet/gnunet.conf) need to be created by each user (for example,
-by running gnunet-setup). For more general information about the GNU
-build process read the INSTALL file.
+by running gnunet-setup).  Note that gnunet-setup is a separate
+download and requires recent versions of GTK+ and Glade; you can also
+edit the configuration file by hand, but this is not recommended.  For
+more general information about the GNU build process read the INSTALL
+file.
 
 If you are compiling the code from subversion, you have to run
 ". bootstrap" before ./configure.  If you receive an error during the
@@ -93,19 +121,19 @@ Configuration
 =============
 
 GNUnet uses two types of configuration files, one that specifies the
-system-wide defaults (typically located in /usr/share/gnunet/defaults
-.conf) and a second one that overrides default values with
-user-specific preferences.  The user-specific configuration file
-should be located in "~/.gnunet/gnunet.conf" or its location can be
-specified by giving the "-c" option to the respective GNUnet
-application.
+system-wide defaults (typically located in
+$GNUNET_PREFIX/share/gnunet/config.d/) and a second one that overrides
+default values with user-specific preferences.  The user-specific
+configuration file should be located in "~/.gnunet/gnunet.conf" or its
+location can be specified by giving the "-c" option to the respective
+GNUnet application.
 
 The defaults that are shipped with the installation are usually ok,
 you may want to adjust the limitations (space consumption, bandwidth,
 etc.) though.  The configuration files are human-readable.  Note that
 you MUST create "~/.gnunet/gnunet.conf" explicitly before starting
-GNUnet.  You can either copy "defaults.conf" or simply create an empty
-file.
+GNUnet.  You can either run gnunet-setup (available as part of the
+gnunet-gtk source package) or simply create an empty file.
 
 
 Usage
@@ -132,20 +160,9 @@ to "$SERVICEHOME/data/hosts/" (where $SERVICEHOME is the directory
 specified in the gnunet.conf configuration file).
 
 Now start the local node using "gnunet-arm -s".  GNUnet should run 24/7 if
-you want to maximize your anonymity.  
-
-The GTK user interface is shipped separately.  After downloading and
-installing gnunet-gtk, you can invoke the GUI with:
-
-$ gnunet-gtk
-
-// FIXME: gnunet-qt is not yet supported in 0.9.x
-For Qt/KDE users, there is also a QT user interface (also shipped 
-separately).  If you install gnunet-qt, you can invoke the GUI with:
+you want to maximize your anonymity.
 
-$ gnunet-qt
-
-If you want to use the shell (part of this distribution), use
+You should then be able to access GNUnet using the shell:
 
 $ gnunet-search KEYWORD
 
@@ -157,11 +174,13 @@ to retrieve a file.  The GNUNET_URI is printed by gnunet-search
 together with a description.  To publish files on GNUnet, use the
 "gnunet-publish" command.
 
-// FIXME: auto-share is not yet supported in 0.9.x
-In order to share files, the easiest way is to create a directory
-with the files (and directories) that you want to share and run
 
-$ nohup gnunet-auto-share NAME-OF-THE-DIRECTORY &
+The GTK user interface is shipped separately.  After downloading and
+installing gnunet-gtk, you can invoke the setup tool and the 
+file-sharing GUI with:
+
+$ gnunet-setup
+$ gnunet-fs-gtk
 
 For further documentation, see our webpage.
 
@@ -189,36 +208,36 @@ $ make install
 $ export GNUNET_PREFIX=$SOMEWHERE
 $ make check
 
-If any testcases fail to pass on your system, run "contrib/report.sh"
-and report the output together with information about the failing
-testcase to the Mantis bugtracking system at
-https://gnunet.org/bugs/.
+Some of the testcases require python >= 2.6 and pexpect to be
+installed.  If any testcases fail to pass on your system, run 
+"contrib/report.sh" and report the output together with 
+information about the failing testcase to the Mantis bugtracking 
+system at https://gnunet.org/bugs/.
 
 
-Running http on port 80
-=======================
+Running http on port 80 and https on port 443
+=============================================
 
-In order to hide GNUnet's HTTP traffic perfectly, you might consider
-running GNUnet's HTTP transport on port 80.  However, we do not
-recommend running GNUnet as root.  Instead, forward port 80 to say
-8080 with this command (as root, in your startup scripts):
+In order to hide GNUnet's HTTP/HTTPS traffic perfectly, you might
+consider running GNUnet's HTTP/HTTPS transport on port 80/443.
+However, we do not recommend running GNUnet as root.  Instead, forward
+port 80 to say 8080 with this command (as root, in your startup
+scripts):
 
 # iptables -t nat -A PREROUTING -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 8080
 
-Then set in the HTTP section of gnunet.conf the "ADVERTISED-PORT"
-to "80" and "PORT" to 8080.   You can do the same trick for the
-TCP and UDP transports if you want to map them to a priviledged
-port (from the point of view of the network).
+or for HTTPS
 
+# iptables -t nat -A PREROUTING -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 4433
 
-Running the SMTP transport
-==========================
+Then set in the HTTP section of gnunet.conf the "ADVERTISED-PORT" to
+"80" and "PORT" to 8080 and similarly in the HTTPS section the
+"ADVERTISED-PORT" to "443" and "PORT" to 4433.
 
-// NOTE: SMTP is not currently available in this version of GNUnet
-Running GNUnet over SMTP (e-mail) is a bit more involved.  Note that
-you do not need to run all transports (only running the NAT transport
-is the only thing that will not work).  If you really want to do
-P2P over SMTP, read the instructions at http://gnunet.org/smtp.php3
+You can do the same trick for the TCP and UDP transports if you want
+to map them to a priviledged port (from the point of view of the
+network).  However, we are not aware of this providing any advantages
+at this point.
 
 
 Stay tuned