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