aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md271
1 files changed, 0 insertions, 271 deletions
diff --git a/README.md b/README.md
deleted file mode 100644
index a68ef3700..000000000
--- a/README.md
+++ /dev/null
@@ -1,271 +0,0 @@
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
13How to Install GNUnet
14---------------------
15
16### 1. From Source
17
18**Dependencies**
19
20Install 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
44You 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
47guix 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.
56make
57make 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:
64guix package -f guix-env.scm
65
66# To skip the testing phase:
67guix package -f guix-env.scm:notest
68```
69
70
71### 2. Docker
72
73```
74# From within the top-level of this repository run:
75docker build -t gnunet -f ./contrib/docker/Dockerfile .
76```
77
78For more info on using the docker container see [here](contrib/docker/README.md).
79
80
81
82Using GNUnet
83-------------
84
85There 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
96Before we can begin using most of the components we must start them.
97
98```shell
99gnunet-arm --start
100```
101
102Now we can open up another shell and try using some of the modules.
103
104### Cadet
105
106#### Examples
107
108Open a Cadet connection:
109
110```shell
111# Node 1
112gnunet-cadet -o <shared secret>
113```
114
115Conect to peer:
116
117```shell
118# Node 2
119gnunet-cadet <peer-id of Node 1> <shared secret>
120```
121
122#### Sharing Files
123
124With the cli tool, you can also share files:
125
126```shell
127# Node 1
128gnunet-cadet -o <shared secret> > filename
129```
130
131On 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).
132The 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
136coproc gnunet-cadet <peer-id of Node 1> <shared secret>
137cat <file> >&"${COPROC[1]}"
138```
139
140Now this enables us to do some fun things, such as streaming video by piping to a media player:
141
142```shell
143# Node 1
144gnunet-cadet -o <shared secret> | vlc -
145```
146
147```shell
148# Node 2
149coproc gnunet-cadet <peer-id of Node 1> <shared secret>
150cat <video-file> >&"${COPROC[1]}"
151```
152
153### Filesharing
154
155You can use GNUnet as a content-addressed storage, much like IPFS: sharing immutable files in a decentralized fashion with added privacy.
156
157For instance, you can get a nice cat picture with
158```sh
159gnunet-download gnunet://fs/loc/CB0ZX5EM1ZNNRT7AX93RVHCN1H49242DWZ4AXBTCJBAG22Z33VHYMR61J71YJXTXHEC22TNE0PRWA6D5X7NFNY2J9BNMG0SFN5DKZ0G.R48JSE2T4Y3W2AMDHZYX2MMDJC4HR0BVTJYNWJT2DGK7EQXR35DT84H9ZRAK3QTCTHDBAE1S6W16P8PCKC4HGEEKNW2T42HXF9RS1J0.1906755.J5Z3BDEG2PW332001GGZ2SSKCCSV8WDM696HNARG49X9TMABC4DG.B6Y7BCJ6B5K40EXCXASX1HQAD8MBJ9WTFWPCE3F15Q3Q4Y2PB8BKVGCS5HA4FG4484858NB74PBEE5V1638MGG7NS40A82K7QKK3G0G.1577833200 --output cat.png
160```
161
162You 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
168Publishing `/tmp/ILoveGNUnet.txt` done.
169URI is `gnunet://fs/chk/SXA4RGZWDHE4PDWD2F4XG778J4SZY3E3SNDZ9AWFRZYYBV52W1T2WQNZCF1NYAT842800SSBQ8F247TG6MX7H4S1RWZZSC8ZXGQ4YPR.AZ3B5WR1XCWCWR6W30S2365KFY7A3R5AMF5SRN3Z11R72SMVQDX3F6GXQSZMWZGM5BSYVDQEJ93CR024QAAE65CKHM52GH8MZK1BM90.14`.
170```
171
172The 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
183You 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
185This 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
189First, set up access from GNUnet to IP with `exit`:
190
191`gnunet.conf`:
192```
193[exit]
194FORCESTART = YES
195EXIT_IPV4 = YES
196EXIT_RANGE_IPV4_POLICY = 169.254.86.1;
197```
198
199Exit, 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
201Then, start up a server to be shared. For the sake of example,
202
203```sh
204python3 -m http.server 8080
205```
206
207Now to configure the actual "half-hidden service". The config syntax is as follows:
208
209```sh
210[<shared secret>.gnunet.]
211TCP_REDIRECTS = <exposed port>:<local IP>:<local port>
212```
213
214...which for our example would be
215
216```sh
217[myhttptest.gnunet.]
218TCP_REDIRECTS = 80:169.254.86.1:8080
219```
220
221Local 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
223You 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
23110.11.139.20
232
233# And just connect to the given IP
234$ wget 10.11.139.20
235Connecting 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
244GNUnet Configuration
245--------------------------
246### Examples
247
248```yaml
249[transport]
250OPTIONS = -L DEBUG
251PLUGINS = tcp
252#PLUGINS = udp
253
254[transport-tcp]
255OPTIONS = -L DEBUG
256BINDTO = 192.168.0.2
257```
258
259TODO: *explain what this does and add more*
260
261
262Philosophy
263-------------------------
264
265GNUnet 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
268Related 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>
generated by cgit v1.2.3 (git 2.39.1) at 2024-04-18 05:48:20 +0000