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

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
+	information about the packet rate and DNS traffic rate.</para>
-	rate.</para>
 
 
 <refsect2>

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
+	  File containing the network traffic to replay. This should be a
-	a traffic-summary (generated by <command>traffic_summary.pl</command>)
+          traffic-model (generated by <command>traffic_learner</command>).
-	or a traffic-model (generated by <command>traffic_learner</command>).
+	  Based on this file, this tool will generate 'conversations' which
-	Based on this file, this tool will generate 'conversations' which
+	  represent Samba activity between a network host and the DC.
-	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
+                  Generate this many packets per second, regardless of
-		affect the number of conversations (which is based on the
+                  the traffic rate of the sample on which the model
-		traffic model), but the rate at which the packets are sent will
+                  was based. This cannot be used with <option>-S</option>.
-		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
+		Increases the number of conversations by this factor,
-		option won't affect the rate at which packets get sent (which
+		relative to the original traffic sample on which the
-		is still based on the traffic model), but it will mean more
+		model was based. This option won't affect the rate at
-		conversations get replayed.
+		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>
 
@@ -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>