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 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 Li 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 The
 105 .It Dv NGM_DEFLATE_RESETREQ Pq Li resetreq
 106 This message contains no arguments, and is bi-directional.
 107 If an error is detected during decompression, this message is sent by the
 108 node to the originator of the
 109 .Dv NGM_DEFLATE_CONFIG
 110 message that initiated the session.
 111 The receiver should respond by sending a PPP CCP Reset-Request to the peer.
 112 .Pp
 113 This message may also be received by this node type when a CCP Reset-Request
 114 or Reset-Ack is received by the local PPP entity.
 115 The node will respond by flushing its compression state so the sides
 116 can resynchronize.
 117 .It Dv NGM_DEFLATE_GET_STATS Pq Li getstats
 118 This control message obtains statistics for a given hook.
 119 The statistics are returned in
 120 .Vt "struct ng_deflate_stats" :
 121 .Bd -literal
 122 struct ng_deflate_stats {
 123         uint64_t        FramesPlain;
 124         uint64_t        FramesComp;
 125         uint64_t        FramesUncomp;
 126         uint64_t        InOctets;
 127         uint64_t        OutOctets;
 128         uint64_t        Errors;
 129 };
 130 .Ed
 131 .It Dv NGM_DEFLATE_CLR_STATS Pq Li clrstats
 132 This control message clears statistics for a given hook.
 133 .It Dv NGM_DEFLATE_GETCLR_STATS Pq Li getclrstats
 134 This control message obtains and clears statistics for a given hook.
 135 .El
 136 .Sh SHUTDOWN
 137 This node shuts down upon receipt of a
 138 .Dv NGM_SHUTDOWN
 139 control message, or when hook have been disconnected.
 140 .Sh SEE ALSO
 141 .Xr netgraph 4 ,
 142 .Xr ng_ppp 4 ,
 143 .Xr ngctl 8
 144 .Rs
 145 .%A J. Woods
 146 .%T "PPP Deflate Protocol"
 147 .%O RFC 1979
 148 .Re
 149 .Rs
 150 .%A W. Simpson
 151 .%T "The Point-to-Point Protocol (PPP)"
 152 .%O RFC 1661
 153 .Re
 154 .Sh AUTHORS
 155 .An Alexander Motin Aq mav@alkar.net
 156 .Sh BUGS
 157 Due to nature of netgraph PPP implementation there are possible race conditions
 158 between data packet and ResetAck CCP packet in case of packet loss. As result,
 159 packet loss can produce bigger performance degradation than supposed by protocol.