X-Git-Url: https://tinc-vpn.org/git/browse?a=blobdiff_plain;f=examples%2Fosx-install.mdwn;fp=examples%2Fosx-install.mdwn;h=abde57102c01d5ae9a235cebf3be1229f569c5ab;hb=7c74a57cd95cfc0358fdd5980d9170ea16751dfb;hp=0000000000000000000000000000000000000000;hpb=f980b3945271b51a8a200c44b8d3e7d61d086bab;p=wiki diff --git a/examples/osx-install.mdwn b/examples/osx-install.mdwn new file mode 100644 index 0000000..abde571 --- /dev/null +++ b/examples/osx-install.mdwn @@ -0,0 +1,161 @@ +[[!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)