path: root/upstream/archlinux/man7/traffic_replay.7

'\" t
.\"     Title: traffic_replay
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 02/19/2024
.\"    Manual: User Commands
.\"    Source: Samba 4.19.5
.\"  Language: English
.\"
.TH "TRAFFIC_REPLAY" "7" "02/19/2024" "Samba 4\&.19\&.5" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
traffic_replay \- Samba traffic generation tool\&.
.SH "SYNOPSIS"
.HP \w'\ 'u
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}
.HP \w'\ 'u
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}
.HP \w'\ 'u
traffic_replay {\-c|\-\-clean\-up} {dns\-hostname}
.HP \w'\ 'u
traffic_replay [\-h,\ \-\-help] [\-V,\ \-\-version]
.SH "DESCRIPTION"
.PP
This tool is part of the
\fBsamba\fR(7)
suite\&.
.PP
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\&.
.PP
This tool is intended to run against a dedicated test DC (rather than a live DC that is handling real network traffic)\&.
.PP
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\&.
.SH "OPTIONS"
.PP
\-h|\-\-help
.RS 4
Print a summary of command line options\&.
.RE
.PP
summary\-file
.RS 4
File containing the network traffic to replay\&. This should be a traffic\-model (generated by
traffic_learner)\&. Based on this file, this tool will generate \*(Aqconversations\*(Aq which represent Samba activity between a network host and the DC\&.
.RE
.PP
dns\-hostname
.RS 4
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\&.
.RE
.PP
\-F|\-\-fixed\-password <test\-password>
.RS 4
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\&.
.sp
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\&.
.RE
.PP
random\-seed
.RS 4
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\&.
.RE
.PP
Traffic Model Options
.RS 4
When the summary\-file is a traffic\-model (produced by
traffic_learner), use these options to alter the traffic that gets generated\&.
.PP
\-D|\-\-duration <seconds>
.RS 4
Specifies the approximate duration in seconds to generate traffic for\&. The default is 60 seconds\&.
.RE
.PP
\-T|\-\-packets\-per\-second <number>
.RS 4
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
\fB\-S\fR\&.
.RE
.PP
\-S|\-\-scale\-traffic <factor>
.RS 4
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
\fB\-T\fR, which sets the traffic rate in a different way\&.
.RE
.PP
\-r|\-\-replay\-rate <factor>
.RS 4
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\&.
.RE
.PP
\-\-traffic\-summary <output\-file>
.RS 4
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\&.
.sp
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\&.
.RE
.PP
\-\-stop\-on\-any\-error
.RS 4
Any client error causes the whole run to stop\&.
.RE
.PP
\-\-conversation\-persistence <0\-1>
.RS 4
Conversation termination (as decided by the model) is re\-interpreted as a long pause with this probability\&.
.RE
.PP
\-\-latency\-timeout <seconds>
.RS 4
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\&.
.RE
.RE
.PP
\-\-generate\-users\-only
.RS 4
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\&.
.sp
Generating a large number of users can take a long time, so it this option allows this to be done only once\&.
.sp
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\&.
.PP
\-n|\-\-number\-of\-users <total\-users>
.RS 4
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\&.
.RE
.PP
\-\-number\-of\-groups <total\-groups>
.RS 4
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\&.
.RE
.PP
\-\-average\-groups\-per\-user <average\-groups>
.RS 4
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\&.
.RE
.PP
\-\-group\-memberships <total\-memberships>
.RS 4
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\&.
.RE
.PP
\-\-max\-members <group size>
.RS 4
Limit the largest group to this size, even if the other group options would have it otherwise\&.
.RE
.RS
.sp
.RE
.RE
.PP
\-\-clean\-up
.RS 4
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\&.
.RE
.PP
\-I|\-\-instance\-id <id>
.RS 4
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\&.
.RE
.PP
\-K|\-\-prefer\-kerberos
.RS 4
Use Kerberos to authenticate the test users\&.
.RE
.PP
\-B|\-\-badpassword\-frequency <frequency>
.RS 4
Use this option to simulate users trying to authenticate with an incorrect password\&.
.RE
.PP
\-\-dns\-rate <rate>
.RS 4
Increase the rate at which DNS packets get sent\&.
.RE
.PP
\-t|\-\-timing\-data <file>
.RS 4
This writes extra timing data to the file specified\&. This is mostly used for reporting options, such as generating graphs\&.
.RE
.PP
Samba Common Options
.RS 4
.PP
\-d|\-\-debuglevel=DEBUGLEVEL
.RS 4
\fIlevel\fR
is an integer from 0 to 10\&. The default value if this parameter is not specified is 1 for client applications\&.
.sp
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\&.
.sp
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\&.
.sp
Note that specifying this parameter here will override the
\m[blue]\fBlog level\fR\m[]
parameter in the
/etc/samba/smb\&.conf
file\&.
.RE
.PP
\-\-debug\-stdout
.RS 4
This will redirect debug output to STDOUT\&. By default all clients are logging to STDERR\&.
.RE
.PP
\-\-configfile=<configuration file>
.RS 4
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
\m[blue]\fBclient smb encrypt\fR\m[]\&. See
/etc/samba/smb\&.conf
for more information\&. The default configuration file name is determined at compile time\&.
.RE
.PP
\-\-option=<name>=<value>
.RS 4
Set the
\fBsmb.conf\fR(5)
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\&.
.RE
.PP
\-\-realm=REALM
.RS 4
Set the realm name
.RE
.PP
\-V|\-\-version
.RS 4
Prints the program version number\&.
.RE
.RS
.sp
.RE
.RE
.PP
Credential Options
.RS 4
.PP
\-\-simple\-bind\-dn=DN
.RS 4
DN to use for a simple bind
.RE
.PP
\-\-password=PASSWORD
.RS 4
Password
.RE
.PP
\-U USERNAME|\-\-username=USERNAME
.RS 4
Username
.RE
.PP
\-W WORKGROUP|\-\-workgroup=WORKGROUP
.RS 4
Workgroup
.RE
.PP
\-\-use\-kerberos=desired|required|off
.RS 4
This parameter determines whether Samba client tools will try to authenticate using Kerberos\&. For Kerberos authentication you need to use dns names instead of IP addresses when connecting to a service\&.
.sp
Note that specifying this parameter here will override the
\m[blue]\fBclient use kerberos\fR\m[]
parameter in the
/etc/samba/smb\&.conf
file\&.
.RE
.PP
\-\-ipaddress=IPADDRESS
.RS 4
IP address of the server
.RE
.PP
\-P|\-\-machine\-pass
.RS 4
Use stored machine account password\&.
.RE
.RS
.sp
.RE
.RE
.SH "OPERATIONS"
.SS "Generating a traffic\-summary file"
.PP
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\&.
.PP
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\&.
.PP
Next, you need to convert your packet capture into a traffic summary file, using
traffic_summary\&.pl\&. Basically this removes any sensitive information from the capture and summarizes what type of packet was sent and when\&.
.PP
Refer to the
traffic_summary\&.pl \-\-help
help for more details, but the basic command will look something like:
.PP
tshark \-r capture\&.pcapng \-T pdml | traffic_summary\&.pl > traffic\-summary\&.txt
.SS "Replaying a traffic\-summary file"
.PP
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\&.
.PP
traffic_replay traffic\-summary\&.txt my\-dc\&.samdom\&.example\&.com \-UAdmin%password \-W samdom \-\-realm=samdom\&.example\&.com \-\-fixed\-password=blahblah123!
.PP
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\&.
.PP
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\&.
.PP
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\&.
.PP
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\&.
.SS "Generating a traffic\-model file"
.PP
To create a traffic\-model file, simply pass the traffic\-summary file to the
traffic_learner
script\&. E\&.g\&.
.PP
traffic_learner traffic\-summary\&.txt \-o traffic\-model\&.txt
.PP
This generates a model of the Samba activity in your network\&. This model\-file can now be used to generate traffic\&.
.SS "Replaying the traffic\-model file"
.PP
Packet generation using a traffic\-model file uses the same command as a traffic\-summary file, e\&.g\&.
.PP
traffic_replay traffic\-model\&.txt my\-dc\&.samdom\&.example\&.com \-UAdmin%password
.PP
By default, this will generate 60 seconds worth of traffic based on the model\&. You can specify longer using the \-\-duration parameter\&.
.PP
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)\&.
.PP
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
.PP
For example, to generate approximately 10 times the amount of traffic seen over a two\-minute period (based on the network capture), use:
.PP
traffic_replay traffic\-model\&.txt my\-dc\&.samdom\&.example\&.com \-UAdmin%password \-\-fixed\-password=blahblah123! \-\-scale\-traffic=10 \-\-duration=120
.SS "Scaling the number of users"
.PP
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\&.
.PP
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\&.
.PP
For example, to populate the DB with an extra 5000 users (note this will take a while), use the command:
.PP
traffic_replay my\-dc\&.samdom\&.example\&.com \-UAdmin%password \-\-generate\-users\-only \-\-fixed\-password=blahblah123! \-\-number\-of\-users=5000
.PP
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\&.
.PP
For example, to assign the users in the replayed conversations into 10 groups on average, use a command like:
.PP
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
.PP
The users created by the test will have names like STGU\-0\-xyz\&. The groups generated have names like STGG\-0\-xyz\&.
.SH "VERSION"
.PP
This man page is complete for version 4\&.19\&.5 of the Samba suite\&.
.SH "SEE ALSO"
.PP
\fBtraffic_learner\fR(7)\&.
.SH "AUTHOR"
.PP
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\&.
.PP
The traffic_replay tool was developed by the Samba team at Catalyst IT Ltd\&.
.PP
The traffic_replay manpage was written by Tim Beale\&.