Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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

       -4     Enable   IPv4  forwarding.  See
	      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  in-
	      coming  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  de-
	      tach  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  de-

       -C     Disable  the  local  controller interface. The controller	inter-
	      faces listens on localhost ( and	::1 port 8066) for in-
	      coming  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. 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 op-

       -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/ 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 de-
	      faults. IPv6 addresses must be escaped by	square brackets.
	      The special parameter "none" disables OnionCat from making  out-
	      bound  connections. This shall be	used only in special test sce-

       -T tun_dev
	      TUN device file to open for creation of TUN  interface.  It  de-
	      faults  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 an-
	      other OC was used	for outgoing and incoming packets. Since  this
	      could  be	 a  security  risk under certain conditions, unidirec-
	      tional 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	ether-
       net (layer 2) interface.

       This man	page is	still not finished...


       Concepts, software,  and	 man  page  written  by	 Bernhard  R.  Fischer
       <>.  Package	maintenance  and additional support by
       Ferdinand Haselbacher, Daniel Haslinger	<>,  and
       Wim Gaethofs.

       OnionCat	project	page

       Tor project homepage

       I2P project homepage

       Copyright 2008-2013 Bernhard R. Fischer.

       This file is part of OnionCat.

       OnionCat	is free	software: you can redistribute it and/or modify	it un-
       der 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 <>.

ocat				  2009-11-15			       OCAT(1)


Want to link to this manual page? Use this URL:

home | help