How to use GNUnet - in a nutshell

Make sure your GNUnet installation works...

After installing and starting GNUnet you should make sure that your peer is connecting to the P2P-network. By typing gnunet-core you should see something like this:

$ gnunet-core
Tue Oct 30 19:58:48 2018: connection established DSTJ (timeout in 293 s)
Tue Oct 30 19:58:48 2018: connection established A4MK (timeout in 292 s)
Tue Oct 30 19:58:48 2018: connection established 7WRD (timeout in 299 s)
Tue Oct 30 19:58:48 2018: connection established 5WBG (timeout in 299 s)


Overtime the list will change as new peers connect or drop out, this is normal.

... and play around with it.

So let's try out some of GNUnet's most common use-cases to illustrate it's power. Please be mindful that some should be done in a particular order, one after another:

• Filesharing
• A simple chat using CADET
• Another simple chat using a nim client
• Name resolution using GNS on the command line
• Name resolution using GNS with a browser (do it on the command line first)
• Serving a website using VPN (do name resolution with a browser first)

ファイル共有

Let's publish a file in the GNUnet filesharing network. We use the keywords ("commons" and "state") so other people will be able to search for the file.

We can choose any file and describe it with meaningful keywords (using the `-k` command line option), in this example these are "commons" and "state".

$ gnunet-publish -k commons -k state ostrom.pdf
Publishing `/home/myself/ostrom.pdf' done.
URI is `gnunet://fs/chk/M57S...

GNUnet users can find the file by using the gnunet-search command.

$ gnunet-search commons
#1:
gnunet-download -o "ostrom.pdf" gnunet://fs/chk/M57S...

gnunet-search returns the command line call to download the file (and store it as ostrom.pdf)!

It's recommended for filesharing that you increase GNUnet's bandwidth restrictions from the actually pretty low defaults. The example below sets the WAN and LAN limits to the value "unlimited".

Please note that it might take some time (up to some hours) till your peers can see your freshly uploaded files.

Further reading: Please also refer to the chapter on filesharing in the handbook.

CADET (and Chat)

The CADET subsystem is at the heart of the GNUnet project because it is responsible for secure end-to-end communications between peers (nodes) in the GNUnet overlay network.

Users can chat and send files to each other on the GNUnet network using a simple CADET tool. We use the `gnunet-cadet` command line tool to open a port on our local machine and from another peer on the network connect to this port. Users can then chat or transfer files.

In the following example, Alice will create a CADET session on her laptop. Bob will then connect to Alice from his desktop. Alice will first need her peer ID of the GNUnet and provide it to Bob.

