Macvlan support

[jbernardini]

Allows the user to specify in topology file, and containerlab to create, a mgmt network using the docker macvlan driver. Working and tested. Also creates the host networking on linux to support current host-to-device ssh behavior.

More context here: https://discord.com/channels/860500297297821756/1400987584460755165

[steiler]

Hi @jbernardini,
I'm wondering if that logic should not in general move somewhere e.g. in utils or so... I ssume it could be reused for podman also?!

[jbernardini]

Hi @jbernardini, I'm wondering if that logic should not in general move somewhere e.g. in utils or so... I ssume it could be reused for podman also?!

the host network adapter/route logic? I agree and will work to pull it out now that I've got it all working. Also, do you have any examples of platform specific code? That piece should only go in the linux build atm.

do you also mean the docker macvlan network creation?

[Copilot]

Pull Request Overview

This PR adds support for Docker macvlan networks in containerlab as an alternative to the existing bridge driver. It allows users to specify macvlan configuration in topology files and automatically creates the necessary network infrastructure including host-side interfaces for container communication.

• Adds macvlan driver support with configuration options for parent interface, mode, and auxiliary addresses
• Implements network creation, management, and cleanup functionality for macvlan networks
• Creates host-side macvlan interfaces to enable communication between the host and containers

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 8 comments.

File	Description
types/types.go	Adds macvlan-specific configuration fields to MgmtNet struct
schemas/clab.schema.json	Defines JSON schema validation for new macvlan configuration options
runtime/docker/docker.go	Implements macvlan network creation, validation, and cleanup logic
hostnet/macvlan.go	New module handling host-side macvlan interface creation and management

Comments suppressed due to low confidence (1)

runtime/docker/docker.go:342

• Variable name uses underscore instead of camelCase. Should be ipv6Subnet to match Go naming conventions.

	var ipv6_subnet string

[jbernardini]

Everything seems to be working on create and delete, whether the macvlan network needs to be created or already exists. This is nice because if someone needs something a little more complex they can just use docker native tools to create the network and clab will consume it. That's good because this does not provide full coverage of the docker macvlan capabilities, but provides the simplest way to get a lab up with management IPs reachable from your network. That does make it super easy to spin up duplicate IP addresses on the network if you're not careful.

The host network adapter/route operations are all moved out to a hostnet package. Subnets and routing get's a little complicated and I've tried to add some guidance in the logs. Will want some solid documentation around this. To facilitate the easiest option - as in, you don't have to do anything and it'll just work- I've allowed a CIDR address into the aux-address input. That lets you set the macvlan subnet to the host's subnet so container <=> network communications are automatic, but also build a static route on a smaller subnet from the host to the containers which is otherwise blocked by the kernel with macvlan.

I haven't looked closely at the podman or containers runtimes yet but the docker macvlan driver networking seems correctly placed in docker.go, along side the docker bridge driver networking.

[jbernardini]

# Example: Using CIDR notation to avoid route conflicts
# Host is on 192.168.1.0/24, containers use same subnet but route only a /26
name: macvlan-cidr-aux
mgmt:
  network: clab-macvlan
  driver: macvlan
  macvlan-parent: eth0
  ipv4-subnet: 192.168.1.0/24         # Host subnet for automatic networking
  ipv4-gw: 192.168.1.1                # Same gateway as host
  macvlan-aux: 192.168.1.129/26       # Creates static route any subnet smaller than the host subnet 

# This configuration:
# - Allows containers to communicate on the containerlab host network
# - Routes /26 through the host macvlan interface
# - to avoid conflict with existing .0/24 route on the host
# - container IPS should be from the smaller subnet /26 in this example.
# - Could implement the docker macvlan address range to facilitate that.

[jbernardini]

created a video demonstrating the new functionality: https://youtu.be/PfOUbXWDR74

[jbernardini]

@steiler I have the changes now ready for podman to support macvlan on the mgmt network. Okay to update this PR because they are dependent on the hostnet/macvlan.go additions in this PR? Or would you rather another PR for podman?

[steiler]

@steiler I have the changes now ready for podman to support macvlan on the mgmt network. Okay to update this PR because they are dependent on the hostnet/macvlan.go additions in this PR? Or would you rather another PR for podman?

Thats on @hellt to decide. But thanks for the effort already!

[jbernardini]

I've got a bug in the network destroy code that'll recreate the network on destroy if it doesn't exist. Thought I'd fixed that but must have reintroduced it somehow. Will update.

[jbernardini]

I've got a bug in the network destroy code that'll recreate the network on destroy if it doesn't exist. Thought I'd fixed that but must have reintroduced it somehow. Will update.

resolved

[jbernardini]

Hello @hellt, Should I resolve the conflicts to keep this moving? I figured they were at least in part due to the command refactor and maybe someone else would want to look at them?

[hellt]

Yes, sorry it has been a busy month with some work related PRs getting priority. If you resolve the issues I will have a look

[brenton-h]

Good job @jbernardini - I hope to see this completed soon as it will be quite useful

[jbernardini]

Good job @jbernardini - I hope to see this completed soon as it will be quite useful

thanks. we've been using it for months so I guess I'm comfortable it works. will try and circle back and address these conflicts.

[FloSch62]

@jbernardini I made it up2date with main.

some things worth to check/do:

• prefer netlink APIs over executing ip from PATH

• mgmt.driver: macvlan is advertised in the schema, but Podman ignores it and still builds a bridge network. See schemas/clab.schema.json:1920 and runtime/podman/util.go:441. Either reject macvlan for Podman with a clear error or implement it there too.

• Cleanup can disable promiscuous mode even if containerlab did not enable it. hostnet/macvlan.go:40 enables it based on current state, but hostnet/macvlan.go:331 later turns it off if no other host-visible macvlans remain. That can mutate pre-existing host NIC config. Track original state or avoid toggling promisc automatically.

• Reusing an existing host macvlan interface is not fully idempotent. hostnet/macvlan.go:179 returns as soon as the IP is present, without verifying parent, mode, link state, or restoring the route added later at hostnet/macvlan.go:259. A redeploy after a missing route would silently stay broken.

• No docs or tests are added in this PR. For a new mgmt surface, I’d expect at least docs/manual/network.md coverage

[jbernardini]

Thanks @FloSch62 . Unfortunately I'm no longer working on the project where we used this so probably won't finish out the work on the PR. As it is, it worked quite well for us, and probably will be useful for others, so I'd encourage you or someone to complete it.