| 1 |
Miredo : open-source Teredo |
| 2 |
============================ |
| 3 |
Copyright (C) 2004-2007 Rémi Denis-Courmont. |
| 4 |
|
| 5 |
Welcome to Miredo’s user’s guide! |
| 6 |
|
| 7 |
Where to go? |
| 8 |
============= |
| 9 |
|
| 10 |
If you’ve used olders versions of this program, you should read NEWS |
| 11 |
for a summary of the most recent updates and changes. |
| 12 |
|
| 13 |
For detailled usage instructions, you should refer to the Unix manual |
| 14 |
page miredo(8) which should be provided with your copy of the program. |
| 15 |
For quick usage instructions, see below. |
| 16 |
|
| 17 |
See INSTALL for general instructions on how to build the package and |
| 18 |
install the program from sources. Additionnal informations may be found |
| 19 |
below. 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 |
| 23 |
License (GPL) version 2 written by the Free Software Foundation, Inc. |
| 24 |
for 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 |
|
| 30 |
What 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 |
| 35 |
standard (RFC 4380). It can provide either client or relay |
| 36 |
functionality. A separate program, miredo-server is also included in |
| 37 |
the package; it consists of a Teredo server. |
| 38 |
|
| 39 |
Miredo can be used to provide IPv6 connectivity to users behind NAT |
| 40 |
devices, such as broadband routers. Most of these device do not support |
| 41 |
IPv6, and do not allow forwarding of proto-41 (including 6to4). |
| 42 |
|
| 43 |
|
| 44 |
System requirements |
| 45 |
==================== |
| 46 |
|
| 47 |
Miredo aims to support all POSIX-like open-source operating system |
| 48 |
kernels with IPv6 and userland layer-3 tunneling support. See below |
| 49 |
for system specific notes. |
| 50 |
|
| 51 |
Miredo is believed to be architecture-independant, but it was only |
| 52 |
properly tested on Linux i386, with GCC 4.1, GCC 3.3 and ICC 8.0. |
| 53 |
GCC 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 |
|
| 60 |
Linux: |
| 61 |
------- |
| 62 |
Miredo runs fine on Linux kernel 2.6.9; if possible, kernel version |
| 63 |
2.6.12 or more recent is recommended. It can run with older versions as |
| 64 |
well, including the 2.4 branch. However, there are known problems with |
| 65 |
the -experimental- IPv6 stack of these kernel releases; this is not |
| 66 |
specific 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 |
| 71 |
2.6.17.2 and GNU/libc 2.5 are required. |
| 72 |
|
| 73 |
FreeBSD: |
| 74 |
--------- |
| 75 |
Miredo works fine with FreeBSD 5.5 and up. You can use the net/miredo |
| 76 |
port. There is a known problem with the FreeBSD 6.2 and older; it |
| 77 |
should mostly affect Miredo in "relay" mode. |
| 78 |
FreeBSD 4.11 is not supported. |
| 79 |
|
| 80 |
OpenBSD: |
| 81 |
--------- |
| 82 |
OpenBSD might work. Version 3.7 was tested with older releases. |
| 83 |
|
| 84 |
NetBSD: |
| 85 |
-------- |
| 86 |
NetBSD 4.0 is required, for IPv6 tunneling. Miredo should be |
| 87 |
available through pkgsrc. |
| 88 |
|
| 89 |
Darwin (Mac OS X): |
| 90 |
------------------- |
| 91 |
Miredo works on Mac OS X (Panther, Tiger) and might work on other |
| 92 |
Darwin variants. On Mac OS X, you will have to install a third party |
| 93 |
tunneling driver; Miredo was tested with Mattis Nissler's tuntap from: |
| 94 |
http://www-user.rhrk.uni-kl.de/~nissler/tuntap/ |
| 95 |
|
| 96 |
Note that Mac OS X users should consider using Miredo-OSX from |
| 97 |
http://www.deepdarc.com/ which provides prebuilt OS X binaries of |
| 98 |
Miredo along with Nissler's tuntap, LibJudy and OS X specific additions |
| 99 |
and tweaks. |
| 100 |
|
| 101 |
DragonFly: |
| 102 |
----------- |
| 103 |
Miredo should work. It is in NetBSD's pkgsrc. |
| 104 |
|
| 105 |
|
| 106 |
Quick usage |
| 107 |
============ |
| 108 |
|
| 109 |
Easy installation: |
| 110 |
------------------- |
| 111 |
First, compile and install Miredo. Refer to INSTALL for detailled |
| 112 |
instructions. 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 |
| 120 |
C/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 |
| 124 |
means you are probably reinstalling or upgrading Miredo). This sample |
| 125 |
will cause Miredo to run as a Teredo client, with “teredo.remlab.net” |
| 126 |
(Miredo official testing Teredo server) as its Teredo server. These |
| 127 |
default settings should be fine for most users. |
| 128 |
|
| 129 |
Starting the program: |
| 130 |
---------------------- |
| 131 |
Before you start, please note that Miredo must be started by root, |
| 132 |
and that it will detach and run in the background. If something goes |
| 133 |
wrong, 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 |
| 143 |
a restricted NAT, which is frequent. After about 20 seconds, you should |
| 144 |
have access to the IPv6 Internet through Teredo, with a public Teredo |
| 145 |
IPv6 address on the “teredo” networking interface : |
| 146 |
|
| 147 |
# ifconfig teredo |
| 148 |
teredo 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 |
| 158 |
PING www.kame.net(orange.kame.net) 56 data bytes |
| 159 |
64 bytes from orange.kame.net: icmp_seq=1 ttl=50 time=558 ms |
| 160 |
64 bytes from orange.kame.net: icmp_seq=2 ttl=50 time=585 ms |
| 161 |
64 bytes from orange.kame.net: icmp_seq=3 ttl=50 time=562 ms |
| 162 |
64 bytes from orange.kame.net: icmp_seq=4 ttl=50 time=552 ms |
| 163 |
|
| 164 |
--- www.kame.net ping statistics --- |
| 165 |
4 packets transmitted, 4 received, 0% packet loss, time 3003ms |
| 166 |
rtt min/avg/max/mdev = 552.830/564.865/585.031/12.218 ms |
| 167 |
|
| 168 |
Monitoring: |
| 169 |
------------ |
| 170 |
If you wish to monitor the Teredo tunnel, I suggest you use famous |
| 171 |
network analyzer Wireshark (formerly Ethereal®) which includes a Teredo |
| 172 |
“dissector”. |
| 173 |
|
| 174 |
Teredo relay and/or server: |
| 175 |
---------------------------- |
| 176 |
Please refer to the sample configuration miredo.conf-dist for further |
| 177 |
information. You can get a comprehensive reference of all possible |
| 178 |
options in the manual pages provided with the package: |
| 179 |
miredo(8) and miredo.conf(5) |
| 180 |
|
| 181 |
# man 8 miredo |
| 182 |
# man 5 miredo.conf |
| 183 |
|
| 184 |
|
| 185 |
Securing you Miredo installation |
| 186 |
================================= |
| 187 |
|
| 188 |
By default, Miredo drops its root privileges and runs as user nobody. |
| 189 |
While that is far more secure than keeping root privileges as previous |
| 190 |
versions did by default, it is not optimal. If you are security |
| 191 |
concious, paranoid, or if you are building a package, you are advised |
| 192 |
to perform the following steps to restrict the impact of a possible |
| 193 |
compromise of the Miredo daemon. |
| 194 |
|
| 195 |
They are some steps to secure Miredo installation, because they are |
| 196 |
non trivial and non portable, they cannot be done automatically. That |
| 197 |
is why miredo defaults to using “nobody” user account which is |
| 198 |
available on any POSIX-like operating system. |
| 199 |
|
| 200 |
1) 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 |
|
| 216 |
NOTE: If you are running Miredo as a Teredo client, Miredo will spawn a |
| 217 |
separate privileged process whose only job will be the Teredo interface |
| 218 |
parameters (it must be root to do that). If someone breaks Miredo, it |
| 219 |
might still be able to break your IPv6 networking setup, but it should |
| 220 |
not be able to compromise the whole system. |
| 221 |
|
| 222 |
2) Chroot jail: |
| 223 |
---------------- |
| 224 |
Chroot jail can be enabled with the “-t” command line option. Note |
| 225 |
that when using miredo as a Teredo client, you will typically have to |
| 226 |
install your DNS resolver library and configuration within the chroot |
| 227 |
environment, 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 |
| 230 |
the chroot. You will also have to resynchronize /etc/resolv.conf within |
| 231 |
the 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, |
| 235 |
you should really enable the chroot, as it is safer and should work |
| 236 |
fine “out of the box”. |
| 237 |
|
| 238 |
3) POSIX capabilities: |
| 239 |
----------------------- |
| 240 |
Miredo supports POSIX.1e capabilities (at least on Linux), if they |
| 241 |
are available. You should not need to worry as it is entirely |
| 242 |
automatic. |
| 243 |
|
| 244 |
If you are a packager, you should consider installing your system’s |
| 245 |
POSIX capabilities library development files, before building Miredo. |
| 246 |
|
| 247 |
|
| 248 |
Feedback: |
| 249 |
========== |
| 250 |
|
| 251 |
If you have further questions, please write to: |
| 252 |
|
| 253 |
miredo (dash) devel (at) remlab (dot) net |
| 254 |
|
| 255 |
-- |
| 256 |
Rémi Denis-Courmont <remi (at) remlab (dot) net> |
| 257 |
http://www.remlab.net/miredo/ |