! Pre-Tagging map -- upon matching a set of given conditions, pre_tag_map does

! return numerical (set_tag, set_tag2) or string (label) IDs.

!

! File syntax is key-based. Position of keys inside the same row (rule) is not

! relevant; Spaces are not allowed (ie. 'id = 1' is not valid). The first full

! match wins (like in firewall rules). MATCH keys support negations via a

! negative valuee (ie. 'in=-2' for data not entering via interface with ifindex

! 2); negations are intuitively not supported on SET keys (ie. 'set_tag', etc.);

! also 'filter' and 'ip' keys do not support negative values. 'label', 'jeq' and

! 'stack' keys can be used to alter the standard flow of rules evaluation.

!

! nfacctd: valid keys: set_tag, set_tag2, set_label, set_tos, ip, in, out,

! engine_type, engine_id, source_id, flowset_id, nexthop, bgp_nexthop, filter,

! sample_type, is_bi_flow, is_nel, is_nsel, direction, fwd_status, src_mac,

! dst_mac, vlan, cvlan, src_net, dst_net, ip_proto, src_port, dst_port,

! tcp_flags, is_multicast, mpls_pw_id, mpls_vpn_id_in, mpls_vpn_id_out.

!

! sfacctd: valid keys: set_tag, set_tag2, set_label, set_tos, ip, in, out,

! nexthop, bgp_nexthop, filter, agent_id, sample_type, direction, src_mac,

! dst_mac, vlan, src_net, dst_net, ip_proto, src_port, dst_port, tcp_flags,

! is_multicast, mpls_pw_id, engine_id.

!

! pmacctd: valid keys: set_tag, set_tag2, set_label, direction and filter.

!

! uacctd: valid keys: set_tag, set_tag2 and set_label.

!

! nfacctd when in 'tee' mode: valid keys: set_tag, set_tag2, set_label, ip,

! in, out, direction, src_mac, dst_mac, vlan, src_net, dst_net, ip_proto,

! src_port, dst_port, tcp_flaga, bgp_nexthop, engine_type, engine_id,

! source_id.

!

! sfacctd when in 'tee' mode: valid keys: set_tag, set_tag2, set_label, ip,

! in, out, direction, src_mac, dst_mac, vlan, src_net, dst_net, ip_proto,

! src_port, dst_port, tcp_flags, bgp_nexthop, agent_id.

!

! BGP-related keys supported by pre_tag_map are independent of the collection

! method in use, hence apply to all traffic daemons (when BGP thread is

! enabled): src_as, dst_as, src_comms, comms, peer_src_as, peer_dst_as,

! src_local_pref, local_pref, src_roa, dst_roa, mpls_vpn_rd.

!

! Non-traffic daemons and threads, ie. pmbgpd (bgp_daemon_tag_map), pmbmpd

! (bmp_daemon_tag_map), pmtelemetryd (telemetry_daemon_tag_map) valid keys:

! set_tag, set_label, ip.

!

! list of currently supported keys follows:

!

! 'set_tag' SET: tag assigned to a matching packet, flow or sample;

! tag can be also defined auto-increasing, ie. <tag #>++;

! its use is mutually exclusive to set_tag2 and set_label

! within the same rule. The resulting value is written to

! the 'tag' field when using memory tables and 'agent_id'

! when using a SQL plugin (unless a schema v9 is used).

! Valid tag values are in the range 1 to (2^64-1).

! 'set_tag2' SET: tag assigned to a matching packet, flow or sample;

! tag can be also defined auto-increasing, ie. <tag #>++;

! its use is mutually exclusive to set_tag and set_label

! within the same rule. The resulting value is written to

! the 'tag2' field when using memory tables and 'agent_id2'

! when using a SQL plugin (unless a schema v9 is used).

! If using a SQL plugin, read more about the 'agent_id2'

! field in the 'sql/README.agent_id2' document. Valid tag

! values are in the range 1 to (2^64-1).

! 'set_label' SET: string label assigned to a matching packet, flow

! or sample; its use is mutually exclusive to tags within

! the same rule. The resulting value is written to the

