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>] [-U, --username user]
15 [--password <password>] [-W --workgroup <workgroup>] [--realm <realm>]
16 [-s, --config-file <file>] [-k, --kerberos <kerberos>]
17 [--ipaddress <address>] [-P, --machine-pass] [--option <option>]
18 [-d, --debuglevel <debug level>] {summary-file} {dns-hostname}
19 traffic_replay [-G, --generate-users-only]
21 [-F, --fixed-password <test-password>]
22 [-n, --number-of-users <total users>]
23 [--number-of-groups <total groups>]
24 [--average-groups-per-user <average number>]
25 [--group-memberships <total memberships>] {dns-hostname}
26 traffic_replay {-c|--clean-up} {dns-hostname}
28 traffic_replay [-h, --help] [-V, --version]
30
32 This tool is part of the samba(7) suite.
33 This tool generates traffic in order to measure the performance of a
35 Samba DC, and to test how well Samba will scale as a network increases
36 in size. It can simulate multiple different hosts making multiple
37 different types of requests to a DC.
38 This tool is intended to run against a dedicated test DC (rather than a
40 live DC that is handling real network traffic).
41 Note that a side-effect of running this tool is that user accounts will
43 be created on the DC, in order to test various Samba operations. As
44 creating accounts can be very time-consuming, these users will remain
45 on the DC by default. To remove these accounts, use the --clean-up
46 option.
47
49 -h|--help
50 Print a summary of command line options.
51 summary-file
53 File containing the network traffic to replay. This should either
54 be a traffic-summary (generated by traffic_summary.pl) or a
55 traffic-model (generated by traffic_learner). Based on this file,
56 this tool will generate 'conversations' which represent Samba
57 activity between a network host and the DC.
58 dns-hostname
60 The full DNS hostname of the DC that's being tested. The Samba
61 activity in the summary-file will be replicated and directed at
62 this DC. It's recommended that you use a dedicated DC for testing
63 and don't try to run this tool against a DC that's processing live
64 network traffic.
65 -F|--fixed-password <test-password>
67 Test users are created when this tool is run, so that actual Samba
68 activity, such as authorizing users, can be mimicked. This option
69 specifies the password that will be used for any test users that
70 are created.
71 Note that any users created by this tool will remain on the DC
73 until you run the --clean-up option. Therefore, the fixed-password
74 option needs to be the same each time the tool is run, otherwise
75 the test users won't authenticate correctly.
76 Traffic Model Options
78 When the summary-file is a traffic-model (produced by
79 traffic_learner), use these options to alter the traffic that gets
80 generated.
81 -D|--duration <seconds>
83 Specifies the approximate duration in seconds to generate
84 traffic for. The default is 60 seconds.
85 -r|--replay-rate <factor>
87 Replays the traffic faster by this factor. This option won't
88 affect the number of conversations (which is based on the
89 traffic model), but the rate at which the packets are sent will
90 be increased.
91 -S|--scale-traffic <factor>
93 Increases the number of conversations by this factor. This
94 option won't affect the rate at which packets get sent (which
95 is still based on the traffic model), but it will mean more
96 conversations get replayed.
97 --traffic-summary <output-file>
99 Instead of replaying a traffic-model, this option generates a
100 traffic-summary file based on what traffic would be sent. Using
101 a traffic-model allows you to scale the packet rate and number
102 of packets sent. However, using a traffic-model introduces some
103 randomness into the traffic generation. So running the same
104 traffic_replay command multiple times using a model file may
105 result in some differences in the actual traffic sent. However,
106 running the same traffic_replay command multiple times with a
107 traffic-summary file will always result in the same traffic
108 being sent.
109 For taking performance measurements over several test runs,
111 it's recommended to use this option and replay the traffic from
112 a traffic-summary file.
113 --generate-users-only
116 Add extra user/groups on the DC to increase the DB size. By
117 default, this tool automatically creates test users that map to the
118 traffic conversations being generated. This option allows extra
119 users to be created on top of this. Note that these extra users may
120 not actually used for traffic generation - the traffic generation
121 is still based on the number of conversations from the
122 model/summary file.
123 Generating a large number of users can take a long time, so it this
125 option allows this to be done only once.
126 Note that the users created will remain on the DC until the tool is
128 run with the --clean-up option. This means that it is best to only
129 assign group memberships once, i.e. run --clean-up before assigning
130 a different allocation of group memberships.
131 -n|--number-of-users <total-users>
133 Specifies the total number of test users to create (excluding
134 any machine accounts required for the traffic). Note that these
135 extra users simply populate the DC's DB - the actual user
136 traffic generated is still based on the summary-file.
137 --number-of-groups <total-groups>
139 Creates the specified number of groups, for assigning the test
140 users to. Note that users are not automatically assigned to
141 groups - use either --average-groups-per-user or
142 --group-membership to do this.
143 --average-groups-per-user <average-groups>
145 Randomly assigns the test users to the test groups created. The
146 group memberships are distributed so that the overall average
147 groups that a user is member of matches this number. Some users
148 will belong to more groups and some users will belong to fewer
149 groups. This option is incompatible with the --group-membership
150 option.
151 --group-memberships <total-memberships>
153 Randomly assigns the test users to the test groups created. The
154 group memberships are distributed so that the total groups that
155 a user is member of, across all users, matches this number. For
156 example, with 100 users and 10 groups, --group-memberships=300
157 would assign a user to 3 groups on average. Some users will
158 belong to more groups and some users will belong to fewer
159 groups, but the total of all member linked attributes would be
160 300. This option is incompatible with the --group-membership
161 option.
162 --clean-up
165 Cleans up any users and groups that were created by previously
166 running this tool. It is recommended you always clean up after
167 running the tool.
168 -I|--instance-id <id>
170 Use this option to run multiple instances of the tool on the same
171 DC at the same time. This adds a prefix to the test users generated
172 to keep them separate on the DC.
173 -K|--prefer-kerberos
175 Use Kerberos to authenticate the test users.
176 -B|--badpassword-frequency <frequency>
178 Use this option to simulate users trying to authenticate with an
179 incorrect password.
180 --dns-rate <rate>
182 Increase the rate at which DNS packets get sent.
183 -t|--timing-data <file>
185 This writes extra timing data to the file specified. This is mostly
186 used for reporting options, such as generating graphs.
187 Samba Common Options
189 -d|--debuglevel=level
191 level is an integer from 0 to 10. The default value if this
192 parameter is not specified is 1.
193 The higher this value, the more detail will be logged to the
195 log files about the activities of the server. At level 0, only
196 critical errors and serious warnings will be logged. Level 1 is
197 a reasonable level for day-to-day running - it generates a
198 small amount of information about operations carried out.
199 Levels above 1 will generate considerable amounts of log data,
201 and should only be used when investigating a problem. Levels
202 above 3 are designed for use only by developers and generate
203 HUGE amounts of log data, most of which is extremely cryptic.
204 Note that specifying this parameter here will override the log
206 level parameter in the smb.conf file.
207 -s|--configfile=<configuration file>
209 The file specified contains the configuration details required
210 by the server. The information in this file includes
211 server-specific information such as what printcap file to use,
212 as well as descriptions of all the services that the server is
213 to provide. See smb.conf for more information. The default
214 configuration file name is determined at compile time.
215 --option=<name>=<value>
217 Set the smb.conf(5) option "<name>" to value "<value>" from the
218 command line. This overrides compiled-in defaults and options
219 read from the configuration file.
220 --realm=REALM
222 Set the realm name
223 -V|--version
225 Prints the program version number.
226 Credential Options
229 --simple-bind-dn=DN
231 DN to use for a simple bind
232 --password=PASSWORD
234 Password
235 -U USERNAME|--username=USERNAME
237 Username
238 -W WORKGROUP|--workgroup=WORKGROUP
240 Workgroup
241 -k|--kerberos
243 Try to authenticate with kerberos. Only useful in an Active
244 Directory environment.
245 --ipaddress=IPADDRESS
247 IP address of the server
248 -P|--machine-pass
250 Use stored machine account password.
251
254 Generating a traffic-summary file
255 To use this tool, you need either a traffic-summary file or a
256 traffic-model file. To generate either of these files, you will need a
257 packet capture of actual Samba activity on your network.
258 Use Wireshark to take a packet capture on your network of the traffic
260 you want to generate. For example, if you want to simulate lots of
261 users logging on, then take a capture at 8:30am when users are logging
262 in.
263 Next, you need to convert your packet capture into a traffic summary
265 file, using traffic_summary.pl. Basically this removes any sensitive
266 information from the capture and summarizes what type of packet was
267 sent and when.
268 Refer to the traffic_summary.pl --help help for more details, but the
270 basic command will look something like:
271 tshark -r capture.pcapng -T pdml | traffic_summary.pl >
273 traffic-summary.txt
274 Replaying a traffic-summary file
276 Once you have a traffic-summary file, you can use it to generate
277 traffic. The traffic_replay tool gets passed the traffic-summary file,
278 along with the full DNS hostname of the DC being tested. You also need
279 to provide some user credentials, and possibly the Samba realm and
280 workgroup (although the realm and workgroup may be determined
281 automatically, for example from the /etc/smb.conf file, if one is
282 present). E.g.
283 traffic_replay traffic-summary.txt my-dc.samdom.example.com
285 -UAdmin%password -W samdom --realm=samdom.example.com
286 --fixed-password=blahblah123!
287 This simply regenerates Samba activity seen in the traffic summary. The
289 traffic is grouped into 'conversations' between a host and the DC. A
290 user and machine account is created on the DC for each conversation, in
291 order to allow logon and other operations to succeed. The script
292 generates the same types of packets as those seen in the summary.
293 Creating users can be quite a time-consuming process, especially if a
295 lot of conversations are being generated. To save time, the test users
296 remain on the DC by default. You will need to run the --clean-up option
297 to remove them, once you have finished generating traffic. Because the
298 same test users are used across multiple runs of the tool, a consistent
299 password for these users needs to be used - this is specified by the
300 --fixed-password option.
301 The benefit of this tool over simply using tcprelay is that the traffic
303 generated is independent of any specific network. No setup is needed
304 beforehand on the test DC. The traffic no longer contains sensitive
305 details, so the traffic summary could be potentially shared with other
306 Samba developers.
307 However, replaying a traffic-summary directly is somewhat limited in
309 what you can actually do. A more flexible approach is to generate the
310 traffic using a model file.
311 Generating a traffic-model file
313 To create a traffic-model file, simply pass the traffic-summary file to
314 the traffic_learner script. E.g.
315 traffic_learner traffic-summary.txt -o traffic-model.txt
317 This generates a model of the Samba activity in your network. This
319 model-file can now be used to generate traffic.
320 Replaying the traffic-model file
322 Packet generation using a traffic-model file uses the same command as a
323 traffic-summary file, e.g.
324 traffic_replay traffic-model.txt my-dc.samdom.example.com
326 -UAdmin%password
327 By default, this will generate 60 seconds worth of traffic based on the
329 model. You can specify longer using the --duration parameter.
330 The traffic generated is an approximation of what was seen in the
332 network capture. The traffic generation involves some randomness, so
333 running the same command multiple times may result in slightly
334 different traffic being generated.
335 As well as changing how long the model runs for, you can also change
337 how many conversations get generated and how fast the traffic gets
338 replayed. To roughly double the number of conversations that get
339 replayed, use --scale-traffic=2 or to approximately halve the number
340 use --scale-traffic=0.5. To approximately double how quickly the
341 conversations get replayed, use --replay-rate=2, or to halve this use
342 --replay-rate=0.5
343 For example, to generate approximately 10 times the amount of traffic
345 seen over a two-minute period (based on the network capture), use:
346 traffic_replay traffic-model.txt my-dc.samdom.example.com
348 -UAdmin%password --fixed-password=blahblah123! --scale-traffic=10
349 --duration=120
350 Scaling the number of users
352 The performance of a Samba DC running a small subset of test users will
353 be different to a fully-populated Samba DC running in a network. As the
354 number of users increases, the size of the DB increases, and a very
355 large DB will perform worse than a smaller DB.
356 To increase the size of the Samba DB, this tool can also create extra
358 users and groups. These extra users are basically 'filler' for the DB.
359 They won't actually be used to generate traffic, but they may slow down
360 authentication of the test users.
361 For example, to populate the DB with an extra 5000 users (note this
363 will take a while), use the command:
364 traffic_replay my-dc.samdom.example.com -UAdmin%password
366 --generate-users-only --fixed-password=blahblah123!
367 --number-of-users=5000
368 You can also create groups and assign users to groups. The users can be
370 randomly assigned to groups - this includes any extra users created as
371 well as the users that map to conversations. Use either
372 --average-groups-per-user or --group-memberships to specify how many
373 group memberships should be assigned to the test users.
374 For example, to assign the users in the replayed conversations into 10
376 groups on average, use a command like:
377 traffic_replay traffic-model.txt my-dc.samdom.example.com
379 -UAdmin%password --fixed-password=blahblah123! --generate-users-only
380 --number-of-groups=25 --average-groups-per-user=10
381 The users created by the test will have names like STGU-0-xyz. The
383 groups generated have names like STGG-0-xyz.
384
386 This man page is complete for version 4.8.3 of the Samba suite.
387
389 traffic_learner(7).
390
392 The original Samba software and related utilities were created by
393 Andrew Tridgell. Samba is now developed by the Samba Team as an Open
394 Source project similar to the way the Linux kernel is developed.
395 The traffic_replay tool was developed by the Samba team at Catalyst IT
397 Ltd.
398 The traffic_replay manpage was written by Tim Beale.
400Samba 4.8.3 10/30/2018 TRAFFIC_REPLAY(7)