.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "MAST" 4 "" "" ""
.SH NAME
mast \- pseudo-driver for attaching tunnelling protocols
.SH "SYNOPSIS"
.ad l
.hy 0


#include <net/mast.h>

.sp
.HP 27
struct\ device\ *\fBmast_init\fR\ (int\ \fIfamily\fR, struct\ mast_callbacks\ *\fIcallbacks\fR, unsigned\ int\ \fIflags\fR, char\ *\fIunit\fR, unsigned\ int\ \fImax_flowref\fR, void\ *\fIcontext\fR);
.HP 18
int\ \fBpacket_encap\fR\ (struct\ device\ *\fImast\fR, void\ *\fIcontext\fR, struct\ skb\ *\fIskb\fR, int\ \fIflowref\fR);
.HP 18
int\ \fBlink_inquire\fR\ (struct\ device\ *\fImast\fR, void\ *\fIcontext\fR);
.HP 19
int\ \fBmast_linkstat\fR\ (struct\ device\ *\fImast\fR, int\ \fIflowref\fR, int\ \fIstatus\fR);
.HP 23
int\ \fBmast_setreference\fR\ (struct\ device\ *\fImast\fR, int\ \fIdefault_flowref\fR);
.HP 23
int\ \fBmast_setneighbour\fR\ (struct\ device\ *\fImast\fR, struct\ sockaddr\ *\fIsource\fR, struct\ sockaddr\ *\fIdestination\fR, int\ \fIflowref\fR);
.ad
.hy

.SH "DESCRIPTION"

.PP
The mast network interface is a pseudo device that allows tunnelling protocols to be attached to the base of the device, and routing protocols and daemons to the top. The metaphor is that of a blimp attached to a mooring post or mast.

.PP
 mast stands for Mooring And Status Tunnel.

.PP
The network interfaces are named anything that can fit in 16 printable characters. We suggest \fBmast0\fR, \fBmast1\fR and so on, as many as desired, but they could also be named \fBmast\-rome\fR or even \fBvpn\-rome\fR or other more descriptive names. The names should be unique in the namespace of the network devices.

.PP
They are created with the "ip tunnel" command. (XXX? are they. Maybe, maybe not.)

.PP
The mast device provides a way to anchor routing daemon to virtual topologies. It provides a consistent abstraction to various kinds of tunnelling technology: IP\-encap (protocol 4), IPv6 (protocol 41), GRE (protocol 47), ESP (protocol 50), AH (protocol 51), IPIP (protocol 94) and ENCAP (protocol 98).

.PP
There are three ways that a mast can be used. They correspond to how additional information (i.e. policy) is attached to the packets that are directed toward the device. mast devices are bi\-directional devices, but the flow of the packets that emerge do so in a uniform manner.

.PP
The first way is called the PPP method. A mast is considered to be portal to to which packets that need a predefined kind of encapsulation may be sent. The mast acts as a point to point device \- a virtual leased line \- sending all packets into the an underlying tunnel mechanism, having attached a default security policy to each packet. (As is described under "SECURITY POLICY", the nfmark is used). A mast device used in this way should be indistinguishable from a SLIP interface \- it has no layer two protocol. The layer two link status of the mast device may reflect the state of the dead peer detection status for the remote end point, if this feature has been enabled.

.PP
The second way that a mast device may be used is as an entry into a non\-broadcast, multiple access encapsulation media. The is the NFMARK method. The choice of a particular tunnel is indicated by setting bits in the control structure (the skb). This is described under "SECURITY POLICY".

.PP
The third way that a mast device may be used is with a virtual link layer. This is the NMBA method. This is the This is a variation of the previous method \- the device is still a non\-broadcast, multiple access device, except that the mast device supports a layer two similar to ARP. The layer two information that the network stack attaches to each packet will be used to determine which tunnel will be used. The mast device will keep the neighbour cache updated with liveness info. If the tunnel to a given neighbour is known to be down (such as, because of a lack of a key, or expiration of such), then the neighbour cache entry will be removed.

.PP
Packets that are sent upwards (in the direction of decapsulation) from the mast device will be marked by the tunnel on which the packet was received. The choice of which mast device to emerge from is also defined by the tunnel decapsulation mechanism. Typically, a unique device will be created per major policy category. This is done to simplify the firewall rules.

