The nmeta policy configures how nmeta works with data plane traffic. This includes traffic classification rules, what classifiers are used, in what order and what actions are taken.
The policy is designed as a tree with many first level branches and only a shallow depth.
Nmeta ships with a default policy in the YAML file:
Do not edit the default policy as it will be overwritten by nmeta updates.
Create Your Own Policy¶
Create your own policy by copying the default file to this location:
(note the user directory)
If a main_policy.yaml file is present in the user directory it will completely override the default policy. Note that a user-defined main policy file will not be part of the git distribution, as it is excluded in the .gitignore file.
TC Branch - Rules¶
The traffic classification policy is based off a root key tc_rules. This root contains a ruleset name (only one ruleset supported at this stage), which in turn contains one or more rules. Rules contain conditions and these in turn contain classifiers, as per the following diagram:
Rules are an ordered list (denoted by preceding dash). Each rule contains:
- A comment to describe the purpose of the rule (optional). A comment must start with the attribute comment: and any single-line string can follow
- Match Type
A match_type is one of:
- Match if any of the conditions in the rule match
- Match only if all of the conditions in the rule match
- Match only if none of the conditions in the rule match
- Conditions List
- A list that contains one or more condition stanzas that each contain a match type and a classifiers_list containing one or more classifiers.
- A single actions stanza that contains one or more actions
Example simple traffic classification policy with a single rule:
A condition contains:
- A match type, which is one of:
- Match if any of the classifiers in the condition match
- Match only if all of the classifiers in the condition match
- Match only if none of the classifiers in the condition match.
- A classifiers_list containing one or more classifiers (see further below)
An actions stanza contains one or more attribute/value pairs
Here is a more complex traffic classification policy:
Conditions invoke classifiers. There are three types of classifier supported:
- Custom (Payload / Statistical / Multi-classifier)
TC Branch - Static Classifiers¶
Static classifiers match on attributes in packet headers, or on environmental attributes such as port numbers.
Supported attributes are:
Logical location (as defined by policy) of switch/port
Time of day range (matches if flow start time is in this time range)
Note that range can extend through midnight and times are in 24 hour format
Ethernet source MAC address.
Ethernet destination MAC address.
Ethernet type. Can be in hex (starting with 0x) or decimal.
Examples:eth_type: 0x0800eth_type: 35020
IP source address. Can be a single address, a network with a mask in CIDR notation, or an IP range with two addresses separated by a hyphen. Both addresses in a range must be the same type, and the second address must be higher than the first.
Examples:ip_src: 192.168.56.12ip_src: 192.168.56.0/24ip_src: 192.168.56.12-192.168.56.31
IP destination address. Can be a single address, a network with a mask in CIDR notation, or an IP range with two addresses separated by a hyphen. Both addresses in a range must be the same type, and the second address must be higher than the first.
Examples:ip_dst: 192.168.57.40ip_dst: 192.168.57.0/24ip_dst: 192.168.57.36-192.168.78.31
TCP source port.
TCP destination port.
UDP source port.
UDP destination port.
TC Branch - Identity Classifiers¶
All identity classifiers are prefixed with:
LLDP systemname may be matched as a regular expression. The match pattern must be contained in single quotes. For example, to match system names of *.audit.example.com, add this policy condition:
Supported attributes are:
Exact match against a system name discovered via LLDP. Example:
Regular expression match against a system name discovered via LLDP. Example:
Exact match against a host name discovered via DHCP (option 12). Example:
Regular expression match against a host name discovered via DHCP (option 12). Example:
Exact match of either IP address in a flow against a DNS domain. Example:
Regular expression match of either IP address in a flow against a DNS domain. Example:
TC Branch - Custom Classifiers¶
Nmeta supports the creation of custom classifiers.
All custom classifiers have the attribute:
The value determines the custom .py file to load from the nmeta/classifiers directory
For example, the following condition loads a custom classifier file
TC Branch - Actions¶
Actions are specific to a rule, and define what nmeta should do when the rule is matched. Multiple actions can be defined on a rule.
Supported attributes are:
Drop the packet
No flow modification or packet-out will occur. The packet will however appear in metadata and does add load to the controller.
Values can be:
A drop action with ‘at_controller_and_switch’ value will install a flow entry with no actions (which implicitly drops) onto the switch that sent the matching packet to the controller. Be aware that nmeta will generate a fine-grained match for this drop rule that may not align with what is specified in the policy. It builds the rule based on the classified packet and will do a match on IPs & TCP or UDP destination port for TCP or UDP or IPs for other IP traffic. It will not apply a rule for non-IP traffic.
Specify QoS treatment for flow.
Values can be:
Set description for the flow. This is a convenience for humans.
Example:set_desc: "This is a flow type description"
QoS Treatment Branch¶
Quality of Service (QoS) treatment parameters are configured in main policy under the qos_treatment root directive. They map qos action values to queue numbers. Example:
qos_treatment: # Control Quality of Service (QoS) treatment mapping of # names to output queue numbers: default_priority: 0 constrained_bw: 1 high_priority: 2 low_priority: 3
The QoS queue numbers are arbitrary and are used to map packets and flows to queues that have been configured on the switch (separate to nmeta).
Port Sets Branch¶
Port Sets are used to abstract a set of switches/ports so that they can be referenced elsewhere in the policy. Port Sets are located under the root key port_sets.
port_sets: # Port Sets control what data plane ports policies and # features are applied on. Names must be unique. port_set_list: - name: port_set_location_internal port_list: - name: VirtualSwitch1-internal DPID: 8796748549206 ports: 1-3,5,66 vlan_id: 0 - name: VirtualSwitch2-internal DPID: 255 ports: 3,5 vlan_id: 0
In this example, the port set port_set_location_internal refers to specific ports on the switches with DPIDs of 8796748549206 and 255.
Locations are a policy-defined aspect of an identity that are based on the source or destination DPID/port, which is looked up against a list that links location names to port sets.
Locations are located under the root key locations.
A default location must be defined.
locations: # Locations are logical groupings of ports. Takes first match. locations_list: - name: internal port_set_list: - port_set: port_set_location_internal - name: external port_set_list: - port_set: port_set_location_external default_match: unknown
A YAML file holds the system configuration. You wouldn’t normally need to change this file from the defaults. It allows you to change values like timers, database sizing and logging levels.
It’s location is:
These default configuration parameters can be overwritten by creating a file:
Add the parameters to the file that you want to override. For example, to override the default console logging level for the tc_policy module, add the following line to the user config file:
Note that the user-defined config file will not be part of the git distribution, as it is excluded in the .gitignore file.