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