OPTIONS¶

In the following is a description of all options. Typically you won't need any of them except specifying your OnionCat's .onion hostname. Depending on your setup you may use options -g and -A.

-2

This option is here only for simplicity. With this option OnionCat behaves like OnionCat3 (version < 0.4.0). Actually it is a short form for using the options -D -H -S.

-4

Enable IPv4 forwarding. See http://www.cypherpunk.at/onioncat_trac/wiki/IPv4
IPv4-througth-IPv6 tunnel through OnionCat is recommended instead of using native IPv4 forwarding.

-5 'socks5'|'direct'

This option has a mandatory argument which is literally either socks5 or direct.
By default OnionCat uses SOCKS4A (version 4a) to connect to the anonymization network proxy (e.g. Tor). With this option set to socks5, OnionCat uses SOCKS5 (version 5 as specified in RFC1928), currently with no authentication mechanism. As of today it actually makes no difference but it might be desireable in future.
If direct is used, OnionCat does not connect through the SOCKS server but instead it connects directly to the remote peers using the hosts lookup mechanism (see option -H). This feature is experimental and turns OnionCat into a distributed virtual switch based on regular Internet transport instead of Tor. It is a useful feature for a lab setup.
This option also disables the remote hostname validation (option -J).
Please note that OnionCat does not implement any encryption technique! It is a plain tunneling through TCP sessions.

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

-A [ipv6/]hostname

This option lets you add an IP address hostname pair to the internal hosts db. Typically it is enough to specify just the .onion hostname because the IPv6 address is derived from the hostname. Adding an IP address is either redundant or may be used in special scenarios where the IPv6 address differes from its original address. The latter will only work in a closed environment and is not interoperable with other OnionCats in the wild because by default the names and IPs are verified to be correct. This option may be specified multple times. Alternatively you could put the IP/hostname pairs into the OnionCat hosts file (see option -g).

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

-D

Disable OnionCat's DNS lookup. If OnionCat has to make an outgoing connection but no suitable entry is found in the internal hosts db, OnionCat will do a DNS query at the hosts found in the internal hosts db. This option deactivates this feature.
Hostname lookups are enabled by default since OnionCat4.

-e ifup

Execute script ifup to bring up the tunnel interface.
OnionCat will create a new tunnel interface and execute ifup immediatly after opening the network interface. This is intended as a universial interface for configuring the tunnel device and do additinal tasks when starting OnionCat. The script is executed with the same privilege as OnionCat is started, i.e. before dropping privileges. This typically is root. The script is run only once at startup.

See below in section EXAMPLES for a typical Linux ifup shell script.

OnionCat executes the file ifup with a call to execlp(3) and will pass the following environment variables:

OCAT_IFNAME
This variable contains the name of the network interface, e.g. "tun0".

OCAT_ADDRESS
This variable contains the IPv6 address which is associated with this instance of OnionCat and its hidden service address.

OCAT_PREFIXLEN
This variable contains the prefix length of the IPv6 prefix which typically is 48.

OCAT_PREFIX
This variable contains the IPv6 prefix, i.e. the network. This typically is fd87:d87e:eb43:: in OnionCat (Tor) mode and fd60:db4d:ddb5:: in GarliCat (I2P) mode.

OCAT_ONION_URL
This variable contains the short onion URL without domain appendix. It is a 16 character long string.

OCAT_ONION3_URL
This variable contains the long onion URL if available which is always true for I2P and in case of Tor it is used together with the HSv3 variant.

OCAT_DOMAIN
This variable contains the TLD appendix which is .onion for Tor and .b32.i2p for I2P.

-E s

This option sets the expiry time in secondes for remote entries in the internal hosts db.
If the TTL of an entry expires, OnionCat will try to renew the entry by connecting to the remote OnionCat to retrieve a new keepalive. If it is unreachable it will retry after some time again. If it was unreachable for more than s seconds, the entry will be removed from the internal hosts db.
The default expiry time is 604800 seconds which is 7 days.

-f config file

Read initial configuration from config file.

-g hosts_path

Set the path to the hosts file. This option automatically enables option -H (see there). If -g is not set, the path defaults to SYSCONFDIR/tor/onioncat.hosts where SYSCONFDIR typically is /etc or /usr/local/etc.
On exit, OnionCat saves all collected hosts entries to DATADIR/onioncat/hosts.cached. This file is pulled in automatically at the next startup again. The entries are also save regularly every 5 minutes. This is only done if the internal hosts db was modified, i.e. if new entries where collected during the period of the last save to prevent unnecessary storage interaction. Please note that if you manually delete the file on the command line, it will not be recreated if no new entries where collected afterwards.

-H

This option disables the hosts reverse lookup in the internal hosts db. Host lookups are required for Tor's hidden services V3 as well as for I2P. Thus, disabling the lookup function by using this options does only make sense when using Tor's hidden services V2.
Reverse lookups are enabled by default since OnionCat4.

-h

Display short usage message and shows options.

-i

Convert onion_id to IPv6 address and exit.

-I

Run OnionCat in GarliCat (I2P) mode.

-J

Disable remote hostname validation. OnionCat is able to receive remote hostnames from keepalive messages and DNS queries. OnionCat validates if these names "make sense", i.e. it checks if the name is a valid onion name, and it checks if the name translates to the right IP.
Hostname validation is enabled by default.
This is a security feature. Rogue OnionCats could send special crafted keepalives or DNS answers which may trick OnionCat into connecting somewhere else instead outside of the Tor network or to a fake hidden service.

-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 few differences. See TAP DEVICE later.

-P [pid file]

Create pid file at pid_file. If the option parameter is omitted OnionCat 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 or the options list is terminated with a "--".

-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 OnionCat does NOT run in unidirectional mode which is default since SVN version 555 (see option -U). So usually you will not use this option.

-S

OnionCat runs a lightweight DNS services to respond to DNS queries from other OnionCats (see also option -D). This option disables this DNS service. It responds only to reverse lookups within the Tor (FD87:D87E:EB43::/48) or I2P (FD60:DB4D:DDB5::/48) prefix.
The name service is enable by default.

-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 default. If compiled on Windows with Cygwin 9150 will be used because this is the default for the Tor browser bundle. In GarliCat mode it defaults to 9051. 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 its uid and gid 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 the unidirectional mode does not interoperate with option -R if the remote OC is working in unidirectional mode. If option -R is not used (which is the regular case), unidirectional und bidirectional OnionCats can be mixed. Please note that the only advantage of bidirectional mode is that it has a lower setup time since it needs only one Tor circuit. Unidirectional mode needs two circuits, one for each direction.

-u username

username under which OnionCat should run. The uid is changed as soon as possible after the tun device setup. If -u is omitted, on OpenBSD and FreeBSD it tries to use the uid of the user "_tor" which is by default used for Tor. On all other systems it tries to get the uid for the user "tor". If it does not exists (it calls getpwnam(3)) it defaults to the uid 65534.

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.