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, 0 insertions, 358 deletions
diff --git a/static/freebsd/man4/ng_ppp.4 3.html b/static/freebsd/man4/ng_ppp.4 3.html deleted file mode 100644 index 56c18b90..00000000 --- a/static/freebsd/man4/ng_ppp.4 3.html +++ /dev/null @@ -1,358 +0,0 @@ -<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> |