Sun Jan 4 16:27:48 2009 UTC ()

 * in diagrams, name routers as such
 * enhance formatting
 * add section headers for examples


(hubertf)

diff -r1.39 -r1.40 src/share/man/man4/gre.4

--- src/share/man/man4/gre.4 2008/05/10 09:33:31	1.39
+++ src/share/man/man4/gre.4 2009/01/04 16:27:48	1.40

 @@ -1,14 +1,14 @@
-.\" $NetBSD: gre.4,v 1.39 2008/05/10 09:33:31 martin Exp $
+.\" $NetBSD: gre.4,v 1.40 2009/01/04 16:27:48 hubertf Exp $
 .\"
 .\" Copyright (c) 1998 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to The NetBSD Foundation
 .\" by Heiko W.Rupp <hwr@pilhuhn.de>
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
 .\" 1. Redistributions of source code must retain the above copyright
 .\"    notice, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 @@ -17,27 +17,27 @@
 .\"
 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 .\" TO, THE  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 .\" CONTRACT, STRICT  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 .\" ARISING IN ANY WAY  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 4, 2006
+.Dd January 4, 2009
 .Dt GRE 4
 .Os
 .Sh NAME
 .Nm gre
 .Nd encapsulating network device
 .Sh SYNOPSIS
 .Cd pseudo-device gre
 .Sh DESCRIPTION
 The
 .Nm gre
 network interface pseudo device encapsulates datagrams
 into IP.
 These encapsulated datagrams are routed to a destination host,
 @@ -134,160 +134,174 @@ Query operation mode.
 .It GRESSOCK :
 Delegate a socket from userland to a tunnel interface in UDP
 encapsulation mode.
 The file descriptor for the socket is passed in
 (struct ifreq)-\*[Gt]ifr_value.
 .El
 .Pp
 Note that the IP addresses of the tunnel endpoints may be the same as the
 ones defined with
 .Xr ifconfig 8
 for the interface (as if IP is encapsulated), but need not be, as e.g. when
 encapsulating AppleTalk.
 .Sh EXAMPLES
 .Ss Example 1: Basic GRE tunneling
 Configuration example:
 .Bd -literal
-Host X-- Host A  ----------------tunnel---------- cisco D------Host E
+Host X-- Router A  --------------tunnel---------- Router D ----Host E
-          \\                                          |
+          |                                          |
            \\                                        /
-             +------Host B----------Host C----------+
+            +----- Router B ----- Router C --------+
 .Ed
-On host A
+.Pp
 On Router A
 .Pq Nx :
 .Bd -literal
    # route add default B
    # ifconfig greN create
    # ifconfig greN A D netmask 0xffffffff linkX up
    # ifconfig greN tunnel A D
    # route add E D
 .Ed
-On Host D (Cisco):
+.Pp
 On Router D (Cisco):
 .Bd -literal
    Interface TunnelX
     ip unnumbered D   ! e.g. address from Ethernet interface
     tunnel source D   ! e.g. address from Ethernet interface
     tunnel destination A
    ip route C \*[Lt]some interface and mask\*[Gt]
    ip route A mask C
    ip route X mask tunnelX
 .Ed
-OR
+.Pp
-On Host D
+or on Router D
 .Pq Nx :
 .Bd -literal
    # route add default C
    # ifconfig greN create
    # ifconfig greN D A
    # ifconfig tunnel greN D A
 .Ed
 .Pp
 If all goes well, you should see packets flowing ;-)
 .Pp
-If you want to reach Host A over the tunnel (from Host D (Cisco)), then
+If you want to reach Router A over the tunnel (from Router D (Cisco)), then
-you have to have an alias on Host A for e.g. the Ethernet interface like:
+you have to have an alias on Router A for e.g. the Ethernet interface like:
 .Bd -literal
      ifconfig \*[Lt]etherif\*[Gt] alias Y
 .Ed
-and on the cisco
+.Pp
 and on the Cisco
 .Bd -literal
      ip route Y mask tunnelX
 .Ed
-.Pp
+.Ss Example 2: Linking private subnets
 A similar setup can be used to create a link between two private networks
 (for example in the 192.168 subnet) over the Internet:
 .Bd -literal
 .168.1.* --- Router A  -------tunnel-------- Router B --- 192.168.2.*
                    \\                              /
                     \\                            /
                       +----- the Internet ------+
 .Ed
-Assuming router A has the (external) IP address A and the internal address
+.Pp
-.168.1.1, while router B has external address B and internal address
+Assuming Router A has the (external) IP address A and the internal address
 .168.1.1, while Router B has external address B and internal address
 .168.2.1, the following commands will configure the tunnel:
 .Pp
-On router A:
+On Router A:
 .Bd -literal
    # ifconfig greN create
    # ifconfig greN 192.168.1.1 192.168.2.1
    # ifconfig greN tunnel A B
    # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1
 .Ed
 .Pp
-On router B:
+On Router B:
 .Bd -literal
    # ifconfig greN create
    # ifconfig greN 192.168.2.1 192.168.1.1
    # ifconfig greN tunnel B A
    # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1
 .Ed
 .Pp
 .Ss Example 3: Encapsulating GRE in UDP
 To setup the same tunnel as above, but using GRE in UDP encapsulation
 instead of GRE encapsulation, set flags
 .Ar link0
 and
 .Ar link2 ,
 and specify source and destination UDP ports.
 .Pp
-On router A:
+On Router A:
 .Bd -literal
    # ifconfig greN create
    # ifconfig greN link0 link2
    # ifconfig greN 192.168.1.1 192.168.2.1
    # ifconfig greN tunnel A,port-A B,port-B
    # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1
 .Ed
 .Pp
-On router B:
+On Router B:
 .Bd -literal
    # ifconfig greN create
    # ifconfig greN link0 link2
    # ifconfig greN 192.168.2.1 192.168.1.1
    # ifconfig greN tunnel B,port-B A,port-A
    # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1
 .Ed
 .Pp
 .Ss Example 4: Realizing IPv6 connectivity
 Along these lines, you can use GRE tunnels to interconnect two IPv6
 networks over an IPv4 infrastructure, or to hook up to the IPv6 internet
 via an IPv4 tunnel to a Cisco router.
 .Bd -literal
-:db8:1::/64 -- NetBSD A  -----tunnel----- Cisco B --- IPv6 Internet
+:db8:1::/64 -- NetBSD A  ---- Tunnel ---- Cisco B --- IPv6 Internet
                    \\                              /
                     \\                            /
-                      +----- the Internet ------+
+                     +------ the Internet ------+
 .Ed
 .Pp
 The example will use the following addressing:
-.Nx
+.Bl -hang
-A has the IPv4 address A and the IPv6 address 2001:db8:1::1 (connects
+.It Nx A
 has the IPv4 address A and the IPv6 address 2001:db8:1::1 (connects
 to internal network 2001:db8:1::/64).
-Cisco B has external IPv4 address B.
+.It Cisco B
-All the IPv6 internet world is behind B, so A wants to route 0::0/0
+has external IPv4 address B.
 .It All the IPv6 internet world
 is behind B, so A wants to route 0::0/0
 (the IPv6 default route) into the tunnel.
-The GRE tunnel will use a transit network: 2001:db8:ffff::1/64 on
+.It The GRE tunnel
 will use a transit network: 2001:db8:ffff::1/64 on
 the
 .Nx
 side, and ::2/64 on the Cisco side.
 .El
 .Pp
 Then the following commands will configure the tunnel:
 .Pp
-On router A
+On Router A
 .Pq Nx :
 .Bd -literal
    # ifconfig greN create
    # ifconfig greN inet6 2001:db8:ffff::1/64
    # ifconfig greN tunnel A B
    # route add -inet6 2001:db8:ffff::/64 2001:db8:ffff::2 -ifp greN
    # route add -inet6 0::0/0 2001:db8:ffff::2 -ifp greN
 .Ed
 .Pp
-On router B (Cisco):
+On Router B (Cisco):
 .Bd -literal
    Interface TunnelX
      tunnel mode gre ip
      ipv6 address 2001:db8:ffff::2/64   ! transfer network
      tunnel source B                    ! e.g. address from LAN interface
      tunnel destination A               ! where the tunnel is connected to
    ipv6 route 2001:db8::/64 TunnelX     ! route this network through tunnel
 .Ed
 .Ed
 .Sh NOTES
 The MTU of
 .Sy gre Ns Ar X
 interfaces is set to 1476 by default to match the value used by Cisco routers.