! 'label' field. If pre_tag_label_encode_as_map is set to

! true in the config, the '%' character is used to delimit

! key and value, ie. "set_label=key%value".

! 'set_tos' SET: Matching packets are set their 'tos' primitive to

! the specified value. Currently valid only in nfacctd. If

! collecting ingress NetFlow at both trusted and untrusted

! borders, e.g., this is useful to selectively override ToS

! values read only at untrusted ones.

! 'ip' MATCH: in nfacctd this is compared against the source

! IP address of the device originating NetFlow packets;

! in sfacctd this is compared against the AgentId field

! of received sFlow samples. Expected argument are an IP

! address or prefix (ie. XXX.XXX.XXX.XXX/NN). 0.0.0.0/0

! would match all IPv4 addresses; ::/0 would match all

! IPv6 addresses; not specifying an 'ip' clause would

! match both all IPv4 and IPv6 addresses, in which case

! two objects per map entry will be allocated (corollary:

! maps_entries should be set to at least twice the amount

! of entries in the map).

! 'in' MATCH: Input interface. In NFv9/IPFIX this is compared

! against IE #10 and, if not existing, against IE #252.

! 'out' MATCH: Output interface. In NFv9/IPFIX this is compared

! against IE #14 and, if not existing, against IE #253.

! 'engine_type' MATCH: in NFv5 this is compared against the engine_type

! header field. Provides uniqueness with respect to the

! routing engine on the exporting device.

! 'engine_id' MATCH: in NFv5 this is compared against the engine_id

! header field; this provides uniqueness with respect to the

! particular line card on the exporting device. In NFv9/IPFIX

! it's compared against the source_id header field.

! 'source_id' MATCH: In NFv9/IPFIX it's compared against the source_id

! header field. This is an alias to engine_id.

! 'flowset_id' MATCH: In NFv9/IPFIX this is compared against the flowset

! ID field of the flowset header.

! 'nexthop' MATCH: IPv4/IPv6 address of the next-hop router. In NFv9/

! IPFIX this is compared against IE #15.

! 'bgp_nexthop' MATCH: IPv4/IPv6 address of the next-hop BGP router. In

! MPLS-enabled networks this can be also matched against top

! label address where available (ie. egress NFv9/IPFIX

! exports). In NFv9/IPFIX this is compared against IE #18

! for IPv4 and IE #62 for IPv6.

! 'filter' MATCH: incoming packets are matched against the supplied

! filter expression (expected in libpcap syntax); the filter

! needs to be enclosed in quotes (').

! 'agent_id' MATCH: in sFlow v5 it's compared against the subAgentId

! field. sFlow v2/v4 do not carry such field, hence it does

! not apply.

! 'sample_type' MATCH: in sFlow v2/v4/v5 this is compared against the

! sample type field. Expected in <Enterprise>:<Format>

! notation. In NetFlow/IPIX three keywords are supported:

! "flow" to match any flow traffic data, "flow-ipv4" and

! "flow-ipv6" to match respectively only IPv4 and IPv6 flow

! traffic data, "flow-mpls-ipv4" and "flow-mpls-ipv6" to

! match respectively only MPLS-labelled IPv4 and IPv6 flow

! traffic data, "event" to match templates suitable to flag

! events and "option" to denote NetFlow/IPFIX option records

! data.

! 'is_bi_flow' MATCH: in NetFlow/IPFIX this checks the presence of both

! initiatorOctets and responderOctets in a flow to infer

! that it is a bi-directional flow. If set to 'true' this

! does match bi-flows, if set to 'false' it does match non

! bi-flows.

! 'is_nel' MATCH: in NetFlow/IPFIX this checks the presence of the

! natEvent field (230) to infer that this is NEL kind data.

! If set to 'true' this does match NSEL, if set to 'false'

! it does match non NEL.

! 'is_nsel' MATCH: in NetFlow/IPFIX this checks the presence of the

! firewallEvent field (233) to infer that this is NSEL kind

! of data. If set to 'true' this does match NSEL, if set to

! 'false' it does match non NSEL.

! 'direction' MATCH: expected values are 0 (ingress direction) or 1

! (egress direction). In NFv9/IPFIX this is compared

! against the direction (61) field; in sFlow v2/v4/v5 this

! returns a positive match if: 1) source_id equals to input

! interface and this 'direction' key is set to '0' or 2)

! source_id equals to output interface and this 'direction'

! key is set to '1'.

! 'src_as' MATCH: source Autonomous System Number. In pmacctd, if

! the BGP daemon is not enabled it works only against a

! Networks map (see 'networks_file' directive); in nfacctd

! and sfacctd it works against a Networks Map, the source

! ASN field in either sFlow or NetFlow datagrams. Since

! 0.12, this can be compared against the corresponding BGP

! RIB of the exporting device ('bgp_daemon' configuration

! directive).

! 'dst_as' MATCH: destination Autonomous System Number. Same 'src_as'

! remarks hold here. Please read them above.

! 'peer_src_as' MATCH: peering source Autonomous System Number. This is

! compared against the source of info configured in

! bgp_peer_src_as_type.

! 'peer_dst_as' MATCH: peering destination Autonomous System Number. Same

! 'peer_src_as' remarks hold here. Please read them above.

! 'src_local_pref' MATCH: source IP prefix BGP Local Preference attribute.

! This is compared against the source of info configured in

! bgp_src_local_pref_type.

! 'local_pref' MATCH: destination IP prefix BGP Local Preference attribute.

! This is compared against the BGP RIB of the exporting

! device.

! 'src_roa' MATCH: source IP prefix RPKI/ROA status. This is compared

! against the BGP RIB of the exporting device.

! 'dst_roa' MATCH: destination IP prefix RPKI/ROA status. This is

! compared against the BGP RIB of the exporting device.

! 'src_comms' MATCH: Destination IP prefix BGP standard communities;

! multiple elements, up to 16, can be supplied, comma-

! separated (no spaces allowed); the check is successful

! if any of the communities is matched. This is compared

! against the source of info configured in

! bgp_src_std_comm_type.

! 'comms' MATCH: Destination IP prefix BGP standard communities;

! multiple elements, up to 16, can be supplied, comma-

! separated (no spaces allowed); the check is successful

! if any of the communities is matched. This is compared

! against the BGP RIB of the exporting device. See examples

! below.

! 'mpls_vpn_rd' MATCH: Destination IP prefix BGP-signalled MPLS L3 VPN

! Route Distinguisher (RD) value. Encoding types #0, #1

! and #2 are supported as per rfc4364. See example below.

! 'mpls_pw_id' MATCH: Signalled MPLS L2 VPNs Pseudowire ID. In NetFlow

! v9/IPFIX this is compared against IE #249; in sFlow v5

! this is compared against vll_vc_id field, extended MPLS

! VC object.

! 'mpls_vpn_id_in' MATCH: ingress MPLS VPN ID. A positive 32-bit unsigned

! integer is expected as value. In NetFlow/IPFIX this is

! compared against field type #234.

! 'mpls_vpn_id_out' MATCH: egress MPLS VPN ID. A positive 32-bit unsigned

! integer is expected as value. In NetFlow/IPFIX this is

! compared against field type #235.

! 'src_mac' MATCH: In NFv9/IPFIX this is compared against IE #56,

! in sFlow against source MAC address field part of the

! Extended Switch object.

! 'dst_mac' MATCH: In NFv9/IPFIX this is compared against IE #57,

! in sFlow against destination MAC address field part of

! the Extended Switch object.

! 'vlan' MATCH: In NFv9/IPFIX this is compared against IE #58 and,

! if not existing, against IE #242; in sFlow this is

! compared against in/out VLAN ID fields part of the

! Extended Switch object.

! 'cvlan' MATCH: In NFv9/IPFIX this is compared against IE #245

! and, if not existing, against IE #255; in sFlow this is

! compared against the cvlan field part of the Extended

! Switch object.

! 'src_net' MATCH: Source IP address field in NeFlow v5 and sFlow.

! In NFv9/IPFIX this is compared against IE #27 or #44.

! 'dst_net' MATCH: Destination IP address field in NetFlow v5 and

