Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 380 insertions, 0 deletions

diff --git a/upstream/archlinux/man7/traffic_replay.7 b/upstream/archlinux/man7/traffic_replay.7
new file mode 100644
index 00000000..997495c9
--- /dev/null
+++ b/upstream/archlinux/man7/traffic_replay.7
@@ -0,0 +1,380 @@
+'\" 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\&.