Skip to content

Conversation

DSS3113
Copy link

@DSS3113 DSS3113 commented Oct 12, 2025

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update

Motivation and Context

[Why is this change needed?]
Currently, there is no way to specify a custom MAC address for a container's network interface and the MAC address is auto-generated by the system.

Use Cases

  • Network Testing: Developers testing network-dependent applications that need predictable MAC addresses
  • License Management: Running containerized software with MAC-based license keys
  • Network Automation: Scripts and tools that expect specific MAC addresses for configuration
  • Debugging: Consistent MAC addresses across container restarts for easier troubleshooting

Testing

  • Tested locally
  • Added/updated tests
  • Added/updated docs

Issue

closes #752

@siikamiika siikamiika mentioned this pull request Oct 12, 2025
7 tasks
return networkIds.enumerated().map { item in
guard item.offset == 0 else {
return AttachmentConfiguration(network: item.element, options: AttachmentOptions(hostname: containerId))
return AttachmentConfiguration(network: item.element, options: AttachmentOptions(hostname: containerId, macAddress: item.offset == 0 ? macAddress : nil))
Copy link
Contributor

Choose a reason for hiding this comment

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

(disclaimer: I'm not a maintainer and I'm not requesting a change, just interested in this feature because I'm implementing an adjacent feature to --network in #751)

Do you know how docker or podman handle this if there are multiple networks? I think if you do something like --network net-1 --network net-2 --mac-address ff:ff:ff:ff:ff:ff this will set the MAC on net-1.

Copy link
Author

@DSS3113 DSS3113 Oct 12, 2025

Choose a reason for hiding this comment

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

Thanks for the question! Yes, multiple --network flags are supported with a single --mac-address flag. I tested this and here's the behavior:

container run --network net-1 --network net-2 --mac-address 02:42:ac:11:00:02 ubuntu
net-1 (first network): Gets the specified MAC address 02:42:ac:11:00:02
net-2 (subsequent networks): Gets auto-generated MAC address

I am not sure about podman but docker simply does not support inputting multiple --network flags in the run command when a single --mac-address is specified. [Edited]

docker run -d --name test-mac-container --mac-address 02:42:ac:11:00:99 --network test-net-1 --network test-net-2 --network test-net-3 alpine sleep 300

docker: Error response from daemon: Container cannot be connected to network endpoints: test-net-1, test-net-2, test-net-3.
See 'docker run --help'.

Copy link
Contributor

@siikamiika siikamiika Oct 13, 2025

Choose a reason for hiding this comment

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

That's interesting, according to Docker docs multiple networks should be supported. Could it be related to the --mac-address flag even though the error message is a bit vague? (or maybe that's what you meant)

I don't have Docker installed at the moment, but I tried how Podman works in a VM:

# by default podman uses host networking
# podman also has a default bridge network that can be used with either --network=bridge or --network=podman, same as --network=default or no --network in apple/container

# create two custom named bridge networks:
$ podman network create net-1 # gets the network 10.89.0.0/24
$ podman network create net-2 # gets the network 10.89.1.0/24

$ podman run --rm -it --network=bridge --mac-address=02:00:00:00:00:01 alpine # default bridge network gets static mac (command fails with just --mac-address but that's due to the network type)
$ podman run --rm -it --network=net-1 --mac-address=02:00:00:00:00:01 alpine # custom bridge network net-1 gets static mac
$ podman run --rm -it --network=net-1 --network=net-2 alpine  # starts (random mac for both)
$ podman run --rm -it --mac-address=02:00:00:00:00:01 --network=net-1 --network=net-2 alpine # fails
Error: --mac-address can only be set for a single network: invalid argument
$ podman run --rm -it --network=net-1:mac=02:00:00:00:00:01 --network=net-2 alpine # net-1 gets static mac, net-2 gets random mac
$ podman run --rm -it --network=net-1:mac=02:00:00:00:00:01 --network=net-2:mac=02:00:00:00:00:02 alpine # both get static mac

Copy link
Author

@DSS3113 DSS3113 Oct 14, 2025

Choose a reason for hiding this comment

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

You're right, I apologize. I should've clarified that the docker example failing was in the case when the --mac-address flag is specified with multiple networks.

@jglogan
Copy link
Contributor

jglogan commented Oct 16, 2025

@DSS3113 Thank you! Got a bit of a backlog but let's get the workflow going and I'll try to look it over no later than early next week.

@jglogan
Copy link
Contributor

jglogan commented Oct 16, 2025

@DSS3113 however, an immediate comment relating to the multiple networks aspect.

What do you think about handling attachment properties similarly to mount options for filesystems?

This has the attractive property of being extensible without cluttering the CLI with a bunch of options.

The drawback is discovery/documentation isn't as simple; there's only so much you can include in the help for a single option.

Example:

container run --network default --network backend,mac=addr1 --network backend2,mac=addr2

@DSS3113 DSS3113 marked this pull request as draft October 18, 2025 17:08
@DSS3113
Copy link
Author

DSS3113 commented Oct 18, 2025

@DSS3113 however, an immediate comment relating to the multiple networks aspect.

What do you think about handling attachment properties similarly to mount options for filesystems?

This has the attractive property of being extensible without cluttering the CLI with a bunch of options.

The drawback is discovery/documentation isn't as simple; there's only so much you can include in the help for a single option.

Example:

container run --network default --network backend,mac=addr1 --network backend2,mac=addr2

@jglogan Sure, I can start adjusting it to match this format.

Replace --mac-address flag with --network name,mac=XX:XX:XX:XX:XX:XX syntax for per-attachment configuration.
@DSS3113 DSS3113 marked this pull request as ready for review October 20, 2025 22:00
@DSS3113 DSS3113 marked this pull request as draft October 20, 2025 22:17
@DSS3113 DSS3113 marked this pull request as ready for review October 20, 2025 22:20
@jglogan
Copy link
Contributor

jglogan commented Oct 21, 2025

@DSS3113 Building now but there are conflicts (probably because of the just merged --network none stuff).

I'll also pull down a patch into my local and test it out, looking fwd to trying it!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Request]: Add --mac-address flag to set custom MAC addresses for containers

3 participants