! sFlow. In NFv9/IPFIX this is compared against IE #28 or

! IE #45.

! 'ip_proto' MATCH: IP protocol field in NetFlow v5 and sFlow. In

! NFv9/IPFIX this is compared against IE #4.

! 'src_port' MATCH: Source Port in NetFlow v5 and sFlow. In NFv9/IPFIX

! this is compared against IE #7.

! 'dst_port' MATCH: Destination Port in NetFlow v5 and sFlow. In NFv9/

! IPFIX this is compared against IE #11.

! 'tcp_flags' MATCH: TCP Flags field in NetFlow v5 and sFlow. In NFv9/

! IPFIX this is compared against IE #6. The expected value

! is in hexadecimal format (ie. 0x01 to match SYN packets).

! While in NetFlow/IPFIX the accumulation of all bits seen

! in a flow is set to 1, this key matches the exact value

! of the field, ie. it does not perform bitwise operations.

! 'is_multicast' MATCH: in NFv9/IPFIX this is compared against IE #57,

! in sFlow against destination MAC address field part of

! the Extended Switch object. If set to 'true' this does

! match MAC multicast addresses, if set to 'false' it won't

! match them. To match or exclude IPv4/IPv6 multicast

! addresses please use 'dst_net'.

! 'fwd_status' MATCH: In NFv9/IPFIX this is compared against IE #89; see

! https://www.iana.org/assignments/ipfix/ipfix.xhtml for

! the specific semantics of the field and some examples.

! 'label' SET: Mark the rule with label's value. Labels don't need

! to be unique: when jumping, the first matching label wins.

! Label value 'next' is reserved for internal use and

! hence must not be used in a map. Doing otherwise might

! give unexpected results.

! 'jeq' SET: Jump on EQual. Jumps to the supplied label in case

! of rule match. Jumps are Only forward. Label "next" is

! reserved and causes to go to the next rule, if any.

! 'stack' SET: Currently 'sum' (A + B) and 'or' (A | B) operators

! are supported. This key makes sense only if JEQs are in

! use. When matching, accumulate tags, using the specified

! operator/function. By setting 'stack=sum', the resulting

! tag would be: <tag>=<previous ID + current ID>.

!

!

! Examples:

!

! Some basic examples applicable to NetFlow, IPFIX and sFlow.

!

set_tag=1 ip=192.168.2.1 in=4

set_tag=10 ip=192.168.1.1 in=5 out=3

set_tag=11 ip=192.168.1.1 in=3 out=5

set_tag=12 ip=192.168.1.1 in=3

set_tag=13 ip=192.168.1.1 nexthop=10.0.0.254

set_tag=14 ip=192.168.1.1 engine_type=1 engine_set_tag=0

set_tag=15 ip=192.168.1.1 in=3 filter='src net 192.168.0.0/24'

!

! The following rule instructs to increase the tag value at every pre_tag_map run,

! starting from a given floor value (in the example below, '1'). Since tags are

! part of the aggregate key, this causes no two objects to be further aggregated

! together.

!

set_tag=1++ ip=0.0.0.0/0

!

! The following rule sets labels on matching IP ranges non-aligned with subnets,

! ie. issue 'labelA' for the IP range 192.168.0.1 - 192.168.0.100 and 'labelB'

