diff options
Diffstat (limited to 'static/freebsd/man4/ng_l2tp.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ng_l2tp.4 3.html | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/static/freebsd/man4/ng_l2tp.4 3.html b/static/freebsd/man4/ng_l2tp.4 3.html new file mode 100644 index 00000000..ec4706da --- /dev/null +++ b/static/freebsd/man4/ng_l2tp.4 3.html @@ -0,0 +1,246 @@ +<table class="head"> + <tr> + <td class="head-ltitle">NG_L2TP(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">NG_L2TP(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">ng_l2tp</code> — <span class="Nd">L2TP + protocol netgraph node type</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">sys/types.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">netgraph/ng_l2tp.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">l2tp</code> node type implements the + encapsulation layer of the L2TP protocol as described in RFC 2661. This + includes adding the L2TP packet header for outgoing packets and verifying + and removing it for incoming packets. The node maintains the L2TP sequence + number state and handles control session packet acknowledgment and + retransmission.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HOOKS"><a class="permalink" href="#HOOKS">HOOKS</a></h1> +<p class="Pp">The <code class="Nm">l2tp</code> node type supports the following + hooks:</p> +<dl class="Bl-tag"> + <dt id="lower"><var class="Va">lower</var></dt> + <dd>L2TP frames.</dd> + <dt id="ctrl"><var class="Va">ctrl</var></dt> + <dd>Control packets.</dd> + <dt id="session_hhhh"><var class="Va">session_hhhh</var></dt> + <dd>Session 0xhhhh data packets.</dd> +</dl> +<p class="Pp">L2TP control and data packets are transmitted to, and received + from, the L2TP peer via the <code class="Dv">lower</code> hook. Typically + this hook would be connected to the <code class="Dv">inet/dgram/udp</code> + hook of an <a class="Xr">ng_ksocket(4)</a> node for L2TP over UDP.</p> +<p class="Pp">The <code class="Dv">ctrl</code> hook connects to the local L2TP + management entity. L2TP control messages (without any L2TP headers) are + transmitted and received on this hook. Messages written to this hook are + guaranteed to be delivered to the peer reliably, in order, and without + duplicates.</p> +<p class="Pp">Packets written to the <code class="Dv">ctrl</code> hook must + contain a two byte session ID prepended to the frame (in network order). + This session ID is copied to the outgoing L2TP header. Similarly, packets + read from the <code class="Dv">ctrl</code> hook will have the received + session ID prepended.</p> +<p class="Pp">Once an L2TP session has been created, the corresponding session + hook may be used to transmit and receive the session's data frames: for the + session with session ID <code class="Dv">0xabcd</code>, the hook is named + <code class="Dv">session_abcd</code>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CONTROL_MESSAGES"><a class="permalink" href="#CONTROL_MESSAGES">CONTROL + MESSAGES</a></h1> +<p class="Pp">This node type supports the generic control messages, plus the + following:</p> +<dl class="Bl-tag"> + <dt id="NGM_L2TP_SET_CONFIG"><a class="permalink" href="#NGM_L2TP_SET_CONFIG"><code class="Dv">NGM_L2TP_SET_CONFIG</code></a> + (<code class="Ic">setconfig</code>)</dt> + <dd>This command updates the configuration of the node. It takes a + <var class="Vt">struct ng_l2tp_config</var> as an argument: + <div class="Bd Pp Li"> + <pre>/* Configuration for a node */ +struct ng_l2tp_config { + u_char enabled; /* enables traffic flow */ + u_char match_id; /* tunnel id must match 'tunnel_id' */ + uint16_t tunnel_id; /* local tunnel id */ + uint16_t peer_id; /* peer's tunnel id */ + uint16_t peer_win; /* peer's max recv window size */ + uint16_t rexmit_max; /* max retransmits before failure */ + uint16_t rexmit_max_to; /* max delay between retransmits */ +};</pre> + </div> + <p class="Pp">The <var class="Va">enabled</var> field enables packet + processing. Each time this field is changed back to zero the sequence + number state is reset. In this way, reuse of a node is possible.</p> + <p class="Pp">The <var class="Va">tunnel_id</var> field configures the local + tunnel ID for the control connection. The <var class="Va">match_id</var> + field determines how incoming L2TP packets with a tunnel ID field + different from <var class="Va">tunnel_id</var> are handled. If + <var class="Va">match_id</var> is non-zero, they will be dropped; + otherwise, they will be dropped only if the tunnel ID is non-zero. + Typically <var class="Va">tunnel_id</var> is set to the local tunnel ID + as soon as it is known and <var class="Va">match_id</var> is set to + non-zero after receipt of the SCCRP or SCCCN control message.</p> + <p class="Pp">The peer's tunnel ID should be set in + <var class="Va">peer_id</var> as soon as it is learned, typically after + receipt of a SCCRQ or SCCRP control message. This value is copied into + the L2TP header for outgoing packets.</p> + <p class="Pp">The <var class="Va">peer_win</var> field should be set from + the “Receive Window Size” AVP received from the peer. The + default value for this field is one; zero is an invalid value. As long + as <var class="Va">enabled</var> is non-zero, this value may not be + decreased.</p> + <p class="Pp">The <var class="Va">rexmit_max</var> and + <var class="Va">rexmit_max_to</var> fields configure packet + retransmission. <var class="Va">rexmit_max_to</var> is the maximum + retransmission delay between packets, in seconds. The retransmit delay + will start at a small value and increase exponentially up to this limit. + The <var class="Va">rexmit_max</var> sets the maximum number of times a + packet will be retransmitted without being acknowledged before a failure + condition is declared. Once a failure condition is declared, each + additional retransmission will cause the <code class="Nm">l2tp</code> + node to send a <code class="Dv">NGM_L2TP_ACK_FAILURE</code> + (<code class="Ic">ackfailure</code>) control message back to the node + that sent the last <code class="Dv">NGM_L2TP_SET_CONFIG</code>. + Appropriate action should then be taken to shutdown the control + connection.</p> + </dd> + <dt id="NGM_L2TP_GET_CONFIG"><a class="permalink" href="#NGM_L2TP_GET_CONFIG"><code class="Dv">NGM_L2TP_GET_CONFIG</code></a> + (<code class="Ic">getconfig</code>)</dt> + <dd>Returns the current configuration as a <var class="Vt">struct + ng_l2tp_config</var>.</dd> + <dt id="NGM_L2TP_SET_SESS_CONFIG"><a class="permalink" href="#NGM_L2TP_SET_SESS_CONFIG"><code class="Dv">NGM_L2TP_SET_SESS_CONFIG</code></a> + (<code class="Ic">setsessconfig</code>)</dt> + <dd>This control message configures a single data session. The corresponding + hook must already be connected before sending this command. The argument + is a <var class="Vt">struct ng_l2tp_sess_config</var>: + <div class="Bd Pp Li"> + <pre>/* Configuration for a session hook */ +struct ng_l2tp_sess_config { + uint16_t session_id; /* local session id */ + uint16_t peer_id; /* peer's session id */ + u_char control_dseq; /* whether we control data sequencing */ + u_char enable_dseq; /* whether to enable data sequencing */ + u_char include_length; /* whether to include length field */ +};</pre> + </div> + <p class="Pp">The <var class="Va">session_id</var> and + <var class="Va">peer_id</var> fields configure the local and remote + session IDs, respectively.</p> + <p class="Pp">The <var class="Va">control_dseq</var> and + <var class="Va">enable_dseq</var> fields determine whether sequence + numbers are used with L2TP data packets. If + <var class="Va">enable_dseq</var> is zero, then no sequence numbers are + sent and incoming sequence numbers are ignored. Otherwise, sequence + numbers are included on outgoing packets and checked on incoming + packets.</p> + <p class="Pp">If <var class="Va">control_dseq</var> is non-zero, then the + setting of <var class="Va">enable_dseq</var> will never change except by + another <code class="Dv">NGM_L2TP_SET_SESS_CONFIG</code> control + message. If <var class="Va">control_dseq</var> is zero, then the peer + controls whether sequence numbers are used: if an incoming L2TP data + packet contains sequence numbers, <var class="Va">enable_dseq</var> is + set to one, and conversely if an incoming L2TP data packet does not + contain sequence numbers, <var class="Va">enable_dseq</var> is set to + zero. The current value of <var class="Va">enable_dseq</var> is always + accessible via the <code class="Dv">NGM_L2TP_GET_SESS_CONFIG</code> + control message (see below). Typically an LNS would set + <var class="Va">control_dseq</var> to one while a LAC would set + <var class="Va">control_dseq</var> to zero (if the Sequencing Required + AVP were not sent), thus giving control of data packet sequencing to the + LNS.</p> + <p class="Pp">The <var class="Va">include_length</var> field determines + whether the L2TP header length field is included in outgoing L2TP data + packets. For incoming packets, the L2TP length field is always checked + when present.</p> + </dd> + <dt id="NGM_L2TP_GET_SESS_CONFIG"><a class="permalink" href="#NGM_L2TP_GET_SESS_CONFIG"><code class="Dv">NGM_L2TP_GET_SESS_CONFIG</code></a> + (<code class="Ic">getsessconfig</code>)</dt> + <dd>This command takes a two byte session ID as an argument and returns the + current configuration for the corresponding data session as a + <var class="Vt">struct ng_l2tp_sess_config</var>. The corresponding + session hook must be connected.</dd> + <dt id="NGM_L2TP_GET_STATS"><a class="permalink" href="#NGM_L2TP_GET_STATS"><code class="Dv">NGM_L2TP_GET_STATS</code></a> + (<code class="Ic">getstats</code>)</dt> + <dd>This command returns a <var class="Vt">struct ng_l2tp_stats</var> + containing statistics of the L2TP tunnel.</dd> + <dt id="NGM_L2TP_CLR_STATS"><a class="permalink" href="#NGM_L2TP_CLR_STATS"><code class="Dv">NGM_L2TP_CLR_STATS</code></a> + (<code class="Ic">clrstats</code>)</dt> + <dd>This command clears the statistics for the L2TP tunnel.</dd> + <dt id="NGM_L2TP_GETCLR_STATS"><a class="permalink" href="#NGM_L2TP_GETCLR_STATS"><code class="Dv">NGM_L2TP_GETCLR_STATS</code></a> + (<code class="Ic">getclrstats</code>)</dt> + <dd>Same as <code class="Dv">NGM_L2TP_GET_STATS</code>, but also atomically + clears the statistics as well.</dd> + <dt id="NGM_L2TP_GET_SESSION_STATS"><a class="permalink" href="#NGM_L2TP_GET_SESSION_STATS"><code class="Dv">NGM_L2TP_GET_SESSION_STATS</code></a> + (<code class="Ic">getsessstats</code>)</dt> + <dd>This command takes a two byte session ID as an argument and returns a + <var class="Vt">struct ng_l2tp_session_stats</var> containing statistics + for the corresponding data session. The corresponding session hook must be + connected.</dd> + <dt id="NGM_L2TP_CLR_SESSION_STATS"><a class="permalink" href="#NGM_L2TP_CLR_SESSION_STATS"><code class="Dv">NGM_L2TP_CLR_SESSION_STATS</code></a> + (<code class="Ic">clrsessstats</code>)</dt> + <dd>This command takes a two byte session ID as an argument and clears the + statistics for that data session. The corresponding session hook must be + connected.</dd> + <dt id="NGM_L2TP_GETCLR_SESSION_STATS"><a class="permalink" href="#NGM_L2TP_GETCLR_SESSION_STATS"><code class="Dv">NGM_L2TP_GETCLR_SESSION_STATS</code></a> + (<code class="Ic">getclrsessstats</code>)</dt> + <dd>Same as <code class="Dv">NGM_L2TP_GET_SESSION_STATS</code>, but also + atomically clears the statistics as well.</dd> + <dt id="NGM_L2TP_SET_SEQ"><a class="permalink" href="#NGM_L2TP_SET_SEQ"><code class="Dv">NGM_L2TP_SET_SEQ</code></a> + (<code class="Ic">setsequence</code>)</dt> + <dd>This command sets the sequence numbers of a not yet enabled node. It takes + a <var class="Vt">struct ng_l2tp_seq_config</var> as argument, where + <var class="Va">xack</var> and <var class="Va">nr</var> respectively + <var class="Va">ns</var> and <var class="Va">rack</var> must be the same. + This option is particularly useful if one receives and processes the first + packet entirely in userspace and wants to hand over further processing to + the node.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SHUTDOWN"><a class="permalink" href="#SHUTDOWN">SHUTDOWN</a></h1> +<p class="Pp">This node shuts down upon receipt of a + <code class="Dv">NGM_SHUTDOWN</code> control message, or when all hooks have + been disconnected.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">netgraph(4)</a>, <a class="Xr">ng_ksocket(4)</a>, + <a class="Xr">ng_ppp(4)</a>, <a class="Xr">ng_pptpgre(4)</a>, + <a class="Xr">ngctl(8)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">W. Townsley</span>, + <span class="RsA">A. Valencia</span>, <span class="RsA">A. Rubens</span>, + <span class="RsA">G. Pall</span>, <span class="RsA">G. Zorn</span>, and + <span class="RsA">B. Palter</span>, <span class="RsT">Layer Two Tunneling + Protocol L2TP</span>, <span class="RsO">RFC 2661</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">l2tp</code> node type was developed at Packet + Design, LLC, <span class="Pa">http://www.packetdesign.com/</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Archie Cobbs</span> + <<a class="Mt" href="mailto:archie@packetdesign.com">archie@packetdesign.com</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">November 13, 2012</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |