OCAT(1)

📦 version 4.11.0, in opensuse-leap 16.0

🧅 OCAT(1) — the ocat manual, aka OnionCat User's Manual ✨

okay so bestie, welcome to ocat, the OnionCat manual page. this is the user's manual, it's giving "transparent IPv6 layer" realness and honestly? iconic. let's get into it 💅

🌸 NAME 🌸

ocat — OnionCat creates a transparent IPv6 layer on top of Tor's or I2P's hidden services. that's it, that's the whole vibe 🫶

⭐ SYNOPSIS ⭐

ocat -i onion_id                      (1st form)
ocat -o IPv6_address                  (2nd form)
ocat [OPTION] onion_id                (3rd form)
ocat -R [OPTION]                      (4th form)
ocat -I [OPTION] i2p_id               (5th form)

five forms, five vibes, pick your fighter ✨

🦋 DESCRIPTION 🦋

OnionCat creates a transparent IPv6 layer on top of Tor's hidden services or I2P's tunnels, no cap. it transmits any kind of IP-based data transparently through the Tor/I2P network on a location hidden basis. like… think of it as a peer-to-peer VPN between hidden services 💖

OnionCat is a stand-alone application which runs in userland and is a connector between Tor/I2P and the local OS. any protocol which is based on IP can be transmitted — and yes, UDP and TCP (and probably ICMP) are the most important ones, but literally all the other protocols can also be forwarded through it. main character energy 🔥

OnionCat opens a TUN device and assigns an IPv6 address to it. all packets forwarded to the TUN device by the kernel get forwarded by OnionCat to other OnionCats listening on Tor's hidden service ports or I2P's server tunnels, periodt. the IPv6 address depends on the onion_id or the i2p_id, respectively. the onion_id is the hostname of the locally configured hidden service (see tor(8)). depending on the configuration of Tor, the onion_id usually can be found at /var/lib/tor/hidden_service/hostname or similar location. the i2p_id is the 80 bit long Base32 encoded hostname of the I2P server tunnel 👑

OnionCat has two implemented loopback responders for easier network debugging, and honestly? so helpful of it. ping responses from loopback address fd87:d87e:eb43::dead:beef indicate correct network setup between the kernel and OnionCat. ping responses from fd87:d87e:eb43::feed:beef indicate that the connection between OnionCat and Tor itself works, hidden service correctly configured and enabled 🧚

✨ OPTIONS ✨

in the following is a description of all options. typically you won't need any of them except specifying your OnionCat's .onion hostname. depending on your setup you may use options -g and -A. (yes, they're all here, i'm not skipping a single one, that would be rude 🙈)

  • -2 — this option is here only for simplicity. with this option OnionCat behaves like OnionCat3 (version < 0.4.0). actually it's a short form for using the options -D -H -S. cute little shortcut, lowkey love that 💜
  • -4 — enable IPv4 forwarding. see http://www.cypherpunk.at/onioncat_trac/wiki/IPv4 — an IPv4-througth-IPv6 tunnel through OnionCat is recommended instead of using native IPv4 forwarding. (that spelling is theirs, not mine, i'm just the messenger 😭)
  • -5 'socks5'|'direct' — this option has a mandatory argument which is literally either socks5 or direct. by default OnionCat uses SOCKS4A (version 4a) to connect to the anonymization network proxy (e.g. Tor). with this option set to socks5, OnionCat uses SOCKS5 (version 5 as specified in RFC1928), currently with no authentication mechanism. as of today it actually makes no difference but it might be desireable in future 👀 if direct is used, OnionCat does not connect through the SOCKS server but instead it connects directly to the remote peers using the hosts lookup mechanism (see option -H). this feature is experimental and turns OnionCat into a distributed virtual switch based on regular Internet transport instead of Tor. it's a useful feature for a lab setup 🧪 this option also disables the remote hostname validation (option -J).
