flows module¶
The flows module is part of the nmeta suite
It provides an abstraction for conversations (flows), using a MongoDB database for storage and data retention maintenance.
Flows are identified via an indexed bi-directionally-unique hash value, derived from IP-value-ordered 5-tuple (source and destination IP addresses, IP protocol and transport source and destination port numbers).
Ingesting a packet puts the flows object into the context of the packet that flow belongs to, and updates the database object for that flow with information from the current packet.
There are various methods (see class docstring) that provide views into the state of the flow.
-
class
flows.
Flow
(config)¶ Bases:
baseclass.BaseClass
An object that represents a flow that we are classifying
Intended to provide an abstraction of a flow that classifiers can use to make determinations without having to understand implementations such as database lookups etc.
Be aware that this module is not very mature yet. It does not cover some basic corner cases such as packet retransmissions and out of order or missing packets.
Read a packet_in event into flows (assumes class instantiated as an object called ‘flow’):
flow.ingest_packet(dpid, in_port, pkt, timestamp)Variables available for Classifiers (assumes class instantiated as an object called ‘flow’):
Variables for the current packet:
- flow.packet.flow_hash
- The hash of the 5-tuple of the current packet
- flow.packet.packet_hash
- The hash of the current packet used for deduplication. It is an indexed uni-directionally packet identifier, derived from ip_src, ip_dst, proto, tp_src, tp_dst, tp_seq_src, tp_seq_dst
- flow.packet.dpid
- The DPID that the current packet was received from via a Packet-In message
- flow.packet.in_port
- The switch port that the current packet was received on before being sent to the controller
- flow.packet.timestamp
- The time in datetime format that the current packet was received at the controller
- flow.packet.length
- Length in bytes of the current packet on wire
- flow.packet.eth_src
- Ethernet source MAC address of current packet
- flow.packet.eth_dst
- Ethernet destination MAC address of current packet
- flow.packet.eth_type
- Ethertype of current packet in decimal
- flow.packet.ip_src
- IP source address of current packet
- flow.packet.ip_dst
- IP destination address of current packet
- flow.packet.proto
- IP protocol number of current packet
- flow.packet.tp_src
- Source transport-layer port number of current packet
- flow.packet.tp_dst
- Destination transport-layer port number of current packet
- flow.packet.tp_flags
- Transport-layer flags of the current packet
- flow.packet.tp_seq_src
- Source transport-layer sequence number (where existing) of current packet
- flow.packet.tp_seq_dst
- Destination transport-layer sequence number (where existing) of current packet
- flow.packet.payload
- Payload data of current packet
- flow.packet.tcp_fin()
- True if TCP FIN flag is set in the current packet
- flow.packet.tcp_syn()
- True if TCP SYN flag is set in the current packet
- flow.packet.tcp_rst()
- True if TCP RST flag is set in the current packet
- flow.packet.tcp_psh()
- True if TCP PSH flag is set in the current packet
- flow.packet.tcp_ack()
- True if TCP ACK flag is set in the current packet
- flow.packet.tcp_urg()
- True if TCP URG flag is set in the current packet
- flow.packet.tcp_ece()
- True if TCP ECE flag is set in the current packet
- flow.packet.tcp_cwr()
- True if TCP CWR flag is set in the current packet
Variables for the whole flow:
- flow.packet_count()
- Unique packets registered for the flow
- flow.client()
- The IP that is the originator of the flow (if known, otherwise 0)
- flow.server()
- The IP that is the destination of the flow (if known, otherwise 0)
- flow.packet_direction()
- c2s (client to server) or s2c directionality based on first observed packet direction in the flow. Source of first packet in flow is assumed to be the client
- flow.max_packet_size()
- Size of largest packet in the flow
- flow.max_interpacket_interval()
- TBD
- flow.min_interpacket_interval()
- TBD
Variables for the whole flow relating to classification:
classification.TBD
- Challenges (not handled - yet):
- duplicate packets due to retransmissions or multiple switches in path
- IP fragments
- Flow reuse - TCP source port reused
-
class
Classification
(flow_hash, clsfn, time_limit)¶ Bases:
object
An object that represents an individual traffic classification
-
commit
()¶ Record current state of flow classification into MongoDB classifications collection.
-
dbdict
()¶ Return a dictionary object of traffic classification parameters for storing in the database
-
-
class
Flow.
Packet
¶ Bases:
object
An object that represents the current packet
-
dbdict
()¶ Return a dictionary object of metadata parameters of current packet (excludes payload), for storing in database
-
tcp_ack
()¶ Does the current packet have the TCP ACK flag set?
-
tcp_cwr
()¶ Does the current packet have the TCP CWR flag set?
-
tcp_ece
()¶ Does the current packet have the TCP ECE flag set?
-
tcp_fin
()¶ Does the current packet have the TCP FIN flag set?
-
tcp_psh
()¶ Does the current packet have the TCP PSH flag set?
-
tcp_rst
()¶ Does the current packet have the TCP RST flag set?
-
tcp_syn
()¶ Does the current packet have the TCP SYN flag set?
-
tcp_urg
()¶ Does the current packet have the TCP URG flag set?
-
-
Flow.
client
()¶ The IP that is the originator of the flow (if known, otherwise 0)
Finds first packet seen for the flow_hash within the time limit and returns the source IP
-
Flow.
ingest_packet
(dpid, in_port, pkt, timestamp)¶ Ingest a packet into the packet_ins collection and put the flow object into the context of the packet. Note that timestamp MUST be in datetime format
-
Flow.
max_interpacket_interval
()¶ Return the size of the largest inter-packet time interval in the flow (assessed per direction in flow) as seconds (type float)
Note: c2s = client to server direction s2c = server to client direction
Note: results are slightly inaccurate due to floating point rounding.
-
Flow.
max_packet_size
()¶ Return the size of the largest packet in the flow (in either direction)
-
Flow.
min_interpacket_interval
()¶ Return the size of the smallest inter-packet time interval in the flow (assessed per direction in flow) as seconds (type float)
Note: c2s = client to server direction s2c = server to client direction
Note: results are slightly inaccurate due to floating point rounding.
-
Flow.
packet_count
()¶ Return the number of packets in the flow (counting packets in both directions). This method should deduplicate for where the same packet is received from multiple switches, but is TBD...
Works by retrieving packets from packet_ins database with current packet flow_hash and within flow reuse time limit.
-
Flow.
packet_direction
()¶ Return the direction of the current packet in the flow where c2s is client to server and s2c is server to client.
-
Flow.
server
()¶ The IP that is the destination of the flow (if known, otherwise 0)
Finds first packet seen for the hash within the time limit and returns the destination IP
-
Flow.
suppress_flow
()¶ Set the suppressed attribute in the flow database object to the current packet count so that future suppressions of the same flow can be backed off to prevent overwhelming the controller