OCAT(1)                     OnionCat User's Manual                     OCAT(1)

       ocat - OnionCat creates a transparent IPv6 layer on top of Tor's hidden
       gcat - GarliCat is like OnionCat but it works with I2P instead of Tor.

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

       OnionCat creates a transparent IPv6 layer on top of Tor's hidden
       services or I2P's tunnels. It transmits any kind of IP-based data
       transparently through the Tor/I2P network on a location hidden basis.
       You can 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. Of course, UDP and TCP (and probably ICMP)
       are the most important ones but all other protocols can also be
       forwarded through it.

       OnionCat opens a TUN device and assigns an IPv6 address to it. All
       packets forwarded to the TUN device by the kernel are forwarded by
       OnionCat to other OnionCats listening on Tor's hidden service ports or
       I2P's server tunnels. 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.

       -4     Enable IPv4 forwarding. See
              http://www.cypherpunk.at/onioncat/wiki/IPv4 for further
              information on IPv4.
              Native IPv4 forwarding is deprecated. The recommended solution
              for IPv4 forwarding is to build a IPv4-through-IPv6 tunnel
              through OnionCat.

       -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).

       -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

       -C     Disable the local controller interface. The controller
              interfaces listens on localhost ( and ::1 port 8066)
              for incoming connections. It's currently used for debugging
              purpose and not thread-safe and does not have any kind of
              authentication or authorization mechanism. Hence, it should not
              be used in production environments.

       -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).

       -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

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

              This variable contains the name of the network interface, e.g.

              This variable contains the IPv6 address which is associated with
              this instance of OnionCat and its hidden service address.

              This variable contains the prefix length of the IPv6 prefix
              which typically is 48.

       -f config file
              Read initial configuration from config file.

       -h     Display short usage message and shows options.

       -i     Convert onion_id to IPv6 address and exit.

       -I     Run OnionCat in GarliCat mode. Using this option is identical to
              running OnionCat with the command name gcat.

       -l [ip:]port
              Bind Onioncat to specific ip  and/or port number for incoming
              connections. It defaults to This option could be
              set multiple times. IPv6 addresses must be given in square
              The parameter "none" deactivates the listener completely. This
              is for special purpose only and shall not be used in regular

       -L log_file
              Log output to log_file. If option is omitted, OnionCat logs to
              syslog if running in background or to stderr if running in
              foreground. If syslogging is desired while running in
              foreground, specify the special file name "syslog" as log file.

       -o IPv6 address
              Convert IPv6 address to onion_id and exit program.

       -p     Use TAP device instead of TUN device. There are a view
              differences. See TAP DEVICE later.

       -P [pid file]
              Create pid file at pid_file. If the option parameter is omitted
              OC will create a pid file at /var/run/ocat.pid. In the latter
              case it MUST NOT be the last option in the list of options.

       -r     Run OnionCat as root and do not change user id (see option -u).

       -R     Use this option only if you really know what you do!  OnionCat
              generates a random local onion_id. With this option it is not
              necessary to add a hidden service to the Tor configuration file
              torrc.  One might use OnionCat services within Tor as usually
              but it is NOT possible to receive incoming connections. If you
              plan to also receive connections (e.g.  because you provide a
              service or you use software which opens sockets for incoming
              connections like Bitorrent) you MUST configure a hidden service
              and supply its hostname to OnionCat on the command line.  Please
              note that this option does only work if the remote OC does not
              run in unidirectional mode which is default since SVN version
              555 (see option -U).

       -s port
              Set OnionCat's virtual hidden service port to port. This should
              usually not be changed.

       -t (IP|[IP:]port)
              Set Tor SOCKS IP and/or port. If no IP is specified
              will be used, if no port is specified 9050 will be used as
              defaults. IPv6 addresses must be escaped by square brackets.
              The special parameter "none" disables OnionCat from making
              outbound connections. This shall be used only in special test

       -T tun_dev
              TUN device file to open for creation of TUN interface. It
              defaults to /dev/net/tun on Linux and /dev/tun0 on most other
              OSes, or /dev/tap0 if TAP mode is in use. Setup of a TUN device
              needs root permissions. OnionCat automatically changes userid
              after the TUN device is set up correctly.

       -U     Deactivate unidirectional mode. Before SVN version 555 OnionCat
              ran only in bidirectional mode. This is that a connection to
              another OC was used for outgoing and incoming packets. Since
              this could be a security risk under certain conditions,
              unidirectional mode was implemented in SVN r555 and set to
              default. With this option bidirectional mode can be enabled
              again. Please note that this does not interoperate with option
              -R if the remote OC is working in unidirectional mode.

       -u username
              username under which ocat should run. The uid is changed as soon
              as possible after tun device setup.

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

       A typical ifup script for OnionCat for a modern Linux distribution
       using the `ip` command for configuring network related stuff could look
       like the following:


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

       This man page is still not finished...


       Concepts, software, and man page written by Bernhard R. Fischer
       <bf@abenteuerland.at>. Package maintenance and additional support by
       Ferdinand Haselbacher, Daniel Haslinger <creo-ocat@blackmesa.at>, and
       Wim Gaethofs.

       OnionCat project page https://www.onioncat.org/

       OnionCat source packages are found at

       Tor project homepage https://www.torproject.org/

       I2P project homepage https://geti2p.net/

       Copyright 2008-2017 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/>.

ocat                              2017-03-05                           OCAT(1)