/
meta-flow.xml
4800 lines (4211 loc) · 181 KB
/
meta-flow.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8"?>
<fields>
<h1>Introduction</h1>
<p>
This document aims to comprehensively document all of the fields,
both standard and non-standard, supported by OpenFlow or Open
vSwitch, regardless of origin.
</p>
<h2>Fields</h2>
<p>
A <dfn>field</dfn> is a property of a packet. Most familiarly, <dfn>data
fields</dfn> are fields that can be extracted from a packet. Most data
fields are copied directly from protocol headers, e.g. at layer 2, the
Ethernet source and destination addresses, or the VLAN ID; at layer 3, the
IPv4 or IPv6 source and destination; and at layer 4, the TCP or UDP ports.
Other data fields are computed, e.g. <ref field="ip_frag"/> describes
whether a packet is a fragment but it is not copied directly from the IP
header.
</p>
<p>
Data fields that are always present as a consequence of the basic
networking technology in use are called called <dfn>root fields</dfn>.
Open vSwitch 2.7 and earlier considered Ethernet fields to be root fields,
and this remains the default mode of operation for Open vSwitch bridges.
When a packet is received from a non-Ethernet interfaces, such as a layer-3
LISP tunnel, Open vSwitch 2.7 and earlier force-fit the packet to this
Ethernet-centric point of view by pretending that an Ethernet header is
present whose Ethernet type that indicates the packet's actual type (and
whose source and destination addresses are all-zero).
</p>
<p>
Open vSwitch 2.8 and later implement the ``packet type-aware pipeline''
concept introduced in OpenFlow 1.5. Such a pipeline does not have any root
fields. Instead, a new metadata field, <ref field="packet_type"/>,
indicates the basic type of the packet, which can be Ethernet, IPv4, IPv6,
or another type. For backward compatibility, by default Open vSwitch 2.8
imitates the behavior of Open vSwitch 2.7 and earlier. Later versions of
Open vSwitch may change the default, and in the meantime controllers can
turn off this legacy behavior, on a port-by-port basis, by setting
<code>options:packet_type</code> to <code>ptap</code> in the
<code>Interface</code> table. This is significant only for ports that can
handle non-Ethernet packets, which is currently just LISP, VXLAN-GPE, and
GRE tunnel ports. See <code>ovs-vwitchd.conf.db</code>(5) for more
information.
</p>
<p>
Non-root data fields are not always present. A packet contains ARP
fields, for example, only when its packet type is ARP or when it is an
Ethernet packet whose Ethernet header indicates the Ethertype for ARP,
0x0806. In this documentation, we say that a field is
<dfn>applicable</dfn> when it is present in a packet, and
<dfn>inapplicable</dfn> when it is not. (These are not standard terms.)
We refer to the conditions that determine whether a field is applicable as
<dfn>prerequisites</dfn>. Some VLAN-related fields are a special case:
these fields are always applicable for Ethernet packets, but have a
designated value or bit that indicates whether a VLAN header is present,
with the remaining values or bits indicating the VLAN header's content
(if it is present). <!-- XXX also ethertype -->
</p>
<p>
An inapplicable field does not have a value, not even a nominal
``value'' such as all-zero-bits. In many circumstances, OpenFlow
and Open vSwitch allow references only to applicable fields. For
example, one may match (see <cite>Matching</cite>, below) a given
field only if the match includes the field's prerequisite,
e.g. matching an ARP field is only allowed if one also matches on
Ethertype 0x0806 or the <ref field="packet_type"/> for ARP in a packet
type-aware bridge.
</p>
<p>
Sometimes a packet may contain multiple instances of a header.
For example, a packet may contain multiple VLAN or MPLS headers,
and tunnels can cause any data field to recur. OpenFlow and Open
vSwitch do not address these cases uniformly. For VLAN and MPLS
headers, only the outermost header is accessible, so that inner
headers may be accessed only by ``popping'' (removing) the outer
header. (Open vSwitch supports only a single VLAN header in any
case.) For tunnels, e.g. GRE or VXLAN, the outer header and inner
headers are treated as different data fields.
</p>
<p>
Many network protocols are built in layers as a stack of concatenated
headers. Each header typically contains a ``next type'' field that
indicates the type of the protocol header that follows, e.g. Ethernet
contains an Ethertype and IPv4 contains a IP protocol type. The
exceptional cases, where protocols are layered but an outer layer does not
indicate the protocol type for the inner layer, or gives only an ambiguous
indication, are troublesome. An MPLS header, for example, only indicates
whether another MPLS header or some other protocol follows, and in the
latter case the inner protocol must be known from the context. In these
exceptional cases, OpenFlow and Open vSwitch cannot provide insight into
the inner protocol data fields without additional context, and thus they
treat all later data fields as inapplicable until an OpenFlow action
explicitly specifies what protocol follows. In the case of MPLS, the
OpenFlow ``pop MPLS'' action that removes the last MPLS header from a
packet provides this context, as the Ethertype of the payload. See
<cite>Layer 2.5: MPLS</cite> for more information.
</p>
<p>
OpenFlow and Open vSwitch support some fields other than data
fields. <dfn>Metadata fields</dfn> relate to the origin or
treatment of a packet, but they are not extracted from the packet
data itself. One example is the physical port on which a packet
arrived at the switch. <dfn>Register fields</dfn> act like
variables: they give an OpenFlow switch space for temporary
storage while processing a packet. Existing metadata and register
fields have no prerequisites.
</p>
<p>
A field's value consists of an integral number of bytes. For data
fields, sometimes those bytes are taken directly from the packet.
Other data fields are copied from a packet with padding (usually
with zeros and in the most significant positions). The remaining
data fields are transformed in other ways as they are copied from
the packets, to make them more useful for matching.
</p>
<h2>Matching</h2>
<p>
The most important use of fields in OpenFlow is
<dfn>matching</dfn>, to determine whether particular field values
agree with a set of constraints called a <dfn>match</dfn>. A
match consists of zero or more constraints on individual fields,
all of which must be met to satisfy the match. (A match that
contains no constraints is always satisfied.) OpenFlow and Open
vSwitch support a number of forms of matching on individual
fields:
</p>
<dl>
<dt><dfn>Exact match</dfn>, e.g. <code>nw_src=10.1.2.3</code></dt>
<dd>
<p>
Only a particular value of the field is matched; for example, only one
particular source IP address. Exact matches are written as
<code><var>field</var>=<var>value</var></code>. The forms accepted for
<var>value</var> depend on the field.
</p>
<p>
All fields support exact matches.
</p>
</dd>
<dt>
<dfn>Bitwise match</dfn>, e.g. <code>nw_src=10.1.0.0/255.255.0.0</code>
</dt>
<dd>
<p>
Specific bits in the field must have specified values; for example,
only source IP addresses in a particular subnet. Bitwise matches are
written as
<code><var>field</var>=<var>value</var>/<var>mask</var></code>, where
<var>value</var> and <var>mask</var> take one of the forms accepted for
an exact match on <var>field</var>. Some fields accept other forms for
bitwise matches; for example, <code>nw_src=10.1.0.0/255.255.0.0</code>
may also be written <code>nw_src=10.1.0.0/16</code>.
</p>
<p>
Most OpenFlow switches do not allow every bitwise matching on every
field (and before OpenFlow 1.2, the protocol did not even provide for
the possibility for most fields). Even switches that do allow bitwise
matching on a given field may restrict the masks that are allowed, e.g.
by allowing matches only on contiguous sets of bits starting from the
most significant bit, that is, ``CIDR'' masks [RFC 4632]. Open vSwitch
does not allows bitwise matching on every field, but it allows
arbitrary bitwise masks on any field that does support bitwise
matching. (Older versions had some restrictions, as documented in the
descriptions of individual fields.)
</p>
</dd>
<dt><dfn>Wildcard</dfn>, e.g. ``any <code>nw_src</code>''</dt>
<dd>
<p>
The value of the field is not constrained. Wildcarded fields may be
written as <code><var>field</var>=*</code>, although it is unusual to
mention them at all. (When specifying a wildcard explicitly in a
command invocation, be sure to using quoting to protect against shell
expansion.)
</p>
<p>
There is a tiny difference between wildcarding a field and not
specifying any match on a field: wildcarding a field requires
satisfying the field's prerequisites.
</p>
</dd>
</dl>
<p>
Some types of matches on individual fields cannot be expressed directly
with OpenFlow and Open vSwitch. These can be expressed indirectly:
</p>
<dl>
<dt><dfn>Set match</dfn>, e.g. ``<code>tcp_dst</code> ∈ {80, 443,
8080}''</dt>
<dd>
<p>
The value of a field is one of a specified set of values; for
example, the TCP destination port is 80, 443, or 8080.
</p>
<p>
For matches used in flows (see <cite>Flows</cite>, below), multiple
flows can simulate set matches.
</p>
</dd>
<dt><dfn>Range match</dfn>, e.g. ``1000 ≤ <code>tcp_dst</code> ≤
1999''</dt>
<dd>
<p>
The value of the field must lie within a numerical range, for
example, TCP destination ports between 1000 and 1999.
</p>
<p>
Range matches can be expressed as a collection of bitwise matches. For
example, suppose that the goal is to match TCP source ports 1000 to
1999, inclusive. The binary representations of 1000 and 1999 are:
</p>
<pre fixed="yes">
01111101000
11111001111
</pre>
<p>
The following series of bitwise matches will match 1000 and
1999 and all the values in between:
</p>
<pre fixed="yes">
01111101xxx
0111111xxxx
10xxxxxxxxx
110xxxxxxxx
1110xxxxxxx
11110xxxxxx
1111100xxxx
</pre>
<p>
which can be written as the following matches:
</p>
<pre>
tcp,tp_src=0x03e8/0xfff8
tcp,tp_src=0x03f0/0xfff0
tcp,tp_src=0x0400/0xfe00
tcp,tp_src=0x0600/0xff00
tcp,tp_src=0x0700/0xff80
tcp,tp_src=0x0780/0xffc0
tcp,tp_src=0x07c0/0xfff0
</pre>
</dd>
<dt><dfn>Inequality match</dfn>, e.g. ``<code>tcp_dst</code> ≠ 80''</dt>
<dd>
<p>
The value of the field differs from a specified value, for
example, all TCP destination ports except 80.
</p>
<p>
An inequality match on an <var>n</var>-bit field can be expressed as a
disjunction of <var>n</var> 1-bit matches. For example, the inequality
match ``<code>vlan_pcp</code> ≠ 5'' can be expressed as
``<code>vlan_pcp</code> = 0/4 or <code>vlan_pcp</code> = 2/2 or
<code>vlan_pcp</code> = 0/1.'' For matches used in flows (see
<cite>Flows</cite>, below), sometimes one can more compactly express
inequality as a higher-priority flow that matches the exceptional case
paired with a lower-priority flow that matches the general case.
</p>
<p>
Alternatively, an inequality match may be converted to a pair of range
matches, e.g. <code>tcp_src ≠ 80</code> may be expressed as ``0 ≤
<code>tcp_src</code> < 80 or 80 < <code>tcp_src</code> ≤ 65535'',
and then each range match may in turn be converted to a bitwise match.
</p>
</dd>
<dt><dfn>Conjunctive match</dfn>, e.g. ``<code>tcp_src</code> ∈ {80, 443, 8080} and <code>tcp_dst</code> ∈ {80, 443, 8080}''</dt>
<dd>
As an OpenFlow extension, Open vSwitch supports matching on conditions on
conjunctions of the previously mentioned forms of matching. See the
documentation for <ref field="conj_id"/> for more information.
</dd>
</dl>
<p>
All of these supported forms of matching are special cases of bitwise
matching. In some cases this influences the design of field values. <ref
field="ip_frag"/> is the most prominent example: it is designed to make all
of the practically useful checks for IP fragmentation possible as a single
bitwise match.
</p>
<h3>Shorthands</h3>
<p>
Some matches are very commonly used, so Open vSwitch accepts shorthand
notations. In some cases, Open vSwitch also uses shorthand notations when
it displays matches. The following shorthands are defined, with their long
forms shown on the right side:
</p>
<dl>
<dt><code>eth</code></dt>
<dd><code>packet_type=(0,0)</code> (Open vSwitch 2.8 and later)</dd>
<dt><code>ip</code></dt> <dd><code>eth_type=0x0800</code></dd>
<dt><code>ipv6</code></dt> <dd><code>eth_type=0x86dd</code></dd>
<dt><code>icmp</code></dt> <dd><code>eth_type=0x0800,ip_proto=1</code></dd>
<dt><code>icmp6</code></dt> <dd><code>eth_type=0x86dd,ip_proto=58</code></dd>
<dt><code>tcp</code></dt> <dd><code>eth_type=0x0800,ip_proto=6</code></dd>
<dt><code>tcp6</code></dt> <dd><code>eth_type=0x86dd,ip_proto=6</code></dd>
<dt><code>udp</code></dt> <dd><code>eth_type=0x0800,ip_proto=17</code></dd>
<dt><code>udp6</code></dt> <dd><code>eth_type=0x86dd,ip_proto=17</code></dd>
<dt><code>sctp</code></dt> <dd><code>eth_type=0x0800,ip_proto=132</code></dd>
<dt><code>sctp6</code></dt> <dd><code>eth_type=0x86dd,ip_proto=132</code></dd>
<dt><code>arp</code></dt> <dd><code>eth_type=0x0806</code></dd>
<dt><code>rarp</code></dt> <dd><code>eth_type=0x8035</code></dd>
<dt><code>mpls</code></dt> <dd><code>eth_type=0x8847</code></dd>
<dt><code>mplsm</code></dt> <dd><code>eth_type=0x8848</code></dd>
</dl>
<h2>Evolution of OpenFlow Fields</h2>
<p>
The discussion so far applies to all OpenFlow and Open vSwitch
versions. This section starts to draw in specific information by
explaining, in broad terms, the treatment of fields and matches in
each OpenFlow version.
</p>
<h3>OpenFlow 1.0</h3>
<p>
OpenFlow 1.0 defined the OpenFlow protocol format of a match as a
fixed-length data structure that could match on the following
fields:
</p>
<ul>
<li>Ingress port.</li>
<li>Ethernet source and destination MAC.</li>
<li>Ethertype (with a special value to match frames that lack an
Ethertype).</li>
<li>VLAN ID and priority.</li>
<li>IPv4 source, destination, protocol, and DSCP.</li>
<li>TCP source and destination port.</li>
<li>UDP source and destination port.</li>
<li>ICMPv4 type and code.</li>
<li>ARP IPv4 addresses (SPA and TPA) and opcode.</li>
</ul>
<p>
Each supported field corresponded to some member of the data
structure. Some members represented multiple fields, in the case
of the TCP, UDP, ICMPv4, and ARP fields whose presence is mutually
exclusive. This also meant that some members were poor fits for
their fields: only the low 8 bits of the 16-bit ARP opcode could
be represented, and the ICMPv4 type and code were padded with 8 bits
of zeros to fit in the 16-bit members primarily meant for TCP and
UDP ports. An additional bitmap member indicated, for each
member, whether its field should be an ``exact'' or ``wildcarded''
match (see <cite>Matching</cite>), with additional support for
CIDR prefix matching on the IPv4 source and destination fields.
</p>
<p>
Simplicity was recognized early on as the main virtue of this
approach. Obviously, any fixed-length data structure cannot
support matching new protocols that do not fit. There was no
room, for example, for matching IPv6 fields, which was not a
priority at the time. Lack of room to support matching the
Ethernet addresses inside ARP packets actually caused more of a
design problem later, leading to an Open vSwitch extension action
specialized for dropping ``spoofed'' ARP packets in which the
frame and ARP Ethernet source addressed differed. (This extension
was never standardized. Open vSwitch dropped support for it a few
releases after it added support for full ARP matching.)
</p>
<p>
The design of the OpenFlow fixed-length matches also illustrates
compromises, in both directions, between the strengths and
weaknesses of software and hardware that have always influenced
the design of OpenFlow. Support for matching ARP fields that do
fit in the data structure was only added late in the design
process (and remained optional in OpenFlow 1.0), for example,
because common switch ASICs did not support matching these fields.
</p>
<p>
The compromises in favor of software occurred for more complicated
reasons. The OpenFlow designers did not know how to implement
matching in software that was fast, dynamic, and general. (A way
was later found [Srinivasan].) Thus, the designers sought to
support dynamic, general matching that would be fast in realistic
special cases, in particular when all of the matches were
<dfn>microflows</dfn>, that is, matches that specify every field
present in a packet, because such matches can be implemented as a
single hash table lookup. Contemporary research supported the
feasibility of this approach: the number of microflows in a campus
network had been measured to peak at about 10,000 [Casado, section
3.2]. (Calculations show that this can only be true in a lightly
loaded network [Pepelnjak].)
</p>
<p>
As a result, OpenFlow 1.0 required switches to treat microflow
matches as the highest possible priority. This let software
switches perform the microflow hash table lookup first. Only on
failure to match a microflow did the switch need to fall back to
checking the more general and presumed slower matches. Also, the
OpenFlow 1.0 flow match was minimally flexible, with no support
for general bitwise matching, partly on the basis that this seemed
more likely amenable to relatively efficient software
implementation. (CIDR masking for IPv4 addresses was added
relatively late in the OpenFlow 1.0 design process.)
</p>
<p>
Microflow matching was later discovered to aid some hardware
implementations. The TCAM chips used for matching in hardware do
not support priority in the same way as OpenFlow but instead tie
priority to ordering [Pagiamtzis]. Thus, adding a new match with
a priority between the priorities of existing matches can require
reordering an arbitrary number of TCAM entries. On the other
hand, when microflows are highest priority, they can be managed as
a set-aside portion of the TCAM entries.
</p>
<p>
The emphasis on matching microflows also led designers to
carefully consider the bandwidth requirements between switch and
controller: to maximize the number of microflow setups per second,
one must minimize the size of each flow's description. This
favored the fixed-length format in use, because it expressed
common TCP and UDP microflows in fewer bytes than more flexible
``type-length-value'' (TLV) formats. (Early versions of OpenFlow
also avoided TLVs in general to head off protocol fragmentation.)
</p>
<h4>Inapplicable Fields</h4>
<p>
OpenFlow 1.0 does not clearly specify how to treat inapplicable
fields. The members for inapplicable fields are always present in
the match data structure, as are the bits that indicate whether
the fields are matched, and the ``correct'' member and bit values
for inapplicable fields is unclear. OpenFlow 1.0 implementations
changed their behavior over time as priorities shifted. The early
OpenFlow reference implementation, motivated to make every flow a
microflow to enable hashing, treated inapplicable fields as exact
matches on a value of 0. Initially, this behavior was implemented
in the reference controller only.
</p>
<p>
Later, the reference switch was also changed to actually force any
wildcarded inapplicable fields into exact matches on 0. The
latter behavior sometimes caused problems, because the modified
flow was the one reported back to the controller later when it
queried the flow table, and the modifications sometimes meant that
the controller could not properly recognize the flow that it had
added. In retrospect, perhaps this problem should have alerted
the designers to a design error, but the ability to use a single
hash table was held to be more important than almost every other
consideration at the time.
</p>
<p>
When more flexible match formats were introduced much later, they
disallowed any mention of inapplicable fields as part of a match.
This raised the question of how to translate between this new
format and the OpenFlow 1.0 fixed format. It seemed somewhat
inconsistent and backward to treat fields as exact-match in one
format and forbid matching them in the other, so instead the
treatment of inapplicable fields in the fixed-length format was
changed from exact match on 0 to wildcarding. (A better
classifier had by now eliminated software performance problems
with wildcards.)
</p>
<p>
The OpenFlow 1.0.1 errata (released only in 2012) added some
additional explanation [OpenFlow 1.0.1, section 3.4], but it did
not mandate specific behavior because of variation among
implementations.
</p>
<h3>OpenFlow 1.1</h3>
<p>
The OpenFlow 1.1 protocol match format was designed as a type/length/value
(TLV) format to allow for future flexibility. The specification
standardized only a single type <code>OFPMT_STANDARD</code> (0) with a
fixed-size payload, described here. The additional fields and bitwise
masks in OpenFlow 1.1 cause this match structure to be over twice as large
as in OpenFlow 1.0, 88 bytes versus 40.
</p>
<p>
OpenFlow 1.1 added support for the following fields:
</p>
<ul>
<li>SCTP source and destination port.</li>
<li>MPLS label and traffic control (TC) fields.</li>
<li>One 64-bit register (named ``metadata'').</li>
</ul>
<p>
OpenFlow 1.1 increased the width of the ingress port number field (and all
other port numbers in the protocol) from 16 bits to 32 bits.
</p>
<p>
OpenFlow 1.1 increased matching flexibility by introducing
arbitrary bitwise matching on Ethernet and IPv4 address fields and
on the new ``metadata'' register field. Switches were not
required to support all possible masks [OpenFlow 1.1, section
4.3].
</p>
<p>
By a strict reading of the specification, OpenFlow 1.1 removed
support for matching ICMPv4 type and code [OpenFlow 1.1, section
A.2.3], but this is likely an editing error because ICMP
matching is described elsewhere [OpenFlow 1.1, Table 3, Table 4,
Figure 4]. Open vSwitch does support ICMPv4 type and code
matching with OpenFlow 1.1.
</p>
<p>
OpenFlow 1.1 avoided the pitfalls of inapplicable fields that
OpenFlow 1.0 encountered, by requiring the switch to ignore the
specified field values [OpenFlow 1.1, section A.2.3]. It also
implied that the switch should ignore the bits that indicate
whether to match inapplicable fields.
</p>
<h4>Physical Ingress Port</h4>
<p>
OpenFlow 1.1 introduced a new pseudo-field, the physical ingress port. The
physical ingress port is only a pseudo-field because it cannot be used for
matching. It appears only one place in the protocol, in the ``packet-in''
message that passes a packet received at the switch to an OpenFlow
controller.
</p>
<p>
A packet's ingress port and physical ingress port are identical except for
packets processed by a switch feature such as bonding or tunneling that
makes a packet appear to arrive on a ``virtual'' port associated with the
bond or the tunnel. For such packets, the ingress port is the virtual port
and the physical ingress port is, naturally, the physical port. Open
vSwitch implements both bonding and tunneling, but its bonding
implementation does not use virtual ports and its tunnels are typically not
on the same OpenFlow switch as their physical ingress ports (which need not
be part of any switch), so the ingress port and physical ingress port are
always the same in Open vSwitch.
</p>
<h3>OpenFlow 1.2</h3>
<p>
OpenFlow 1.2 abandoned the fixed-length approach to matching. One reason
was size, since adding support for IPv6 address matching (now seen as
important), with bitwise masks, would have added 64 bytes to the match
length, increasing it from 88 bytes in OpenFlow 1.1 to over 150 bytes.
Extensibility had also become important as controller writers increasingly
wanted support for new fields without having to change messages throughout
the OpenFlow protocol. The challenges of carefully defining fixed-length
matches to avoid problems with inapplicable fields had also become clear
over time.
</p>
<p>
Therefore, OpenFlow 1.2 adopted a flow format using a flexible
type-length-value (TLV) representation, in which each TLV expresses a match
on one field. These TLVs were in turn encapsulated inside the outer TLV
wrapper introduced in OpenFlow 1.1 with the new identifier
<code>OFPMT_OXM</code> (1). (This wrapper fulfilled its intended purpose
of reducing the amount of churn in the protocol when changing match
formats; some messages that included matches remained unchanged from
OpenFlow 1.1 to 1.2 and later versions.)
</p>
<p>
OpenFlow 1.2 added support for the following fields:
</p>
<ul>
<li>ARP hardware addresses (SHA and THA).</li>
<li>IPv4 ECN.</li>
<li>IPv6 source and destination addresses, flow label, DSCP, ECN,
and protocol.</li>
<li>TCP, UDP, and SCTP port numbers when encapsulated inside IPv6.</li>
<li>ICMPv6 type and code.</li>
<li>ICMPv6 Neighbor Discovery target address and source and target
Ethernet addresses.</li>
</ul>
<!-- mention tun_id_from_cookie extension? -->
<p>
The OpenFlow 1.2 format, called <dfn>OXM</dfn> (<dfn>OpenFlow Extensible
Match</dfn>), was modeled closely on an extension to OpenFlow 1.0
introduced in Open vSwitch 1.1 called <dfn>NXM</dfn> (<dfn>Nicira Extended
Match</dfn>). Each OXM or NXM TLV has the following format:
</p>
<diagram>
<header name="type">
<bits name="vendor/class" above="16" width=".75"/>
<bits name="field" above="7" width=".4"/>
</header>
<nospace/>
<header name="">
<bits name="HM" above="1" width=".25"/>
<bits name="length" above="8" width=".4"/>
</header>
<header name="">
<bits name="body" above="length bytes" width="1.7"/>
</header>
</diagram>
<p>
The most significant 16 bits of the NXM or OXM header, called
<code>vendor</code> by NXM and <code>class</code> by OXM, identify
an organization permitted to allocate identifiers for fields. NXM
allocates only two vendors, 0x0000 for fields supported by
OpenFlow 1.0 and 0x0001 for fields implemented as an Open vSwitch
extension. OXM assigns classes as follows:
</p>
<dl>
<dt>0x0000 (<code>OFPXMC_NXM_0</code>).</dt>
<dt>0x0001 (<code>OFPXMC_NXM_1</code>).</dt>
<dd>Reserved for NXM compatibility.</dd>
<dt>0x0002 to 0x7fff</dt>
<dd>
Reserved for allocation to ONF members, but none yet assigned.
</dd>
<dt>0x8000 (<code>OFPXMC_OPENFLOW_BASIC</code>)</dt>
<dd>
Used for most standard OpenFlow fields.
</dd>
<dt>0x8001 (<code>OFPXMC_PACKET_REGS</code>)</dt>
<dd>
Used for packet register fields in OpenFlow 1.5 and later.
</dd>
<dt>0x8002 to 0xfffe</dt>
<dd>
Reserved for the OpenFlow specification.
</dd>
<dt>0xffff (<code>OFPXMC_EXPERIMENTER</code>)</dt>
<dd>Experimental use.</dd>
</dl>
<p>
When <code>class</code> is 0xffff, the OXM header is extended to 64 bits by
using the first 32 bits of the body as an <code>experimenter</code> field
whose most significant byte is zero and whose remaining bytes are an
Organizationally Unique Identifier (OUI) assigned by the IEEE [IEEE OUI],
as shown below.
</p>
<diagram>
<header name="type">
<bits name="class" above="16" below="0xffff" width=".75"/>
<bits name="field" above="7" width=".4"/>
</header>
<nospace/>
<header name="">
<bits name="HM" above="1" width=".25"/>
<bits name="length" above="8" width=".4"/>
</header>
<header name="experimenter">
<bits name="zero" above="8" below="0x00" width=".4"/>
<bits name="OUI" above="24" width="1"/>
</header>
<header name="">
<bits name="body" above="(length - 4) bytes" width="1.7"/>
</header>
</diagram>
<p>
OpenFlow says that support for experimenter fields is optional. Open
vSwitch 2.4 and later does support them, so that it can support the
following experimenter classes:
</p>
<dl>
<dt>0x4f4e4600 (<code>ONFOXM_ET</code>)</dt>
<dd>
Used by official Open Networking Foundation extensions in OpenFlow 1.3
and later.
e.g. [TCP Flags Match Field Extension].
</dd>
<dt>0x005ad650 (<code>NXOXM_NSH</code>)</dt>
<dd>
Used by Open vSwitch for NSH extensions, in the absence of an official
ONF-assigned class. (This OUI is randomly generated.)
</dd>
</dl>
<p>
Taken as a unit, <code>class</code> (or <code>vendor</code>),
<code>field</code>, and <code>experimenter</code> (when present) uniquely
identify a particular field.
</p>
<p>
When <code>hasmask</code> (abbreviated <code>HM</code> above) is 0, the OXM
is an exact match on an entire field. In this case, the body (excluding
the experimenter field, if present) is a single value to be matched.
</p>
<p>
When <code>hasmask</code> is 1, the OXM is a bitwise match. The body
(excluding the experimenter field) consists of a value to match, followed
by the bitwise mask to apply. A 1-bit in the mask indicates that the
corresponding bit in the value should be matched and a 0-bit that it should
be ignored. For example, for an IP address field, a value of 192.168.0.0
followed by a mask of 255.255.0.0 would match addresses in the
196.168.0.0/16 subnet.
</p>
<ul>
<li>
Some fields might not support masking at all, and some fields that do
support masking might restrict it to certain patterns. For example,
fields that have IP address values might be restricted to CIDR masks.
The descriptions of individual fields note these restrictions.
</li>
<li>
An OXM TLV with a mask that is all zeros is not useful (although it is
not forbidden), because it is has the same effect as omitting the TLV
entirely.
</li>
<li>
It is not meaningful to pair a 0-bit in an OXM mask with a 1-bit in its
value, and Open vSwitch rejects such an OXM with the error
<code>OFPBMC_BAD_WILDCARDS</code>, as required by OpenFlow 1.3 and later.
</li>
</ul>
<p>
The <code>length</code> identifies the number of bytes in the body,
including the 4-byte <code>experimenter</code> header, if it is present.
Each OXM TLV has a fixed length; that is, given <code>class</code>,
<code>field</code>, <code>experimenter</code> (if present), and
<code>hasmask</code>, <code>length</code> is a constant. The
<code>length</code> is included explicitly to allow software to minimally
parse OXM TLVs of unknown types.
</p>
<p>
OXM TLVs must be ordered so that a field's prerequisites are satisfied
before it is parsed. For example, an OXM TLV that matches on the IPv4
source address field is only allowed following an OXM TLV that matches on
the Ethertype for IPv4. Similarly, an OXM TLV that matches on the TCP
source port must follow a TLV that matches an Ethertype of IPv4 or IPv6 and
one that matches an IP protocol of TCP (in that order). The order of OXM
TLVs is not otherwise restricted; no canonical ordering is defined.
</p>
<p>
A given field may be matched only once in a series of OXM TLVs.
</p>
<!-- EXT-482? -->
<h3>OpenFlow 1.3</h3>
<p>
OpenFlow 1.3 showed OXM to be largely successful, by adding new fields
without making any changes to how flow matches otherwise worked. It added
OXMs for the following fields supported by Open vSwitch:
</p>
<ul>
<li>Tunnel ID for ports associated with e.g. VXLAN or keyed GRE.</li>
<li>MPLS ``bottom of stack'' (BOS) bit.</li>
</ul>
<p>
OpenFlow 1.3 also added OXMs for the following fields not documented here
and not yet implemented by Open vSwitch:
</p>
<ul>
<li>IPv6 extension header handling.</li>
<li>PBB I-SID.</li>
</ul>
<h3>OpenFlow 1.4</h3>
<p>
OpenFlow 1.4 added OXMs for the following fields not documented here and
not yet implemented by Open vSwitch:
</p>
<ul>
<li>PBB UCA.</li>
</ul>
<h3>OpenFlow 1.5</h3>
<p>
OpenFlow 1.5 added OXMs for the following fields supported by Open vSwitch:
</p>
<ul>
<li>Packet type.</li>
<li>TCP flags.</li>
<li>Packet registers.</li>
<li>The output port in the OpenFlow action set.</li>
</ul>
<h1>Fields Reference</h1>
<p>
The following sections document the fields that Open vSwitch supports.
Each section provides introductory material on a group of related fields,
followed by information on each individual field. In addition to
field-specific information, each field begins with a table with entries for
the following important properties:
</p>
<dl>
<dt>Name</dt>
<dd>
The field's name, used for parsing and formatting the field, e.g. in
<code>ovs-ofctl</code> commands. For historical reasons, some fields
have an additional name that is accepted as an alternative in parsing.
This name, when there is one, is listed as well, e.g. ``<code>tun</code>
(aka <code>tunnel_id</code>).''
</dd>
<dt>Width</dt>
<dd>
The field's width, always a multiple of 8 bits. Some fields don't use
all of the bits, so this may be accompanied by an explanation. For
example, OpenFlow embeds the 2-bit IP ECN field as as the low bits in an
8-bit byte, and so its width is expressed as ``8 bits (only the
least-significant 2 bits may be nonzero).''
</dd>
<dt>Format</dt>
<dd>
<p>
How a value for the field is formatted or parsed by, e.g.,
<code>ovs-ofctl</code>. Some possibilities are generic:
</p>
<dl>
<dt>decimal</dt>
<dd>
Formats as a decimal number. On input, accepts decimal numbers or
hexadecimal numbers prefixed by <code>0x</code>.
</dd>
<dt>hexadecimal</dt>
<dd>
Formats as a hexadecimal number prefixed by <code>0x</code>. On
input, accepts decimal numbers or hexadecimal numbers prefixed by
<code>0x</code>. (The default for parsing is <em>not</em>
hexadecimal: only a <code>0x</code> prefix causes input to be treated
as hexadecimal.)
</dd>
<dt>Ethernet</dt>
<dd>
Formats and accepts the common Ethernet address format
<code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code>.
</dd>
<dt>IPv4</dt>
<dd>
Formats and accepts the dotted-quad format
<code><var>a</var>.<var>b</var>.<var>c</var>.<var>d</var></code>.
For bitwise matches, formats and accepts
<code><var>address</var>/<var>length</var></code> CIDR notation in
addition to <code><var>address</var>/<var>mask</var></code>.
</dd>
<dt>IPv6</dt>
<dd>
Formats and accepts the common IPv6 address formats, plus CIDR
notation for bitwise matches.
</dd>
<dt>OpenFlow 1.0 port</dt>
<dd>
Accepts 16-bit port numbers in decimal, plus OpenFlow well-known port
names (e.g. <code>IN_PORT</code>) in uppercase or lowercase.
</dd>
<dt>OpenFlow 1.1+ port</dt>
<dd>
Same syntax as OpenFlow 1.0 ports but for 32-bit OpenFlow 1.1+ port
number fields.
</dd>
</dl>
<p>
Other, field-specific formats are explained along with their fields.
</p>
</dd>
<dt>Masking</dt>
<dd>
For most fields, this says ``arbitrary bitwise masks,'' meaning that a
flow may match any combination of bits in the field. Some fields
instead say ``exact match only,'' which means that a flow that matches
on this field must match on the whole field instead of just certain
bits. Either way, this reports masking support for the latest version
of Open vSwitch using OXM or NXM (that is, either OpenFlow 1.2+ or
OpenFlow 1.0 plus Open vSwitch NXM extensions). In particular,
OpenFlow 1.0 (without NXM) and 1.1 don't always support masking even if
Open vSwitch itself does; refer to the <em>OpenFlow 1.0</em> and
<em>OpenFlow 1.1</em> rows to learn about masking with these protocol
versions.
</dd>
<dt>Prerequisites</dt>
<dd>
<p>
Requirements that must be met to match on this field. For example,
<ref field="ip_src"/> has IPv4 as a prerequisite, meaning that a match
must include <code>eth_type=0x0800</code> to match on the IPv4 source
address. The following prerequisites, with their requirements, are
currently in use:
</p>
<dl>
<dt>none</dt>
<dd>(no requirements)</dd>
<dt>VLAN VID</dt>
<dd><code>vlan_tci=0x1000/0x1000</code> (i.e. a VLAN header is
present)</dd>
<dt>ARP</dt>
<dd><code>eth_type=0x0806</code> (ARP) or <code>eth_type=0x8035</code> (RARP)</dd>
<dt>IPv4</dt>
<dd><code>eth_type=0x0800</code></dd>
<dt>IPv6</dt>
<dd><code>eth_type=0x86dd</code></dd>
<dt>IPv4/IPv6</dt>
<dd>IPv4 or IPv6</dd>
<dt>MPLS</dt>
<dd><code>eth_type=0x8847</code> or <code>eth_type=0x8848</code></dd>
<dt>TCP</dt>
<dd>IPv4/IPv6 and <code>ip_proto=6</code></dd>
<dt>UDP</dt>
<dd>IPv4/IPv6 and <code>ip_proto=17</code></dd>
<dt>SCTP</dt>
<dd>IPv4/IPv6 and <code>ip_proto=132</code></dd>
<dt>ICMPv4</dt>