docs-xml/manpages/traffic_replay.7.xml

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