1TRAFFIC_REPLAY(7) User Commands TRAFFIC_REPLAY(7)
2
6 traffic_replay - Samba traffic generation tool.
7
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 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 traffic_replay {-c|--clean-up} {dns-hostname}
33 traffic_replay [-h, --help] [-V, --version]
35
37 This tool is part of the samba(7) suite.
38 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 This tool is intended to run against a dedicated test DC (rather than a
45 live DC that is handling real network traffic).
46 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
54 -h|--help
55 Print a summary of command line options.
56 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 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 -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 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 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 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 -D|--duration <seconds>
93 Specifies the approximate duration in seconds to generate
94 traffic for. The default is 60 seconds.
95 -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 -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 -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 --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 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 --stop-on-any-error
131 Any client error causes the whole run to stop.
132 --conversation-persistence <0-1>
134 Conversation termination (as decided by the model) is
135 re-interpreted as a long pause with this probability.
136 --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 --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 Generating a large number of users can take a long time, so it this
152 option allows this to be done only once.
153 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 -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 --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 --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 --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 --max-members <group size>
191 Limit the largest group to this size, even if the other group
192 options would have it otherwise.
193 --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 -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 -K|--prefer-kerberos
206 Use Kerberos to authenticate the test users.
207 -B|--badpassword-frequency <frequency>
209 Use this option to simulate users trying to authenticate with an
210 incorrect password.
211 --dns-rate <rate>
213 Increase the rate at which DNS packets get sent.
214 -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 Samba Common Options
220 -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 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 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 Note that specifying this parameter here will override the log
237 level parameter in the smb.conf file.
238 -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 --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 --realm=REALM
253 Set the realm name
254 -V|--version
256 Prints the program version number.
257 Credential Options
260 --simple-bind-dn=DN
262 DN to use for a simple bind
263 --password=PASSWORD
265 Password
266 -U USERNAME|--username=USERNAME
268 Username
269 -W WORKGROUP|--workgroup=WORKGROUP
271 Workgroup
272 -k|--kerberos
274 Try to authenticate with kerberos. Only useful in an Active
275 Directory environment.
276 --ipaddress=IPADDRESS
278 IP address of the server
279 -P|--machine-pass
281 Use stored machine account password.
282
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 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 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 Refer to the traffic_summary.pl --help help for more details, but the
301 basic command will look something like:
302 tshark -r capture.pcapng -T pdml | traffic_summary.pl >
304 traffic-summary.txt
305 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 traffic_replay traffic-summary.txt my-dc.samdom.example.com
316 -UAdmin%password -W samdom --realm=samdom.example.com
317 --fixed-password=blahblah123!
318 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 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 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 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 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 traffic_learner traffic-summary.txt -o traffic-model.txt
348 This generates a model of the Samba activity in your network. This
350 model-file can now be used to generate traffic.
351 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 traffic_replay traffic-model.txt my-dc.samdom.example.com
357 -UAdmin%password
358 By default, this will generate 60 seconds worth of traffic based on the
360 model. You can specify longer using the --duration parameter.
361 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 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 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 traffic_replay traffic-model.txt my-dc.samdom.example.com
380 -UAdmin%password --fixed-password=blahblah123! --scale-traffic=10
381 --duration=120
382 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 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 For example, to populate the DB with an extra 5000 users (note this
395 will take a while), use the command:
396 traffic_replay my-dc.samdom.example.com -UAdmin%password
398 --generate-users-only --fixed-password=blahblah123!
399 --number-of-users=5000
400 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 For example, to assign the users in the replayed conversations into 10
408 groups on average, use a command like:
409 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 The users created by the test will have names like STGU-0-xyz. The
415 groups generated have names like STGG-0-xyz.
416
418 This man page is complete for version 4.12.2 of the Samba suite.
419
421 traffic_learner(7).
422
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 The traffic_replay tool was developed by the Samba team at Catalyst IT
429 Ltd.
430 The traffic_replay manpage was written by Tim Beale.
432Samba 4.12.2 04/28/2020 TRAFFIC_REPLAY(7)