1TRAFFIC_REPLAY(7)                User Commands               TRAFFIC_REPLAY(7)
2
3
4

NAME

6       traffic_replay - Samba traffic generation tool.
7

SYNOPSIS

9       traffic_replay [-F, --fixed-password <test-password>]
10        [-T, --packets-per-second <number>]
11        [-S, --scale-traffic <scale by factor>]
12        [-r, --replay-rate <scale by factor>] [-D, --duration <seconds>]
13        [--traffic-summary <output file>] [-I, --instance-id <id>]
14        [-K, --prefer-kerberos] [-B, --badpassword-frequency <frequency>]
15        [--dns-rate <rate>] [-t, --timing-data <file>] [--random-seed <seed>]
16        [-U, --username user] [--password <password>]
17        [-W --workgroup <workgroup>] [--realm <realm>]
18        [-s, --config-file <file>] [-k, --kerberos <kerberos>]
19        [--ipaddress <address>] [-P, --machine-pass] [--option <option>]
20        [-d, --debuglevel <debug level>] [--conversation-persistence <0-1>]
21        [--latency-timeout <seconds>] [--stop-on-any-error] {summary-file}
22        {dns-hostname}
23
24       traffic_replay [-G, --generate-users-only]
25        [-F, --fixed-password <test-password>]
26        [-n, --number-of-users <total users>]
27        [--number-of-groups <total groups>]
28        [--average-groups-per-user <average number>]
29        [--group-memberships <total memberships>] [--max-members <group size>]
30        {dns-hostname}
31
32       traffic_replay {-c|--clean-up} {dns-hostname}
33
34       traffic_replay [-h, --help] [-V, --version]
35

DESCRIPTION

37       This tool is part of the samba(7) suite.
38
39       This tool generates traffic in order to measure the performance of a
40       Samba DC, and to test how well Samba will scale as a network increases
41       in size. It can simulate multiple different hosts making multiple
42       different types of requests to a DC.
43
44       This tool is intended to run against a dedicated test DC (rather than a
45       live DC that is handling real network traffic).
46
47       Note that a side-effect of running this tool is that user accounts will
48       be created on the DC, in order to test various Samba operations. As
49       creating accounts can be very time-consuming, these users will remain
50       on the DC by default. To remove these accounts, use the --clean-up
51       option.
52

OPTIONS

