Garlicat-HOWTO

This is a new version of the Garlicat-HOWTO which I wrote about 10 years ago in November 2009. Actually, this original HOWTO still applies but, anyway, I rewrote it to match the software versions of today, August 2019. This document is based on the I2P router version 0.9.41 and Onioncat 0.2.7, both running on a recent Debian Linux 9.9 system.

This HOWTO explains how to connect two systems named onioncat-A and onioncat-B together using Garlicat and I2P. Of course, the setup is not limited to two hosts, you can connect as many as you like.

Update note 2021/03/14: The gcat symlink was removed from the installation procedure because of a name conflict with another binary. To run OnionCat in GarliCat mode add option -I to ocat: ocat -I

What is Garlicat?

Garlicat is Onioncat with a few configuration changes, i.e. Garlicat uses different port numbers and IPv6 addresses than Onioncat but everything else is the same. This difference is made to be able to run Tor and Onioncat, and I2P and Garlicat in parallel on the same host. Hence, everything that applies to Onioncat also applies to Garlicat. The terms can really be used interchangeably.

What is Onioncat?

Onioncat is a VPN adapter which is designed to connect through Tor/I2P to other Onioncats. Thus you can build a VPN between systems based on anonymization networks. No surveillor will be able to monitor your traffic dependent on the strength of your Tor/I2P node and its network.

Preqrequisites

