FreeBSD Manual Pages
APPLABEL(1) Yet Another Flowmeter APPLABEL(1) NAME applabel - yaf application labeling SYNOPSIS yaf --applabel --max-payload=MAX_PAYLOAD [--applabel-rules=FILE] ... DESCRIPTION yaf(1) can examine a flow record's packet payloads, determine the applica- tion protocol in use within the flow, and export a 16-bit application label (often called an applabel) with each flow. (This feature must be enabled when yaf is built by supplying the --enable-applabel option to the config- ure script.) The exported application label typically uses the assigned or common port number for the protocol. For example, if yaf determines a flow contains HTTP traffic, yaf assigns an applabel of 80 (the default HTTP port) for the flow independent of what ports the flow record contains. Labels and rules are taken from a configuration file read by yaf at startup time. The location of the rule file may be given on the command line using the --applabel-rules option. If the location is not specified, yaf at- tempts to read it from the default location of /usr/local/etc/yaf/yafAppla- belRules.conf. The application labeling system also uses compiled plug-ins (dynamically loaded libraries) that yaf must load. If yaf is unable to find these plug-ins, it may be necessary to set the LTDL_LIBRARY_PATH envi- ronment variable to the location of the application label plugins. yaf in- stalls the application labeling plugins in /usr/local/lib/yaf/yaf. Application labeling examines the payload of the flow records, and it re- quires payload capture to be enabled with the --max-payload option. A min- imum payload capture length of 384 bytes is recommended for best results. Application labeling is not guaranteed to be 100% accurate. Application labels are supported in other tools in the NetSA suite, including yaf- scii(1), super_mediator(1), and SiLK via rwflowpack(8), flowcap(8), and rwipfix2silk(1). CONFIGURATION FILE FORMAT The yafApplabelRules.conf file is the source of information by which yaf determines application labels, and the file is required for application la- beling support. The file's default location is set during installation; for this installation, the file is /usr/local/etc/yaf/yafApplabel- Rules.conf. The file may contain comments, blank lines, label statements, and port statements. Comments and Blank Lines A '"#"' symbol starts a comment in the rules file, and the rest of the line is a comment. The comment and any whitespace that precedes it is ignored. Comments must appear on their own line; they are not recognized if they ap- pear after another keyword. Example: "# this is a comment" A completely empty line or a line containing only whitespace is considered a blank line and is ignored. Label Statements A label statement begins with the keyword '"label"', and has the following format: label APP { regex | plugin | signature } LABEL-RULE-ARGUMENTS where * APP is a unsigned 16-bit decimal integer (in the range 1 to 65535) and usually represents the application label to set in the flow record. * regex, plugin, or signature is the rule type and specifies how to recog- nize the given application protocol. * LABEL-RULE-ARGUMENTS are additional arguments that depend on the rule type. The APP value must be unique across all regex and plugin rules, and it is recommended, but not required, that it also be unique across signature rules. Rule Execution Once a label is assigned to a flow record, the application labeling process stops; there is no attempt to find a "better" match. The signature rule tests are performed first in the order they appear in the configuration file (regardless of where they appear in the file), and these rules are tested against both the forward and reverse payload. If a rule matches, the applabel is assigned and no other rules are tested. If none of the signature rules match, the regex rule and plugin rule tests are checked. These are port-based tests: If the source or destination port of a flow record matches a rule's APP value (see also "Port Statements" be- low), that rule's test is performed. If the test passes, yaf assigns an applabel to the flow record and no other rules are tested. For application protocols that use common ports (such as HTTP on port 80), the APP used in the rule should the common port. This helps yaf run the most-like-to-succeed test first and improve performance. If the port-specific test fails or if the flow's ports do not match a spe- cific rule, yaf begins testing the record against the regex and plugins rules in the order they appear in the configuration file regardless of type. If a rule succeeds, an applabel is assigned to the record and pro- cessing stops. The order of the regex and plugin rules makes a difference. More common protocols (especially if known to run on arbitrary ports) should be speci- fied earlier in the file to increase efficiency. Rules that have few false positives and use simple regular expressions or heuristics should also ap- pear closer to the beginning of the file. For regex and plugin rules, the rules are executed first using the forward payload. If no applabel is assigned, the rules are then executed using the reverse payload. As of YAF-2.18, if --applabel-check-early=OCTETS is used, yaf tests the payload for a given direction once the captured payload in that direction reaches OCTETS octets. Regex Rules A label statement that uses a regex (regular expression) rule has the the following form: label APP regex EXPRESSION where * APP is the label to assign to the record, and records that use APP as their source or destination port check this rule first. * EXPRESSION is a PCRE2 <https://www.pcre.org/> regular expression (see pcre2pattern(1). Note that EXPRESSION is not delimited: it is separated from the regex keyword by whitespace and continues to the end of the line. The APP value must be unique across all regex and plugin rules. The rule is ignored if it uses a previously defined label. The EXPRESSION is compared against the available application payload for one direction of the flow. If the expression matches, the label APP is ap- plied to the flow and the labeling process stops. Regular expressions specifically crafted for reverse payloads are not rec- ommended unless there is no chance they will match another protocol. Be aware that poorly crafted regular expressions can be detrimental to the ef- ficiency of the software. For example, the regex rule to match HTTP traffic is label 80 regex HTTP/\d where the final '"\d"' matches any decimal digit (0-9). Plugin Rules A plugin rule label statement examines a flow record's application payload using a dynamically loaded library, written in C. Its syntax is label APP plugin LIBRARY FUNCTION-NAME [ ARG [ ARG... ] ] where * APP tells yaf that flow records that use that port should rule this test first * LIBRARY is the name of the dynamically loadable library that exists some- where within the LD_LIBRARY_PATH, the LTDL_LIBRARY_PATH, or a system li- brary path, without the library extension name (typically ".so") * FUNCTION-NAME is the name of the function to call within the library * [ARG [ARG...]] represents an optional, space-separated list of arguments that are passed to the function in the style of the "argc" and "argv" pa- rameters to a C program's main() function The APP value must be unique across all plugin and regex rules. The rule is ignored if it uses a previously defined label. During the application labeling process, yaf calls FUNCTION-NAME with the flow record and either its forward or reverse payload as arguments (plus any ARG values specified in the yafApplabelRules.conf file). If FUNCTION-NAME returns 0, no applabel is assigned. Any other return value (except 1) becomes the applabel assigned to the flow, and the appli- cation labeling process stops. This allows a single plugin to identify multiple protocols. A return value of 1 tells yaf to use the APP value specific in the yafApplabelRules.conf file, but this feature is deprecated as it does not interoperate well with early payload detection (--appla- bel-check-early). See the source code to the plugins included with yaf for details on the specific protocol implementations. The plugin rule to match TLS traffic is label 443 plugin tlsplugin tlsplugin_LTX_ycTlsScanScan where "tlsplugin" refers to the dynamic library (likely named tlsplugin.so and compiled from the C source file tlsplugin.c), and "tlsplu- gin_LTX_ycTlsScanScan" is a function defined in that file. Signature Rules The syntax of a signature rule label statement is similar to a regex rule: label APP signature EXPRESSION where EXPRESSION is a PCRE2 <https://www.pcre.org/> regular expression and it is not delimited: it is separated from the signature keyword by white- space and continues to the end of the line. yaf checks whether EXPRESSION matches either the forward or reverse application payload of a flow record and assigns the label APP to the flow if a match is found. Signature rules differ from Regex Rules in that they are tested before the other rules and the flow's ports are not considered: yaf tests a flow's payload with all the signature rules' regular expressions in the order the rules appear in the configuration file, stopping if a match is found. Multiple signature rules may use the same APP value, and a signature rule's APP value may also be used by a regex or plugin rule. For example, to apply the applabel 9876 to flow records that have the phrase "foo bar" anywhere within the application payload, add the following to the yafApplabelRules.conf file: label 9876 signature foo bar Port Statements As of YAF-2.19, the port statement allows one to provide additional hints to yaf that traffic on a particular port is likely to match a particular applabel. The syntax of the port statement is port PORT label APP where PORT is a port number present on the flow record and APP is a previ- ously defined label-regex rule or label-plugin rule. The PORT value must be unique among all port statements, and it may not duplicate an APP value in a previous label-regex statement or label-plugin statement. As mentioned in the "Rule Execution" section above, for port-based tests yaf uses the rule's APP number (e.g., 443 for TLS) as a hint that if a flow record's source or destination port matches that value (443), yaf should first check whether the record's payload matches the rule for that protocol (TLS). The port statement extends this to tell yaf that traffic on additional ports should also first be checked against a particular rule. For example, port 993 is typically used by IMAPS (IMAP over TLS). To tell yaf to run the TLS test first on a flow record using port 993, specify this in the yafApplabelRules.conf file: port 993 label 443 Port statements are useful in three instances: 1. When the common port is not the assigned port, such as IRC using port 6667 instead of the IANA-assigned port 194. 2. When the same protocol is used by services on multiple ports, such as the IMAPS example above. 3. When multiple protocols use common plugin code, such as the DNS-plugin recognizing DNS (port 53), NetBIOS (137), MDNS (5353), and LLMNR (5355). Proxy Traffic If yaf is seeing traffic behind a web proxy, it may incorrectly label https (443) traffic as http (80) due to the HTTP Connect method that occurs be- fore the certificate exchange. To accurately label https traffic, uncom- ment the following line in the yafApplabelRules.conf file: label APP plugin proxyplugin proxyplugin_LTX_ycProxyScanScan and set APP to the port on which the proxy is listening for connections. This does label https flows as APP; instead It sets the application label to 443 and allows the DPI plugin to capture and export X.509 Certificates. DEFINED LABELS As of YAF-2.19, the following application labels are enabled by default. They are presented in alphabetical order. Application Protocol AppLabel Since YAF Notes ======================== ======== ========= ===== AIM 5190 2.0.0 BGP 179 2.0.0 BitTorrent 6881 2.5.0 DHCP 67 2.0.0 DNP 3.0 20000 2.5.0 DNS 53 1.x Ethernet/IP 44818 2.5.0 FTP 21 1.x Gh0st RAT 9997 2.7.0 Gnutella 6346 1.x HTTP 80 1.x IKEv2 500 2.12.2 IMAP 143 1.x IRC 194 1.x 1 Jabber XMPP 5222 2.2.0 LDAP 389 2.6.0 LDP 646 2.5.0 LLMNR 5355 2.18.0 2 MDNS 5353 2.18.0 2 MEGACO 2944 2.3.0 MGCP 2427 2.3.0 MQTT 1883 2.12.2 MSNP 1863 2.2.0 MSOffice Update 2223 2.2.0 Modbus 502 2.5.0 MySQL 3306 1.x NNTP 119 1.x NTP 123 2.9.0 NETBIOS 137 2.0.0 2 NETBIOS Datagram Service 138 2.7.0 POP3 110 1.x PPTP 1723 1.x Palevo 65533 2.3.0 Poison Ivy 65534 2.3.0 QUIC 51443 2.12.2 RDP 3389 2.12.2 RSYNC 873 1.x RTCP 5005 2.2.0 3 RTP 5004 2.2.0 RTSP 554 1.x SIP 5060 1.x SLP 427 1.x SMB 139 2.0.0 SMTP 25 1.x SNMP 161 2.0.0 SOCKS 1080 2.0.0 SSH 22 1.x TFTP 69 1.x TLS/SSL 443 1.x Teredo 3544 1.x VMware Server Console 902 2.4.0 VNC 5900 2.1.0 Yahoo Messenger 5050 1.x Notes: 1. IRC servers typically run on port 6667 but 194 is the port assigned by IANA 2. LLMNR, MDNS, and NETBIOS are not included in the configuration file. They are contained in the DNS decoder due to their similarities with the DNS Protocol. 3. RTCP is not included in the configuration file. It is contained in the RTP decoder due to similarities in the protocols. SEE ALSO yaf(1), yafdpi(1), yafscii(1), rwipfix2silk(1), rwflowpack(8), flowcap(8), <https://www.pcre.org/>, pcre2pattern(3) or pcre2pattern <https://www.pcre.org/current/doc/html/pcre2pattern.html> 2.19.3 4-Aug-2026 APPLABEL(1)
NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION FILE FORMAT | DEFINED LABELS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=applabel&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>