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