Miredo: open-source Teredo
===========================
Copyright (C) 2004-2014 Rémi Denis-Courmont.

  Welcome to Miredo’s user’s guide!

Where to go?
=============

  If you’ve used olders versions of this program, you should read NEWS
for a summary of the most recent updates and changes.

  For detailled usage instructions, you should refer to the Unix manual
page miredo(8) which should be provided with your copy of the program.
For quick usage instructions, see below.

  See INSTALL for general instructions on how to build the package and
install the program from sources. Additionnal informations may be found
below. If you are building from the Subversion repository, run the
“./autogen.sh” script first.

  This package is distributed under the terms of the General Public
License (GPL) version 2 written by the Free Software Foundation, Inc.
for full licensing details, please read COPYING.

  If you have further questions, please send an email to:
    miredo (dash) devel (at) remlab (dot) net


What is Miredo?
================

  Miredo is an Unix daemon program which mostly implements the
“Teredo: Tunneling IPv6 over UDP through NATs” Internet proposed
standard (RFC 4380). It can provide either client or relay
functionality. A separate program, miredo-server is also included in
the package; it consists of a Teredo server.

  Miredo can be used to provide IPv6 connectivity to users behind NAT
devices, such as broadband routers. Most of these device do not support
IPv6, and do not allow forwarding of proto-41 (including 6to4).


System requirements
====================

  Miredo aims to support all POSIX.2008 operating systems with IPv6 and
userland layer-3 tunneling support. See below for system specific notes.

  When available, Miredo can use the following optional libraries:
 - GNU gettext for localization,
 - libcap (currently Linux-specific) for POSIX capabilities,
 - Judy dynamic arrays library for better scalability.

On Linux, Miredo requires the Universal TUNTAP driver (CONFIG_TUN) and
of course the IPv6 protocol suites (CONFIG_IPV6) support from kernel.


Quick usage
============

Easy installation:
-------------------
  First, compile and install Miredo. Refer to INSTALL for detailled
instructions. Miredo can be installed the usual way:

# ./configure
# make
# su
# make install

  Miredo has no particular required dependencies, besides the usual
C compiler and development libraries.

  A sample configuration file is automatically installed at
/usr/local/etc/miredo/miredo.conf - unless the file already existed
(which means you are probably reinstalling or upgrading Miredo). This
sample will cause Miredo to run as a Teredo client, with
“teredo.remlab.net” (Miredo official testing Teredo server) as its
Teredo server. These default settings should be fine for most users.

Starting the program:
----------------------
  Before you start, please note that Miredo must be started by root,
and that it will detach and run in the background. If something goes
wrong, there are two ways two know what:
- read your system logs (typically /var/log/syslog),
- force Miredo to run in the foreground (that’s meant for debugging),
  by starting it with the “--foreground” command line parameter, and
  wait for about 20 seconds.

  You can now run miredo (as root!):
# /usr/local/sbin/miredo

  It will need some time to initialize, particularly if you are behind
a restricted NAT, which is frequent. After about 20 seconds, you should
have access to the IPv6 Internet through Teredo, with a public Teredo
IPv6 address on the “teredo” networking interface:

# ifconfig teredo
teredo    Link encap:UNSPEC  HWaddr 00-00-00-00-00-00-00-00-00-00-00...
          inet6 addr: 2001:0:8ac3:9ddd:0:7ffa:ad80:3464/32 Scope:...
          inet6 addr: fe80::5445:5245:444f/64 Scope:Link
          UP POINTOPOINT RUNNING NOARP  MTU:1280  Metric:1
          RX packets:5 errors:0 dropped:0 overruns:0 frame:0
          TX packets:7 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:500
          RX bytes:468 (468.0 b)  TX bytes:560 (560.0 b)

# ping6 -c 4 www.example.com
PING www.example.com(2001:db8::dead:beef) 56 data bytes
64 bytes from 2001:db8::dead:beef: icmp_seq=1 ttl=50 time=558 ms
64 bytes from 2001:db8::dead:beef: icmp_seq=2 ttl=50 time=585 ms
64 bytes from 2001:db8::dead:beef: icmp_seq=3 ttl=50 time=562 ms
64 bytes from 2001:db8::dead:beef: icmp_seq=4 ttl=50 time=552 ms

--- www.example.com ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3003ms
rtt min/avg/max/mdev = 552.830/564.865/585.031/12.218 ms

Monitoring:
------------
  If you wish to monitor the Teredo tunnel, I suggest you use famous
network analyzer Wireshark which includes a Teredo “dissector”.

Teredo relay and/or server:
----------------------------
  Please refer to the sample configuration miredo.conf-dist for further
information. You can get a comprehensive reference of all possible
options in the manual pages provided with the package:
miredo(8) and miredo.conf(5)

# man 8 miredo
# man 5 miredo.conf


Securing you Miredo installation
=================================

  By default, Miredo drops its root privileges and runs as user nobody.
While that is far more secure than keeping root privileges as early
versions did, it is not optimal. Miredo should rather run with its own
user account rather than common user “nobody”. They are two ways to
achieve that:

- You can enable the “--enable-miredo-user” command line option when
  running the source code configure script. If you are a packager,
  please use that method. Miredo will try to SetUID as “miredo” by
  default, though that can be overriden with the “-u” command line
  option (see man page miredo(8)).

- You can use the “-u” option when starting Miredo. That saves the
  cost of recompiling Miredo. For example:

  # /usr/local/sbin/miredo -u miredo

NOTE: If you are running Miredo as a Teredo client, Miredo will spawn a
separate privileged process to configure the Teredo interface (requiring
root). If someone breaks Miredo, it might still be possible to break the
IPv6 networking setup, but not compromise the whole system.

POSIX capabilities:
--------------------
  Miredo supports POSIX.1e capabilities (at least on Linux), if they
are available. You should not need to worry as it is entirely
automatic.

  If you are a packager, you should consider installing your system’s
POSIX capabilities library development files, before building Miredo.


Feedback:
==========

  If you have further questions, please write to:

    miredo (dash) devel (at) remlab (dot) net

-- 
Rémi Denis-Courmont <remi (at) remlab (dot) net>
http://www.remlab.net/miredo/