Configure¶

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.

Main Policy¶

Nmeta ships with a default policy in the YAML file:

~/nmeta/nmeta/config/main_policy.yaml

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:

~/nmeta/nmeta/config/user/main_policy.yaml

(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:

Comment

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:

any

Match if any of the conditions in the rule match

all

Match only if all of the conditions in the rule match

none

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.

Actions

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:

any

Match if any of the classifiers in the condition match

all

Match only if all of the classifiers in the condition match

none

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:

Static
Identity
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:

location_src¶

Logical location (as defined by policy) of switch/port

Example:

location_src: external

time_of_day¶

Time of day range (matches if flow start time is in this time range)

Example:

time_of_day: 21:00-07:00

Note that range can extend through midnight and times are in 24 hour format

eth_src¶

Ethernet source MAC address.

Example:

eth_src: 08:00:27:4a:2d:41

eth_dst¶

Ethernet destination MAC address.

Example:

eth_dst: 08:00:27:4a:2d:42

eth_type¶

Ethernet type. Can be in hex (starting with 0x) or decimal.

Examples:

eth_type: 0x0800

eth_type: 35020

ip_src¶

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.12

ip_src: 192.168.56.0/24

ip_src: 192.168.56.12-192.168.56.31

ip_dst¶

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.40

ip_dst: 192.168.57.0/24

ip_dst: 192.168.57.36-192.168.78.31

tcp_src¶

TCP source port.

Example:
tcp_src: 22

tcp_dst¶

TCP destination port.

Example:
tcp_dst: 80

udp_src¶

UDP source port.

Example:
udp_src: 123

udp_dst¶

UDP destination port.

Example:
udp_dst: 53

TC Branch - Identity Classifiers¶

All identity classifiers are prefixed with:

identity_

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:

identity_lldp_systemname_re: '.*\.audit\.example\.com'

Supported attributes are:

identity_lldp_systemname¶

Exact match against a system name discovered via LLDP. Example:

identity_lldp_systemname: bob.example.com

identity_lldp_systemname_re¶

Regular expression match against a system name discovered via LLDP. Example:

identity_lldp_systemname_re: '.*\.audit\.example\.com'

identity_dhcp_hostname¶

Exact match against a host name discovered via DHCP (option 12). Example:

identity_dhcp_hostname: bob

identity_dhcp_hostname_re¶

Regular expression match against a host name discovered via DHCP (option 12). Example:

identity_dhcp_hostname_re: 'bob.*'

identity_service_dns¶

Exact match of either IP address in a flow against a DNS domain. Example:

identity_service_dns: www.example.com

identity_service_dns_re¶

Regular expression match of either IP address in a flow against a DNS domain. Example:

identity_service_dns_re: '.*\.example\.com'

TC Branch - Custom Classifiers¶

Nmeta supports the creation of custom classifiers.

All custom classifiers have the attribute:

custom

The value determines the custom .py file to load from the nmeta/classifiers directory

For example, the following condition loads a custom classifier file ~/nmeta/nmeta/classifiers/statistical_qos_bandwidth_1.py:

custom: statistical_qos_bandwidth_1

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¶

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:

at_controller

at_controller_and_switch

Example:
drop: at_controller_and_switch
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.

qos_treatment¶

Specify QoS treatment for flow.

Values can be:

default_priority

constrained_bw

high_priority

low_priority

classifier_return

Example:
qos_treatment: classifier_return

set_desc¶

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.

Example:

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 Branch¶

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.

Example:

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

System Config¶

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:

~/nmeta/nmeta/config/config.yaml

These default configuration parameters can be overwritten by creating a file:

~/nmeta/nmeta/config/user/config.yaml

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:

tc_policy_logging_level_c: INFO

Note that the user-defined config file will not be part of the git distribution, as it is excluded in the .gitignore file.