diff --git a/torchat/doc/howto_mac_osx.html b/torchat/doc/howto_mac_osx.html deleted file mode 100644 index e69de29b..00000000 diff --git a/torchat/doc/howto_mac_osx.md b/torchat/doc/howto_mac_osx.md new file mode 100644 index 00000000..26363600 --- /dev/null +++ b/torchat/doc/howto_mac_osx.md @@ -0,0 +1,211 @@ +# Installation / Usage Instructions for TorChat on Mac OS X # + +***WARNING: THESE INSTRUCTIONS CURRENTLY HAVE BEEN TESTED ONLY ON MAC OS X + VERSION 10.8. ALL OTHER VERSIONS USE CAUTION.*** + +## Download and Install Tor ## + +Unfortunately, TorChat currently requires a `tor` executable in order to +function. This severely complicates the install, as the Tor project +tries to helpfully package Tor into a one-stop bundle for browsing the +web. + +There are three ways in which to install Tor on Mac OS X: downloading +a pre-built image from upstream TorProject, installing through +[MacPorts](https://www.macports.org/), or building from upstream +TorProject source. + +### Web Package Download ### + +If you're not running MacPorts (if you don't know what that is, you're +not running it), go +[here](https://www.torproject.org/download/download.html.en#apple) and +download either the i686 version (32-bit) or x86_64 (64-bit) version. +If you're not sure which one you need, go with the i686 (32-bit) +version. + +This will create a file in your downloads folder with a name like +**TorBrowser-2.3.25-10-osx-x86_64-en-US.zip**. If it doesn't create +an application with a name like **TorBrowser_en-US** as well, +double-click on the aforementioned file. An application named +**TorBrowser_en-US** should now appear. Move the **TorBrowser_en-US** +file into your Applications folder. + +The key to installing this way is that there is a `tor` executable +within the **TorBrowser_en-US** application. + +### MacPorts ### + +If you already have MacPorts installed, you can simply use the command: + + $ sudo port install tor torsocks + +and Tor will be installed, regardless of platform. + +This method creates a `tor` executable wherever your MacPorts is set +to install to (typically */opt/local/tor*). + +### Building from Upstream Source ### + +Source can be found +[here](https://www.torproject.org/download/download.html.en#source). +I recommend using the stable version. Build instructions can also be +found in that location. + +## Download and Install Python 2.x ## + +If you're using Mac OS X 10.8, you're in luck! Python 2.7 comes by +default. + +TODO: other versions of Mac OS X. Need at least Python 2.6 for +wxPython (unless MacPorts deals with earlier versions). + +## Download and Install wxPython 2.x ## + +Which wxPython you use will depend on which Python you are using. If +you installed Python from MacPorts, you should also install wxPython +from MacPorts; if you downloaded a binary of Python or used the +built-in Mac OS Python, you should download a binary of wxPython; and +if you want to build things from source, follow the instructions below. + +### Download a Pre-Built Binary ### + +Pre-built binaries can be found +[here](http://wxpython.org/download.php#stable). I cannot think of a +reason to use the binaries with "ansi" in their names. You should use +the version of wxPython appropriate to your Python installation (so, +for example, if you're using Python 2.7, you will want the link +**wxPython2.8-osx-unicode-py2.7**, or for Python 2.6, you would want +**wxPython2.8-osx-unicode-py2.6**). + +When you download the appropriate wxPython, a disk image should be +mounted (with a name like +**wxPython2.8-osx-unicode-2.8.12.1-universal-py27**). If it is not, +check your Downloads folder for a file with name like +**wxPython2.8-osx-unicode-2.8.12.1-universal-py2.7.dmg** and +double-click it. + +In the disk image, there will be an installer named something like +**wxPython2.8-osx-unicode-universal-py2.7.pkg**. Double-click it, and +the installer will begin. + +Click "Continue" to begin the installation, read the Software License +Agreement (click "Continue", then "Agree" when done if and only if you +agree to abide by it), then click "Install". (You may be prompted for +a password at this point.) When the installation finishes, click +"close" on the installer. + +### MacPorts ### + +(TODO: once bug is resolved, write up how to do this) + +### Building from Source ### + +It's important to note that the benefit here is not from building +Python binaries (because Python binaries aren't a thing), but from +building wxWidgets from source. Anyway, take a deep breath, +reconsider your life choices, and follow the instructions +[here](http://wxpython.org/builddoc.php). + +## TorChat ## + +For purposes of this guide, we will install torchat-source, which is a +source release of TorChat. It is also totally workable to substitute +another version from git instead; however, it is assumed that if you +do this, you know what you are doing. + +Releases can be downloaded +[here](https://github.com/prof7bit/TorChat/downloads). You probably +want to download the highest entry whose name resembles +**torchat-source-0.9.9.553.zip**. + +This will create a file in your Downloads folder with name something +like **torchat-source-0.9.9.553.zip**. If it does not also create a +folder with name like **torchat-source-0.9.9.553**, double click on +the aforementioned file and it should appear. + +Okay, so now we're going to launch TorChat. Take a deep breath, and +let's make a launcher. Open TextEdit (or the text editor of your +choice). Ensure the document is plain text by going to the "Format" +menu. If you see an option "Make Plain Text", choose it; otherwise, +your document is already plain text so don't select anything. Type +the following: + + #!/bin/bash + PATH=/Applications/TorBrowser_en-US.app/Contents/MacOS:$PATH + arch -i386 python ~/Downloads/torchat-source-*/src/torchat.py & + exit + +Be sure to leave a blank line at the end of the file, then save it on +the Desktop (or Applications folder or anywhere you like) with a +clever name (I like **TorChat Launcher**, myself). When saving, be +sure to uncheck the box that says "If no extension is provided, use +'.txt'.", and also ensure that there are no periods ('.') in the name +that you save it as. + +Select the file you just made in the finder. Then open +**Terminal.app** (it can be found in the **Utilities** folder in your +**Applications** folder). Type `chmod +x ` (with a space at the end) +and then, *before hitting enter*, drag your TorChat launcher into the +Terminal.app window. Then press the Return key. You should see the +icon of your launcher change in the Finder. + +Simply double-click on the launcher to launch TorChat. After a +moment, another window will open: your TorChat contact list! + +## Upgrading components ## + +All components of the setup we just made are upgradable. Here's how: + +### Tor ### + +If you installed Tor through the TorBrowser pre-built binary, update +as instructed by TorProject. Your TorChat launcher will continue to +work. + +If you installed Tor through MacPorts, `sudo port upgrade tor +torsocks` will automatically update you, and your TorChat launcher +will continue to work. + +If you built Tor from source, you will need to rebuild and re-install +to the same location you did initially in order for the TorChat +launcher to continue to work. + +### Python ### + +If you used built-in Python, Python will update through Software +Update/App Store. The launcher script will continue to function. + +If you installed Python from MacPorts, `sudo port upgrade outdated` +will automatically update you, and your TorChat launcher will continue +to work. + +If you downloaded a pre-built binary of Python, just download and run +the appropriate newer installer. As long as it installs to the same +location as it did the first time, your TorChat launcher will continue +to work. + +### wxPython ### + +If you downloaded a pre-built binary of wxPython, just download and +run the appropriate newer installer. As long as it installs to the +same location as it did the first time, your TorChat launcher will +continue to work. + +If you installed wxPython from MacPorts, `sudo port upgrade outdated` +will automatically update you, and your TorChat launcher will continue +to work. + +If you built wxPython from source, you will need to build the new +version and install it to the same location you did initially. If you +do so, your TorChat launcher will continue to work. + +### TorChat ### + +When a new TorChat is released, a new torchat-source entry will appear +on [the Downloads +page](https://github.com/prof7bit/TorChat/downloads). Before +downloading, remove the old torchat-source files from your Downloads +folder, then follow instructions as if you were installing TorChat +above. You do not need to recreate the launcher; it will continue to +work. diff --git a/torchat/doc/howto_second_instance.html b/torchat/doc/howto_second_instance.html index c26ad633..e9db4a44 100644 --- a/torchat/doc/howto_second_instance.html +++ b/torchat/doc/howto_second_instance.html @@ -9,7 +9,7 @@
This howto will not work with versions below 0.9.9.260 @@ -17,12 +17,12 @@
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. + things about addresses 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 + Most of 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. @@ -44,9 +44,9 @@
+
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 + which you can carry around on a 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 @@ -58,39 +58,39 @@
+
+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 + to a read-only folder like c:\programs\ or /usr/* and all of its 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 + tor service with these settings. On Windows systems it will contain its own tor.exe instead of the shell script. -
-- Finally there is another variant of operation, the Client Mode +
++ 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. -
+- 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 + There is a file called portable.txt. Its contents are completely + irrelevant, in fact it could be empty, only its existence is an + indicator whether TorChat should run in portable mode or not. If you delete + this file, TorChat will store all its 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 + its configuration and data in the same folder where torchat.exe (or .py on *ix systems) is located.
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 + Depending on whether 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 + 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] @@ -112,17 +112,17 @@
- If we are in portable mode (portable.txt) TorChat will use the the Tor + If we are in portable mode (if portable.txt was found) TorChat will use 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 + 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 its tor service from within there.
- If you delete the tor.exe (or tor.sh on *ix) you can force TorChat into + 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 @@ -142,7 +142,7 @@
or if you are more attracted to tables we can summarize it in a tabular way: @@ -187,7 +186,7 @@
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 + as its 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] + service port 11009 to localhost:11009. Note that these are the same + port numbers as configured in torchat.ini section [tor_portable].
- The hidden service directory is hidden_service
+ 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 + you will have to change all the port numbers and also the corresponding settings in torchat.ini section [tor_portable] and [client] in the second copy of the whole TorChat folder.
@@ -227,15 +226,15 @@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 + 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 + and have a copy of its Tor folder in this directory, so you can change the + port numbers only for this profile and will be able to run as many different profiles on the same machine as you want as long as you avoid conflicting port numbers.
@@ -256,13 +255,13 @@- Now restart your Tor service, make sure it runs without errors. While Tor is + Now restart your Tor service, make sure it runs without errors. When 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. + 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. @@ -276,7 +275,7 @@
- Torchat ist configured with torchat.ini. Where this file is located depends + Torchat is 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].
@@ -292,17 +291,17 @@
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
+ not recommended for inexperienced users, then the settings in [tor] are
+ used instead of those in [tor_portable]. In this mode you are responsible
for configuring a hidden service manually and finding out the correct
- setting for own_hostname yourself, which otherwise would be done
+ setting for own_hostname yourself, which otherwise would be done
automatically.
Now you have learned enough to actually make changes to the configuration. - Following are a few common scenarios and how to configure them + Following are a few common scenarios and how to configure them.
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 + want another instance of it running on the same computer with its own settings and buddy list.
@@ -328,7 +327,7 @@
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 + 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 @@ -370,8 +369,8 @@
- The setting own_hostname can be left alone. it will be updated - automatically. In Full Portble Mode TorChat will look into the + The setting own_hostname can be left alone, it will be updated + automatically. In Full Portable Mode, TorChat will look into the hostname file, extract the hostname from it and automatically fill in the correct value.
@@ -379,11 +378,11 @@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 + something wrong. If all your contacts get stuck in the state with a 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 @@ -398,16 +397,16 @@
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 + operating systems, and started TorChat for the first time, then there + should 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 + the menu, because TorChat must be able to properly stop its 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 + that will still provide its hidden service and is bound to the ports it was configured to use.
@@ -435,13 +434,14 @@
- yet to be written... + yet to be written...
- yet to be written... + yet to be written...