'\" t
.TH "PG3" "8" "" "iputils s20180629" "iputils"
.\" -----------------------------------------------------------------
.\" * 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"
pg3, ipg, pgset \- send stream of UDP packets
.SH "SYNOPSIS"
.HP \w'\fBsource\fR\ 'u
\fBsource\fR \fIipg\fR
.br

.HP \w'\fBpg\fR\ 'u
\fBpg\fR
.br

.HP \w'\fBpgset\fR\ 'u
\fBpgset\fR \fICOMMAND\fR
.br

.SH "DESCRIPTION"
.PP
\fBipg\fR
is not a program, it is script which should be sourced to
\fBbash\fR\&. When sourced it loads module
\fIpg3\fR
and exports a few of functions accessible from parent shell\&. These macros are
\fBpg\fR
to start packet injection and to get the results of run; and
\fBpgset\fR
to setup packet generator\&.
.PP
\fBpgset\fR
can send the following commands to module
\fIpg3\fR:
.SH "COMMAND"
.PP
\fBodev \fR\fIDEVICE\fR
.RS 4
Name of Ethernet device to test\&. See warning below\&.
.RE
.PP
\fBpkt_size \fR\fIBYTES\fR
.RS 4
Size of packet to generate\&. The size includes all the headers: UDP, IP, MAC, but does not account for overhead internal to medium, i\&.e\&. FCS and various paddings\&.
.RE
.PP
\fBfrags \fR\fINUMBER\fR
.RS 4
Each packet will contain
\fINUMBER\fR
of fragments\&. Maximal amount for linux\-2\&.4 is 6\&. Far not all the devices support fragmented buffers\&.
.RE
.PP
\fBcount \fR\fINUMBER\fR
.RS 4
Send stream of
\fINUMBER\fR
of packets and stop after this\&.
.RE
.PP
\fBipg \fR\fITIME\fR
.RS 4
Introduce artificial delay between packets of
\fITIME\fR
microseconds\&.
.RE
.PP
\fBdst \fR\fIIP_ADDRESS\fR
.RS 4
Select IP destination where the stream is sent to\&. Beware, never set this address at random\&.
\fBpg3\fR
is not a toy, it creates really tough stream\&. Default value is 0\&.0\&.0\&.0\&.
.RE
.PP
\fBdst \fR\fIMAC_ADDRESS\fR
.RS 4
Select MAC destination where the stream is sent to\&. Default value is 00:00:00:00:00:00 in hope that this will not be received by any node on LAN\&.
.RE
.PP
\fBstop\fR
.RS 4
Abort packet injection\&.
.RE
.SH "WARNING"
.PP
When output device is set to some random device different of hardware Ethernet device,
\fBpg3\fR
will crash kernel\&.
.PP
Do not use it on VLAN, ethertap, VTUN and other devices, which emulate Ethernet not being real Ethernet in fact\&.
.SH "AUTHOR"
.PP
\fBpg3\fR
was written by Robert Olsson <robert\&.olsson@its\&.uu\&.se>\&.
.SH "SECURITY"
.PP
This can be used only by superuser\&.
.PP
This tool creates floods of packets which is unlikely to be handled even by high\-end machines\&. For example, it saturates gigabit link with 60 byte packets when used with Intel\*(Aqs e1000\&. In face of such stream switches, routers and end hosts may deadlock, crash, explode\&. Use only in test lab environment\&.
.SH "AVAILABILITY"
.PP
\fBpg3\fR
is part of
\fIiputils\fR
package\&.
