scripts: Scripts to replay and generate samba traffic

Scripts to generate representative network traffic and replay this to a
samba instance.  For load testing, performance profiling and capacity
planning.

traffic_learner  process a file generated by traffic_summary and
                 generate a model that can be used by traffic_replay to
                 generate samba network traffic.

traffic_replay   Replay a summary file generated by traffic_summary, or
                 use a model created by traffic_learner to generate
                 network traffic.

Signed-off-by: Gary Lockyer <gary@catalyst.net.nz>
Signed-off-by: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>

Reviewed-by: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>
Reviewed-by: Garming Sam <garming@catalyst.net.nz>
Pair-programmed-with: Garming Sam <garming@catalyst.net.nz>
Pair-programmed-with: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>
Pair-Programmed-With: Andrew Bartlett <abartlet@samba.org>
Pair-Programmed-With: Tim Beale <timbeale@catalyst.net.nz>

3 files changed, 768 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 00000000000..4082ce0dae9
--- /dev/null
+++ b/docs-xml/manpages/traffic_learner.7.xml
@@ -0,0 +1,200 @@
+<?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">4.7</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 conversation 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 4 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>
diff --git a/docs-xml/manpages/traffic_replay.7.xml b/docs-xml/manpages/traffic_replay.7.xml
new file mode 100644
index 00000000000..7fdb7905bb0
--- /dev/null
+++ b/docs-xml/manpages/traffic_replay.7.xml
@@ -0,0 +1,566 @@
+<?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_replay.7">
+
+<refmeta>
+	<refentrytitle>traffic_replay</refentrytitle>
+	<manvolnum>7</manvolnum>
+	<refmiscinfo class="source">Samba</refmiscinfo>
+	<refmiscinfo class="manual">User Commands</refmiscinfo>
+	<refmiscinfo class="version">4.7</refmiscinfo>
+</refmeta>
+
+
+<refnamediv>
+	<refname>traffic_replay</refname>
+	<refpurpose>Samba traffic generation tool.
+	</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+	<cmdsynopsis>
+		<command>traffic_replay</command>
+		<arg choice="opt">-F, --fixed-password &lt;test-password&gt;</arg>
+		<arg choice="opt">-S, --scale-traffic &lt;scale by factor&gt;</arg>
+		<arg choice="opt">-r, --replay-rate &lt;scale by factor&gt;</arg>
+		<arg choice="opt">-D, --duration &lt;seconds&gt;</arg>
+		<arg choice="opt">--traffic-summary &lt;output file&gt;</arg>
+		<arg choice="opt">-I, --instance-id &lt;id&gt;</arg>
+		<arg choice="opt">-K, --prefer-kerberos</arg>
+		<arg choice="opt">-B, --badpassword-frequency &lt;frequency&gt;</arg>
+		<arg choice="opt">--dns-rate &lt;rate&gt;</arg>
+		<arg choice="opt">-t, --timing-data &lt;file&gt;</arg>
+		<arg choice="opt">-U, --username user</arg>
+		<arg choice="opt">--password &lt;password&gt;</arg>
+		<arg choice="opt">-W --workgroup &lt;workgroup&gt;</arg>
+		<arg choice="opt">--realm &lt;realm&gt;</arg>
+		<arg choice="opt">-s, --config-file &lt;file&gt;</arg>
+		<arg choice="opt">-k, --kerberos &lt;kerberos&gt;</arg>
+		<arg choice="opt">--ipaddress &lt;address&gt;</arg>
+		<arg choice="opt">-P, --machine-pass</arg>
+		<arg choice="opt">--option &lt;option&gt;</arg>
+		<arg choice="opt">-d, --debuglevel &lt;debug level&gt;</arg>
+		<arg choice="req">summary-file</arg>
+		<arg choice="req">dns-hostname</arg>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+		<command>traffic_replay</command>
+		<arg choice="opt">-G, --generate-users-only</arg>
+		<arg choice="opt">-F, --fixed-password &lt;test-password&gt;</arg>
+		<arg choice="opt">-n, --number-of-users &lt;total users&gt;</arg>
+		<arg choice="opt">--number-of-groups &lt;total groups&gt;</arg>
+		<arg choice="opt">--average-groups-per-user &lt;average number&gt;</arg>
+		<arg choice="opt">--group-memberships &lt;total memberships&gt;</arg>
+		<arg choice="req">dns-hostname</arg>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+		<command>traffic_replay</command>
+		<arg choice="req">-c|--clean-up</arg>
+		<arg choice="req">dns-hostname</arg>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+		<command>traffic_replay</command>
+		<arg choice="opt">-h, --help</arg>
+		<arg choice="opt">-V, --version</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 generates traffic in order to measure the performance
+	of a Samba DC, and to test how well Samba will scale as a network
+	increases in size. It can simulate multiple different hosts making
+	multiple different types of requests to a DC.</para>
+
+	<para>This tool is intended to run against a dedicated test DC (rather
+	than a live DC that is handling real network traffic).</para>
+
+	<para>Note that a side-effect of running this tool is that user
+	accounts will be created on the DC, in order to test various Samba
+	operations. As creating accounts can be very time-consuming, these
+	users will remain on the DC by default. To remove these accounts, use
+	the --clean-up option.
+	</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 the network traffic to replay. This should either be
+	a traffic-summary (generated by <command>traffic_summary.pl</command>)
+	or a traffic-model (generated by <command>traffic_learner</command>).
+	Based on this file, this tool will generate 'conversations' which
+	represent Samba activity between a network host and the DC.
+	</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>dns-hostname</term>
+	<listitem><para>
+	The full DNS hostname of the DC that's being tested. The Samba activity
+	in the summary-file will be replicated and directed at this DC. It's
+	recommended that you use a dedicated DC for testing and don't try to run
+	this tool against a DC that's processing live network traffic.
+	</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>-F|--fixed-password &lt;test-password&gt;</term>
+	<listitem><para>
+	Test users are created when this tool is run, so that actual Samba
+	activity, such as authorizing users, can be mimicked. This option
+	specifies the password that will be used for any test users that are
+	created.</para>
+
+	<para>Note that any users created by this tool will remain on the DC
+	until you run the --clean-up option. Therefore, the fixed-password
+	option needs to be the same each time the tool is run, otherwise the
+	test users won't authenticate correctly.
+	</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>Traffic Model Options</term>
+	<listitem><para>
+	When the summary-file is a traffic-model (produced by
+	<command>traffic_learner</command>), use these options to alter the
+	traffic that gets generated.</para>
+	<itemizedlist>
+		<varlistentry>
+		<term>-D|--duration &lt;seconds&gt;</term>
+		<listitem><para>
+		Specifies the approximate duration in seconds to generate
+		traffic for. The default is 60 seconds.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>-r|--replay-rate &lt;factor&gt;</term>
+		<listitem><para>
+		Replays the traffic faster by this factor. This option won't
+		affect the number of conversations (which is based on the
+		traffic model), but the rate at which the packets are sent will
+		be increased.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>-S|--scale-traffic &lt;factor&gt;</term>
+		<listitem><para>
+		Increases the number of conversations by this factor. This
+		option won't affect the rate at which packets get sent (which
+		is still based on the traffic model), but it will mean more
+		conversations get replayed.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--traffic-summary &lt;output-file&gt;</term>
+		<listitem><para>
+		Instead of replaying a traffic-model, this option generates a
+		traffic-summary file based on what traffic would be sent. Using
+		a traffic-model allows you to scale the packet rate and number
+		of packets sent. However, using a traffic-model introduces
+		some randomness into the traffic generation. So running the
+		same traffic_replay command multiple times using a model file
+		may result in some differences in the actual traffic sent.
+		However, running the same traffic_replay command multiple times
+		with a traffic-summary file will always result in the same
+		traffic being sent. </para>
+		<para>
+		For taking performance measurements over several test runs,
+		it's recommended to use this option and replay the traffic from
+		a traffic-summary file.
+		</para></listitem>
+		</varlistentry>
+	</itemizedlist>
+	</listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>--generate-users-only</term>
+	<listitem><para>Add extra user/groups on the DC to increase the DB
+	size. By default, this tool automatically creates test users that map
+	to the traffic conversations being generated. This option allows extra
+	users to be created on top of this. Note that these extra users may
+	not actually used for traffic generation - the traffic generation is
+	still based on the number of conversations from the model/summary file.
+	</para>
+	
+	<para>
+	Generating a large number of users can take a long time, so it this
+	option allows this to be done only once.</para>
+
+	<para>Note that the users created will remain on the DC until the
+	tool is run with the --clean-up option. This means that it is best to
+	only assign group memberships once, i.e. run --clean-up before
+	assigning a different allocation of group memberships.</para>
+	<itemizedlist>
+
+		<varlistentry>
+		<term>-n|--number-of-users &lt;total-users&gt;</term>
+		<listitem><para>
+		Specifies the total number of test users to create (excluding
+		any machine accounts required for the traffic). Note that these
+		extra users simply populate the DC's DB - the actual user
+		traffic generated is still based on the summary-file.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--number-of-groups &lt;total-groups&gt;</term>
+		<listitem><para>
+		Creates the specified number of groups, for assigning the test
+		users to. Note that users are not automatically assigned to
+		groups - use either --average-groups-per-user or
+		--group-membership to do this.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--average-groups-per-user &lt;average-groups&gt;</term>
+		<listitem><para>
+		Randomly assigns the test users to the test groups created.
+		The group memberships are distributed so that the overall
+		average groups that a user is member of matches this number.
+		Some users will belong to more groups and some users will
+		belong to fewer groups. This option is incompatible with
+		the --group-membership option.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--group-memberships &lt;total-memberships&gt;</term>
+		<listitem><para>
+		Randomly assigns the test users to the test groups created.
+		The group memberships are distributed so that the total
+		groups that a user is member of, across all users, matches
+		this number. For example, with 100 users and 10 groups,
+		--group-memberships=300 would assign a user to 3 groups
+		on average. Some users will belong to more groups and some
+		users will belong to fewer groups, but the total of all
+		member linked attributes would be 300. This option is
+		incompatible with the --group-membership option.
+		</para></listitem>
+		</varlistentry>
+	</itemizedlist>
+	</listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>--clean-up</term>
+	<listitem><para>
+	Cleans up any users and groups that were created by previously running
+	this tool. It is recommended you always clean up after running the tool.
+	</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>-I|--instance-id &lt;id&gt;</term>
+	<listitem><para>
+	Use this option to run multiple instances of the tool on the same DC at
+	the same time. This adds a prefix to the test users generated to keep
+	them separate on the DC.
+	</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>-K|--prefer-kerberos</term>
+	<listitem><para>
+	Use Kerberos to authenticate the test users.
+	</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>-B|--badpassword-frequency &lt;frequency&gt;</term>
+	<listitem><para>
+	Use this option to simulate users trying to authenticate with an
+	incorrect password.
+	</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>--dns-rate &lt;rate&gt;</term>
+	<listitem><para>
+	Increase the rate at which DNS packets get sent.
+	</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>-t|--timing-data &lt;file&gt;</term>
+	<listitem><para>
+	This writes extra timing data to the file specified. This is mostly
+	used for reporting options, such as generating graphs.
+	</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>Samba Common Options</term>
+	<listitem>
+	<itemizedlist>
+		&stdarg.client.debug;
+		&stdarg.configfile;
+		&stdarg.option;
+		<varlistentry>
+		<term>--realm=REALM</term>
+		<listitem><para>
+		Set the realm name
+		</para></listitem>
+		</varlistentry>
+		&stdarg.version;
+	</itemizedlist>
+	</listitem>
+	</varlistentry>
+
+	<varlistentry>
+	<term>Credential Options</term>
+	<listitem>
+	<itemizedlist>
+		<varlistentry>
+		<term>--simple-bind-dn=DN</term>
+		<listitem><para>
+		DN to use for a simple bind
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--password=PASSWORD</term>
+		<listitem><para>
+		Password
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>-U USERNAME|--username=USERNAME</term>
+		<listitem><para>
+		Username
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>-W WORKGROUP|--workgroup=WORKGROUP</term>
+		<listitem><para>
+		Workgroup
+		</para></listitem>
+		</varlistentry>
+
+		&stdarg.kerberos;
+
+		<varlistentry>
+		<term>--ipaddress=IPADDRESS</term>
+		<listitem><para>
+		IP address of the server
+		</para></listitem>
+		</varlistentry>
+
+		&stdarg.machinepass;
+	</itemizedlist>
+	</listitem>
+	</varlistentry>
+
+	</variablelist>
+</refsect1>
+
+<refsect1>
+<title>OPERATIONS</title>
+
+<refsect2>
+	<title>Generating a traffic-summary file</title>
+	<para>To use this tool, you need either a traffic-summary file or a
+	traffic-model file. To generate either of these files, you will need a
+	packet capture of actual Samba activity on your network.</para>
+
+	<para>Use Wireshark to take a packet capture on your network of the
+	traffic you want to generate. For example, if you want to simulate lots
+	of users logging on, then take a capture at 8:30am when users are
+	logging in.</para>
+
+	<para>Next, you need to convert your packet capture into a traffic
+	summary file, using <command>traffic_summary.pl</command>. Basically
+	this removes any sensitive information from the capture and summarizes
+	what type of packet was sent and when.</para>
+
+	<para>Refer to the <command>traffic_summary.pl --help</command> help for more
+	details, but the basic command will look something like:</para>
+
+	<para><command>tshark -r capture.pcapng -T pdml |
+	traffic_summary.pl &gt; traffic-summary.txt</command></para>
+</refsect2>
+
+<refsect2>
+	<title>Replaying a traffic-summary file</title>
+	<para>Once you have a traffic-summary file, you can use it to generate
+	traffic. The traffic_replay tool gets passed the traffic-summary file,
+	along with the full DNS hostname of the DC being tested. You also need
+	to provide some user credentials, and possibly the Samba realm and
+	workgroup (although the realm and workgroup may be determined
+	automatically, for example from the /etc/smb.conf file, if one is 
+	present). E.g.</para>
+
+	<para><command>traffic_replay traffic-summary.txt
+	my-dc.samdom.example.com -UAdmin%password -W samdom
+	--realm=samdom.example.com --fixed-password=blahblah123!</command>
+	</para>
+
+	<para>This simply regenerates Samba activity seen in the traffic
+	summary. The traffic is grouped into 'conversations' between a host and
+	the DC.	A user and machine account is created on the DC for each
+	conversation, in order to allow logon and other operations to succeed.
+	The script generates the same types of packets as those seen in the
+	summary.</para>
+
+	<para>Creating users can be quite a time-consuming process, especially
+	if a lot of conversations are being generated. To save time, the test
+	users remain on the DC by default. You will need to run the --clean-up
+	option to remove them, once you have finished generating traffic.
+	Because the same test users are used across multiple runs of the tool,
+	a consistent password for these users needs to be used - this is
+	specified by the --fixed-password option.
+	</para>
+
+	<para>The benefit of this tool over simply using tcprelay is that the
+	traffic generated is independent of any specific network. No setup is
+	needed beforehand on the test DC. The traffic no longer contains
+	sensitive details, so the traffic summary could be potentially shared
+	with other Samba developers.</para>
+
+	<para>However, replaying a traffic-summary directly is somewhat limited
+	in what you can actually do. A more flexible approach is to generate
+	the traffic using a model file.</para>
+</refsect2>
+
+<refsect2>
+	<title>Generating a traffic-model file</title>
+	<para>To create a traffic-model file, simply pass the traffic-summary
+	file to the <command>traffic_learner</command> script. E.g.</para>
+
+	<para><command>traffic_learner traffic-summary.txt
+	-o traffic-model.txt</command></para>
+
+	<para>This generates a model of the Samba activity in your network.
+	This model-file can now be used to generate traffic.</para>
+</refsect2>
+
+<refsect2>
+	<title>Replaying the traffic-model file</title>
+	<para>Packet generation using a traffic-model file uses the same
+	command as a traffic-summary file, e.g.</para>
+
+	<para><command>traffic_replay traffic-model.txt
+	my-dc.samdom.example.com -UAdmin%password</command>
+	</para>
+
+	<para>By default, this will generate 60 seconds worth of traffic based
+	on the model. You can specify longer using the --duration parameter.
+	</para>
+
+	<para>The traffic generated is an approximation of what was seen in
+	the network capture. The traffic generation involves some randomness,
+	so running the same command multiple times may result in slightly
+	different traffic being generated.</para>
+
+	<para>As well as changing how long the model runs for, you can also
+	change how many conversations get generated and how fast the traffic
+	gets replayed. To roughly double the number of conversations that get
+	replayed, use --scale-traffic=2 or to approximately halve the number
+	use --scale-traffic=0.5. To approximately double how quickly the
+	conversations get replayed, use --replay-rate=2, or to halve this use
+	--replay-rate=0.5</para>
+
+	<para>For example, to generate approximately 10 times the amount of
+	traffic seen over a two-minute period (based on the network capture),
+	use:</para>
+
+	<para><command>traffic_replay traffic-model.txt
+	my-dc.samdom.example.com -UAdmin%password --fixed-password=blahblah123!
+	--scale-traffic=10 --duration=120</command></para>
+</refsect2>
+
+<refsect2>
+	<title>Scaling the number of users</title>
+	<para>The performance of a Samba DC running a small subset of test
+	users will be different to a fully-populated Samba DC running in a
+	network. As the number of users increases, the size of the DB
+	increases, and a very large DB will perform worse than a smaller DB.
+	</para>
+
+	<para>To increase the size of the Samba DB, this tool can also create
+	extra users and groups. These extra users are basically 'filler' for
+	the DB. They won't actually be used to generate traffic, but they may
+	slow down authentication of the test users.</para>
+
+	<para>For example, to populate the DB with an extra 5000 users (note
+	this will take a while), use the command:</para>
+
+	<para><command>traffic_replay my-dc.samdom.example.com
+	-UAdmin%password --generate-users-only --fixed-password=blahblah123!
+	--number-of-users=5000</command></para>
+
+	<para>You can also create groups and assign users to groups. The users
+	can be randomly assigned to groups - this includes any extra users
+	created as well as the users that map to conversations. Use either
+	--average-groups-per-user or --group-memberships to specify how many
+	group memberships should be assigned to the test users.</para>
+
+	<para>For example, to assign the users in the replayed conversations
+	into 10 groups on average, use a command like:</para>
+
+	<para><command>traffic_replay traffic-model.txt my-dc.samdom.example.com
+	-UAdmin%password --fixed-password=blahblah123!
+	--generate-users-only --number-of-groups=25 --average-groups-per-user=10
+	</command></para>
+
+	<para>The users created by the test will have names like STGU-0-xyz.
+	The groups generated have names like STGG-0-xyz.</para>
+</refsect2>
+</refsect1>
+
+
+<refsect1>
+	<title>VERSION</title>
+
+	<para>This man page is complete for version 4 of the Samba
+	suite.</para>
+</refsect1>
+
+<refsect1>
+	<title>SEE ALSO</title>
+	<para>
+	<citerefentry>
+	<refentrytitle>traffic_learner</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_replay tool was developed by the Samba team at
+	Catalyst IT Ltd.</para>
+
+	<para>The traffic_replay manpage was written by Tim Beale.</para>
+</refsect1>
+
+</refentry>
diff --git a/docs-xml/wscript_build b/docs-xml/wscript_build
index cbc09a56559..e329ad40295 100644
--- a/docs-xml/wscript_build
+++ b/docs-xml/wscript_build
@@ -46,6 +46,8 @@ manpages='''
          manpages/smbtar.1
          manpages/smbtree.1
          manpages/testparm.1
+         manpages/traffic_replay.7
+         manpages/traffic_learner.7
          manpages/vfs_acl_tdb.8
          manpages/vfs_acl_xattr.8
          manpages/vfs_aio_fork.8