Debian Codegraph @

upstream/mageia-cauldron/man7/traffic_replay.7

raw
1 '\" t
2 .\" Title: traffic_replay
3 .\" Author: [see the "AUTHOR" section]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 05/28/2026
6 .\" Manual: User Commands
7 .\" Source: Samba 4.23.8
8 .\" Language: English
9 .\"
10 .TH "TRAFFIC_REPLAY" "7" "05/28/2026" "Samba 4\&.23\&.8" "User Commands"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 traffic_replay \- Samba traffic generation tool\&.
32 .SH "SYNOPSIS"
33 .HP \w'\ 'u
34 traffic_replay [\-F,\ \-\-fixed\-password\ <test\-password>] [\-T,\ \-\-packets\-per\-second\ <number>] [\-S,\ \-\-scale\-traffic\ <scale\ by\ factor>] [\-r,\ \-\-replay\-rate\ <scale\ by\ factor>] [\-D,\ \-\-duration\ <seconds>] [\-\-traffic\-summary\ <output\ file>] [\-I,\ \-\-instance\-id\ <id>] [\-K,\ \-\-prefer\-kerberos] [\-B,\ \-\-badpassword\-frequency\ <frequency>] [\-\-dns\-rate\ <rate>] [\-t,\ \-\-timing\-data\ <file>] [\-\-random\-seed\ <seed>] [\-U,\ \-\-username\ user] [\-\-password\ <password>] [\-W\ \-\-workgroup\ <workgroup>] [\-\-realm\ <realm>] [\-s,\ \-\-config\-file\ <file>] [\-k,\ \-\-kerberos\ <kerberos>] [\-\-ipaddress\ <address>] [\-P,\ \-\-machine\-pass] [\-\-option\ <option>] [\-d,\ \-\-debuglevel\ <debug\ level>] [\-\-conversation\-persistence\ <0\-1>] [\-\-latency\-timeout\ <seconds>] [\-\-stop\-on\-any\-error] {summary\-file} {dns\-hostname}
35 .HP \w'\ 'u
36 traffic_replay [\-G,\ \-\-generate\-users\-only] [\-F,\ \-\-fixed\-password\ <test\-password>] [\-n,\ \-\-number\-of\-users\ <total\ users>] [\-\-number\-of\-groups\ <total\ groups>] [\-\-average\-groups\-per\-user\ <average\ number>] [\-\-group\-memberships\ <total\ memberships>] [\-\-max\-members\ <group\ size>] {dns\-hostname}
37 .HP \w'\ 'u
38 traffic_replay {\-c|\-\-clean\-up} {dns\-hostname}
39 .HP \w'\ 'u
40 traffic_replay [\-h,\ \-\-help] [\-V,\ \-\-version]
41 .SH "DESCRIPTION"
42 .PP
43 This tool is part of the
44 \fBsamba\fR(7)
45 suite\&.
46 .PP
47 This tool generates traffic in order to measure the performance of a Samba DC, and to test how well Samba will scale as a network increases in size\&. It can simulate multiple different hosts making multiple different types of requests to a DC\&.
48 .PP
49 This tool is intended to run against a dedicated test DC (rather than a live DC that is handling real network traffic)\&.
50 .PP
51 Note that a side\-effect of running this tool is that user accounts will be created on the DC, in order to test various Samba operations\&. As creating accounts can be very time\-consuming, these users will remain on the DC by default\&. To remove these accounts, use the \-\-clean\-up option\&.
52 .SH "OPTIONS"
53 .PP
54 \-h|\-\-help
55 .RS 4
56 Print a summary of command line options\&.
57 .RE
58 .PP
59 summary\-file
60 .RS 4
61 File containing the network traffic to replay\&. This should be a traffic\-model (generated by
62 traffic_learner)\&. Based on this file, this tool will generate \*(Aqconversations\*(Aq which represent Samba activity between a network host and the DC\&.
63 .RE
64 .PP
65 dns\-hostname
66 .RS 4
67 The full DNS hostname of the DC that\*(Aqs being tested\&. The Samba activity in the summary\-file will be replicated and directed at this DC\&. It\*(Aqs recommended that you use a dedicated DC for testing and don\*(Aqt try to run this tool against a DC that\*(Aqs processing live network traffic\&.
68 .RE
69 .PP
70 \-F|\-\-fixed\-password <test\-password>
71 .RS 4
72 Test users are created when this tool is run, so that actual Samba activity, such as authorizing users, can be mimicked\&. This option specifies the password that will be used for any test users that are created\&.
73 .sp
74 Note that any users created by this tool will remain on the DC until you run the \-\-clean\-up option\&. Therefore, the fixed\-password option needs to be the same each time the tool is run, otherwise the test users won\*(Aqt authenticate correctly\&.
75 .RE
76 .PP
77 random\-seed
78 .RS 4
79 A number to seed the random number generator with\&. When traffic is generated from a model\-file, use this option to keep the traffic consistent across multiple test runs\&. This allows you to compare the performance of Samba between different releases\&.
80 .RE
81 .PP
82 Traffic Model Options
83 .RS 4
84 When the summary\-file is a traffic\-model (produced by
85 traffic_learner), use these options to alter the traffic that gets generated\&.
86 .PP
87 \-D|\-\-duration <seconds>
88 .RS 4
89 Specifies the approximate duration in seconds to generate traffic for\&. The default is 60 seconds\&.
90 .RE
91 .PP
92 \-T|\-\-packets\-per\-second <number>
93 .RS 4
94 Generate this many packets per second, regardless of the traffic rate of the sample on which the model was based\&. This cannot be used with
95 \fB\-S\fR\&.
96 .RE
97 .PP
98 \-S|\-\-scale\-traffic <factor>
99 .RS 4
100 Increases the number of conversations by this factor, relative to the original traffic sample on which the model was based\&. This option won\*(Aqt affect the rate at which packets get sent (which is still based on the traffic model), but it will mean more conversations get replayed\&. It cannot be combined with
101 \fB\-T\fR, which sets the traffic rate in a different way\&.
102 .RE
103 .PP
104 \-r|\-\-replay\-rate <factor>
105 .RS 4
106 Replays the traffic faster by this factor\&. This option won\*(Aqt affect the number of packets sent, but it will squeeze them into fewer conversations, which may reduce resource usage\&.
107 .RE
108 .PP
109 \-\-traffic\-summary <output\-file>
110 .RS 4
111 Instead of replaying a traffic\-model, this option generates a traffic\-summary file based on what traffic would be sent\&. Using a traffic\-model allows you to scale the packet rate and number of packets sent\&. However, using a traffic\-model introduces some randomness into the traffic generation\&. So running the same traffic_replay command multiple times using a model file may result in some differences in the actual traffic sent\&. However, running the same traffic_replay command multiple times with a traffic\-summary file will always result in the same traffic being sent\&.
112 .sp
113 For taking performance measurements over several test runs, it\*(Aqs recommended to use this option and replay the traffic from a traffic\-summary file, or to use the \-\-random\-seed option\&.
114 .RE
115 .PP
116 \-\-stop\-on\-any\-error
117 .RS 4
118 Any client error causes the whole run to stop\&.
119 .RE
120 .PP
121 \-\-conversation\-persistence <0\-1>
122 .RS 4
123 Conversation termination (as decided by the model) is re\-interpreted as a long pause with this probability\&.
124 .RE
125 .PP
126 \-\-latency\-timeout <seconds>
127 .RS 4
128 Wait this long at the end of the run for outstanding reply packets\&. The number of conversations that have not finished at the end of the timeout is a failure metric\&.
129 .RE
130 .RE
131 .PP
132 \-\-generate\-users\-only
133 .RS 4
134 Add extra user/groups on the DC to increase the DB size\&. By default, this tool automatically creates test users that map to the traffic conversations being generated\&. This option allows extra users to be created on top of this\&. Note that these extra users may not actually used for traffic generation \- the traffic generation is still based on the number of conversations from the model/summary file\&.
135 .sp
136 Generating a large number of users can take a long time, so it this option allows this to be done only once\&.
137 .sp
138 Note that the users created will remain on the DC until the tool is run with the \-\-clean\-up option\&. This means that it is best to only assign group memberships once, i\&.e\&. run \-\-clean\-up before assigning a different allocation of group memberships\&.
139 .PP
140 \-n|\-\-number\-of\-users <total\-users>
141 .RS 4
142 Specifies the total number of test users to create (excluding any machine accounts required for the traffic)\&. Note that these extra users simply populate the DC\*(Aqs DB \- the actual user traffic generated is still based on the summary\-file\&.
143 .RE
144 .PP
145 \-\-number\-of\-groups <total\-groups>
146 .RS 4
147 Creates the specified number of groups, for assigning the test users to\&. Note that users are not automatically assigned to groups \- use either \-\-average\-groups\-per\-user or \-\-group\-memberships to do this\&.
148 .RE
149 .PP
150 \-\-average\-groups\-per\-user <average\-groups>
151 .RS 4
152 Randomly assigns the test users to the test groups created\&. The group memberships are distributed so that the overall average groups that a user is member of matches this number\&. Some users will belong to more groups and some users will belong to fewer groups\&. This option is incompatible with the \-\-group\-membership option\&.
153 .RE
154 .PP
155 \-\-group\-memberships <total\-memberships>
156 .RS 4
157 Randomly assigns the test users to the test groups created\&. The group memberships are distributed so that the total groups that a user is member of, across all users, matches this number\&. For example, with 100 users and 10 groups, \-\-group\-memberships=300 would assign a user to 3 groups on average\&. Some users will belong to more groups and some users will belong to fewer groups, but the total of all member linked attributes would be 300\&. This option is incompatible with the \-\-average\-groups\-per\-user option\&.
158 .RE
159 .PP
160 \-\-max\-members <group size>
161 .RS 4
162 Limit the largest group to this size, even if the other group options would have it otherwise\&.
163 .RE
164 .RS
165 .sp
166 .RE
167 .RE
168 .PP
169 \-\-clean\-up
170 .RS 4
171 Cleans up any users and groups that were created by previously running this tool\&. It is recommended you always clean up after running the tool\&.
172 .RE
173 .PP
174 \-I|\-\-instance\-id <id>
175 .RS 4
176 Use this option to run multiple instances of the tool on the same DC at the same time\&. This adds a prefix to the test users generated to keep them separate on the DC\&.
177 .RE
178 .PP
179 \-K|\-\-prefer\-kerberos
180 .RS 4
181 Use Kerberos to authenticate the test users\&.
182 .RE
183 .PP
184 \-B|\-\-badpassword\-frequency <frequency>
185 .RS 4
186 Use this option to simulate users trying to authenticate with an incorrect password\&.
187 .RE
188 .PP
189 \-\-dns\-rate <rate>
190 .RS 4
191 Increase the rate at which DNS packets get sent\&.
192 .RE
193 .PP
194 \-t|\-\-timing\-data <file>
195 .RS 4
196 This writes extra timing data to the file specified\&. This is mostly used for reporting options, such as generating graphs\&.
197 .RE
198 .PP
199 Samba Common Options
200 .RS 4
201 .PP
202 \-d|\-\-debuglevel=level
203 .RS 4
204 \fIlevel\fR
205 is an integer from 0 to 10\&. The default value if this parameter is not specified is 1 for client applications\&.
206 .sp
207 The higher this value, the more detail will be logged to the log files about the activities of the server\&. At level 0, only critical errors and serious warnings will be logged\&. Level 1 is a reasonable level for day\-to\-day running \- it generates a small amount of information about operations carried out\&.
208 .sp
209 Levels above 1 will generate considerable amounts of log data, and should only be used when investigating a problem\&. Levels above 3 are designed for use only by developers and generate HUGE amounts of log data, most of which is extremely cryptic\&.
210 .sp
211 Note that specifying this parameter here will override the
212 \m[blue]\fBlog level\fR\m[]
213 parameter in the
214 /etc/samba/smb\&.conf
215 file\&.
216 .RE
217 .PP
218 \-\-debug\-stdout
219 .RS 4
220 This will redirect debug output to STDOUT\&. By default all clients are logging to STDERR\&.
221 .RE
222 .PP
223 \-\-configfile=<configuration file>
224 .RS 4
225 The file specified contains the configuration details required by the client\&. The information in this file can be general for client and server or only provide client specific like options such as
226 \m[blue]\fBclient smb encrypt\fR\m[]\&. See
227 /etc/samba/smb\&.conf
228 for more information\&. The default configuration file name is determined at compile time\&.
229 .RE
230 .PP
231 \-\-option=<name>=<value>
232 .RS 4
233 Set the
234 \fBsmb.conf\fR(5)
235 option "<name>" to value "<value>" from the command line\&. This overrides compiled\-in defaults and options read from the configuration file\&. If a name or a value includes a space, wrap whole \-\-option=name=value into quotes\&.
236 .RE
237 .PP
238 \-\-realm=REALM
239 .RS 4
240 Set the realm name
241 .RE
242 .PP
243 \-V|\-\-version
244 .RS 4
245 Prints the program version number\&.
246 .RE
247 .RS
248 .sp
249 .RE
250 .RE
251 .PP
252 Credential Options
253 .RS 4
254 .PP
255 \-\-simple\-bind\-dn=DN
256 .RS 4
257 DN to use for a simple bind
258 .RE
259 .PP
260 \-\-password=PASSWORD
261 .RS 4
262 Password
263 .RE
264 .PP
265 \-U USERNAME|\-\-username=USERNAME
266 .RS 4
267 Username
268 .RE
269 .PP
270 \-W WORKGROUP|\-\-workgroup=WORKGROUP
271 .RS 4
272 Workgroup
273 .RE
274 .PP
275 \-\-use\-kerberos=desired|required|off
276 .RS 4
277 This parameter determines whether Samba client tools will try to authenticate using Kerberos\&. For Kerberos authentication you should use DNS names instead of IP addresses when connecting to a service\&. By default Samba client tools will try to use the default Kerberos credential cache (ccache)\&. In case the ccache does not exist or \-U|\-\-user option was specified, clients will ask to enter a password and will obtain a Kerberos ticket (kinit) for you\&. If you want to use an alternative Kerberos credentical cache, use the \-\-use\-krb5\-ccache option\&.
278 .sp
279 Note that specifying this parameter here will override the
280 \m[blue]\fBclient use kerberos\fR\m[]
281 parameter in the
282 /etc/samba/smb\&.conf
283 file\&.
284 .RE
285 .PP
286 \-\-ipaddress=IPADDRESS
287 .RS 4
288 IP address of the server
289 .RE
290 .PP
291 \-P|\-\-machine\-pass
292 .RS 4
293 Use stored machine account password\&.
294 .RE
295 .RS
296 .sp
297 .RE
298 .RE
299 .SH "OPERATIONS"
300 .SS "Generating a traffic\-summary file"
301 .PP
302 To use this tool, you need either a traffic\-summary file or a traffic\-model file\&. To generate either of these files, you will need a packet capture of actual Samba activity on your network\&.
303 .PP
304 Use Wireshark to take a packet capture on your network of the traffic you want to generate\&. For example, if you want to simulate lots of users logging on, then take a capture at 8:30am when users are logging in\&.
305 .PP
306 Next, you need to convert your packet capture into a traffic summary file, using
307 traffic_summary\&.pl\&. Basically this removes any sensitive information from the capture and summarizes what type of packet was sent and when\&.
308 .PP
309 Refer to the
310 traffic_summary\&.pl \-\-help
311 help for more details, but the basic command will look something like:
312 .PP
313 tshark \-r capture\&.pcapng \-T pdml | traffic_summary\&.pl > traffic\-summary\&.txt
314 .SS "Replaying a traffic\-summary file"
315 .PP
316 Once you have a traffic\-summary file, you can use it to generate traffic\&. The traffic_replay tool gets passed the traffic\-summary file, along with the full DNS hostname of the DC being tested\&. You also need to provide some user credentials, and possibly the Samba realm and workgroup (although the realm and workgroup may be determined automatically, for example from the /etc/smb\&.conf file, if one is present)\&. E\&.g\&.
317 .PP
318 traffic_replay traffic\-summary\&.txt my\-dc\&.samdom\&.example\&.com \-UAdmin%password \-W samdom \-\-realm=samdom\&.example\&.com \-\-fixed\-password=blahblah123!
319 .PP
320 This simply regenerates Samba activity seen in the traffic summary\&. The traffic is grouped into \*(Aqconversations\*(Aq between a host and the DC\&. A user and machine account is created on the DC for each conversation, in order to allow logon and other operations to succeed\&. The script generates the same types of packets as those seen in the summary\&.
321 .PP
322 Creating users can be quite a time\-consuming process, especially if a lot of conversations are being generated\&. To save time, the test users remain on the DC by default\&. You will need to run the \-\-clean\-up option to remove them, once you have finished generating traffic\&. Because the same test users are used across multiple runs of the tool, a consistent password for these users needs to be used \- this is specified by the \-\-fixed\-password option\&.
323 .PP
324 The benefit of this tool over simply using tcprelay is that the traffic generated is independent of any specific network\&. No setup is needed beforehand on the test DC\&. The traffic no longer contains sensitive details, so the traffic summary could be potentially shared with other Samba developers\&.
325 .PP
326 However, replaying a traffic\-summary directly is somewhat limited in what you can actually do\&. A more flexible approach is to generate the traffic using a model file\&.
327 .SS "Generating a traffic\-model file"
328 .PP
329 To create a traffic\-model file, simply pass the traffic\-summary file to the
330 traffic_learner
331 script\&. E\&.g\&.
332 .PP
333 traffic_learner traffic\-summary\&.txt \-o traffic\-model\&.txt
334 .PP
335 This generates a model of the Samba activity in your network\&. This model\-file can now be used to generate traffic\&.
336 .SS "Replaying the traffic\-model file"
337 .PP
338 Packet generation using a traffic\-model file uses the same command as a traffic\-summary file, e\&.g\&.
339 .PP
340 traffic_replay traffic\-model\&.txt my\-dc\&.samdom\&.example\&.com \-UAdmin%password
341 .PP
342 By default, this will generate 60 seconds worth of traffic based on the model\&. You can specify longer using the \-\-duration parameter\&.
343 .PP
344 The traffic generated is an approximation of what was seen in the network capture\&. The traffic generation involves some randomness, so running the same command multiple times may result in slightly different traffic being generated (although you can avoid this, by specifying the \-\-random\-seed option)\&.
345 .PP
346 As well as changing how long the model runs for, you can also change how many conversations get generated and how fast the traffic gets replayed\&. To roughly double the number of conversations that get replayed, use \-\-scale\-traffic=2 or to approximately halve the number use \-\-scale\-traffic=0\&.5\&. To approximately double how quickly the conversations get replayed, use \-\-replay\-rate=2, or to halve this use \-\-replay\-rate=0\&.5
347 .PP
348 For example, to generate approximately 10 times the amount of traffic seen over a two\-minute period (based on the network capture), use:
349 .PP
350 traffic_replay traffic\-model\&.txt my\-dc\&.samdom\&.example\&.com \-UAdmin%password \-\-fixed\-password=blahblah123! \-\-scale\-traffic=10 \-\-duration=120
351 .SS "Scaling the number of users"
352 .PP
353 The performance of a Samba DC running a small subset of test users will be different to a fully\-populated Samba DC running in a network\&. As the number of users increases, the size of the DB increases, and a very large DB will perform worse than a smaller DB\&.
354 .PP
355 To increase the size of the Samba DB, this tool can also create extra users and groups\&. These extra users are basically \*(Aqfiller\*(Aq for the DB\&. They won\*(Aqt actually be used to generate traffic, but they may slow down authentication of the test users\&.
356 .PP
357 For example, to populate the DB with an extra 5000 users (note this will take a while), use the command:
358 .PP
359 traffic_replay my\-dc\&.samdom\&.example\&.com \-UAdmin%password \-\-generate\-users\-only \-\-fixed\-password=blahblah123! \-\-number\-of\-users=5000
360 .PP
361 You can also create groups and assign users to groups\&. The users can be randomly assigned to groups \- this includes any extra users created as well as the users that map to conversations\&. Use either \-\-average\-groups\-per\-user or \-\-group\-memberships to specify how many group memberships should be assigned to the test users\&.
362 .PP
363 For example, to assign the users in the replayed conversations into 10 groups on average, use a command like:
364 .PP
365 traffic_replay traffic\-model\&.txt my\-dc\&.samdom\&.example\&.com \-UAdmin%password \-\-fixed\-password=blahblah123! \-\-generate\-users\-only \-\-number\-of\-groups=25 \-\-average\-groups\-per\-user=10
366 .PP
367 The users created by the test will have names like STGU\-0\-xyz\&. The groups generated have names like STGG\-0\-xyz\&.
368 .SH "VERSION"
369 .PP
370 This man page is complete for version 4\&.23\&.8 of the Samba suite\&.
371 .SH "SEE ALSO"
372 .PP
373 \fBtraffic_learner\fR(7)\&.
374 .SH "AUTHOR"
375 .PP
376 The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&.
377 .PP
378 The traffic_replay tool was developed by the Samba team at Catalyst IT Ltd\&.
379 .PP
380 The traffic_replay manpage was written by Tim Beale\&.