diff options
Diffstat (limited to 'net/samba419/files/man/traffic_replay.7')
| -rw-r--r-- | net/samba419/files/man/traffic_replay.7 | 380 |
1 files changed, 0 insertions, 380 deletions
diff --git a/net/samba419/files/man/traffic_replay.7 b/net/samba419/files/man/traffic_replay.7 deleted file mode 100644 index a6599ce143bf..000000000000 --- a/net/samba419/files/man/traffic_replay.7 +++ /dev/null @@ -1,380 +0,0 @@ -'\" t -.\" Title: traffic_replay -.\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> -.\" Date: 08/09/2022 -.\" Manual: User Commands -.\" Source: Samba 4.16.4 -.\" Language: English -.\" -.TH "TRAFFIC_REPLAY" "7" "08/09/2022" "Samba 4\&.16\&.4" "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 -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 -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 connnecting to a service\&. -.sp -Note that specifying this parameter here will override the -\m[blue]\fBclient use kerberos\fR\m[] -parameter in the -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\&.16\&.4 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\&. |