YAFZCBALANCE(1)

NAME
yafzcbalance - PF_RING ZC Load balancer for YAF.

SYNOPSIS
    yafzcbalance [--in DEVICE]
                 [--cluster CLUSTER_ID]
                 [--num NUM_YAFS]
                 [--core CORE_ID]
                 [--time TIME_CORE_ID]
                 [--pidfile FILENAME]
                 [--daemon]
                 [--log LOG_FILE]
                 [--user BECOME_USER]
                 [--stats SECONDS]
                 [--version]

DESCRIPTION
yafzcbalance is a tool that load balances packets received on one or more interfaces to multiple consumer processes. This process hashes the incoming packets and sends them to the appropriate yaf(1) process listening on a cluster ID/queue.

yafzcbalance is based off of the example application, zbalance_ipc, that is distributed with PF_RING. Changes have been made to simplify the process to run specifically with yaf(1).

yafzcbalance allows you to bind the application to a particular core. Additionally, you can bind the time pulse thread to the same or another core.

yafzcbalance or a similar application is required for running yaf on zc interfaces. yaf simply listens on a cluster ID, not on the zc interface. This application will listen on the interface(s) and distribute packets to the appropriate cluster.

OPTIONS
The following options are available for yafzcbalance.

--in DEVICE
    The DEVICE is a comma-separated list of devices. Typically when the device is in zero-copy mode, each device name will be in the form zc:<device_name>.

--cluster CLUSTER_ID
    CLUSTER_ID is the unique ID for the PF_RING cluster. All applications belonging to the same cluster can share incoming packets in zero-copy. There can be multiple queues within a cluster that can be used for filtering and distributing packets towards multiple applications.

--num NUM_YAFS
    NUM_YAFS is the number of yaf(1) applications that yafzcbalance will distribute packets to. The default is 1.

--core CORE_ID
    Bind yafzcbalance to core CORE_ID.

--time TIME_CORE_ID
    By default, hardware timestamps are disabled in zero-copy mode. yaf(1) requires that a packet have a timestamp, so yafzcbalance creates a thread that will add a timestamp to the PF_RING packet header. Use this option to bind that thread to core TIME_CORE_ID.

--pidfile PID_FILE
    PID_FILE is the complete path to write the process ID of yafzcbalance.

--daemon
    Run yafzcbalance as a daemon.

--log LOG_FILE
    Write any log messages and process statistics to LOG_FILE. By default, process statistics are disabled. To turn on periodic process statistics, use the --stats option. Otherwise, you can send yafzcbalance the SIGUSR1 process signal to write process statistics to the LOG_FILE or stdout if --log is not present.

--user BECOME_USER
    After opening the live capture device, drop privilege to the named user BECOME_USER.

--stats SECONDS
    If present, yafzcbalance will write process statistics to the LOG_FILE or stdout every SECONDS seconds. yafzcbalance will write the per-interface statistics.

--version
    If present, print version and copyright information to standard error and exit.

Examples
In the following examples, the dollar sign ("$") represents the shell prompt. The text after the dollar sign represents the command line.

 $ yafzcbalance --in zc:p6p1,zc:p6p1 -c 99 -n 2 -d -l /var/log/yafzcbalance.log

 $ yaf --in 99:0 --live zc --out localhost --ipfix tcp --ipfix-port=18000 --silk

 $ yaf --in 99:1 --live zc --out localhost --ipfix tcp --ipfix-port=18001 --silk

Known Issues
yafzcbalance will not start if yaf is already running on the cluster. If you see this error message:

    *** cluster recovery not supported ***
    pfring_zc_create_cluster error [Operation not supported]Please check your hugetlb configuration

Terminate the yaf processes and restart yafzcbalance. yafzcbalance must start before yaf.

Bug reports may be sent directly to the Network Situational Awareness team at <netsa-help@cert.org>.

AUTHORS
Emily Sarneso and the CERT Network Situational Awareness Group Engineering Team, <http://www.cert.org/netsa>.

SEE ALSO
yaf(1)