please note that OnionCat does not implement any encryption technique! it is a plain tunneling through TCP sessions. like, zero encryption, bestie. don't forget that 💀
  • -a — OnionCat creates a log file at $HOME/.ocat/connect_log. all incoming connects are logged to that file. $HOME is determined from the user under which OnionCat runs (see option -u). receipts for every connection, we love to see it 🎀
  • -A [ipv6/]hostname — this option lets you add an IP address hostname pair to the internal hosts db. typically it is enough to specify just the .onion hostname because the IPv6 address is derived from the hostname. adding an IP address is either redundant or may be used in special scenarios where the IPv6 address differes from its original address. the latter will only work in a closed environment and is not interoperable with other OnionCats in the wild because by default the names and IPs are verified to be correct. this option may be specified multple times. alternatively you could put the IP/hostname pairs into the OnionCat hosts file (see option -g) 💫
  • -b — run OnionCat in background. this is default. OnionCat will detach from a running shell and close standard IO if no log file is given with option -L 🐚
  • -B — run OnionCat in foreground. OnionCat will log to stderr by default 👀
  • -C — disable the local controller interface. the controller interface listens on localhost (127.0.0.1 and ::1 port 8066) for incoming connections. it's currently used for debugging purpose and is not thread-safe and does not have any kind of authentication or authorization mechanism. hence, it should not be used in production environments. like seriously, keep this one in the lab 🚨
  • -d n — set debug level to n. default = 7 which is maximum. debug output will only be created if OnionCat was compiled with option DEBUG (i.e. configure was run with option --enable-debug) 🔍
  • -D — disable OnionCat's DNS lookup. if OnionCat has to make an outgoing connection but no suitable entry is found in the internal hosts db, OnionCat will do a DNS query at the hosts found in the internal hosts db. this option deactivates this feature. hostname lookups are enabled by default since OnionCat4 🌈
  • -e ifup — execute script ifup to bring up the tunnel interface. OnionCat will create a new tunnel interface and execute ifup immediatly after opening the network interface. this is intended as a universial interface for configuring the tunnel device and do additinal tasks when starting OnionCat. the script is executed with the same privilege as OnionCat is started, i.e. before dropping privileges. this typically is root. the script is run only once at startup 🛠️

see below in section EXAMPLES for a typical Linux ifup shell script.

OnionCat executes the file ifup with a call to execlp(3) and will pass the following environment variables:

  • OCAT_IFNAME — this variable contains the name of the network interface, e.g. "tun0".
  • OCAT_ADDRESS — this variable contains the IPv6 address which is associated with this instance of OnionCat and its hidden service address.
  • OCAT_PREFIXLEN — this variable contains the prefix length of the IPv6 prefix which typically is 48.
  • OCAT_PREFIX — this variable contains the IPv6 prefix, i.e. the network. this typically is fd87:d87e:eb43:: in OnionCat (Tor) mode and fd60:db4d:ddb5:: in GarliCat (I2P) mode.
  • OCAT_ONION_URL — this variable contains the short onion URL without domain appendix. it is a 16 character long string.
  • OCAT_ONION3_URL — this variable contains the long onion URL if available which is always true for I2P and in case of Tor it is used together with the HSv3 variant.
  • OCAT_DOMAIN — this variable contains the TLD appendix which is .onion for Tor and .b32.i2p for I2P.
  • -E s — this option sets the expiry time in secondes for remote entries in the internal hosts db. if the TTL of an entry expires, OnionCat will try to renew the entry by connecting to the remote OnionCat to retrieve a new keepalive. if it is unreachable it will retry after some time again. if it was unreachable for more than s seconds, the entry will be removed from the internal hosts db. the default expiry time is 604800 seconds which is 7 days ⏳
  • -f config file — read initial configuration from config file 📄
  • -g hosts_path — set the path to the hosts file. this option automatically enables option -H (see there). if -g is not set, the path defaults to SYSCONFDIR/tor/onioncat.hosts where SYSCONFDIR typically is /etc or /usr/local/etc. on exit, OnionCat saves all collected hosts entries to DATADIR/onioncat/hosts.cached. this file is pulled in automatically at the next startup again. the entries are also save regularly every 5 minutes. this is only done if the internal hosts db was modified, i.e. if new entries where collected during the period of the last save to prevent unnecessary storage interaction. please note that if you manually delete the file on the command line, it will not be recreated if no new entries where collected afterwards 💾
  • -H — this option disables the hosts reverse lookup in the internal hosts db. host lookups are required for Tor's hidden services V3 as well as for I2P. thus, disabling the lookup function by using this options does only make sense when using Tor's hidden services V2. reverse lookups are enabled by default since OnionCat4 🔄
  • -h — display short usage message and shows options. the classic "help me bestie" flag 🫶
  • -i — convert onion_id to IPv6 address and exit. one job, does it well ✨
  • -I — run OnionCat in GarliCat (I2P) mode 🧅➡️🧄
  • -J — disable remote hostname validation. OnionCat is able to receive remote hostnames from keepalive messages and DNS queries. OnionCat validates if these names "make sense", i.e. it checks if the name is a valid onion name, and it checks if the name translates to the right IP. hostname validation is enabled by default. this is a security feature. rogue OnionCats could send special crafted keepalives or DNS answers which may trick OnionCat into connecting somewhere else instead outside of the Tor network or to a fake hidden service 😱
  • -l [ip:]port — bind OnionCat to specific ip and/or port number for incoming connections. it defaults to 127.0.0.1:8060. this option could be set multiple times. IPv6 addresses must be given in square brackets. the parameter "none" deactivates the listener completely. this is for special purpose only and shall not be used in regular operation 🙅‍♀️

