/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$
 36.\" $Whistle: ng_vjc.8,v 1.4 1999/01/25 23:46:28 archie Exp $
 37.\"
 38.Dd January 19, 1999
 39.Dt NG_VJC 4
 40.Os
 41.Sh NAME
 42.Nm ng_vjc
 43.Nd Van Jacobson compression netgraph node type
 44.Sh SYNOPSIS
 45.In sys/types.h
 46.In netinet/in.h
 47.In netinet/in_systm.h
 48.In netinet/ip.h
 49.In net/slcompress.h
 50.In netgraph/ng_vjc.h
 51.Sh DESCRIPTION
 52The
 53.Nm vjc
 54node type performs Van Jacobson compression, which is used
 55over PPP, SLIP, and other point-to-point IP connections to
 56compress TCP packet headers.
 57The
 58.Dv ip
 59hook represents the uncompressed side of the node, while the
 60.Dv vjcomp ,
 61.Dv vjuncomp ,
 62and
 63.Dv vjip
 64hooks represent the compressed side of the node.
 65Packets received on the
 66.Dv ip
 67will be compressed or passed through as appropriate.
 68Packets received on the other three hooks will be uncompressed as appropriate.
 69This node also supports
 70.Dq always pass through
 71mode in either direction.
 72.Pp
 73Van Jacobson compression only applies to TCP packets.
 74Only
 75.Dq normal
 76(i.e., common case) TCP packets are actually compressed.
 77These are output on the
 78.Dv vjcomp
 79hook.
 80Other TCP packets are run through the state machine but not
 81compressed; these appear on the
 82.Dv vjuncomp
 83hook.
 84Other non-TCP IP packets are forwarded unchanged to
 85.Dv vjip .
 86.Pp
 87When connecting to a
 88.Xr ng_ppp 4
 89node, the
 90.Dv ip ,
 91.Dv vjuncomp ,
 92.Dv vjcomp ,
 93and
 94.Dv vjip
 95hooks should be connected to the
 96.Xr ng_ppp 4
 97node's
 98.Dv vjc_ip ,
 99.Dv vjc_vjcomp ,
100.Dv vjc_vjuncomp ,
101and
102.Dv vjc_ip
103hooks, respectively.
104.Sh HOOKS
105This node type supports the following hooks:
106.Bl -tag -width foobarbazi
107.It Dv ip
108Upstream (uncompressed) IP packets.
109.It Dv vjcomp
110Downstream compressed TCP packets.
111.It Dv vjuncomp
112Downstream uncompressed TCP packets.
113.It Dv vjip
114Downstream uncompressed IP packets.
115.El
116.Sh CONTROL MESSAGES
117This node type supports the generic control messages, plus the following:
118.Bl -tag -width foo
119.It Dv NGM_VJC_SET_CONFIG
120This command resets the compression state and configures it according
121to the supplied
122.Dv "struct ngm_vjc_config"
123argument.
124This structure contains the following fields:
125.Bd -literal -offset 4n
126struct ngm_vjc_config {
127  u_char   enableComp;    /* Enable compression */
128  u_char   enableDecomp;  /* Enable decompression */
129  u_char   maxChannel;    /* Number of outgoing channels - 1 */
130  u_char   compressCID;   /* OK to compress outgoing CID's */
131};
132.Ed
133.Pp
134When
135.Dv enableComp
136is set to zero, all packets received on the
137.Dv ip
138hook are forwarded unchanged out the
139.Dv vjip
140hook.
141Similarly, when
142.Dv enableDecomp
143is set to zero, all packets received on the
144.Dv vjip
145hook are forwarded unchanged out the
146.Dv ip
147hook, and packets are not accepted on the
148.Dv vjcomp
149and
150.Dv vjuncomp
151hooks.
152When a node is first created,
153both compression and decompression are disabled and the node is
154therefore operating in bi-directional
155.Dq pass through
156mode.
157.Pp
158When enabling compression,
159.Dv maxChannel
160should be set to the number of outgoing compression channels minus one,
161and is a value between 3 and 15, inclusive.
162The
163.Dv compressCID
164field indicates whether it is OK to compress the CID header field for
165outgoing compressed TCP packets.
166This value should be zero unless
167either (a) it is not possible for an outgoing frame to be lost, or
168(b) lost frames can be reliably detected and immediately
169reported to the peer's decompression engine (see
170.Dv NGM_VJC_RECV_ERROR
171below).
172.It Dv NGM_VJC_GET_STATE
173This command returns the node's current state described by the
174.Dv "struct slcompress"
175structure, which is defined in
176.In net/slcompress.h .
177.It Dv NGM_VJC_CLR_STATS
178Clears the node statistics counters.
179Statistics are also cleared whenever the
180.Dv enableComp
181or
182.Dv enableDecomp
183fields are changed from zero to one by a
184.Dv NGM_VJC_SET_CONFIG
185control message.
186.It Dv NGM_VJC_RECV_ERROR
187When the peer has CID header field compression enabled,
188this message must be sent to the local
189.Nm vjc
190node immediately
191after detecting that a received frame has been lost, due to a bad
192checksum or for any other reason.
193Failing to do this can result in corrupted TCP stream data.
194.El
195.Sh SHUTDOWN
196This node shuts down upon receipt of a
197.Dv NGM_SHUTDOWN
198control message, or when all hooks have been disconnected.
199.Sh SEE ALSO
200.Xr netgraph 4 ,
201.Xr ng_iface 4 ,
202.Xr ng_ppp 4 ,
203.Xr ngctl 8
204.Rs
205.%A V. Jacobson
206.%T "Compressing TCP/IP Headers"
207.%O RFC 1144
208.Re
209.Rs
210.%A G. McGregor
211.%T "The PPP Internet Control Protocol (IPCP)"
212.%O RFC 1332
213.Re
214.Sh HISTORY
215The
216.Nm
217node type was implemented in
218.Fx 4.0 .
219.Sh AUTHORS
220.An Archie Cobbs Aq archie@FreeBSD.org
221.Sh BUGS
222As the initialization routine in the kernel implementation of
223Van Jacobson compression initializes both compression and decompression
224at once, this node does not allow compression and decompression to
225be enabled in separate operations.
226In order to enable one when
227the other is already enabled, first both must be disabled, then
228both enabled.
229This of course resets the node state.
230This restriction may be lifted in a later version.
231.Pp
232When built as a loadable kernel module, this module includes the file
233.Pa net/slcompress.c .
234Although loading the module should fail if
235.Pa net/slcompress.c
236already exists in the kernel, currently it does not, and the duplicate
237copies of the file do not interfere.
238However, this may change in the future.