Why does the IETF YANG ACL model (RFC 8519) key its rules by name yet mark them ordered-by user, and what changes for a client?

seniorshould knowfreq 10%

answer

identity versus position
who owns the order
first matching rule wins
first, last, before, after
re-sending does not move

basics

~20 s

In YANG, ordered-by user makes the server keep list entries in the order the client sets, which an ACL needs because the first matching rule decides; keying rules by name keeps each rule's identity stable while its position changes.

solid answer

~50 s

YANG lists default to ordered-by system: the server may order entries as it likes, and SHOULD do so deterministically so equal configurations diff cleanly. That breaks an ACL, where RFC 8519 applies the actions of the first matching entry and skips the rest, so its ace list is ordered-by user and the server keeps the client's order. Identity and position are then separate: an ACE keyed by name keeps its name when it moves, and nothing is renumbered. The client owns the ordering. In NETCONF <edit-config> it sets the insert attribute to first, last, before or after, with key naming the anchor entry for the last two; a create without insert goes last; a merge of an existing entry without insert leaves it where it is; RESTCONF offers insert and point query parameters for the same job.

YANG lists default to `ordered-by system`: the server may order entries as it likes, and SHOULD do so deterministically so equal configurations diff cleanly. That breaks an ACL, where RFC 8519 applies the actions of the first matching entry and skips the rest, so its `ace` list is `ordered-by user` and the server keeps the client's order. Identity and position are then separate: an ACE keyed by `name` keeps its name when it moves, and nothing is renumbered. The client owns the ordering. In NETCONF `<edit-config>` it sets the `insert` attribute to `first`, `last`, `before` or `after`, with `key` naming the anchor entry for the last two; a create without `insert` goes last; a merge of an existing entry without `insert` leaves it where it is; RESTCONF offers `insert` and `point` query parameters for the same job.

code

xml · 20 lines

xml

<rpc message-id="101"
     xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
     xmlns:yang="urn:ietf:params:xml:ns:yang:1">
  <edit-config>
    <target><candidate/></target>
    <config>
      <acls xmlns="urn:ietf:params:xml:ns:yang:ietf-access-control-list"
            xmlns:acl="urn:ietf:params:xml:ns:yang:ietf-access-control-list">
        <acl>
          <name>edge-in</name>
          <aces>
            <ace yang:insert="before" yang:key="[acl:name='permit-web']">
              <name>deny-telnet</name>
            </ace>
          </aces>
        </acl>
      </acls>
    </config>
  </edit-config>
</rpc>

go deeper

for a junior

Recall the two styles: ordered-by system lets the server order entries, ordered-by user keeps the order the client sets, and ACL rules need the second.

for a middle

Explain the insert attribute's four values, the key attribute for before and after, and that a create without insert lands last.

for a senior

Show the operational traps: merge does not reorder existing entries, sorted diffs hide behaviour changes, and name keys make a move one edit instead of renumbering.

for a principal

Weigh name keys with user order against sequence-number keys with system order when standardising policy models across many device types and automation tools.

Two ordering styles

YANG lists and leaf-lists come in two ordering styles, chosen with the ordered-by statement (RFC 7950 §7.7.7):

	`ordered-by system` (default)	`ordered-by user`
who decides the order	the server	the client
what the server must do	any reasonable order; SHOULD be the same for the same data	keep exactly the order the client set
typical data	user accounts, interfaces	packet filter rules, policy statements
how a client positions an entry	it cannot	`insert` with `first`, `last`, `before`, `after`

For a system-ordered list the RFC adds that an implementation SHOULD use the same order for the same data, regardless of how the data were created, so that two equal configurations compare equal with a plain diff. ordered-by is ignored entirely on state data, RPC output and notification content.

Why an ACL needs user order

RFC 7950 §7.7.1 uses exactly this case to motivate the statement: whether a rule that discards all TCP traffic comes before or after a rule that allows traffic from trusted interfaces decides what happens to a packet. RFC 8519, the IETF access control list model, makes it normative for ACLs: an ACL is an ordered list of entries (ACEs), and the actions of the first matching ACE are applied with no processing of subsequent ACEs. A server free to sort ACEs alphabetically would silently change what the filter does.

