How to run more than on instance of TorChat

This howto will not work with versions below 0.9.9.260

First I will explain how torchat.ini and portable mode are working and where all relevant data files are located. Then I will explain some things about adresses and port numbers of the client and the Tor proxy. You should fully understand this before you go on to the second part where we actually move files around and change some of the settings.

Most of the this document is primarily targeted towards users of Microsoft Windows, because Windows is by far the most complicated operating system in existence. Users of Unix/Linux based operating systems can easily adopt all the information here for their platforms without problems.

Part 1 - How it works

The most important things are

I will now try to explain how this all works together.

portable mode or permanent installation

Portable Mode means that all that is needed is contained in one folder which you can carry around on an usb drive and run it wherever you happen to be. Therefore TorChat (for windows) comes bundled with its own tor.exe which it will try to start and all settings and data files remain inside this folder. Nothing will be copied or installed outside this folder to the computer's hard drive. The windows version you can download is already preconfigured for Portable Mode out of the box. TorChat for *ix systems (including OS-X) has a little shell script "tor.sh" that will do exactly the same thing as the windows "tor.exe" by starting a second instance of the Tor that is already installed on this machine, but with a special TorChat configuration (torrc.txt). The only difference on *ix is that you will have to install Tor yourself in order to be able to use TorChat.

