feat(asav): add support for asav (#2945)

jmreicha · kaelemc · web-flow · commit 200808e4758c · 2025-11-28T10:25:47.000+01:00
Adds support for Cisco ASAv firewall. This change includes registering
the new node type and implementing its initialization logic, allowing
users to deploy Cisco ASAv nodes within their container-based network
labs. Adds basic documentation and an example lab for usage.

I tested a few things locally with the sample lab provided, not sure
what else needs to be checked/verified in order to be accepted.

---------

Co-authored-by: Kaelem Chandra &lt;kc@kaelem.net&gt;
diff --git a/core/register.go b/core/register.go
@@ -11,6 +11,7 @@ import (
 	clabnodesc8000 "github.com/srl-labs/containerlab/nodes/c8000"
 	clabnodesceos "github.com/srl-labs/containerlab/nodes/ceos"
 	clabnodescheckpoint_cloudguard "github.com/srl-labs/containerlab/nodes/checkpoint_cloudguard"
+	clabnodescisco_asav "github.com/srl-labs/containerlab/nodes/cisco_asav"
 	clabnodescisco_sdwan "github.com/srl-labs/containerlab/nodes/cisco_sdwan"
 	clabnodescjunosevolved "github.com/srl-labs/containerlab/nodes/cjunosevolved"
 	clabnodescrpd "github.com/srl-labs/containerlab/nodes/crpd"
@@ -77,6 +78,7 @@ func (c *CLab) RegisterNodes() { //nolint:funlen
 	clabnodessrl.Register(c.Reg)
 	clabnodessros.Register(c.Reg)
 	clabnodesvr_aoscx.Register(c.Reg)
+	clabnodescisco_asav.Register(c.Reg)
 	clabnodesvr_csr.Register(c.Reg)
 	clabnodesvr_c8000v.Register(c.Reg)
 	clabnodesvr_freebsd.Register(c.Reg)
diff --git a/docs/lab-examples/asav01.md b/docs/lab-examples/asav01.md
@@ -0,0 +1,85 @@
+|                               |                                                                      |
+| ----------------------------- | -------------------------------------------------------------------- |
+| **Description**               | A Cisco ASAv connected to two Alpine Linux Hosts                     |
+| **Components**                | [Cisco ASAv][asav], [Multitool Alpine Linux][client]                 |
+| **Resource requirements**[^1] | :fontawesome-solid-microchip: 1 <br/>:fontawesome-solid-memory: 2 GB |
+| **Topology file**             | [asav01.clab.yml][topofile]                                          |
+| **Name**                      | asav01                                                               |
+| **Version information**[^2]   | `asav9-23-1.qcow2`, `docker:24.0.6`                                  |
+
+## Description
+
+This lab consists of one Cisco ASAv firewall connected to two Alpine Linux nodes.
+
+```
+client1<---->ASAv<---->client2
+```
+
+## Configuration
+
+The ASAv node takes about 5-7 minutes to complete its start up. Check using "docker container ls" and "docker logs -f clab-asav01-asav1" until the ASAv container shows up as "healthy".
+
+```
+# docker container ls
+CONTAINER ID   IMAGE                                  COMMAND                  CREATED          STATUS                    PORTS                                       NAMES
+5682d73984d1   vrnetlab/vr-asav:9.23.1                "/launch.py --userna…"   5 minutes ago    Up 5 minutes (healthy)    22/tcp, 80/tcp, 443/tcp, 5000/tcp, 10000-10099/tcp   clab-asav01-asav1
+1ebe3dae6846   wbitt/network-multitool:alpine-extra   "/bin/sh /docker-ent…"   5 minutes ago    Up 5 minutes              80/tcp, 443/tcp, 1180/tcp, 11443/tcp                 clab-asav01-client1
+9726c9bb9e21   wbitt/network-multitool:alpine-extra   "/bin/sh /docker-ent…"   5 minutes ago    Up 5 minutes              80/tcp, 443/tcp, 1180/tcp, 11443/tcp                 clab-asav01-client2
+```
+
+### asav1
+
+Log into the ASAv node using SSH and add the following configuration. Password is `CiscoAsa1!`.
+
+```bash
+ssh admin@clab-asav01-asav1
+```
+
+Optionally configure the ASA with any additional settings as needed.
+
+### client1
+
+The two clients should be configured with the correct IP addresses and a route to the other client via the ASAv node.
+First attach to the container process `docker exec -it clab-asav01-client1 bash`
+
+```
+docker exec -it clab-asav01-client1 bash
+
+# ip -br a show dev eth1
+eth0@if7         UP             172.20.20.4/24 3fff:172:20:20::4/64 fe80::a4ea:64ff:fe33:c15c/64
+
+# ip route
+default via 172.20.20.1 dev eth0
+172.20.20.0/24 dev eth0 proto kernel scope link src 172.20.20.4
+
+# ping 172.20.20.2
+PING 172.20.20.2 (172.20.20.2) 56(84) bytes of data.
+64 bytes from 172.20.20.2: icmp_seq=1 ttl=64 time=0.163 ms
+64 bytes from 172.20.20.2: icmp_seq=2 ttl=64 time=0.047 ms
+64 bytes from 172.20.20.2: icmp_seq=3 ttl=64 time=0.053 ms
+```
+
+### client2
+
+Similarly for client2, verify connectivity:
+
+```
+docker exec -it clab-asav01-client2 bash
+
+# ip -br a show dev eth1
+eth0@if5         UP             172.20.20.2/24 3fff:172:20:20::2/64 fe80::b86b:51ff:fed8:1c85/64
+
+# ping 172.20.20.4
+PING 172.20.20.4 (172.20.20.4) 56(84) bytes of data.
+64 bytes from 172.20.20.4: icmp_seq=1 ttl=64 time=0.055 ms
+64 bytes from 172.20.20.4: icmp_seq=2 ttl=64 time=0.035 ms
+64 bytes from 172.20.20.4: icmp_seq=3 ttl=64 time=0.065 ms
+
+# ping 172.20.20.6
+PING 172.20.20.6 (172.20.20.6) 56(84) bytes of data.
+From 172.20.20.2 icmp_seq=1 Destination Host Unreachable
+From 172.20.20.2 icmp_seq=2 Destination Host Unreachable
+From 172.20.20.2 icmp_seq=3 Destination Host Unreachable
+```
+
+[topofile]: https://github.com/srl-labs/containerlab/tree/main/lab-examples/asav01/asav01.clab.yml
diff --git a/docs/manual/kinds/cisco_asav.md b/docs/manual/kinds/cisco_asav.md
@@ -0,0 +1,95 @@
+---
+search:
+  boost: 4
+kind_code_name: cisco_asav
+kind_display_name: Cisco ASAv
+---
+
+# Cisco ASAv
+
+[Cisco ASAv](https://www.cisco.com/c/en/us/products/collateral/security/adaptive-security-virtual-appliance-asav/adapt-security-virtual-appliance-ds.html) is identified with `cisco_asav` kind in the [topology file](../topo-def-file.md). It is built using [vrnetlab](../vrnetlab.md) project and essentially is a Qemu VM packaged in a docker container format.
+
+## Managing ASAv nodes
+
+/// note
+Containers with Cisco ASAv inside will take ~5-7 min to fully boot.
+You can monitor the progress with `docker logs -f <container-name>`.
+///
+
+To connect to a `bash` shell of a running ASAv container:
+
+```bash
+docker exec -it <container-name/id> bash
+```
+
+To connect to the ASAv CLI (password `CiscaoAsa1!`):
+
+```bash
+ssh admin@<container-name>
+```
+
+To connect to the serial port (console) exposed over TCP port 5000:
+
+```bash
+# from container host
+telnet <container-name> 5000
+```
+
+You can also connect to the container and use `telnet localhost 5000` if telnet is not available on your container host.
+
+/// note
+Default user credentials (non-standard due to complexity length requirement): `admin:CiscoAsa1!`
+///
+
+## Interface naming
+
+You can use [interfaces names](../topo-def-file.md#interface-naming) in the topology file like they appear in -{{ kind_display_name }}-.
+
+The interface naming convention is: `GigabitEthernet0/X` (or `Gi0/X`), where `X` is the port number.
+
+With that naming convention in mind:
+
+- `Gi0/0` - first data port available
+- `Gi0/1` - second data port, and so on...
+
+/// note
+Data port numbering starts at `0`.
+///
+
+The example ports above would be mapped to the following Linux interfaces inside the container running the -{{ kind_display_name }}- VM:
+
+- `eth0` - management interface connected to the containerlab management network (rendered as `Management0/0` in the CLI)
+- `eth1` - first data interface, mapped to the first data port of the VM (rendered as `GigabitEthernet0/0`)
+- `eth2+` - second and subsequent data interfaces, mapped to the second and subsequent data ports of the VM (rendered as `GigabitEthernet0/1` and so on)
+
+When containerlab launches -{{ kind_display_name }}- node the `Management0/0` interface of the VM gets assigned `10.0.0.15/24` address from the QEMU DHCP server. This interface is transparently stitched with container's `eth0` interface such that users can reach the management plane of the -{{ kind_display_name }}- using containerlab's assigned IP.
+
+Data interfaces `GigabitEthernet0/0+` need to be configured with IP addressing manually using CLI or other available management interfaces.
+
+## Features and options
+
+### Node configuration
+
+Cisco ASAv nodes come up with a basic configuration where only the management interface and default `admin` user are provisioned.
+
+#### User defined startup config
+
+It is possible to make ASAv nodes boot up with a user-defined startup-config instead of a built-in one. With a [`startup-config`](../nodes.md#startup-config) property of the node/kind user sets the path to the config file that will be mounted to a container and used as a startup-config:
+
+```yaml
+topology:
+  nodes:
+    asav:
+      kind: cisco_asav
+      startup-config: myconfig.txt
+```
+
+With this knob containerlab is instructed to take a file `myconfig.txt` from the directory that hosts the topology file, and copy it to the lab directory for that specific node under the `/config/startup-config.cfg` name. Then the directory that contains the startup-config dir is mounted to the container. This will result in this config being applied at startup by the node.
+
+Configuration is applied after the node is started, thus it can contain partial configuration snippets that you desire to add on top of the default config that a node boots up with.
+
+## Lab examples
+
+The following simple lab consists of two Linux hosts connected via one ASAv firewall node:
+
+- [Cisco ASAv](../../lab-examples/asav01.md)
diff --git a/lab-examples/asav01/asav01.clab.yml b/lab-examples/asav01/asav01.clab.yml
@@ -0,0 +1,20 @@
+name: asav01
+
+topology:
+  nodes:
+    # ASAv runs as a VM and is slower to boot. Use 'docker logs -f clab-asav01-asav1' to view progress
+    asav1:
+      kind: cisco_asav
+      image: vrnetlab/cisco_asav:9-23-1
+
+    client1:
+      kind: linux
+      image: wbitt/network-multitool:alpine-extra
+
+    client2:
+      kind: linux
+      image: wbitt/network-multitool:alpine-extra
+
+  links:
+    - endpoints: ["client1:eth1", "asav1:eth1"]
+    - endpoints: ["client2:eth1", "asav1:eth2"]
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -27,6 +27,7 @@ nav:
               - Cisco SD-WAN: manual/kinds/cisco_sdwan.md
               - Cisco Catalyst 9000v: manual/kinds/vr-cat9kv.md
               - Cisco IOL: manual/kinds/cisco_iol.md
+              - Cisco ASAv: manual/kinds/cisco_asav.md
               - Cisco FTDv: manual/kinds/vr-ftdv.md
           - Juniper:
               - Juniper cRPD: manual/kinds/crpd.md
@@ -169,6 +170,7 @@ nav:
       - RARE/freeRtr: lab-examples/rare-freertr.md
       - Juniper vSRX: lab-examples/vsrx01.md
       - OpenBSD: lab-examples/openbsd01.md
+      - Cisco ASAv: lab-examples/asav01.md
       - Cisco FTDv: lab-examples/ftdv01.md
       - Templated labs:
           - Leaf-spine topology: lab-examples/templated01.md
diff --git a/nodes/cisco_asav/cisco_asav.go b/nodes/cisco_asav/cisco_asav.go
@@ -0,0 +1,91 @@
+// Copyright 2020 Nokia
+// Licensed under the BSD 3-Clause License.
+// SPDX-License-Identifier: BSD-3-Clause
+
+package cisco_asav
+
+import (
+	"fmt"
+	"path"
+	"regexp"
+
+	clabnodes "github.com/srl-labs/containerlab/nodes"
+	clabtypes "github.com/srl-labs/containerlab/types"
+	clabutils "github.com/srl-labs/containerlab/utils"
+)
+
+var (
+	kindNames          = []string{"cisco_asav"}
+	defaultCredentials = clabnodes.NewCredentials("admin", "CiscoAsa1!")
+
+	InterfaceRegexp = regexp.MustCompile(`(?:GigabitEthernet|Gi)\s?0/(?P<port>\d+)`)
+	InterfaceOffset = 0
+	InterfaceHelp   = "GigabitEthernet0/X or Gi0/X (where X >= 0) or ethX (where X >= 1)"
+)
+
+const (
+	scrapliPlatformName = "cisco_asa"
+)
+
+// Register registers the node in the NodeRegistry.
+func Register(r *clabnodes.NodeRegistry) {
+	platformAttrs := &clabnodes.PlatformAttrs{
+		ScrapliPlatformName: scrapliPlatformName,
+	}
+
+	nrea := clabnodes.NewNodeRegistryEntryAttributes(defaultCredentials, nil, platformAttrs)
+
+	r.Register(kindNames, func() clabnodes.Node {
+		return new(asav)
+	}, nrea)
+}
+
+type asav struct {
+	clabnodes.VRNode
+}
+
+func (n *asav) Init(cfg *clabtypes.NodeConfig, opts ...clabnodes.NodeOption) error {
+	// Init VRNode
+	n.VRNode = *clabnodes.NewVRNode(n, defaultCredentials, scrapliPlatformName)
+	// set virtualization requirement
+	n.HostRequirements.VirtRequired = true
+
+	n.Cfg = cfg
+	for _, o := range opts {
+		o(n)
+	}
+	// env vars are used to set launch.py arguments in vrnetlab container
+	defEnv := map[string]string{
+		"CONNECTION_MODE":    clabnodes.VrDefConnMode,
+		"USERNAME":           defaultCredentials.GetUsername(),
+		"PASSWORD":           defaultCredentials.GetPassword(),
+		"DOCKER_NET_V4_ADDR": n.Mgmt.IPv4Subnet,
+		"DOCKER_NET_V6_ADDR": n.Mgmt.IPv6Subnet,
+	}
+	n.Cfg.Env = clabutils.MergeStringMaps(defEnv, n.Cfg.Env)
+
+	// mount config dir to support startup-config functionality
+	n.Cfg.Binds = append(
+		n.Cfg.Binds,
+		fmt.Sprint(path.Join(n.Cfg.LabDir, n.ConfigDirName), ":/config"),
+	)
+
+	if n.Cfg.Env["CONNECTION_MODE"] == "macvtap" {
+		// mount dev dir to enable macvtap
+		n.Cfg.Binds = append(n.Cfg.Binds, "/dev:/dev")
+	}
+
+	n.Cfg.Cmd = fmt.Sprintf(
+		"--username %s --password %s --hostname %s --connection-mode %s --trace",
+		n.Cfg.Env["USERNAME"],
+		n.Cfg.Env["PASSWORD"],
+		n.Cfg.ShortName,
+		n.Cfg.Env["CONNECTION_MODE"],
+	)
+
+	n.InterfaceRegexp = InterfaceRegexp
+	n.InterfaceOffset = InterfaceOffset
+	n.InterfaceHelp = InterfaceHelp
+
+	return nil
+}
diff --git a/nodes/cisco_asav/cisco_asav_test.go b/nodes/cisco_asav/cisco_asav_test.go
diff --git a/schemas/clab.schema.json b/schemas/clab.schema.json
