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, 717 insertions, 0 deletions
diff --git a/static/freebsd/man4/siftr.4 3.html b/static/freebsd/man4/siftr.4 3.html new file mode 100644 index 00000000..804c2bbf --- /dev/null +++ b/static/freebsd/man4/siftr.4 3.html @@ -0,0 +1,717 @@ +<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> |