xml_docs: update traffic script documentation

Signed-off-by: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>
Reviewed-by: Tim Beale <timbeale@samba.org>

Autobuild-User(master): Douglas Bagnall <dbagnall@samba.org>
Autobuild-Date(master): Wed Jan  9 03:53:58 CET 2019 on sn-devel-144

2 files changed, 64 insertions, 22 deletions

diff --git a/docs-xml/manpages/traffic_learner.7.xml b/docs-xml/manpages/traffic_learner.7.xml
index 6fd7975393d..b921035e4bd 100644
--- a/docs-xml/manpages/traffic_learner.7.xml
+++ b/docs-xml/manpages/traffic_learner.7.xml
@@ -118,8 +118,7 @@
 	</para>
 
 	<para>The model is stored in JSON format, and also contains
-	information about the conversation rate and DNS traffic
-	rate.</para>
+	information about the packet rate and DNS traffic rate.</para>
 
 
 <refsect2>
diff --git a/docs-xml/manpages/traffic_replay.7.xml b/docs-xml/manpages/traffic_replay.7.xml
index da8da5cf3c6..167bd9e0b08 100644
--- a/docs-xml/manpages/traffic_replay.7.xml
+++ b/docs-xml/manpages/traffic_replay.7.xml
@@ -21,6 +21,7 @@
 	<cmdsynopsis>
 		<command>traffic_replay</command>
 		<arg choice="opt">-F, --fixed-password &lt;test-password&gt;</arg>
+		<arg choice="opt">-T, --packets-per-second &lt;number&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>
@@ -41,6 +42,9 @@
 		<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="opt">--conversation-persistence &lt;0-1&gt;</arg>
+                <arg choice="opt">--latency-timeout &lt;seconds&gt;</arg>
+                <arg choice="opt">--stop-on-any-error</arg>
 		<arg choice="req">summary-file</arg>
 		<arg choice="req">dns-hostname</arg>
 	</cmdsynopsis>
@@ -53,6 +57,7 @@
 		<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="opt">--max-members &lt;group size&gt;</arg>
 		<arg choice="req">dns-hostname</arg>
 	</cmdsynopsis>
 
@@ -104,11 +109,10 @@
 	<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.
+	  File containing the network traffic to replay. This should be 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>
 
@@ -153,7 +157,7 @@
 	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>
+	<variablelist>
 		<varlistentry>
 		<term>-D|--duration &lt;seconds&gt;</term>
 		<listitem><para>
@@ -163,22 +167,34 @@
 		</varlistentry>
 
 		<varlistentry>
-		<term>-r|--replay-rate &lt;factor&gt;</term>
+		<term>-T|--packets-per-second &lt;number&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.
+                  Generate this many packets per second, regardless of
+                  the traffic rate of the sample on which the model
+                  was based. This cannot be used with <option>-S</option>.
 		</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.
+		Increases the number of conversations by this factor,
+		relative to the original traffic sample on which the
+		model was based. 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. It cannot be combined with
+                <option>-T</option>, which sets the traffic rate in a
+                different way.
+		</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 packets
+		sent, but it will squeeze them into fewer
+		conversations, which may reduce resource usage.
 		</para></listitem>
 		</varlistentry>
 
@@ -201,7 +217,28 @@
 		a traffic-summary file, or to use the --random-seed option.
 		</para></listitem>
 		</varlistentry>
-	</itemizedlist>
+		<varlistentry>
+		<term>--stop-on-any-error</term>
+		<listitem><para> Any client error causes the whole run to stop.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--conversation-persistence &lt;0-1&gt;</term>
+		<listitem><para> Conversation termination (as decided
+		by the model) is re-interpreted as a long pause with
+		this probability. </para></listitem>
+		</varlistentry>
+
+                <varlistentry>
+		<term>--latency-timeout &lt;seconds&gt;</term>
+		<listitem><para> Wait this long at the end of the run
+		for outstanding reply packets. The number of
+		conversations that have not finished at the end of the
+		timeout is a failure metric. </para></listitem>
+		</varlistentry>
+
+	</variablelist>
 	</listitem>
 	</varlistentry>
 
@@ -214,7 +251,7 @@
 	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>
@@ -241,7 +278,7 @@
 		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.
+		--group-memberships to do this.
 		</para></listitem>
 		</varlistentry>
 
@@ -268,7 +305,13 @@
 		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.
+		incompatible with the --average-groups-per-user option.
+		</para></listitem>
+		</varlistentry>
+		<varlistentry>
+		<term>--max-members &lt;group size&gt;</term>
+		<listitem><para> Limit the largest group to this size,
+		even if the other group options would have it otherwise.
 		</para></listitem>
 		</varlistentry>
 	</itemizedlist>
@@ -422,7 +465,7 @@
 	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 
+	automatically, for example from the /etc/smb.conf file, if one is
 	present). E.g.</para>
 
 	<para><command>traffic_replay traffic-summary.txt