Debian Codegraph @

README

raw
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/