Then there is the Permanent Installation. TorChat can be installed to a read-only folder like c:\programs\ or /usr/* and all of it's data and configuration will be in %APPDATA%\torchat\ or ~/.torchat/ In This mode TorChat will create a copy of the "Tor" folder in the data directory and use that instead just as it would use it in portable mode. On *ix systems this Tor folder will contain the torrc.txt with the port settings for this profile and the tor.sh to start an already installed tor service with this settings. On Windows systems it will contain it's own tor.exe instead of the shell script.

Finally there is another variant of operation, the Client Mode This mode is only useful in rare special cases if you want to run TorChat over some already running (and correctly configured) Tor proxy in your network or on your machine. This mode is for experts only.

The next few sections will explain how the mode is selected and how this is related to the configuration files.

portable.txt

There is a file called portable.txt. It's contents are completely irrelevant, in fact it could be empty, only it's existance is an indicator wether TorChat should run in portable mode or not. If you delete this file, TorChat will store all it's data like the buddy-list and the configuration file in the user's home directory If the file portable.txt exists TorChat will look for all it's configuration and data in the same folder where torchat.exe (or .py on *ix systems) is located.

torchat.ini

torchat.ini will be automatically created at the first start of TorChat or whenever it has been deleted or moved and TorChat can not find it. Depending on wether the portable.txt is found or not TorChat will look for torchat.ini in the current directory or in the user's home directory. torchat.ini contains two sections [tor] and [tor_portable]. If TorChat was able to successfully start the bundled tor.exe (or the tor.sh script on *ix) the section [tor_portable] is used, else it will use the settings in [tor] and you will have to configure the settings of your tor service yourself including the hostname of the hidden service.

The folder Tor

If we are in portable mode (portable.txt) TorChat will use the the Tor folder that is in the TorChat directory and try to start Tor\tor.exe (or Tor/tor.sh) with the Tor configuration in Tor\torrc.txt.

If we are not in portable mode TorChat will look for this Tor folder in the user's data directory (~/.torchat or %APPDATA%\torchat) and start it's tor service from within there.

If you delete the tor.exe (or tor.sh on *ix) you can force TorChat into using an already installed Tor service on your network. This is the Client Mode. It is not recommended for normal users. TorChat will use the settings in [tor] instead of those in [tor_portable] and you must configure your Tor service manually and find the correct hostname (.onion address) and put it into torchat.ini yourself!

Summary

The whole thing could also be explained by some piece of pseudo-code:

    if found portable.txt:
        -> Portable Mode
        -> use current folder for all data
    else:
        -> Permanent Installation
        -> use home folder for all data
        
    if can start tor.exe (or tor.sh):
        -> normal mode of operation
        -> use settings in torchat.ini/[tor_portable] and torrc.txt
    else:
        -> Client Mode
        -> use settings in [tor]
        -> all must be configured manually!

  

or if you are more attracted to tables we can summarize it in a tabular way:

portable.txt Tor/tor.exe what will happen
present present and working Portable Mode
all data and config in installation folder
settings in [tor_portable] are used
missing present and working (in profile folder) Permanent Installation
all data and config in home folder (~/.torchat or %APPDATA%\torchat)
settings in [tor_portable] are used
present missing Client Mode (portable)
like Portable Mode
but settings in [tor] are used.
Only experienced users should use this, all has to be configured manually
missing missing Client mode (permanent installation)
like Permanent Installaton
but settings in [tor] are used.
Only experienced users should use this, all has to be configured manually

The configuration of Tor

Normal operation, Portable Mode

In this Mode normally you don't have to configure anything. The Tor binary which is bundled with TorChat will be started with /Tor/torrc.txt as it's configuration file. Out of the box it is configured to listen on port 11109 (socks) and port 11119 (control) and to forward the hidden service port 11009 to localhost:11009. Note that this are the same port numbers as configured in torchat.ini section [tor_portable]

The hidden service directory is hidden_service inside the Tor folder. You may not change this.

If you plan to run a second portable instance on the same computer you will have to change all this port numbers and also the corresponding settings in torchat.ini section [tor_portable] and [client] in the second copy of the whole TorChat folder.

Normal operation, Permanent Installation

Everything is like in portable mode except for the location of the configuration files torchat.ini and Tor/torrx.txt. They are inside your profile folder (%APPDATA%\torchat\ on windows and ~/.torchat/ on *ix systems)

Additionally you can use different profiles, if you start torchat with the name of a profile at the commandline. If you start TorChat with the commandline

   torchat HansFranz
  

it will use the folder ~/.torchat_HansFranz/ or %APPDATA%\torchat_HansFranz\ and have a copy of it's Tor folder in this directory, so you can change the port numbers only for this profile and will be able to run as much different profiles on the same machine as you want as long as you avoid conflicting port numbers.

Client Mode (not recommended)

You need to configure a hidden service in your existing Tor installation. To do this create a folder somewhere on your harddisk. For simplicity we just assume the full path to this folder is

   c:\foo\bar\onion1
  

put the following lines into your torrc:

   HiddenServiceDir c:\foo\bar\onion1
   HiddenServicePort 11009 localhost:11009
  

Now restart your Tor service, make sure it runs without errors. While Tor is now running again in the background as normal, have a look into our hidden service folder we just created. There should be two files (which have been created by Tor). One is named private_key and one is named hostname. Inside this file (open it with notepad) you will find your .onion address. It will be something like 16crypticletters.onion. Later on in this document i will refer to this 16 cryptic letters as your .onion address. Put this .onion address (without the .onion at the end) into your torchat.ini under own_hostname or it will not work. Otherwise TorChat has no way of finding out what his own hidden hostname is.

Note: In the example above we have forwarded the hidden service 11009 to the local address localhost, port 11009. The first 11009 is the port "inside" the Tor network, never change this.

The configuration of TorChat

Torchat ist configured with torchat.ini. Where this file is located depends on the mode (portable or permanent, see above). Two sections in this configuration file are of interest here: [tor_portable] and [client].

The options in [tor_portable] tell TorChat how to reach your tor proxy. They must correspond to SocksPort and ControlPort in the torrc.txt.

The options in [client] tell TorChat where to listen for incoming connections. They correspond to the last part of the HiddenServicePort setting in your torrc.

If you are running in Client Mode (delete tor.exe or tor.sh), which is not recommended for unexperienced users, then the settings in [tor] are used instead of those in [tor_portable]. In this mode you are rsponsable for configuring a hidden service manually and finding out the correct setting for own_hostname yourself, which otherwise would be done automatically.

Part 2 - Some common scenarios

Now you have learned enough to actually make changes to the configuration. Following are a few common scenarios and how to configure them

A second instance in portable mode

I recommend that you start experimenting with this scenario until you feel confident with all the settings. You can always start out with a fresh copy of the bin folder if you think you have screwed it all up, you don't need to make any changes to files or configurations outside this folder. The portable mode configuration is a great place to get used to the Tor configuration without the danger of screwing up your whole system.

Scenario: You already have TorChat running in portable mode and you want another instance of it running on the same computer with it's own settings and buddy list.

Step 1: Take your existing and already working copy and make a second copy of the bin folder. This will become your second Full Portable instance.

Step 2: Make this copy virgin again. Delete the file buddy-list.txt, go to the folder Tor, delete the two folders hidden_service and tor_data

Step 3: Configure the second Tor instance: We know that our ports 11009, 11109 and 11119 are already used so we think up 3 other numbers, say 22009 (TorChat), 22209 (Tor socks) and 22229 (Tor control). Our torrc.txt should now be altered so that the relevant lines look like this:

   SocksPort 22209
   SocksListenAddress 127.0.0.1
   ControlPort 22229
   HiddenServiceDir hidden_service
   HiddenServicePort 11009 127.0.0.1:22009
  

Note the last line: HiddenServicePort 11009 127.0.0.1:22009 The first number is the TorChat Port inside the hidden network, it is never seen from the outside. It must always be 11009 or TorChat would not work. Other clients will always try to connect to 11009. The second number is what is interesting for you, it is where you want this port to be forwarded to when it leaves the tunnel and enters the real world on your machine.

Step 4: The configuration of the second TorChat instance. Open torchat.ini with your text editor and change the relevant lines so that they look like below (note that the settings in [tor] are not relevant in Full Portable Mode):

   [tor_portable]
   tor_server_control_port = 22229
   tor_server_socks_port = 22209
   tor_server = 127.0.0.1

   [client]
   own_hostname = xxxxxxxxxxxxxxxx
   listen_interface = 127.0.0.1
   listen_port = 22009
  

The setting own_hostname can be left alone. it will be updated automatically. In Full Portble Mode TorChat will look into the hostname file, extract the hostname from it and automatically fill in the correct value.

Step 5: Try it out! It is time to start your second copy of TorChat. It should start with an empty buddy list with only the newly generated unique hostname as "myself" on it. Remember that it can take some time until the myself-icon will become green.

If it doesn't become green after more than 15 minutes then there is something wrong. If all your contacts get stuck in the state with blue earth symbol and never turn green, then this is a sign that outgoing connections work, but incoming connections don't work. In this case make sure that HiddenServicePort in torrc.txt and listen_port in torchat.ini are configured correctly.

A permanent installation with more than one profile

There is no windows installer yet, so if you are on windows, please always use portable mode instead and follow the instructions above.

If you have installed the .deb package on debian, ubuntu or similar operating systems, and started TorChat for the first time then there sould be a folder ~/.torchat/ in your home directory. Inside this folder there is your torchat.ini and another folder 'Tor' with torrc.txt

Now quit this instance of TorChat. Never quit TorChat by hitting Ctrl-C in the terminal, always use "quit" from the menu, because TorChat must be able to properly stop it's child process (tor.sh with tor) or you will have a tor process hanging around that will still provide it's hidden service and is bound to the ports it was configured to use.

Open a commandline window and type for example (use whatever name you want):

   torchat JoeSixpack
  

TorChat will start again, but with a different ID and if you have a look into your home directory there will now be a second torchat folder named ~/.torchat_JoeSixpack. This is the profile folder of your alter ego Joe Sixpack, but if you try to start both instances at the same time it will complain, you need to edit two files to make it work.

See above under "A second instance in portable mode" and apply the steps 3 to 5 to one of the two profiles to make sure that no port numbers are used twice. This way you should be able to configure and run as many instances as you like.

Using your already installed Tor service

yet to be written...

More than one instance using the same Tor service

yet to be written...