diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 000000000..3f40b3d87 --- /dev/null +++ b/README.md | |||
@@ -0,0 +1,268 @@ | |||
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 | docker build -t gnunet . | ||
75 | ``` | ||
76 | |||
77 | |||
78 | |||
79 | Using GNUnet | ||
80 | ------------- | ||
81 | |||
82 | There are many possible ways to use the subsystems of GNUnet, so we will provide a few examples in this section. | ||
83 | |||
84 | <p align="center"> | ||
85 | <a href="contrib/gnunet-arch-full.svg"><img src="contrib/gnunet-arch-full.svg" alt="GNUnet Modular Architecture" width="600px" border="1px"/></a> | ||
86 | </p> | ||
87 | |||
88 | >***GNUnet is composed of over 30 modular subsystems*** | ||
89 | |||
90 | |||
91 | ### Start GNUnet Services | ||
92 | |||
93 | Before we can begin using most of the components we must start them. | ||
94 | |||
95 | ```shell | ||
96 | gnunet-arm --start | ||
97 | ``` | ||
98 | |||
99 | Now we can open up another shell and try using some of the modules. | ||
100 | |||
101 | ### Cadet | ||
102 | |||
103 | #### Examples | ||
104 | |||
105 | Open a Cadet connection: | ||
106 | |||
107 | ```shell | ||
108 | # Node 1 | ||
109 | gnunet-cadet -o <shared secret> | ||
110 | ``` | ||
111 | |||
112 | Conect to peer: | ||
113 | |||
114 | ```shell | ||
115 | # Node 2 | ||
116 | gnunet-cadet <peer-id of Node 1> <shared secret> | ||
117 | ``` | ||
118 | |||
119 | #### Sharing Files | ||
120 | |||
121 | With the cli tool, you can also share files: | ||
122 | |||
123 | ```shell | ||
124 | # Node 1 | ||
125 | gnunet-cadet -o <shared secret> > filename | ||
126 | ``` | ||
127 | |||
128 | 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). | ||
129 | 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) | ||
130 | |||
131 | ```shell | ||
132 | # Node 2 | ||
133 | coproc gnunet-cadet <peer-id of Node 1> <shared secret> | ||
134 | cat <file> >&"${COPROC[1]}" | ||
135 | ``` | ||
136 | |||
137 | Now this enables us to do some fun things, such as streaming video by piping to a media player: | ||
138 | |||
139 | ```shell | ||
140 | # Node 1 | ||
141 | gnunet-cadet -o <shared secret> | vlc - | ||
142 | ``` | ||
143 | |||
144 | ```shell | ||
145 | # Node 2 | ||
146 | coproc gnunet-cadet <peer-id of Node 1> <shared secret> | ||
147 | cat <video-file> >&"${COPROC[1]}" | ||
148 | ``` | ||
149 | |||
150 | ### Filesharing | ||
151 | |||
152 | You can use GNUnet as a content-addressed storage, much like IPFS: sharing immutable files in a decentralized fashion with added privacy. | ||
153 | |||
154 | For instance, you can get a nice cat picture with | ||
155 | ```sh | ||
156 | gnunet-download gnunet://fs/loc/CB0ZX5EM1ZNNRT7AX93RVHCN1H49242DWZ4AXBTCJBAG22Z33VHYMR61J71YJXTXHEC22TNE0PRWA6D5X7NFNY2J9BNMG0SFN5DKZ0G.R48JSE2T4Y3W2AMDHZYX2MMDJC4HR0BVTJYNWJT2DGK7EQXR35DT84H9ZRAK3QTCTHDBAE1S6W16P8PCKC4HGEEKNW2T42HXF9RS1J0.1906755.J5Z3BDEG2PW332001GGZ2SSKCCSV8WDM696HNARG49X9TMABC4DG.B6Y7BCJ6B5K40EXCXASX1HQAD8MBJ9WTFWPCE3F15Q3Q4Y2PB8BKVGCS5HA4FG4484858NB74PBEE5V1638MGG7NS40A82K7QKK3G0G.1577833200 --output cat.png | ||
157 | ``` | ||
158 | |||
159 | You can also give files to the network, like so: | ||
160 | |||
161 | ```sh | ||
162 | $ echo "I love GNUnet" > ILoveGNUnet.txt | ||
163 | $ gnunet-publish ILoveGNUnet.txt | ||
164 | |||
165 | Publishing `/tmp/ILoveGNUnet.txt` done. | ||
166 | URI is `gnunet://fs/chk/SXA4RGZWDHE4PDWD2F4XG778J4SZY3E3SNDZ9AWFRZYYBV52W1T2WQNZCF1NYAT842800SSBQ8F247TG6MX7H4S1RWZZSC8ZXGQ4YPR.AZ3B5WR1XCWCWR6W30S2365KFY7A3R5AMF5SRN3Z11R72SMVQDX3F6GXQSZMWZGM5BSYVDQEJ93CR024QAAE65CKHM52GH8MZK1BM90.14`. | ||
167 | ``` | ||
168 | |||
169 | The URI you get is what you can use to retrieve the file with `gnunet-download`. | ||
170 | |||
171 | ### GNS | ||
172 | |||
173 | *coming soon* | ||
174 | |||
175 | |||
176 | ### VPN | ||
177 | |||
178 | #### "Half-hidden" services | ||
179 | |||
180 | 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. | ||
181 | |||
182 | 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. | ||
183 | |||
184 | #### Configuring server | ||
185 | |||
186 | First, set up access from GNUnet to IP with `exit`: | ||
187 | |||
188 | `gnunet.conf`: | ||
189 | ``` | ||
190 | [exit] | ||
191 | FORCESTART = YES | ||
192 | EXIT_IPV4 = YES | ||
193 | EXIT_RANGE_IPV4_POLICY = 169.254.86.1; | ||
194 | ``` | ||
195 | |||
196 | 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. | ||
197 | |||
198 | Then, start up a server to be shared. For the sake of example, | ||
199 | |||
200 | ```sh | ||
201 | python3 -m http.server 8080 | ||
202 | ``` | ||
203 | |||
204 | Now to configure the actual "half-hidden service". The config syntax is as follows: | ||
205 | |||
206 | ```sh | ||
207 | [<shared secret>.gnunet.] | ||
208 | TCP_REDIRECTS = <exposed port>:<local IP>:<local port> | ||
209 | ``` | ||
210 | |||
211 | ...which for our example would be | ||
212 | |||
213 | ```sh | ||
214 | [myhttptest.gnunet.] | ||
215 | TCP_REDIRECTS = 80:169.254.86.1:8080 | ||
216 | ``` | ||
217 | |||
218 | 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. | ||
219 | |||
220 | 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. | ||
221 | |||
222 | #### Connecting | ||
223 | |||
224 | `gnunet-vpn` gives you ephemeral IPs to connect to if you tell it a peer id and a shared secret, like so: | ||
225 | |||
226 | ```sh | ||
227 | $ gnunet-vpn -p N7R25J8ADR553EPW0NFWNCXK9V80RVCP69QJ47XMT82VKAR7Y300 -t -s myhttptest | ||
228 | 10.11.139.20 | ||
229 | |||
230 | # And just connect to the given IP | ||
231 | $ wget 10.11.139.20 | ||
232 | Connecting to 10.11.139.20:80... connected. | ||
233 | ``` | ||
234 | |||
235 | (You can try it out with your browser too.) | ||
236 | |||
237 | ### Running a Hostlist Server | ||
238 | |||
239 | *coming soon* | ||
240 | |||
241 | GNUnet Configuration | ||
242 | -------------------------- | ||
243 | ### Examples | ||
244 | |||
245 | ```yaml | ||
246 | [transport] | ||
247 | OPTIONS = -L DEBUG | ||
248 | PLUGINS = tcp | ||
249 | #PLUGINS = udp | ||
250 | |||
251 | [transport-tcp] | ||
252 | OPTIONS = -L DEBUG | ||
253 | BINDTO = 192.168.0.2 | ||
254 | ``` | ||
255 | |||
256 | TODO: *explain what this does and add more* | ||
257 | |||
258 | |||
259 | Philosophy | ||
260 | ------------------------- | ||
261 | |||
262 | GNUnet is made for an open society: It's a self-organizing network and it's [http://www.gnu.org/philosophy/free-sw.html](free software) 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. | ||
263 | |||
264 | |||
265 | Related Projects | ||
266 | ------------------------- | ||
267 | |||
268 | <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> | ||