Module Name: src
Committed By: kefren
Date: Tue Jun 29 14:10:04 UTC 2010
Modified Files:
src/share/man/man4: Makefile
Added Files:
src/share/man/man4: mpls.4
Log Message:
add mpls(4) manpage created with great help from wiz@
To generate a diff of this commit:
cvs rdiff -u -r1.519 -r1.520 src/share/man/man4/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man4/mpls.4
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man4/Makefile
diff -u src/share/man/man4/Makefile:1.519 src/share/man/man4/Makefile:1.520
--- src/share/man/man4/Makefile:1.519 Tue Jun 8 05:38:32 2010
+++ src/share/man/man4/Makefile Tue Jun 29 14:10:04 2010
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.519 2010/06/08 05:38:32 riz Exp $
+# $NetBSD: Makefile,v 1.520 2010/06/29 14:10:04 kefren Exp $
# @(#)Makefile 8.1 (Berkeley) 6/18/93
MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
@@ -37,8 +37,8 @@
kloader.4 kse.4 ksyms.4 kttcp.4 \
lc.4 ld.4 lii.4 lo.4 lxtphy.4 \
mainbus.4 makphy.4 mbe.4 mca.4 mcclock.4 md.4 mfb.4 mfi.4 mhzc.4 \
- midi.4 mii.4 mk48txx.4 mlx.4 mly.4 mpt.4 mpu.4 mtd.4 mtio.4 \
- multicast.4 mvsata.4 \
+ midi.4 mii.4 mk48txx.4 mlx.4 mly.4 mpls.4 mpt.4 mpu.4 mtd.4 \
+ mtio.4 multicast.4 mvsata.4 \
nadb.4 ne.4 neo.4 netintro.4 nfe.4 nfsmb.4 njata.4 njs.4 \
nsclpcsio.4 nsp.4 nsphy.4 nsphyter.4 ntwoc.4 null.4 nsmb.4 \
oak.4 oosiop.4 opl.4 options.4 optiide.4 osiop.4 \
Added files:
Index: src/share/man/man4/mpls.4
diff -u /dev/null src/share/man/man4/mpls.4:1.1
--- /dev/null Tue Jun 29 14:10:04 2010
+++ src/share/man/man4/mpls.4 Tue Jun 29 14:10:04 2010
@@ -0,0 +1,261 @@
+.\" $NetBSD: mpls.4,v 1.1 2010/06/29 14:10:04 kefren Exp $
+.\"
+.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" 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
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" 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 June 29, 2010
+.Dt MPLS 4
+.OS
+.Sh NAME
+.Nm mpls
+.Nd Multiprotocol Label Switching
+.Sh SYNOPSIS
+.Cd options MPLS
+.Cd pseudo-interface ifmpls
+.In sys/types.h
+.In netmpls/mpls.h
+.Sh DESCRIPTION
+MultiProtocol Label Switching represents a mechanism which directs
+and carries data in high-performance networks, its techniques being
+applicable to any network layer protocol.
+.Pp
+In an MPLS domain the assignment of a particular packet a particular
+Forward Equivalence Class is done just once, as the packet enters the
+network.
+The FEC to which the packet is assigned is encoded as a
+short fixed length value known as a
+.Dq label .
+When a packet is forwarded to the next hop, the label is sent along
+with it; that is, the packets are
+.Dq labeled
+before they are forwarded.
+.Pp
+A router capable of receiving and forwarding MPLS frame is called
+.Dq Label Switch Router
+or LSR. Label scope is generally router-wide meaning that a certain
+label has a specific meaning only for a certain LSR.
+.Pp
+Currently,
+.Nx
+supports MPLS over Ethernet interfaces and GRE tunnels.
+For these kind of interfaces, a label is contained by a fixed
+sized
+.Dq shim
+that precedes any network layer headers, just after data
+link layer headers.
+.Ss MPLS shim header structure
+In network bit order:
+.Bd -literal
+-------------------------------------------
+| | | | |
+| Label | Exp. | BoS | TTL |
+| 20 bits | 3 bits | 1 bit | 8 bits |
+| | | | |
+-------------------------------------------
+.Ed
+.Bl -tag -width "Bottom of stack"
+.It Label
+20 bits representing FEC, consequently the only information
+used to forward the frame to next-hop
+.It Experimental
+3 bits that are sometimes used for specifying a type of service
+.It Bottom of stack
+1 bit that is set for the last entry in the shim
+stack and 0 for all others.
+This way, multiple labels can
+be prepended to a single packet.
+.It TTL
+8 bits, representing Time to Live, decremented at every LSR.
+.El
+.Sh USAGE
+The MPLS behavior is controlled by the
+.Li net.mpls
+.Xr sysctl 8
+tree:
+.Bl -tag -width "net.mpls.inet6_map_prec"
+.It Li net.mpls.accept
+If zero, MPLS frames are dropped on sight on ingress interfaces.
+.It Li net.mpls.forwarding
+If zero, MPLS frames are not forwarded to next-hop.
+.It Li net.mpls.ttl
+The default ttl for self generated MPLS frames.
+.It Li net.mpls.inet_mapttl
+If set, TTL field from IP header will be mapped
+into the MPLS shim on encapsulation, and the TTL field from MPLS shim
+will be copied into IP header on decapsulation.
+.It Li net.mpls.inet6_mapttl
+The IPv6 version of the above.
+.It Li net.mpls.inet_map_prec
+If set, precedence field from IP header will be
+mapped into MPLS shim EXP bits on encapsulation, and the MPLS EXP
+field will be copied into IP Precedence field on decapsulation.
+.It Li net.mpls.inet6_map_prec
+The IPv6 version of the above.
+.It Li net.mpls.icmp_respond
+Returns ICMP TTL exceeded in transit when an MPLS
+frame is dropped because of TTL = 0 on egress interface.
+.El
+In order to encapsulate and decapsulate to and from MPLS, an mpls
+pseudo-interface must be created and packets that should be encapsulated
+must be routed to that interface.
+.Pp
+.Dq Pure
+MPLS routes can be created using
+.Dv AF_MPLS
+.Li sa_family
+sockaddrs for destination and tag fields.
+Other protocols can be encapsulated using
+routes pointing to mpls pseudo-interfaces, and
+.Dv AF_MPLS
+sockaddrs for tags.
+Decapsulation can be made using values of reserved labels set in
+the tag field (see below).
+For more information about doing this using
+userland utilities see the
+.Sx EXAMPLES
+section of this manual page.
+.Pp
+The
+.Xr netstat 1
+and
+.Xr route 8
+utilities should be used to manage routes from userland.
+.Pp
+.Xr ldpd 8
+should be used in order to automatically import, manage and
+distribute labels among LSRs in the same MPLS domain.
+.Ss RESERVED LABELS
+MPLS labels 0 through 15 are reserved.
+Out of those, only four are currently defined:
+.Bl -tag -width X
+.It 0
+IPv4 Explicit NULL label.
+This label value is only legal at the bottom of the label stack.
+It indicates that the label stack must be popped,
+and the forwarding of the packet must then be based on the IPv4 header.
+.It 1
+Router Alert Label.
+Currently not implemented in
+.Nx .
+.It 2
+IPv6 Explicit NULL label.
+It indicates that the label stack must be popped, and the forwarding
+of the packet must then be based on the IPv6 header.
+.It 3
+Implicit NULL label.
+This is a label that an LSR may assign and
+distribute, but which never actually appears in the encapsulation.
+When an LSR would otherwise replace the label at the top of the stack
+with a new label, but the new label is
+.Dq Implicit NULL ,
+the LSR will pop the stack instead of doing the replacement.
+.El
+.Sh EXAMPLES
+.Bl -enum
+.It
+Create an MPLS interface and set an IP address:
+.Bd -literal
+# ifconfig mpls0 create up
+# ifconfig mpls0 inet 192.168.0.1/32
+.Ed
+.It
+Route IP packets into MPLS domain with a specific tag
+.Bd -literal
+# route add 10.0.0.0/8 -ifp mpls0 -tag 25 192.168.1.100
+.Ed
+.It
+Create a static MPLS forwarding rule - swap the incoming
+label 50 to 33 and forward the frame to 192.168.1.101 and verify
+the route
+.Bd -literal
+# route add -mpls 50 -tag 33 -inet 192.168.1.101
+add host 50: gateway 192.168.1.101
+# route -n get -mpls 50
+ route to: 50
+destination: 50
+ gateway: 192.168.1.101
+ Tag: 33
+ local addr: 192.168.1.180
+ interface: sk0
+ flags: \*[Lt]UP,GATEWAY,HOST,DONE,STATIC\*[Gt]
+recvpipe sendpipe ssthresh rtt,msec rttvar hopcount mtu expire
+ 0 0 0 0 0 0 0 0
+sockaddrs: \*[Lt]DST,GATEWAY,IFP,IFA,TAG\*[Gt]
+.Ed
+.It
+Route IP packets into MPLS domain but use a different source
+address for local generated packets.
+.Bd -literal
+# route add 10.0.0.0/8 -ifa 192.168.1.180 -ifp mpls0 -tag 25 192.168.1.100
+.Ed
+For the latter example, setting an IP address for the mpls0 interface
+is not necessary.
+.It
+Route MPLS packets encapsulated with label 60 to 192.168.1.100 and POP label
+.Bd -literal
+# route add -mpls 60 -tag 3 -inet 192.168.1.100
+.Ed
+.El
+.Sh SEE ALSO
+.Xr netstat 1 ,
+.Xr route 4 ,
+.Xr ldpd 8 ,
+.Xr route 8 ,
+.Xr sysctl 8
+.Rs
+.%R RFC 3031
+.%T Multiprotocol Label Switching Architecture
+.Re
+.Rs
+.%R RFC 3032
+.%T MPLS Label Stack Encoding
+.Re
+.Sh HISTORY
+The
+.Nm
+support appeared in
+.Nx 6.0 .
+.Sh SECURITY CONSIDERATIONS
+User must be aware that encapsulating IP packets in MPLS implies a
+major security effect when using firewalls.
+Currently neither
+.Xr ipf 4
+nor
+.Xr pf 4
+implement the heuristics in order to look inside an MPLS frame.
+Moreover, it's technically impossible in most cases for an LSR to
+know information related to encapsulated packet.
+Therefore, MPLS Domains should be strictly controlled and, in most
+cases, limited to trusted connections inside the same Autonomous
+System.
+.Pp
+Users must be aware that the MPLS forwarding domain is entirely separated
+from the inner (IP, IPv6 etc.) forwarding domain and once a packet is
+encapsulated in MPLS, the former forwarding is used.
+This could result in a different path for MPLS encapsulated packets
+than the original non-MPLS one.
+.Pp
+IP or IPv6 forwarding is not necessary for MPLS forwarding. Your system
+may still forward IP or IPv6 packets encapsulated into MPLS if
+net.mpls.forwarding is set.
