1 [[!meta title="installing tinc on Mac OS/X"]]
3 ## Example: installing tinc on Mac OS/X
5 This example shows how to install and configure tinc on Mac OS X.
6 The following was tested on Snow Leopard based system, however should be
7 generalisable to other Apple systems as well.
8 This document is intended to give a step-by-step instruction on how
9 to install tinc and how to configure it to be used as a basic
10 client for tinc server.
14 ### Overview and assumptions
16 The following documents is designed to allow you an easy and fast
17 installation/configuration of tinc. It deals with the client side
18 only and the assumption is that you have a tinc server configured
23 The recommended methods to install tinc is by using the macports port system.
24 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.
25 Macports is recommended because it does not modify your system files. It keeps itself separate from your system.
29 XCode is a required prerequisite. It must be installed before installing Macports.
30 Download and install the Macports system from MacForge.
32 * [XCode](https://developer.apple.com/xcode/) (requires
33 free online ADC Membership); it can also be obtained from original
35 * [Macports](http://www.macports.org/install.php)
37 After Macports is installed, close and reopen your terminal.
38 Update the ports system and ports list.
43 This command will install tinc and all the necessary dependencies.
45 sudo port install tinc
47 Configuration files are located in /opt/local/etc/tinc.
49 Tinc can now be configured and executed.
52 ### Start tinc automatically on system boot
54 [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.
56 To use launchd, you have to create a property-list file for tinc and put it under /Library/LaunchDaemons/
58 The following example is a plist file for the tinc network name: myvpn
60 */Library/LaunchDaemons/myvpn.tinc.plist*:
63 <?xml version="1.0" encoding="UTF-8"?>
64 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
70 <string>tinc.myvpn</string>
71 <key>ProgramArguments</key>
73 <string>/opt/local/tinc/sbin/tincd</string>
75 <string>myvpn</string>
82 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 `<key>KeepAlive</key>` 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:
84 launchctl unload -w /Library/LaunchDaemons/myvpn.tinc.plist
86 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:
88 launchctl load -w /Library/LaunchDaemons/myvpn.tinc.plist
90 This removes the *disabled* key from the file and starts tincd.
94 launchctl stop tinc.myvpn
96 To list all services monitored by launchd:
100 If tinc has been configured with launchd, you will see tinc.myvpn listed with a process id.
103 #### Handle standby and other network interrupts
105 Tinc automatically tries to reconnect, but this takes time and the longer there
106 is no connection, the longer tinc waits to try and reconnect again. A small
107 tool is available at https://gitorious.org/tinc-on-osx/networknotify which will
108 signal tinc to reconnect when the network connection is available. It uses OS
109 X its network reachability framework and can be build using Xcode.
114 ### Alternative Installation Methods
116 There are two alternative methods of getting tinc:
117 compiling it or downloading a precompiled binary.
118 The second option (download it) - is easier and faster way of
119 getting tinc to work.
123 In the case of compiling tinc the following is required:
125 * [XCode](https://developer.apple.com/xcode/)
126 * [LZO libraries](http://www.oberhumer.com/opensource/lzo/)
128 Before starting, create a new folder `tmp` in your home directory
129 and enter it (it can be any other location). From Terminal level it
130 can be done in the following way:
132 [[!img examples/osx/tmp.png]]
136 Download LZO (you can use `wget` or Safari to do it). I used LZO
137 version 2.03 ("lzo-2.03.tar.gz"). Using `wget:`
139 [[!img examples/osx/lzo1.png]]
141 Unpack it, enter the directory:
143 [[!img examples/osx/lzo2.png]]
145 And issue `configure/make:`
147 [[!img examples/osx/lzo3.png]]
149 If everything goes well, after a few minutes the operation will be
150 finished, execute make install using root rights (using `sudo`
153 [[!img examples/osx/lzo4.png]]
155 Having installed LZO, we can install tinc.
159 Download Tinc (again you can use `wget` or Safari to do it). I used
160 [Tinc version 1.0.9](/packages/tinc-1.0.9.tar.gz). Using the same approach as
161 before - download and extract it:
163 [[!img examples/osx/tinc1.png]]
165 Enter the directory, and execute configure, make, make install:
167 [[!img examples/osx/tinc2.png]]
169 Having installed Tinc, you can move to the [next section](#config).
173 Tinc on OS X looks for configuration files in `/usr/etc/tinc`. In
174 our case we will place configuration files in `~/Library/tinc/`.
175 Navigate to your home directory and create configuration folders
176 for your `company` (see manual for details). In my case it is
179 [[!img examples/osx/config1.png]]
181 For further steps the following assumptions are made: the server to
182 connect to has name `myserver` and the client we are configuring:
184 You will need to create the following files and folders within:
186 - [[tinc.conf|examples/osx/tinc.conf]]
187 - [[tinc-up|examples/osx/tinc-up]]
188 - [[tinc-down|examples/osx/tinc-down]]
189 - [[hosts/myserver|examples/osx/myserver]]
190 - [[hosts/myclient0|examples/osx/myclient0]]
192 The sample files contain necessary explanation to make it work.
193 Make sure `tinc-up` and `tinc-down` are executable:
195 [[!img examples/osx/config2.png]]
197 You will also need to generate pair of keys (private/public) for
198 your client. Do it only after the above files are configured
199 properly! You will be asked for locations of certain files. The
200 default locations are fine.
202 [[!img examples/osx/config3.png]]
204 Once you are done, copy `hosts/myclient0` file and place it on your
205 server in the same location (`hosts/myclient0`). At this stage your
206 client should be able to connect to the server.
210 To start tinc everything you need is to execute:
212 [[!img examples/osx/start1.png]]
214 Tincd will issue a notice once it is successfully connected. For
215 more details on the syntax check `tincd --help`.
216 To stop the client you can kill it be executing:
218 [[!img examples/osx/start2.png]]
220 ### Configuring tinc-up and tinc-down scripts
222 `tincd-up` and `tincd-down` are two files that tincd executes on
223 start of the service and on stop respectively. They are usually
224 used to notify system to use the vpn as a default gateway. The
225 files provided in the previous page are minimalistic and used only
226 to bring up and down the interface. If you would like to tunnel all
227 the traffic over vpn use the scripts provided below. You have to
228 modify them accordingly to your configuration. Please see the notes
231 - [[tinc-up|examples/osx/tinc-up-1]] (Advanced example)
232 - [[tinc-down|examples/osx/tinc-down-1]] (Advanced example)
234 Please remember to rename the files to `tinc-up` and `tinc-down`
235 respectively and place them in your configuration folder replacing
236 the two existing files (if applicable).
240 - Mike Bentzen (mike (at) bentzen . com . au)
241 - Grzegorz Dymarek (gd58 (at) alumni . st-andrews . ac . uk)