OCAT(1) OnionCat User's Manual OCAT(1)NAMEocat - OnionCat creates a transparent IPv6 layer on top of Tor's hidden
services.
gcat - GarliCat is like OnionCat but it works with I2P instead of Tor.
SYNOPSISocat-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)
DESCRIPTION
OnionCat creates a transparent IPv6 layer on top of Tor's hidden ser‐
vices or I2P's tunnels. It transmits any kind of IP-based data trans‐
parently 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 for‐
warded 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 con‐
figured hidden service (see tor(8)). Depending on the configuration of
Tor the onion_id usually can be found at /var/lib/tor/hidden_ser‐
vice/hostname or similar location. The i2p_id is the 80 bit long
Base32 encoded hostname of the I2P server tunnel.
OPTIONS
-4 Enable IPv4 forwarding. See http://www.cypherpunk.at/onion‐
cat/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
default.
-C Disable the local controller interface. The controller inter‐
faces listens on localhost (127.0.0.1 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 pro‐
duction 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).
-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. This defaults to 127.0.0.1:8060. This option could
be set multiple times. IPv6 addresses must be given in square
brackets.
-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 fore‐
ground. 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 differ‐
ences. 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.
-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 127.0.0.1
will be used, if no port is specified 9050 will be used as
defaults. IPv6 addresses must be escaped by square brackets.
-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 username
username under which ocat should run. The uid is changed as soon
as possible after tun device setup.
TAP DEVICE
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 ether‐
net (layer 2) interface.
NOTES
This man page is still not finished...
FILES
$HOME/.ocat/connect_log
AUTHOR
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.
SEE ALSO
OnionCat project page http://www.cypherpunk.at/onioncat/
Tor project homepage http://www.torproject.org/
I2P project homepage http://www.i2p2.de/
COPYRIGHT
Copyright 2008-2009 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 2009-11-15 OCAT(1)