54       -h|--help
55           Print a summary of command line options.
56
57       summary-file
58           File containing the network traffic to replay. This should be a
59           traffic-model (generated by traffic_learner). Based on this file,
60           this tool will generate 'conversations' which represent Samba
61           activity between a network host and the DC.
62
63       dns-hostname
64           The full DNS hostname of the DC that's being tested. The Samba
65           activity in the summary-file will be replicated and directed at
66           this DC. It's recommended that you use a dedicated DC for testing
67           and don't try to run this tool against a DC that's processing live
68           network traffic.
69
70       -F|--fixed-password <test-password>
71           Test users are created when this tool is run, so that actual Samba
72           activity, such as authorizing users, can be mimicked. This option
73           specifies the password that will be used for any test users that
74           are created.
75
76           Note that any users created by this tool will remain on the DC
77           until you run the --clean-up option. Therefore, the fixed-password
78           option needs to be the same each time the tool is run, otherwise
79           the test users won't authenticate correctly.
80
81       random-seed
82           A number to seed the random number generator with. When traffic is
83           generated from a model-file, use this option to keep the traffic
84           consistent across multiple test runs. This allows you to compare
85           the performance of Samba between different releases.
86
87       Traffic Model Options
88           When the summary-file is a traffic-model (produced by
89           traffic_learner), use these options to alter the traffic that gets
90           generated.
91
92           -D|--duration <seconds>
93               Specifies the approximate duration in seconds to generate
94               traffic for. The default is 60 seconds.
95
96           -T|--packets-per-second <number>
97               Generate this many packets per second, regardless of the
98               traffic rate of the sample on which the model was based. This
99               cannot be used with -S.
100
101           -S|--scale-traffic <factor>
102               Increases the number of conversations by this factor, relative
103               to the original traffic sample on which the model was based.
104               This option won't affect the rate at which packets get sent
105               (which is still based on the traffic model), but it will mean
106               more conversations get replayed. It cannot be combined with -T,
107               which sets the traffic rate in a different way.
108
109           -r|--replay-rate <factor>
110               Replays the traffic faster by this factor. This option won't
111               affect the number of packets sent, but it will squeeze them
112               into fewer conversations, which may reduce resource usage.
113
114           --traffic-summary <output-file>
115               Instead of replaying a traffic-model, this option generates a
116               traffic-summary file based on what traffic would be sent. Using
117               a traffic-model allows you to scale the packet rate and number
118               of packets sent. However, using a traffic-model introduces some
119               randomness into the traffic generation. So running the same
120               traffic_replay command multiple times using a model file may
121               result in some differences in the actual traffic sent. However,
122               running the same traffic_replay command multiple times with a
123               traffic-summary file will always result in the same traffic
124               being sent.
125
126               For taking performance measurements over several test runs,
127               it's recommended to use this option and replay the traffic from
128               a traffic-summary file, or to use the --random-seed option.
129
130           --stop-on-any-error
131               Any client error causes the whole run to stop.
132
133           --conversation-persistence <0-1>
134               Conversation termination (as decided by the model) is
135               re-interpreted as a long pause with this probability.
136
137           --latency-timeout <seconds>
138               Wait this long at the end of the run for outstanding reply
139               packets. The number of conversations that have not finished at
140               the end of the timeout is a failure metric.
141
142       --generate-users-only
143           Add extra user/groups on the DC to increase the DB size. By
144           default, this tool automatically creates test users that map to the
145           traffic conversations being generated. This option allows extra
146           users to be created on top of this. Note that these extra users may
147           not actually used for traffic generation - the traffic generation
148           is still based on the number of conversations from the
149           model/summary file.
150
151           Generating a large number of users can take a long time, so it this
152           option allows this to be done only once.
153
154           Note that the users created will remain on the DC until the tool is
155           run with the --clean-up option. This means that it is best to only
156           assign group memberships once, i.e. run --clean-up before assigning
157           a different allocation of group memberships.
158
159           -n|--number-of-users <total-users>
160               Specifies the total number of test users to create (excluding
161               any machine accounts required for the traffic). Note that these
162               extra users simply populate the DC's DB - the actual user
163               traffic generated is still based on the summary-file.
164
165           --number-of-groups <total-groups>
166               Creates the specified number of groups, for assigning the test
167               users to. Note that users are not automatically assigned to
168               groups - use either --average-groups-per-user or
169               --group-memberships to do this.
170
171           --average-groups-per-user <average-groups>
172               Randomly assigns the test users to the test groups created. The
173               group memberships are distributed so that the overall average
174               groups that a user is member of matches this number. Some users
175               will belong to more groups and some users will belong to fewer
176               groups. This option is incompatible with the --group-membership
177               option.
178
179           --group-memberships <total-memberships>
180               Randomly assigns the test users to the test groups created. The
181               group memberships are distributed so that the total groups that
182               a user is member of, across all users, matches this number. For
183               example, with 100 users and 10 groups, --group-memberships=300
184               would assign a user to 3 groups on average. Some users will
185               belong to more groups and some users will belong to fewer
186               groups, but the total of all member linked attributes would be
187               300. This option is incompatible with the
188               --average-groups-per-user option.
189
190           --max-members <group size>
191               Limit the largest group to this size, even if the other group
192               options would have it otherwise.
193
194
195       --clean-up
196           Cleans up any users and groups that were created by previously
197           running this tool. It is recommended you always clean up after
198           running the tool.
199
200       -I|--instance-id <id>
201           Use this option to run multiple instances of the tool on the same
202           DC at the same time. This adds a prefix to the test users generated
203           to keep them separate on the DC.
204
205       -K|--prefer-kerberos
206           Use Kerberos to authenticate the test users.
207
208       -B|--badpassword-frequency <frequency>
209           Use this option to simulate users trying to authenticate with an
210           incorrect password.
211
212       --dns-rate <rate>
213           Increase the rate at which DNS packets get sent.
214
215       -t|--timing-data <file>
216           This writes extra timing data to the file specified. This is mostly
217           used for reporting options, such as generating graphs.
218
219       Samba Common Options
220
221           -d|--debuglevel=level
222               level is an integer from 0 to 10. The default value if this
223               parameter is not specified is 1.
224
225               The higher this value, the more detail will be logged to the
226               log files about the activities of the server. At level 0, only
227               critical errors and serious warnings will be logged. Level 1 is
228               a reasonable level for day-to-day running - it generates a
229               small amount of information about operations carried out.
230
231               Levels above 1 will generate considerable amounts of log data,
232               and should only be used when investigating a problem. Levels
233               above 3 are designed for use only by developers and generate
234               HUGE amounts of log data, most of which is extremely cryptic.
235
236               Note that specifying this parameter here will override the log
237               level parameter in the smb.conf file.
238
239           -s|--configfile=<configuration file>
240               The file specified contains the configuration details required
241               by the server. The information in this file includes
242               server-specific information such as what printcap file to use,
243               as well as descriptions of all the services that the server is
244               to provide. See smb.conf for more information. The default
245               configuration file name is determined at compile time.
246
247           --option=<name>=<value>
248               Set the smb.conf(5) option "<name>" to value "<value>" from the
249               command line. This overrides compiled-in defaults and options
250               read from the configuration file.
251
252           --realm=REALM
253               Set the realm name
254
255           -V|--version
256               Prints the program version number.
257
258
259       Credential Options
260
261           --simple-bind-dn=DN
262               DN to use for a simple bind
263
264           --password=PASSWORD
265               Password
266
267           -U USERNAME|--username=USERNAME
268               Username
269
270           -W WORKGROUP|--workgroup=WORKGROUP
271               Workgroup
272
273           -k|--kerberos
274               Try to authenticate with kerberos. Only useful in an Active
275               Directory environment.
276
277           --ipaddress=IPADDRESS
278               IP address of the server
279
280           -P|--machine-pass
281               Use stored machine account password.
282
283

