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

DESCRIPTION

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

OPTIONS

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

OPERATIONS

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

VERSION

394       This man page is complete for version 4.9.8 of the Samba suite.
395

SEE ALSO

397       traffic_learner(7).
398

AUTHOR

400       The original Samba software and related utilities were created by
401       Andrew Tridgell. Samba is now developed by the Samba Team as an Open
402       Source project similar to the way the Linux kernel is developed.
403
404       The traffic_replay tool was developed by the Samba team at Catalyst IT
405       Ltd.
406
407       The traffic_replay manpage was written by Tim Beale.
408
409
410
411Samba 4.9.8                       05/14/2019                 TRAFFIC_REPLAY(7)
Impressum