X-Git-Url: https://tinc-vpn.org/git/browse?a=blobdiff_plain;f=examples%2Fosx-install.mdwn;h=adbf8536d3134cd659f8d4efe941b2fc07834296;hb=HEAD;hp=abde57102c01d5ae9a235cebf3be1229f569c5ab;hpb=7c74a57cd95cfc0358fdd5980d9170ea16751dfb;p=wiki diff --git a/examples/osx-install.mdwn b/examples/osx-install.mdwn index abde571..5a4f7fe 100644 --- a/examples/osx-install.mdwn +++ b/examples/osx-install.mdwn @@ -3,7 +3,7 @@ ## 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 +The following was tested on Snow 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 @@ -20,7 +20,100 @@ and running properly. ### Installing tinc -There are two ways of getting tinc: +The recommended methods to install tinc is by using the macports port system. +The MacPorts Project is an open-source community initiative to design an easy-to-use system for compiling, installing, and upgrading either command-line, X11 or Aqua based open-source software on the MacOSX operating system. +Macports is recommended because it does not modify your system files. It keeps itself separate from your system. + +#### MacPorts + +XCode is a required prerequisite. It must be installed before installing Macports. +Download and install the Macports system from MacForge. + +* [XCode](https://developer.apple.com/xcode/) (requires + free online ADC Membership); it can also be obtained from original + OSX installation DVD +* [Macports](http://www.macports.org/install.php) + +After Macports is installed, close and reopen your terminal. +Update the ports system and ports list. + + sudo port selfupdate + sudo port sync + +This command will install tinc and all the necessary dependencies. + + sudo port install tinc + +Configuration files are located in /opt/local/etc/tinc. + +Tinc can now be configured and executed. + + +### Start tinc automatically on system boot + +[launchd](https://en.wikipedia.org/wiki/Launchd) is a system for monitoring services and make sure services are started if certain conditions are met. This system is available on OS X 10.5 and later versions. + +To use launchd, you have to create a property-list file for tinc and put it under /Library/LaunchDaemons/ + +The following example is a plist file for the tinc network name: myvpn + +*/Library/LaunchDaemons/myvpn.tinc.plist*: + +``` + + + + + KeepAlive + + Label + tinc.myvpn + ProgramArguments + + /opt/local/tinc/sbin/tincd + -n + myvpn + -D + + + +``` + +This will configure tincd to start the myvpn configuration in the foreground (-D). If tincd is started as background daemon, launchd will not function correctly with tinc. Launchd will directly start tincd if this file is found. The `KeepAlive` element will ensure that tincd is always running, and to be restarted if it stops. To stop tincd, use the *launchctl* command. Some commands to remember are: + + launchctl unload -w /Library/LaunchDaemons/myvpn.tinc.plist + +This adds a *disabled* key to the file and stops tincd. The disabled key ensure that launchd will not start tincd anymore. The inverse operation is: + + launchctl load -w /Library/LaunchDaemons/myvpn.tinc.plist + +This removes the *disabled* key from the file and starts tincd. + +To stop tinc: + + launchctl stop tinc.myvpn + +To list all services monitored by launchd: + + launchctl list + +If tinc has been configured with launchd, you will see tinc.myvpn listed with a process id. + + +#### Handle standby and other network interrupts + +Tinc automatically tries to reconnect, but this takes time and the longer there +is no connection, the longer tinc waits to try and reconnect again. A small +tool is available at https://gitorious.org/tinc-on-osx/networknotify which will +signal tinc to reconnect when the network connection is available. It uses OS +X its network reachability framework and can be build using Xcode. + +--- + + +### Alternative Installation Methods + +There are two alternative methods 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. @@ -29,22 +122,14 @@ getting tinc to work. 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 +* [XCode](https://developer.apple.com/xcode/) * [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]] +[[!img examples/osx/tmp.png]] ##### LZO @@ -72,7 +157,7 @@ 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 +[Tinc version 1.0.9](/packages/tinc-1.0.9.tar.gz). Using the same approach as before - download and extract it: [[!img examples/osx/tinc1.png]] @@ -83,12 +168,6 @@ Enter the directory, and execute configure, make, make install: 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 @@ -158,4 +237,6 @@ the two existing files (if applicable). * * * * * -Grzegorz Dymarek (gd58 (at) alumni . st-andrews . ac . uk) +- Mike Bentzen (mike (at) bentzen . com . au) +- Grzegorz Dymarek (gd58 (at) alumni . st-andrews . ac . uk) +- wizztick