OPERATIONS

285   Generating a traffic-summary file
286       To use this tool, you need either a traffic-summary file or a
287       traffic-model file. To generate either of these files, you will need a
288       packet capture of actual Samba activity on your network.
289
290       Use Wireshark to take a packet capture on your network of the traffic
291       you want to generate. For example, if you want to simulate lots of
292       users logging on, then take a capture at 8:30am when users are logging
293       in.
294
295       Next, you need to convert your packet capture into a traffic summary
296       file, using traffic_summary.pl. Basically this removes any sensitive
297       information from the capture and summarizes what type of packet was
298       sent and when.
299
300       Refer to the traffic_summary.pl --help help for more details, but the
301       basic command will look something like:
302
303       tshark -r capture.pcapng -T pdml | traffic_summary.pl >
304       traffic-summary.txt
305
306   Replaying a traffic-summary file
307       Once you have a traffic-summary file, you can use it to generate
308       traffic. The traffic_replay tool gets passed the traffic-summary file,
309       along with the full DNS hostname of the DC being tested. You also need
310       to provide some user credentials, and possibly the Samba realm and
311       workgroup (although the realm and workgroup may be determined
312       automatically, for example from the /etc/smb.conf file, if one is
313       present). E.g.
314
315       traffic_replay traffic-summary.txt my-dc.samdom.example.com
316       -UAdmin%password -W samdom --realm=samdom.example.com
317       --fixed-password=blahblah123!
318
319       This simply regenerates Samba activity seen in the traffic summary. The
320       traffic is grouped into 'conversations' between a host and the DC. A
321       user and machine account is created on the DC for each conversation, in
322       order to allow logon and other operations to succeed. The script
323       generates the same types of packets as those seen in the summary.
324
325       Creating users can be quite a time-consuming process, especially if a
326       lot of conversations are being generated. To save time, the test users
327       remain on the DC by default. You will need to run the --clean-up option
328       to remove them, once you have finished generating traffic. Because the
329       same test users are used across multiple runs of the tool, a consistent
330       password for these users needs to be used - this is specified by the
331       --fixed-password option.
332
333       The benefit of this tool over simply using tcprelay is that the traffic
334       generated is independent of any specific network. No setup is needed
335       beforehand on the test DC. The traffic no longer contains sensitive
336       details, so the traffic summary could be potentially shared with other
337       Samba developers.
338
339       However, replaying a traffic-summary directly is somewhat limited in
340       what you can actually do. A more flexible approach is to generate the
341       traffic using a model file.
342
343   Generating a traffic-model file
344       To create a traffic-model file, simply pass the traffic-summary file to
345       the traffic_learner script. E.g.
346
347       traffic_learner traffic-summary.txt -o traffic-model.txt
348
349       This generates a model of the Samba activity in your network. This
350       model-file can now be used to generate traffic.
351
352   Replaying the traffic-model file
353       Packet generation using a traffic-model file uses the same command as a
354       traffic-summary file, e.g.
355
356       traffic_replay traffic-model.txt my-dc.samdom.example.com
357       -UAdmin%password
358
359       By default, this will generate 60 seconds worth of traffic based on the
360       model. You can specify longer using the --duration parameter.
361
362       The traffic generated is an approximation of what was seen in the
363       network capture. The traffic generation involves some randomness, so
364       running the same command multiple times may result in slightly
365       different traffic being generated (although you can avoid this, by
366       specifying the --random-seed option).
367
368       As well as changing how long the model runs for, you can also change
369       how many conversations get generated and how fast the traffic gets
370       replayed. To roughly double the number of conversations that get
371       replayed, use --scale-traffic=2 or to approximately halve the number
372       use --scale-traffic=0.5. To approximately double how quickly the
373       conversations get replayed, use --replay-rate=2, or to halve this use
374       --replay-rate=0.5
375
376       For example, to generate approximately 10 times the amount of traffic
377       seen over a two-minute period (based on the network capture), use:
378
379       traffic_replay traffic-model.txt my-dc.samdom.example.com
380       -UAdmin%password --fixed-password=blahblah123! --scale-traffic=10
381       --duration=120
382
383   Scaling the number of users
384       The performance of a Samba DC running a small subset of test users will
385       be different to a fully-populated Samba DC running in a network. As the
386       number of users increases, the size of the DB increases, and a very
387       large DB will perform worse than a smaller DB.
388
389       To increase the size of the Samba DB, this tool can also create extra
390       users and groups. These extra users are basically 'filler' for the DB.
391       They won't actually be used to generate traffic, but they may slow down
392       authentication of the test users.
393
394       For example, to populate the DB with an extra 5000 users (note this
395       will take a while), use the command:
396
397       traffic_replay my-dc.samdom.example.com -UAdmin%password
398       --generate-users-only --fixed-password=blahblah123!
399       --number-of-users=5000
400
401       You can also create groups and assign users to groups. The users can be
402       randomly assigned to groups - this includes any extra users created as
403       well as the users that map to conversations. Use either
404       --average-groups-per-user or --group-memberships to specify how many
405       group memberships should be assigned to the test users.
406
407       For example, to assign the users in the replayed conversations into 10
408       groups on average, use a command like:
409
410       traffic_replay traffic-model.txt my-dc.samdom.example.com
411       -UAdmin%password --fixed-password=blahblah123! --generate-users-only
412       --number-of-groups=25 --average-groups-per-user=10
413
414       The users created by the test will have names like STGU-0-xyz. The
415       groups generated have names like STGG-0-xyz.
416

VERSION

418       This man page is complete for version 4.10.4 of the Samba suite.
419

SEE ALSO

421       traffic_learner(7).
422

AUTHOR

424       The original Samba software and related utilities were created by
425       Andrew Tridgell. Samba is now developed by the Samba Team as an Open
426       Source project similar to the way the Linux kernel is developed.
427
428       The traffic_replay tool was developed by the Samba team at Catalyst IT
429       Ltd.
430
431       The traffic_replay manpage was written by Tim Beale.
432
433
434
435Samba 4.10.4                      05/28/2019                 TRAFFIC_REPLAY(7)
Impressum