network: add --mac-address support to docker network connect

[ahmedharabi]

• relates to mac-address option available as docker run --network option, but missing as argument in docker network connect moby/moby#51796

Add --mac-address support to docker network connect

Closes moby/moby#51796

This change adds support for specifying a MAC address when connecting an existing container to a network using docker network connect, bringing feature parity with docker run --network.

The flag follows the same behavior as existing network-related options such as --ip and --ip6. The MAC address is parsed and validated client-side, then forwarded to the daemon via EndpointSettings.MacAddress.

This is particularly useful for macvlan networks, where explicit MAC address assignment is a common requirement.

Note: This change requires a companion update in moby/moby for the daemon to actually apply the MAC address during network connection.

---

What I did

• Added a --mac-address flag to docker network connect
• Implemented MAC address parsing and validation
• Passed the MAC address through EndpointSettings.MacAddress to the daemon

---

How I did it

• Introduced a new CLI flag consistent with existing network flags
• Validated input using net.ParseMAC
• Converted the value to network.HardwareAddr before sending it to the API
• Ensured invalid MAC addresses are rejected before making the API call

---

How to verify it

docker network create -d macvlan \
  --subnet=192.168.70.0/24 \
  --gateway=192.168.70.1 \
  -o parent=<interface> test-macvlan

docker run -d --name mysql3 mysql:8.0

docker network connect \
  --mac-address 02:42:ac:70:00:28 \
  test-macvlan mysql3

docker inspect mysql3 | jq '.[0].NetworkSettings.Networks."test-macvlan".MacAddress'

[codecov-commenter]

Codecov Report

❌ Patch coverage is 50.00000% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cli/command/network/connect.go	50.00%	2 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[thaJeztah]

Thanks for contributing! While reviewing, and testing my code suggestions, I think the "network connect" endpoint currently doesn't support setting a MAC-address 🤔 at least, I didn't get the expected result, so I think changes may still be needed on the daemon side for this

docker rm -fv foo
docker network create net1
docker run -d --name foo nginx:alpine
docker network connect --mac-address=92:d0:c6:0a:29:33 net1 foo
docker container inspect foo | jq '.[0].NetworkSettings.Networks."net1".MacAddress'
"62:ad:7e:be:84:dc"

[thaJeztah]

Lacking a special mac-address flag-type (I'm looking into creating some generics for these), we can probably add macAddress as string for now, and handle the parsing in runConnect

[thaJeztah]

Looking at the type; we could probably use the network.HardwareAddr's UnmarshalText method for this; that way we wouldn't have to cast it to the right type 🤔

[thaJeztah]

I pushed a temporary commit with suggestions, but let me move this one to draft, as it looks like it requires changes on the daemon-side for this

cc @robmry

[ahmedharabi]

Thanks for checking and for the detailed review.

I reached the same conclusion after multiple attempts: the MAC address does not appear to be applied by the daemon during network connect. I was unable to observe any change on the container side either.

My intention with this change was to surface the flag at the CLI level first, so the behavior and expectations are explicit and testable, and so any required follow-up on the daemon side is clearer and easier to reason about.

If this needs to be handled entirely in the daemon first, I’m happy to adjust or pause this PR and follow your guidance on the preferred approach.

[thaJeztah]

I reached the same conclusion after multiple attempts: the MAC address does not appear to be applied by the daemon during network connect. I was unable to observe any change on the container side either.

Yes, looks like we need to look what's needed on the daemon-side. I saw your original ticket, and thought "oh, this probably needs to be implemented", but then tried this PR and it didn't produce an error, so initially thought "perhaps not, and perhaps it was just not wired up in the CLI!" (hoping that if that was the case, we could still include this in the upcoming 29.2 release 😄)

The fact that the daemon doesn't produce an error was slightly surprising, but some of this may be due to the same Go types / structs being reused for multiple places (both "create", "connect" and "inspect"). Those were probably poor choices made in the past, and we've made some attempts to be more specific (e.g. moby/moby#51204), but some of those are very deeply ingrained in the code-base, making it hard to change, so may be something we just need to live with now.

But yeah, it looks like more work is needed to make this work for connect. Perhaps if we cannot make that work short-term, at least we should look if we should produce an error to prevent it being silently discarded.

[ahmedharabi]

Yeah, agreed changing the shared struct types would likely require a lot more work than makes sense right now. Given that, returning a clear error to the user instead of silently ignoring the option feels like the best approach for now.

I’m happy to update the PR in that direction, or we can leave this here and revisit once daemon support becomes feasible.