alice@laptop $ gnunet-peerinfo -s
I am peer `P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG'.

Now Alice will open a port using the -o option, giving it a name, in this case Alice calls it 'my-secret-port' (it can be any string!):

alice@laptop $ gnunet-cadet -o my-secret-port

On Bob's machine he can connect to Alice using her peer ID and the port name. Once connected they can start chatting.

bob@desktop $ gnunet-cadet P4T5GHS1PCZ06R82D3KW8Z8J1113BQZWAWGYHTZ8G1ZXMWXQGAVG my-secret-port

It's worth noting that the other peers can be a friend's machine which has GNUnet running, or it can also just be another shell on your own machine.

If you are interested in the details of CADET, please read the "Cadet-Subsystem" chapter in the GNUnet handbook.

Chatting with a convenient client

To make chatting a tiny bit easier and prettier, we need to install additional software.

You can select one of the options listed here under applications using the Messenger service. Those are generally compatible with each other using the same underlying library but tell apart in their user interface and design.

In other words: You can choose by your own preference how to chat.

After you have picked an application (for example Messenger-GTK or messenger-cli), follow the instructions for build and installation. Notice that depending on the picked application, you might need additional dependencies besides the library for the chatting functionality.

Once you installed the application and started it, a dialog should open to ask you for an account to use or whether you want to create a new one. An account is pretty much an identity which can also be used for GNS capabilities. Accounts don't require any information besides a chosen identifier or nick.

Next step is to enter a chat room via your application. The easiest step is choosing a public chat room which is similar to communicate via CADET through a shared port. Look for a function to add a new room or "platform". You should be able to enter any sort of text as key for the room and confirm.

A chat room should open using the entered key as identifier and any other person you share the key with should be able to join this room as well using one of the compatible applications as linked above. From here you can simply write text in a proper field and send it as a message to communicate.

In case of any more advanced functionality it is recommended to look for a guide or more detailed information on the source of the used application since implementations can vary, especially the design of user interface.

Also you can always use the simplified command line tool `gnunet-messenger` provided by GNUnet itself to open or join a chat with its key in a similar way as described above. See the more detailed information in the handbook to use it.

Name resolution using GNS on the command line

The GNU Name Service (GNS) is a fully decentralized alternative to the Domain Name System (DNS). Where GNS does not suffer the same major security flaws as DNS.

In this example, Alice will save the IP address (195.54.164.39) of the Chaos Computer Club e.V. (CCC) homepage into a GNUnet namestore record and then try to resolve it using GNUnet GNS.

First Alice needs to create a GNUnet identity which is the equivalent to a zone in a DNS. We'll call it "myself" and create it using the `gnunet-identity` command line tool. Instead of "myself" you can use your nickname, or any other name.

alice@laptop $ gnunet-identity -C myself

Alice can check to see if it worked using the same tool. The name of her identity and the corresponding public key are displayed.

alice@laptop $ gnunet-identity -d
myself - HWTYD3P5D77JVFNVMZ1M5T10V4SZYNMY3PCGQCSVENKD6ZCRKPMG

Now Alice adds a public `A` record to the zone. We'll call it "ccc" with the value "195.54.164.39" and it expires after one day.

alice@laptop $ gnunet-namestore -z myself -a -e "1 d" -p -t A -n ccc -V 195.54.164.39

Now the GNS can be queried using the command line tool `gnunet-gns`.

alice@laptop $ gnunet-gns -t A -u ccc.myself
ccc.myself:
Got `A' record: 195.54.164.39

So it worked! But only resolving our own records is boring. So we can give our identity (the public key of it to be precise) to someone else so they can try to resolve our records, too. The other person (Bob) has to add it to his namestore like this:

bob@desktop $ gnunet-namestore -z myself -a -e never -p -t PKEY -n alice -V HWTYD3P5D77JVFNVMZ1M5T10V4SZYNMY3PCGQCSVENKD6ZCRKPMG

