Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
APPLABEL(1)		     Yet Another Flowmeter		   APPLABEL(1)

NAME
       yaf application labeling

DESCRIPTION
       yaf can examine packet payloads and determine the application protocol
       in use within a flow, and export	a 16-bit application label with	each
       flow if yaf is built with application labeler support (using the
       --enable-applabel option	to ./configure when yaf	is built).

       The exported application	label uses the common port number for the
       protocol.  For example, HTTP Traffic, independent of what port the
       traffic is detected on, will be labeled with a value of 80, the default
       HTTP port.  Labels and rules are	taken from a configuration file	read
       by yaf at startup time.	This rule file can be given on the command
       line with the --applabel-rules option or	will try to be read from the
       default location	of /usr/local/etc/yafApplabelRules.conf.  If yaf was
       installed in a nonstandard location, it may be necessary	to set the
       LTDL_LIBRARY_PATH environment variable to the location of the
       application label plugins.  By default, yaf installs the	application
       labeling	plugins	in /usr/local/lib/yaf.

       Application labeling requires payload capture to	be enabled with	the
       --max-payload option.  A	minimum	payload	capture	length of 384 bytes is
       recommended for best results.

       Application labeling is presently experimental, and not guaranteed to
       be 100% accurate.  However, application labels are supported in yafscii
       and SiLK	via rwflowpack,	flowcap, and rwipfix2silk.

CONFIG FILE FORMAT
       The yafApplabelRules.conf file is the main source of information	by
       which yaf determines application	labels,	and is required	for
       application labeling support.  By default, this file is located in
       /usr/local/etc/yafApplabelRules.conf.

       The file	is a list of label statements.	A label	statement begins with
       the keyword 'label', and	has the	following form:

	label <N> <label-rule>

       where <N> is the	application label to apply (an unsigned	16-bit decimal
       integer in the range 0 to 65535), and <label-rule> specifies how	to
       recognize the given application protocol.  There	are three types	of
       label rules supported: regex, plugin, and signature.

       A '#' symbol starts a comment in	the rule file, and the rest of the
       line is a comment.

   Rule	Types
       Regular Expression Rules
	   Regular Expression rules have the following form:

	    label <N> regex <expression>

	   The regular expression is compared against the available payload of
	   the flow, and is a PCRE regular expression (see PCRE	documentation
	   for details).  The expression is undelimited, and continues until
	   the end of the line.	<N> should be the well-known port of the
	   protocol you	are trying to detect with the <expression>.  The
	   regular expression is stored	along with the application label <N>
	   and will be compared	first against the forward payload with source
	   or destination port matching	<N>.  For example, if a	flow has a
	   destination port of 80, it will first be matched against the
	   regular expression associated with application label	80.  If	a
	   match does not occur, it starts at the beginning of the
	   configuration file and proceeds down	the list until it either finds
	   a match or all options have been tried.  If no match	has occurred,
	   it will repeat the previous steps with the reverse payload.	For
	   this	reason,	<N> should be the well-known port of the protocol.  If
	   the expression matches, the label <N> is applied to the flow.

       Plugin Rules
	   Plugin rules	are used to label application payload using a
	   dynamically loaded library, written in C, and have the following
	   form:

	    label <N> plugin <library> <function name> <arg-list>

	   where <library> is the name of the dynamically loadable library
	   that	exists somewhere within	the LD_LIBRARY_PATH, the
	   LTDL_LIBRARY_PATH, or a system library path,	without	the library
	   extension name (usually .so); <function> is the name	of the
	   function to call within the library;	and the	optional <arg-list> is
	   a space-separated list of arguments that will be passed as the argc
	   and argv parameters to that function.  See the source code to the
	   plugins included with yaf for details on the	specific protocol
	   implementations.  Similar to	regular	expression rules, <N> should
	   be the well-known port of the application you are trying to detect
	   because the plugin is first executed	on flows which have a  source
	   or destination port matching	<N>.  The label	<N> is applied to a
	   flow	if the flow passes all the requirements	specified in the
	   plugin.

       Signature Rules
	   Signatures are the newest addition to the application labeling
	   feature in yaf.  Regular expression rules that only search for some
	   expression, regardless of port, have	the following form:

	    label <N> signature	<expression>

	   The <expression> is compared	against	the available payload of the
	   flow.  All signature	regular	expressions are	compared before	port-
	   based matching begins.  The <expression> should be a	PCRE Regular
	   expression.	The expression is undelimited, and continues until the
	   end of the line.  If	the expression matches,	the label <N> is
	   applied to the flow,	and port-based matching	will not execute.  For
	   example, if you want	to label flows that have the phrase "foo bar"
	   with	application label 9876,	you would add the following to the
	   yafApplabelRules.conf file:

	    label 9876 signature foo bar

MISCELLANEOUS
       Regardless of rule type,	each rule should have a	unique application
       label.  Note that once a	match is found,	application labeling will not
       continue	to find	a "better" match.  Therefore, the order	of the rules
       in the configuration file can make a difference.	 More common protocols
       should be listed	at the beginning of the	configuration file to increase
       efficiency.  Regular expressions	specifically crafted for reverse
       payloads	are not	recommended; unless there is no	chance that they will
       match another protocol in the list.  This issue may be addressed	in a
       later release.  Be aware	that poorly crafted regular expressions	can be
       detrimental to the efficiency of	the software.

       Since signature rule labels are usually not a well-known	port, they
       will be compared	against	the payload in the same	order as they appear
       in the configuration file.

       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 before the Certificate exchange.	To accurately label https
       traffic,	uncomment the following	line in	the yafApplabelRules.conf
       file:

       label <N> plugin	proxyplugin proxyplugin_LTX_ycProxyScanScan

       and set <N> to the port on which	the proxy is listening for
       connections.  This will not label https flows as	<N>.  It will set the
       application label to 443	and will allow the DPI plugin to capture and
       export X.509 Certificates.

LABELS
       *NETBIOS	is not included	in the configuration file.  It is contained in
       the DNS decoder due to its similarites with the DNS Protocol.

       **RTCP is not included in the configuration file.  It is	contained in
       the RTP decoder due to similarities in the protocols.

AUTHORS
       CERT Network Situational	Awareness Group	Engineering Team,
       http://www.cert.org/netsa

SEE ALSO
       yaf(1), yafscii(1)

2.11.0				  22-Sep-2021			   APPLABEL(1)

NAME | DESCRIPTION | CONFIG FILE FORMAT | MISCELLANEOUS | LABELS | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=applabel&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help