path: root/static/freebsd/man4/ng_ppp.4 3.html

<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> &#x2014; <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
    &lt;<a class="In">sys/types.h</a>&gt;</code>
  <br/>
  <code class="In">#include
  &lt;<a class="In">netgraph/ng_ppp.h</a>&gt;</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 &#x201C;pass through&#x201D; 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&lt;N&gt;</var></dt>
  <dd>Individual PPP link number <code class="Dv">&lt;N&gt;</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>
    &lt;<a class="Mt" href="mailto:archie@FreeBSD.org">archie@FreeBSD.org</a>&gt;</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>