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 [-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 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 traffic_replay {-c|--clean-up} {dns-hostname}
29 traffic_replay [-h, --help] [-V, --version]
31
33 This tool is part of the samba(7) suite.
34 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 This tool is intended to run against a dedicated test DC (rather than a
41 live DC that is handling real network traffic).
42 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
50 -h|--help
51 Print a summary of command line options.
52 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 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 -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 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 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 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 -D|--duration <seconds>
90 Specifies the approximate duration in seconds to generate
91 traffic for. The default is 60 seconds.
92 -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 -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 --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 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 --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 Generating a large number of users can take a long time, so it this
132 option allows this to be done only once.
133 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 -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 --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 --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 --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 --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 -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 -K|--prefer-kerberos
182 Use Kerberos to authenticate the test users.
183 -B|--badpassword-frequency <frequency>
185 Use this option to simulate users trying to authenticate with an
186 incorrect password.
187 --dns-rate <rate>
189 Increase the rate at which DNS packets get sent.
190 -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 Samba Common Options
196 -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 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 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 Note that specifying this parameter here will override the log
213 level parameter in the smb.conf file.
214 -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 --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 --realm=REALM
229 Set the realm name
230 -V|--version
232 Prints the program version number.
233 Credential Options
236 --simple-bind-dn=DN
238 DN to use for a simple bind
239 --password=PASSWORD
241 Password
242 -U USERNAME|--username=USERNAME
244 Username
245 -W WORKGROUP|--workgroup=WORKGROUP
247 Workgroup
248 -k|--kerberos
250 Try to authenticate with kerberos. Only useful in an Active
251 Directory environment.
252 --ipaddress=IPADDRESS
254 IP address of the server
255 -P|--machine-pass
257 Use stored machine account password.
258
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 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 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 Refer to the traffic_summary.pl --help help for more details, but the
277 basic command will look something like:
278 tshark -r capture.pcapng -T pdml | traffic_summary.pl >
280 traffic-summary.txt
281 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 traffic_replay traffic-summary.txt my-dc.samdom.example.com
292 -UAdmin%password -W samdom --realm=samdom.example.com
293 --fixed-password=blahblah123!
294 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 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 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 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 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 traffic_learner traffic-summary.txt -o traffic-model.txt
324 This generates a model of the Samba activity in your network. This
326 model-file can now be used to generate traffic.
327 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 traffic_replay traffic-model.txt my-dc.samdom.example.com
333 -UAdmin%password
334 By default, this will generate 60 seconds worth of traffic based on the
336 model. You can specify longer using the --duration parameter.
337 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 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 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 traffic_replay traffic-model.txt my-dc.samdom.example.com
356 -UAdmin%password --fixed-password=blahblah123! --scale-traffic=10
357 --duration=120
358 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 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 For example, to populate the DB with an extra 5000 users (note this
371 will take a while), use the command:
372 traffic_replay my-dc.samdom.example.com -UAdmin%password
374 --generate-users-only --fixed-password=blahblah123!
375 --number-of-users=5000
376 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 For example, to assign the users in the replayed conversations into 10
384 groups on average, use a command like:
385 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 The users created by the test will have names like STGU-0-xyz. The
391 groups generated have names like STGG-0-xyz.
392
394 This man page is complete for version 4.9.1 of the Samba suite.
395
397 traffic_learner(7).
398
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 The traffic_replay tool was developed by the Samba team at Catalyst IT
405 Ltd.
406 The traffic_replay manpage was written by Tim Beale.
408Samba 4.9.1 05/11/2019 TRAFFIC_REPLAY(7)