So RFC 8519 declares its ace list with key "name" and ordered-by user.

The same test applies to any list a device evaluates in sequence: policy terms tried until one matches, a preference-ordered list of servers to try, a leaf-list of addresses where the first is primary. If reordering the entries changes behaviour, the list is user-ordered; if it changes nothing but presentation, leave it system-ordered and let the server sort it, because user ordering puts real work on every client.

Keys and positions are separate things

A key is an entry's identity; with ordered-by user, its position is separate state the server preserves. Two designs follow from that choice:

Key by name, order by user (RFC 8519's choice): moving a rule changes only its position. Its name, and anything that refers to it, stays the same. Nothing is renumbered.
Key by a sequence number, order by system: the order is derived from the key. Inserting between rules 10 and 20 needs a free number, and inserting between 10 and 11 means renumbering — which, since the key is the identity, means deleting and re-creating entries.

How a NETCONF client controls the order

In <edit-config>, an ordered-by user list accepts two attributes in the YANG XML namespace (urn:ietf:params:xml:ns:yang:1), per RFC 7950 §7.8.6:

insert takes first, last, before or after.
For before and after, key MUST name an existing entry, written as the key predicates of its instance identifier, such as [acl:name='permit-web'].
With create, the attributes place a new entry; without insert, the new entry goes last.
With merge or replace, they place a new entry or move an existing one. Without them, an existing entry is not moved.
Several entries in one request are handled one at a time, in the order of the XML elements.
A <copy-config>, or a replace covering the whole list, sets the order to the order of the elements in the request.

The positioning attributes are an error on any list that is not ordered-by user; a leaf-list uses value instead of key to name the anchor value. RESTCONF (RFC 8040) carries the same control as its insert and point query parameters, and JSON encoding (RFC 7951) keeps array order by the same rules.

Operational traps

Re-sending a reordered ACL with merge changes nothing. Each existing entry stays put unless insert says otherwise; replace the whole list, or move entries explicitly.
Sorting before diffing hides real changes. On a user-ordered list a reorder is a behaviour change, so a drift check must compare order, not just membership.
Order lives in configuration only. ordered-by is ignored on state lists, so the order in which a device reports a state list carries no meaning a client can rely on.
Moving a rule is one edit. With name keys, a move is a single merge (the default operation of <edit-config>) with insert="before", as the example shows.

## Two ordering styles YANG lists and leaf-lists come in two ordering styles, chosen with the `ordered-by` statement (RFC 7950 §7.7.7): | | `ordered-by system` (default) | `ordered-by user` | |---|---|---| | who decides the order | the server | the client | | what the server must do | any reasonable order; SHOULD be the same for the same data | keep exactly the order the client set | | typical data | user accounts, interfaces | packet filter rules, policy statements | | how a client positions an entry | it cannot | `insert` with `first`, `last`, `before`, `after` | For a system-ordered list the RFC adds that an implementation **SHOULD use the same order for the same data, regardless of how the data were created**, so that two equal configurations compare equal with a plain diff. `ordered-by` is ignored entirely on state data, RPC output and notification content. ## Why an ACL needs user order RFC 7950 §7.7.1 uses exactly this case to motivate the statement: whether a rule that discards all TCP traffic comes before or after a rule that allows traffic from trusted interfaces decides what happens to a packet. RFC 8519, the IETF access control list model, makes it normative for ACLs: an ACL is an ordered list of entries (ACEs), and **the actions of the first matching ACE are applied with no processing of subsequent ACEs**. A server free to sort ACEs alphabetically would silently change what the filter does. So RFC 8519 declares its `ace` list with `key "name"` and `ordered-by user`. The same test applies to any list a device evaluates in sequence: policy terms tried until one matches, a preference-ordered list of servers to try, a leaf-list of addresses where the first is primary. If reordering the entries changes behaviour, the list is user-ordered; if it changes nothing but presentation, leave it system-ordered and let the server sort it, because user ordering puts real work on every client. ## Keys and positions are separate things A key is an entry's **identity**; with `ordered-by user`, its **position** is separate state the server preserves. Two designs follow from that choice: - **Key by name, order by user** (RFC 8519's choice): moving a rule changes only its position. Its name, and anything that refers to it, stays the same. Nothing is renumbered. - **Key by a sequence number, order by system**: the order is derived from the key. Inserting between rules 10 and 20 needs a free number, and inserting between 10 and 11 means renumbering — which, since the key is the identity, means deleting and re-creating entries. ## How a NETCONF client controls the order In `<edit-config>`, an `ordered-by user` list accepts two attributes in the YANG XML namespace (`urn:ietf:params:xml:ns:yang:1`), per RFC 7950 §7.8.6: 1. `insert` takes `first`, `last`, `before` or `after`. 2. For `before` and `after`, `key` MUST name an existing entry, written as the key predicates of its instance identifier, such as `[acl:name='permit-web']`. 3. With `create`, the attributes place a new entry; without `insert`, the new entry goes **last**. 4. With `merge` or `replace`, they place a new entry or **move an existing one**. Without them, an existing entry **is not moved**. 5. Several entries in one request are handled one at a time, in the order of the XML elements. 6. A `<copy-config>`, or a `replace` covering the whole list, sets the order to the order of the elements in the request. The positioning attributes are an error on any list that is not `ordered-by user`; a leaf-list uses `value` instead of `key` to name the anchor value. RESTCONF (RFC 8040) carries the same control as its `insert` and `point` query parameters, and JSON encoding (RFC 7951) keeps array order by the same rules. ## Operational traps - **Re-sending a reordered ACL with merge changes nothing.** Each existing entry stays put unless `insert` says otherwise; replace the whole list, or move entries explicitly. - **Sorting before diffing hides real changes.** On a user-ordered list a reorder is a behaviour change, so a drift check must compare order, not just membership. - **Order lives in configuration only.** `ordered-by` is ignored on state lists, so the order in which a device reports a state list carries no meaning a client can rely on. - **Moving a rule is one edit.** With name keys, a move is a single `merge` (the default operation of `<edit-config>`) with `insert="before"`, as the example shows.

A client re-sends a whole ACL with merge in a new order; why does nothing move?
For an existing entry of an `ordered-by user` list, NETCONF's merge or replace moves it only when `insert` is present (with `key` for `before` and `after`); otherwise the entry stays where it was. To set the order wholesale, replace the entire list or use `<copy-config>`; then the order is the order of the elements in the request.
Why should a server keep a system-ordered list in a deterministic order?
RFC 7950 says an implementation SHOULD use the same order for the same data regardless of how it was created. Then two retrievals of equal configurations compare equal with a plain line diff; without it, backups and drift checks report changes that are only reordering.
What happens if a NETCONF client sends positioning attributes on a list that is ordered-by system?
RFC 7950's payload-parsing rules make the server reply with an `unknown-attribute` error when positioning appears on any element that is not a list whose `ordered-by` property is `user`. Where the server owns the order, a client-chosen position has no meaning.

saying these in an interview costs you the question

ordered-by user means entries are sorted by their key values.
Re-sending entries in a new order with merge reorders an ordered-by user list.
With ordered-by system, the server must return entries in creation order.
ordered-by user on a config false list fixes the order a device reports.
A NETCONF create without an insert attribute puts the new entry first.

Why does the IETF YANG ACL model (RFC 8519) key its rules by name yet mark them ordered-by user, and what changes for a client?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

Two ordering styles

Why an ACL needs user order

Keys and positions are separate things

How a NETCONF client controls the order

Operational traps

▾common follow-ups3 questions

▾red flags5 flags

Two ordering styles

Why an ACL needs user order

Keys and positions are separate things

How a NETCONF client controls the order

Operational traps

answer

go deeper