1Miredo : open-source Teredo 2============================ 3Copyright (C) 2004-2007 Rémi Denis-Courmont. 4 5 Welcome to Miredo’s user’s guide! 6 7Where to go? 8============= 9 10 If you’ve used olders versions of this program, you should read NEWS 11for a summary of the most recent updates and changes. 12 13 For detailled usage instructions, you should refer to the Unix manual 14page miredo(8) which should be provided with your copy of the program. 15For quick usage instructions, see below. 16 17 See INSTALL for general instructions on how to build the package and 18install the program from sources. Additionnal informations may be found 19below. If you are building from the Subversion repository, run the 20“./autogen.sh” script first. 21 22 This package is distributed under the terms of the General Public 23License (GPL) version 2 written by the Free Software Foundation, Inc. 24for full licensing details, please read COPYING. 25 26 If you have further questions, please send an email to: 27 miredo (dash) devel (at) remlab (dot) net 28 29 30What is Miredo? 31================ 32 33 Miredo is an Unix daemon program which mostly implements the 34“Teredo: Tunneling IPv6 over UDP through NATs” Internet proposed 35standard (RFC 4380). It can provide either client or relay 36functionality. A separate program, miredo-server is also included in 37the package; it consists of a Teredo server. 38 39 Miredo can be used to provide IPv6 connectivity to users behind NAT 40devices, such as broadband routers. Most of these device do not support 41IPv6, and do not allow forwarding of proto-41 (including 6to4). 42 43 44System requirements 45==================== 46 47 Miredo aims to support all POSIX-like open-source operating system 48kernels with IPv6 and userland layer-3 tunneling support. See below 49for system specific notes. 50 51 Miredo is believed to be architecture-independant, but it was only 52properly tested on Linux i386, with GCC 4.1, GCC 3.3 and ICC 8.0. 53GCC 2.95 is purposedly not supported. 54 55 When available, Miredo can use the following optional libraries : 56 - GNU gettext for localization, 57 - libcap (currently Linux-specific) for POSIX capabilities, 58 - Judy dynamic arrays library for better scalability. 59 60Linux: 61------- 62 Miredo runs fine on Linux kernel 2.6.9; if possible, kernel version 632.6.12 or more recent is recommended. It can run with older versions as 64well, including the 2.4 branch. However, there are known problems with 65the -experimental- IPv6 stack of these kernel releases; this is not 66specific to the usage of Miredo. 67 Miredo requires the Universal TUNTAP driver (CONFIG_TUN) and IPv6 68(CONFIG_IPV6). 69 70 For proper source address selection (RFC3484 support), kernel version 712.6.17.2 and GNU/libc 2.5 are required. 72 73FreeBSD: 74--------- 75 Miredo works fine with FreeBSD 5.5 and up. You can use the net/miredo 76port. There is a known problem with the FreeBSD 6.2 and older; it 77should mostly affect Miredo in "relay" mode. 78 FreeBSD 4.11 is not supported. 79 80OpenBSD: 81--------- 82 OpenBSD might work. Version 3.7 was tested with older releases. 83 84NetBSD: 85-------- 86 NetBSD 4.0 is required, for IPv6 tunneling. Miredo should be 87available through pkgsrc. 88 89Darwin (Mac OS X): 90------------------- 91 Miredo works on Mac OS X (Panther, Tiger) and might work on other 92Darwin variants. On Mac OS X, you will have to install a third party 93tunneling driver; Miredo was tested with Mattis Nissler's tuntap from: 94http://www-user.rhrk.uni-kl.de/~nissler/tuntap/ 95 96 Note that Mac OS X users should consider using Miredo-OSX from 97http://www.deepdarc.com/ which provides prebuilt OS X binaries of 98Miredo along with Nissler's tuntap, LibJudy and OS X specific additions 99and tweaks. 100 101DragonFly: 102----------- 103 Miredo should work. It is in NetBSD's pkgsrc. 104 105 106Quick usage 107============ 108 109Easy installation: 110------------------- 111 First, compile and install Miredo. Refer to INSTALL for detailled 112instructions. Miredo can be installed the usual way: 113 114# ./configure 115# make 116# su 117# make install 118 119 Miredo has no particular required dependencies, besides the usual 120C/C++ compilers and development libraries. 121 122 A sample configuration file is automatically installed at 123/usr/local/etc/miredo.conf - unless the file already existed (which 124means you are probably reinstalling or upgrading Miredo). This sample 125will cause Miredo to run as a Teredo client, with “teredo.remlab.net” 126(Miredo official testing Teredo server) as its Teredo server. These 127default settings should be fine for most users. 128 129Starting the program: 130---------------------- 131 Before you start, please note that Miredo must be started by root, 132and that it will detach and run in the background. If something goes 133wrong, there are two ways two know what : 134- read your system logs (typically /var/log/syslog), 135- force Miredo to run in the foreground (that’s meant for debugging), 136 by starting it with the “--foreground” command line parameter, and 137 wait for about 20 seconds. 138 139 You can now run miredo (as root!): 140# /usr/local/sbin/miredo 141 142 It will need some time to initialize, particularly if you are behind 143a restricted NAT, which is frequent. After about 20 seconds, you should 144have access to the IPv6 Internet through Teredo, with a public Teredo 145IPv6 address on the “teredo” networking interface : 146 147# ifconfig teredo 148teredo Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00... 149 inet6 addr: 2001:0:8ac3:9ddd:0:7ffa:ad80:3464/32 Scope:... 150 inet6 addr: fe80::5445:5245:444f/64 Scope:Link 151 UP POINTOPOINT RUNNING NOARP MTU:1280 Metric:1 152 RX packets:5 errors:0 dropped:0 overruns:0 frame:0 153 TX packets:7 errors:0 dropped:0 overruns:0 carrier:0 154 collisions:0 txqueuelen:500 155 RX bytes:468 (468.0 b) TX bytes:560 (560.0 b) 156 157# ping6 -c 4 www.kame.net 158PING www.kame.net(orange.kame.net) 56 data bytes 15964 bytes from orange.kame.net: icmp_seq=1 ttl=50 time=558 ms 16064 bytes from orange.kame.net: icmp_seq=2 ttl=50 time=585 ms 16164 bytes from orange.kame.net: icmp_seq=3 ttl=50 time=562 ms 16264 bytes from orange.kame.net: icmp_seq=4 ttl=50 time=552 ms 163 164--- www.kame.net ping statistics --- 1654 packets transmitted, 4 received, 0% packet loss, time 3003ms 166rtt min/avg/max/mdev = 552.830/564.865/585.031/12.218 ms 167 168Monitoring: 169------------ 170 If you wish to monitor the Teredo tunnel, I suggest you use famous 171network analyzer Wireshark (formerly Ethereal®) which includes a Teredo 172“dissector”. 173 174Teredo relay and/or server: 175---------------------------- 176 Please refer to the sample configuration miredo.conf-dist for further 177information. You can get a comprehensive reference of all possible 178options in the manual pages provided with the package: 179miredo(8) and miredo.conf(5) 180 181# man 8 miredo 182# man 5 miredo.conf 183 184 185Securing you Miredo installation 186================================= 187 188 By default, Miredo drops its root privileges and runs as user nobody. 189While that is far more secure than keeping root privileges as previous 190versions did by default, it is not optimal. If you are security 191concious, paranoid, or if you are building a package, you are advised 192to perform the following steps to restrict the impact of a possible 193compromise of the Miredo daemon. 194 195 They are some steps to secure Miredo installation, because they are 196non trivial and non portable, they cannot be done automatically. That 197is why miredo defaults to using “nobody” user account which is 198available on any POSIX-like operating system. 199 2001) System user: 201---------------- 202 Miredo should run with its own user account rather than common user 203“nobody”. They are two ways to do that : 204 205- You can enable the “--enable-miredo-user” command line option when 206 running the source code configure script. If you are a packager, 207 please use that method. Miredo will try to SetUID as “miredo” by 208 default, though that can be overriden with the “-u” command line 209 option (see man page miredo(8)). 210 211- You can use the “-u” option when starting Miredo. That saves the 212 cost of recompiling Miredo. For example: 213 214 # /usr/local/sbin/miredo -u miredo 215 216NOTE: If you are running Miredo as a Teredo client, Miredo will spawn a 217separate privileged process whose only job will be the Teredo interface 218parameters (it must be root to do that). If someone breaks Miredo, it 219might still be able to break your IPv6 networking setup, but it should 220not be able to compromise the whole system. 221 2222) Chroot jail: 223---------------- 224 Chroot jail can be enabled with the “-t” command line option. Note 225that when using miredo as a Teredo client, you will typically have to 226install your DNS resolver library and configuration within the chroot 227environment, which is why the feature is currently disabled by default. 228 On Linux/libc6, that would consist of copying /etc/resolv.conf, 229/etc/nsswitch.conf and the Name Service Switch shared objects within 230the chroot. You will also have to resynchronize /etc/resolv.conf within 231the chroot with the one at the system root every time it is modified 232(such as when the DHCP client updates /etc/resolv.conf). 233 234 If you intend to use miredo only as a Teredo relay and/or server, 235you should really enable the chroot, as it is safer and should work 236fine “out of the box”. 237 2383) POSIX capabilities: 239----------------------- 240 Miredo supports POSIX.1e capabilities (at least on Linux), if they 241are available. You should not need to worry as it is entirely 242automatic. 243 244 If you are a packager, you should consider installing your system’s 245POSIX capabilities library development files, before building Miredo. 246 247 248Feedback: 249========== 250 251 If you have further questions, please write to: 252 253 miredo (dash) devel (at) remlab (dot) net 254 255-- 256Rémi Denis-Courmont <remi (at) remlab (dot) net> 257http://www.remlab.net/miredo/ 258