www.tinc-vpn.org Git - wiki/blob - examples/osx-install.mdwn

   1 [[!meta title="installing tinc on Mac OS/X"]]
   2
   3 ## Example: installing tinc on Mac OS/X
   4
   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.
  11
  12 [[!toc levels=3]]
  13
  14 ### Overview and assumptions
  15
  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
  19 and running properly.
  20
  21 ### Installing tinc
  22
  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.
  26
  27 #### MacPorts
  28
  29 XCode is a required prerequisite. It must be installed before installing Macports.
  30 Download and install the Macports system from MacForge.
  31
  32 * [XCode](http://developer.apple.com/technology/Xcode.html) (requires
  33   free online ADC Membership); it can also be obtained from original
  34   OSX installation DVD
  35 * [Macports](http://www.macports.org/install.php)
  36
  37 After Macports is installed, close and reopen your terminal.
  38 Update the ports system and ports list.
  39
  40     sudo port selfupdate
  41     sudo port sync
  42
  43 This command will install tinc and all the necessary dependancies.
  44
  45     sudo port install tinc
  46
  47 Configuration files are located in /opt/local/etc/tinc.
  48
  49 Tinc can now be configured and executed.
  50
  51
  52 ### Alternative Installation Methods
  53
  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
  57 getting tinc to work.
  58
  59 #### Compile it
  60
  61 In the case of compiling tinc the following is required:
  62
  63 * [XCode](http://developer.apple.com/technology/Xcode.html)
  64 * [LZO libraries](http://www.oberhumer.com/opensource/lzo/)
  65
  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:
  69
  70 [[!img examples/osx-tmp.png]]
  71
  72 ##### LZO
  73
  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:`
  76
  77 [[!img examples/osx/lzo1.png]]
  78
  79 Unpack it, enter the directory:
  80
  81 [[!img examples/osx/lzo2.png]]
  82
  83 And issue `configure/make:`
  84
  85 [[!img examples/osx/lzo3.png]]
  86
  87 If everything goes well, after a few minutes the operation will be
  88 finished, execute make install using root rights (using `sudo`
  89 prefix):
  90
  91 [[!img examples/osx/lzo4.png]]
  92
  93 Having installed LZO, we can install tinc.
  94
  95 ##### Tinc
  96
  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:
 100
 101 [[!img examples/osx/tinc1.png]]
 102
 103 Enter the directory, and execute configure, make, make install:
 104
 105 [[!img examples/osx/tinc2.png]]
 106
 107 Having installed Tinc, you can move to the [next section](#config).
 108
 109 #### Download it
 110
 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/`.
 114
 115 ### Configuring tinc
 116
 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
 121 called `myvpn`.
 122
 123 [[!img examples/osx/config1.png]]
 124
 125 For further steps the following assumptions are made: the server to
 126 connect to has name `myserver` and the client we are configuring:
 127 `myclient0`.
 128 You will need to create the following files and folders within:
 129
 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]]
 135
 136 The sample files contain necessary explanation to make it work.
 137 Make sure `tinc-up` and `tinc-down` are executable:
 138
 139 [[!img examples/osx/config2.png]]
 140
 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.
 145
 146 [[!img examples/osx/config3.png]]
 147
 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.
 151
 152 ### Starting tinc
 153
 154 To start tinc everything you need is to execute:
 155
 156 [[!img examples/osx/start1.png]]
 157
 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:
 161
 162 [[!img examples/osx/start2.png]]
 163
 164 ### Configuring tinc-up and tinc-down scripts
 165
 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
 173 inside them:
 174
 175 - [[tinc-up|examples/osx/tinc-up-1]] (Advanced example)
 176 - [[tinc-down|examples/osx/tinc-down-1]] (Advanced example)
 177
 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).
 181
 182 * * * * *
 183
 184 - Grzegorz Dymarek (gd58 (at) alumni . st-andrews . ac . uk)
 185 - Mike Bentzen (mike (@) goodlook . com . au)