share/man/man4/ng_vjc.4

   1 .\" Copyright (c) 1996-1999 Whistle Communications, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Subject to the following obligations and disclaimer of warranty, use and
   5 .\" redistribution of this software, in source or object code forms, with or
   6 .\" without modifications are expressly permitted by Whistle Communications;
   7 .\" provided, however, that:
   8 .\" 1. Any and all reproductions of the source or object code must include the
   9 .\"    copyright notice above and the following disclaimer of warranties; and
  10 .\" 2. No rights are granted, in any manner or form, to use Whistle
  11 .\"    Communications, Inc. trademarks, including the mark "WHISTLE
  12 .\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
  13 .\"    such appears in the above copyright notice or in the software.
  14 .\"
  15 .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
  16 .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
  17 .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
  18 .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
  20 .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
  21 .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
  22 .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
  23 .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
  24 .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
  25 .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
  26 .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
  27 .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
  31 .\" OF SUCH DAMAGE.
  32 .\"
  33 .\" Author: Archie Cobbs <archie@FreeBSD.org>
  34 .\"
  35 .\" $FreeBSD: src/share/man/man4/ng_vjc.4,v 1.17.2.1 2001/12/21 09:00:51 ru Exp $
  36 .\" $DragonFly: src/share/man/man4/ng_vjc.4,v 1.2 2003/06/17 04:36:59 dillon Exp $
  37 .\" $Whistle: ng_vjc.8,v 1.4 1999/01/25 23:46:28 archie Exp $
  38 .\"
  39 .Dd January 19, 1999
  40 .Dt NG_VJC 4
  41 .Os
  42 .Sh NAME
  43 .Nm ng_vjc
  44 .Nd Van Jacobson compression netgraph node type
  45 .Sh SYNOPSIS
  46 .In net/slcompress.h
  47 .In netgraph/ng_vjc.h
  48 .Sh DESCRIPTION
  49 The
  50 .Nm vjc
  51 node type performs Van Jacobson compression, which is used
  52 over PPP, SLIP, and other point-to-point IP connections to
  53 compress TCP packet headers.  The
  54 .Dv ip
  55 hook represents the uncompressed side of the node, while the
  56 .Dv vjcomp ,
  57 .Dv vjuncomp ,
  58 and
  59 .Dv vjip
  60 hooks represent the compressed side of the node.  Packets received on the
  61 .Dv ip
  62 will be compressed or passed through as appropriate.  Packets received
  63 on the other three hooks will be uncompressed as appropriate.
  64 This node also supports
  65 .Dq always pass through
  66 mode in either direction.
  67 .Pp
  68 Van Jacobson compression only applies to TCP packets.
  69 Only
  70 .Dq normal
  71 (i.e., common case) TCP packets are actually compressed.
  72 These are output on the
  73 .Dv vjcomp
  74 hook.  Other TCP packets are run through the state machine but not
  75 compressed; these appear on the
  76 .Dv vjuncomp
  77 hook.
  78 Other non-TCP IP packets are forwarded unchanged to
  79 .Dv vjip .
  80 .Pp
  81 When connecting to a
  82 .Xr ng_ppp 4
  83 node, the
  84 .Dv ip ,
  85 .Dv vjuncomp ,
  86 .Dv vjcomp ,
  87 and
  88 .Dv vjip
  89 hooks should be connected to the
  90 .Xr ng_ppp 4
  91 node's
  92 .Dv vjc_ip ,
  93 .Dv vjc_vjcomp ,
  94 .Dv vjc_vjuncomp ,
  95 and
  96 .Dv vjc_ip
  97 hooks, respectively.
  98 .Sh HOOKS
  99 This node type supports the following hooks:
 100 .Pp
 101 .Bl -tag -width foobarbazi
 102 .It Dv ip
 103 Upstream (uncompressed) IP packets.
 104 .It Dv vjcomp
 105 Downstream compressed TCP packets.
 106 .It Dv vjuncomp
 107 Downstream uncompressed TCP packets.
 108 .It Dv vjip
 109 Downstream uncompressed IP packets.
 110 .El
 111 .Sh CONTROL MESSAGES
 112 This node type supports the generic control messages, plus the following:
 113 .Bl -tag -width foo
 114 .It Dv NGM_VJC_SET_CONFIG
 115 This command resets the compression state and configures it according
 116 to the supplied
 117 .Dv "struct ngm_vjc_config"
 118 argument.  This structure contains the following fields:
 119 .Bd -literal -offset 4n
 120 struct ngm_vjc_config {
 121   u_char   enableComp;    /* Enable compression */
 122   u_char   enableDecomp;  /* Enable decompression */
 123   u_char   maxChannel;    /* Number of outgoing channels - 1 */
 124   u_char   compressCID;   /* OK to compress outgoing CID's */
 125 };
 126 .Ed
 127 .Pp
 128 When
 129 .Dv enableComp
 130 is set to zero, all packets received on the
 131 .Dv ip
 132 hook are forwarded unchanged out the
 133 .Dv vjip
 134 hook.  Similarly, when
 135 .Dv enableDecomp
 136 is set to zero, all packets received on the
 137 .Dv vjip
 138 hook are forwarded unchanged out the
 139 .Dv ip
 140 hook, and packets are not accepted on the
 141 .Dv vjcomp
 142 and
 143 .Dv vjuncomp
 144 hooks.
 145 When a node is first created,
 146 both compression and decompression are disabled and the node is
 147 therefore operating in bi-directional
 148 .Dq pass through
 149 mode.
 150 .Pp
 151 When enabling compression,
 152 .Dv maxChannel
 153 should be set to the number of outgoing compression channels minus one,
 154 and is a value between 3 and 15, inclusive.  The
 155 .Dv compressCID
 156 field indicates whether it is OK to compress the CID header field for
 157 outgoing compressed TCP packets.  This value should be zero unless
 158 either (a) it is not possible for an outgoing frame to be lost, or
 159 (b) lost frames can be reliably detected and immediately
 160 reported to the peer's decompression engine (see
 161 .Dv NGM_VJC_RECV_ERROR
 162 below).
 163 .It Dv NGM_VJC_GET_STATE
 164 This command returns the node's current state described by the
 165 .Dv "struct slcompress"
 166 structure, which is defined in
 167 .Pa net/slcompress.h .
 168 .It Dv NGM_VJC_CLR_STATS
 169 Clears the node statistics counters.  Statistics are also cleared whenever the
 170 .Dv enableComp
 171 or
 172 .Dv enableDecomp
 173 fields are changed from zero to one by a
 174 .Dv NGM_VJC_SET_CONFIG
 175 control message.
 176 .It Dv NGM_VJC_RECV_ERROR
 177 When the peer has CID header field compression enabled,
 178 this message must be sent to the local
 179 .Nm vjc
 180 node immediately
 181 after detecting that a received frame has been lost, due to a bad
 182 checksum or for any other reason.  Failing to do this can result
 183 in corrupted TCP stream data.
 184 .El
 185 .Sh SHUTDOWN
 186 This node shuts down upon receipt of a
 187 .Dv NGM_SHUTDOWN
 188 control message, or when all hooks have been disconnected.
 189 .Sh BUGS
 190 Because the initialization routine in the kernel implementation of
 191 Van Jacobson compression initializes both compression and decompression
 192 at once, this node does not allow compression and decompression to
 193 be enabled in separate operations.  In order to enable one when
 194 the other is already enabled, first both must be disabled, then
 195 both enabled.  This of course resets the node state.  This restriction
 196 may be lifted in a later version.
 197 .Pp
 198 When built as a loadable kernel module, this module includes the file
 199 .Pa net/slcompress.c .
 200 Although loading the module should fail if
 201 .Pa net/slcompress.c
 202 already exists in the kernel, currently it does not, and the duplicate
 203 copies of the file do not interfere.
 204 However, this may change in the future.
 205 .Sh SEE ALSO
 206 .Xr netgraph 4 ,
 207 .Xr ng_iface 4 ,
 208 .Xr ng_ppp 4 ,
 209 .Xr ngctl 8
 210 .Rs
 211 .%A V. Jacobson
 212 .%T "Compressing TCP/IP Headers"
 213 .%O RFC 1144
 214 .Re
 215 .Rs
 216 .%A G. McGregor
 217 .%T "The PPP Internet Control Protocol (IPCP)"
 218 .%O RFC 1332
 219 .Re
 220 .Sh HISTORY
 221 The
 222 .Nm
 223 node type was implemented in
 224 .Fx 4.0 .
 225 .Sh AUTHORS
 226 .An Archie Cobbs Aq archie@FreeBSD.org