network: add --mac-address support to `docker network connect` #6728

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'

@ahmedharabi


 Add --mac-address flag to network connect command

0ab4470

This adds support for specifying a MAC address when connecting
a container to a network, particularly useful for macvlan networks.
The flag follows the same pattern as existing network options like
--ip and --ip6, parsing and validating the MAC address before
sending it to the daemon via the EndpointSettings.MacAddress field.
Note: This requires a companion change in moby/moby to have the
daemon actually apply the MAC address during network conne
Signed-off-by: ahmedharabi <harabiahmed88@gmail.com>

@codecov-commenter

Copy link

codecov-commenter commented Jan 5, 2026 •

edited

Loading

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 thaJeztah requested review from a team and thaJeztah as code owners

January 7, 2026 10:05

thaJeztah

thaJeztah requested changes

Jan 7, 2026

View reviewed changes

Copy link

Member

@thaJeztah thaJeztah left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"

cli/command/network/connect.go Outdated

if err != nil {

return fmt.Errorf("invalid MAC address: %q", macStr)

}

options.macAddress = mac

Copy link

Member

@thaJeztah thaJeztah Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

cli/command/network/connect.go Outdated

// Validate MAC address if provided

if macStr != "" {

mac, err := net.ParseMAC(macStr)

Copy link

Member

@thaJeztah thaJeztah Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Member

thaJeztah commented Jan 7, 2026

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

@thaJeztah thaJeztah marked this pull request as draft

January 7, 2026 10:06

@thaJeztah


 WIP: review suggestions

e605695

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

@thaJeztah thaJeztah force-pushed the 51796-network-connect-mac-address branch from 935dabf to e605695 Compare

January 7, 2026 10:07

@ahmedharabi

Copy link

Author

ahmedharabi commented Jan 7, 2026

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

Copy link

Member

thaJeztah commented Jan 8, 2026

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

Copy link

Author

ahmedharabi commented Jan 8, 2026

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.

Labels

None yet

3 participants

@ahmedharabi @codecov-commenter @thaJeztah

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

Are you sure you want to change the base?

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

Conversation

@ahmedharabi ahmedharabi commented Jan 2, 2026 • edited by thaJeztah Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add --mac-address support to docker network connect

What I did

How I did it

How to verify it

Uh oh!

codecov-commenter commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

@thaJeztah thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

@thaJeztah thaJeztah Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

@thaJeztah thaJeztah Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Jan 7, 2026

Uh oh!

ahmedharabi commented Jan 7, 2026

Uh oh!

thaJeztah commented Jan 8, 2026

Uh oh!

ahmedharabi commented Jan 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

network: add --mac-address support to `docker network connect` #6728

network: add --mac-address support to `docker network connect` #6728

@ahmedharabi ahmedharabi commented Jan 2, 2026 •

edited by thaJeztah

Loading

Add `--mac-address` support to `docker network connect`

codecov-commenter commented Jan 5, 2026 •

edited

Loading