
[[ga-flow-support-classification-engine]]
= Flows Classification
:description: Learn more about the {page-component-title} classification engine that helps improve flows management through rules filters that group flows.

For improved flows management, {page-component-title} uses a classification engine that applies predefined and user-defined rules to filter and classify flows.
The included predefined rules are based on the https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml[IANA Service Name and Transport Protocol Port Number Registry].

You can group flows by a combination of parameters: source/destination port, source/destination address, IP protocol, and exporter filter.
Once set up, you can view classification groups on the home page.
Use classification to help you determine how the flows associated with a particular appliance, service, or other component affect your network (for example, all YouTube traffic or all flows to port 80 marked as `http`).

To classify a flow, you must define a rule.
A rule includes at least a name for the classified flows and additional parameters that must match for successful classification.

Use the Classification UI to define new rules:

. Click menu:Administration[Configure OpenNMS] in the side menu, then click menu:Flow Management[Manage Flow Classification]

== Flows classification example

Assume that you define the following rules:

[options="header"]
[cols="1,1,1,1,1,1,1"]
|===
| name
| srcAddress
| srcPort
| dstAddress
| dstPort
| protocol
| exporterFilter

| OpenNMS
|
|
| 10.0.0.1
| 8980
| tcp
|

| http
|
|
|
| 80,8980,8080,9000
| tcp
|

| https
|
|
|
| 443
|
|

| Exporters
|
|
|
|
|
| categoryName == 'Exporters'
|===

{page-component-title} receives the following flows, classified according to the rules defined above:

[options="header"]
[cols="3,1"]
|===
| Flow
| Classification

| protocol: tcp, +
  srcAddress: 10.0.0.5, srcPort: 60123, +
  dstAddress: 54.246.188.65, dstPort: 80, +
  exporterAddress: 10.0.0.55
| http

| protocol: tcp, +
  srcAddress: 10.0.0.5, srcPort: 60123, +
  dstAddress: 54.246.188.65, dstPort: 443, +
  exporterAddress: 10.0.0.55
| https

| protocol: tcp, +
  srcAddress: 10.0.0.5, srcPort: 60123, +
  dstAddress: 10.0.0.1, dstPort: 8980, +
  exporterAddress: 10.0.0.55
| OpenNMS

|===

== Create a flows classification rule

A flows classification rule must include at least a name and one definition for source/destination port, source/destination address, IP protocol, or exporter filter.

By default, rules that a user creates appear in the "user-defined rules" group.
You can <<rule-groups, create other groups>> as needed and assign rules to those groups.

. Click menu:Administration[Configure OpenNMS] in the side menu, then click menu:Flow Management[Manage Flow Classification]
. In the *User-defined Rules* tab, click the plus sign.
. Type a name for the rule in the *Application Name* field.
. Specify a value in at least one of the following fields:
+
[cols="1,3"]
|===
| Source IP Address
| The source IP address of the flow to match.
May include wildcard characters (for example, asterisks (*)) to define a dynamic range of IP addresses that can be matched.

| Source Port
| The source port of the flow to match.
May be a range or list of ports; for example, 80,8080,8980, or 8000-9000.

| Destination IP Address
| The destination IP address of the flow to match.
May include wildcard characters (for example, asterisks (*)) to define a dynamic range of IP addresses that can be matched.

| Destination Port
| The destination port of the flow to match.
May be a range or list of ports; for example, 80,8080,8980, or 8000-9000.

| Exporter Filter
| The exporter of the flow (device/observation point) must match this criteria.
This parameter supports all capabilities of the {page-component-title} xref:reference:configuration/filters/filters.adoc[Filters API].

| IP Protocol
| The IP protocol of the flow to match.
|===

. Mark the rule as omnidirectional to evaluate it with interchanged endpoint addresses and ports.
+
This classifies related traffic that matches the classification in the same way.

. Click *Create*.

Note that when you have more than one user-defined rule, in the *Position* field, you can specify the order you want the classification engine to evaluate the rule within its group.
Lower numbers are evaluated first (0 > 1 > 2).
By default, the *Position* field increments the number with each new rule.
(The classification engine would evaluate the rules based on the order in which you create them.)
See <<evaluation-order, order of evaluation>>.

[[rule-groups]]
== Rule groups

Each rule is associated with a rule group.
The default user groups are "user-defined rules" and "pre-defined rules".
You can add, edit, and delete groups.
Note that you cannot edit or delete the "pre-defined" group or its rules.

To add a rule group, follow these steps:

. Click menu:Administration[Configure OpenNMS] in the side menu, then click *Manage Flow Classification*.
. In the *Settings* tab, click the plus sign.
. In the *Position* field, choose a number for the order you want the group to be evaluated.
+
Evaluation order goes from lowest number to highest (0>1>2).

. Type a name and description in the appropriate fields and click *Create*.

If you originally created a rule in the user-defined rules group, you can edit that rule to assign it to a different group.

== Verify rule configuration

To verify that a complex set of rules is configured correctly, navigate to the classification UI (menu:Gears icon[Flow Management > Manage Flow Classification]) and select the test classification icon (magic wand) in the top right.

Define values in the screen and click *Classify*.
(You are basically crafting an IP packet by hand.)

This simulates sending a flow to the classification engine.

If the configuration is correct, the name of the associated rule appears in the bottom left of the *Test Classification* dialog:

image::flows/test-classification.png[classify,300]

[[evaluation-order]]
== Order of evaluation

Rules and groups each have a position in the order of evaluation.
The classification engine evaluates lower positions first.
The position of a rules group is more important than the rule's position within its group.
The pre-defined group is always evaluated last.

Drag and drop or edit the *Position* field in the group/rules dialogs to change the positions of rules.

An example of an evaluation:

[options="header"]
[cols="1,2,1,2"]
|===
| Group Position
| Group
| Rule Position
| Rule

| 1
| group 1
| 1
| rule 1.1

| 1
| group 1
| 2
| rule 1.2

| 1
| group 1
| 3
| rule 1.3

| 1
| group 1
| 4
| rule 1.4

| 2
| group 2
| 1
| rule 2.1

| 2
| group 2
| 2
| rule 2.2

| 2
| group 2
| 3
| rule 2.3

| 2
| group 2
| 4
| rule 2.4

| 3
| group 3
| 1
| rule 3.1

| 3
| group 3
| 2
| rule 3.2
|===