Both systems have to have a working I2P installation, an installed Onioncat 0.2.7, and of course a working Internet connection. Open your I2P router console (usually at http://localhost:7657/) and check the version in left upper corner of the screen.
Then check Onioncat, run ocat -h on the command line. It will output the current version. You can install Onioncat either with your package manager or you can compile and install the latest version of Onioncat from here: https://www.cypherpunk.at/ocat/download/Source/current/ (unpack it, run ./configure, make, and sudo make install, as usual).

Make sure that your system has the ifconfig command installed. Simply run ifconfig as root and see what happens. If it says “ifconfig: command not found” then most probably it is not installed. Modern Linux distributions switched to a different set of network commands (ip) instead, but ifconfig can still be installed. On Debian-based systems ifconfig is found within the net-tools package (install with apt-get install net-tools).

Configure I2P

Onioncat is a client and a server at the same time, meaning that you can connect (as a client) to other Onioncats but you can also accept (like a server) incoming connections from other Onioncats. Hence you have to configure a client and a server tunnel in the I2P router console.

Create Server Tunnel

Open the I2P router console of host onioncat-A at http://localhost:7657/. Scroll down to the bottom of the left sidebar and click on “LOCAL TUNNELS” (http://localhost:7657/i2ptunnelmgr) which will bring up the I2P tunnel manager. Within the box “I2P HIDDEN SERVICES” on the right lower corner select “Standard” and click “Create”. This will bring up the new screen “NEW SERVER SETTINGS”.

Now fill in a name (e.g. “gcat-server”), a description, choose to start it automatically and most importantly set port number 8061.

Scroll down to the bottom of the page and click “Save”. This will bring you back to the tunnel manager and your new Garlicat tunnel shall be listed in the “I2P HIDDEN SERVICES” box. Note the Base32-encoded string shown behind “Destination”. Copy this string to a text file and make a remark for host onioncat-A. We will need this in a later step.

Create Client Tunnel

Now scroll down to the bottom of the “I2P CLIENT TUNNELS” box. Select “Socks 4/4a/5” and click “Create”. Enter a name (e.g. “gcat-client”), a description, choose to start automatically and most importantly enter port number 9051. Finally scroll down and click save.

The I2P router will now try to bring up these tunnels and after a while they should show up in the left side bar under “LOCAL TUNNELS” with a green star.

Now create a server and a client tunnel on the second host onioncat-B in exactly the same way. Don’t forget to note the Base32-encoded destination string. This string is the unique address of your server tunnel within the I2P network. Onioncat will use this address to connect as a client to the server side.

Compile Hosts File

Garlicat needs to translate IPv6 addresses to I2P destinations (.b32.i2p) to be able to connect properly. This translation is done with a simple text file, known as “the hosts file”.

On the command line of host onioncat-A run Garlicat with option -i and the I2P destination address of its own server tunnel (the destination address of the gcat-server tunnel of I2P on onioncat-A):

ocat -I -i qp3q7cytpx47py64sglsqxtrelq6mwexv2qaigxve3f3qy5milla.b32.i2p

Garlicat will output an IPv6 address, in this case fd60:db4d:ddb5:41af:526c:bb86:3ac4:2d60. Copy this IPv6 address followed by the destination address to your text file. Do the same with the second destination and copy it into the same text file. You can add comments starting with # into the file for better readability. Do the same with the onioncat-B address. Finally, you should end up with a file which looks similar to this (Please note that the IP adress and the destination address are on a single line and not on two separate lines (…web page formatting issue…)!):

# onioncat-A
fd60:db4d:ddb5:41af:526c:bb86:3ac4:2d60 qp3q7cytpx47py64sglsqxtrelq6mwexv2qaigxve3f3qy5milla.b32.i2p
# onioncat-B
fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50 xy2aq6iod6sh6nivnttnb35qxg2ohdljofqba34dhjid3ktk4hsq.b32.i2p

Now copy this file to all of your hosts (which is onioncat-A and onioncat-B in this example) to a specific location, e.g. into your I2P installation directory to /home/<your_username>/i2p/hosts.gc.

Run Garlicat

Now we are ready to run Garlicat. On each host run it with its own destination address as an argument, e.g. on host onioncat-A we start Garlicat as root (e.g. with sudo) with the following command (in one line):

ocat -I -B -U -g $HOME/i2p/hosts.gc qp3q7cytpx47py64sglsqxtrelq6mwexv2qaigxve3f3qy5milla.b32.i2p

Option -B keeps Garlicat running in the foreground which may be convient for the installation and testing procedure. If -B is omitted, Garlicat will fork to the background and the log messages are written to the syslog.

Side note: Option -g $HOME/i2p/hosts.gc sets the path for the hosts file to be used. If this option is omitted, Onioncat will do the lookup in the system hosts file (/etc/hosts). Option -U disables the unidirectional mode. Although this is not necessary in this setup, with this option the time of connection setup is reduced.

Test the Setup

To test the setup open a new shell on one of your systems. You should be able to ping the other host with the ping6 command:

$ ping6 fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50
 PING fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50(fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50) 56 data bytes
 64 bytes from fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50: icmp_seq=2 ttl=64 time=7304 ms
 64 bytes from fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50: icmp_seq=3 ttl=64 time=6280 ms
 64 bytes from fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50: icmp_seq=4 ttl=64 time=5256 ms
 64 bytes from fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50: icmp_seq=5 ttl=64 time=7314 ms
 64 bytes from fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50: icmp_seq=6 ttl=64 time=6291 ms
 64 bytes from fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50: icmp_seq=7 ttl=64 time=5267 ms

The tunnel setup may take a while (serveral seconds) thus the first few pings may be lost. If this works you can now work with these hosts as with any other VPN, e.g. ssh to it:

eagle@onioncat-A:~$ ssh fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50
 The authenticity of host 'fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50 (fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50)' can't be established.
 ECDSA key fingerprint is SHA256:544ApVFmA1+J2zMNp58zD9aDS2PE8M0s6ly7fo+drqA.
 Are you sure you want to continue connecting (yes/no)? yes
 Warning: Permanently added 'fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50' (ECDSA) to the list of known hosts.
 eagle@fd60:db4d:ddb5:6f8:33a5:3da:a6ae:1e50's password: 
 Linux onioncat-B 4.9.0-9-amd64 #1 SMP Debian 4.9.168-1+deb9u5 (2019-08-11) x86_64
 The programs included with the Debian GNU/Linux system are free software;
 the exact distribution terms for each program are described in the
 individual files in /usr/share/doc/*/copyright.
 Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
 permitted by applicable law.
 You have new mail.
 Last login: Tue Aug 20 09:28:37 2019 from 192.168.122.1
 eagle@onioncat-B:~$