README.md

   1 <p align="center">
   2   <a href="https://gnunet.org"><img src="contrib/branding/logo/gnunet-logo-dark-text.svg" alt="GNUnet" width="300px"/></a>
   3 </p>
   4
   5 > GNUnet is a *new* network protocol stack for building secure, distributed, and privacy-preserving applications.
   6
   7 * [Install](#how-to-install-gnunet)
   8   * [From Source](#from-source)
   9   * [Using Docker](#docker)
  10 * [Using GNUnet](#using-gnunet)
  11 * [License](#license)
  12
  13 How to Install GNUnet
  14 ---------------------
  15
  16 ### 1. From Source
  17
  18 **Dependencies**
  19
  20 Install these packages. Some of them may need to be installed from source depending on your OS.
  21
  22 ```
  23 - libmicrohttpd      >= 0.9.42      (available from https://www.gnu.org/software/libmicrohttpd/)
  24 - libgcrypt          >= 1.6
  25 - libgnurl           >= 7.35.0      (recommended, available from https://gnunet.org/gnurl)
  26 - libcurl            >= 7.35.0      (alternative to libgnurl)
  27 - libunistring       >= 0.9.2
  28 - gnutls             >= 3.2.12      (highly recommended: a gnutls linked against libunbound)
  29 - libidn             >= 1.0
  30 - libextractor       >= 0.6.1       (highly recommended)
  31 - openssl            >= 1.0         (binary, used to generate X.509 certificate)
  32 - libltdl            >= 2.2         (part of GNU libtool)
  33 - sqlite             >= 3.8         (default database, required)
  34 - mysql              >= 5.1         (alternative to sqlite)
  35 - postgres           >= 9.5         (alternative to sqlite)
  36 - Texinfo            >= 5.2         [*1]
  37 - which                             (for the bootstrap script)
  38 - gettext
  39 - zlib
  40 - pkg-config
  41 ```
  42
  43
  44 You can also install the dependencies with the [GNU Guix package manager:](https://https://www.gnu.org/software/guix/) by using the provided environment file:
  45
  46 ```shell
  47 guix package -l guix-env.scm
  48 ```
  49
  50
  51 **Using GNU Make**
  52
  53 ```shell
  54 ./bootstrap # Run this to generate the configure files.
  55 ./configure # See the various flags avalable to you.
  56 make
  57 make install
  58 ```
  59
  60 **Using the [GNU Guix package manager:](https://https://www.gnu.org/software/guix/)**
  61
  62 ```shell
  63 # To build, run tests, and install:
  64 guix package -f guix-env.scm
  65
  66 # To skip the testing phase:
  67 guix package -f guix-env.scm:notest
  68 ```
  69
  70
  71 ### 2. Docker
  72
  73 ```
  74 # From within the top-level of this repository run:
  75 docker build -t gnunet -f ./contrib/docker/Dockerfile .
  76 ```
  77
  78 For more info on using the docker container see [here](contrib/docker/README.md).
  79
  80
  81
  82 Using GNUnet
  83 -------------
  84
  85 There are many possible ways to use the subsystems of GNUnet, so we will provide a few examples in this section.
  86
  87 <p align="center">
  88   <a href="contrib/gnunet-arch-full.svg"><img src="contrib/gnunet-arch-full.svg" alt="GNUnet Modular Architecture" width="600px" border="1px"/></a>
  89 </p>
  90
  91 >***GNUnet is composed of over 30 modular subsystems***
  92
  93
  94 ### Start GNUnet Services
  95
  96 Before we can begin using most of the components we must start them.
  97
  98 ```shell
  99 gnunet-arm --start
 100 ```
 101
 102 Now we can open up another shell and try using some of the modules.
 103
 104 ### Cadet
 105
 106 #### Examples
 107
 108 Open a Cadet connection:
 109
 110 ```shell
 111 # Node 1
 112 gnunet-cadet -o <shared secret>
 113 ```
 114
 115 Conect to peer:
 116
 117 ```shell
 118 # Node 2
 119 gnunet-cadet <peer-id of Node 1> <shared secret>
 120 ```
 121
 122 #### Sharing Files
 123
 124 With the cli tool, you can also share files:
 125
 126 ```shell
 127 # Node 1
 128 gnunet-cadet -o <shared secret> > filename
 129 ```
 130
 131 On the Node 2 we're going to send the file to Node 1, and to do this we need to make use of [coprocesses](https://www.gnu.org/software/bash/manual/html_node/Coprocesses.html).
 132 The syntax for using coprocesses varies per shell. In our example we are assuming Bash. More info for different shells can be found [here](https://unix.stackexchange.com/questions/86270/how-do-you-use-the-command-coproc-in-various-shells)
 133
 134 ```shell
 135 # Node 2
 136 coproc gnunet-cadet <peer-id of Node 1> <shared secret>
 137 cat <file> >&"${COPROC[1]}"
 138 ```
 139
 140 Now this enables us to do some fun things, such as streaming video by piping to a media player:
 141
 142 ```shell
 143 # Node 1
 144 gnunet-cadet -o <shared secret> | vlc -
 145 ```
 146
 147 ```shell
 148 # Node 2
 149 coproc gnunet-cadet <peer-id of Node 1> <shared secret>
 150 cat <video-file> >&"${COPROC[1]}"
 151 ```
 152
 153 ### Filesharing
 154
 155 You can use GNUnet as a content-addressed storage, much like IPFS: sharing immutable files in a decentralized fashion with added privacy.
 156
 157 For instance, you can get a nice cat picture with
 158 ```sh
 159 gnunet-download gnunet://fs/loc/CB0ZX5EM1ZNNRT7AX93RVHCN1H49242DWZ4AXBTCJBAG22Z33VHYMR61J71YJXTXHEC22TNE0PRWA6D5X7NFNY2J9BNMG0SFN5DKZ0G.R48JSE2T4Y3W2AMDHZYX2MMDJC4HR0BVTJYNWJT2DGK7EQXR35DT84H9ZRAK3QTCTHDBAE1S6W16P8PCKC4HGEEKNW2T42HXF9RS1J0.1906755.J5Z3BDEG2PW332001GGZ2SSKCCSV8WDM696HNARG49X9TMABC4DG.B6Y7BCJ6B5K40EXCXASX1HQAD8MBJ9WTFWPCE3F15Q3Q4Y2PB8BKVGCS5HA4FG4484858NB74PBEE5V1638MGG7NS40A82K7QKK3G0G.1577833200 --output cat.png
 160 ```
 161
 162 You can also give files to the network, like so:
 163
 164 ```sh
 165 $ echo "I love GNUnet" > ILoveGNUnet.txt
 166 $ gnunet-publish ILoveGNUnet.txt
 167
 168 Publishing `/tmp/ILoveGNUnet.txt` done.
 169 URI is `gnunet://fs/chk/SXA4RGZWDHE4PDWD2F4XG778J4SZY3E3SNDZ9AWFRZYYBV52W1T2WQNZCF1NYAT842800SSBQ8F247TG6MX7H4S1RWZZSC8ZXGQ4YPR.AZ3B5WR1XCWCWR6W30S2365KFY7A3R5AMF5SRN3Z11R72SMVQDX3F6GXQSZMWZGM5BSYVDQEJ93CR024QAAE65CKHM52GH8MZK1BM90.14`.
 170 ```
 171
 172 The URI you get is what you can use to retrieve the file with `gnunet-download`.
 173
 174 ### GNS
 175
 176 *coming soon*
 177
 178
 179 ### VPN
 180
 181 #### "Half-hidden" services
 182
 183 You can tunnel IP traffic through GNUnet allowing you to offer web, [rsh](https://linux.die.net/man/1/rsh), messaging or other servers without revealing your IP address.
 184
 185 This is similar to Tor's Hidden (aka Onion) services, but currently does not provide as much privacy as onion routing isn't yet implemented; on the other hand, you can tunnel UDP, unlike Tor.
 186
 187 #### Configuring server
 188
 189 First, set up access from GNUnet to IP with `exit`:
 190
 191 `gnunet.conf`:
 192 ```
 193 [exit]
 194 FORCESTART = YES
 195 EXIT_IPV4 = YES
 196 EXIT_RANGE_IPV4_POLICY = 169.254.86.1;
 197 ```
 198
 199 Exit, by the way can also be used as a general-purpose IP proxy i.e. exit relay but here we restrict IPs to be accessed to those we'll be serving stuff on only.
 200
 201 Then, start up a server to be shared. For the sake of example,
 202
 203 ```sh
 204 python3 -m http.server 8080
 205 ```
 206
 207 Now to configure the actual "half-hidden service". The config syntax is as follows:
 208
 209 ```sh
 210 [<shared secret>.gnunet.]
 211 TCP_REDIRECTS = <exposed port>:<local IP>:<local port>
 212 ```
 213
 214 ...which for our example would be
 215
 216 ```sh
 217 [myhttptest.gnunet.]
 218 TCP_REDIRECTS = 80:169.254.86.1:8080
 219 ```
 220
 221 Local IP can be anything (if allowed by other configuration) but a localhost address (in other words, you can't bind a hidden service to the loopback interface and say 127.0.0.1 in `TCP_REDIRECTS`). The packets will appear as coming from the exit TUN interface to whatever address is configured in `TCP_REDIRECTS` (unlike SSH local forwarding, where the packets appear as coming from the loopback interface) and so they will not be forwarded to 127.0.0.1.
 222
 223 You can share access to this service with a peer id, shared secret and IP port numbler: here `gnunet-peerinfo -s`, `myhttptest` and `80` respectively.
 224
 225 #### Connecting
 226
 227 `gnunet-vpn` gives you ephemeral IPs to connect to if you tell it a peer id and a shared secret, like so:
 228
 229 ```sh
 230 $ gnunet-vpn -p N7R25J8ADR553EPW0NFWNCXK9V80RVCP69QJ47XMT82VKAR7Y300 -t -s myhttptest
 231 10.11.139.20
 232
 233 # And just connect to the given IP
 234 $ wget 10.11.139.20
 235 Connecting to 10.11.139.20:80... connected.
 236 ```
 237
 238 (You can try it out with your browser too.)
 239
 240 ### Running a Hostlist Server
 241
 242 *coming soon*
 243
 244 GNUnet Configuration
 245 --------------------------
 246 ### Examples
 247
 248 ```yaml
 249 [transport]
 250 OPTIONS = -L DEBUG
 251 PLUGINS = tcp
 252 #PLUGINS = udp
 253
 254 [transport-tcp]
 255 OPTIONS = -L DEBUG
 256 BINDTO = 192.168.0.2
 257 ```
 258
 259 TODO: *explain what this does and add more*
 260
 261
 262 Philosophy
 263 -------------------------
 264
 265 GNUnet is made for an open society: It's a self-organizing network and it's (free software)[https://www.gnu.org/philosophy/free-sw.html] as in freedom. GNUnet puts you in control of your data. You determine which data to share with whom, and you're not pressured to accept compromises.
 266
 267
 268 Related Projects
 269 -------------------------
 270
 271  <a href="https://pep.foundation"><img src="https://pep.foundation/static/media/uploads/peplogo.svg" alt="pep.foundation" width="80px"/></a>  <a href="https://secushare.org"><img src="https://secushare.org/img/secushare-0444.png" alt="Secushare" width="80px"/></a>