docs-xml/manpages/traffic_learner.7.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <refentry id="traffic_learner.7">
   4
   5 <refmeta>
   6         <refentrytitle>traffic_learner</refentrytitle>
   7         <manvolnum>7</manvolnum>
   8         <refmiscinfo class="source">Samba</refmiscinfo>
   9         <refmiscinfo class="manual">User Commands</refmiscinfo>
  10         <refmiscinfo class="version">&doc.version;</refmiscinfo>
  11 </refmeta>
  12
  13
  14 <refnamediv>
  15         <refname>traffic_learner</refname>
  16         <refpurpose>Samba tool to assist with traffic generation.
  17         </refpurpose>
  18 </refnamediv>
  19
  20 <refsynopsisdiv>
  21         <cmdsynopsis>
  22                 <command>traffic_learner</command>
  23                 <arg choice="req">-o OUTPUT_FILE ...</arg>
  24                 <arg choice="opt">-h</arg>
  25                 <arg choice="opt">--dns-mode {inline|count}</arg>
  26                 <arg choice="opt">SUMMARY_FILE</arg>
  27                 <arg choice="opt">SUMMARY_FILE ...</arg>
  28         </cmdsynopsis>
  29 </refsynopsisdiv>
  30
  31 <refsect1>
  32         <title>DESCRIPTION</title>
  33         <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
  34         <manvolnum>7</manvolnum></citerefentry> suite.</para>
  35
  36         <para>This tool assists with generation of Samba traffic.
  37         It takes a traffic-summary file (produced by
  38         <command>traffic_summary.pl</command>) as input and produces a
  39         traffic-model file that can be used by <command>traffic_replay</command>
  40         for traffic generation.</para>
  41
  42         <para>The model file summarizes the types of traffic ('conversations'
  43         between a host and a Samba DC) that occur on a network. The model file
  44         describes the traffic in a way that allows it to be scaled so that
  45         either more (or fewer) packets get sent, and the packets can be sent at
  46         a faster (or slower) rate than that seen in the network.</para>
  47 </refsect1>
  48
  49 <refsect1>
  50         <title>OPTIONS</title>
  51
  52         <variablelist>
  53
  54         <varlistentry>
  55         <term>-h|--help</term>
  56         <listitem><para>
  57         Print a summary of command line options.
  58         </para></listitem>
  59         </varlistentry>
  60
  61         <varlistentry>
  62         <term>SUMMARY_FILE</term>
  63         <listitem><para>
  64         File containing a network traffic-summary. The traffic-summary file
  65         should be generated by <command>traffic_summary.pl</command> from a
  66         packet capture of actual network traffic.
  67         More than one file can be specified, in which case the traffic will
  68         be combined into a single traffic-model. If no SUMMARY_FILE is
  69         specified, this tool will read the traffic-summary from STDIN, i.e.
  70         you can pipe the output from traffic_summary.pl directly to this tool.
  71         </para></listitem>
  72         </varlistentry>
  73
  74         <varlistentry>
  75         <term>-o|--out OUTPUT_FILE</term>
  76         <listitem><para>
  77         The traffic-model that is produced will be written to this file. The
  78         OUTPUT_FILE can then be passed to <command>traffic_replay</command>
  79         to generate (and manipulate) Samba network traffic.
  80         </para></listitem>
  81         </varlistentry>
  82
  83         <varlistentry>
  84         <term>--dns-mode [inline|count]</term>
  85         <listitem><para>
  86         How DNS traffic should be handled by the model.
  87         </para></listitem>
  88         </varlistentry>
  89
  90         </variablelist>
  91 </refsect1>
  92
  93 <refsect1>
  94         <title>EXAMPLES</title>
  95
  96         <para>To take a traffic-summary file and produce a traffic-model
  97         file, use:</para>
  98
  99         <para><command>traffic_learner traffic-summary.txt
 100         -o traffic-model.txt</command></para>
 101
 102         <para>To generate a traffic-model from a packet capture, you can
 103         pipe the traffic summary to STDIN using:</para>
 104
 105         <para><command>tshark -r capture.pcapng -T pdml |
 106         traffic_summary.pl | traffic_learner -o traffic-model.txt</command></para>
 107 </refsect1>
 108
 109 <refsect1>
 110         <title>OUTPUT FILE FORMAT</title>
 111
 112         <para>The output model file describes a Markov model estimating the
 113         probability of a packet occurring given the last two packets.</para>
 114
 115         <para>The count of each continuation after a pair of
 116         successive packets is stored, and the ratios of these counts
 117         is used to calculate probabilities for the next packet.
 118         </para>
 119
 120         <para>The model is stored in JSON format, and also contains
 121         information about the conversation rate and DNS traffic
 122         rate.</para>
 123
 124
 125 <refsect2>
 126         <title>Example ngram listing</title>
 127         <para>The following listing shows a contrived example of a single ngram entry.
 128         </para>
 129
 130         <programlisting>
 131           "ngrams": {
 132              "ldap:0\tdcerpc:11": {
 133                  "lsarpc:77": 1,
 134                  "ldap:2": 370,
 135                  "ldap:3": 62,
 136                  "wait:3": 2,
 137                  "-": 1
 138              }, <lineannotation>[...]</lineannotation>
 139           }
 140         </programlisting>
 141         <para> This counts the observed continuations after an ldap
 142         packet with opcode 0 (a bind) followed by a dcerpc packet with
 143         opcode 11 (also a bind). The most common next packet is
 144         "<code>ldap:2</code>" which is an unbind, so this is the most
 145         likely packet type to be selected in replay. At the other
 146         extreme, lsarpc opcode 77 (lookup names) has been seen only
 147         once, and it is unlikely but possible that this will be
 148         selected in replay.
 149         </para>
 150         <para> There are two special packet types here.
 151         "<code>wait:3</code>" refers to a temporary pause in the
 152         conversation, where the "<code>3</code>" pseudo-opcode indicates
 153         the length of the wait on an exponential scale. That is, a
 154         "<code>wait:4</code>" pause would be about 2.7 times longer that
 155         a "<code>wait:3</code>", which in turn would be similarly longer
 156         than a "<code>wait:2</code>".
 157         </para>
 158
 159         <para>The other special packet is "-", which represents the
 160         limit of the conversation. In the example, this indicates that
 161         one observed conversation ended after this particular ngram.
 162         This special opcode is also used at the beginning of
 163         conversations, which are indicated by the ngram "<code>-\t-</code>".
 164         </para>
 165
 166
 167 </refsect2>
 168 </refsect1>
 169
 170 <refsect1>
 171         <title>VERSION</title>
 172
 173         <para>This man page is complete for version &doc.version; of the Samba
 174         suite.</para>
 175 </refsect1>
 176
 177 <refsect1>
 178         <title>SEE ALSO</title>
 179         <para>
 180         <citerefentry>
 181         <refentrytitle>traffic_replay</refentrytitle><manvolnum>7</manvolnum>
 182         </citerefentry>.
 183         </para>
 184 </refsect1>
 185
 186 <refsect1>
 187         <title>AUTHOR</title>
 188
 189         <para>The original Samba software and related utilities
 190         were created by Andrew Tridgell. Samba is now developed
 191         by the Samba Team as an Open Source project similar
 192         to the way the Linux kernel is developed.</para>
 193
 194         <para>The traffic_learner tool was developed by the Samba team at
 195         Catalyst IT Ltd.</para>
 196
 197         <para>The traffic_learner manpage was written by Tim Beale.</para>
 198 </refsect1>
 199
 200 </refentry>