(no commit message)
[wiki] / examples / macbook-install.mdwn
1 [[!meta title="installing tinc on Mac OS/X laptop"]]
2
3 ## Example: installing tinc on Mac OS/X laptop
4
5 **This page is under construction, don't use what is written here yet.**
6
7 This page explains how to intergrate tinc as a system service on a laptop. Allowing tinc to reconnect as soon as a internet connection is available. Installing an configuring tinc is explained on [[osx-install]]. I have used the compile-it-yourself method, as the intergration into OS X is currently a small application you have to compile yourself anyway.
8
9 [[!toc levels=3]]
10
11 ### Configuration of tinc for a laptop
12
13 The configuration as used on the [[osx-install]] page works on a laptop. The important thing is that the host-file descrbing the laptop does not give an ip address, because it changes to wherever the laptop will be. Instead, the laptop sould have a ConnectTo = myserver line in its tincd.conf file.
14
15 Auto discovery (bonjour) of network services on the vpn might work when tinc runs in Router mode. But I use a switch-based network to make the laptop appear as part of my local network, which even allows dhcp to work over the vpn. Note that this can lower the performance of your vpn. To use the switch mode in tinc, just add the line 'Mode = Switch' in the tincd.conf on the server and laptop side. If you have a local network, you will also need a bridge on the server between your local network and the vpn. There are guides on how to setup such a bridge but I give an example below.
16
17
18 #### Setup a bridge on your server
19
20 We assume *eth0* is your local network. We name the brigde *priv*, but you can use any name. On your server bring down eth0 using *ifdown eth0*. **Be careful not to shut yourself out**. In /etc/network/interfaces add:
21
22     # Prevent NetworkManager to run on these interfaces
23     iface eth0 inet manual
24     
25     #  Start priv on boot
26     auto priv
27     # make eth0 part of the bridge priv and configure priv via dhcp
28     iface priv inet dhcp
29         bridge_ports eth0
30
31 If there are other references to eth0, these should likely be removed. Now the tinc-up file of your vpn on your server should look like:
32
33     #!/bin/sh
34     ifconfig "$INTERFACE" up
35     brctl addif priv "$INTERFACE"
36
37 The tinc-down file should be:
38
39     #!/bin/sh
40     brctl delif priv "$INTERFACE"
41
42 This add and removes the vpn interface as part of the bridge if tinc starts or stops. A bridge is like a virtual switch and allows two network devices to be on the same subnet.
43
44 ### Start tinc at startup
45
46 OS X has something called [launchd](http://en.wikipedia.org/wiki/Launchd). This is a system for monitoring services and make sure services are started if certain conditions are met. This is used at least on OS X 10.5 and maybe newer versions as well. (If you want me to check it, you have to give me a laptop with that version installed on it.)
47
48 To use launchd, you have to create a property-list file for tinc and put it under /Library/LaunchDaemons/
49
50 For instance, I created */Library/LaunchDaemons/myvpn.tinc.plist* with the following:
51
52     <?xml version="1.0" encoding="UTF-8"?>
53     <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
54     <plist version="1.0">
55     <dict>
56         <key>KeepAlive</key>
57         <true/>
58         <key>Label</key>
59         <string>tinc.myvpn</string>
60         <key>ProgramArguments</key>
61         <array>
62                 <string>/usr/local/tinc/sbin/tincd</string>
63                 <string>-n</string>
64                 <string>myvpn</string>
65                 <string>-D</string>
66         </array>
67     </dict>
68     </plist>
69
70 This will configures tincd to start the myvpn configuration in the foreground (-D). If tincd is started as background daemon, launchd will become confused. Launchd will directly start tincd if this file is found (it might be that you first have to use the load command as explained below - I cannot remember), the KeepAlive will ensure that if tincd will stop, it is restarted directly. To be able to stop tincd you have to use *launchctl*. Good commands to remember are:
71
72     launchctl unload -w /Library/LaunchDaemons/myvpn.tinc.plist
73
74 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:
75
76     launchctl load -w /Library/LaunchDaemons/myvpn.tinc.plist
77
78 This removes the *disabled* key from the file and starts tincd. Using:
79
80     launchctl list
81
82 you will get a list of all services monitored by launchd. If done correctly, you will see tinc.myvpn listed with some process id.
83
84 There is also a stop command:
85
86     launchctl stop tinc.myvpn
87
88 But because the property list does not specify any condition when to start the command, launchd will directly start the tinc.myvpn service again.
89
90 ### Reconnect tinc if internet becomes available
91