/share/man/man4/ng_vjc.4

https://bitbucket.org/freebsd/freebsd-head/ · Forth · 238 lines · 238 code · 0 blank · 0 comment · 3 complexity · 7148d5ce6b8dd279946236ce4ff50162 MD5 · raw file

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