RFC 8519
YANG Data Model for Network Access Control Lists (ACLs)
Appendix A. Extending ACL Model Examples
A.1. Example of a Company's Proprietary Module
The "example-newco-acl" module is an example of a company's proprietary model that augments the "ietf-acl" module. It shows how to use 'augment' with an XML Path Language (XPath) expression to add additional match criteria, actions, and default actions for when no ACE matches are found. All these are company proprietary extensions or system feature extensions. "example-newco-acl" is just an example, and it is expected that vendors will create their own proprietary models. module example-newco-acl { yang-version 1.1; namespace "http://example.com/ns/example-newco-acl"; prefix example-newco-acl; import ietf-access-control-list { prefix acl; } organization "Newco model group."; contact "abc@newco.com"; description "This YANG module augments the IETF ACL YANG module."; revision 2019-03-04 { description "Creating NewCo proprietary extensions to the ietf-acl model."; reference "RFC 8519: YANG Data Model for Network Access Control Lists (ACLs)."; } augment "/acl:acls/acl:acl/" + "acl:aces/acl:ace/" + "acl:matches" { description "Newco proprietary simple filter matches.";
choice protocol-payload-choice {
description
"Newco proprietary payload match condition.";
list protocol-payload {
key "value-keyword";
ordered-by user;
description
"Match protocol payload.";
uses match-simple-payload-protocol-value;
}
}
choice metadata {
description
"Newco proprietary interface match condition.";
leaf packet-length {
type uint16;
description
"Match on packet length.";
}
}
}
augment "/acl:acls/acl:acl/"
+ "acl:aces/acl:ace/"
+ "acl:actions" {
description
"Newco proprietary simple filter actions.";
choice action {
description
"Newco proprietary action choices.";
case count {
description
"Count the packet in the named counter.";
leaf count {
type uint32;
description
"Count.";
}
}
case policer {
description
"Name of policer used to rate-limit traffic.";
leaf policer {
type string;
description
"Name of the policer.";
}
}
case hierarchical-policer {
leaf hierarchical-policer {
type string;
description
"Name of the hierarchical policer.";
}
description
"Name of the hierarchical policer used to
rate-limit traffic.";
}
}
}
augment "/acl:acls/acl:acl"
+ "/acl:aces/acl:ace/"
+ "acl:actions" {
leaf default-action {
type identityref {
base acl:forwarding-action;
}
default "acl:drop";
description
"Actions that occur if no ACE is matched.";
}
description
"Newco proprietary default action.";
}
grouping match-simple-payload-protocol-value {
description
"Newco proprietary payload";
leaf value-keyword {
type enumeration {
enum icmp {
description
"Internet Control Message Protocol.";
}
enum icmp6 {
description
"Internet Control Message Protocol
Version 6.";
}
enum range {
description
"Range of values.";
}
}
description
"(null).";
}
}
}
The following figure is the tree diagram of example-newco-acl. In
this example, /ietf-acl:acls/ietf-acl:acl/ietf-acl:aces/ietf-acl:ace/
ietf-acl:matches are augmented with two new choices: protocol-
payload-choice and metadata. The protocol-payload-choice uses a
grouping with an enumeration of all supported protocol values.
Metadata matches apply to fields associated with the packet, that are
not in the packet header, such as overall packet length. In another
example, /ietf-acl:acls/ietf-acl:acl/ietf-acl:aces/ietf-acl:ace/
ietf-acl:actions are augmented with a new choice of actions.
module: example-newco-acl
augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:matches:
+--rw (protocol-payload-choice)?
| +--:(protocol-payload)
| +--rw protocol-payload* [value-keyword]
| +--rw value-keyword enumeration
+--rw (metadata)?
+--:(packet-length)
+--rw packet-length? uint16
augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:actions:
+--rw (action)?
+--:(count)
| +--rw count? uint32
+--:(policer)
| +--rw policer? string
+--:(hierarchical-policer)
+--rw hierarchical-policer? string
augment /acl:acls/acl:acl/acl:aces/acl:ace/acl:actions:
+--rw default-action? identityref
A.2. Linux nftables
As the Linux platform is becoming more popular than the networking
platform, the Linux data model is changing. Previously, ACLs in
Linux were highly protocol specific, and different utilities were
used (iptables, ip6tables, arptables, and ebtables), so each one had
a separate data model. Recently, this has changed, and a single
utility, nftables, has been developed. With a single application, it
has a single data model for firewall filters, and it follows very
similarly the ietf-access-control list module proposed in this
document. The nftables support input and output ACEs, and each ACE
can be defined with match and action.
The example in Section 4.3 can be configured using nftable tool as below. nft add table ip filter nft add chain filter input nft add rule ip filter input ip protocol tcp ip saddr \ 192.0.2.1/24 drop The configuration entries added in nftable would be: table ip filter { chain input { ip protocol tcp ip saddr 192.0.2.1/24 drop } } We can see that there are many similarities between Linux nftables and IETF ACL YANG data models and their extension models. It should be fairly easy to do translation between the ACL YANG model described in this document and Linux nftables.A.3. Ethertypes
The ACL module is dependent on the definition of Ethertypes. IEEE owns the allocation of those Ethertypes. This model is being included here to enable the definition of those types till such time that IEEE takes up the task of publication of the model that defines those Ethertypes. At that time, this model can be deprecated. <CODE BEGINS> file "ietf-ethertypes@2019-03-04.yang" module ietf-ethertypes { namespace "urn:ietf:params:xml:ns:yang:ietf-ethertypes"; prefix ethertypes; organization "IETF NETMOD (Network Modeling) Working Group."; contact "WG Web: <https://datatracker.ietf.org/wg/netmod/> WG List: <mailto:netmod@ietf.org> Editor: Mahesh Jethanandani <mjethanandani@gmail.com>"; description "This module contains common definitions for the
Ethertype used by different modules. It is a
placeholder module, till such time that IEEE
starts a project to define these Ethertypes
and publishes a standard.
At that time, this module can be deprecated.
Copyright (c) 2019 IETF Trust and the persons identified as
the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD
License set forth in Section 4.c of the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC 8519; see
the RFC itself for full legal notices.";
revision 2019-03-04 {
description
"Initial revision.";
reference
"RFC 8519: YANG Data Model for Network Access Control
Lists (ACLs).";
}
typedef ethertype {
type union {
type uint16;
type enumeration {
enum ipv4 {
value 2048;
description
"Internet Protocol version 4 (IPv4) with a
hex value of 0x0800.";
reference
"RFC 791: Internet Protocol.";
}
enum arp {
value 2054;
description
"Address Resolution Protocol (ARP) with a
hex value of 0x0806.";
reference
"RFC 826: An Ethernet Address Resolution Protocol: Or
Converting Network Protocol Addresses to 48.bit
Ethernet Address for Transmission on Ethernet
Hardware.";
}
enum wlan {
value 2114;
description
"Wake-on-LAN. Hex value of 0x0842.";
}
enum trill {
value 8947;
description
"Transparent Interconnection of Lots of Links.
Hex value of 0x22F3.";
reference
"RFC 6325: Routing Bridges (RBridges): Base Protocol
Specification.";
}
enum srp {
value 8938;
description
"Stream Reservation Protocol. Hex value of
0x22EA.";
reference
"IEEE 801.1Q-2011.";
}
enum decnet {
value 24579;
description
"DECnet Phase IV. Hex value of 0x6003.";
}
enum rarp {
value 32821;
description
"Reverse Address Resolution Protocol.
Hex value 0x8035.";
reference
"RFC 903: A Reverse Address Resolution Protocol.";
}
enum appletalk {
value 32923;
description
"Appletalk (Ethertalk). Hex value of 0x809B.";
}
enum aarp {
value 33011;
description
"Appletalk Address Resolution Protocol. Hex value
of 0x80F3.";
}
enum vlan {
value 33024;
description
"VLAN-tagged frame (IEEE 802.1Q) and Shortest Path
Bridging IEEE 802.1aq with Network-Network
Interface (NNI) compatibility. Hex value of
0x8100.";
reference
"IEEE 802.1Q.";
}
enum ipx {
value 33079;
description
"Internetwork Packet Exchange (IPX). Hex value
of 0x8137.";
}
enum qnx {
value 33284;
description
"QNX Qnet. Hex value of 0x8204.";
}
enum ipv6 {
value 34525;
description
"Internet Protocol Version 6 (IPv6). Hex value
of 0x86DD.";
reference
"RFC 8200: Internet Protocol, Version 6 (IPv6)
Specification
RFC 8201: Path MTU Discovery for IP version 6.";
}
enum efc {
value 34824;
description
"Ethernet flow control using pause frames.
Hex value of 0x8808.";
reference
"IEEE 802.1Qbb.";
}
enum esp {
value 34825;
description
"Ethernet Slow Protocol. Hex value of 0x8809.";
reference
"IEEE 802.3-2015.";
}
enum cobranet {
value 34841;
description
"CobraNet. Hex value of 0x8819.";
}
enum mpls-unicast {
value 34887;
description
"Multiprotocol Label Switching (MPLS) unicast traffic.
Hex value of 0x8847.";
reference
"RFC 3031: Multiprotocol Label Switching Architecture.";
}
enum mpls-multicast {
value 34888;
description
"MPLS multicast traffic. Hex value of 0x8848.";
reference
"RFC 3031: Multiprotocol Label Switching Architecture.";
}
enum pppoe-discovery {
value 34915;
description
"Point-to-Point Protocol over Ethernet. Used during
the discovery process. Hex value of 0x8863.";
reference
"RFC 2516: A Method for Transmitting PPP Over Ethernet
(PPPoE).";
}
enum pppoe-session {
value 34916;
description
"Point-to-Point Protocol over Ethernet. Used during
session stage. Hex value of 0x8864.";
reference
"RFC 2516: A Method for Transmitting PPP Over Ethernet
(PPPoE).";
}
enum intel-ans {
value 34925;
description
"Intel Advanced Networking Services. Hex value of
0x886D.";
}
enum jumbo-frames {
value 34928;
description
"Jumbo frames or Ethernet frames with more than
1500 bytes of payload, up to 9000 bytes.";
}
enum homeplug {
value 34939;
description
"Family name for the various power line
communications. Hex value of 0x887B.";
}
enum eap {
value 34958;
description
"Ethernet Access Protocol (EAP) over LAN. Hex value
of 0x888E.";
reference
"IEEE 802.1X.";
}
enum profinet {
value 34962;
description
"PROcess FIeld Net (PROFINET). Hex value of 0x8892.";
}
enum hyperscsi {
value 34970;
description
"Small Computer System Interface (SCSI) over Ethernet.
Hex value of 0x889A.";
}
enum aoe {
value 34978;
description
"Advanced Technology Advancement (ATA) over Ethernet.
Hex value of 0x88A2.";
}
enum ethercat {
value 34980;
description
"Ethernet for Control Automation Technology (EtherCAT).
Hex value of 0x88A4.";
}
enum provider-bridging {
value 34984;
description
"Provider Bridging (802.1ad) and Shortest Path Bridging
(801.1aq). Hex value of 0x88A8.";
reference
"IEEE 802.1ad and IEEE 802.1aq).";
}
enum ethernet-powerlink {
value 34987;
description
"Ethernet Powerlink. Hex value of 0x88AB.";
}
enum goose {
value 35000;
description
"Generic Object Oriented Substation Event (GOOSE).
Hex value of 0x88B8.";
reference
"IEC/ISO 8802-2 and 8802-3.";
}
enum gse {
value 35001;
description
"Generic Substation Events. Hex value of 88B9.";
reference
"IEC 61850.";
}
enum sv {
value 35002;
description
"Sampled Value Transmission. Hex value of 0x88BA.";
reference
"IEC 61850.";
}
enum lldp {
value 35020;
description
"Link Layer Discovery Protocol (LLDP). Hex value of
0x88CC.";
reference
"IEEE 802.1AB.";
}
enum sercos {
value 35021;
description
"Sercos Interface. Hex value of 0x88CD.";
}
enum wsmp {
value 35036;
description
"WAVE Short Message Protocol (WSMP). Hex value of
0x88DC.";
}
enum homeplug-av-mme {
value 35041;
description
"HomePlug AV Mobile Management Entity (MME). Hex value
of 88E1.";
}
enum mrp {
value 35043;
description
"Media Redundancy Protocol (MRP). Hex value of
0x88E3.";
reference
"IEC 62439-2.";
}
enum macsec {
value 35045;
description
"MAC Security. Hex value of 0x88E5.";
reference
"IEEE 802.1AE.";
}
enum pbb {
value 35047;
description
"Provider Backbone Bridges (PBB). Hex value of
0x88E7.";
reference
"IEEE 802.1ah.";
}
enum cfm {
value 35074;
description
"Connectivity Fault Management (CFM). Hex value of
0x8902.";
reference
"IEEE 802.1ag.";
}
enum fcoe {
value 35078;
description
"Fiber Channel over Ethernet (FCoE). Hex value of
0x8906.";
reference
"T11 FC-BB-5.";
}
enum fcoe-ip {
value 35092;
description
"FCoE Initialization Protocol. Hex value of 0x8914.";
}
enum roce {
value 35093;
description
"RDMA over Converged Ethernet (RoCE). Hex value of
0x8915.";
}
enum tte {
value 35101;
description
"TTEthernet Protocol Control Frame (TTE). Hex value
of 0x891D.";
reference
"SAE AS6802.";
}
enum hsr {
value 35119;
description
"High-availability Seamless Redundancy (HSR). Hex
value of 0x892F.";
reference
"IEC 62439-3:2016.";
}
}
}
description
"The uint16 type placeholder is defined to enable
users to manage their own ethertypes not
covered by the module. Otherwise, the module contains
enum definitions for the more commonly used ethertypes.";
}
}
<CODE ENDS>
Acknowledgements
Alex Clemm, Andy Bierman, and Lisa Huang started by sketching an initial draft version in several past IETF meetings. That document included an ACL YANG model structure and a rich set of match filters, and it acknowledged contributions by Louis Fourie, Dana Blair, Tula Kraiser, Patrick Gili, George Serpa, Martin Bjorklund, Kent Watsen, and Phil Shafer. Many people have reviewed the various earlier draft versions that made the document that went into IETF charter. Dean Bogdanovic, Kiran Agrahara Sreenivasa, Lisa Huang, and Dana Blair each evaluated the YANG model in earlier draft versions separately, and then they worked together to create an ACL draft version that was supported by different vendors. That document removed vendor-specific features and gave examples that allowed vendors to extend their own proprietary ACLs. That earlier draft version was superseded with this document and received participation from many vendors. The authors would like to thank Jason Sterne, Lada Lhotka, Juergen Schoenwalder, David Bannister, Jeff Haas, Kristian Larsson, and Einar Nilsen-Nygaard for their reviews of and suggestions for the document.Authors' Addresses
Mahesh Jethanandani VMware Email: mjethanandani@gmail.com Sonal Agarwal Cisco Systems, Inc. Email: sagarwal12@gmail.com Lisa Huang Email: huangyi_99@yahoo.com Dana Blair Email: dana@blairhome.com