GNU Linux-libre 6.9.1-gnu
[releases.git] / Documentation / netlink / specs / ovs_flow.yaml
1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
2
3 name: ovs_flow
4 version: 1
5 protocol: genetlink-legacy
6 uapi-header: linux/openvswitch.h
7
8 doc:
9   OVS flow configuration over generic netlink.
10
11 definitions:
12   -
13     name: ovs-header
14     type: struct
15     doc: |
16       Header for OVS Generic Netlink messages.
17     members:
18       -
19         name: dp-ifindex
20         type: u32
21         doc: |
22           ifindex of local port for datapath (0 to make a request not specific
23           to a datapath).
24   -
25     name: ovs-flow-stats
26     type: struct
27     members:
28       -
29         name: n-packets
30         type: u64
31         doc: Number of matched packets.
32       -
33         name: n-bytes
34         type: u64
35         doc: Number of matched bytes.
36   -
37     name: ovs-key-ethernet
38     type: struct
39     members:
40       -
41         name: eth-src
42         type: binary
43         len: 6
44         display-hint: mac
45       -
46         name: eth-dst
47         type: binary
48         len: 6
49         display-hint: mac
50   -
51     name: ovs-key-mpls
52     type: struct
53     members:
54       -
55         name: mpls-lse
56         type: u32
57         byte-order: big-endian
58   -
59     name: ovs-key-ipv4
60     type: struct
61     members:
62       -
63         name: ipv4-src
64         type: u32
65         byte-order: big-endian
66         display-hint: ipv4
67       -
68         name: ipv4-dst
69         type: u32
70         byte-order: big-endian
71         display-hint: ipv4
72       -
73         name: ipv4-proto
74         type: u8
75       -
76         name: ipv4-tos
77         type: u8
78       -
79         name: ipv4-ttl
80         type: u8
81       -
82         name: ipv4-frag
83         type: u8
84         enum: ovs-frag-type
85   -
86     name: ovs-key-ipv6
87     type: struct
88     members:
89       -
90         name: ipv6-src
91         type: binary
92         len: 16
93         byte-order: big-endian
94         display-hint: ipv6
95       -
96         name: ipv6-dst
97         type: binary
98         len: 16
99         byte-order: big-endian
100         display-hint: ipv6
101       -
102         name: ipv6-label
103         type: u32
104         byte-order: big-endian
105       -
106         name: ipv6-proto
107         type: u8
108       -
109         name: ipv6-tclass
110         type: u8
111       -
112         name: ipv6-hlimit
113         type: u8
114       -
115         name: ipv6-frag
116         type: u8
117   -
118     name: ovs-key-ipv6-exthdrs
119     type: struct
120     members:
121       -
122         name: hdrs
123         type: u16
124   -
125     name: ovs-frag-type
126     name-prefix: ovs-frag-type-
127     enum-name: ovs-frag-type
128     type: enum
129     entries:
130       -
131         name: none
132         doc: Packet is not a fragment.
133       -
134         name: first
135         doc: Packet is a fragment with offset 0.
136       -
137         name: later
138         doc: Packet is a fragment with nonzero offset.
139       -
140         name: any
141         value: 255
142   -
143     name: ovs-key-tcp
144     type: struct
145     members:
146       -
147         name: tcp-src
148         type: u16
149         byte-order: big-endian
150       -
151         name: tcp-dst
152         type: u16
153         byte-order: big-endian
154   -
155     name: ovs-key-udp
156     type: struct
157     members:
158       -
159         name: udp-src
160         type: u16
161         byte-order: big-endian
162       -
163         name: udp-dst
164         type: u16
165         byte-order: big-endian
166   -
167     name: ovs-key-sctp
168     type: struct
169     members:
170       -
171         name: sctp-src
172         type: u16
173         byte-order: big-endian
174       -
175         name: sctp-dst
176         type: u16
177         byte-order: big-endian
178   -
179     name: ovs-key-icmp
180     type: struct
181     members:
182       -
183         name: icmp-type
184         type: u8
185       -
186         name: icmp-code
187         type: u8
188   -
189     name: ovs-key-arp
190     type: struct
191     members:
192       -
193         name: arp-sip
194         type: u32
195         byte-order: big-endian
196       -
197         name: arp-tip
198         type: u32
199         byte-order: big-endian
200       -
201         name: arp-op
202         type: u16
203         byte-order: big-endian
204       -
205         name: arp-sha
206         type: binary
207         len: 6
208         display-hint: mac
209       -
210         name: arp-tha
211         type: binary
212         len: 6
213         display-hint: mac
214   -
215     name: ovs-key-nd
216     type: struct
217     members:
218       -
219         name: nd_target
220         type: binary
221         len: 16
222         byte-order: big-endian
223       -
224         name: nd-sll
225         type: binary
226         len: 6
227         display-hint: mac
228       -
229         name: nd-tll
230         type: binary
231         len: 6
232         display-hint: mac
233   -
234     name: ovs-key-ct-tuple-ipv4
235     type: struct
236     members:
237       -
238         name: ipv4-src
239         type: u32
240         byte-order: big-endian
241       -
242         name: ipv4-dst
243         type: u32
244         byte-order: big-endian
245       -
246         name: src-port
247         type: u16
248         byte-order: big-endian
249       -
250         name: dst-port
251         type: u16
252         byte-order: big-endian
253       -
254         name: ipv4-proto
255         type: u8
256   -
257     name: ovs-action-push-vlan
258     type: struct
259     members:
260       -
261         name: vlan_tpid
262         type: u16
263         byte-order: big-endian
264         doc: Tag protocol identifier (TPID) to push.
265       -
266         name: vlan_tci
267         type: u16
268         byte-order: big-endian
269         doc: Tag control identifier (TCI) to push.
270   -
271     name: ovs-ufid-flags
272     name-prefix: ovs-ufid-f-
273     enum-name:
274     type: flags
275     entries:
276       - omit-key
277       - omit-mask
278       - omit-actions
279   -
280     name: ovs-action-hash
281     type: struct
282     members:
283       -
284         name: hash-alg
285         type: u32
286         doc: Algorithm used to compute hash prior to recirculation.
287       -
288         name: hash-basis
289         type: u32
290         doc: Basis used for computing hash.
291   -
292     name: ovs-hash-alg
293     enum-name: ovs-hash-alg
294     type: enum
295     doc: |
296       Data path hash algorithm for computing Datapath hash. The algorithm type only specifies
297       the fields in a flow will be used as part of the hash. Each datapath is free to use its
298       own hash algorithm. The hash value will be opaque to the user space daemon.
299     entries:
300       - ovs-hash-alg-l4
301
302   -
303     name: ovs-action-push-mpls
304     type: struct
305     members:
306       -
307         name: mpls-lse
308         type: u32
309         byte-order: big-endian
310         doc: |
311           MPLS label stack entry to push
312       -
313         name: mpls-ethertype
314         type: u32
315         byte-order: big-endian
316         doc: |
317           Ethertype to set in the encapsulating ethernet frame.  The only values
318           ethertype should ever be given are ETH_P_MPLS_UC and ETH_P_MPLS_MC,
319           indicating MPLS unicast or multicast. Other are rejected.
320   -
321     name: ovs-action-add-mpls
322     type: struct
323     members:
324       -
325         name: mpls-lse
326         type: u32
327         byte-order: big-endian
328         doc: |
329           MPLS label stack entry to push
330       -
331         name: mpls-ethertype
332         type: u32
333         byte-order: big-endian
334         doc: |
335           Ethertype to set in the encapsulating ethernet frame.  The only values
336           ethertype should ever be given are ETH_P_MPLS_UC and ETH_P_MPLS_MC,
337           indicating MPLS unicast or multicast. Other are rejected.
338       -
339         name: tun-flags
340         type: u16
341         doc: |
342           MPLS tunnel attributes.
343   -
344     name: ct-state-flags
345     enum-name:
346     type: flags
347     name-prefix: ovs-cs-f-
348     entries:
349       -
350         name: new
351         doc: Beginning of a new connection.
352       -
353         name: established
354         doc: Part of an existing connenction
355       -
356         name: related
357         doc: Related to an existing connection.
358       -
359         name: reply-dir
360         doc: Flow is in the reply direction.
361       -
362         name: invalid
363         doc: Could not track the connection.
364       -
365         name: tracked
366         doc: Conntrack has occurred.
367       -
368         name: src-nat
369         doc: Packet's source address/port was mangled by NAT.
370       -
371         name: dst-nat
372         doc: Packet's destination address/port was mangled by NAT.
373
374 attribute-sets:
375   -
376     name: flow-attrs
377     enum-name: ovs-flow-attr
378     name-prefix: ovs-flow-attr-
379     attributes:
380       -
381         name: key
382         type: nest
383         nested-attributes: key-attrs
384         doc: |
385           Nested attributes specifying the flow key. Always present in
386           notifications. Required for all requests (except dumps).
387       -
388         name: actions
389         type: nest
390         nested-attributes: action-attrs
391         doc: |
392           Nested attributes specifying the actions to take for packets that
393           match the key. Always present in notifications. Required for
394           OVS_FLOW_CMD_NEW requests, optional for OVS_FLOW_CMD_SET requests.  An
395           OVS_FLOW_CMD_SET without OVS_FLOW_ATTR_ACTIONS will not modify the
396           actions.  To clear the actions, an OVS_FLOW_ATTR_ACTIONS without any
397           nested attributes must be given.
398       -
399         name: stats
400         type: binary
401         struct: ovs-flow-stats
402         doc: |
403           Statistics for this flow. Present in notifications if the stats would
404           be nonzero. Ignored in requests.
405       -
406         name: tcp-flags
407         type: u8
408         doc: |
409           An 8-bit value giving the ORed value of all of the TCP flags seen on
410           packets in this flow. Only present in notifications for TCP flows, and
411           only if it would be nonzero. Ignored in requests.
412       -
413         name: used
414         type: u64
415         doc: |
416           A 64-bit integer giving the time, in milliseconds on the system
417           monotonic clock, at which a packet was last processed for this
418           flow. Only present in notifications if a packet has been processed for
419           this flow. Ignored in requests.
420       -
421         name: clear
422         type: flag
423         doc: |
424           If present in a OVS_FLOW_CMD_SET request, clears the last-used time,
425           accumulated TCP flags, and statistics for this flow.  Otherwise
426           ignored in requests. Never present in notifications.
427       -
428         name: mask
429         type: nest
430         nested-attributes: key-attrs
431         doc: |
432           Nested attributes specifying the mask bits for wildcarded flow
433           match. Mask bit value '1' specifies exact match with corresponding
434           flow key bit, while mask bit value '0' specifies a wildcarded
435           match. Omitting attribute is treated as wildcarding all corresponding
436           fields. Optional for all requests. If not present, all flow key bits
437           are exact match bits.
438       -
439         name: probe
440         type: binary
441         doc: |
442           Flow operation is a feature probe, error logging should be suppressed.
443       -
444         name: ufid
445         type: binary
446         doc: |
447           A value between 1-16 octets specifying a unique identifier for the
448           flow. Causes the flow to be indexed by this value rather than the
449           value of the OVS_FLOW_ATTR_KEY attribute. Optional for all
450           requests. Present in notifications if the flow was created with this
451           attribute.
452         display-hint: uuid
453       -
454         name: ufid-flags
455         type: u32
456         enum: ovs-ufid-flags
457         doc: |
458           A 32-bit value of ORed flags that provide alternative semantics for
459           flow installation and retrieval. Optional for all requests.
460       -
461         name: pad
462         type: binary
463
464   -
465     name: key-attrs
466     enum-name: ovs-key-attr
467     name-prefix: ovs-key-attr-
468     attributes:
469       -
470         name: encap
471         type: nest
472         nested-attributes: key-attrs
473       -
474         name: priority
475         type: u32
476       -
477         name: in-port
478         type: u32
479       -
480         name: ethernet
481         type: binary
482         struct: ovs-key-ethernet
483         doc: struct ovs_key_ethernet
484       -
485         name: vlan
486         type: u16
487         byte-order: big-endian
488       -
489         name: ethertype
490         type: u16
491         byte-order: big-endian
492       -
493         name: ipv4
494         type: binary
495         struct: ovs-key-ipv4
496       -
497         name: ipv6
498         type: binary
499         struct: ovs-key-ipv6
500         doc: struct ovs_key_ipv6
501       -
502         name: tcp
503         type: binary
504         struct: ovs-key-tcp
505       -
506         name: udp
507         type: binary
508         struct: ovs-key-udp
509       -
510         name: icmp
511         type: binary
512         struct: ovs-key-icmp
513       -
514         name: icmpv6
515         type: binary
516         struct: ovs-key-icmp
517       -
518         name: arp
519         type: binary
520         struct: ovs-key-arp
521         doc: struct ovs_key_arp
522       -
523         name: nd
524         type: binary
525         struct: ovs-key-nd
526         doc: struct ovs_key_nd
527       -
528         name: skb-mark
529         type: u32
530       -
531         name: tunnel
532         type: nest
533         nested-attributes: tunnel-key-attrs
534       -
535         name: sctp
536         type: binary
537         struct: ovs-key-sctp
538       -
539         name: tcp-flags
540         type: u16
541         byte-order: big-endian
542       -
543         name: dp-hash
544         type: u32
545         doc: Value 0 indicates the hash is not computed by the datapath.
546       -
547         name: recirc-id
548         type: u32
549       -
550         name: mpls
551         type: binary
552         struct: ovs-key-mpls
553       -
554         name: ct-state
555         type: u32
556         enum: ct-state-flags
557         enum-as-flags: true
558       -
559         name: ct-zone
560         type: u16
561         doc: connection tracking zone
562       -
563         name: ct-mark
564         type: u32
565         doc: connection tracking mark
566       -
567         name: ct-labels
568         type: binary
569         display-hint: hex
570         doc: 16-octet connection tracking label
571       -
572         name: ct-orig-tuple-ipv4
573         type: binary
574         struct: ovs-key-ct-tuple-ipv4
575       -
576         name: ct-orig-tuple-ipv6
577         type: binary
578         doc: struct ovs_key_ct_tuple_ipv6
579       -
580         name: nsh
581         type: nest
582         nested-attributes: ovs-nsh-key-attrs
583       -
584         name: packet-type
585         type: u32
586         byte-order: big-endian
587         doc: Should not be sent to the kernel
588       -
589         name: nd-extensions
590         type: binary
591         doc: Should not be sent to the kernel
592       -
593         name: tunnel-info
594         type: binary
595         doc: struct ip_tunnel_info
596       -
597         name: ipv6-exthdrs
598         type: binary
599         struct: ovs-key-ipv6-exthdrs
600         doc: struct ovs_key_ipv6_exthdr
601   -
602     name: action-attrs
603     enum-name: ovs-action-attr
604     name-prefix: ovs-action-attr-
605     attributes:
606       -
607         name: output
608         type: u32
609         doc: ovs port number in datapath
610       -
611         name: userspace
612         type: nest
613         nested-attributes: userspace-attrs
614       -
615         name: set
616         type: nest
617         nested-attributes: key-attrs
618         doc: Replaces the contents of an existing header. The single nested attribute specifies a header to modify and its value.
619       -
620         name: push-vlan
621         type: binary
622         struct: ovs-action-push-vlan
623         doc: Push a new outermost 802.1Q or 802.1ad header onto the packet.
624       -
625         name: pop-vlan
626         type: flag
627         doc: Pop the outermost 802.1Q or 802.1ad header from the packet.
628       -
629         name: sample
630         type: nest
631         nested-attributes: sample-attrs
632         doc: |
633           Probabilistically executes actions, as specified in the nested attributes.
634       -
635         name: recirc
636         type: u32
637         doc: recirc id
638       -
639         name: hash
640         type: binary
641         struct: ovs-action-hash
642       -
643         name: push-mpls
644         type: binary
645         struct: ovs-action-push-mpls
646         doc: |
647           Push a new MPLS label stack entry onto the top of the packets MPLS
648           label stack. Set the ethertype of the encapsulating frame to either
649           ETH_P_MPLS_UC or ETH_P_MPLS_MC to indicate the new packet contents.
650       -
651         name: pop-mpls
652         type: u16
653         byte-order: big-endian
654         doc: ethertype
655       -
656         name: set-masked
657         type: nest
658         nested-attributes: key-attrs
659         doc: |
660           Replaces the contents of an existing header. A nested attribute
661           specifies a header to modify, its value, and a mask. For every bit set
662           in the mask, the corresponding bit value is copied from the value to
663           the packet header field, rest of the bits are left unchanged. The
664           non-masked value bits must be passed in as zeroes. Masking is not
665           supported for the OVS_KEY_ATTR_TUNNEL attribute.
666       -
667         name: ct
668         type: nest
669         nested-attributes: ct-attrs
670         doc: |
671           Track the connection. Populate the conntrack-related entries
672           in the flow key.
673       -
674         name: trunc
675         type: u32
676         doc: struct ovs_action_trunc is a u32 max length
677       -
678         name: push-eth
679         type: binary
680         doc: struct ovs_action_push_eth
681       -
682         name: pop-eth
683         type: flag
684       -
685         name: ct-clear
686         type: flag
687       -
688         name: push-nsh
689         type: nest
690         nested-attributes: ovs-nsh-key-attrs
691         doc: |
692           Push NSH header to the packet.
693       -
694         name: pop-nsh
695         type: flag
696         doc: |
697           Pop the outermost NSH header off the packet.
698       -
699         name: meter
700         type: u32
701         doc: |
702           Run packet through a meter, which may drop the packet, or modify the
703           packet (e.g., change the DSCP field)
704       -
705         name: clone
706         type: nest
707         nested-attributes: action-attrs
708         doc: |
709           Make a copy of the packet and execute a list of actions without
710           affecting the original packet and key.
711       -
712         name: check-pkt-len
713         type: nest
714         nested-attributes: check-pkt-len-attrs
715         doc: |
716           Check the packet length and execute a set of actions if greater than
717           the specified packet length, else execute another set of actions.
718       -
719         name: add-mpls
720         type: binary
721         struct: ovs-action-add-mpls
722         doc: |
723           Push a new MPLS label stack entry at the start of the packet or at the
724           start of the l3 header depending on the value of l3 tunnel flag in the
725           tun_flags field of this OVS_ACTION_ATTR_ADD_MPLS argument.
726       -
727         name: dec-ttl
728         type: nest
729         nested-attributes: dec-ttl-attrs
730   -
731     name: tunnel-key-attrs
732     enum-name: ovs-tunnel-key-attr
733     name-prefix: ovs-tunnel-key-attr-
734     attributes:
735       -
736         name: id
737         type: u64
738         byte-order: big-endian
739         value: 0
740       -
741         name: ipv4-src
742         type: u32
743         byte-order: big-endian
744       -
745         name: ipv4-dst
746         type: u32
747         byte-order: big-endian
748       -
749         name: tos
750         type: u8
751       -
752         name: ttl
753         type: u8
754       -
755         name: dont-fragment
756         type: flag
757       -
758         name: csum
759         type: flag
760       -
761         name: oam
762         type: flag
763       -
764         name: geneve-opts
765         type: binary
766         sub-type: u32
767       -
768         name: tp-src
769         type: u16
770         byte-order: big-endian
771       -
772         name: tp-dst
773         type: u16
774         byte-order: big-endian
775       -
776         name: vxlan-opts
777         type: nest
778         nested-attributes: vxlan-ext-attrs
779       -
780         name: ipv6-src
781         type: binary
782         doc: |
783           struct in6_addr source IPv6 address
784       -
785         name: ipv6-dst
786         type: binary
787         doc: |
788           struct in6_addr destination IPv6 address
789       -
790         name: pad
791         type: binary
792       -
793         name: erspan-opts
794         type: binary
795         doc: |
796           struct erspan_metadata
797       -
798         name: ipv4-info-bridge
799         type: flag
800   -
801     name: check-pkt-len-attrs
802     enum-name: ovs-check-pkt-len-attr
803     name-prefix: ovs-check-pkt-len-attr-
804     attributes:
805       -
806         name: pkt-len
807         type: u16
808       -
809         name: actions-if-greater
810         type: nest
811         nested-attributes: action-attrs
812       -
813         name: actions-if-less-equal
814         type: nest
815         nested-attributes: action-attrs
816   -
817     name: sample-attrs
818     enum-name: ovs-sample-attr
819     name-prefix: ovs-sample-attr-
820     attributes:
821       -
822         name: probability
823         type: u32
824       -
825         name: actions
826         type: nest
827         nested-attributes: action-attrs
828   -
829     name: userspace-attrs
830     enum-name: ovs-userspace-attr
831     name-prefix: ovs-userspace-attr-
832     attributes:
833       -
834         name: pid
835         type: u32
836       -
837         name: userdata
838         type: binary
839       -
840         name: egress-tun-port
841         type: u32
842       -
843         name: actions
844         type: flag
845   -
846     name: ovs-nsh-key-attrs
847     enum-name: ovs-nsh-key-attr
848     name-prefix: ovs-nsh-key-attr-
849     attributes:
850       -
851         name: base
852         type: binary
853       -
854         name: md1
855         type: binary
856       -
857         name: md2
858         type: binary
859   -
860     name: ct-attrs
861     enum-name: ovs-ct-attr
862     name-prefix: ovs-ct-attr-
863     attributes:
864       -
865         name: commit
866         type: flag
867       -
868         name: zone
869         type: u16
870       -
871         name: mark
872         type: binary
873       -
874         name: labels
875         type: binary
876       -
877         name: helper
878         type: string
879       -
880         name: nat
881         type: nest
882         nested-attributes: nat-attrs
883       -
884         name: force-commit
885         type: flag
886       -
887         name: eventmask
888         type: u32
889       -
890         name: timeout
891         type: string
892   -
893     name: nat-attrs
894     enum-name: ovs-nat-attr
895     name-prefix: ovs-nat-attr-
896     attributes:
897       -
898         name: src
899         type: flag
900       -
901         name: dst
902         type: flag
903       -
904         name: ip-min
905         type: binary
906       -
907         name: ip-max
908         type: binary
909       -
910         name: proto-min
911         type: u16
912       -
913         name: proto-max
914         type: u16
915       -
916         name: persistent
917         type: flag
918       -
919         name: proto-hash
920         type: flag
921       -
922         name: proto-random
923         type: flag
924   -
925     name: dec-ttl-attrs
926     enum-name: ovs-dec-ttl-attr
927     name-prefix: ovs-dec-ttl-attr-
928     attributes:
929       -
930         name: action
931         type: nest
932         nested-attributes: action-attrs
933   -
934     name: vxlan-ext-attrs
935     enum-name: ovs-vxlan-ext-
936     name-prefix: ovs-vxlan-ext-
937     attributes:
938       -
939         name: gbp
940         type: u32
941
942 operations:
943   name-prefix: ovs-flow-cmd-
944   fixed-header: ovs-header
945   list:
946     -
947       name: get
948       doc: Get / dump OVS flow configuration and state
949       value: 3
950       attribute-set: flow-attrs
951       do: &flow-get-op
952         request:
953           attributes:
954             - key
955             - ufid
956             - ufid-flags
957         reply:
958           attributes:
959             - key
960             - ufid
961             - mask
962             - stats
963             - actions
964       dump: *flow-get-op
965     -
966       name: new
967       doc: Create OVS flow configuration in a data path
968       value: 1
969       attribute-set: flow-attrs
970       do:
971         request:
972           attributes:
973             - key
974             - ufid
975             - mask
976             - actions
977
978 mcast-groups:
979   list:
980     -
981       name: ovs_flow