diff options
Diffstat (limited to 'static/freebsd/man4/ng_ppp.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ng_ppp.4 3.html | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/static/freebsd/man4/ng_ppp.4 3.html b/static/freebsd/man4/ng_ppp.4 3.html new file mode 100644 index 00000000..56c18b90 --- /dev/null +++ b/static/freebsd/man4/ng_ppp.4 3.html @@ -0,0 +1,358 @@ +<table class="head"> + <tr> + <td class="head-ltitle">NG_PPP(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">NG_PPP(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_ppp</code> — <span class="Nd">PPP + 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_ppp.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">ppp</code> node type performs multiplexing + for the PPP protocol. It handles only packets that contain data, and + forwards protocol negotiation and control packets to a separate controlling + entity (e.g., a user-land daemon). This approach combines the fast dispatch + of kernel implementations with the configuration flexibility of a user-land + implementations. The PPP node type directly supports multi-link PPP, Van + Jacobson compression, PPP compression, PPP encryption, and the IP, IPX, and + AppleTalk protocols. A single PPP node corresponds to one PPP multi-link + bundle.</p> +<p class="Pp">There is a separate hook for each PPP link in the bundle, plus + several hooks corresponding to the directly supported protocols. For + compression and encryption, separate attached nodes are required to do the + actual work. The node type used will of course depend on the algorithm + negotiated. There is also a <code class="Dv">bypass</code> hook which is + used to handle any protocol not directly supported by the node. This + includes all of the control protocols: LCP, IPCP, CCP, etc. Typically this + node is connected to a user-land daemon via a <a class="Xr">ng_socket(4)</a> + type node.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="ENABLING_FUNCTIONALITY"><a class="permalink" href="#ENABLING_FUNCTIONALITY">ENABLING + FUNCTIONALITY</a></h1> +<p class="Pp">In general, the PPP node enables a specific link or functionality + when (a) a <code class="Dv">NGM_PPP_SET_CONFIG</code> message has been + received which enables it, and (b) the corresponding hook(s) are connected. + This allows the controlling entity to use either method (a) or (b) (or both) + to control the node's behavior. When a link is connected but disabled, + traffic can still flow on the link via the <code class="Dv">bypass</code> + hook (see below).</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="LINK_HOOKS"><a class="permalink" href="#LINK_HOOKS">LINK + HOOKS</a></h1> +<p class="Pp">During normal operation, the individual PPP links are connected to + hooks <code class="Dv">link0</code>, <code class="Dv">link1</code>, etc. Up + to <code class="Dv">NG_PPP_MAX_LINKS</code> links are supported. These + device-independent hooks transmit and receive full PPP frames, which include + the PPP protocol, address, control, and information fields, but no checksum + or other link-specific fields.</p> +<p class="Pp">On outgoing frames, when protocol compression has been enabled and + the protocol number is suitable for compression, the protocol field will be + compressed (i.e., sent as one byte instead of two). Either compressed or + uncompressed protocol fields are accepted on incoming frames. Similarly, if + address and control field compression has been enabled for the link, the + address and control fields will be omitted (except for LCP frames as + required by the standards). Incoming frames have the address and control + fields stripped automatically if present.</p> +<p class="Pp">Since all negotiation is handled outside the PPP node, the links + should not be connected and enabled until the corresponding link has reached + the network phase (i.e., LCP negotiation and authentication have completed + successfully) and the PPP node has been informed of the link parameters via + the <code class="Dv">NGM_PPP_LINK_CONFIG</code> message.</p> +<p class="Pp">When a link is connected but disabled, all received frames are + forwarded directly out the <code class="Dv">bypass</code> hook, and + conversely, frames may be transmitted via the <code class="Dv">bypass</code> + hook as well. This mode is appropriate for the link authentication phase. As + soon as the link is enabled, the PPP node will begin processing frames + received on the link.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="COMPRESSION_AND_ENCRYPTION"><a class="permalink" href="#COMPRESSION_AND_ENCRYPTION">COMPRESSION + AND ENCRYPTION</a></h1> +<p class="Pp">Compression is supported via two hooks, + <code class="Dv">compress</code> and <code class="Dv">decompress</code>. + Compression and decompression can be enabled by toggling the + <var class="Vt">enableCompression</var> and + <var class="Vt">enableDecompression</var> fields of the node configuration + structure. (See below.) If <var class="Vt">enableCompression</var> is set to + <code class="Dv">NG_PPP_COMPRESS_SIMPLE</code>, then all outgoing frames are + sent to the <code class="Dv">compress</code> hook and all packets received + on this hook are expected to be compressed, so the COMPD tag is put on them + unconditionally. If <var class="Vt">enableCompression</var> is set to + <code class="Dv">NG_PPP_COMPRESS_FULL</code>, then packets received on the + <code class="Dv">compress</code> hook are resent as is. The compressor node + should put the tag, if the packet was compressed. If + <var class="Vt">enableDecompression</var> is set to + <code class="Dv">NG_PPP_DECOMPRESS_SIMPLE</code>, then the node will sent to + the <code class="Dv">decompress</code> hook only those frames, that are + marked with the COMPD tag. If <var class="Vt">enableDecompression</var> is + set to <code class="Dv">NG_PPP_DECOMPRESS_FULL</code>, then the node will + sent all incoming packets to the <code class="Dv">decompress</code> hook. + Compression and decompression can be completely disabled by setting the + <var class="Vt">enableCompression</var> and + <var class="Vt">enableDecompression</var> fields to the + <code class="Dv">NG_PPP_COMPRESS_NONE</code> and + <code class="Dv">NG_PPP_DECOMPRESS_NONE</code>, respectively.</p> +<p class="Pp">Encryption works exactly analogously via the + <code class="Dv">encrypt</code> and <code class="Dv">decrypt</code> nodes. + Data is always compressed before being encrypted, and decrypted before being + decompressed.</p> +<p class="Pp">Only bundle-level compression and encryption is directly + supported; link-level compression and encryption can be handled + transparently by downstream nodes.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="VAN_JACOBSON_COMPRESSION"><a class="permalink" href="#VAN_JACOBSON_COMPRESSION">VAN + JACOBSON COMPRESSION</a></h1> +<p class="Pp">When all of the <code class="Dv">vjc_ip</code>, + <code class="Dv">vjc_vjcomp</code>, <code class="Dv">vjc_vjuncomp</code>, + and <code class="Dv">vjc_vjip</code> hooks are connected, and the + corresponding configuration flag is enabled, Van Jacobson compression and/or + decompression will become active. Normally these hooks connect to the + corresponding hooks of a single <a class="Xr">ng_vjc(4)</a> node. The PPP + node is compatible with the “pass through” modes of the + <a class="Xr">ng_vjc(4)</a> node type.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BYPASS_HOOK"><a class="permalink" href="#BYPASS_HOOK">BYPASS + HOOK</a></h1> +<p class="Pp">When a frame is received on a link with an unsupported protocol, + or a protocol which is disabled or for which the corresponding hook is + unconnected, the PPP node forwards the frame out the + <code class="Dv">bypass</code> hook, prepended with a four byte prefix. This + first two bytes of the prefix indicate the link number on which the frame + was received (in network order). For such frames received over the bundle + (i.e., encapsulated in the multi-link protocol), the special link number + <code class="Dv">NG_PPP_BUNDLE_LINKNUM</code> is used. After the two byte + link number is the two byte PPP protocol number (also in network order). The + PPP protocol number is two bytes long even if the original frame was + protocol compressed.</p> +<p class="Pp">Conversely, any data written to the <code class="Dv">bypass</code> + hook is assumed to be in this same format. The four byte header is stripped + off, the PPP protocol number is prepended (possibly compressed), and the + frame is delivered over the desired link. If the link number is + <code class="Dv">NG_PPP_BUNDLE_LINKNUM</code> the frame will be delivered + over the multi-link bundle; or, if multi-link is disabled, over the (single) + PPP link.</p> +<p class="Pp">Typically when the controlling entity receives an unexpected + packet on the <code class="Dv">bypass</code> hook it responds either by + dropping the frame (if it is not ready for the protocol) or with an LCP + protocol reject (if it does not recognize or expect the protocol).</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MULTILINK_OPERATION"><a class="permalink" href="#MULTILINK_OPERATION">MULTILINK + OPERATION</a></h1> +<p class="Pp">To enable multi-link PPP, the corresponding configuration flag + must be set and at least one link connected. The PPP node will not allow + more than one link to be connected if multi-link is not enabled, nor will it + allow certain multi-link settings to be changed while multi-link operation + is active (e.g., short sequence number header format).</p> +<p class="Pp">Since packets are sent as fragments across multiple individual + links, it is important that when a link goes down the PPP node is notified + immediately, either by disconnecting the corresponding hook or disabling the + link via the <code class="Dv">NGM_PPP_SET_CONFIG</code> control message.</p> +<p class="Pp" id="round-robin">Each link has configuration parameters for + latency (specified in milliseconds) and bandwidth (specified in tens of + bytes per second). The PPP node can be configured for + <a class="permalink" href="#round-robin"><i class="Em">round-robin</i></a> + or + <a class="permalink" href="#optimized"><i class="Em" id="optimized">optimized</i></a> + packet delivery.</p> +<p class="Pp">When configured for round-robin delivery, the latency and + bandwidth values are ignored and the PPP node simply sends each frame as a + single fragment, alternating frames across all the links in the bundle. This + scheme has the advantage that even if one link fails silently, some packets + will still get through. It has the disadvantage of sub-optimal overall + bundle latency, which is important for interactive response time, and + sub-optimal overall bundle bandwidth when links with different bandwidths + exist in the same bundle.</p> +<p class="Pp">When configured for optimal delivery, the PPP node distributes the + packet across the links in a way that minimizes the time it takes for the + completed packet to be received by the far end. This involves taking into + account each link's latency, bandwidth, and current queue length. Therefore + these numbers should be configured as accurately as possible. The algorithm + does require some computation, so may not be appropriate for very slow + machines and/or very fast links.</p> +<p class="Pp">As a special case, if all links have identical latency and + bandwidth, then the above algorithm is disabled (because it is unnecessary) + and the PPP node simply fragments frames into equal sized portions across + all of the links.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HOOKS"><a class="permalink" href="#HOOKS">HOOKS</a></h1> +<p class="Pp">This node type supports the following hooks:</p> +<dl class="Bl-tag"> + <dt id="link_N_"><var class="Va">link<N></var></dt> + <dd>Individual PPP link number <code class="Dv"><N></code></dd> + <dt id="compress"><var class="Va">compress</var></dt> + <dd>Connection to compression engine</dd> + <dt id="decompress"><var class="Va">decompress</var></dt> + <dd>Connection to decompression engine</dd> + <dt id="encrypt"><var class="Va">encrypt</var></dt> + <dd>Connection to encryption engine</dd> + <dt id="decrypt"><var class="Va">decrypt</var></dt> + <dd>Connection to decryption engine</dd> + <dt id="vjc_ip"><var class="Va">vjc_ip</var></dt> + <dd>Connection to <a class="Xr">ng_vjc(4)</a> <code class="Dv">ip</code> + hook</dd> + <dt id="vjc_vjcomp"><var class="Va">vjc_vjcomp</var></dt> + <dd>Connection to <a class="Xr">ng_vjc(4)</a> <code class="Dv">vjcomp</code> + hook</dd> + <dt id="vjc_vjuncomp"><var class="Va">vjc_vjuncomp</var></dt> + <dd>Connection to <a class="Xr">ng_vjc(4)</a> <code class="Dv">vjuncomp</code> + hook</dd> + <dt id="vjc_vjip"><var class="Va">vjc_vjip</var></dt> + <dd>Connection to <a class="Xr">ng_vjc(4)</a> <code class="Dv">vjip</code> + hook</dd> + <dt id="inet"><var class="Va">inet</var></dt> + <dd>IP packet data</dd> + <dt id="ipv6"><var class="Va">ipv6</var></dt> + <dd>IPv6 packet data</dd> + <dt id="atalk"><var class="Va">atalk</var></dt> + <dd>AppleTalk packet data</dd> + <dt id="ipx"><var class="Va">ipx</var></dt> + <dd>IPX packet data</dd> + <dt id="bypass"><var class="Va">bypass</var></dt> + <dd>Bypass hook; frames have a four byte header consisting of a link number + and a PPP protocol number.</dd> +</dl> +</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_PPP_SET_CONFIG"><a class="permalink" href="#NGM_PPP_SET_CONFIG"><code class="Dv">NGM_PPP_SET_CONFIG</code></a> + (<code class="Ic">setconfig</code>)</dt> + <dd>This command configures all aspects of the node. This includes enabling + multi-link PPP, encryption, compression, Van Jacobson compression, and IP, + IPv6, AppleTalk, and IPX packet delivery. It includes per-link + configuration, including enabling the link, setting latency and bandwidth + parameters, and enabling protocol field compression. Note that no link or + functionality is active until the corresponding hook is also connected. + This command takes a <code class="Dv">struct ng_ppp_node_conf</code> as an + argument: + <div class="Bd Pp Bd-indent Li"> + <pre>/* Per-link config structure */ +struct ng_ppp_link_conf { + u_char enableLink; /* enable this link */ + u_char enableProtoComp;/* enable protocol field compression */ + u_char enableACFComp; /* enable addr/ctrl field compression */ + uint16_t mru; /* peer MRU */ + uint32_t latency; /* link latency (in milliseconds) */ + uint32_t bandwidth; /* link bandwidth (in bytes/sec/10) */ +}; + +/* Bundle config structure */ +struct ng_ppp_bund_conf { + uint16_t mrru; /* multilink peer MRRU */ + u_char enableMultilink; /* enable multilink */ + u_char recvShortSeq; /* recv multilink short seq # */ + u_char xmitShortSeq; /* xmit multilink short seq # */ + u_char enableRoundRobin; /* xmit whole packets */ + u_char enableIP; /* enable IP data flow */ + u_char enableIPv6; /* enable IPv6 data flow */ + u_char enableAtalk; /* enable AppleTalk data flow */ + u_char enableIPX; /* enable IPX data flow */ + u_char enableCompression; /* enable PPP compression */ + u_char enableDecompression; /* enable PPP decompression */ + u_char enableEncryption; /* enable PPP encryption */ + u_char enableDecryption; /* enable PPP decryption */ + u_char enableVJCompression; /* enable VJ compression */ + u_char enableVJDecompression; /* enable VJ decompression */ +}; + +struct ng_ppp_node_conf { + struct ng_ppp_bund_conf bund; + struct ng_ppp_link_conf links[NG_PPP_MAX_LINKS]; +};</pre> + </div> + </dd> + <dt id="NGM_PPP_GET_CONFIG"><a class="permalink" href="#NGM_PPP_GET_CONFIG"><code class="Dv">NGM_PPP_GET_CONFIG</code></a> + (<code class="Ic">getconfig</code>)</dt> + <dd>Returns the current configuration as a <code class="Dv">struct + ng_ppp_node_conf</code>.</dd> + <dt id="NGM_PPP_GET_LINK_STATS"><a class="permalink" href="#NGM_PPP_GET_LINK_STATS"><code class="Dv">NGM_PPP_GET_LINK_STATS</code></a> + (<code class="Ic">getstats</code>)</dt> + <dd>This command takes a two byte link number as an argument and returns a + <code class="Dv">struct ng_ppp_link_stat</code> containing statistics for + the corresponding link. Here <code class="Dv">NG_PPP_BUNDLE_LINKNUM</code> + is a valid link number corresponding to the multi-link bundle.</dd> + <dt id="NGM_PPP_GET_LINK_STATS64"><a class="permalink" href="#NGM_PPP_GET_LINK_STATS64"><code class="Dv">NGM_PPP_GET_LINK_STATS64</code></a> + (<code class="Ic">getstats64</code>)</dt> + <dd>Same as NGM_PPP_GET_LINK_STATS but returns <code class="Dv">struct + ng_ppp_link_stat64</code> containing 64bit counters.</dd> + <dt id="NGM_PPP_CLR_LINK_STATS"><a class="permalink" href="#NGM_PPP_CLR_LINK_STATS"><code class="Dv">NGM_PPP_CLR_LINK_STATS</code></a> + (<code class="Ic">clrstats</code>)</dt> + <dd>This command takes a two byte link number as an argument and clears the + statistics for that link.</dd> + <dt id="NGM_PPP_GETCLR_LINK_STATS"><a class="permalink" href="#NGM_PPP_GETCLR_LINK_STATS"><code class="Dv">NGM_PPP_GETCLR_LINK_STATS</code></a> + (<code class="Ic">getclrstats</code>)</dt> + <dd>Same as <code class="Dv">NGM_PPP_GET_LINK_STATS</code>, but also + atomically clears the statistics as well.</dd> + <dt id="NGM_PPP_GETCLR_LINK_STATS64"><a class="permalink" href="#NGM_PPP_GETCLR_LINK_STATS64"><code class="Dv">NGM_PPP_GETCLR_LINK_STATS64</code></a> + (<code class="Ic">getclrstats64</code>)</dt> + <dd>Same as NGM_PPP_GETCLR_LINK_STATS but returns <code class="Dv">struct + ng_ppp_link_stat64</code> containing 64bit counters.</dd> +</dl> +<p class="Pp">This node type also accepts the control messages accepted by the + <a class="Xr">ng_vjc(4)</a> node type. When received, these messages are + simply forwarded to the adjacent <a class="Xr">ng_vjc(4)</a> node, if any. + This is particularly useful when the individual PPP links are able to + generate <code class="Dv">NGM_VJC_RECV_ERROR</code> messages (see + <a class="Xr">ng_vjc(4)</a> for a description).</p> +</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_async(4)</a>, + <a class="Xr">ng_iface(4)</a>, <a class="Xr">ng_mppc(4)</a>, + <a class="Xr">ng_pppoe(4)</a>, <a class="Xr">ng_vjc(4)</a>, + <a class="Xr">ngctl(8)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">W. Simpson</span>, + <span class="RsT">The Point-to-Point Protocol (PPP)</span>, + <span class="RsO">RFC 1661</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsA">K. Sklower</span>, + <span class="RsA">B. Lloyd</span>, <span class="RsA">G. McGregor</span>, + <span class="RsA">D. Carr</span>, and <span class="RsA">T. Coradetti</span>, + <span class="RsT">The PPP Multilink Protocol (MP)</span>, + <span class="RsO">RFC 1990</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">ng_ppp</code> node type was implemented in + <span class="Ux">FreeBSD 4.0</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@FreeBSD.org">archie@FreeBSD.org</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> |