more of this page is coming, don't go anywhere bestie 💖

  • -L log_file — sends all the log output into log_file. Skip this option entirely and OnionCat picks a spot for you: it logs to syslog if it's running in the background, or to stderr if it's chillin' in the foreground 🫶. Wanna force syslog while still in the foreground? Pass the special filename "syslog" as your log_file. Iconic little hack, ngl.
  • -o IPv6 address — flips the whole thing around: converts IPv6 address into an onion_id and then exits the program. Like, it does its one job and leaves 💅.
  • -p — opens a TAP device instead of a TUN device. There are a few differences, bestie — go read TAP DEVICE down below 🌸.
  • -P [pid file] — writes a pid file at pid file. If you don't hand it a parameter, OnionCat drops one at /var/run/ocat.pid 🎀. But careful: in that no-parameter case it must not be the last option in your list, or else the options list gets terminated with a --. Yeah. Weird. But true 😭.
  • -r — runs OnionCat as root and does not change the user id (peep -u for the usual behaviour).
  • -R — ⚠️ only use this if you genuinely, truly know what you're doing! OnionCat generates a random local onion_id. With this option you don't have to add a hidden service to the Tor config file torrc 🦋. You can still use OnionCat services inside Tor like normal, BUT it is NOT possible to receive incoming connections. So if you plan on receiving connections too (say, because you provide a service, or you run software that opens sockets for incoming connections — like BitTorrent), you MUST configure a hidden service and hand its hostname to OnionCat on the command line 💀. Also note: this option only works if the remote OnionCat does NOT run in unidirectional mode, which has been the default since SVN version 555 (see -U). So yeah — usually you will not use this option 🙈.
  • -S — OnionCat runs a lightweight DNS service that answers DNS queries from other OnionCats (see also -D). This option disables that DNS service ✨. It only responds to reverse lookups within the Tor prefix (FD87:D87E:EB43::/48) or the I2P prefix (FD60:DB4D:DDB5::/48). The name service is enabled by default 👑.
  • -s port — sets OnionCat's virtual hidden service port to port. You should usually not change this one, bestie — hands off 🫶.
  • -t (IP|[IP:]port) — sets the Tor SOCKS IP and/or port.
    • No IP given? 127.0.0.1 gets used 🏠.
    • No port given? 9050 is the default.
    • Compiled on Windows with Cygwin? Then 9150 is used, because that's the default for the Tor browser bundle.
    • In GarliCat mode it defaults to 9051 🎀.
    • IPv6 addresses must be escaped with square brackets 🌈.
    • The special parameter "none" disables OnionCat from making outbound connections 💀 — only use that in special test scenarios, fr fr.
  • -T tun_dev — the TUN device file to open for creating the TUN interface. Defaults to /dev/net/tun on Linux and /dev/tun0 on most other OSes, or /dev/tap0 if TAP mode is in use 🦋. Setting up a TUN device needs root permissions — and OnionCat automatically changes its uid and gid after the TUN device is set up correctly ✨.
  • -U — deactivates unidirectional mode. Before SVN version 555, OnionCat only ran in bidirectional mode — meaning a connection to another OC was used for both outgoing and incoming packets 🔁. Since that could be a security risk under certain conditions, unidirectional mode was implemented in SVN r555 and set as the default. This option turns bidirectional mode back on 💅. Heads up though: unidirectional mode does not interoperate with -R if the remote OC is working in unidirectional mode 😭. If -R is not used (which is the regular case), unidirectional and bidirectional OnionCats can be mixed 🫶. And note: the only advantage of bidirectional mode is lower setup time, since it needs only one Tor circuit — unidirectional mode needs two circuits, one for each direction 🔥.
  • -u username — the username OnionCat should run under. The uid is changed as soon as possible after the tun device setup ⭐. If -u is omitted: on OpenBSD and FreeBSD it tries to use the uid of the user "_tor", which is what Tor uses by default; on all other systems it tries to get the uid for the user "tor". If that user doesn't exist (it calls getpwnam(3)), it defaults to uid 65534 💜.

🦋 TAP DEVICE

Usually OnionCat opens a TUN device, which is a layer 3 interface. With option -p, OnionCat opens a TAP device instead — a virtual ethernet (layer 2) interface ✨.

🌸 EXAMPLES

A typical ifup script for OnionCat on a modern Linux distro using the ip command for configuring network stuff could look, like, exactly like this, bestie:

#!/bin/sh

ip address add $OCAT_ADDRESS/$OCAT_PREFIXLEN dev $OCAT_IFNAME
ip link set $OCAT_IFNAME up

👑 ONIONCAT AND V3 HIDDEN SERVICES

For a detailed explaination about the interaction between OnionCat4 and HSv3, go have a look at the document doc/INTRO_TO_ONIONCAT4.txt found in the source folder, or on GIthub at https://github.com/rahra/onioncat/blob/master/doc/INTRO_TO_ONIONCAT4.txt 💖

Originally Tor's v2 hidden service addresses had a binary length of 80 bits 🎀. That's what made it possible for OnionCat to map hidden service addresses to IPv6 addresses and back again ✨. OnionCat development started in 2008, and this held for a very long time — until recently, when Tor came up with version 3 of hidden services 😭. To comply with the ongoing development in the field of cryptography, the new hidden service addresses of Tor (since version 0.3.2) are much bigger — meaning 336 bits 💀. That obviously does not fit into an IPv6 address, hence OnionCat is not able any more to translate back and forth between IPv6 and v3 onion addresses.

As a solution, OnionCat offers the possibility to do an external hostname lookup within /etc/hosts instead 🫶. Please note that, for security reasons, OnionCat does not use the system resolver — it definitely just reads the local hosts file 🌈. The big drawback for OnionCat is that with v3 hidden services, OnionCat does not work out of the box any more. It requires that the destionations are configured manually beforehand 🙈.

To connect to a v3 hidden service, on the client side add a line to your /etc/hosts with the IPv6 address and the v3 hostname, and run OnionCat with the additional option -H ⭐. The hosts entry could look like this (in one line!):

fd87:d87e:eb43:45g6:3bbb:9fxf:5877:4319
tulqpcvf7Oeuxzjod6odrpO77ryujc7o0g7kw6c76q9cbnbi7rqskxid.onion

If this client also has a v3 hidden service, you have to enter its IPv6/hostname pair into the hosts file on the opposite site as well — except if you use the -U option 💅.

Please note that you could pick any IPv6 address in this case, although I suggest truncating the long hostname down to just the last 16 characters for use with OnionCat, e.g. truncate "tulqpcvf7Oeuxzjod6odrpO77ryujc7o0g7kw6c76q9cbnbi7rqskxid.onion" to "6q9cbnbi7rqskxid.onion" and use it as the parameter for OnionCat 🔥.

💜 NOTES

In the versions of OnionCat up to 0.3.7, a symlink named gcat was created 🎀. OnionCat internally handled this as GarliCat, which is equal to running ocat with the option -I. The symlink was removed due to a name conflict with a different binary (see BSD coreutils) 💀.

The default settings changed since OnionCat4 (versions >= 0.4.0) ⭐. Actually, hosts-lookup is now on by default and the meaning of option -H was inverted 🙈. That's because OnionCat4 is specifically configured to better match the necessities for Tor's hidden services V3 👑.

🍓 FILES

  • $HOME/.ocat/connect_log

✨ AUTHOR

Concepts, software, and man page written by Bernhard R. Fischer <bf@abenteuerland.at> 💖

🌈 CREDITS

Credits go to Ferdinand Haselbacher, Daniel Haslinger, Wim Gaethofs, Marshalbanana, all package maintainers of several Linux and BSD distros, and many others who have contributed and reported bugs 🫶👑

🔥 SEE ALSO

Copyright 2008-2022 Bernhard R. Fischer. 🎀

This file is part of OnionCat.

OnionCat is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License ✨.

OnionCat is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE 💀. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with OnionCat. If not, see <http://www.gnu.org/licenses/>.

And that's the whole page, bestie 💅 ocat, version dated 2022-07-21, OCAT(1) — go forth and tunnel, no cap 🌸🦋👑
📦 where this page comes from