X-Git-Url: https://www.tinc-vpn.org/git/browse?a=blobdiff_plain;f=examples%2Fosx-install.mdwn;h=adbf8536d3134cd659f8d4efe941b2fc07834296;hb=8a83924a8938c2d85cc26366f681b0e7169bb0af;hp=abde57102c01d5ae9a235cebf3be1229f569c5ab;hpb=7c74a57cd95cfc0358fdd5980d9170ea16751dfb;p=wiki diff --git a/examples/osx-install.mdwn b/examples/osx-install.mdwn index abde571..adbf853 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,98 @@ 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 +120,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 +155,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 +166,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 +235,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