! for the IP range 192.168.0.101 - 192.168.0.200 (note: ip[12:4] is the source

! IP address and ip[16:4] is the destination one.

!

set_label=LabelA filter='((ip[12:4] >= 0xC0A80001) and (ip[12:4] <= 0xC0A80064)) or ((ip[16:4] >= 0xC0A80001) and (ip[16:4] <= 0xC0A80064))'

set_label=LabelB filter='((ip[12:4] >= 0xC0A80065) and (ip[12:4] <= 0xC0A800C8)) or ((ip[16:4] >= 0xC0A80065) and (ip[16:4] <= 0xC0A800C8))'

!

! A few examples sFlow-related. The format of the rules is the same of 'nfacctd' ones

! but some keys don't apply to it.

!

set_tag=30 ip=192.168.1.1

set_tag=31 ip=192.168.1.1 out=50

set_tag=32 ip=192.168.1.1 out=50 agent_id=100

!

! === JEQ example #1:

! - 'set_tag' used to store input interface tags

! - 'set_tag2' used to store output interface tags

!

set_tag=1000 ip=192.168.1.1 in=1 jeq=eval_out

set_tag=1001 ip=192.168.1.1 in=2 jeq=eval_out

set_tag=1002 ip=192.168.1.1 in=3 jeq=eval_out

! ... further INs

set_tag2=1000 ip=192.168.1.1 out=1 label=eval_out

set_tag2=1001 ip=192.168.1.1 out=2

set_tag2=1002 ip=192.168.1.1 out=3

! ... further OUTs

!

! ===

!

! === JEQ example #2:

! - 'id' structured hierarchically to store both input and output interface tags

!

set_tag=11000 ip=192.168.1.1 in=1 jeq=eval_out

set_tag=12000 ip=192.168.1.1 in=2 jeq=eval_out

set_tag=13000 ip=192.168.1.1 in=3 jeq=eval_out

! ... further INs

set_tag=100 ip=192.168.1.1 out=1 label=eval_out stack=sum

set_tag=101 ip=192.168.1.1 out=2 stack=sum

set_tag=102 ip=192.168.1.1 out=3 stack=sum

! ... further OUTs

!

! ===

!

! === BGP standard communities example #1

! - check is successful if matches either 65000:1234 or 65000:2345

!

set_tag=100 ip=192.168.1.1 comms=65000:1234,65000:2345

!

! ===

!

! === BGP standard communities example #2

! - a series of checks can be piled up in order to mimic match-all

! - underlying logics is:

! > tag=200 is considered a successful check;

! > tag=0 or tag=100 is considered unsuccessful

!

set_tag=100 ip=192.168.1.1 comms=65000:1234 label=65000:1234 jeq=65000:2345

set_tag=100 ip=192.168.1.1 comms=65000:2345 label=65000:2345 jeq=65000:3456

! ... further set_tag=100

set_tag=200 ip=192.168.1.1 comms=65000:3456 label=65000:3456

!

! ===

!

! === BGP/MPLS VPN Route Distinguisher (RD) example

! - check is successful if matches encoding type #0 with value 65512:1

!

set_tag=100 ip=192.168.1.1 mpls_vpn_rd=0:65512:1

!

! ===

!

! === sfprobe/nfprobe: determining semi-dynamically direction and ifindex

! - Two steps approach:

! > determine direction first (1=in, 2=out)

! > then short circuit it to return an ifindex value

! - Configuration would look like the following fragment:

! ...

! nfprobe_direction: tag

! nfprobe_ifindex: tag2

! ...

!

set_tag=1 filter='ether dst 00:11:22:33:44:55' jeq=fivefive

set_tag=1 filter='ether dst 00:11:22:33:44:66' jeq=sixsix

set_tag=1 filter='ether dst 00:11:22:33:44:77' jeq=sevenseven

set_tag=2 filter='ether src 00:11:22:33:44:55' jeq=fivefive

set_tag=2 filter='ether src 00:11:22:33:44:66' jeq=sixsix

set_tag=2 filter='ether src 00:11:22:33:44:77' jeq=sevenseven

!

set_tag2=5 label=fivefive

set_tag2=6 label=sixsix

set_tag2=7 label=sevenseven

!

! ===

!

! === Basic set_label example

! Tag as "blabla,blabla2" NetFlow/sFlow data received from all exporters.

! If, ie. as a result of JEQ's in a pre_tag_map, multiple 'set_label' are

! matched, then labels are appended and separated by a comma (warning: if

! using print plugin with CSV output, the file separator should be changed

! with print_output_separator)

!

set_label=blabla ip=0.0.0.0/0 label=blabla jeq=blabla2

set_label=blabla2 ip=0.0.0.0/0 label=blabla2

!

!

! pre_tag_label_filter[xxx]: -null

! pre_tag_label_filter[yyy]: blabla

! pre_tag_label_filter[zzz]: blabla, blabla2

!

! ===