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=DEBUGLEVEL
222 level is an integer from 0 to 10. The default value if this
223 parameter is not specified is 1 for client applications.
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 /etc/samba/smb.conf file.
238 --debug-stdout
240 This will redirect debug output to STDOUT. By default all
241 clients are logging to STDERR.
242 --configfile=<configuration file>
244 The file specified contains the configuration details required
245 by the client. The information in this file can be general for
246 client and server or only provide client specific like options
247 such as client smb encrypt. See /etc/samba/smb.conf for more
248 information. The default configuration file name is determined
249 at compile time.
250 --option=<name>=<value>
252 Set the smb.conf(5) option "<name>" to value "<value>" from the
253 command line. This overrides compiled-in defaults and options
254 read from the configuration file. If a name or a value includes
255 a space, wrap whole --option=name=value into quotes.
256 --realm=REALM
258 Set the realm name
259 -V|--version
261 Prints the program version number.
262 Credential Options
265 --simple-bind-dn=DN
267 DN to use for a simple bind
268 --password=PASSWORD
270 Password
271 -U USERNAME|--username=USERNAME
273 Username
274 -W WORKGROUP|--workgroup=WORKGROUP
276 Workgroup
277 --use-kerberos=desired|required|off
279 This parameter determines whether Samba client tools will try
280 to authenticate using Kerberos. For Kerberos authentication you
281 need to use dns names instead of IP addresses when connecting
282 to a service.
283 Note that specifying this parameter here will override the
285 client use kerberos parameter in the /etc/samba/smb.conf file.
286 --ipaddress=IPADDRESS
288 IP address of the server
289 -P|--machine-pass
291 Use stored machine account password.
292
295 Generating a traffic-summary file
296 To use this tool, you need either a traffic-summary file or a
297 traffic-model file. To generate either of these files, you will need a
298 packet capture of actual Samba activity on your network.
299 Use Wireshark to take a packet capture on your network of the traffic
301 you want to generate. For example, if you want to simulate lots of
302 users logging on, then take a capture at 8:30am when users are logging
303 in.
304 Next, you need to convert your packet capture into a traffic summary
306 file, using traffic_summary.pl. Basically this removes any sensitive
307 information from the capture and summarizes what type of packet was
308 sent and when.
309 Refer to the traffic_summary.pl --help help for more details, but the
311 basic command will look something like:
312 tshark -r capture.pcapng -T pdml | traffic_summary.pl >
314 traffic-summary.txt
315 Replaying a traffic-summary file
317 Once you have a traffic-summary file, you can use it to generate
318 traffic. The traffic_replay tool gets passed the traffic-summary file,
319 along with the full DNS hostname of the DC being tested. You also need
320 to provide some user credentials, and possibly the Samba realm and
321 workgroup (although the realm and workgroup may be determined
322 automatically, for example from the /etc/smb.conf file, if one is
323 present). E.g.
324 traffic_replay traffic-summary.txt my-dc.samdom.example.com
326 -UAdmin%password -W samdom --realm=samdom.example.com
327 --fixed-password=blahblah123!
328 This simply regenerates Samba activity seen in the traffic summary. The
330 traffic is grouped into 'conversations' between a host and the DC. A
331 user and machine account is created on the DC for each conversation, in
332 order to allow logon and other operations to succeed. The script
333 generates the same types of packets as those seen in the summary.
334 Creating users can be quite a time-consuming process, especially if a
336 lot of conversations are being generated. To save time, the test users
337 remain on the DC by default. You will need to run the --clean-up option
338 to remove them, once you have finished generating traffic. Because the
339 same test users are used across multiple runs of the tool, a consistent
340 password for these users needs to be used - this is specified by the
341 --fixed-password option.
342 The benefit of this tool over simply using tcprelay is that the traffic
344 generated is independent of any specific network. No setup is needed
345 beforehand on the test DC. The traffic no longer contains sensitive
346 details, so the traffic summary could be potentially shared with other
347 Samba developers.
348 However, replaying a traffic-summary directly is somewhat limited in
350 what you can actually do. A more flexible approach is to generate the
351 traffic using a model file.
352 Generating a traffic-model file
354 To create a traffic-model file, simply pass the traffic-summary file to
355 the traffic_learner script. E.g.
356 traffic_learner traffic-summary.txt -o traffic-model.txt
358 This generates a model of the Samba activity in your network. This
360 model-file can now be used to generate traffic.
361 Replaying the traffic-model file
363 Packet generation using a traffic-model file uses the same command as a
364 traffic-summary file, e.g.
365 traffic_replay traffic-model.txt my-dc.samdom.example.com
367 -UAdmin%password
368 By default, this will generate 60 seconds worth of traffic based on the
370 model. You can specify longer using the --duration parameter.
371 The traffic generated is an approximation of what was seen in the
373 network capture. The traffic generation involves some randomness, so
374 running the same command multiple times may result in slightly
375 different traffic being generated (although you can avoid this, by
376 specifying the --random-seed option).
377 As well as changing how long the model runs for, you can also change
379 how many conversations get generated and how fast the traffic gets
380 replayed. To roughly double the number of conversations that get
381 replayed, use --scale-traffic=2 or to approximately halve the number
382 use --scale-traffic=0.5. To approximately double how quickly the
383 conversations get replayed, use --replay-rate=2, or to halve this use
384 --replay-rate=0.5
385 For example, to generate approximately 10 times the amount of traffic
387 seen over a two-minute period (based on the network capture), use:
388 traffic_replay traffic-model.txt my-dc.samdom.example.com
390 -UAdmin%password --fixed-password=blahblah123! --scale-traffic=10
391 --duration=120
392 Scaling the number of users
394 The performance of a Samba DC running a small subset of test users will
395 be different to a fully-populated Samba DC running in a network. As the
396 number of users increases, the size of the DB increases, and a very
397 large DB will perform worse than a smaller DB.
398 To increase the size of the Samba DB, this tool can also create extra
400 users and groups. These extra users are basically 'filler' for the DB.
401 They won't actually be used to generate traffic, but they may slow down
402 authentication of the test users.
403 For example, to populate the DB with an extra 5000 users (note this
405 will take a while), use the command:
406 traffic_replay my-dc.samdom.example.com -UAdmin%password
408 --generate-users-only --fixed-password=blahblah123!
409 --number-of-users=5000
410 You can also create groups and assign users to groups. The users can be
412 randomly assigned to groups - this includes any extra users created as
413 well as the users that map to conversations. Use either
414 --average-groups-per-user or --group-memberships to specify how many
415 group memberships should be assigned to the test users.
416 For example, to assign the users in the replayed conversations into 10
418 groups on average, use a command like:
419 traffic_replay traffic-model.txt my-dc.samdom.example.com
421 -UAdmin%password --fixed-password=blahblah123! --generate-users-only
422 --number-of-groups=25 --average-groups-per-user=10
423 The users created by the test will have names like STGU-0-xyz. The
425 groups generated have names like STGG-0-xyz.
426
428 This man page is complete for version 4.19.3 of the Samba suite.
429
431 traffic_learner(7).
432
434 The original Samba software and related utilities were created by
435 Andrew Tridgell. Samba is now developed by the Samba Team as an Open
436 Source project similar to the way the Linux kernel is developed.
437 The traffic_replay tool was developed by the Samba team at Catalyst IT
439 Ltd.
440 The traffic_replay manpage was written by Tim Beale.
442Samba 4.19.3 11/27/2023 TRAFFIC_REPLAY(7)