.\" Copyright 2008 Bernhard R. Fischer, Daniel Haslinger.
.\"
.\" 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 .
.\"
.TH OCAT 1 2009-11-15 "ocat" "OnionCat User's Manual"
.SH NAME
ocat \- OnionCat creates a transparent IPv6 layer on top of Tor's hidden services.
.br
gcat \- GarliCat is like OnionCat but it works with I2P instead of Tor.
.SH SYNOPSIS
.B ocat
\-i \fIonion_id (1st form)\fP
.br
.B ocat
\-o \fIIPv6_address (2nd form)\fP
.br
.B ocat
[\fIOPTION\fP] \fIonion_id (3rd form)\fP
.br
.B ocat
\-R [\fIOPTION\fP]\fI (4th form)\fP
.br
.B gcat
[\fIOPTION\fP] \fIi2p_id (5th form)\fP
.br
.SH 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 \fIonion_id\fP or the i2p_id, respectively. The
\fIonion_id\fP is the hostname of the locally configured hidden service (see
\fBtor(8)\fP). Depending on the configuration of Tor the \fIonion_id\fP usually
can be found at \fI/var/lib/tor/hidden_service/hostname\fP or similar location.
The \fIi2p_id\fP is the 80 bit long Base32 encoded hostname of the I2P server
tunnel.
.SS OPTIONS
.TP
\fB\-4\fP
Enable IPv4 forwarding. See http://www.cypherpunk.at/onioncat/wiki/IPv4 for further
information on IPv4.
.br
Native IPv4 forwarding is deprecated. The recommended solution for IPv4
forwarding is to build a IPv4-through-IPv6 tunnel through OnionCat.
.TP
\fB\-a\fP
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).
.TP
\fB\-b\fP
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.
.TP
\fB\-B\fP
Run OnionCat in foreground. OnionCat will log to stderr by default.
.TP
\fB\-C\fP
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.
.TP
\fB\-d\fP \fIn\fP
Set debug level to \fIn\fP. 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).
.TP
\fB\-f\fP \fIconfig file\fP
Read initial configuration from \fIconfig file\fP.
.TP
\fB\-h\fP
Display short usage message and shows options.
.TP
\fB\-i\fP
Convert \fIonion_id\fP to IPv6 address and exit.
.TP
\fB\-I\fP
Run OnionCat in GarliCat mode. Using this option is identical to running OnionCat
with the command name \fBgcat\fP.
.TP
\fB\-l\fP \fI[ip:]port\fP
Bind Onioncat to specific \fIip \fP and/or \fIport\fP 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.
.br
The parameter \fI"none"\fP deactivates the listener completely. This is for
special purpose only and shall not be used in regular operation.
.TP
\fB\-L\fP \fIlog_file\fP
Log output to \fIlog_file\fP. 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.
.TP
\fB\-o\fP \fIIPv6 address\fP
Convert \fIIPv6 address\fP to \fIonion_id\fP and exit program.
.TP
\fB\-p\fP
Use TAP device instead of TUN device. There are a view differences. See \fBTAP
DEVICE\fP later.
.TP
\fB\-P\fP \fI[pid file]\fP
Create \fIpid file\fP at \fIpid_file\fP. If the option parameter is omitted OC
will create a pid file at \fB/var/run/ocat.pid\fP. In the latter case it MUST
NOT be the last option in the list of options.
.TP
\fB\-r\fP
Run OnionCat as root and do not change user id (see option \fB\-u\fP).
.TP
\fB\-R\fP
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 \fBtorrc\fP. 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
\fB\-U\fP).
.TP
\fB\-s\fP \fIport\fP
Set OnionCat's virtual hidden service port to \fIport\fP. This should usually
not be changed.
.TP
\fB\-t\fP \fI(IP|[IP:]port)\fP
Set Tor SOCKS \fIIP\fP and/or \fIport\fP. If no \fIIP\fP is specified 127.0.0.1
will be used, if no \fIport\fP is specified 9050 will be used as defaults. IPv6
addresses must be escaped by square brackets.
.br
The special parameter \fI"none"\fP disables OnionCat from making outbound
connections. This shall be used only in special test scenarios.
.TP
\fB\-T\fP \fItun_dev\fP
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.
.TP
\fB\-U\fP
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 \fIand\fP 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 \fB\-R\fP if the remote OC is
working in unidirectional mode.
.TP
\fB\-u\fP \fIusername\fP
\fIusername\fP under which ocat should run. The uid is changed as soon as possible
after tun device setup.
.SS TAP DEVICE
Usually OnionCat opens a TUN device which is a layer 3 interface. With option
\fB\-p\fP OnionCat opens a TAP device instead which is a virtual ethernet
(layer 2) interface.
.SH NOTES
This man page is still not finished...
.SH FILES
$HOME/.ocat/connect_log
.SH AUTHOR
Concepts, software, and man page written by Bernhard R. Fischer
. Package maintenance and additional support by Ferdinand
Haselbacher, Daniel Haslinger , and Wim Gaethofs.
.SH "SEE ALSO"
OnionCat project page http://www.cypherpunk.at/onioncat/
Tor project homepage http://www.torproject.org/
I2P project homepage http://www.i2p2.de/
.SH 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 .