source: trunk/man/ocat.1 @ 416

Last change on this file since 416 was 416, checked in by eagle, 8 years ago

man page updated
support of random local addresses added (option -R)

File size: 5.9 KB
Line 
1.\" Copyright 2008 Bernhard R. Fischer, Daniel Haslinger.
2.\"
3.\" This file is part of OnionCat.
4.\"
5.\" OnionCat is free software: you can redistribute it and/or modify
6.\" it under the terms of the GNU General Public License as published by
7.\" the Free Software Foundation, version 3 of the License.
8.\"
9.\" OnionCat is distributed in the hope that it will be useful,
10.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12.\" GNU General Public License for more details.
13.\"
14.\" You should have received a copy of the GNU General Public License
15.\" along with OnionCat. If not, see <http://www.gnu.org/licenses/>.
16.\"
17.TH OCAT 1 2008-12-07 "ocat" "OnionCat User's Manual"
18.SH NAME
19ocat \- OnionCat creates a transparent IPv6 layer on top of TOR's hidden services.
20.SH SYNOPSIS
21.B ocat
22-i \fIonion_id                      (1st form)\fP
23.br
24.B ocat
25-o \fIIPv6_address                  (2nd form)\fP
26.br
27.B ocat
28[\fIOPTION\fP] \fIonion_id                (3rd form)\fP
29.br
30.B ocat
31-R [\fIOPTION\fP]\fI                      (4th form)\fP
32.br
33.SH DESCRIPTION
34OnionCat creates a transparent IPv6 layer on top of TOR's hidden services. It
35transmits any kind of IP-based data transparently through the TOR network on a
36location hidden basis. You can think of it as a point-to-multipoint VPN
37between hidden services.
38
39OnionCat is a stand-alone application which runs in userland and is a connector
40between TOR and the local OS. Any protocol which is based on IP can be
41transmitted. Of course, UDP and TCP (and probably ICMP) are the most important
42ones but all other protocols can also be forwarded through it.
43
44OnionCat opens a TUN device and assigns an IPv6 address to it. All packets
45forwarded to the TUN device by the kernel are forwarded by OnionCat to other
46OnionCats listening on TOR's hidden service ports.  The IPv6 address depends on
47the \fIonion_id\fP of the locally configured hidden service (see \fBtor(8)\fP).
48Depending on the configuration of TOR the \fIonion_id\fP usually can be found
49at \fI/var/lib/tor/hidden_service/hostname\fP or similar location.
50
51.SS OPTIONS
52.TP
53\fB\-4\fP
54Enable IPv4 forwarding.
55.TP
56\fB\-a\fP
57OnionCat creates a log file at $HOME/.ocat/connect_log. All incomming connects are
58log to that file. $HOME is determined from the user under which OnionCat runs
59(see option -u).
60.TP
61\fB\-b\fP
62Run OnionCat in background.
63.TP
64\fB\-C\fP
65Disable the local controller interface. The controller interfaces listens on
66localhost (127.0.0.1 and ::1 port 8066) for incomming connections. It's
67currently used for debugging purpose and not thread-safe and does not have any
68kind of authentication or authorization mechanism. Hence, it should not be used
69in production environments.
70.TP
71\fB\-d\fP \fIn\fP
72Set debug level to \fIn\fP. Default = 7 which is maximum. Debug output will
73only be created if OnionCat was compiled with option DEBUG.
74.TP
75\fB\-f\fP \fIconfig file\fP
76Read initial configuration from \fIconfig file\fP.
77.TP
78\fB\-h\fP
79Display short usage message and shows options.
80.TP
81\fB\-i\fP
82Convert \fIonion_id\fP to IPv6 address and exit.
83.TP
84\fB\-l\fP \fIport\fP
85Local \fIport\fP number OnionCat listens for incoming connections.
86.TP
87\fB\-L\fP \fIlog_file\fP
88Log output to \fIlog_file\fP instead of stderr.
89.TP
90\fB\-o\fP \fIIPv6 address\fP
91Convert \fIIPv6 address\fP to \fIonion_id\fP and exit program.
92.TP
93\fB\-p\fP
94Use TAP device instead of TUN device. There are a view differences. See \fBTAP
95DEVICE\fP later.
96.TP
97\fB\-P\fP \fIpid file\fP
98Create \fIpid file\fP instead of \fB/var/run/ocat.pid\fP.
99.TP
100\fB\-r\fP
101Run OnionCat as root and don't change user id (see option \fB\-u\fP).
102.TP
103\fB\-R\fP
104Generate a random local onion_id. With this option it is not necessary to add a
105hidden service to the Tor configuration file \fBtorrc\fP.  With this option set
106one might use OnionCat services within Tor as usualy but it is NOT possible to
107receive incoming connections. If you plan to also receive connections (e.g.
108because you provide a service or you use software which opens sockets for
109incomming connections like Bitorrent) you MUST configure a hidden service and
110supply its hostname to OnionCat on the command line.
111.TP
112\fB\-s\fP \fIport\fP
113Set OnionCat's virtual hidden service port to \fIport\fP.
114.TP
115\fB\-t\fP \fI(IP|[IP:]port)\fP
116Set TOR SOCKS \fIIP\fP and/or \fIport\fP. If no \fIIP\fP is specified 127.0.0.1
117will be used, if no \fIport\fP is specified 9050 will be used as defaults. IPv6
118addresses must be escaped by square brackets.
119.TP
120\fB\-T\fP \fItun_dev\fP
121TUN device file to open for creation of TUN interface, defaults to
122/dev/net/tun. Setup of a TUN device needs root permissions. OnionCat automatically
123changes userid after the TUN device is set up correctly.
124.TP
125\fB\-u\fP \fIusername\fP
126\fIusername\fP under which ocat should run. The uid is changed as soon as possible
127after tun device setup.
128
129.SS TAP DEVICE
130Usually OnionCat opens a TUN device which is a layer 3 interface. With option
131\fB\-p\fP OnionCat opens a TAP device instead which is a virtual ethernet
132(layer 2) interface.
133
134.SH NOTES
135This man page is still not finished...
136
137.SH FILES
138$HOME/.ocat/connect_log
139
140.SH AUTHOR
141Software and man page written by Bernhard R. Fischer.
142Concept by Bernhard R. Fischer and Daniel Haslinger.
143
144.SH "SEE ALSO"
145OnionCat project page http://www.abenteuerland.at/onioncat/
146
147TOR project homepage http://www.torproject.org/
148
149.SH COPYRIGHT
150Copyright 2008 Bernhard R. Fischer, Daniel Haslinger.
151
152This file is part of OnionCat.
153
154OnionCat is free software: you can redistribute it and/or modify
155it under the terms of the GNU General Public License as published by
156the Free Software Foundation, version 3 of the License.
157
158OnionCat is distributed in the hope that it will be useful,
159but WITHOUT ANY WARRANTY; without even the implied warranty of
160MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
161GNU General Public License for more details.
162
163You should have received a copy of the GNU General Public License
164along with OnionCat. If not, see <http://www.gnu.org/licenses/>.
Note: See TracBrowser for help on using the repository browser.