Onioncat and Tor Hidden Services V3

For security reasons the Tor project introduced hidden services version 3 (HSv3) which facilitate stronger cryptography to comply with modern needs for security. Onioncat was developed with version 2 of hidden services which are still in place work as expected. Unfortunately HSv3 do not integrate smoothly into the OnionCat concept but nevertheless, with a few additional steps Onioncat still will run perfect with these new HSv3 services.

This HowTo explains how to setup three systems to connect to each other using HSv3. It does not explain technical details, why everything is done in such a way, it simply shall be a step by step procedure to success.

In the following explanation there are three hosts, named onioncat-A, onioncat-B, and onioncat-C which may be any system anywhere in the Internet. This Howto was based on a clean Debian Linux installations but it shall work straight forward on any other system.


Make sure the systems are properly connected to the Internet.

Tor’s hidden services where implemented into Tor starting with version 0.3.2. Make sure you have at least this version of Tor installed (run tor --version). If you have an older version on your system but you still want to use HSv3 you have to upgrade your Tor installation. Either use your package manager or download, compile, and install the latest version of Tor from https://dist.torproject.org/ .

Although the necessary feature was implemented into Onioncat many years ago, a tiny bug which came up recently prevented it from working correctly. You need to have Onioncat version 0.2.4 or higher on your system for HSv3 to work properly. Make sure you have at least 0.2.4 installed (run ocat -h to see installed version). Use your package manager to upgrade or download, compile, and install the latest version of Onioncat from https://www.cypherpunk.at/ocat/download/Source/current/ .

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 Tor

All of yoour Tor client (which are intended to be used with Onioncat) needs to have a hidden service configured.
Edit the Tor configuration file which typically is found at either /etc/torrc or /usr/local/etc/torrc and add the following three lines to each of the three systems (onioncat-a, onioncat-b, and onioncat-c)

HiddenServiceDir /var/lib/tor/onioncat_hsv3
HiddenServiceVersion 3
HiddenServicePort 8060

Now run or restart Tor.

Note: Make sure that Tor connects properly to the Tor network. It typically outputs the following text into its logfile if everything is fine: “Bootstrapped 100% (done): Done“.

Compile Onioncat Hosts File

Now we need to create a hosts file. This is a list of your onion hostnames and the according Onioncat ipv6 addresses. It is a single file which can be shared (meaning copied to) between these three hosts. Because of we setup three hosts, the hosts file contains three lines.

On host “onioncat-a” change into the designated hidden service directory of Tor which is /var/lib/tor/onioncat_hsv3 (e.g. cd /var/lib/tor/onioncat_hsv3). We need root permission to do so. Within the directory we find a file named “hostname”. Display the contents of the file (e.g. cat hostname). It contains a string like this: qr4sshhsbcqfyircxqmi77j5pmgcki4keh5f6kybschqjb7xmas3siqd.onion. This is the unique onion name of the hidden service on host onioncat-a. To find the associated IPv6 address run Onioncat with option -i and this hostname as argument: ocat -i qr4sshhsbcqfyircxqmi77j5pmgcki4keh5f6kybschqjb7xmas3siqd.onion. It will output an IPv6 address which in this case is fd87:d87e:eb43:908f:487:f760:25b9:2203.
Create a new empty text file and add a line containing the IPv6 address followed by the hostname. You can add additional hostnames for your personal convenience if you like and you can add descriptive comments starting with a #.
Lookup the hostname and IPv6 address on each of the three systems and add the names and IP addresses to the same text file (the hosts files). Finally you should end up with a file like this (please note that there is no linebreak after the IP address, i.e. there’s just a single line after each comment):

# onioncat-a
fd87:d87e:eb43:908f:487:f760:25b9:2203 qr4sshhsbcqfyircxqmi77j5pmgcki4keh5f6kybschqjb7xmas3siqd.onion onioncat-a
# onioncat-b
fd87:d87e:eb43:6862:da73:63ad:fa91:f203 jbhu6id5htvwx3kahz6o2ms32bms75fbxjhyy2uonbrnu43dvx5jd4qd.onion onioncat-b
# onioncat-c
fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03 o3cjd437sxzfzobqn7g2ppy3b4j

Copy this file to each of the three hosts, e.g. into the Tor configuration directory at /etc/tor/hosts.oc (or /usr/local/etc/tor/hosts.oc).

Run Onioncat

Now we are ready to run Onioncat. On each host run Onioncat with its own onion hostname as an argument, e.g. on host onioncat-a we start Onioncat as root with the following command (in one line):

ocat -H -g /etc/tor/hosts.oc -U -B qr4sshhsbcqfyircxqmi77j5pmgcki4keh5f6kybschqjb7xmas3siqd.onion

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

