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](http://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*:
62 <?xml version="1.0" encoding="UTF-8"?>
63 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
69 <string>tinc.myvpn</string>
70 <key>ProgramArguments</key>
72 <string>/opt/local/tinc/sbin/tincd</string>
74 <string>myvpn</string>
80 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:
82 launchctl unload -w /Library/LaunchDaemons/myvpn.tinc.plist
84 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:
86 launchctl load -w /Library/LaunchDaemons/myvpn.tinc.plist
88 This removes the *disabled* key from the file and starts tincd.
92 launchctl stop tinc.myvpn
94 To list all services monitored by launchd:
98 If tinc has been configured with launchd, you will see tinc.myvpn listed with a process id.
101 #### Handle standby and other network interrupts
103 Tinc automatically tries to reconnect, but this takes time and the longer there
104 is no connection, the longer tinc waits to try and reconnect again. A small
105 tool is available at https://gitorious.org/tinc-on-osx/networknotify which will
106 signal tinc to reconnect when the network connection is available. It uses OS
107 X its network reachability framework and can be build using Xcode.
112 ### Alternative Installation Methods
114 There are two alternative methods of getting tinc:
115 compiling it or downloading a precompiled binary.
116 The second option (download it) - is easier and faster way of
117 getting tinc to work.
121 In the case of compiling tinc the following is required:
123 * [XCode](http://developer.apple.com/xcode/)
124 * [LZO libraries](http://www.oberhumer.com/opensource/lzo/)
126 Before starting, create a new folder `tmp` in your home directory
127 and enter it (it can be any other location). From Terminal level it
128 can be done in the following way:
130 [[!img examples/osx/tmp.png]]
134 Download LZO (you can use `wget` or Safari to do it). I used LZO
135 version 2.03 ("lzo-2.03.tar.gz"). Using `wget:`
137 [[!img examples/osx/lzo1.png]]
139 Unpack it, enter the directory:
141 [[!img examples/osx/lzo2.png]]
143 And issue `configure/make:`
145 [[!img examples/osx/lzo3.png]]
147 If everything goes well, after a few minutes the operation will be
148 finished, execute make install using root rights (using `sudo`
151 [[!img examples/osx/lzo4.png]]
153 Having installed LZO, we can install tinc.
157 Download Tinc (again you can use `wget` or Safari to do it). I used
158 [Tinc version 1.0.9](/packages/tinc-1.0.9.tar.gz). Using the same approach as
159 before - download and extract it:
161 [[!img examples/osx/tinc1.png]]
163 Enter the directory, and execute configure, make, make install:
165 [[!img examples/osx/tinc2.png]]
167 Having installed Tinc, you can move to the [next section](#config).
171 Link: [tincd-1.0.9.zip](/packages/osx/tincd-1.0.9.zip). Please note that this archieve
172 provides only the executable and does not include any manual. Once
173 downloaded, place the extracted executable into `/usr/sbin/`.
177 Tinc on OS X looks for configuration files in `/usr/etc/tinc`. In
178 our case we will place configuration files in `~/Library/tinc/`.
179 Navigate to your home directory and create configuration folders
180 for your `company` (see manual for details). In my case it is
183 [[!img examples/osx/config1.png]]
185 For further steps the following assumptions are made: the server to
186 connect to has name `myserver` and the client we are configuring:
188 You will need to create the following files and folders within:
190 - [[tinc.conf|examples/osx/tinc.conf]]
191 - [[tinc-up|examples/osx/tinc-up]]
192 - [[tinc-down|examples/osx/tinc-down]]
193 - [[hosts/myserver|examples/osx/myserver]]
194 - [[hosts/myclient0|examples/osx/myclient0]]
196 The sample files contain necessary explanation to make it work.
197 Make sure `tinc-up` and `tinc-down` are executable:
199 [[!img examples/osx/config2.png]]
201 You will also need to generate pair of keys (private/public) for
202 your client. Do it only after the above files are configured
203 properly! You will be asked for locations of certain files. The
204 default locations are fine.
206 [[!img examples/osx/config3.png]]
208 Once you are done, copy `hosts/myclient0` file and place it on your
209 server in the same location (`hosts/myclient0`). At this stage your
210 client should be able to connect to the server.
214 To start tinc everything you need is to execute:
216 [[!img examples/osx/start1.png]]
218 Tincd will issue a notice once it is successfully connected. For
219 more details on the syntax check `tincd --help`.
220 To stop the client you can kill it be executing:
222 [[!img examples/osx/start2.png]]
224 ### Configuring tinc-up and tinc-down scripts
226 `tincd-up` and `tincd-down` are two files that tincd executes on
227 start of the service and on stop respectively. They are usually
228 used to notify system to use the vpn as a default gateway. The
229 files provided in the previous page are minimalistic and used only
230 to bring up and down the interface. If you would like to tunnel all
231 the traffic over vpn use the scripts provided below. You have to
232 modify them accordingly to your configuration. Please see the notes
235 - [[tinc-up|examples/osx/tinc-up-1]] (Advanced example)
236 - [[tinc-down|examples/osx/tinc-down-1]] (Advanced example)
238 Please remember to rename the files to `tinc-up` and `tinc-down`
239 respectively and place them in your configuration folder replacing
240 the two existing files (if applicable).
244 - Mike Bentzen (mike (at) bentzen . com . au)
245 - Grzegorz Dymarek (gd58 (at) alumni . st-andrews . ac . uk)