summaryrefslogtreecommitdiffstats
path: root/docs-xml/manpages/traffic_learner.7.xml
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs-xml/manpages/traffic_learner.7.xml199
1 files changed, 199 insertions, 0 deletions
diff --git a/docs-xml/manpages/traffic_learner.7.xml b/docs-xml/manpages/traffic_learner.7.xml
new file mode 100644
index 0000000..b921035
--- /dev/null
+++ b/docs-xml/manpages/traffic_learner.7.xml
@@ -0,0 +1,199 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<refentry id="traffic_learner.7">
+
+<refmeta>
+ <refentrytitle>traffic_learner</refentrytitle>
+ <manvolnum>7</manvolnum>
+ <refmiscinfo class="source">Samba</refmiscinfo>
+ <refmiscinfo class="manual">User Commands</refmiscinfo>
+ <refmiscinfo class="version">&doc.version;</refmiscinfo>
+</refmeta>
+
+
+<refnamediv>
+ <refname>traffic_learner</refname>
+ <refpurpose>Samba tool to assist with traffic generation.
+ </refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+ <cmdsynopsis>
+ <command>traffic_learner</command>
+ <arg choice="req">-o OUTPUT_FILE ...</arg>
+ <arg choice="opt">-h</arg>
+ <arg choice="opt">--dns-mode {inline|count}</arg>
+ <arg choice="opt">SUMMARY_FILE</arg>
+ <arg choice="opt">SUMMARY_FILE ...</arg>
+ </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+ <title>DESCRIPTION</title>
+ <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
+ <manvolnum>7</manvolnum></citerefentry> suite.</para>
+
+ <para>This tool assists with generation of Samba traffic.
+ It takes a traffic-summary file (produced by
+ <command>traffic_summary.pl</command>) as input and produces a
+ traffic-model file that can be used by <command>traffic_replay</command>
+ for traffic generation.</para>
+
+ <para>The model file summarizes the types of traffic ('conversations'
+ between a host and a Samba DC) that occur on a network. The model file
+ describes the traffic in a way that allows it to be scaled so that
+ either more (or fewer) packets get sent, and the packets can be sent at
+ a faster (or slower) rate than that seen in the network.</para>
+</refsect1>
+
+<refsect1>
+ <title>OPTIONS</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>-h|--help</term>
+ <listitem><para>
+ Print a summary of command line options.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SUMMARY_FILE</term>
+ <listitem><para>
+ File containing a network traffic-summary. The traffic-summary file
+ should be generated by <command>traffic_summary.pl</command> from a
+ packet capture of actual network traffic.
+ More than one file can be specified, in which case the traffic will
+ be combined into a single traffic-model. If no SUMMARY_FILE is
+ specified, this tool will read the traffic-summary from STDIN, i.e.
+ you can pipe the output from traffic_summary.pl directly to this tool.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-o|--out OUTPUT_FILE</term>
+ <listitem><para>
+ The traffic-model that is produced will be written to this file. The
+ OUTPUT_FILE can then be passed to <command>traffic_replay</command>
+ to generate (and manipulate) Samba network traffic.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--dns-mode [inline|count]</term>
+ <listitem><para>
+ How DNS traffic should be handled by the model.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+</refsect1>
+
+<refsect1>
+ <title>EXAMPLES</title>
+
+ <para>To take a traffic-summary file and produce a traffic-model
+ file, use:</para>
+
+ <para><command>traffic_learner traffic-summary.txt
+ -o traffic-model.txt</command></para>
+
+ <para>To generate a traffic-model from a packet capture, you can
+ pipe the traffic summary to STDIN using:</para>
+
+ <para><command>tshark -r capture.pcapng -T pdml |
+ traffic_summary.pl | traffic_learner -o traffic-model.txt</command></para>
+</refsect1>
+
+<refsect1>
+ <title>OUTPUT FILE FORMAT</title>
+
+ <para>The output model file describes a Markov model estimating the
+ probability of a packet occurring given the last two packets.</para>
+
+ <para>The count of each continuation after a pair of
+ successive packets is stored, and the ratios of these counts
+ is used to calculate probabilities for the next packet.
+ </para>
+
+ <para>The model is stored in JSON format, and also contains
+ information about the packet rate and DNS traffic rate.</para>
+
+
+<refsect2>
+ <title>Example ngram listing</title>
+ <para>The following listing shows a contrived example of a single ngram entry.
+ </para>
+
+ <programlisting>
+ "ngrams": {
+ "ldap:0\tdcerpc:11": {
+ "lsarpc:77": 1,
+ "ldap:2": 370,
+ "ldap:3": 62,
+ "wait:3": 2,
+ "-": 1
+ }, <lineannotation>[...]</lineannotation>
+ }
+ </programlisting>
+ <para> This counts the observed continuations after an ldap
+ packet with opcode 0 (a bind) followed by a dcerpc packet with
+ opcode 11 (also a bind). The most common next packet is
+ "<code>ldap:2</code>" which is an unbind, so this is the most
+ likely packet type to be selected in replay. At the other
+ extreme, lsarpc opcode 77 (lookup names) has been seen only
+ once, and it is unlikely but possible that this will be
+ selected in replay.
+ </para>
+ <para> There are two special packet types here.
+ "<code>wait:3</code>" refers to a temporary pause in the
+ conversation, where the "<code>3</code>" pseudo-opcode indicates
+ the length of the wait on an exponential scale. That is, a
+ "<code>wait:4</code>" pause would be about 2.7 times longer that
+ a "<code>wait:3</code>", which in turn would be similarly longer
+ than a "<code>wait:2</code>".
+ </para>
+
+ <para>The other special packet is "-", which represents the
+ limit of the conversation. In the example, this indicates that
+ one observed conversation ended after this particular ngram.
+ This special opcode is also used at the beginning of
+ conversations, which are indicated by the ngram "<code>-\t-</code>".
+ </para>
+
+
+</refsect2>
+</refsect1>
+
+<refsect1>
+ <title>VERSION</title>
+
+ <para>This man page is complete for version &doc.version; of the Samba
+ suite.</para>
+</refsect1>
+
+<refsect1>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>traffic_replay</refentrytitle><manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para>
+</refsect1>
+
+<refsect1>
+ <title>AUTHOR</title>
+
+ <para>The original Samba software and related utilities
+ were created by Andrew Tridgell. Samba is now developed
+ by the Samba Team as an Open Source project similar
+ to the way the Linux kernel is developed.</para>
+
+ <para>The traffic_learner tool was developed by the Samba team at
+ Catalyst IT Ltd.</para>
+
+ <para>The traffic_learner manpage was written by Tim Beale.</para>
+</refsect1>
+
+</refentry>