< Using the OnionCoffee GUI

Frequently Asked Questions >

OnionCoffee is customizable via its configuration file TORRC. You can use statement lines for customization. Some statement lines set a certain value in OnionCoffee; the first appeareance of such a statement counts; all following appeareances of the same statement line are ignored. On the other hand there are statements which gives instructions to OnionCoffee; like filter rules. They are aggregated and used as a whole.

Statement lines are given by lines of the following format:
Statement 12 en ...
where 12 is the first parameter and en the second parameter in this example

In this guide the above option line would be described like the following:

• Statement <First parameter>(First default value) <Second parameter>(Second default value) ....: This is an description of the statement with the name "Statement"

Currently the torrc file has to be placed into the same directory as the TorJava.JAR file to be recognized as a TORRC config file. The OnionCoffee distribution is accompied with a default configuration file.

General Options

• cacheMaxAgeSeconds <Seconds>(24 * 3600: one day) Maximum age of the directory cache file until it is thrown away.
• startupDelaySeconds <Seconds>(15) Time interval of the startup phase during which no connections are possible; this is needed because the time that the circuits need to be build up can only be estimated.
• portwwwproxy <Port number>(8080) Port number under which the WWW proxy server that OnionCoffee supplies can be accessed. This option may be useful if you have problems with your local firewall.
• portsocksproxy <Port number>(1080) ort number under which the SOCKS proxy server that OnionCoffee supplies can be accessed. This option may be useful if you have problems with your local firewall.

Logging Options

OnionCoffee can report a lot of events that happen while it is running. This is very important for finding out causes of complex problems and for optimization. It is possible to set the log verbosity of certain functionality areas. Beyond this you can decide what you want to be displayed in the terminal and what should be written to a logfile that you specified.

Be aware that the messages written into the logfiles are accompied with time and date and will break your anonymity if they are combined with connection data from your internet provider. Consider to safely delete your logging data in certain intervals or simply turn of logging if you don't need it.

The general fromat of a logging option in TORRC is:

• Log <Area> <Verbosity>: Log messages that are displayed on the console
• LogFile <Area> <Verbosity>: Log messages that are written to the logfile
• Log filename <Filename>: Set <Filename> as logfile for TorJava.

Consult the following tables for different recognized values of <Area> and <Verbosity>:

<Area>	Description of messages
General	Anything that does not fit into another category Especially experimental functionality
Directory	Fetching, updating, parsing, and writing directories Also messages concerning version 2 directories
TLS	Certificates and TLS connection management
Circuit	Buildup and closedown of circuits
Stream	Buildup and closedown of streams. Especially also thread management because threads are extensivly used in conjunction with streams data processing.
Cell	Sending, receiving, dispatching and especially parsing cells.With high verbosity this results in a high troughput of output messages.
Crypto	Symmetric encryption and digest checks.
HiddenService	Experimental.

<Verbosity>	Internal Name	Description
0	NOLOG	Log nothing
1	ERROR	Only log real errors
2	WARNING	Aditionally: Errors that are non critical.
3	INFO	Aditionally: Important information messages
4	VERBOSE	Aditionally: Log detailed program flow.
5	RAW_DATA	Aditionally: Logging on data package (binary) level.This leads naturally to a very high troughput of log messages.

Country and Node Avoidance

It is possible to configure OnionCoffee in a way so that selected nodes or countries are avoided. This is of interest if you do not trust certain nodes or if there are problems with using nodes in certain countries.

• AvoidCountry <Country Code>: Avoid all nodes in the country with the mentioned country code.
• AvoidNode <Node Name>: Avoid the node with the mentioned name. You can find out about node names by looking at the log or logfile, via the GUI, or with an directory dump.

GUI Options

• guiUpdateIntervalMilliSeconds <Milliseconds>(3000): This is the refresh interval for all GUI controls. A changed state of OnionCoffee is only updated in the GUI at those intervals.
• guiDisplayNodeNames <true/false>(false): Should the names of the nodes be displayed near the pictured points on the world map in the GUI? If enabled this can lead to serious clutter in the map; so it is disabled by default.
• guiCountryOfUser <Country Code>(eu) Set the country of the user; this is used by certain GUI elements.

TOR Directories

• trusted <TOR node name>(moria2) <TOR node IP adress>(18.224.0.114) <TOR node port number for directory services>(80) <TOR node fingerprint in dotted hex notation>(71:9B:E4:5D:E2:24:B6:07:C5:37:07:D0:E2:14:3E:2D:42:3E:74:CF): Defines certain TOR nodes as trusted. Trusted nodes are those that are used by TorJava for fetching the directory initially.
• DirectoryV1Refresh <Minutes>(30): Interval of directory refreshes for version 1 directories (currently phasing out) in minutes. This is much longer than the refresh interval for version 2 directories due to the fact that version 1 directories are refreshed as a whole all at once; not incrementally
• DirectoryRefresh <Minutes>(2): Interval of directory refreshes for version 2 directories in minutes.
• dirV2ReloadRetries <Number>(3): Number of reload retires while updating version 2 directories.
• dirV2ReloadTimeout <Minutes>(10): Timeout value in minutes for the reload of version 2 directories.
• dirV2DescriptorsPerBatch <Number>(1): Number of descriptors that should be retrieved per batch. Changing this value is considered somewhat experimental.
• MaxNumberOfDescriptorsFirstTime <Number>(180): Maximum number of disciptors that are processed during the first retrival of a version 2 directory. Set the number to 0 if you do not want to set an upper limit. Setting this value to a reasonable number is strongly suggested for circumventing overflow attemps.
• MaxNumberOfDescriptorsPerUpdate <Number>(80): Maximum number of disciptors that are processed during a version 2 directory update. This number is less than the number for the first time retrieval due to the fact that it is assumed that updated are smaller than first time retrivals. Set the number to 0 if you do not want to set an upper limit. Setting this value to a reasonable number is strongly suggested for circumventing overflow attemps.