Side note: Option -H enables hostname lookup which is required for the HSv3 lookup in a hosts file. Option -g /etc/tor/hosts.oc 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 each of the three hosts with the ping6 command:

$ ping6 fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03
 PING fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03(fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03) 56 data bytes
 64 bytes from fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03: icmp_seq=2 ttl=64 time=315 ms
 64 bytes from fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03: icmp_seq=3 ttl=64 time=350 ms
 64 bytes from fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03: icmp_seq=4 ttl=64 time=313 ms
 --- fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03 ping statistics ---
 5 packets transmitted, 3 received, 40% packet loss, time 4035ms
 rtt min/avg/max/mdev = 313.864/326.645/350.502/16.890 ms

$ ping6 fd87:d87e:eb43:6862:da73:63ad:fa91:f203
 PING fd87:d87e:eb43:6862:da73:63ad:fa91:f203(fd87:d87e:eb43:6862:da73:63ad:fa91:f203) 56 data bytes
 64 bytes from fd87:d87e:eb43:6862:da73:63ad:fa91:f203: icmp_seq=3 ttl=64 time=570 ms
 64 bytes from fd87:d87e:eb43:6862:da73:63ad:fa91:f203: icmp_seq=4 ttl=64 time=593 ms
 64 bytes from fd87:d87e:eb43:6862:da73:63ad:fa91:f203: icmp_seq=5 ttl=64 time=618 ms
 64 bytes from fd87:d87e:eb43:6862:da73:63ad:fa91:f203: icmp_seq=6 ttl=64 time=539 ms
 --- fd87:d87e:eb43:6862:da73:63ad:fa91:f203 ping statistics ---
7 packets transmitted, 4 received, 42% packet loss, time 6041ms
 rtt min/avg/max/mdev = 539.112/580.280/618.032/29.220 ms

Please note that the first few pings may be lost because of the time Tor needs to create the circuit through the Tor network. Once the connection is open there should be no dataloss. The connections are close be Onioncat after two minutes of inactivity.


2 pings

Skip to comment form

    • A on August 26, 2019 at 8:20 pm
    • Reply

    P2P Filesharing Networks such as Bittorrent, Bitcoin, IPFS, storage, VoIP, and many other P2P protocols can be and are running over OnionCat with v2 onions. You do not need to use v3 onions if you do not need the features v3 provides. Most P2P applications and use cases do not actually need v3, ie: the reliability, security, performance, anonymity, location and attack resistance is sufficient for most use cases under v2.

    Fixed config mapping is a showstopper for v3, so a solution for OnionCat does need to be developed soon.

    1. Yes, definitely. As long as Tor offers v2 hidden services they can be used.
      Nevertheless, his article shows how to use it in the current stage of develpmont. I agree, that the major feature of Onioncat gets lost with v3. We would need some kind of lookup mechanism within Tor.

      1. Hallo bernhard hab ne frage an dich ich brauche einen eu Ausweiss am besten niederlande

    2. Tor devs are planning to deprecate v2 onions in a year or two so the problems with v3 can’t be ignored unfortunately as it will be the only way to connect at some point.

  1. Hi Bernhard. Nice to see Onioncat actively maintained. Can you please explain the security properties and implications of using it with v3 onions?

    We will re-recommend use in our Whonix documentation if it provides the same guarantees. Thanks.

    1. It’s a good question, I’ll write an article on security considerations of Onioncat.

    • Anonymous on November 15, 2019 at 6:24 am
    • Reply

    Thank you for OnionCat, I needed something to do UDP over Tor HS’s and this did it! Hopefully something for v3 can be figured out. Thx.

    • Elele on April 10, 2020 at 2:18 pm
    • Reply

    please fix the released version (segfault) – it’s fixed in git, but the git version is incomplete and doesn’t build, so I had to adopt the fix from there to the release version to have V3 HS onioncat running. but with the fix it works like a charme. good work.

    1. Sorry for late response. Here’s the latest package, just uploaded:

    • Gerry on July 15, 2020 at 2:10 am
    • Reply

    Tor Project “developers” are trying to remove v2 onions from tor without considering that onioncat REQUIRES v2 to support things like Bittorrent, some voice/video, and other P2P apps within onionland.

    Attn users: help raise support for v2 now!!!

  1. […] the speed of the connection setup and it may be easier in combination with v3 hidden services (Read Onioncat and Tor hidden services v3 for more […]

  2. […] current solution uses a local text file for translation (see Onioncat and HSv3). But again, it does not work out-of-the-box, you have to setup the hosts file on all Onioncats […]

Leave a Reply

Your email address will not be published.