---------------------------------------------- SCILAB-SIFTR v0.1 README (released 16th July 2012) ---------------------------------------------- This document is part of SCILAB-SIFTR ( http://caia.swin.edu.au/newtcp/tools.html ). It gives an overview of SCILAB-SIFTR. OVERVIEW -------- SIFTR [1] provides an in-depth view of the FreeBSD TCP stack. The log files it produces give per-packet states of the TCP stack and TCP flow. The SCILAB-SIFTR module is a set of functions to facilitate SIFTR [1] users in parsing SIFTR log files, in order to enhance their TCP research abilities. DOCUMENTATION ------------- Note: a '\' in the example log lines indicates a line continuation and is not part of the log messages. All functions take at least a file pointer or path string as an argument. To avoid unnecessary overhead, if you are doing multiple function calls on the same file, pass a file pointer to the functions instead of a string. For exampe: fp = mopen("siftr.log"); head = siftr_head(fp); data = siftr_getl(fp, 1000); mclose(fp); siftr_head ( path ) Path: file pointer or path string. Returns an array of the values from the enable_time line of the SIFTR log file. Each of the key=value pairs from the enable line [2] are included as elements in the returned array. An example SIFTR enable line is as follows: enable_time_secs=1238556193 enable_time_usecs=462104 \ siftrver=1.2.2 hz=1000 tcp_rtt_scale=32 \ sysname=FreeBSD sysver=604000 ipmode=4 siftr_tail ( path ) Path: file pointer or path string. Returns an array of the values from the disable_time line of the SIFTR log file. Each of the key=value pairs from the disable line are included as elements in the returned array. The hosts list is left in string form, and can be expanded out by using: t = siftr_tail("siftr.log"); strsplit( t['flow_list'], ','); An example SIFTR disable line is as follows: disable_time_secs=1238556197 disable_time_usecs=933607 \ num_inbound_tcp_pkts=356 num_outbound_tcp_pkts=627 \ total_tcp_pkts=983 num_inbound_skipped_pkts_malloc=0 \ num_outbound_skipped_pkts_malloc=0 num_inbound_skipped_pkts_mtx=0 \ num_outbound_skipped_pkts_mtx=0 num_inbound_skipped_pkts_tcb=0 \ num_outbound_skipped_pkts_tcb=0 num_inbound_skipped_pkts_icb=0 \ num_outbound_skipped_pkts_icb=0 total_skipped_tcp_pkts=0 \ flow_list=172.16.7.28;22-172.16.2.5;55931, siftr_read_meta ( path ) Path: file pointer or path string. Returns an array containing two child arrays, "head" and "tail", containing the respective arrays from siftr_head() and siftr_tail(). siftr_getl( path, lines ) Path: file pointer or path string. Lines: Number of lines to read from SIFTR log file. -1 to read EOF. If lines is greater than what remains in the file, siftr_getl will return what remains. Returns an array of structs containing each of the columns of data from the SIFTR log file. See the SIFTR documentation [2] for further description of each column. Note: If you pass a path string to siftr_getl(), it will read the specified amount of lines from the beginning of the file. The lines argument is passed straight to mgetl() in Scilab and any lines that are not 'packet' lines are ignored. Typically, this means n-1 rows will be returned, as the first line read is typically the enable line and is ignored. An example log line is as follows: o,0xbec491a5,1238556193.463551,172.16.7.28,22,172.16.2.5,55931, \ 1073725440,172312,6144,66560,66608,8,1,4,1448,936,1,996,255, \ 33304,208,66608,0,208,0 The meaning of each of the comma-separated fields is shown in [2]. For a description of each of the fields returned by each function, please see the "Log Format" section of the SIFTR man page [2]. LIMITATIONS ----------- Scilab's stacksize will limit the number of lines the siftr_getl() function can read in one call. If you get an error regarding the stacksize being exceeded, use `stacksize ('max');` [3] to increase the available stacksize. Note that this will significantly increase the RAM usage of Scilab. If this does not stop the error message from appearing, alter your script such that the available stack is used more efficiently - request small numbers of lines at a time from siftr_getl() and reduce them to just the data you need before requesting more lines. CONTRIBUTIONS ------------- We welcome your feedback and contributions! If you have discovered a bug, have a request for a new feature or have produced a code patch, please contact Grenville Armitage (garmitage@swin.edu.au). REFERENCES ---------- [1] http://caia.swin.edu.au/newtcp/tools.html newtcp, CAIA [2] http://www.freebsd.org/cgi/man.cgi?query=siftr SIFTR man page [3] http://help.scilab.org/docs/5.3.1/en_US/stacksize.html Stacksize() - Scilab manual LICENSE ------- SCILAB-SIFTR is distributed under the FreeBSD license. Copyright (c) 2010-2012 Centre for Advanced Internet Architectures, Swinburne University of Technology. Author: Greville Armitage ( garmitage@swin.edu.au ) Chris Holman ( 6963420@student.swin.edu.au ) Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. CONTACT ------- The SCILAB-SIFTR module is part of the NewTCP/SIFTR project, whose website is: http://caia/newtcp/tools.html If you have any questions or want to report any bugs please contact Grenville Armitage (garmitage@swin.edu.au). Centre for Advanced Internet Architectures Swinburne University of Technology Melbourne, Australia CRICOS number 00111D http://www.caia.swin.edu.au