Filtering HTTP Requests

While OnionCoffee can expand anonymity in case of connection data it does not anonymize the transmitted data itself. You as a user have to make sure that you do not break your anonymity by sending information that is suitable to identify you. What TOR itself also does not provide is application layer anonymity. Concerning the WorldWideWeb the application layer is HTTP. This is while you should use an HTTP request anonymizer together with TOR.

OnionCoffee has a small HTTP Header filter which will suit most situations well and filters most of the worst kinds of de-anonymizing information.

• FilterHeader <Header Name>: Filter out the HTTP header with the given name from the HTTP request.
• ReplaceHeader <Header Name> <Replacement content>: Replace the content of the HTTP header with the given name with the replacement content that is given.

Quality of Service

Quality of service is an important topic in anonymity networks. While anonymity and performance are contrasts in the standard case it is also possible to fine-tune or trade in some other areas for better performance. So if you need to optimize performance of OnionCoffee (and other clients for anonymous overlay networks) you have basically the following options:

• Applying additional knowledge about the network: Rankings
• Estimating chances for successful execution: Retries and Timeouts
• Trading friendliness for performance: Patience and Aggressiveness
• Trading anonymity for performance: Less anonymity

Rankings

OnionCoffee tries to rank nodes in the TOR network for their performance and stability. It also uses rankings from the version 2 directories. There are currently two options in this area that can be fine-tuned:

• RankingIndexEffect <Probability>(0.5): Probabilty that a random node that was choosen is actually used for a circuit; stochastically independent from the ranking index of the node.
• RankingTransferPerServerUpdate <Probability>(0.8): States how much of the old locally stored ranking index should be transfered into the new local ranking index during a server update. A value of 1 makes the new local ranking index the old local ranking index; a value of 0 makes the remote ranking index the new local ranking index.

Retries and Timeouts

Sometimes you don't know if a certain action will be successful. While trying again with the same values places the same burden on the network than trying with new values it lenghtes the time an action is successfully executed. There are two retry-counts that do not influcence the fiendliness of your client inside the TOR network:

• RetriesConnect <Number>(3): Specifies how often OnionCoffee should try to build a circuit with a certain first node in the TOR network until the first node is abandoned.
• RetriesStreamBuildup <Number>(3): Currently disabled.

Queue timeouts are not directly upper time limits for the respective action; you can think of queue timeouts as an upper limit for time intervals between the steps of a particular action. So queue timeouts are give indirectly the upper bound for fulfilling a particualr task.

• QueueTimeoutCircuit <Second>(40) Queue timeout value during the buildup of circuits.
• QueueTimeoutResolve <Second>(20) Queue timeout value for anonymously resolving hostname.
• QueueTimeoutStreamBuildup <Second>(40) Queue timeout value during the buildup of streams.

Patience and Aggressiveness

While blocking network ressources is not especially nice it is better in terms of performance to keep resources in your hand; so that you have them if you need them at short notice. Also it is better to try to obtain serveral circuits at once if they are needed; so that you get a circuit in the shortest time as possible. This is especially unfriendly.

• ReconnectCircuit <Number>(3): How many times should the mainteance thread try to rebuild a circuit after a nodes fails until the whole circuit is closed down?
• DefaultIdleCircuits <Number>(3): How much circuits should be kept around by the background threads even when there is no network activity?
• CircuitClosesOnFailures <Number>(4): After how many (stream buildup or likewise) failures should a circuit be closed?
• circuitsMaximumNumber <Number>(3): Maximum number of circuits that TorJava can open at any given time.
• veryAggressiveStreamBuilding <true/false>(false): Agressive stream buildings means that OnionCoffee tries to open several streams at once if one request from the client comes in. While this leads most times to shorter response times it severly wastes resources of the TOR network.Please be aware that enabling this option could lead to your IP or IP subnet being expelled from the TOR network. It is only used for experimental purposes currently.

Less anonymity

As a last resort in solving performance problems you can try to lessen the anonymity of your communication. All options below more or less degrade your anonymity. You can even nearly de-anonymize yourself by setting those options to certain values..

• RouteMinLength <Number>(3): General minimum length of a route that a circuit is build upon.
• RouteMaxLength <Number>(3): General maximum length of a route that a circuit is build upon.
• RouteUniqClassC <true/false>(true): All TOR nodes in a route must each be in a different class c network if this option is set to true.
• RouteUniqCountry <true/false>(true): All TOR nodes in a route must each be in a different country if this option is set to true.
• AllowNodeMultipleCircuits <Number>(3): In how much circuits can a node be used simultanously? This value should be at least 1
• StreamsPerCircuit <Number>(50): How much streams are allowed to be routed through a single circuit simultanously?

Server Mode (currently disabled)

Server mode is currently not completly tested and implemented. We decided to disable the code in the current releases. For the sake of completeness we have included here a list of options that only apply to OnionCoffee operating in server mode.

• nickname <String>(TorJava) Nickname of the OnionCoffee server. Currently only used for builing version 1 directories.
• dirserverport <Portnumber>(0) Portnumber under which the OnionCoffee (version 1) directory server should operate. Special value 0 leads to the dirserver being disabled.
• orport i><Portnumber>(0) Portnumber under which the OnionCoffee onion router (server mode) should operate. Special value 0 leads to onion router (server mode) being disabled.