.PP
The PPP method is most appropriate for use on the client side of a road warrior configuration, or when there is a sufficiently small number of VPN tunnels that it is practical (or desireable) for each tunnel to have its own device associated with it. The simplification of firewall rules for output is the primary benefit of this mode.

.PP
The NFMARK mechanism is used by more traditional VPN topologies, and by Opportunistic Encryption. These two categories of use mandate a different output device per major policy. Both would use specific setting of policy bits (skb\->nfmark) for selection of outgoing policy.

.PP
The NMBA mechanism, where an ARP\-like layer two is maintained, is most appropriate for layered systems like the xbone, where there may be too many tunnels for it to be practical to create a device per tunnel. At the same time, the reachability information that the layer\-two tables provide can be used by routing systems to determine the optimal path.

.PP
The mast device permits kernel code to create them with: 

.nf

	struct device *mast;

	mast = mast_init(family, callbacks, flags,
	                 unit, max_flowref, context)

.fi
 

.PP
A new mast device is create per address family. This is not strictly necessary, but may simplify policy checks as well.

.TP
\fIfamily\fR
is AF_INET or AF_INET6.

.TP
\fIflags\fR
is one of

MAST_PPP:the device will operate only as a point to point device ignoring any bits set in the nfmark field.

MAST_NFMARK: the device will examine the nfmark field, extracting bits from this field to form an SArefence, which is passed to the encapsulation routine.

MAST_NBMA: the device will examine virtual layer two information pointed to by the skb\->mac.raw field.

.TP
\fIunit\fR
is an integer X, the unit number, and results in the creation of the appropriate mastX device. If this unit number is in use, then an error will result, and NULL will be returned.

.TP
\fImax_flowref\fR
is the theoretical highest flowref that can be assigned. It is recorded for sanity checking. It may also be used for scaling of virtual layer\-2 structures.

.TP
\fIcallbacks\fR
The callback is a structure containing function pointers for \fBpacket_encap\fR and \fBlink_inquire\fR.

.TP
\fIcontext\fR
The context contains mast sub\-type\-specific information.

.TP
\fImast\fR
The mast is a struct device * previously created by \fBmast_init\fR.

.TP
\fIskb\fR
The skb is a struct sk_buff * passed down for processing.

.TP
\fIflowref\fR
The flowref is a reference to a policy to be used for packet processing.

.TP
\fIstatus\fR
The status is a flag indicating the link state.

.TP
\fIdefault_flowref\fR
The default_flowref is a reference to a default policy to be used for packet processing.

.TP
\fIsource\fR and \fIdestination\fR
The source and destination are IPv4 or IPv6 addresses.

.PP
The \fBpacket_encap\fR callback is called by the mast device when a packet has been forwarded into the mast device in some fashion. The function will be called with the \fIcontext\fR that was provided in the \fBmast_init\fR call.

.PP
The packet to be processed will be passed in the \fIskb\fR parameter. The flow reference will have been extracted and passed in the \fIflowref\fR parameter.

.PP
The link_inquire() function is a request from the mast device to have its link status updated by the tunnel apparatus. Link status can be updated with the \fBmast_linkstat\fR function.

.PP
In the link_inquire call(), status is up==1/down==0. Some mast devices may maintain per\-flowref link status (in the pseudo\-ARP case), in which case the flowref should be provided. A flowref of \-1 updates the global link status.

.PP
A mast device may have its default flow reference set via the \fBmast_setflowref\fR function.

.PP
A mast device examines packets that it receives, looks at the appropriate parts of the nfmark and turns that into the reference #. If these bits are zero, then the default flow reference is used. If the default flow reference is not set, then the packet is dropped as a transmit error.

.PP
The \fBmast_setneighbour\fR function will be filled out at a later time.

.SH "SECURITY POLICY"

.PP
When the mast device is configured to be in \fBMAST_NFMARK\fR mode, it will examine the skb\->nfmark field of each incoming packet. The upper 24 bits of the nfmark will be extracted. If bit 31 is set, then the nfmark will be considered to be have been initialized. Bits 8 through 30 are then shifted to the right, resulting in a 23 bit number. This is considered the flowref.

.PP
If the bit is not set, then the packet will have the default flow reference applied to it.

.SH AUTHOR
Michael Richardson <mcr@sandelman.ottawa.on.ca>.