docs: networking: convert pktgen.txt to ReST

   operstates

   packet_mmap

   phonet

   pktgen

.. only::  subproject and html

.. SPDX-License-Identifier: GPL-2.0

====================================

HOWTO for the linux packet generator

                  ------------------------------------

====================================

Enable CONFIG_NET_PKTGEN to compile and build pktgen either in-kernel

or as a module.  A module is preferred; modprobe pktgen if needed.  Once

Monitoring and controlling is done via /proc.  It is easiest to select a

suitable sample script and configure that.

On a dual CPU:

On a dual CPU::

    ps aux | grep pkt

    root       129  0.3  0.0     0    0 ?        SW    2003 523:20 [kpktgend_0]

    root       130  0.3  0.0     0    0 ?        SW    2003 509:50 [kpktgend_1]

For monitoring and control pktgen creates:

For monitoring and control pktgen creates::

	/proc/net/pktgen/pgctrl

	/proc/net/pktgen/kpktgend_X

	/proc/net/pktgen/ethX

The default NIC settings are (likely) not tuned for pktgen's artificial

overload type of benchmarking, as this could hurt the normal use-case.

Specifically increasing the TX ring buffer in the NIC:

Specifically increasing the TX ring buffer in the NIC::

 # ethtool -G ethX tx 1024

A larger TX ring can improve pktgen's performance, while it can hurt

and the cleanup interval is affected by the ethtool --coalesce setting

of parameter "rx-usecs".

For ixgbe use e.g. "30" resulting in approx 33K interrupts/sec (1/30*10^6):

For ixgbe use e.g. "30" resulting in approx 33K interrupts/sec (1/30*10^6)::

 # ethtool -C ethX rx-usecs 30

Pktgen creates a thread for each CPU with affinity to that CPU.

Which is controlled through procfile /proc/net/pktgen/kpktgend_X.

Example: /proc/net/pktgen/kpktgend_0

Example: /proc/net/pktgen/kpktgend_0::

 Running:

 Stopped: eth4@0

Most important are the devices assigned to the thread.

The two basic thread commands are:

 * add_device DEVICE@NAME -- adds a single device

 * rem_device_all         -- remove all associated devices

The Params section holds configured information.  The Current section

holds running statistics.  The Result is printed after a run or after

interruption.  Example:

interruption.  Example::

    /proc/net/pktgen/eth4@0

This is done via the /proc interface, and most easily done via pgset

as defined in the sample scripts.

You need to specify PGDEV environment variable to use functions from sample

scripts, i.e.:

scripts, i.e.::

    export PGDEV=/proc/net/pktgen/eth4@0

    source samples/pktgen/functions.sh

Examples:

Examples::

 pg_ctrl start           starts injection.

 pg_ctrl stop            aborts injection. Also, ^C aborts generator.

samples/pktgen directory. The helper parameters.sh file support easy

and consistent parameter parsing across the sample scripts.

Usage example and help:

Usage example and help::

 ./pktgen_sample01_simple.sh -i eth4 -m 00:1B:21:3C:9D:F8 -d 192.168.8.2

Usage: ./pktgen_sample01_simple.sh [-vx] -i ethX

Usage:::

  ./pktgen_sample01_simple.sh [-vx] -i ethX

  -i : ($DEV)       output interface/device (required)

  -s : ($PKT_SIZE)  packet size

  -d : ($DEST_IP)   destination IP

interface/device parameter "-i" sets variable $DEV.  Copy the

pktgen_sampleXX scripts and modify them to fit your own needs.

The old scripts:

The old scripts::

    pktgen.conf-1-2                  # 1 CPU 2 dev

    pktgen.conf-1-1-rdos             # 1 CPU 1 dev w. route DoS

Enable IPsec

============

Default IPsec transformation with ESP encapsulation plus transport mode

can be enabled by simply setting:

can be enabled by simply setting::

    pgset "flag IPSEC"

    pgset "flows 1"

Current commands and configuration options

==========================================

** Pgcontrol commands:

**Pgcontrol commands**::

    start

    stop

    reset

** Thread commands:

**Thread commands**::

    add_device

    rem_device_all

** Device commands:

**Device commands**::

    count

    clone_skb

References:

ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/

ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/examples/

- ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/

- tp://robur.slu.se/pub/Linux/net-development/pktgen-testing/examples/

Paper from Linux-Kongress in Erlangen 2004.

ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/pktgen_paper.pdf

- ftp://robur.slu.se/pub/Linux/net-development/pktgen-testing/pktgen_paper.pdf

Thanks to:

Grant Grundler for testing on IA-64 and parisc, Harald Welte,  Lennert Buytenhek

Stephen Hemminger, Andi Kleen, Dave Miller and many others.

	  what was just said, you don't need it: say N.

	  Documentation on how to use the packet generator can be found

	  at <file:Documentation/networking/pktgen.txt>.

	  at <file:Documentation/networking/pktgen.rst>.

	  To compile this code as a module, choose M here: the

	  module will be called pktgen.

 * Integrated to 2.5.x 021029 --Lucio Maciel (luciomaciel@zipmail.com.br)

 *

 * 021124 Finished major redesign and rewrite for new functionality.

 * See Documentation/networking/pktgen.txt for how to use this.

 * See Documentation/networking/pktgen.rst for how to use this.

 *

 * The new operation:

 * For each CPU one thread/process is created at start. This process checks

This directory contains some pktgen sample and benchmark scripts, that

can easily be copied and adjusted for your own use-case.

General doc is located in kernel: Documentation/networking/pktgen.txt

General doc is located in kernel: Documentation/networking/pktgen.rst

Helper include files

====================