Ubuntu Manpage: ocat - OnionCat creates a transparent IPv6 layer on top of Tor's hidden services.

Provided by: onioncat_0.2.2+svn559-1_amd64

NAME

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

SYNOPSIS

       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)

DESCRIPTION

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.

OPTIONS
-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 default.

-C Disable the local controller interface. The controller interfaces 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
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).

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

-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 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.
The special parameter "none" disables OnionCat from making outbound connections.
This shall be used only in special test scenarios.

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

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 ethernet (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.

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