This page explains the service features included with YAF.
When running yaf(1) as a service, YAF must read data from a live capture device such as a network interface. The IPFIX data created by YAF must either be written to collector listening on a network socket or stored in rotating output files.
systemd
On systems that support it, systemd is an option for managing yaf services (as of YAF 2.16.0). The implementation of yaf as a systemd service is intended to provide an easy transition for those migrating from the SysV init.d service implementation.
When running a yaf service for the first time, you must first modify the configuration file, yaf.conf, with relevant parameters for your intended use. If you are upgrading from a previous version of yaf, your configuration file will have persisted during the upgrade. The yaf.conf file is typically found in /etc. See below for additional details regarding this file.
Once the configuration file is completed, starting yaf as a service is the same as starting any other systemd service:
# systemctl start yaf.service
Checking the service's status and stopping the service are also typical:
# systemctl status yaf.service
and:
# systemctl stop yaf.service
To have yaf start automatically when the system is booted, run
# systemctl enable yaf.service
Should you have trouble using systemctl to start YAF, know the following: When systemctl is used to start (or restart) YAF, a shell script is invoked to read the yaf.conf file and start yaf. That shell script is typically installed at /usr/libexec/yaf/yaf_startup.
Instantiated Services
With systemd functionality comes the ability to start a yaf service as an instance, with a unique configuration per instance.
To start YAF as an instantiated service, you must create a unique configuration file in the configuration file directory. The config file should be named yaf.foo.conf where foo is the name you want to give your instantiated service. Once this is done, you can start the instantiated service by passing your service name.
For example:
# systemctl start yaf@foo.service
starts an instantiated service using the configuration file yaf.foo.conf.
init.d
For systems that do not support systemd, the SysV init.d service script is still available, however this capability is not present when installing via rpm.
(For YAF 2.15.0 or earlier, the init.d capability is installed by the rpm and administrators should follow the instructions in this section.)
Running a yaf service using init.d is very similar to using systemd. The yaf.conf configuration file (described below must be configured prior to first use with the parameters you want the service to use. The configuration file is typically located in /etc.
Once your configuration file is complete, you can start the yaf service using the following command:
# service yaf start
You can stop the service or check its status using:
# service yaf stop
and
# service yaf status
The init.d service has one additional feature that does not exist in systemd: dumpstats. This sends a signal to the service telling it write its collection statistics to the yaf log, and the service continues to run. The command has no effect if yaf is not running. It can be called using the command:
# service yaf dumpstats
One can mimic the instantiated services of systemd by creating a configuration file /etc/yaf-foo.conf and either copying or linking /etc/init.d/yaf to /etc/init.d/yaf-foo.
# ln /etc/init.d/yaf /etc/init.d/yaf-foo
Running
# service yaf-foo start
will use the configuration settings in /etc/yaf-foo.conf. This approach should only be used on systems which do not support systemd, and it is not forward-compatible with systemd.
yaf.conf
The yaf.conf configuration file sets shell variables that customize the command line options passed to yaf when systemctl ACTION yaf.service or service yaf ACTION is invoked. This file typically resides in /etc or PREFIX/etc, where PREFIX is the installation prefix specified when YAF was built.
(For documentation on the Lua-based configuration file used as an argument to yaf --config, see the yaf.init manual page).
When using instantiated services for yaf@foo, the configuration file will be named yaf.foo.conf. When mimicking instantiated services with init.d, the configuration file will be named yaf-foo.conf.
Predefined Variables
When yaf.conf is read, the following shell variables are defined:
PROGRAM_NAME
The name of the program (without any directory prefix). This is most likely yaf, but may be different if --program-prefix or --program-suffix was specified when YAF was built.
INSTANCE_SUFFIX
If this file is loaded via systemctl start yaf@foo.service, this is set to .foo (with the leading dot).
If this file is loaded via service yaf-bar start where yaf-bar is a script in /etc/init.d/yaf-bar, the INSTANCE_SUFFIX is -bar (with the leading hyphen).
Enabling the Configuration
The YAF start-up script will ignore the configuration file unless the ENABLED variable is set to a non-empty value. If this is not set, the start-up scripts quietly exit.
# Must be non-empty to start YAF ENABLED=1
Setting Program Paths
The default values of these variables should be fine for most installations.
PROGRAM_PATH
The complete path to the program to start. It defaults to PREFIX/bin/${PROGRAM_NAME}.
LTDL_LIBRARY_PATH
The library load path tells YAF where to find the plug-ins used for application labeling and DPI, and it is set before reading this file. If you set PROGRAM_PATH, you may need to modify this value too.
YAF_STATEDIR
The path to state location directory, which is used to set YAF_LOG and YAF_PIDFILE later in this file. It default to PREFIX/var.
Upgrading Note: Prior to YAF-2.18, YAF_STATEDIR was set before the yaf.conf file was read. As of YAF-2.18 that is no longer true. If you wish to use YAF_STATEDIR in the yaf.conf file (particularly when upgrading from an older YAF), you must set it explicitly.
Configuring Live Capture
The live capture type and interface must be specified. The pcap type is always available; other types may be available depending on the features enabled when YAF was built. Check the output of yaf --version.
For a list of pcap interfaces available on your system, run ifconfig -a or tcpdump --list-interfaces.
# Live capture type YAF_CAP_TYPE=pcap # Live capture interface: loopback on linux YAF_CAP_IF=lo
Exporting Over the Network
To export IPFIX over the network, set the name of the host to receive the data, the IP protocol to use for sending, and optionally the network port where the collector is listening. If the port is not set, YAF writes data to 4739, the IANA-assigned port for IPFIX.
# IPFIX transport protocol YAF_IPFIX_PROTO=tcp # Hostname or IP address of IPFIX collector YAF_IPFIX_HOST=localhost # Port where the collector is listening (default 4739) YAF_IPFIX_PORT=4739
Exporting to Rotating Files
To export IPFIX to rotating output files, first set YAF_IPFIX_PROTO to an empty value or comment it out.
#YAF_IPFIX_PROTO=tcp
For file rotation, YAF takes a single value that specifies the directory and the prefix for files in that directory. Set YAF_ROTATE_LOCATION to that directory and file prefix.
# This creates files named "yaf-TIMESTAMP-SEQNUM.yaf" in the directory # /var/data/ipfix, where TIMESTAMP is a timestamp and SEQNUM is a five # digit sequence number. YAF_ROTATE_LOCATION=/var/data/ipfix/yaf
Alternatively, to specify the directory and file prefix separately, use this configuration (make certain YAF_ROTATE_LOCATION is set as it is the only value the start-up scripts use):
YAF_ROTATE_DIR=/var/data/ipfix
YAF_ROTATE_PREFIX=yaf
YAF_ROTATE_LOCATION="${YAF_ROTATE_DIR}/${YAF_ROTATE_PREFIX}"
If you are running YAF as an instantiated service, consider using the INSTANCE_SUFFIX variable as part of the output location. If YAF is started with systemctl start yaf@foo.service, the following writes data to files named yaf.foo-TIMESTAMP-SEQNUM.yaf.
YAF_ROTATE_DIR=/var/data/ipfix
YAF_ROTATE_PREFIX=yaf${INSTANCE_SUFFIX}
YAF_ROTATE_LOCATION="${YAF_ROTATE_DIR}/${YAF_ROTATE_PREFIX}"
By default, YAF rotates files every 120 seconds. To change how often files are rotated set YAF_ROTATE_TIME.
YAF_ROTATE_TIME=120
Customizing Logging
By default, if the ${YAF_STATEDIR}/log directory exists, YAF writes its log messages to ${YAF_STATEDIR}/log/${PROGRAM_NAME}${INSTANCE_SUFFIX}.log; otherwise, YAF attempts to use PREFIX/var/log/${PROGRAM_NAME}${INSTANCE_SUFFIX}.log. If neither exists, the start-up script exits with an error.
To customize the log destination, set YAF_LOG to the complete path. To write the messages to syslog, specify a syslog facility as described in the syslog(3) manual page or journalctl --facility=help.
# Write messages to the "user" syslog facility YAF_LOG=user
When using a SysV init.d-style startup, YAF_PIDFILE specifies the complete path to the file where the process ID of the running yaf process is stored. The default location is ${YAF_STATEDIR}/run/${PROGRAM_NAME}${INSTANCE_SUFFIX}.pid. As with the log-file setting, if the ${YAF_STATEDIR}/run directory does not exist, YAF uses PREFIX/var/run/${PROGRAM_NAME}${INSTANCE_SUFFIX}.pid. If neither exists, the start-up script exits with an error.
# Either not needed (systemd) or leave blank to use the default YAF_PIDFILE=
Enabling Other Features
YAF normally needs root access to read from the network interface. To have YAF drop privileges and use a different user ID after it connects to the interface, set YAF_USER to the user to become.
# Become this user after start-up YAF_USER=
Any other settings (e.g., application labeling, deep packet inspection, SiLK mode), are enabled by adding the yaf command line options to YAF_EXTRAFLAGS.
# Enable deep packet inspection YAF_EXTRAFLAGS="--applabel --plugin-name dpacketplugin --max-payload=4096"
Reference Copies
As of YAF-2.18, reference copies of all the start-up files are installed under PREFIX/share/yaf. When YAF is installed via an RPM, the systemd files are installed in their correct locations. For other systems, move these required files into the appropriate location to use them.
PREFIX/share/yaf/lib/systemd/system/yaf.service
Reference copy of systemd unit file for the YAF service.
PREFIX/share/yaf/lib/systemd/system/yaf@.service
Reference copy of systemd unit file for YAF instantiated services.
PREFIX/share/yaf/libexec/yaf/yaf_startup
Reference copy of the yaf_startup script referenced by the systemd unit files for YAF.
PREFIX/share/yaf/etc/init.d/yaf
Reference copy of the SysV init.d-style start-up script.
PREFIX/share/yaf/etc/yaf.conf
Reference copy of the yaf.conf file.
PREFIX/share/yaf/yaf.init
Reference copy of the Lua-based configuration file, yaf.init, to use as the argument to yaf --config yaf.init.
