---

   ovs-fields    ( 7 )

---

CONJUNCTIVE MATCH FIELDS

Summary: Name Bytes Mask RW? Prereqs NXM/OXM Support ──────── ────── ───── ──── ──────── ──────────────── conj_id 4 no no none OVS 2.4+

An individual OpenFlow flow can match only a single value for each field. However, situations often arise where one wants to match one of a set of values within a field or fields. For matching a single field against a set, it is straightforward and efficient to add multiple flows to the flow table, one for each value in the set. For example, one might use the following flows to send packets with IP source address a, b, c, or d to the OpenFlow controller:

ip,ip_src=a actions=controller ip,ip_src=b actions=controller ip,ip_src=c actions=controller ip,ip_src=d actions=controller

Similarly, these flows send packets with IP destination address e, f, g, or h to the OpenFlow controller:

ip,ip_dst=e actions=controller ip,ip_dst=f actions=controller ip,ip_dst=g actions=controller ip,ip_dst=h actions=controller

Installing all of the above flows in a single flow table yields a disjunctive effect: a packet is sent to the controller if ip_src ∈ {a,b,c,d} or ip_dst ∈ {e,f,g,h} (or both). (Pedantically, if both of the above sets of flows are present in the flow table, they should have different priorities, because OpenFlow says that the results are undefined when two flows with same priority can both match a single packet.)

Suppose, on the other hand, one wishes to match conjunctively, that is, to send a packet to the controller only if both ip_src ∈ {a,b,c,d} and ip_dst ∈ {e,f,g,h}. This requires 4 × 4 = 16 flows, one for each possible pairing of ip_src and ip_dst. That is acceptable for our small example, but it does not gracefully extend to larger sets or greater numbers of dimensions.

The conjunction action is a solution for conjunctive matches that is built into Open vSwitch. A conjunction action ties groups of individual OpenFlow flows into higher-level ``conjunctive flows''. Each group corresponds to one dimension, and each flow within the group matches one possible value for the dimension. A packet that matches one flow from each group matches the conjunctive flow.

To implement a conjunctive flow with conjunction, assign the conjunctive flow a 32-bit id, which must be unique within an OpenFlow table. Assign each of the n ≥ 2 dimensions a unique number from 1 to n; the ordering is unimportant. Add one flow to the OpenFlow flow table for each possible value of each dimension with conjunction(id, k/n) as the flow's actions, where k is the number assigned to the flow's dimension. Together, these flows specify the conjunctive flow's match condition. When the conjunctive match condition is met, Open vSwitch looks up one more flow that specifies the conjunctive flow's actions and receives its statistics. This flow is found by setting conj_id to the specified id and then again searching the flow table.

The following flows provide an example. Whenever the IP source is one of the values in the flows that match on the IP source (dimension 1 of 2), and the IP destination is one of the values in the flows that match on IP destination (dimension 2 of 2), Open vSwitch searches for a flow that matches conj_id against the conjunction ID (1234), finding the first flow listed below.

conj_id=1234 actions=controller ip,ip_src=10.0.0.1 actions=conjunction(1234, 1/2) ip,ip_src=10.0.0.4 actions=conjunction(1234, 1/2) ip,ip_src=10.0.0.6 actions=conjunction(1234, 1/2) ip,ip_src=10.0.0.7 actions=conjunction(1234, 1/2) ip,ip_dst=10.0.0.2 actions=conjunction(1234, 2/2) ip,ip_dst=10.0.0.5 actions=conjunction(1234, 2/2) ip,ip_dst=10.0.0.7 actions=conjunction(1234, 2/2) ip,ip_dst=10.0.0.8 actions=conjunction(1234, 2/2)

Many subtleties exist:

• In the example above, every flow in a single dimension has the same form, that is, dimension 1 matches on ip_src and dimension 2 on ip_dst, but this is not a requirement. Different flows within a dimension may match on different bits within a field (e.g. IP network prefixes of different lengths, or TCP/UDP port ranges as bitwise matches), or even on entirely different fields (e.g. to match packets for TCP source port 80 or TCP destination port 80).

• The flows within a dimension can vary their matches across more than one field, e.g. to match only specific pairs of IP source and destination addresses or L4 port numbers.

• A flow may have multiple conjunction actions, with different id values. This is useful for multiple conjunctive flows with overlapping sets. If one conjunctive flow matches packets with both ip_src ∈ {a,b} and ip_dst ∈ {d,e} and a second conjunctive flow matches ip_src ∈ {b,c} and ip_dst ∈ {f,g}, for example, then the flow that matches ip_src=b would have two conjunction actions, one for each conjunctive flow. The order of conjunction actions within a list of actions is not significant.

• A flow with conjunction actions may also include note actions for annotations, but not any other kind of actions. (They would not be useful because they would never be executed.)

• All of the flows that constitute a conjunctive flow with a given id must have the same priority. (Flows with the same id but different priorities are currently treated as different conjunctive flows, that is, currently id values need only be unique within an OpenFlow table at a given priority. This behavior isn't guaranteed to stay the same in later releases, so please use id values unique within an OpenFlow table.)

• Conjunctive flows must not overlap with each other, at a given priority, that is, any given packet must be able to match at most one conjunctive flow at a given priority. Overlapping conjunctive flows yield unpredictable results. (The flows that constitute a conjunctive flow may overlap with those that constitute the same or another conjunctive flow.)

• Following a conjunctive flow match, the search for the flow with conj_id=id is done in the same general-purpose way as other flow table searches, so one can use flows with conj_id=id to act differently depending on circumstances. (One exception is that the search for the conj_id=id flow itself ignores conjunctive flows, to avoid recursion.) If the search with conj_id=id fails, Open vSwitch acts as if the conjunctive flow had not matched at all, and continues searching the flow table for other matching flows.

• OpenFlow prerequisite checking occurs for the flow with conj_id=id in the same way as any other flow, e.g. in an OpenFlow 1.1+ context, putting a mod_nw_src action into the example above would require adding an ip match, like this:

conj_id=1234,ip actions=mod_nw_src:1.2.3.4,controller

• OpenFlow prerequisite checking also occurs for the individual flows that comprise a conjunctive match in the same way as any other flow.

• The flows that constitute a conjunctive flow do not have useful statistics. They are never updated with byte or packet counts, and so on. (For such a flow, therefore, the idle and hard timeouts work much the same way.)

• Sometimes there is a choice of which flows include a particular match. For example, suppose that we added an extra constraint to our example, to match on ip_src ∈ {a,b,c,d} and ip_dst ∈ {e,f,g,h} and tcp_dst = i. One way to implement this is to add the new constraint to the conj_id flow, like this:

conj_id=1234,tcp,tcp_dst=i actions=mod_nw_src:1.2.3.4,controller

but this is not recommended because of the cost of the extra flow table lookup. Instead, add the constraint to the individual flows, either in one of the dimensions or (slightly better) all of them.

• A conjunctive match must have n ≥ 2 dimensions (otherwise a conjunctive match is not necessary). Open vSwitch enforces this.

• Each dimension within a conjunctive match should ordinarily have more than one flow. Open vSwitch does not enforce this.

Conjunction ID Field

Name: conj_id Width: 32 bits Format: decimal Masking: not maskable

Prerequisites: none Access: read-only OpenFlow 1.0: not supported OpenFlow 1.1: not supported OXM: none NXM: NXM_NX_CONJ_ID (37) since Open vSwitch 2.4

Used for conjunctive matching. See above for more information.