share/man/man4/ng_deflate.4

   1 .\"
   2 .\" Author: Alexander Motin <mav@alkar.net>
   3 .\"
   4 .\" Copyright (c) 2006, Alexander Motin <mav@alkar.net>
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice unmodified, this list of conditions, and the following
  12 .\"    disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd December 23, 2006
  32 .Dt NG_DEFLATE 4
  33 .Os
  34 .Sh NAME
  35 .Nm ng_deflate
  36 .Nd Deflate PPP compression (RFC 1979) netgraph node type
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In netgraph/ng_deflate.h
  40 .Sh DESCRIPTION
  41 The
  42 .Nm deflate
  43 node type implements the Deflate sub-protocols of the Compression Control
  44 Protocol (CCP).
  45 .Pp
  46 The node has two hooks,
  47 .Va comp
  48 for compression and
  49 .Va decomp
  50 for decompression.
  51 Only one of them can be connected at the same time, specifying node's
  52 operation mode.
  53 Typically that hooks would be connected to the
  54 .Xr ng_ppp 4
  55 node type hook of the same name.
  56 Corresponding
  57 .Xr ng_ppp 4
  58 node hook must be switched to
  59 .Dv NG_PPP_DECOMPRESS_FULL
  60 mode to permit sending uncompressed frames.
  61 .Sh HOOKS
  62 This node type supports the following hooks:
  63 .Pp
  64 .Bl -tag -compact -width ".Va decomp"
  65 .It Va comp
  66 Connection to
  67 .Xr ng_ppp 4
  68 .Va comp
  69 hook.
  70 Incoming frames are compressed (if possible) and sent back out the same hook.
  71 .It Va decomp
  72 Connection to
  73 .Xr ng_ppp 4
  74 .Va decomp
  75 hook.
  76 Incoming frames are decompressed (if they are compressed), and sent
  77 back out the same hook.
  78 .El
  79 .Pp
  80 Only one hook can be connected at the same time, specifying node's
  81 operation mode.
  82 .Sh CONTROL MESSAGES
  83 This node type supports the generic control messages, plus the following:
  84 .Bl -tag -width foo
  85 .It Dv NGM_DEFLATE_CONFIG Pq Ic config
  86 This command resets and configures the node for a session
  87 (i.e., for compression or decompression).
  88 This command takes a
  89 .Vt "struct ng_deflate_config"
  90 as an argument:
  91 .Bd -literal -offset 0n
  92 struct ng_deflate_config {
  93         u_char  enable;                 /* node enabled */
  94         u_char  windowBits;             /* log2(Window size) */
  95 };
  96 .Ed
  97 The
  98 .Fa enabled
  99 field enables traffic flow through the node.
 100 The
 101 .Fa windowBits
 102 specify compression windows size as negotiated by the
 103 Compression Control Protocol (CCP) in PPP.
 104 .It Dv NGM_DEFLATE_RESETREQ Pq Ic resetreq
 105 This message contains no arguments, and is bi-directional.
 106 If an error is detected during decompression, this message is sent by the
 107 node to the originator of the
 108 .Dv NGM_DEFLATE_CONFIG
 109 message that initiated the session.
 110 The receiver should respond by sending a PPP CCP Reset-Request to the peer.
 111 .Pp
 112 This message may also be received by this node type when a CCP Reset-Request
 113 or Reset-Ack is received by the local PPP entity.
 114 The node will respond by flushing its compression state so the sides
 115 can resynchronize.
 116 .It Dv NGM_DEFLATE_GET_STATS Pq Ic getstats
 117 This control message obtains statistics for a given hook.
 118 The statistics are returned in
 119 .Vt "struct ng_deflate_stats" :
 120 .Bd -literal
 121 struct ng_deflate_stats {
 122         uint64_t        FramesPlain;
 123         uint64_t        FramesComp;
 124         uint64_t        FramesUncomp;
 125         uint64_t        InOctets;
 126         uint64_t        OutOctets;
 127         uint64_t        Errors;
 128 };
 129 .Ed
 130 .It Dv NGM_DEFLATE_CLR_STATS Pq Ic clrstats
 131 This control message clears statistics for a given hook.
 132 .It Dv NGM_DEFLATE_GETCLR_STATS Pq Ic getclrstats
 133 This control message obtains and clears statistics for a given hook.
 134 .El
 135 .Sh SHUTDOWN
 136 This node shuts down upon receipt of a
 137 .Dv NGM_SHUTDOWN
 138 control message, or when hook have been disconnected.
 139 .Sh SEE ALSO
 140 .Xr netgraph 4 ,
 141 .Xr ng_ppp 4 ,
 142 .Xr ngctl 8
 143 .Rs
 144 .%A J. Woods
 145 .%T "PPP Deflate Protocol"
 146 .%O RFC 1979
 147 .Re
 148 .Rs
 149 .%A W. Simpson
 150 .%T "The Point-to-Point Protocol (PPP)"
 151 .%O RFC 1661
 152 .Re
 153 .Sh AUTHORS
 154 .An Alexander Motin Aq mav@alkar.net
 155 .Sh BUGS
 156 Due to nature of netgraph PPP implementation there are possible race conditions
 157 between data packet and ResetAck CCP packet in case of packet loss. As result,
 158 packet loss can produce bigger performance degradation than supposed by protocol.