# LU-20595 Caller Audit: Full Documentation (English)

> Related tickets: LU-20595 (cYAML_get_object_item recursive-search regression) / LU-20479 (use-after-free instance of the same root cause)
> Audit date: 2026-08-24 | Repo: /root/Lustre-Source/lustre-release_master

---

# Part A: Audit Principles

## A.1 Background

`cYAML_get_object_item()` (lnet/utils/lnetconfig/cyaml.c:716) was accidentally changed by LU-7734 (c906ab9c88, 2016) from LU-2456's (0f753ead66) "direct-children-only search" to a **recursive DFS** (parent self-match + cy_child descent + cy_next sibling walk). The fix is to restore the shallow search, but **all 136 call sites must first be verified to expect shallow semantics** — that is the purpose of this audit.

## A.2 How YAML becomes a tree (source mechanism)

### A.2.1 Parsing chain

```
User YAML text
  -> cYAML_build_tree() (cyaml.c:1404, libyaml parser wrapper)
  -> cYAML_parser_to_tree() (cyaml.c:1333)
  -> yaml_parser_scan() per token (YAML_BLOCK_MAPPING_START / BLOCK_SEQUENCE_START / SCALAR / KEY ...)
  -> dispatch_tbl[token.type] (cyaml.c:126-140) dispatch by token type
  -> state machine (yaml_key etc.) builds the tree
```

### A.2.2 The two key pointers of the tree (cyaml.c:530-543)

```c
static enum cYAML_handler_error yaml_key(...)
{
	...
	tree->cur = create_sibling(tree->cur);   /* next key at the same level -> cy_next sibling */
	...
}
```

- **`cy_child`**: YAML indentation nesting (`net type:` under `net:`) -> parent-child
- **`cy_next`**: YAML same level (`local NI(s):` after `net type:`) -> sibling

**Core rule: YAML indentation = tree level** — libyaml translates indentation into tokens, the state machine translates tokens into cy_child/cy_next. The same input always produces the same tree (deterministic).

### A.2.3 Example (net command of lnetctl import)

```yaml
net:                          <- top-level command (first cy_child of tree)
  - net type: tcp             <- sequence item (command instance node = handler's parent)
    local NI(s):              <- direct child of the command instance node
      - nid: 192.168.1.1@tcp
    interfaces: eth0
    seq_no: 4
```

```
tree (root)
+-- cy_child: "net" (sequence)
    +-- cy_child: sequence item A (command instance node) <- parent passed to handler
        +-- cy_child: "net type" -> "tcp"     <- direct child key
        +-- cy_next: "local NI(s)" -> sequence  <- direct child key
        |   +-- cy_child: item -> "nid" -> "..."
        +-- cy_next: "interfaces" -> "eth0"    <- direct child key
        +-- cy_next: "seq_no" -> "4"           <- direct child key
```

## A.3 How the dispatcher determines parent (lustre_yaml_cb_helper, liblnetconfig.c:6565-6600)

```c
tree = cYAML_build_tree(NULL, f, len, err_rc, false);   /* parse the whole YAML */
child = tree->cy_child;                                  /* first top-level command */
while (child != NULL) {
	cb = lookup_fn(child->cy_string, table);         /* find handler by command name */
	if (cYAML_is_sequence(child)) {
		while ((head = cYAML_get_next_seq_item(child, &item)) != NULL)
			rc = cb(head, show_rc, err_rc);      /* sequence: pass each item as "command instance node" */
	} else {
		rc = cb(child, show_rc, err_rc);           /* non-sequence: pass the command node itself */
	}
	child = child->cy_next;
}
```

**The `tree` argument passed to each handle_yaml_* = command instance node** (top-level command node or sequence item) — `cYAML_get_object_item(tree, "xxx")` inside the handler looks up **direct child keys** of this node.

## A.4 Judgment criteria (4-step method per call site)

1. **Locate parent origin**: which YAML node is the parent? How is it constructed? (cYAML_build_tree result / cYAML_get_object_child return / sequence item / accumulated output tree root)
2. **Determine name's level**: where does the target key sit in the YAML format? (compare in-file comments + constructor/export code)
3. **Judge semantics**:
   - parent is a command instance node / sub-object / sequence item + name is a direct child key -> **S (shallow)**
   - parent is the accumulated-output-tree root + name is a top-level block -> **S (must be shallow)** — recursion hits nested same-name keys (the regression bug itself)
   - name can only exist in a deep subtree -> **R (recursive)**
   - cannot confirm -> **U**
4. **Cross-verify**: constructor (lnetctl.c export / liblnetconfig.c create) + kernel exporter (pcc.c) confirm the structure level; compare the impact of replacing with `cYAML_get_object_child()` (the correct shallow implementation)

## A.5 Evidence chain (E1-E8)

| # | Evidence | Coverage |
|---|---|---|
| E1 | Dispatcher lustre_yaml_cb_helper (:6553) passes the **command instance node** as tree — its direct children are the config keys | 106 command-parse sites |
| E2 | cyaml.c nodes default to CYAML_TYPE_OBJECT (create_child/create_sibling set OBJECT, :301/320/590; sequence items too) — the type pre-check of cYAML_get_object_child passes for all sites | all 136 |
| E3 | No site depends on the recursive version's self-match branch (parent's cy_string never equals the searched name) | all 136 |
| E4 | 8 show-output-tree insertion sites look up **top-level blocks** (route/net/routing/peer/global/ping...) with cYAML_is_sequence check — DFS hits the `net` field inside a route entry and mistakes it for the top-level net block (the regression instance) | 8 insertion sites |
| E5 | 106 command-parse sites: names are all direct child keys of the parent (verbatim match with in-file YAML format comments); tunables/CPT/lnd tunables are already fetched via shallow child() before querying the next level | 106 parse sites |
| E6 | "lnd tunables" confirmed flat scalar by the constructor (lnetctl.c:1888-1930 exports all scalars; liblnetconfig.c:3419-3427 creates) | lnd.c 15 sites |
| E7 | udsp is a direct child of root (liblnetconfig_udsp.c:700-706 create_seq) | udsp.c 1 site |
| E8 | PCC YAML confirmed by kernel exporter (lustre/llite/pcc.c:1127-1155): `pcc:` -> flat backend objects, all scalars | pcc.c 6 sites |

---

# Part B: Audit Process for All 136 Call Sites (per file)

## B.1 liblnetconfig.c (114 sites)

Two distinct reasons, each in its own subsection:

### B.1.1 Reason 1: top-level block lookup in the show output tree (8 sites)

**Pattern**: results of multiple show commands are inserted into one accumulated output tree `*show_rc` — each time the code first looks up a same-named block at the tree top level (route/net/routing/peer/global/ping...); **if found, the current entries are inserted into that block's sequence; if not, a new block is inserted as a sibling**. The lookup must be shallow (top-level blocks exist only at the root's direct-children level).

| Line | Function | name | Parent level | Class |
|---|---|---|---|---|
| 1184 | infra_ping_nid | oper(var:"ping"/"discover") | top level of accumulated tree *show_rc | S |
| 1668 | lustre_lnet_show_route | "route" | top level of accumulated tree | S |
| 3481 | lustre_lnet_show_net | "net" | top level of accumulated tree | S |
| 4052 | lustre_lnet_show_routing | "routing" | top level of accumulated tree | S |
| 4399 | lustre_lnet_show_peer | "peer" | top level of accumulated tree | S |
| 4507 | lustre_lnet_list_peer | "peer" | top level of accumulated tree | S |
| 4535 | add_to_global | "global" | top level of show_rc | S |
| 4921 | show_recovery_queue | name(var:"local NI recovery"/"peer NI recovery") | top level of accumulated tree | S |

### B.1.2 Reason 2: direct-child-key parsing of command instance nodes (106 sites)

**Pattern**: handlers look up **direct child keys** on a **single command instance node / sub-object / sequence item** (verbatim match with the YAML format comments in the file).

| Line | Function | name | Parent level | Class |
|---|---|---|---|---|
| 5342 | handle_yaml_config_route | "net" | route command instance node | S |
| 5343 | handle_yaml_config_route | "gateway" | route command instance node | S |
| 5344 | handle_yaml_config_route | "hop" | route command instance node | S |
| 5345 | handle_yaml_config_route | "priority" | route command instance node | S |
| 5346 | handle_yaml_config_route | "seq_no" | route command instance node | S |
| 5415 | yaml_extract_cmn_tunables | "peer_timeout" | "tunables" sub-object (fetched via child first) | S |
| 5420 | yaml_extract_cmn_tunables | "peer_credits" | "tunables" sub-object | S |
| 5423 | yaml_extract_cmn_tunables | "peer_buffer_credits" | "tunables" sub-object | S |
| 5426 | yaml_extract_cmn_tunables | "credits" | "tunables" sub-object | S |
| 5508 | yaml_validate_conns_per_peer | "conns_per_peer" | "lnd tunables" sub-object | S |
| 5539 | handle_yaml_config_ni | "ip2net" | net command instance node | S |
| 5540 | handle_yaml_config_ni | "net type" | net command instance node | S |
| 5549 | handle_yaml_config_ni | "local NI(s)" | net command instance node | S |
| 5568 | handle_yaml_config_ni | "seq_no" | net command instance node | S |
| 5572 | handle_yaml_config_ni | "interfaces" | item of "local NI(s)" sequence | S |
| 5667 | handle_yaml_config_ip2nets | "net-spec" | ip2nets command instance node | S |
| 5679 | handle_yaml_config_ip2nets | "seq_no" | ip2nets command instance node | S |
| 5681 | handle_yaml_config_ip2nets | "interfaces" | ip2nets command instance node | S |
| 5688 | handle_yaml_config_ip2nets | "ip-range" | ip2nets command instance node | S |
| 5765 | handle_yaml_del_ni | "net type" | net command instance node (del) | S |
| 5769 | handle_yaml_del_ni | "local NI(s)" | net command instance node (del) | S |
| 5777 | handle_yaml_del_ni | "interfaces" | item of "local NI(s)" sequence | S |
| 5789 | handle_yaml_del_ni | "seq_no" | net command instance node (del) | S |
| 5812 | yaml_nids2nidstr | "nid" | item of "peer ni" sequence | S |
| 5856 | yaml_nids2nidstr | "nid" | item of "peer ni" sequence | S |
| 5893 | handle_yaml_peer_common | "seq_no" | peer command instance node | S |
| 5896 | handle_yaml_peer_common | "primary nid" | peer command instance node | S |
| 5897 | handle_yaml_peer_common | "peer ni" | peer command instance node | S |
| 5942 | handle_yaml_peer_common | "Multi-Rail" | peer command instance node | S |
| 5992 | handle_yaml_config_buffers | "tiny" | buffers command instance node | S |
| 5993 | handle_yaml_config_buffers | "small" | buffers command instance node | S |
| 5994 | handle_yaml_config_buffers | "large" | buffers command instance node | S |
| 5995 | handle_yaml_config_buffers | "seq_no" | buffers command instance node | S |
| 6013 | handle_yaml_config_routing | "seq_no" | routing command instance node | S |
| 6014 | handle_yaml_config_routing | "enable" | routing command instance node | S |
| 6033 | handle_yaml_del_route | "net" | route command instance node (del) | S |
| 6034 | handle_yaml_del_route | "gateway" | route command instance node (del) | S |
| 6035 | handle_yaml_del_route | "seq_no" | route command instance node (del) | S |
| 6048 | handle_yaml_del_routing | "seq_no" | routing command instance node (del) | S |
| 6065 | handle_yaml_show_route | "net" | route command instance node (show) | S |
| 6066 | handle_yaml_show_route | "gateway" | route command instance node (show) | S |
| 6067 | handle_yaml_show_route | "hop" | route command instance node (show) | S |
| 6068 | handle_yaml_show_route | "priority" | route command instance node (show) | S |
| 6069 | handle_yaml_show_route | "detail" | route command instance node (show) | S |
| 6070 | handle_yaml_show_route | "seq_no" | route command instance node (show) | S |
| 6086 | handle_yaml_show_net | "net type" | net command instance node (show) | S |
| 6087 | handle_yaml_show_net | "detail" | net command instance node (show) | S |
| 6088 | handle_yaml_show_net | "seq_no" | net command instance node (show) | S |
| 6101 | handle_yaml_show_routing | "seq_no" | routing command instance node (show) | S |
| 6112 | handle_yaml_show_peers | "seq_no" | peer command instance node (show) | S |
| 6113 | handle_yaml_show_peers | "detail" | peer command instance node (show) | S |
| 6114 | handle_yaml_show_peers | "nid" | peer command instance node (show) | S |
| 6127 | handle_yaml_show_stats | "seq_no" | statistics command instance node (show) | S |
| 6138 | handle_yaml_config_numa | "seq_no" | numa command instance node | S |
| 6139 | handle_yaml_config_numa | "range" | numa command instance node | S |
| 6151 | handle_yaml_del_numa | "seq_no" | numa command instance node (del) | S |
| 6162 | handle_yaml_show_numa | "seq_no" | numa command instance node (show) | S |
| 6173 | handle_yaml_del_udsp | "seq_no" | udsp command instance node (del) | S |
| 6174 | handle_yaml_del_udsp | "idx" | udsp command instance node (del) | S |
| 6187 | handle_yaml_config_udsp | "seq_no" | udsp command instance node | S |
| 6188 | handle_yaml_config_udsp | "src" | udsp command instance node | S |
| 6189 | handle_yaml_config_udsp | "rte" | udsp command instance node | S |
| 6190 | handle_yaml_config_udsp | "dst" | udsp command instance node | S |
| 6191 | handle_yaml_config_udsp | "priority" | udsp command instance node | S |
| 6192 | handle_yaml_config_udsp | "idx" | udsp command instance node | S |
| 6212 | handle_yaml_show_udsp | "seq_no" | udsp command instance node (show) | S |
| 6213 | handle_yaml_show_udsp | "idx" | udsp command instance node (show) | S |
| 6229 | handle_yaml_config_global_settings | "seq_no" | global command instance node | S |
| 6230 | handle_yaml_config_global_settings | "max_interfaces" | global command instance node | S |
| 6232 | handle_yaml_config_global_settings | "max_intf" (legacy alias) | global command instance node | S |
| 6239 | handle_yaml_config_global_settings | "numa_range" | global command instance node | S |
| 6246 | handle_yaml_config_global_settings | "discovery" | global command instance node | S |
| 6253 | handle_yaml_config_global_settings | "drop_asym_route" | global command instance node | S |
| 6260 | handle_yaml_config_global_settings | "retry_count" | global command instance node | S |
| 6267 | handle_yaml_config_global_settings | "transaction_timeout" | global command instance node | S |
| 6274 | handle_yaml_config_global_settings | "health_sensitivity" | global command instance node | S |
| 6281 | handle_yaml_config_global_settings | "recovery_interval" | global command instance node | S |
| 6288 | handle_yaml_config_global_settings | "router_sensitivity" | global command instance node | S |
| 6295 | handle_yaml_config_global_settings | "response_tracking" | global command instance node | S |
| 6302 | handle_yaml_config_global_settings | "recovery_limit" | global command instance node | S |
| 6319 | handle_yaml_del_global_settings | "seq_no" | global command instance node (del) | S |
| 6320 | handle_yaml_del_global_settings | "max_interfaces" | global command instance node (del) | S |
| 6322 | handle_yaml_del_global_settings | "max_intf" (legacy alias) | global command instance node (del) | S |
| 6329 | handle_yaml_del_global_settings | "numa_range" | global command instance node (del) | S |
| 6337 | handle_yaml_del_global_settings | "discovery" | global command instance node (del) | S |
| 6345 | handle_yaml_del_global_settings | "drop_asym_route" | global command instance node (del) | S |
| 6362 | handle_yaml_show_global_settings | "seq_no" | global command instance node (show) | S |
| 6363 | handle_yaml_show_global_settings | "max_interfaces" | global command instance node (show) | S |
| 6365 | handle_yaml_show_global_settings | "max_intf" (legacy alias) | global command instance node (show) | S |
| 6371 | handle_yaml_show_global_settings | "numa_range" | global command instance node (show) | S |
| 6377 | handle_yaml_show_global_settings | "discovery" | global command instance node (show) | S |
| 6383 | handle_yaml_show_global_settings | "drop_asym_route" | global command instance node (show) | S |
| 6389 | handle_yaml_show_global_settings | "retry_count" | global command instance node (show) | S |
| 6395 | handle_yaml_show_global_settings | "transaction_timeout" | global command instance node (show) | S |
| 6401 | handle_yaml_show_global_settings | "health_sensitivity" | global command instance node (show) | S |
| 6407 | handle_yaml_show_global_settings | "recovery_interval" | global command instance node (show) | S |
| 6413 | handle_yaml_show_global_settings | "router_sensitivity" | global command instance node (show) | S |
| 6419 | handle_yaml_show_global_settings | "response_tracking" | global command instance node (show) | S |
| 6426 | handle_yaml_show_global_settings | "recovery_limit" | global command instance node (show) | S |
| 6441 | handle_yaml_ping | "seq_no" | ping command instance node (exec) | S |
| 6442 | handle_yaml_ping | "primary nid" | ping command instance node (exec) | S |
| 6443 | handle_yaml_ping | "timeout" | ping command instance node (exec) | S |
| 6444 | handle_yaml_ping | "source_nid" | ping command instance node (exec) | S |
| 6458 | handle_yaml_discover | "seq_no" | discover command instance node (exec) | S |
| 6459 | handle_yaml_discover | "primary nid" | discover command instance node (exec) | S |
| 6460 | handle_yaml_discover | "force" | discover command instance node (exec) | S |

**All 114 sites are S** (R=0, U=0)

## B.2 liblnetconfig_lnd.c (15 sites)

Uniform pattern: `lndparams = cYAML_get_object_child(tree, "lnd tunables")` -> look up scalar parameter names on lndparams (constructor lnetctl.c:1888-1930 confirms all children of "lnd tunables" are scalars — flat object).

| # | Line | Function | name | Parent level | Class |
|---|---|---|---|---|---|
| 1 | 224 | yaml_extract_o2ib_tun | map_on_demand | "lnd tunables" object (flat scalar) | S |
| 2 | 228 | yaml_extract_o2ib_tun | concurrent_sends | same | S |
| 3 | 232 | yaml_extract_o2ib_tun | fmr_pool_size | same | S |
| 4 | 236 | yaml_extract_o2ib_tun | fmr_flush_trigger | same | S |
| 5 | 241 | yaml_extract_o2ib_tun | fmr_cache | same | S |
| 6 | 245 | yaml_extract_o2ib_tun | ntx | same | S |
| 7 | 248 | yaml_extract_o2ib_tun | conns_per_peer | same | S |
| 8 | 252 | yaml_extract_o2ib_tun | tos | same | S |
| 9 | 275 | yaml_extract_kfi_tun | prov_major_version | same | S |
| 10 | 280 | yaml_extract_kfi_tun | prov_minor_version | same | S |
| 11 | 284 | yaml_extract_kfi_tun | auth_key | same | S |
| 12 | 288 | yaml_extract_kfi_tun | traffic_class | same | S |
| 13 | 309 | yaml_extract_efa_tun | nqps | same | S |
| 14 | 327 | yaml_extract_sock_tun | conns_per_peer | same | S |
| 15 | 331 | yaml_extract_sock_tun | tos | same | S |

**All 15 sites are S**

## B.3 liblnetconfig_udsp.c (1 site)

| # | Line | Function | name | Parent level | Class |
|---|---|---|---|---|---|
| 1 | 845 | lustre_lnet_show_udsp | udsp | top-level object (direct child of root, create_seq :700-706) | S |

Same pattern as B.1.1 (top-level block lookup in the show output tree): `root = cYAML_create_object(NULL, NULL)` (:700) -> `udsp_node = cYAML_create_seq(root, "udsp")` (:703) -> line 845 looks up "udsp" at the top level of `*show_rc`; **if found, insert current entries; if not, insert a new sibling block** (:858 `*show_rc = root` — same as the inductive proof in Part E).

**1 site is S**

## B.4 liblustreapi_pcc.c (6 sites)

PCC YAML structure (confirmed by kernel exporter lustre/llite/pcc.c:1127-1155): `pcc:` is a direct child of the build_tree root (sequence) -> sequence item = flat backend object (pccpath/hsmtool/rwid/roid/flags/autocache, all scalars per pcc_dataset_dump indentation).

| # | Line | Function | name | Parent level | Class |
|---|---|---|---|---|---|
| 1 | 721 | llapi_pcc_yaml_cb_helper | pcc | direct child of build_tree root (sequence) | S |
| 2 | 760 | llapi_handle_yaml_pcc_del | pccpath | item of pcc sequence (flat backend object) | S |
| 3 | 761 | llapi_handle_yaml_pcc_del | hsmtool | same | S |
| 4 | 798 | llapi_handle_yaml_pcc_clear | pccpath | same | S |
| 5 | 799 | llapi_handle_yaml_pcc_clear | hsmtool | same | S |
| 6 | 831 | llapi_pcc_yaml_backend_get | rwid/roid | same | S |

**All 6 sites are S**

## B.5 Classification summary

| File | Call sites | S | R | U |
|---|---|---|---|---|
| liblnetconfig.c | 114 | 114 | 0 | 0 |
| liblnetconfig_lnd.c | 15 | 15 | 0 | 0 |
| liblustreapi_pcc.c | 6 | 6 | 0 | 0 |
| liblnetconfig_udsp.c | 1 | 1 | 0 | 0 |
| **Total** | **136** | **136 (100%)** | **0** | **0** |

---

# Part C: Independent Re-verification of Outlier Sites (second pass)

> The outlier sites (parent levels other than "command instance node") are re-verified independently from the code, without relying on the original audit conclusions.

| Group | Call sites | Independent verification evidence | Verdict |
|---|---|---|---|
| tunables sub-object | 5415-5426 | code 5413 fetches tunables via child() first; constructor 3410 create_object + 3414 fills scalars | OK shallow |
| lnd tunables sub-object | 5508 | 5505 child() fetches lndparams; constructor 3419-3427 scalars | OK shallow |
| local NI(s) sequence item | 5572/5777 | YAML format comment 5473-5477 (`- interfaces:` 8-space indent); constructor 3265 create_object(item,"interfaces") | OK shallow |
| peer ni sequence item | 5812/5856 | constructor 1153/4219 create_seq + 3250/4236 create_string("nid") | OK shallow |
| show output tree (8 sites) | 1184/1668/3481/4052/4399/4507/4535/4921 | 3481 independently verified: non-sequence -> cYAML_free_tree(root) drops output — DFS hitting a nested net field is the direct bug | OK shallow (recursion is the direct bug here) |
| PCC backend | 721/760/761/798/799/831 | 760 independently verified: node = pcc sequence item; kernel exporter pcc.c:1127-1155 all scalars | OK shallow |
| udsp top level | 845 | *show_rc always the top-level root from create_object(NULL,NULL) (:700-706); "udsp" is a direct child | OK shallow |

**Re-verification conclusion: all 7 groups / 14 sites support shallow semantics** — the original verdict (S=136/R=0/U=0) holds after independent re-verification.

---

# Part D: Final Conclusions

1. **Restoring the shallow search is 100% safe** — Recursive search is empty; no site needs recursion or a deep API
2. **Restoring the shallow search is a correct fix for LU-20595** (returns to LU-2456 semantics); the 8 show-output-tree insertion sites go from "wrong" to "right"
3. Optional cleanup: all sites could be switched to `cYAML_get_object_child()` to remove semantic ambiguity, but `cYAML_get_object_item()` must remain as a public API (declared in cyaml.h)
4. Suggested regression tests: `lnetctl export` then `import`, multi-nid ping insertion, simultaneous route+net show — to prevent the recursion from sneaking back
