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