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

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 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
       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	configura-
       tion  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  autho-
	      rization 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.  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 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 neces-
	      sary 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  host-
	      name 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
       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 Ferdi-
       nand 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)