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](http://developer.apple.com/technology/Xcode.html) (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 dependancies.
45 sudo port install tinc
47 Configuration files are located in /opt/local/etc/tinc.
49 Tinc can now be configured and executed.
52 ### Alternative Installation Methods
54 There are two alternative methods of getting tinc:
55 compiling it or downloading a precompiled binary.
56 The second option (download it) - is easier and faster way of
61 In the case of compiling tinc the following is required:
63 * [XCode](http://developer.apple.com/technology/Xcode.html)
64 * [LZO libraries](http://www.oberhumer.com/opensource/lzo/)
66 Before starting, create a new folder `tmp` in your home directory
67 and enter it (it can be any other location). From Terminal level it
68 can be done in the following way:
70 [[!img examples/osx-tmp.png]]
74 Download LZO (you can use `wget` or Safari to do it). I used LZO
75 version 2.03 ("lzo-2.03.tar.gz"). Using `wget:`
77 [[!img examples/osx/lzo1.png]]
79 Unpack it, enter the directory:
81 [[!img examples/osx/lzo2.png]]
83 And issue `configure/make:`
85 [[!img examples/osx/lzo3.png]]
87 If everything goes well, after a few minutes the operation will be
88 finished, execute make install using root rights (using `sudo`
91 [[!img examples/osx/lzo4.png]]
93 Having installed LZO, we can install tinc.
97 Download Tinc (again you can use `wget` or Safari to do it). I used
98 [Tinc version 1.0.9](/packages/tinc-1.0.9.tar.gz). Using the same approach as
99 before - download and extract it:
101 [[!img examples/osx/tinc1.png]]
103 Enter the directory, and execute configure, make, make install:
105 [[!img examples/osx/tinc2.png]]
107 Having installed Tinc, you can move to the [next section](#config).
111 Link: [tincd-1.0.9.zip](/packages/osx/tincd-1.0.9.zip). Please note that this archieve
112 provides only the executable and does not include any manual. Once
113 downloaded, place the extracted executable into `/usr/sbin/`.
117 Tinc on OS X looks for configuration files in `/usr/etc/tinc`. In
118 our case we will place configuration files in `~/Library/tinc/`.
119 Navigate to your home directory and create configuration folders
120 for your `company` (see manual for details). In my case it is
123 [[!img examples/osx/config1.png]]
125 For further steps the following assumptions are made: the server to
126 connect to has name `myserver` and the client we are configuring:
128 You will need to create the following files and folders within:
130 - [[tinc.conf|examples/osx/tinc.conf]]
131 - [[tinc-up|examples/osx/tinc-up]]
132 - [[tinc-down|examples/osx/tinc-down]]
133 - [[hosts/myserver|examples/osx/myserver]]
134 - [[hosts/myclient0|examples/osx/myclient0]]
136 The sample files contain necessary explanation to make it work.
137 Make sure `tinc-up` and `tinc-down` are executable:
139 [[!img examples/osx/config2.png]]
141 You will also need to generate pair of keys (private/public) for
142 your client. Do it only after the above files are configured
143 properly! You will be asked for locations of certain files. The
144 default locations are fine.
146 [[!img examples/osx/config3.png]]
148 Once you are done, copy `hosts/myclient0` file and place it on your
149 server in the same location (`hosts/myclient0`). At this stage your
150 client should be able to connect to the server.
154 To start tinc everything you need is to execute:
156 [[!img examples/osx/start1.png]]
158 Tincd will issue a notice once it is successfully connected. For
159 more details on the syntax check `tincd --help`.
160 To stop the client you can kill it be executing:
162 [[!img examples/osx/start2.png]]
164 ### Configuring tinc-up and tinc-down scripts
166 `tincd-up` and `tincd-down` are two files that tincd executes on
167 start of the service and on stop respectively. They are usually
168 used to notify system to use the vpn as a default gateway. The
169 files provided in the previous page are minimalistic and used only
170 to bring up and down the interface. If you would like to tunnel all
171 the traffic over vpn use the scripts provided below. You have to
172 modify them accordingly to your configuration. Please see the notes
175 - [[tinc-up|examples/osx/tinc-up-1]] (Advanced example)
176 - [[tinc-down|examples/osx/tinc-down-1]] (Advanced example)
178 Please remember to rename the files to `tinc-up` and `tinc-down`
179 respectively and place them in your configuration folder replacing
180 the two existing files (if applicable).
184 - Grzegorz Dymarek (gd58 (at) alumni . st-andrews . ac . uk)
185 - Mike Bentzen (mike (@) goodlook . com . au)