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