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 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 There are two ways of getting tinc:
  24 compiling it or downloading a precompiled binary.
  25 The second option (download it) - is easier and faster way of
  26 getting tinc to work.
  27
  28 #### Compile it
  29
  30 In the case of compiling tinc the following is required:
  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 * [LZO libraries](http://www.oberhumer.com/opensource/lzo/)
  36
  37 It is expected that you know how to install XCode. Moreover, most
  38 of the operations will be carried using Terminal/Console and thus
  39 you should be comfortable using some basic commands.
  40 The general steps are as follows - install XCode, install LZO,
  41 install Tinc.
  42
  43 Before starting, create a new folder `tmp` in your home directory
  44 and enter it (it can be any other location). From Terminal level it
  45 can be done in the following way:
  46
  47 [[!img examples/osx-tmp.png]]
  48
  49 ##### LZO
  50
  51 Download LZO (you can use `wget` or Safari to do it). I used LZO
  52 version 2.03 ("lzo-2.03.tar.gz"). Using `wget:`
  53
  54 [[!img examples/osx/lzo1.png]]
  55
  56 Unpack it, enter the directory:
  57
  58 [[!img examples/osx/lzo2.png]]
  59
  60 And issue `configure/make:`
  61
  62 [[!img examples/osx/lzo3.png]]
  63
  64 If everything goes well, after a few minutes the operation will be
  65 finished, execute make install using root rights (using `sudo`
  66 prefix):
  67
  68 [[!img examples/osx/lzo4.png]]
  69
  70 Having installed LZO, we can install tinc.
  71
  72 ##### Tinc
  73
  74 Download Tinc (again you can use `wget` or Safari to do it). I used
  75 Tinc version 1.09 ("tinc-1.09.tar.gz"). Using the same approach as
  76 before - download and extract it:
  77
  78 [[!img examples/osx/tinc1.png]]
  79
  80 Enter the directory, and execute configure, make, make install:
  81
  82 [[!img examples/osx/tinc2.png]]
  83
  84 Having installed Tinc, you can move to the [next section](#config).
  85
  86 #### Download it
  87
  88 Link: [tincd](tincd-1.0.9.zip). Please note that this archieve
  89 provides only the executable and does not include any manual. Once
  90 downloaded, place the extracted executable into `/usr/sbin/`.
  91
  92 ### Configuring tinc
  93
  94 Tinc on OS X looks for configuration files in `/usr/etc/tinc`. In
  95 our case we will place configuration files in `~/Library/tinc/`.
  96 Navigate to your home directory and create configuration folders
  97 for your `company` (see manual for details). In my case it is
  98 called `myvpn`.
  99
 100 [[!img examples/osx/config1.png]]
 101
 102 For further steps the following assumptions are made: the server to
 103 connect to has name `myserver` and the client we are configuring:
 104 `myclient0`.
 105 You will need to create the following files and folders within:
 106
 107 - [[tinc.conf|examples/osx/tinc.conf]]
 108 - [[tinc-up|examples/osx/tinc-up]]
 109 - [[tinc-down|examples/osx/tinc-down]]
 110 - [[hosts/myserver|examples/osx/myserver]]
 111 - [[hosts/myclient0|examples/osx/myclient0]]
 112
 113 The sample files contain necessary explanation to make it work.
 114 Make sure `tinc-up` and `tinc-down` are executable:
 115
 116 [[!img examples/osx/config2.png]]
 117
 118 You will also need to generate pair of keys (private/public) for
 119 your client. Do it only after the above files are configured
 120 properly! You will be asked for locations of certain files. The
 121 default locations are fine.
 122
 123 [[!img examples/osx/config3.png]]
 124
 125 Once you are done, copy `hosts/myclient0` file and place it on your
 126 server in the same location (`hosts/myclient0`). At this stage your
 127 client should be able to connect to the server.
 128
 129 ### Starting tinc
 130
 131 To start tinc everything you need is to execute:
 132
 133 [[!img examples/osx/start1.png]]
 134
 135 Tincd will issue a notice once it is successfully connected. For
 136 more details on the syntax check `tincd --help`.
 137 To stop the client you can kill it be executing:
 138
 139 [[!img examples/osx/start2.png]]
 140
 141 ### Configuring tinc-up and tinc-down scripts
 142
 143 `tincd-up` and `tincd-down` are two files that tincd executes on
 144 start of the service and on stop respectively. They are usually
 145 used to notify system to use the vpn as a default gateway. The
 146 files provided in the previous page are minimalistic and used only
 147 to bring up and down the interface. If you would like to tunnel all
 148 the traffic over vpn use the scripts provided below. You have to
 149 modify them accordingly to your configuration. Please see the notes
 150 inside them:
 151
 152 - [[tinc-up|examples/osx/tinc-up-1]] (Advanced example)
 153 - [[tinc-down|examples/osx/tinc-down-1]] (Advanced example)
 154
 155 Please remember to rename the files to `tinc-up` and `tinc-down`
 156 respectively and place them in your configuration folder replacing
 157 the two existing files (if applicable).
 158
 159 * * * * *
 160
 161 Grzegorz Dymarek (gd58 (at) alumni . st-andrews . ac . uk)