Raoul,
On Wed, 2006-08-30 at 07:03 -0700, Raoul Carag wrote:
> A write-up of the IP Tunnel Device Driver has been posted for review in:
>
> http://www.opensolaris.org/os/project/clearview/docs
>
> The target audience for this document, and all other write-ups that
> might be posted later, are system administrators. As such, the
> document's final version will be integrated into one of the System
> Administration Guides to be published for a Solaris Express release.
Excellent. This is a good start. Here is my feedback:
I think it would help to introduce what IP tunneling is and what its
conceptual parts are so that the language used in the document can be more
clear and be made more explicit. For example, there is a conceptual
separation between a tunnel data-link and a tunnel IP interface which is
configured above that data-link. That conceptual separation is reflected in
the administrative model, in which the data-link is administered using
dladm, and the IP interface is administered using ifconfig.
Also, there is no tie-in with IPsec in here, and I think there needs to be.
This is especially important given the IPsec tunnel reform work that is
happening (are you in touch with the documentation writer for that
project?). The method of configuring IPsec policy for IP tunnels is being
significantly enhanced by that project, and IPsec VPNs is one of the primary
uses of IP tunneling.
Specific comments:
1. General Description
* In general, I'm not sure I'd put much emphasis on the fact that there's a
new "device driver". The important thing for an administration guide is
the administrative interfaces and administrative tasks that are possible,
and less that there's a new driver underneath.
So instead of saying, "In this Solaris release, a new IP tunneling device
driver is introduced", I'd probably just skip to the chase and say, "In
this Solaris release, IP tunnels data-links are administered using dladm
and can be monitored using tools such as snoop." Then, I might go on to
explain some of the more administratively banal details of why that is
(like the fact that the implementation uses a GLDv3 driver that results in
DLPI nodes, etc.).
* In the first paragraph, I'd expand the last sentence with, "to be
monitored with tools such as snoop."
* Second paragraph, IP tunnel data-links are administered using dladm. To
be explicit, I'd state something like, "... IP tunnel data-link
administration is now performed by using the dladm command, which is
consistent with the administration of other network data-links."
2. dladm Subcommands
* 2nd paragraph: "all aspects of IP tunneling were configured ...".
* 2nd paragraph: only the data-link aspects of IP tunnels are administered
using dladm. I'd also emphasize that this is done to better integrate IP
tunnel data-links with general data-link Solaris features such as
observability and vanity naming.
3.1 How to Create and Configure IP Tunnels
* The first paragraph is incorrect. IP tunneling is not an IPv6-specific
feature.
* I'm not sure this breakdown is the most intuitive. There are three types
of IP tunneling implemented:
- IPv4 tunneling: IP packets (IPv4 or IPv6) are encapsulated in an IPv4
header and sent to a pre-configured unicast IPv4 destination.
- IPv6 tunneling: IP packets (IPv4 or IPv6) are encapsulated in an IPv6
header and sent to a pre-configured unicast IPv6 destination.
- 6to4 tunneling: IPv6 packets are encapsulated in an IPv4 header and sent
to an IPv4 destination that is automatically determined on a per-packet
basis (based on an algorithm defined in the 6to4 protocol).
It would be beneficial to administrators to document these distinctions
somewhere so that they have a reference to understand the overall behavior
of the IP tunnel data-link they are actually creating.
3.1.1 Procedure
* Bullet item 2: This does not make any distinction between what's required
and optional on the command line, nor what is required for each type of IP
tunnel. I have the same comment for other parts of the document where
command-line usage is described.
* Bullet item 3: There are some subtleties missing from this section with
regards to each type of tunnel.
For IPv4 interfaces, setting a source _and_ a destination address for the
point-to-point IP interface is required.
For IPv6 interfaces, the link-local IPv6 source and destination addresses
are automatically set based on an algorithm, but can be optionally
overridden. Global IPv6 addresses can be added by using "addif".
For IPv6 interfaces over 6to4 tunnels, the IPv6 6to4 address is
automatically set based on an algorithm, but can be optionally overridden.
* Under bullet item 3, you state that the ifconfig "tsrc" and "tdst" tokens
are no longer necessary, but you don't explain why. It would help to
state that these are the data-link addresses that were configured using
dladm, and are thus redundant.
* Bullet item 3.c (and the following bullet), the ifconfig command there is
only valid for an IPv4 interface. If an IPv6 interface is being plumbed,
the "inet6" token must precede "plumb".
* If it's a temporary tunnel, then there's no configuration file to grab
ifconfig commands from...
3.1.2 Examples
* Instead of "punchin0", I'd use "vpn0". punchin is a Sun internal program,
and I'm not sure it's meaningful to anyone other than Sun employees.
* Instead of "corresponding configuration file", I'd state "corresponding IP
interface configuration file". Note that with NWAM, hostname files will
go away, so the IP interface configuration portions of this will need to
be revisited. You may want to see what Stef has planned for NWAM
documentation.
* It's sufficient to say "6to4 tunnel" instead of "6to4 IP tunnel".
3.1.1 Procedure
* It _is_ necessary to first unplumb IP interfaces over a tunnel link before
deleting the tunnel link, so the "if necessary" is "unnecessary". ;-) I'd
say, "Unplumb any existing IP interfaces that are configured over the
tunnel."
3.4.1 Procedure
* We will have a way to display either the system's current running
environment, or the persistent configuration.
3.4.2 Examples
* I'm not really happy about the format of the show-iptun output. It
doesn't work at all for IPv6 tunnels, and it won't work at all for
printing persistent configurations that may use long hostnames as source or
destination. I need to brainstorm ways to make this better.
4.1 Introduction
* "Instead, you configure boundary relay routers to become 6to4 routers".
I'd steer clear of the term "relay router" here, as that has an entirely
different meaning in a 6to4 context.
* Instead of "a remote IPv6 network", that should just be "IPv6 networks".
4.2 Procedure
* Step 2: What is <IPv6>? That is not part of the dladm syntax... The IPv6
interface on a 6to4 tunnel must be plumbed using ifconfig, not dladm.
* Step 3: The note is misplaced and incorrect. The real issue is that two
tunnels (regardless of whether it's an IPv4 or an IPv6 tunnel) on the same
system cannot have the same source _and_ destination. In addition to
that, a 6to4 tunnel cannot have the same source address as any IPv4
tunnels also configured on the same system. This detail belongs
elsewhere, however, as it's not 6to4 specific. Probably in the
iptun-create section.
* Step 3: atun no longer exists (the design doc gives the reason why), and
there is no longer a tun(7M) man page, that was the old tun STREAMS
module.
* Step 4 is incorrect. What do you mean by "pseudo-interface"? If you mean
logical IP interface, then the note is also incorrect, as 6to4 tunnels
have IPv4 _link-layer_ addresses and IPv6 network layer addresses. A
single 6to4 tunnel only has one link-layer, but can have multiple IPv6
network layer addresses.
You cannot repeat step 3. In order to add IPv6 addresses to the 6to4
tunnel, you'd simply add "addif" statements to the existing file, but
there's no conceivable reason to do that. I'd just remove step 4
altogether.
* Step 5: That output doesn't look right. The 6to4 address assigned to the
IP interface isn't syntactically possible.
* Step 6: This is done on each IPv6 router in the site (in addition to the
6to4 router itself).
4.3.1 ifconfig Output Showing 6to4 Pseudo-Interface
* What is a pseudo-interface?
4.3.2 6to4Advertisements in/etc/inet/ndpd.conf
* The title of this section needs tweaking. "Enabling IPv6 Router
Advertisements for 6to4 Prefixes in /etc/inet/ndpd.conf" would be more
correct.
Thanks,
-Seb
