share/man/man4/siftr.4

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