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.
104 ### Alternative Installation Methods
106 There are two alternative methods of getting tinc:
107 compiling it or downloading a precompiled binary.
108 The second option (download it) - is easier and faster way of
109 getting tinc to work.
113 In the case of compiling tinc the following is required:
115 * [XCode](http://developer.apple.com/xcode/)
116 * [LZO libraries](http://www.oberhumer.com/opensource/lzo/)
118 Before starting, create a new folder `tmp` in your home directory
119 and enter it (it can be any other location). From Terminal level it
120 can be done in the following way:
122 [[!img examples/osx/tmp.png]]
126 Download LZO (you can use `wget` or Safari to do it). I used LZO
127 version 2.03 ("lzo-2.03.tar.gz"). Using `wget:`
129 [[!img examples/osx/lzo1.png]]
131 Unpack it, enter the directory:
133 [[!img examples/osx/lzo2.png]]
135 And issue `configure/make:`
137 [[!img examples/osx/lzo3.png]]
139 If everything goes well, after a few minutes the operation will be
140 finished, execute make install using root rights (using `sudo`
143 [[!img examples/osx/lzo4.png]]
145 Having installed LZO, we can install tinc.
149 Download Tinc (again you can use `wget` or Safari to do it). I used
150 [Tinc version 1.0.9](/packages/tinc-1.0.9.tar.gz). Using the same approach as
151 before - download and extract it:
153 [[!img examples/osx/tinc1.png]]
155 Enter the directory, and execute configure, make, make install:
157 [[!img examples/osx/tinc2.png]]
159 Having installed Tinc, you can move to the [next section](#config).
163 Link: [tincd-1.0.9.zip](/packages/osx/tincd-1.0.9.zip). Please note that this archieve
164 provides only the executable and does not include any manual. Once
165 downloaded, place the extracted executable into `/usr/sbin/`.
169 Tinc on OS X looks for configuration files in `/usr/etc/tinc`. In
170 our case we will place configuration files in `~/Library/tinc/`.
171 Navigate to your home directory and create configuration folders
172 for your `company` (see manual for details). In my case it is
175 [[!img examples/osx/config1.png]]
177 For further steps the following assumptions are made: the server to
178 connect to has name `myserver` and the client we are configuring:
180 You will need to create the following files and folders within:
182 - [[tinc.conf|examples/osx/tinc.conf]]
183 - [[tinc-up|examples/osx/tinc-up]]
184 - [[tinc-down|examples/osx/tinc-down]]
185 - [[hosts/myserver|examples/osx/myserver]]
186 - [[hosts/myclient0|examples/osx/myclient0]]
188 The sample files contain necessary explanation to make it work.
189 Make sure `tinc-up` and `tinc-down` are executable:
191 [[!img examples/osx/config2.png]]
193 You will also need to generate pair of keys (private/public) for
194 your client. Do it only after the above files are configured
195 properly! You will be asked for locations of certain files. The
196 default locations are fine.
198 [[!img examples/osx/config3.png]]
200 Once you are done, copy `hosts/myclient0` file and place it on your
201 server in the same location (`hosts/myclient0`). At this stage your
202 client should be able to connect to the server.
206 To start tinc everything you need is to execute:
208 [[!img examples/osx/start1.png]]
210 Tincd will issue a notice once it is successfully connected. For
211 more details on the syntax check `tincd --help`.
212 To stop the client you can kill it be executing:
214 [[!img examples/osx/start2.png]]
216 ### Configuring tinc-up and tinc-down scripts
218 `tincd-up` and `tincd-down` are two files that tincd executes on
219 start of the service and on stop respectively. They are usually
220 used to notify system to use the vpn as a default gateway. The
221 files provided in the previous page are minimalistic and used only
222 to bring up and down the interface. If you would like to tunnel all
223 the traffic over vpn use the scripts provided below. You have to
224 modify them accordingly to your configuration. Please see the notes
227 - [[tinc-up|examples/osx/tinc-up-1]] (Advanced example)
228 - [[tinc-down|examples/osx/tinc-down-1]] (Advanced example)
230 Please remember to rename the files to `tinc-up` and `tinc-down`
231 respectively and place them in your configuration folder replacing
232 the two existing files (if applicable).
236 - Mike Bentzen (mike (at) bentzen . com . au)
237 - Grzegorz Dymarek (gd58 (at) alumni . st-andrews . ac . uk)