share/man/man4/siftr.4

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