Alices identity in Bobs namestore is a public record (-p) and never expires (-e never). Now Bob (let's assume he has called his identity myself, too) should be able to resolve Alice's "ccc" record, too!

$ gnunet-gns -t A -u ccc.alice.myself
ccc.alice.myself:
Got `A' record: 195.54.164.39

It can continue like this. A friend of Bob would be able to resolve Alice's records too because Bob published her identity in a public record. Bobs friend would simply use "ccc.alice.bob.myself" to resolve Alice's "ccc" record.

See the chapter "Using the GNU Name System" in our handbook for a more detailed documentation.

Name resolution using GNS with a browser

In the previous use-case "Name resolution using GNS on the command line" we saw how we could retrieve a value (e.g. an IP address) associated with a given named record (e.g. a web address). Now we'll see how GNS can be used with a browser, making it actually useful. Currently Firefox and Chromium are known to work with GNS.

Many websites enforce HTTPS by providing TLS certificates for their hostnames, with the aim of encrypting the web page content between the clients browser and the hostname server, and authenticating the server and client to each other. This is so that a 3rd party cannot see what is being communicated between the client (browser) and server (website host). This is important, for example, if you are using online banking where you don't want anyone seeing your customer ID and password.

Unfortunately, if a browser resolves a hostname through the GNS, the TLS certificates will have the original hostname and the browser will present an error message. In the previous example, we resolved "ccc.myself" to 195.54.164.39 but the hostname's TLS certificate refers to the actual hostname as "https://www.ccc.de/" So GNUnet has to trick the browser by generating it's own certificates for the hostnames GNS resolves. This means we need to create our own certificate authority and tell our browser to use this instead. Luckily there's a script to fix this problem:

$ gnunet-gns-proxy-setup-ca

After executing this script the Browser has to be restarted.

GNUnet provides a proxy service (gnunet-gns-proxy) that the browser can send DNS and HTTP traffic to. It will try to resolve names with GNS first and forward the rest of the DNS traffic to the system's DNS resolver. It will also take care of the HTTP traffic, so the browser gets valid certificates and the web server will not be confused by the hostnames resolved by GNS instead of the DNS. The GNS namestore does not know about any DNS hostnames yet, so we have to store them, too. For our "ccc" A record, we have to store a LEHO (LEgacy HOstname) record, too. It must contain the website's original DNS hostname:

$ gnunet-namestore -z myself -a -e "1 d" -p -t LEHO -n ccc -V www.ccc.de

Now lets start gnunet-gns-proxy.

$ /usr/lib/gnunet/libexec/gnunet-gns-proxy

Our browser has to be configured so it uses our proxy. In Firefox we have to set these options under "about:config":

network.proxy.socks: localhost
network.proxy.socks_port: 7777
network.proxy.socks_remote_dns true
network.proxy.type: 1

To tell Chromium to use the proxy, it has to be started with the "--proxy-server" command line option:

$ chromium --proxy-server="socks5://127.0.0.1:7777"

Now we should be able to resolve our GNS names in the browser! We just have to type "https://ccc.myself" into the address bar. If our friend Bob prepared his system, too, he can resolve our record by typing "ccc.alice.myself".

See the chapter on Integration with Browsers in our handbook for a more detailed description.

VPN

VPN can be used to share your Internet connection (yes, this may be dangerous, just as running a Tor exit node) or to provide access to services on your host (this should be less dangerous, as long as those services are secure).

In this tutorial we concentrate on providing access to services on your host.

For documentation to share your Internet connection have a look into chapter "Configuring the GNUnet VPN" in the handbook.

First you have to edit your gnunet.conf and add this section.

[exit]
START_ON_DEMAND = YES

This is necessary to start the exit daemon.

Furthermore you need to add a section for your service.

[http.gnunet.]
TCP_REDIRECTS = 80:169.254.86.1:80

Here a service named 'http' is configured to be accessed on a remote and local host on port 80. The IP address is the default IP address for the exit interface. If you like to change to another private IP address range you can change the option in section 'exit':

IPV4ADDR = 169.254.86.1

Now we have to add a GNS record to the namestore.

gnunet-namestore -z myself -a -e "1 d" -p -t VPN -n www -V "1 PKEY http"

Where myself is the name of the zone we already used above, but now we are adding a record of type VPN, and the value is a string containing three values. A boolean indicating the use of TCP or UDP (TCP in the example above), the public key of your node and the identifier of the service we used above ([http.gnunet.].

After we added this record we should be able to access www.myself like we did ccc.myself via the browser above.

The UI version of this Tutorial can be find in Chapter Using the GNUnet VPN in the handbook.

Trouble Shooting

You can't reach other people's nodes

Should our computer not have reached the open GNUnet network automatically, we can manually instruct our node how to reach the nodes of our friends. This works by exchanging HELLO strings. This is how we get a hello string for our computer.

We can now pass this string to our friends "out of band" (using whatever existing chat or messaging technology). If the string contains some private IP networks we don't want to share, we can carefully edit them out.

Once we receive such strings from our friends, we can add them like this:

Now our GNUnet nodes can attempt reaching each other directly. This may still fail due to NAT traversal issues.