diff options
Diffstat (limited to 'static/freebsd/man4/siftr.4 3.html')
| -rw-r--r-- | static/freebsd/man4/siftr.4 3.html | 717 |
1 files changed, 0 insertions, 717 deletions
diff --git a/static/freebsd/man4/siftr.4 3.html b/static/freebsd/man4/siftr.4 3.html deleted file mode 100644 index 804c2bbf..00000000 --- a/static/freebsd/man4/siftr.4 3.html +++ /dev/null @@ -1,717 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">SIFTR(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">SIFTR(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">SIFTR</code> — - <span class="Nd">Statistical Information For TCP Research</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp">To load the driver as a module at run-time, run the following - command as root:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>kldload siftr</pre> -</div> -<p class="Pp">Alternatively, to load the driver as a module at boot time, add - the following line into the <a class="Xr">loader.conf(5)</a> file:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>siftr_load="YES"</pre> -</div> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">SIFTR</code> - (<a class="permalink" href="#S"><i class="Em" id="S">S</i></a>tatistical - <a class="permalink" href="#I"><i class="Em" id="I">I</i></a>nformation - <a class="permalink" href="#F"><i class="Em" id="F">F</i></a>or - <a class="permalink" href="#T"><i class="Em" id="T">T</i></a>CP - <a class="permalink" href="#R"><i class="Em" id="R">R</i></a>esearch) kernel - module logs a range of statistics on active TCP connections to a log file. - It provides the ability to make highly granular measurements of TCP - connection state, aimed at system administrators, developers and - researchers.</p> -<section class="Ss"> -<h2 class="Ss" id="Compile-time_Configuration"><a class="permalink" href="#Compile-time_Configuration">Compile-time - Configuration</a></h2> -<p class="Pp">The default operation of <code class="Nm">SIFTR</code> is to - capture IPv4 TCP/IP packets. <code class="Nm">SIFTR</code> can be configured - to support IPv4 and IPv6 by uncommenting:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>CFLAGS+=-DSIFTR_IPV6</pre> -</div> -<p class="Pp">in ⟨sys/modules/siftr/Makefile⟩ and recompiling.</p> -<p class="Pp">In the IPv4-only (default) mode, standard dotted decimal notation - (e.g. "136.186.229.95") is used to format IPv4 addresses for - logging. In IPv6 mode, standard dotted decimal notation is used to format - IPv4 addresses, and standard colon-separated hex notation (see RFC 4291) is - used to format IPv6 addresses (e.g. "fd00::2") for logging.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Run-time_Configuration"><a class="permalink" href="#Run-time_Configuration">Run-time - Configuration</a></h2> -<p class="Pp"><code class="Nm">SIFTR</code> utilises the - <a class="Xr">sysctl(8)</a> interface to export its configuration variables - to user-space. The following variables are available:</p> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="net.inet.siftr.enabled"><var class="Va">net.inet.siftr.enabled</var></dt> - <dd>controls whether the module performs its measurements or not. By default, - the value is set to 0, which means the module will not be taking any - measurements. Having the module loaded with - <var class="Va">net.inet.siftr.enabled</var> set to 0 will have no impact - on the performance of the network stack, as the packet filtering hooks are - only inserted when <var class="Va">net.inet.siftr.enabled</var> is set to - 1.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="net.inet.siftr.ppl"><var class="Va">net.inet.siftr.ppl</var></dt> - <dd>controls how many inbound/outbound packets for a given TCP connection will - cause a log message to be generated for the connection. By default, the - value is set to 1, which means the module will log a message for every - packet of every TCP connection. The value can be set to any integer in the - range [1,2^32], and can be changed at any time, even while the module is - enabled.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="net.inet.siftr.logfile"><var class="Va">net.inet.siftr.logfile</var></dt> - <dd>controls the path to the file that the module writes its log messages to. - By default, the file /var/log/siftr.log is used. The path can be changed - at any time, even while the module is enabled.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="net.inet.siftr.port_filter"><var class="Va">net.inet.siftr.port_filter</var></dt> - <dd>controls on which source or destination port <code class="Nm">SIFTR</code> - should capture. By default, the value is set to 0, which means all ports - are eligible for logging. Set to any other value, only packets where - either the source or destination port is equal to this number are - logged.</dd> -</dl> -</div> -</section> -<section class="Ss"> -<h2 class="Ss" id="Log_Format"><a class="permalink" href="#Log_Format">Log - Format</a></h2> -<p class="Pp">A typical <code class="Nm">SIFTR</code> log file will contain 3 - different types of log message. All messages are written in plain ASCII - text.</p> -<p class="Pp">Note: The "\" present in the example log messages in - this section indicates a line continuation and is not part of the actual log - message.</p> -<p class="Pp">The first type of log message is written to the file when the - module is enabled and starts collecting data from the running kernel. The - text below shows an example module enable log. The fields are tab delimited - key-value pairs which describe some basic information about the system.</p> -<div class="Bd Pp Bd-indent Li"> -<pre>enable_time_secs=1685191807 enable_time_usecs=160752 \ -siftrver=1.3.0 sysname=FreeBSD sysver=1400089 ipmode=4</pre> -</div> -<p class="Pp">Field descriptions are as follows:</p> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="enable_time_secs"><var class="Va">enable_time_secs</var></dt> - <dd>time at which the module was enabled, in seconds since the UNIX - epoch.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="enable_time_usecs"><var class="Va">enable_time_usecs</var></dt> - <dd>time at which the module was enabled, in microseconds since - enable_time_secs.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="siftrver"><var class="Va">siftrver</var></dt> - <dd>version of <code class="Nm">SIFTR</code>.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="sysname"><var class="Va">sysname</var></dt> - <dd>operating system name.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="sysver"><var class="Va">sysver</var></dt> - <dd>operating system version.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="ipmode"><var class="Va">ipmode</var></dt> - <dd>IP mode as defined at compile time. An ipmode of "4" means IPv6 - is not supported and IP addresses are logged in regular dotted quad - format. An ipmode of "6" means IPv6 is supported, and IP - addresses are logged in dotted quad or hex format, as described in the - "Compile-time Configuration" subsection.</dd> -</dl> -</div> -<p class="Pp">The second type of log message is written to the file when a data - log message is generated. The text below shows an example data log triggered - by an IPv4 TCP/IP packet. The data is CSV formatted.</p> -<div class="Bd Pp Bd-indent Li"> -<pre>o,1685191814.185109,10.1.1.2,32291,10.1.1.3,5001,1073725440, \ -14480,2,65160,65700,7,9,4,1460,1000,1,16778209,230000,33580,0, \ -65700,0,0,0,86707916,130</pre> -</div> -<p class="Pp">Field descriptions are as follows:</p> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="1"><var class="Va">1</var></dt> - <dd>Direction of packet that triggered the log message. Either "i" - for in, or "o" for out.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="2"><var class="Va">2</var></dt> - <dd>Time at which the packet that triggered the log message was processed by - the <a class="Xr">pfil(9)</a> hook function, in seconds and microseconds - since the UNIX epoch.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="3"><var class="Va">3</var></dt> - <dd>The IPv4 or IPv6 address of the local host, in dotted quad (IPv4 packet) - or colon-separated hex (IPv6 packet) notation.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="4"><var class="Va">4</var></dt> - <dd>The TCP port that the local host is communicating via.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="5"><var class="Va">5</var></dt> - <dd>The IPv4 or IPv6 address of the foreign host, in dotted quad (IPv4 packet) - or colon-separated hex (IPv6 packet) notation.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="6"><var class="Va">6</var></dt> - <dd>The TCP port that the foreign host is communicating via.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="7"><var class="Va">7</var></dt> - <dd>The slow start threshold for the flow, in bytes.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="8"><var class="Va">8</var></dt> - <dd>The current congestion window for the flow, in bytes.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="9"><var class="Va">9</var></dt> - <dd>The current state of the t_flags2 field for the flow.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="10"><var class="Va">10</var></dt> - <dd>The current sending window for the flow, in bytes. The post scaled value - is reported.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="11"><var class="Va">11</var></dt> - <dd>The current receive window for the flow, in bytes. The post scaled value - is always reported.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="12"><var class="Va">12</var></dt> - <dd>The current window scaling factor for the sending window.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="13"><var class="Va">13</var></dt> - <dd>The current window scaling factor for the receiving window.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="14"><var class="Va">14</var></dt> - <dd>The current state of the TCP finite state machine, as defined in - ⟨<span class="Pa">netinet/tcp_fsm.h</span>⟩.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="15"><var class="Va">15</var></dt> - <dd>The maximum segment size for the flow, in bytes.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="16"><var class="Va">16</var></dt> - <dd>The current smoothed RTT estimate for the flow, in units of - microsecond.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="17"><var class="Va">17</var></dt> - <dd>SACK enabled indicator. 1 if SACK enabled, 0 otherwise.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="18"><var class="Va">18</var></dt> - <dd>The current state of the TCP flags for the flow. See - ⟨<span class="Pa">netinet/tcp_var.h</span>⟩ for information - about the various flags.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="19"><var class="Va">19</var></dt> - <dd>The current retransmission timeout length for the flow, in units - microsecond.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="20"><var class="Va">20</var></dt> - <dd>The current size of the socket send buffer in bytes.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="21"><var class="Va">21</var></dt> - <dd>The current number of bytes in the socket send buffer.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="22"><var class="Va">22</var></dt> - <dd>The current size of the socket receive buffer in bytes.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="23"><var class="Va">23</var></dt> - <dd>The current number of bytes in the socket receive buffer.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="24"><var class="Va">24</var></dt> - <dd>The current number of unacknowledged bytes in-flight. Bytes acknowledged - via SACK are not excluded from this count.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="25"><var class="Va">25</var></dt> - <dd>The current number of segments in the reassembly queue.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="26"><var class="Va">26</var></dt> - <dd>Flowid for the connection. A caveat: Zero '0' either represents a valid - flowid or a default value when it's not being set. There is no easy way to - differentiate without looking at actual network interface card and drivers - being used.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="27"><var class="Va">27</var></dt> - <dd>Flow type for the connection. Flowtype defines which protocol fields are - hashed to produce the flowid. A complete listing is available in - <span class="Pa">sys/mbuf.h</span> under - <code class="Dv">M_HASHTYPE_*</code>.</dd> -</dl> -</div> -<p class="Pp">The third type of log message is written to the file when the - module is disabled and ceases collecting data from the running kernel. The - text below shows an example module disable log. The fields are tab delimited - key-value pairs which provide statistics about operations since the module - was most recently enabled.</p> -<div class="Bd Pp Bd-indent Li"> -<pre>disable_time_secs=1685191816 disable_time_usecs=629397 \ -num_inbound_tcp_pkts=10 num_outbound_tcp_pkts=10 \ -total_tcp_pkts=20 num_inbound_skipped_pkts_malloc=0 \ -num_outbound_skipped_pkts_malloc=0 num_inbound_skipped_pkts_tcpcb=2 \ -num_outbound_skipped_pkts_tcpcb=2 num_inbound_skipped_pkts_inpcb=0 \ -num_outbound_skipped_pkts_inpcb=0 total_skipped_tcp_pkts=4 \ -flow_list=10.1.1.2;32291-10.1.1.3;5001,10.1.1.2;58544-10.1.1.3;5001,</pre> -</div> -<p class="Pp">Field descriptions are as follows:</p> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="disable_time_secs"><var class="Va">disable_time_secs</var></dt> - <dd>Time at which the module was disabled, in seconds since the UNIX - epoch.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="disable_time_usecs"><var class="Va">disable_time_usecs</var></dt> - <dd>Time at which the module was disabled, in microseconds since - disable_time_secs.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="num_inbound_tcp_pkts"><var class="Va">num_inbound_tcp_pkts</var></dt> - <dd>Number of TCP packets that traversed up the network stack. This only - includes inbound TCP packets during the periods when - <code class="Nm">SIFTR</code> was enabled.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="num_outbound_tcp_pkts"><var class="Va">num_outbound_tcp_pkts</var></dt> - <dd>Number of TCP packets that traversed down the network stack. This only - includes outbound TCP packets during the periods when - <code class="Nm">SIFTR</code> was enabled.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="total_tcp_pkts"><var class="Va">total_tcp_pkts</var></dt> - <dd>The summation of num_inbound_tcp_pkts and num_outbound_tcp_pkts.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="num_inbound_skipped_pkts_malloc"><var class="Va">num_inbound_skipped_pkts_malloc</var></dt> - <dd>Number of inbound packets that were not processed because of failed - <a class="permalink" href="#malloc"><code class="Fn" id="malloc">malloc</code></a>() - calls.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="num_outbound_skipped_pkts_malloc"><var class="Va">num_outbound_skipped_pkts_malloc</var></dt> - <dd>Number of outbound packets that were not processed because of failed - <code class="Fn">malloc</code>() calls.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="num_inbound_skipped_pkts_tcpcb"><var class="Va">num_inbound_skipped_pkts_tcpcb</var></dt> - <dd>Number of inbound packets that were not processed because of failure to - find the TCP control block associated with the packet.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="num_outbound_skipped_pkts_tcpcb"><var class="Va">num_outbound_skipped_pkts_tcpcb</var></dt> - <dd>Number of outbound packets that were not processed because of failure to - find the TCP control block associated with the packet.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="num_inbound_skipped_pkts_inpcb"><var class="Va">num_inbound_skipped_pkts_inpcb</var></dt> - <dd>Number of inbound packets that were not processed because of failure to - find the IP control block associated with the packet.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="num_outbound_skipped_pkts_inpcb"><var class="Va">num_outbound_skipped_pkts_inpcb</var></dt> - <dd>Number of outbound packets that were not processed because of failure to - find the IP control block associated with the packet.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="total_skipped_tcp_pkts"><var class="Va">total_skipped_tcp_pkts</var></dt> - <dd>The summation of all skipped packet counters.</dd> -</dl> -</div> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt id="flow_list"><var class="Va">flow_list</var></dt> - <dd>A CSV list of TCP flows that triggered data log messages to be generated - since the module was loaded. Each flow entry in the CSV list is formatted - as "local_ip;local_port-foreign_ip;foreign_port". If there are - no entries in the list (i.e., no data log messages were generated), the - value will be blank. If there is at least one entry in the list, a - trailing comma will always be present.</dd> -</dl> -</div> -<p class="Pp">The total number of data log messages found in the log file for a - module enable/disable cycle should equate to total_tcp_pkts - - total_skipped_tcp_pkts.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION - NOTES</a></h1> -<p class="Pp"><code class="Nm">SIFTR</code> hooks into the network stack using - the <a class="Xr">pfil(9)</a> interface. In its current incarnation, it - hooks into the AF_INET/AF_INET6 (IPv4/IPv6) <a class="Xr">pfil(9)</a> - filtering points, which means it sees packets at the IP layer of the network - stack. This means that TCP packets inbound to the stack are intercepted - before they have been processed by the TCP layer. Packets outbound from the - stack are intercepted after they have been processed by the TCP layer.</p> -<p class="Pp">The diagram below illustrates how <code class="Nm">SIFTR</code> - inserts itself into the stack.</p> -<div class="Bd Pp Bd-indent Li"> -<pre>---------------------------------- - Upper Layers ----------------------------------- - ^ | - | | - | | - | v - TCP in TCP out ----------------------------------- - ^ | - |________ _________| - | | - | v - --------- - | SIFTR | - --------- - ^ | - ________| |__________ - | | - | v -IPv{4/6} in IPv{4/6} out ----------------------------------- - ^ | - | | - | v -Layer 2 in Layer 2 out ----------------------------------- - Physical Layer -----------------------------------</pre> -</div> -<p class="Pp"><code class="Nm">SIFTR</code> uses the <a class="Xr">alq(9)</a> - interface to manage writing data to disk.</p> -<p class="Pp">At first glance, you might mistakenly think that - <code class="Nm">SIFTR</code> extracts information from individual TCP - packets. This is not the case. <code class="Nm">SIFTR</code> uses TCP packet - events (inbound and outbound) for each TCP flow originating from the system - to trigger a dump of the state of the TCP control block for that flow. With - the PPL set to 1, we are in effect sampling each TCP flow's control block - state as frequently as flow packets enter/leave the system. For example, - setting PPL to 2 halves the sampling rate i.e., every second flow packet - (inbound OR outbound) causes a dump of the control block state.</p> -<p class="Pp">The distinction between interrogating individual packets versus - interrogating the control block is important, because - <code class="Nm">SIFTR</code> does not remove the need for packet capturing - tools like <a class="Xr">tcpdump(1)</a>. <code class="Nm">SIFTR</code> - allows you to correlate and observe the cause-and-affect relationship - between what you see on the wire (captured using a tool like - <a class="Xr">tcpdump(1)</a>) and changes in the TCP control block - corresponding to the flow of interest. It is therefore useful to use - <code class="Nm">SIFTR</code> and a tool like <a class="Xr">tcpdump(1)</a> - to gather the necessary data to piece together the complete picture. Use of - either tool on its own will not be able to provide all of the necessary - data.</p> -<p class="Pp">As a result of needing to interrogate the TCP control block, - certain packets during the lifecycle of a connection are unable to trigger a - <code class="Nm">SIFTR</code> log message. The initial handshake takes place - without the existence of a control block or the complete initialization of - the control block, and the final ACK is exchanged when the connection is in - the TIMEWAIT state.</p> -<p class="Pp"><code class="Nm">SIFTR</code> was designed to minimise the delay - introduced to packets traversing the network stack. This design called for a - highly optimised and minimal hook function that extracted the minimal - details necessary whilst holding the packet up, and passing these details to - another thread for actual processing and logging.</p> -<p class="Pp">This multithreaded design does introduce some contention issues - when accessing the data structure shared between the threads of operation. - When the hook function tries to place details in the structure, it must - first acquire an exclusive lock. Likewise, when the processing thread tries - to read details from the structure, it must also acquire an exclusive lock - to do so. If one thread holds the lock, the other must wait before it can - obtain it. This does introduce some additional bounded delay into the - kernel's packet processing code path.</p> -<p class="Pp">In some cases (e.g., low memory, connection termination), TCP - packets that enter the <code class="Nm">SIFTR</code> - <a class="Xr">pfil(9)</a> hook function will not trigger a log message to be - generated. <code class="Nm">SIFTR</code> refers to this outcome as a - "skipped packet". Note that <code class="Nm">SIFTR</code> always - ensures that packets are allowed to continue through the stack, even if they - could not successfully trigger a data log message. - <code class="Nm">SIFTR</code> will therefore not introduce any packet loss - for TCP/IP packets traversing the network stack.</p> -<section class="Ss"> -<h2 class="Ss" id="Important_Behaviours"><a class="permalink" href="#Important_Behaviours">Important - Behaviours</a></h2> -<p class="Pp">The behaviour of a log file path change whilst the module is - enabled is as follows:</p> -<ol class="Bl-enum"> - <li>Attempt to open the new file path for writing. If this fails, the path - change will fail and the existing path will continue to be used.</li> - <li>Assuming the new path is valid and opened successfully: - <ul class="Bl-dash"> - <li>Flush all pending log messages to the old file path.</li> - <li>Close the old file path.</li> - <li>Switch the active log file pointer to point at the new file path.</li> - <li>Commence logging to the new file.</li> - </ul> - </li> -</ol> -<p class="Pp">During the time between the flush of pending log messages to the - old file and commencing logging to the new file, new log messages will still - be generated and buffered. As soon as the new file path is ready for - writing, the accumulated log messages will be written out to the file.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">To enable the module's operations, run the following command as - root: sysctl net.inet.siftr.enabled=1</p> -<p class="Pp">To change the granularity of log messages such that 1 log message - is generated for every 10 TCP packets per connection, run the following - command as root: sysctl net.inet.siftr.ppl=10</p> -<p class="Pp">To change the log file location to /tmp/siftr.log, run the - following command as root: sysctl net.inet.siftr.logfile=/tmp/siftr.log</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">tcpdump(1)</a>, <a class="Xr">tcp(4)</a>, - <a class="Xr">sysctl(8)</a>, <a class="Xr">alq(9)</a>, - <a class="Xr">pfil(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="ACKNOWLEDGEMENTS"><a class="permalink" href="#ACKNOWLEDGEMENTS">ACKNOWLEDGEMENTS</a></h1> -<p class="Pp">Development of this software was made possible in part by grants - from the Cisco University Research Program Fund at Community Foundation - Silicon Valley, and the FreeBSD Foundation.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp"><code class="Nm">SIFTR</code> first appeared in - <span class="Ux">FreeBSD 7.4</span> and <span class="Ux">FreeBSD - 8.2</span>.</p> -<p class="Pp"><code class="Nm">SIFTR</code> was first released in 2007 by - Lawrence Stewart and James Healy whilst working on the NewTCP research - project at Swinburne University of Technology's Centre for Advanced Internet - Architectures, Melbourne, Australia, which was made possible in part by a - grant from the Cisco University Research Program Fund at Community - Foundation Silicon Valley. More details are available at:</p> -<p class="Pp">http://caia.swin.edu.au/urp/newtcp/</p> -<p class="Pp">Work on <code class="Nm">SIFTR</code> v1.2.x was sponsored by the - FreeBSD Foundation as part of the "Enhancing the FreeBSD TCP - Implementation" project 2008-2009. More details are available at:</p> -<p class="Pp">https://www.freebsdfoundation.org/</p> -<p class="Pp">http://caia.swin.edu.au/freebsd/etcp09/</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp"><code class="Nm">SIFTR</code> was written by - <span class="An">Lawrence Stewart</span> - <<a class="Mt" href="mailto:lstewart@FreeBSD.org">lstewart@FreeBSD.org</a>> - and <span class="An">James Healy</span> - <<a class="Mt" href="mailto:jimmy@deefa.com">jimmy@deefa.com</a>>.</p> -<p class="Pp">This manual page was written by <span class="An">Lawrence - Stewart</span> - <<a class="Mt" href="mailto:lstewart@FreeBSD.org">lstewart@FreeBSD.org</a>>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> -<p class="Pp">Current known limitations and any relevant workarounds are - outlined below:</p> -<ul class="Bl-dash"> - <li>The internal queue used to pass information between the threads of - operation is currently unbounded. This allows - <code class="Nm">SIFTR</code> to cope with bursty network traffic, but - sustained high packet-per-second traffic can cause exhaustion of kernel - memory if the processing thread cannot keep up with the packet rate.</li> - <li>If using <code class="Nm">SIFTR</code> on a machine that is also running - other modules utilising the <a class="Xr">pfil(9)</a> framework e.g. - <a class="Xr">dummynet(4)</a>, <a class="Xr">ipfw(8)</a>, - <a class="Xr">pf(4)</a>, the order in which you load the modules is - important. You should kldload the other modules first, as this will ensure - TCP packets undergo any necessary manipulations before - <code class="Nm">SIFTR</code> "sees" and processes them.</li> - <li>There is a known, harmless lock order reversal warning between the - <a class="Xr">pfil(9)</a> mutex and tcbinfo TCP lock reported by - <a class="Xr">witness(4)</a> when <code class="Nm">SIFTR</code> is enabled - in a kernel compiled with <a class="Xr">witness(4)</a> support.</li> - <li>There is no way to filter which TCP flows you wish to capture data for. - Post processing is required to separate out data belonging to particular - flows of interest.</li> - <li>The module does not detect deletion of the log file path. New log messages - will simply be lost if the log file being used by - <code class="Nm">SIFTR</code> is deleted whilst the module is set to use - the file. Switching to a new log file using the - <i class="Em">net.inet.siftr.logfile</i> variable will create the new file - and allow log messages to begin being written to disk again. The new log - file path must differ from the path to the deleted file.</li> - <li>The hash table used within the code is sized to hold 65536 flows. This is - not a hard limit, because chaining is used to handle collisions within the - hash table structure. However, we suspect (based on analogies with other - hash table performance data) that the hash table look up performance (and - therefore the module's packet processing performance) will degrade in an - exponential manner as the number of unique flows handled in a module - enable/disable cycle approaches and surpasses 65536.</li> - <li>There is no garbage collection performed on the flow hash table. The only - way currently to flush it is to disable - <code class="Nm">SIFTR</code>.</li> - <li>The PPL variable applies to packets that make it into the processing - thread, not total packets received in the hook function. Packets are - skipped before the PPL variable is applied, which means there may be a - slight discrepancy in the triggering of log messages. For example, if PPL - was set to 10, and the 8th packet since the last log message is skipped, - the 11th packet will actually trigger the log message to be generated. - This is discussed in greater depth in CAIA technical report 070824A.</li> - <li>At the time of writing, there was no simple way to hook into the TCP layer - to intercept packets. <code class="Nm">SIFTR</code>'s use of IP layer hook - points means all IP traffic will be processed by the - <code class="Nm">SIFTR</code> <a class="Xr">pfil(9)</a> hook function, - which introduces minor, but nonetheless unnecessary packet delay and - processing overhead on the system for non-TCP packets as well. Hooking in - at the IP layer is also not ideal from the data gathering point of view. - Packets traversing up the stack will be intercepted and cause a log - message generation BEFORE they have been processed by the TCP layer, which - means we cannot observe the cause-and-affect relationship between inbound - events and the corresponding TCP control block as precisely as could be. - Ideally, <code class="Nm">SIFTR</code> should intercept packets after they - have been processed by the TCP layer i.e. intercept packets coming up the - stack after they have been processed by - <code class="Fn">tcp_input</code>(), and intercept packets coming down the - stack after they have been processed by - <code class="Fn">tcp_output</code>(). The current code still gives - satisfactory granularity though, as inbound events tend to trigger - outbound events, allowing the cause-and-effect to be observed indirectly - by capturing the state on outbound events as well.</li> - <li>The "inflight bytes" value logged by - <code class="Nm">SIFTR</code> does not take into account bytes that have - been <span class="No">SACK</span>'ed by the receiving host.</li> -</ul> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">May 29, 2023</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |