Add 'debug at startup' capability for IOS and FRR (#2550)

Adds device-specific attributes (ios.debug, frr.debug) that enable
debugging at the beginning of initial device configuration.

The debugging attribute (global or per-node) can be a list of
debugging options or a multi-line string.

Author: ipspace

docs/caveats.md

@@ -123,6 +123,7 @@ These caveats are common to all Cisco IOS/IOS-XE platforms:
 * Cisco IOS does not support passive interfaces in RIPng.
 * Cisco IOS requires a *default metric* when redistributing routes into RIPv2. The RIPv2 configuration template sets the default metric to the value of the **netlab_ripv2_default_metric** node parameter (default: 5)
 * Cisco IOS behaves like an awful IP host from the 1980s with the **no ip routing** configuration; it does not use static routes and relies only on the **ip default-gateway**. IPv4 routing is thus enabled even when a Cisco IOS device has **role** set to *host*.
+* You can use the **ios.debug** global- or node attribute to [enable debugging](node-debug-attribute) during the initial device configuration.
 
 These caveats apply only to Cisco IOSv and IOSvL2
 
@@ -314,6 +315,7 @@ diag debug application httpsd -1
 * IPv6 L3VPN over SRv6 does not work in parallel with the IPv6 AF. You have to disable the IPv6 AF on IPv6 IBGP sessions with **bgp.activate.ipv6: []**.
 * An OSPFv3 ABR running FRR release 10.3 does not originate summary external routes from NSSA areas
 * FRR has no default logging destinations. The initial device configuration adds file logging to `/tmp/logging`.
+* You can use the **frr.debug** global- or node attribute to [enable debugging](node-debug-attribute) during the initial device configuration.
 
 (caveats-junos)=
 ## Common Junos caveats

docs/node/debug.md

@@ -36,3 +36,27 @@ You can enable debugging *before* configuring network devices with this simple t
 ```{warning}
 Some devices (for example, Arista EOS) accept debugging commands only after the corresponding control-plane protocol has been configured, making the above approach a non-starter.
 ```
+
+(node-debug-attribute)=
+## Device-Specific Debugging Attributes
+
+Finally, you might be worried that the symptoms you're experiencing depend on the time after the device boots, so you want to enable debugging as soon as possible. In that case, you can use the device-specific **debug** attribute (on [devices for which we implemented it](platform-initial-extra)), which is a list of debugging parameters that will be executed at the very beginning of the initial device configuration.
+
+**Caveats:**
+
+* The contents of the **_device_.debug** attribute are device-specific. *netlab* currently does not have multi-vendor **debug** capabilites.
+* The values of the **_device_.debug** attribute are not checked. They must be relevant to the underlying network device, or you'll get configuration errors during the initial configuration
+* The initial device configuration template supplies the mandatory prefix (for example, **do debug**). You only have to list the debugging conditions, for example:
+
+```
+nodes:
+  dut:
+    module: [ bgp, ospf, routing ]
+    bgp.as: 65000
+    device: iol
+    ios.debug:
+    - ip routing
+    - bgp ipv4 unicast updates
+    frr.debug:
+    - bgp updates
+```

docs/platforms.md

@@ -283,6 +283,16 @@ The following interface addresses are supported on various platforms:
 * See [Initial Configuration Integration Tests Results](https://release.netlab.tools/_html/coverage.initial) for up-to-date details.
 ```
 
+(platform-initial-extra)=
+Some platforms can enable additional functionality during the initial device configuration:
+
+| Operating system | [Debugging<br>attribute](node-debug-attribute)[^GNDA] |
+|------------------|:-:|
+| Cisco IOS/IOS XE[^18v]| **ios.debug** |
+| FRRouting             | **frr.debug** |
+
+[^GNDA]: The debugging attribute can be specified for a single node or globally, in which case the debugging is activated on all nodes using the specified device.
+
 ## Supported Configuration Modules
 
 (platform-routing-support)=

netsim/ansible/templates/initial/_debug_commands.j2

@@ -0,0 +1,9 @@
+{% macro enable_debugging(debug,prefix) %}
+{%   for dbg in debug|default([]) if dbg %}
+{%     if loop.first %}
+!
+! Enable debugging
+{%     endif %}
+{{ prefix }} {{ dbg }}
+{%   endfor %}
+{% endmacro %}

netsim/ansible/templates/initial/frr.j2

@@ -130,6 +130,8 @@ cat >/tmp/config <<CONFIG
 hostname {{ inventory_hostname }}
 !
 log file /tmp/logging
+{% from '_debug_commands.j2' import enable_debugging %}
+{{ enable_debugging(frr.debug,prefix='debug') }}
 !
 {#
   These commands set the corresponding net.ipv4 / net.ipv6 variables.

netsim/ansible/templates/initial/ios.j2

@@ -1,6 +1,9 @@
 hostname {{ inventory_hostname }}
 !
 no ip domain lookup
+logging buffered 256000
+{% from '_debug_commands.j2' import enable_debugging %}
+{{ enable_debugging(ios.debug,prefix='do debug') }}
 !
 lldp run
 !

netsim/devices/frr.yml

@@ -152,3 +152,11 @@ features:
     vtep6: true
 
 graphite.icon: router
+
+attributes:
+  global:
+    frr:
+      debug: { type: list, split_lines: True }
+  node:
+    frr:
+      debug: { type: list, split_lines: True }

netsim/devices/ios.yml

@@ -2,6 +2,14 @@
 description: Generic Cisco IOS device (meta device, used only as parent)
 _meta_device: True
 template: True
+attributes:
+  global:
+    ios:
+      debug: { type: list, split_lines: True }
+  node:
+    ios:
+      debug: { type: list, split_lines: True }
+
 loopback_interface_name: Loopback{ifindex}
 tunnel_interface_name: Tunnel{ifindex}
 group_vars: