xref: /freebsd/share/man/man4/siftr.4 (revision d09a955a605d03471c5ab7bd17b8a6186fdc148c)
1.\"
2.\" Copyright (c) 2010 The FreeBSD Foundation
3.\"
4.\" Portions of this software were developed at the Centre for Advanced
5.\" Internet Architectures, Swinburne University of Technology, Melbourne,
6.\" Australia by Lawrence Stewart under sponsorship from the FreeBSD
7.\" Foundation.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions, and the following disclaimer,
14.\"    without modification, immediately at the beginning of the file.
15.\" 2. The name of the author may not be used to endorse or promote products
16.\"    derived from this software without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
22.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" $FreeBSD$
31.\"
32.Dd April 25, 2023
33.Dt SIFTR 4
34.Os
35.Sh NAME
36.Nm SIFTR
37.Nd Statistical Information For TCP Research
38.Sh SYNOPSIS
39To load
40the driver
41as a module at run-time, run the following command as root:
42.Bd -literal -offset indent
43kldload siftr
44.Ed
45.Pp
46Alternatively, to load
47the driver
48as a module at boot time, add the following line into the
49.Xr loader.conf 5
50file:
51.Bd -literal -offset indent
52siftr_load="YES"
53.Ed
54.Sh DESCRIPTION
55The
56.Nm
57.Po
58.Em S Ns tatistical
59.Em I Ns nformation
60.Em F Ns or
61.Em T Ns CP
62.Em R Ns esearch
63.Pc
64kernel module logs a range of statistics on active TCP connections to
65a log file.
66It provides the ability to make highly granular measurements of TCP connection
67state, aimed at system administrators, developers and researchers.
68.Ss Compile-time Configuration
69The default operation of
70.Nm
71is to capture IPv4 TCP/IP packets.
72.Nm
73can be configured to support IPv4 and IPv6 by uncommenting:
74.Bd -literal -offset indent
75CFLAGS+=-DSIFTR_IPV6
76.Ed
77.Pp
78in
79.Aq sys/modules/siftr/Makefile
80and recompiling.
81.Pp
82In the IPv4-only (default) mode, standard dotted decimal notation (e.g.
83"136.186.229.95") is used to format IPv4 addresses for logging.
84In IPv6 mode, standard dotted decimal notation is used to format IPv4 addresses,
85and standard colon-separated hex notation (see RFC 4291) is used to format IPv6
86addresses for logging.
87Note that SIFTR uses uncompressed notation to format IPv6 addresses.
88For example, the address "fe80::20f:feff:fea2:531b" would be logged as
89"fe80:0:0:0:20f:feff:fea2:531b".
90.Ss Run-time Configuration
91.Nm
92utilises the
93.Xr sysctl 8
94interface to export its configuration variables to user-space.
95The following variables are available:
96.Bl -tag -offset indent -width Va
97.It Va net.inet.siftr.enabled
98controls whether the module performs its
99measurements or not.
100By default, the value is set to 0, which means the module
101will not be taking any measurements.
102Having the module loaded with
103.Va net.inet.siftr.enabled
104set to 0 will have no impact on the performance of the network stack, as the
105packet filtering hooks are only inserted when
106.Va net.inet.siftr.enabled
107is set to 1.
108.El
109.Bl -tag -offset indent -width Va
110.It Va net.inet.siftr.ppl
111controls how many inbound/outbound packets for a given TCP connection will cause
112a log message to be generated for the connection.
113By default, the value is set to 1, which means the module will log a message for
114every packet of every TCP connection.
115The value can be set to any integer in the range [1,2^32], and can be changed at
116any time, even while the module is enabled.
117.El
118.Bl -tag -offset indent -width Va
119.It Va net.inet.siftr.logfile
120controls the path to the file that the module writes its log messages to.
121By default, the file /var/log/siftr.log is used.
122The path can be changed at any time, even while the module is enabled.
123.El
124.Bl -tag -offset indent -width Va
125.It Va net.inet.siftr.genhashes
126controls whether a hash is generated for each TCP packet seen by
127.Nm .
128By default, the value is set to 0, which means no hashes are generated.
129The hashes are useful to correlate which TCP packet triggered the generation of
130a particular log message, but calculating them adds additional computational
131overhead into the fast path.
132.El
133.Bl -tag -offset indent -width Va
134.It Va net.inet.siftr.port_filter
135controls on which source or destination port siftr should capture
136.Nm .
137By default, the value is set to 0, which means all ports are eligible for logging.
138Set to any other value, only packets where either the source or destination
139port is equal to this number are logged.
140.El
141.Ss Log Format
142A typical
143.Nm
144log file will contain 3 different types of log message.
145All messages are written in plain ASCII text.
146.Pp
147Note: The
148.Qq \e
149present in the example log messages in this section indicates a
150line continuation and is not part of the actual log message.
151.Pp
152The first type of log message is written to the file when the module is
153enabled and starts collecting data from the running kernel.
154The text below shows an example module enable log.
155The fields are tab delimited key-value
156pairs which describe some basic information about the system.
157.Bd -literal -offset indent
158enable_time_secs=1238556193    enable_time_usecs=462104 \\
159siftrver=1.2.2    hz=1000    tcp_rtt_scale=32 \\
160sysname=FreeBSD    sysver=604000    ipmode=4
161.Ed
162.Pp
163Field descriptions are as follows:
164.Bl -tag -offset indent -width Va
165.It Va enable_time_secs
166time at which the module was enabled, in seconds since the UNIX epoch.
167.El
168.Bl -tag -offset indent -width Va
169.It Va enable_time_usecs
170time at which the module was enabled, in microseconds since enable_time_secs.
171.El
172.Bl -tag -offset indent -width Va
173.It Va siftrver
174version of
175.Nm .
176.El
177.Bl -tag -offset indent -width Va
178.It Va sysname
179operating system name.
180.El
181.Bl -tag -offset indent -width Va
182.It Va sysver
183operating system version.
184.El
185.Bl -tag -offset indent -width Va
186.It Va ipmode
187IP mode as defined at compile time.
188An ipmode of "4" means IPv6 is not supported and IP addresses are logged in
189regular dotted quad format.
190An ipmode of "6" means IPv6 is supported, and IP addresses are logged in dotted
191quad or hex format, as described in the
192.Qq Compile-time Configuration
193subsection.
194.El
195.Pp
196The second type of log message is written to the file when a data log message
197is generated.
198The text below shows an example data log triggered by an IPv4
199TCP/IP packet.
200The data is CSV formatted.
201.Bd -literal -offset indent
202o,0xbec491a5,1238556193.463551,172.16.7.28,22,172.16.2.5,55931, \\
2031073725440,172312,34,66560,66608,8,1,4,1448,936,1,996,255, \\
20433304,208,66608,0,208,0
205.Ed
206.Pp
207Field descriptions are as follows:
208.Bl -tag -offset indent -width Va
209.It Va 1
210Direction of packet that triggered the log message.
211Either
212.Qq i
213for in, or
214.Qq o
215for out.
216.El
217.Bl -tag -offset indent -width Va
218.It Va 2
219Hash of the packet that triggered the log message.
220.El
221.Bl -tag -offset indent -width Va
222.It Va 3
223Time at which the packet that triggered the log message was processed by
224the
225.Xr pfil 9
226hook function, in seconds and microseconds since the UNIX epoch.
227.El
228.Bl -tag -offset indent -width Va
229.It Va 4
230The IPv4 or IPv6 address of the local host, in dotted quad (IPv4 packet)
231or colon-separated hex (IPv6 packet) notation.
232.El
233.Bl -tag -offset indent -width Va
234.It Va 5
235The TCP port that the local host is communicating via.
236.El
237.Bl -tag -offset indent -width Va
238.It Va 6
239The IPv4 or IPv6 address of the foreign host, in dotted quad (IPv4 packet)
240or colon-separated hex (IPv6 packet) notation.
241.El
242.Bl -tag -offset indent -width Va
243.It Va 7
244The TCP port that the foreign host is communicating via.
245.El
246.Bl -tag -offset indent -width Va
247.It Va 8
248The slow start threshold for the flow, in bytes.
249.El
250.Bl -tag -offset indent -width Va
251.It Va 9
252The current congestion window for the flow, in bytes.
253.El
254.Bl -tag -offset indent -width Va
255.It Va 10
256The current state of the t_flags2 field for the flow.
257.El
258.Bl -tag -offset indent -width Va
259.It Va 11
260The current sending window for the flow, in bytes.
261The post scaled value is reported, except during the initial handshake (first
262few packets), during which time the unscaled value is reported.
263.El
264.Bl -tag -offset indent -width Va
265.It Va 12
266The current receive window for the flow, in bytes.
267The post scaled value is always reported.
268.El
269.Bl -tag -offset indent -width Va
270.It Va 13
271The current window scaling factor for the sending window.
272.El
273.Bl -tag -offset indent -width Va
274.It Va 14
275The current window scaling factor for the receiving window.
276.El
277.Bl -tag -offset indent -width Va
278.It Va 15
279The current state of the TCP finite state machine, as defined
280in
281.Aq Pa netinet/tcp_fsm.h .
282.El
283.Bl -tag -offset indent -width Va
284.It Va 16
285The maximum segment size for the flow, in bytes.
286.El
287.Bl -tag -offset indent -width Va
288.It Va 17
289The current smoothed RTT estimate for the flow, in units of microsecond.
290.El
291.Bl -tag -offset indent -width Va
292.It Va 18
293SACK enabled indicator. 1 if SACK enabled, 0 otherwise.
294.El
295.Bl -tag -offset indent -width Va
296.It Va 19
297The current state of the TCP flags for the flow.
298See
299.Aq Pa netinet/tcp_var.h
300for information about the various flags.
301.El
302.Bl -tag -offset indent -width Va
303.It Va 20
304The current retransmission timeout length for the flow, in units microsecond.
305.El
306.Bl -tag -offset indent -width Va
307.It Va 21
308The current size of the socket send buffer in bytes.
309.El
310.Bl -tag -offset indent -width Va
311.It Va 22
312The current number of bytes in the socket send buffer.
313.El
314.Bl -tag -offset indent -width Va
315.It Va 23
316The current size of the socket receive buffer in bytes.
317.El
318.Bl -tag -offset indent -width Va
319.It Va 24
320The current number of bytes in the socket receive buffer.
321.El
322.Bl -tag -offset indent -width Va
323.It Va 25
324The current number of unacknowledged bytes in-flight.
325Bytes acknowledged via SACK are not excluded from this count.
326.El
327.Bl -tag -offset indent -width Va
328.It Va 26
329The current number of segments in the reassembly queue.
330.El
331.Bl -tag -offset indent -width Va
332.It Va 27
333Flowid for the connection.
334A caveat: Zero '0' either represents a valid flowid or a default value when it's
335not being set.
336There is no easy way to differentiate without looking at actual
337network interface card and drivers being used.
338.El
339.Bl -tag -offset indent -width Va
340.It Va 28
341Flow type for the connection.
342Flowtype defines which protocol fields are hashed to produce the flowid.
343A complete listing is available in
344.Pa sys/mbuf.h
345under
346.Dv M_HASHTYPE_* .
347.El
348.Pp
349The third type of log message is written to the file when the module is disabled
350and ceases collecting data from the running kernel.
351The text below shows an example module disable log.
352The fields are tab delimited key-value pairs which provide statistics about
353operations since the module was most recently enabled.
354.Bd -literal -offset indent
355disable_time_secs=1238556197    disable_time_usecs=933607 \\
356num_inbound_tcp_pkts=356    num_outbound_tcp_pkts=627 \\
357total_tcp_pkts=983    num_inbound_skipped_pkts_malloc=0 \\
358num_outbound_skipped_pkts_malloc=0    num_inbound_skipped_pkts_tcb=0 \\
359num_outbound_skipped_pkts_tcb=0    num_inbound_skipped_pkts_icb=0 \\
360num_outbound_skipped_pkts_icb=0    total_skipped_tcp_pkts=0 \\
361flow_list=172.16.7.28;22-172.16.2.5;55931,
362.Ed
363.Pp
364Field descriptions are as follows:
365.Bl -tag -offset indent -width Va
366.It Va disable_time_secs
367Time at which the module was disabled, in seconds since the UNIX epoch.
368.El
369.Bl -tag -offset indent -width Va
370.It Va disable_time_usecs
371Time at which the module was disabled, in microseconds since disable_time_secs.
372.El
373.Bl -tag -offset indent -width Va
374.It Va num_inbound_tcp_pkts
375Number of TCP packets that traversed up the network stack.
376This only includes inbound TCP packets during the periods when
377.Nm
378was enabled.
379.El
380.Bl -tag -offset indent -width Va
381.It Va num_outbound_tcp_pkts
382Number of TCP packets that traversed down the network stack.
383This only includes outbound TCP packets during the periods when
384.Nm
385was enabled.
386.El
387.Bl -tag -offset indent -width Va
388.It Va total_tcp_pkts
389The summation of num_inbound_tcp_pkts and num_outbound_tcp_pkts.
390.El
391.Bl -tag -offset indent -width Va
392.It Va num_inbound_skipped_pkts_malloc
393Number of inbound packets that were not processed because of failed
394.Fn malloc
395calls.
396.El
397.Bl -tag -offset indent -width Va
398.It Va num_outbound_skipped_pkts_malloc
399Number of outbound packets that were not processed because of failed
400.Fn malloc
401calls.
402.El
403.Bl -tag -offset indent -width Va
404.It Va num_inbound_skipped_pkts_tcb
405Number of inbound packets that were not processed because of failure to find the
406TCP control block associated with the packet.
407.El
408.Bl -tag -offset indent -width Va
409.It Va num_outbound_skipped_pkts_tcb
410Number of outbound packets that were not processed because of failure to find
411the TCP control block associated with the packet.
412.El
413.Bl -tag -offset indent -width Va
414.It Va num_inbound_skipped_pkts_icb
415Number of inbound packets that were not processed because of failure to find the
416IP control block associated with the packet.
417.El
418.Bl -tag -offset indent -width Va
419.It Va num_outbound_skipped_pkts_icb
420Number of outbound packets that were not processed because of failure to find
421the IP control block associated with the packet.
422.El
423.Bl -tag -offset indent -width Va
424.It Va total_skipped_tcp_pkts
425The summation of all skipped packet counters.
426.El
427.Bl -tag -offset indent -width Va
428.It Va flow_list
429A CSV list of TCP flows that triggered data log messages to be generated since
430the module was loaded.
431Each flow entry in the CSV list is
432formatted as
433.Qq local_ip;local_port-foreign_ip;foreign_port .
434If there are no entries in the list (i.e., no data log messages were generated),
435the value will be blank.
436If there is at least one entry in the list, a trailing comma will always be
437present.
438.El
439.Pp
440The total number of data log messages found in the log file for a module
441enable/disable cycle should equate to total_tcp_pkts - total_skipped_tcp_pkts.
442.Sh IMPLEMENTATION NOTES
443.Nm
444hooks into the network stack using the
445.Xr pfil 9
446interface.
447In its current incarnation, it hooks into the AF_INET/AF_INET6 (IPv4/IPv6)
448.Xr pfil 9
449filtering points, which means it sees packets at the IP layer of the network
450stack.
451This means that TCP packets inbound to the stack are intercepted before
452they have been processed by the TCP layer.
453Packets outbound from the stack are intercepted after they have been processed
454by the TCP layer.
455.Pp
456The diagram below illustrates how
457.Nm
458inserts itself into the stack.
459.Bd -literal -offset indent
460----------------------------------
461           Upper Layers
462----------------------------------
463    ^                       |
464    |                       |
465    |                       |
466    |                       v
467 TCP in                  TCP out
468----------------------------------
469    ^                      |
470    |________     _________|
471            |     |
472            |     v
473           ---------
474           | SIFTR |
475           ---------
476            ^     |
477    ________|     |__________
478    |                       |
479    |                       v
480IPv{4/6} in            IPv{4/6} out
481----------------------------------
482    ^                       |
483    |                       |
484    |                       v
485Layer 2 in             Layer 2 out
486----------------------------------
487          Physical Layer
488----------------------------------
489.Ed
490.Pp
491.Nm
492uses the
493.Xr alq 9
494interface to manage writing data to disk.
495.Pp
496At first glance, you might mistakenly think that
497.Nm
498extracts information from
499individual TCP packets.
500This is not the case.
501.Nm
502uses TCP packet events (inbound and outbound) for each TCP flow originating from
503the system to trigger a dump of the state of the TCP control block for that
504flow.
505With the PPL set to 1, we are in effect sampling each TCP flow's control block
506state as frequently as flow packets enter/leave the system.
507For example, setting PPL to 2 halves the sampling rate i.e., every second flow
508packet (inbound OR outbound) causes a dump of the control block state.
509.Pp
510The distinction between interrogating individual packets versus interrogating the
511control block is important, because
512.Nm
513does not remove the need for packet capturing tools like
514.Xr tcpdump 1 .
515.Nm
516allows you to correlate and observe the cause-and-affect relationship between
517what you see on the wire (captured using a tool like
518.Xr tcpdump 1 Ns )
519and changes in the TCP control block corresponding to the flow of interest.
520It is therefore useful to use
521.Nm
522and a tool like
523.Xr tcpdump 1
524to gather the necessary data to piece together the complete picture.
525Use of either tool on its own will not be able to provide all of the necessary
526data.
527.Pp
528As a result of needing to interrogate the TCP control block, certain packets
529during the lifecycle of a connection are unable to trigger a
530.Nm
531log message.
532The initial handshake takes place without the existence of a control block and
533the final ACK is exchanged when the connection is in the TIMEWAIT state.
534.Pp
535.Nm
536was designed to minimise the delay introduced to packets traversing the network
537stack.
538This design called for a highly optimised and minimal hook function that
539extracted the minimal details necessary whilst holding the packet up, and
540passing these details to another thread for actual processing and logging.
541.Pp
542This multithreaded design does introduce some contention issues when accessing
543the data structure shared between the threads of operation.
544When the hook function tries to place details in the structure, it must first
545acquire an exclusive lock.
546Likewise, when the processing thread tries to read details from the structure,
547it must also acquire an exclusive lock to do so.
548If one thread holds the lock, the other must wait before it can obtain it.
549This does introduce some additional bounded delay into the kernel's packet
550processing code path.
551.Pp
552In some cases (e.g., low memory, connection termination), TCP packets that enter
553the
554.Nm
555.Xr pfil 9
556hook function will not trigger a log message to be generated.
557.Nm
558refers to this outcome as a
559.Qq skipped packet .
560Note that
561.Nm
562always ensures that packets are allowed to continue through the stack, even if
563they could not successfully trigger a data log message.
564.Nm
565will therefore not introduce any packet loss for TCP/IP packets traversing the
566network stack.
567.Ss Important Behaviours
568The behaviour of a log file path change whilst the module is enabled is as
569follows:
570.Bl -enum
571.It
572Attempt to open the new file path for writing.
573If this fails, the path change will fail and the existing path will continue to
574be used.
575.It
576Assuming the new path is valid and opened successfully:
577.Bl -dash
578.It
579Flush all pending log messages to the old file path.
580.It
581Close the old file path.
582.It
583Switch the active log file pointer to point at the new file path.
584.It
585Commence logging to the new file.
586.El
587.El
588.Pp
589During the time between the flush of pending log messages to the old file and
590commencing logging to the new file, new log messages will still be generated and
591buffered.
592As soon as the new file path is ready for writing, the accumulated log messages
593will be written out to the file.
594.Sh EXAMPLES
595To enable the module's operations, run the following command as root:
596sysctl net.inet.siftr.enabled=1
597.Pp
598To change the granularity of log messages such that 1 log message is
599generated for every 10 TCP packets per connection, run the following
600command as root:
601sysctl net.inet.siftr.ppl=10
602.Pp
603To change the log file location to /tmp/siftr.log, run the following
604command as root:
605sysctl net.inet.siftr.logfile=/tmp/siftr.log
606.Sh SEE ALSO
607.Xr tcpdump 1 ,
608.Xr tcp 4 ,
609.Xr sysctl 8 ,
610.Xr alq 9 ,
611.Xr pfil 9
612.Sh ACKNOWLEDGEMENTS
613Development of this software was made possible in part by grants from the
614Cisco University Research Program Fund at Community Foundation Silicon Valley,
615and the FreeBSD Foundation.
616.Sh HISTORY
617.Nm
618first appeared in
619.Fx 7.4
620and
621.Fx 8.2 .
622.Pp
623.Nm
624was first released in 2007 by Lawrence Stewart and James Healy whilst working on
625the NewTCP research project at Swinburne University of Technology's Centre for
626Advanced Internet Architectures, Melbourne, Australia, which was made possible
627in part by a grant from the Cisco University Research Program Fund at Community
628Foundation Silicon Valley.
629More details are available at:
630.Pp
631http://caia.swin.edu.au/urp/newtcp/
632.Pp
633Work on
634.Nm
635v1.2.x was sponsored by the FreeBSD Foundation as part of
636the
637.Qq Enhancing the FreeBSD TCP Implementation
638project 2008-2009.
639More details are available at:
640.Pp
641https://www.freebsdfoundation.org/
642.Pp
643http://caia.swin.edu.au/freebsd/etcp09/
644.Sh AUTHORS
645.An -nosplit
646.Nm
647was written by
648.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org
649and
650.An James Healy Aq Mt jimmy@deefa.com .
651.Pp
652This manual page was written by
653.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .
654.Sh BUGS
655Current known limitations and any relevant workarounds are outlined below:
656.Bl -dash
657.It
658The internal queue used to pass information between the threads of operation is
659currently unbounded.
660This allows
661.Nm
662to cope with bursty network traffic, but sustained high packet-per-second
663traffic can cause exhaustion of kernel memory if the processing thread cannot
664keep up with the packet rate.
665.It
666If using
667.Nm
668on a machine that is also running other modules utilising the
669.Xr pfil 9
670framework e.g.
671.Xr dummynet 4 ,
672.Xr ipfw 8 ,
673.Xr pf 4 Ns ,
674the order in which you load the modules is important.
675You should kldload the other modules first, as this will ensure TCP packets
676undergo any necessary manipulations before
677.Nm
678.Qq sees
679and processes them.
680.It
681There is a known, harmless lock order reversal warning between the
682.Xr pfil 9
683mutex and tcbinfo TCP lock reported by
684.Xr witness 4
685when
686.Nm
687is enabled in a kernel compiled with
688.Xr witness 4
689support.
690.It
691There is no way to filter which TCP flows you wish to capture data for.
692Post processing is required to separate out data belonging to particular flows
693of interest.
694.It
695The module does not detect deletion of the log file path.
696New log messages will simply be lost if the log file being used by
697.Nm
698is deleted whilst the module is set to use the file.
699Switching to a new log file using the
700.Em net.inet.siftr.logfile
701variable will create the new file and allow log messages to begin being written
702to disk again.
703The new log file path must differ from the path to the deleted file.
704.It
705The hash table used within the code is sized to hold 65536 flows.
706This is not a
707hard limit, because chaining is used to handle collisions within the hash table
708structure.
709However, we suspect (based on analogies with other hash table performance data)
710that the hash table look up performance (and therefore the module's packet
711processing performance) will degrade in an exponential manner as the number of
712unique flows handled in a module enable/disable cycle approaches and surpasses
71365536.
714.It
715There is no garbage collection performed on the flow hash table.
716The only way currently to flush it is to disable
717.Nm .
718.It
719The PPL variable applies to packets that make it into the processing thread,
720not total packets received in the hook function.
721Packets are skipped before the PPL variable is applied, which means there may be
722a slight discrepancy in the triggering of log messages.
723For example, if PPL was set to 10, and the 8th packet since the last log message
724is skipped, the 11th packet will actually trigger the log message to be
725generated.
726This is discussed in greater depth in CAIA technical report 070824A.
727.It
728At the time of writing, there was no simple way to hook into the TCP layer
729to intercept packets.
730.Nm Ap s
731use of IP layer hook points means all IP
732traffic will be processed by the
733.Nm
734.Xr pfil 9
735hook function, which introduces minor, but nonetheless unnecessary packet delay
736and processing overhead on the system for non-TCP packets as well.
737Hooking in at the IP layer is also not ideal from the data gathering point of
738view.
739Packets traversing up the stack will be intercepted and cause a log message
740generation BEFORE they have been processed by the TCP layer, which means we
741cannot observe the cause-and-affect relationship between inbound events and the
742corresponding TCP control block as precisely as could be.
743Ideally,
744.Nm
745should intercept packets after they have been processed by the TCP layer i.e.
746intercept packets coming up the stack after they have been processed by
747.Fn tcp_input ,
748and intercept packets coming down the stack after they have been
749processed by
750.Fn tcp_output .
751The current code still gives satisfactory granularity though, as inbound events
752tend to trigger outbound events, allowing the cause-and-effect to be observed
753indirectly by capturing the state on outbound events as well.
754.It
755The
756.Qq inflight bytes
757value logged by
758.Nm
759does not take into account bytes that have been
760.No SACK Ap ed
761by the receiving host.
762.It
763Packet hash generation does not currently work for IPv6 based TCP packets.
764.It
765Compressed notation is not used for IPv6 address representation.
766This consumes more bytes than is necessary in log output.
767.El
768