samba-tool group: Add --special parameter to add predefined special group
[Samba.git] / docs-xml / manpages / traffic_replay.7.xml
blobf0d6ac11bc2a6c1f821fba67b9b6630ee112b5de
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_replay.7">
5 <refmeta>
6         <refentrytitle>traffic_replay</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>
14 <refnamediv>
15         <refname>traffic_replay</refname>
16         <refpurpose>Samba traffic generation tool.
17         </refpurpose>
18 </refnamediv>
20 <refsynopsisdiv>
21         <cmdsynopsis>
22                 <command>traffic_replay</command>
23                 <arg choice="opt">-F, --fixed-password &lt;test-password&gt;</arg>
24                 <arg choice="opt">-T, --packets-per-second &lt;number&gt;</arg>
25                 <arg choice="opt">-S, --scale-traffic &lt;scale by factor&gt;</arg>
26                 <arg choice="opt">-r, --replay-rate &lt;scale by factor&gt;</arg>
27                 <arg choice="opt">-D, --duration &lt;seconds&gt;</arg>
28                 <arg choice="opt">--traffic-summary &lt;output file&gt;</arg>
29                 <arg choice="opt">-I, --instance-id &lt;id&gt;</arg>
30                 <arg choice="opt">-K, --prefer-kerberos</arg>
31                 <arg choice="opt">-B, --badpassword-frequency &lt;frequency&gt;</arg>
32                 <arg choice="opt">--dns-rate &lt;rate&gt;</arg>
33                 <arg choice="opt">-t, --timing-data &lt;file&gt;</arg>
34                 <arg choice="opt">--random-seed &lt;seed&gt;</arg>
35                 <arg choice="opt">-U, --username user</arg>
36                 <arg choice="opt">--password &lt;password&gt;</arg>
37                 <arg choice="opt">-W --workgroup &lt;workgroup&gt;</arg>
38                 <arg choice="opt">--realm &lt;realm&gt;</arg>
39                 <arg choice="opt">-s, --config-file &lt;file&gt;</arg>
40                 <arg choice="opt">-k, --kerberos &lt;kerberos&gt;</arg>
41                 <arg choice="opt">--ipaddress &lt;address&gt;</arg>
42                 <arg choice="opt">-P, --machine-pass</arg>
43                 <arg choice="opt">--option &lt;option&gt;</arg>
44                 <arg choice="opt">-d, --debuglevel &lt;debug level&gt;</arg>
45                 <arg choice="opt">--conversation-persistence &lt;0-1&gt;</arg>
46                 <arg choice="opt">--latency-timeout &lt;seconds&gt;</arg>
47                 <arg choice="opt">--stop-on-any-error</arg>
48                 <arg choice="req">summary-file</arg>
49                 <arg choice="req">dns-hostname</arg>
50         </cmdsynopsis>
52         <cmdsynopsis>
53                 <command>traffic_replay</command>
54                 <arg choice="opt">-G, --generate-users-only</arg>
55                 <arg choice="opt">-F, --fixed-password &lt;test-password&gt;</arg>
56                 <arg choice="opt">-n, --number-of-users &lt;total users&gt;</arg>
57                 <arg choice="opt">--number-of-groups &lt;total groups&gt;</arg>
58                 <arg choice="opt">--average-groups-per-user &lt;average number&gt;</arg>
59                 <arg choice="opt">--group-memberships &lt;total memberships&gt;</arg>
60                 <arg choice="opt">--max-members &lt;group size&gt;</arg>
61                 <arg choice="req">dns-hostname</arg>
62         </cmdsynopsis>
64         <cmdsynopsis>
65                 <command>traffic_replay</command>
66                 <arg choice="req">-c|--clean-up</arg>
67                 <arg choice="req">dns-hostname</arg>
68         </cmdsynopsis>
70         <cmdsynopsis>
71                 <command>traffic_replay</command>
72                 <arg choice="opt">-h, --help</arg>
73                 <arg choice="opt">-V, --version</arg>
74         </cmdsynopsis>
75 </refsynopsisdiv>
77 <refsect1>
78         <title>DESCRIPTION</title>
79         <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
80         <manvolnum>7</manvolnum></citerefentry> suite.</para>
81         <para>This tool generates traffic in order to measure the performance
82         of a Samba DC, and to test how well Samba will scale as a network
83         increases in size. It can simulate multiple different hosts making
84         multiple different types of requests to a DC.</para>
86         <para>This tool is intended to run against a dedicated test DC (rather
87         than a live DC that is handling real network traffic).</para>
89         <para>Note that a side-effect of running this tool is that user
90         accounts will be created on the DC, in order to test various Samba
91         operations. As creating accounts can be very time-consuming, these
92         users will remain on the DC by default. To remove these accounts, use
93         the --clean-up option.
94         </para>
95 </refsect1>
97 <refsect1>
98         <title>OPTIONS</title>
100         <variablelist>
102         <varlistentry>
103         <term>-h|--help</term>
104         <listitem><para>
105         Print a summary of command line options.
106         </para></listitem>
107         </varlistentry>
109         <varlistentry>
110         <term>summary-file</term>
111         <listitem><para>
112           File containing the network traffic to replay. This should be a
113           traffic-model (generated by <command>traffic_learner</command>).
114           Based on this file, this tool will generate 'conversations' which
115           represent Samba activity between a network host and the DC.
116         </para></listitem>
117         </varlistentry>
119         <varlistentry>
120         <term>dns-hostname</term>
121         <listitem><para>
122         The full DNS hostname of the DC that's being tested. The Samba activity
123         in the summary-file will be replicated and directed at this DC. It's
124         recommended that you use a dedicated DC for testing and don't try to run
125         this tool against a DC that's processing live network traffic.
126         </para></listitem>
127         </varlistentry>
129         <varlistentry>
130         <term>-F|--fixed-password &lt;test-password&gt;</term>
131         <listitem><para>
132         Test users are created when this tool is run, so that actual Samba
133         activity, such as authorizing users, can be mimicked. This option
134         specifies the password that will be used for any test users that are
135         created.</para>
137         <para>Note that any users created by this tool will remain on the DC
138         until you run the --clean-up option. Therefore, the fixed-password
139         option needs to be the same each time the tool is run, otherwise the
140         test users won't authenticate correctly.
141         </para></listitem>
142         </varlistentry>
144         <varlistentry>
145         <term>random-seed</term>
146         <listitem><para>
147         A number to seed the random number generator with. When traffic is
148         generated from a model-file, use this option to keep the traffic
149         consistent across multiple test runs. This allows you to compare the
150         performance of Samba between different releases.
151         </para></listitem>
152         </varlistentry>
154         <varlistentry>
155         <term>Traffic Model Options</term>
156         <listitem><para>
157         When the summary-file is a traffic-model (produced by
158         <command>traffic_learner</command>), use these options to alter the
159         traffic that gets generated.</para>
160         <variablelist>
161                 <varlistentry>
162                 <term>-D|--duration &lt;seconds&gt;</term>
163                 <listitem><para>
164                 Specifies the approximate duration in seconds to generate
165                 traffic for. The default is 60 seconds.
166                 </para></listitem>
167                 </varlistentry>
169                 <varlistentry>
170                 <term>-T|--packets-per-second &lt;number&gt;</term>
171                 <listitem><para>
172                   Generate this many packets per second, regardless of
173                   the traffic rate of the sample on which the model
174                   was based. This cannot be used with <option>-S</option>.
175                 </para></listitem>
176                 </varlistentry>
178                 <varlistentry>
179                 <term>-S|--scale-traffic &lt;factor&gt;</term>
180                 <listitem><para>
181                 Increases the number of conversations by this factor,
182                 relative to the original traffic sample on which the
183                 model was based. This option won't affect the rate at
184                 which packets get sent (which is still based on the
185                 traffic model), but it will mean more conversations
186                 get replayed. It cannot be combined with
187                 <option>-T</option>, which sets the traffic rate in a
188                 different way.
189                 </para></listitem>
190                 </varlistentry>
192                 <varlistentry>
193                 <term>-r|--replay-rate &lt;factor&gt;</term>
194                 <listitem><para> Replays the traffic faster by this
195                 factor. This option won't affect the number of packets
196                 sent, but it will squeeze them into fewer
197                 conversations, which may reduce resource usage.
198                 </para></listitem>
199                 </varlistentry>
201                 <varlistentry>
202                 <term>--traffic-summary &lt;output-file&gt;</term>
203                 <listitem><para>
204                 Instead of replaying a traffic-model, this option generates a
205                 traffic-summary file based on what traffic would be sent. Using
206                 a traffic-model allows you to scale the packet rate and number
207                 of packets sent. However, using a traffic-model introduces
208                 some randomness into the traffic generation. So running the
209                 same traffic_replay command multiple times using a model file
210                 may result in some differences in the actual traffic sent.
211                 However, running the same traffic_replay command multiple times
212                 with a traffic-summary file will always result in the same
213                 traffic being sent. </para>
214                 <para>
215                 For taking performance measurements over several test runs,
216                 it's recommended to use this option and replay the traffic from
217                 a traffic-summary file, or to use the --random-seed option.
218                 </para></listitem>
219                 </varlistentry>
220                 <varlistentry>
221                 <term>--stop-on-any-error</term>
222                 <listitem><para> Any client error causes the whole run to stop.
223                 </para></listitem>
224                 </varlistentry>
226                 <varlistentry>
227                 <term>--conversation-persistence &lt;0-1&gt;</term>
228                 <listitem><para> Conversation termination (as decided
229                 by the model) is re-interpreted as a long pause with
230                 this probability. </para></listitem>
231                 </varlistentry>
233                 <varlistentry>
234                 <term>--latency-timeout &lt;seconds&gt;</term>
235                 <listitem><para> Wait this long at the end of the run
236                 for outstanding reply packets. The number of
237                 conversations that have not finished at the end of the
238                 timeout is a failure metric. </para></listitem>
239                 </varlistentry>
241         </variablelist>
242         </listitem>
243         </varlistentry>
245         <varlistentry>
246         <term>--generate-users-only</term>
247         <listitem><para>Add extra user/groups on the DC to increase the DB
248         size. By default, this tool automatically creates test users that map
249         to the traffic conversations being generated. This option allows extra
250         users to be created on top of this. Note that these extra users may
251         not actually used for traffic generation - the traffic generation is
252         still based on the number of conversations from the model/summary file.
253         </para>
255         <para>
256         Generating a large number of users can take a long time, so it this
257         option allows this to be done only once.</para>
259         <para>Note that the users created will remain on the DC until the
260         tool is run with the --clean-up option. This means that it is best to
261         only assign group memberships once, i.e. run --clean-up before
262         assigning a different allocation of group memberships.</para>
263         <itemizedlist>
265                 <varlistentry>
266                 <term>-n|--number-of-users &lt;total-users&gt;</term>
267                 <listitem><para>
268                 Specifies the total number of test users to create (excluding
269                 any machine accounts required for the traffic). Note that these
270                 extra users simply populate the DC's DB - the actual user
271                 traffic generated is still based on the summary-file.
272                 </para></listitem>
273                 </varlistentry>
275                 <varlistentry>
276                 <term>--number-of-groups &lt;total-groups&gt;</term>
277                 <listitem><para>
278                 Creates the specified number of groups, for assigning the test
279                 users to. Note that users are not automatically assigned to
280                 groups - use either --average-groups-per-user or
281                 --group-memberships to do this.
282                 </para></listitem>
283                 </varlistentry>
285                 <varlistentry>
286                 <term>--average-groups-per-user &lt;average-groups&gt;</term>
287                 <listitem><para>
288                 Randomly assigns the test users to the test groups created.
289                 The group memberships are distributed so that the overall
290                 average groups that a user is member of matches this number.
291                 Some users will belong to more groups and some users will
292                 belong to fewer groups. This option is incompatible with
293                 the --group-membership option.
294                 </para></listitem>
295                 </varlistentry>
297                 <varlistentry>
298                 <term>--group-memberships &lt;total-memberships&gt;</term>
299                 <listitem><para>
300                 Randomly assigns the test users to the test groups created.
301                 The group memberships are distributed so that the total
302                 groups that a user is member of, across all users, matches
303                 this number. For example, with 100 users and 10 groups,
304                 --group-memberships=300 would assign a user to 3 groups
305                 on average. Some users will belong to more groups and some
306                 users will belong to fewer groups, but the total of all
307                 member linked attributes would be 300. This option is
308                 incompatible with the --average-groups-per-user option.
309                 </para></listitem>
310                 </varlistentry>
311                 <varlistentry>
312                 <term>--max-members &lt;group size&gt;</term>
313                 <listitem><para> Limit the largest group to this size,
314                 even if the other group options would have it otherwise.
315                 </para></listitem>
316                 </varlistentry>
317         </itemizedlist>
318         </listitem>
319         </varlistentry>
321         <varlistentry>
322         <term>--clean-up</term>
323         <listitem><para>
324         Cleans up any users and groups that were created by previously running
325         this tool. It is recommended you always clean up after running the tool.
326         </para></listitem>
327         </varlistentry>
329         <varlistentry>
330         <term>-I|--instance-id &lt;id&gt;</term>
331         <listitem><para>
332         Use this option to run multiple instances of the tool on the same DC at
333         the same time. This adds a prefix to the test users generated to keep
334         them separate on the DC.
335         </para></listitem>
336         </varlistentry>
338         <varlistentry>
339         <term>-K|--prefer-kerberos</term>
340         <listitem><para>
341         Use Kerberos to authenticate the test users.
342         </para></listitem>
343         </varlistentry>
345         <varlistentry>
346         <term>-B|--badpassword-frequency &lt;frequency&gt;</term>
347         <listitem><para>
348         Use this option to simulate users trying to authenticate with an
349         incorrect password.
350         </para></listitem>
351         </varlistentry>
353         <varlistentry>
354         <term>--dns-rate &lt;rate&gt;</term>
355         <listitem><para>
356         Increase the rate at which DNS packets get sent.
357         </para></listitem>
358         </varlistentry>
360         <varlistentry>
361         <term>-t|--timing-data &lt;file&gt;</term>
362         <listitem><para>
363         This writes extra timing data to the file specified. This is mostly
364         used for reporting options, such as generating graphs.
365         </para></listitem>
366         </varlistentry>
368         <varlistentry>
369         <term>Samba Common Options</term>
370         <listitem>
371         <itemizedlist>
372                 &cmdline.common.debug.client;
373                 &cmdline.common.config.client;
374                 &cmdline.common.option;
375                 <varlistentry>
376                 <term>--realm=REALM</term>
377                 <listitem><para>
378                 Set the realm name
379                 </para></listitem>
380                 </varlistentry>
381                 &cmdline.version;
382         </itemizedlist>
383         </listitem>
384         </varlistentry>
386         <varlistentry>
387         <term>Credential Options</term>
388         <listitem>
389         <itemizedlist>
390                 <varlistentry>
391                 <term>--simple-bind-dn=DN</term>
392                 <listitem><para>
393                 DN to use for a simple bind
394                 </para></listitem>
395                 </varlistentry>
397                 <varlistentry>
398                 <term>--password=PASSWORD</term>
399                 <listitem><para>
400                 Password
401                 </para></listitem>
402                 </varlistentry>
404                 <varlistentry>
405                 <term>-U USERNAME|--username=USERNAME</term>
406                 <listitem><para>
407                 Username
408                 </para></listitem>
409                 </varlistentry>
411                 <varlistentry>
412                 <term>-W WORKGROUP|--workgroup=WORKGROUP</term>
413                 <listitem><para>
414                 Workgroup
415                 </para></listitem>
416                 </varlistentry>
418                 &cmdline.common.credentials.usekerberos;
420                 <varlistentry>
421                 <term>--ipaddress=IPADDRESS</term>
422                 <listitem><para>
423                 IP address of the server
424                 </para></listitem>
425                 </varlistentry>
427                 &cmdline.common.credentials.machinepass;
428         </itemizedlist>
429         </listitem>
430         </varlistentry>
432         </variablelist>
433 </refsect1>
435 <refsect1>
436 <title>OPERATIONS</title>
438 <refsect2>
439         <title>Generating a traffic-summary file</title>
440         <para>To use this tool, you need either a traffic-summary file or a
441         traffic-model file. To generate either of these files, you will need a
442         packet capture of actual Samba activity on your network.</para>
444         <para>Use Wireshark to take a packet capture on your network of the
445         traffic you want to generate. For example, if you want to simulate lots
446         of users logging on, then take a capture at 8:30am when users are
447         logging in.</para>
449         <para>Next, you need to convert your packet capture into a traffic
450         summary file, using <command>traffic_summary.pl</command>. Basically
451         this removes any sensitive information from the capture and summarizes
452         what type of packet was sent and when.</para>
454         <para>Refer to the <command>traffic_summary.pl --help</command> help for more
455         details, but the basic command will look something like:</para>
457         <para><command>tshark -r capture.pcapng -T pdml |
458         traffic_summary.pl &gt; traffic-summary.txt</command></para>
459 </refsect2>
461 <refsect2>
462         <title>Replaying a traffic-summary file</title>
463         <para>Once you have a traffic-summary file, you can use it to generate
464         traffic. The traffic_replay tool gets passed the traffic-summary file,
465         along with the full DNS hostname of the DC being tested. You also need
466         to provide some user credentials, and possibly the Samba realm and
467         workgroup (although the realm and workgroup may be determined
468         automatically, for example from the /etc/smb.conf file, if one is
469         present). E.g.</para>
471         <para><command>traffic_replay traffic-summary.txt
472         my-dc.samdom.example.com -UAdmin%password -W samdom
473         --realm=samdom.example.com --fixed-password=blahblah123!</command>
474         </para>
476         <para>This simply regenerates Samba activity seen in the traffic
477         summary. The traffic is grouped into 'conversations' between a host and
478         the DC. A user and machine account is created on the DC for each
479         conversation, in order to allow logon and other operations to succeed.
480         The script generates the same types of packets as those seen in the
481         summary.</para>
483         <para>Creating users can be quite a time-consuming process, especially
484         if a lot of conversations are being generated. To save time, the test
485         users remain on the DC by default. You will need to run the --clean-up
486         option to remove them, once you have finished generating traffic.
487         Because the same test users are used across multiple runs of the tool,
488         a consistent password for these users needs to be used - this is
489         specified by the --fixed-password option.
490         </para>
492         <para>The benefit of this tool over simply using tcprelay is that the
493         traffic generated is independent of any specific network. No setup is
494         needed beforehand on the test DC. The traffic no longer contains
495         sensitive details, so the traffic summary could be potentially shared
496         with other Samba developers.</para>
498         <para>However, replaying a traffic-summary directly is somewhat limited
499         in what you can actually do. A more flexible approach is to generate
500         the traffic using a model file.</para>
501 </refsect2>
503 <refsect2>
504         <title>Generating a traffic-model file</title>
505         <para>To create a traffic-model file, simply pass the traffic-summary
506         file to the <command>traffic_learner</command> script. E.g.</para>
508         <para><command>traffic_learner traffic-summary.txt
509         -o traffic-model.txt</command></para>
511         <para>This generates a model of the Samba activity in your network.
512         This model-file can now be used to generate traffic.</para>
513 </refsect2>
515 <refsect2>
516         <title>Replaying the traffic-model file</title>
517         <para>Packet generation using a traffic-model file uses the same
518         command as a traffic-summary file, e.g.</para>
520         <para><command>traffic_replay traffic-model.txt
521         my-dc.samdom.example.com -UAdmin%password</command>
522         </para>
524         <para>By default, this will generate 60 seconds worth of traffic based
525         on the model. You can specify longer using the --duration parameter.
526         </para>
528         <para>The traffic generated is an approximation of what was seen in
529         the network capture. The traffic generation involves some randomness,
530         so running the same command multiple times may result in slightly
531         different traffic being generated (although you can avoid this, by
532         specifying the --random-seed option).</para>
534         <para>As well as changing how long the model runs for, you can also
535         change how many conversations get generated and how fast the traffic
536         gets replayed. To roughly double the number of conversations that get
537         replayed, use --scale-traffic=2 or to approximately halve the number
538         use --scale-traffic=0.5. To approximately double how quickly the
539         conversations get replayed, use --replay-rate=2, or to halve this use
540         --replay-rate=0.5</para>
542         <para>For example, to generate approximately 10 times the amount of
543         traffic seen over a two-minute period (based on the network capture),
544         use:</para>
546         <para><command>traffic_replay traffic-model.txt
547         my-dc.samdom.example.com -UAdmin%password --fixed-password=blahblah123!
548         --scale-traffic=10 --duration=120</command></para>
549 </refsect2>
551 <refsect2>
552         <title>Scaling the number of users</title>
553         <para>The performance of a Samba DC running a small subset of test
554         users will be different to a fully-populated Samba DC running in a
555         network. As the number of users increases, the size of the DB
556         increases, and a very large DB will perform worse than a smaller DB.
557         </para>
559         <para>To increase the size of the Samba DB, this tool can also create
560         extra users and groups. These extra users are basically 'filler' for
561         the DB. They won't actually be used to generate traffic, but they may
562         slow down authentication of the test users.</para>
564         <para>For example, to populate the DB with an extra 5000 users (note
565         this will take a while), use the command:</para>
567         <para><command>traffic_replay my-dc.samdom.example.com
568         -UAdmin%password --generate-users-only --fixed-password=blahblah123!
569         --number-of-users=5000</command></para>
571         <para>You can also create groups and assign users to groups. The users
572         can be randomly assigned to groups - this includes any extra users
573         created as well as the users that map to conversations. Use either
574         --average-groups-per-user or --group-memberships to specify how many
575         group memberships should be assigned to the test users.</para>
577         <para>For example, to assign the users in the replayed conversations
578         into 10 groups on average, use a command like:</para>
580         <para><command>traffic_replay traffic-model.txt my-dc.samdom.example.com
581         -UAdmin%password --fixed-password=blahblah123!
582         --generate-users-only --number-of-groups=25 --average-groups-per-user=10
583         </command></para>
585         <para>The users created by the test will have names like STGU-0-xyz.
586         The groups generated have names like STGG-0-xyz.</para>
587 </refsect2>
588 </refsect1>
591 <refsect1>
592         <title>VERSION</title>
594         <para>This man page is complete for version &doc.version; of the Samba
595         suite.</para>
596 </refsect1>
598 <refsect1>
599         <title>SEE ALSO</title>
600         <para>
601         <citerefentry>
602         <refentrytitle>traffic_learner</refentrytitle><manvolnum>7</manvolnum>
603         </citerefentry>.
604         </para>
605 </refsect1>
607 <refsect1>
608         <title>AUTHOR</title>
610         <para>The original Samba software and related utilities
611         were created by Andrew Tridgell. Samba is now developed
612         by the Samba Team as an Open Source project similar
613         to the way the Linux kernel is developed.</para>
615         <para>The traffic_replay tool was developed by the Samba team at
616         Catalyst IT Ltd.</para>
618         <para>The traffic_replay manpage was written by Tim Beale.</para>
619 </refsect1>
621 </refentry>