--- /dev/null
+[[!meta title="installing tinc on Mac OS/X"]]
+
+## Example: installing tinc on Mac OS/X
+
+This example shows how to install and configure tinc on Mac OS X.
+The following was tested on Leopard based system, however should be
+generalisable to other Apple systems as well.
+This document is intended to give a step-by-step instruction on how
+to install tinc and how to configure it to be used as a basic
+client for tinc server.
+
+[[!toc levels=3]]
+
+### Overview and assumptions
+
+The following documents is designed to allow you an easy and fast
+installation/configuration of tinc. It deals with the client side
+only and the assumption is that you have a tinc server configured
+and running properly.
+
+### Installing tinc
+
+There are two ways of getting tinc:
+compiling it or downloading a precompiled binary.
+The second option (download it) - is easier and faster way of
+getting tinc to work.
+
+#### Compile it
+
+In the case of compiling tinc the following is required:
+
+* [XCode](http://developer.apple.com/technology/Xcode.html) (requires
+ free online ADC Membership); it can also be obtained from original
+ OSX installation DVD
+* [LZO libraries](http://www.oberhumer.com/opensource/lzo/)
+
+It is expected that you know how to install XCode. Moreover, most
+of the operations will be carried using Terminal/Console and thus
+you should be comfortable using some basic commands.
+The general steps are as follows - install XCode, install LZO,
+install Tinc.
+
+Before starting, create a new folder `tmp` in your home directory
+and enter it (it can be any other location). From Terminal level it
+can be done in the following way:
+
+[[!img examples/osx-tmp.png]]
+
+##### LZO
+
+Download LZO (you can use `wget` or Safari to do it). I used LZO
+version 2.03 ("lzo-2.03.tar.gz"). Using `wget:`
+
+[[!img examples/osx/lzo1.png]]
+
+Unpack it, enter the directory:
+
+[[!img examples/osx/lzo2.png]]
+
+And issue `configure/make:`
+
+[[!img examples/osx/lzo3.png]]
+
+If everything goes well, after a few minutes the operation will be
+finished, execute make install using root rights (using `sudo`
+prefix):
+
+[[!img examples/osx/lzo4.png]]
+
+Having installed LZO, we can install tinc.
+
+##### Tinc
+
+Download Tinc (again you can use `wget` or Safari to do it). I used
+Tinc version 1.09 ("tinc-1.09.tar.gz"). Using the same approach as
+before - download and extract it:
+
+[[!img examples/osx/tinc1.png]]
+
+Enter the directory, and execute configure, make, make install:
+
+[[!img examples/osx/tinc2.png]]
+
+Having installed Tinc, you can move to the [next section](#config).
+
+#### Download it
+
+Link: [tincd](tincd-1.0.9.zip). Please note that this archieve
+provides only the executable and does not include any manual. Once
+downloaded, place the extracted executable into `/usr/sbin/`.
+
+### Configuring tinc
+
+Tinc on OS X looks for configuration files in `/usr/etc/tinc`. In
+our case we will place configuration files in `~/Library/tinc/`.
+Navigate to your home directory and create configuration folders
+for your `company` (see manual for details). In my case it is
+called `myvpn`.
+
+[[!img examples/osx/config1.png]]
+
+For further steps the following assumptions are made: the server to
+connect to has name `myserver` and the client we are configuring:
+`myclient0`.
+You will need to create the following files and folders within:
+
+- [[tinc.conf|examples/osx/tinc.conf]]
+- [[tinc-up|examples/osx/tinc-up]]
+- [[tinc-down|examples/osx/tinc-down]]
+- [[hosts/myserver|examples/osx/myserver]]
+- [[hosts/myclient0|examples/osx/myclient0]]
+
+The sample files contain necessary explanation to make it work.
+Make sure `tinc-up` and `tinc-down` are executable:
+
+[[!img examples/osx/config2.png]]
+
+You will also need to generate pair of keys (private/public) for
+your client. Do it only after the above files are configured
+properly! You will be asked for locations of certain files. The
+default locations are fine.
+
+[[!img examples/osx/config3.png]]
+
+Once you are done, copy `hosts/myclient0` file and place it on your
+server in the same location (`hosts/myclient0`). At this stage your
+client should be able to connect to the server.
+
+### Starting tinc
+
+To start tinc everything you need is to execute:
+
+[[!img examples/osx/start1.png]]
+
+Tincd will issue a notice once it is successfully connected. For
+more details on the syntax check `tincd --help`.
+To stop the client you can kill it be executing:
+
+[[!img examples/osx/start2.png]]
+
+### Configuring tinc-up and tinc-down scripts
+
+`tincd-up` and `tincd-down` are two files that tincd executes on
+start of the service and on stop respectively. They are usually
+used to notify system to use the vpn as a default gateway. The
+files provided in the previous page are minimalistic and used only
+to bring up and down the interface. If you would like to tunnel all
+the traffic over vpn use the scripts provided below. You have to
+modify them accordingly to your configuration. Please see the notes
+inside them:
+
+- [[tinc-up|examples/osx/tinc-up-1]] (Advanced example)
+- [[tinc-down|examples/osx/tinc-down-1]] (Advanced example)
+
+Please remember to rename the files to `tinc-up` and `tinc-down`
+respectively and place them in your configuration folder replacing
+the two existing files (if applicable).
+
+* * * * *
+
+Grzegorz Dymarek (gd58 (at) alumni . st-andrews . ac . uk)
projects / wiki / blobdiff