Add --mac-address flag to set custom MAC addresses for containers #753

DSS3113 · 2025-10-12T04:11:46Z

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

Sources/ContainerClient/Utility.swift

jglogan · 2025-10-16T20:56:38Z

@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 · 2025-10-16T21:01:22Z

@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 · 2025-10-18T17:08:38Z

@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.

jglogan · 2025-10-21T18:30:58Z

@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!

DSS3113 · 2025-10-22T01:24:55Z

@jglogan Resolved merge conflicts!

Sources/ContainerClient/Parser.swift

jglogan · 2025-10-24T17:07:59Z

@DSS3113 I'm seeing the following with my local build:

% container run -it --name foo --network default,mac=c1:2f:c2:fd:ce:0b alpine:latest sh
Warning! Running debug build. Performance may be degraded.
Error: internalError: "failed to bootstrap container" (cause: "internalError: "failed to bootstrap container foo (cause: "unknown: "internal error (13): ip-link-set: netlink response indicates error, rc = -99"")"")

Are you seeing that it's working without issue on your system?

jglogan · 2025-10-24T17:10:22Z

Ah, that's a multicast address (I just generated a random one). Let me try with a different one...

jglogan · 2025-10-24T17:12:36Z

@DSS3113 Yep, looks good. Lemme take one last look at the code. Could you look at the one comment I posted above?

% container run -it --rm --network default,mac=c2:2f:c2:fd:ce:0b alpine:latest ip link
Warning! Running debug build. Performance may be degraded.
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eth0: <BROADCAST,UP,LOWER_UP> mtu 1280 qdisc pfifo_fast state UP qlen 1000
    link/ether c2:2f:c2:fd:ce:0b brd ff:ff:ff:ff:ff:ff
3: teql0: <NOARP> mtu 1500 qdisc noop state DOWN qlen 100
    link/void 
4: tunl0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN qlen 1000
    link/ipip 0.0.0.0 brd 0.0.0.0
5: sit0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN qlen 1000
    link/sit 0.0.0.0 brd 0.0.0.0
6: ip6tnl0@NONE: <NOARP> mtu 1452 qdisc noop state DOWN qlen 1000
    link/tunnel6 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 brd 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00

jglogan · 2025-10-24T17:14:45Z

@DSS3113 Also it looks like some of your commits in this PR might not have verified sigs.

Could you rebase your branch, reset it back to main, do a single squashed, verified commit, and force push that? I think we're good to go after that.

DSS3113 · 2025-10-24T21:40:18Z

@jglogan Thanks for reviewing! I've done the needful.

jglogan · 2025-10-25T02:30:59Z

Any idea why 4652e2f got pulled into this PR? That's already down in main.

DSS3113 · 2025-10-25T03:39:02Z

@jglogan I believe I cherry-picked the commit and that created a duplicate. My bad, it should be fixed now.

jglogan · 2025-10-25T14:10:45Z

@DSS3113 It looks like there are make fmt issues, and I still see a merge commit (72530a3) that shouldn't be there if your change was cleanly rebased onto the latest main. Could you rebase just your changes onto the current main and run make fmt to resolve the build issues? I think everything should be good to go then. Thank you!

DSS3113 · 2025-10-25T21:15:00Z

@jglogan My sincere apologies! I think it should be good now.

Sources/ContainerCommands/System/DNS/DNSDelete.swift

jglogan

Sorry, only now noticed some seemingly unnecessary diffs in command-reference.md, see comments.

jglogan · 2025-10-30T20:08:08Z

docs/command-reference.md

 **Usage**

 ```bash
-container run [<options>] <image> [<arguments> ...]


I just noticed that there are a lot of changes compared to current main that don't need to be made, along with at least one regression. Could you fix this so that only the PR only updates the material relating to the MAC address? Apologies for the hassle!

I apologize for the trouble. I somehow missed these. Should be fixed now.

No worries! I appreciate your persistence.

Not an excuse but a self-criticism 😄 I've been paging out of PR and issue reviews a lot and I fear it's cost contributors several more round trips than the PRs really need. Something for me to work on!

It’s alright, I understand! Thanks again!

jglogan · 2025-10-30T20:09:41Z

docs/command-reference.md

-Builds an OCI image from a local build context. It reads a Dockerfile (default `Dockerfile`) or Containerfile and produces an image tagged with `-t` option. The build runs in isolation using BuildKit, and resource limits may be set for the build process itself.
-
-When no `-f/--file` is specified, the build command will look for `Dockerfile` first, then fall back to `Containerfile` if `Dockerfile` is not found.
+Builds an OCI image from a local build context. It reads a Dockerfile (default `Dockerfile`) and produces an image tagged with `-t` option. The build runs in isolation using BuildKit, and resource limits may be set for the build process itself.


Regression?

This commit adds support for customizing MAC addresses for containers.

jglogan · 2025-10-30T22:55:20Z

Sources/Services/ContainerNetworkService/NetworkService.swift

        }

        let hostname = try message.hostname()
+        let macAddress = message.string(key: NetworkKeys.macAddress.rawValue)


Just a note to myself and any interested parties here, no change required for this PR.

@dcantah reworked the client, API server, and Sandbox Service so that the client only deals with the API server for sandbox management (instead of the doing bootstrap through API server and the rest directly with the sandbox service) for the 0.5.0 release. This gives us the opportunity to make the API server responsible for allocating IP addresses at container start, and freeing the allocations when a container stops for any reason. Currently if container-linux-runtime gets terminated (SIGKILL) or faults, the IP will be orphaned.

When we make that change we might want simplify this by only passing what's needed for IP allocation and hostname resolution, and see if we can take the returned Attachment and integrate it with the MAC address and other caller-specified properties not related to the core network service functions to produce and Attachment that we can transfer over to the sandbox service at container start time. We trade a simpler interface between NetworkService and its caller for a little more complexity creating the Attachment that contains the user-specified network attributes, the allocated attributes, and the vmnet_network_ref.

siikamiika mentioned this pull request Oct 12, 2025

Specify ip in --network #751

Open

7 tasks

siikamiika reviewed Oct 12, 2025

View reviewed changes

Sources/ContainerClient/Utility.swift Outdated Show resolved Hide resolved

DSS3113 marked this pull request as draft October 18, 2025 17:08

DSS3113 marked this pull request as ready for review October 20, 2025 22:00

DSS3113 marked this pull request as draft October 20, 2025 22:17

DSS3113 marked this pull request as ready for review October 20, 2025 22:20

jglogan reviewed Oct 24, 2025

View reviewed changes

Sources/ContainerClient/Parser.swift Outdated Show resolved Hide resolved

DSS3113 force-pushed the custom-mac-address branch 10 times, most recently from 2de8746 to bfab5ec Compare October 24, 2025 21:39

DSS3113 force-pushed the custom-mac-address branch 2 times, most recently from f921339 to 4652e2f Compare October 24, 2025 23:54

DSS3113 force-pushed the custom-mac-address branch from c03cce1 to a38bc9e Compare October 25, 2025 03:37

DSS3113 force-pushed the custom-mac-address branch 2 times, most recently from dfcf7f7 to b8283f5 Compare October 25, 2025 21:12

DSS3113 force-pushed the custom-mac-address branch 5 times, most recently from d41b25d to 9c9fa40 Compare October 30, 2025 16:12

jglogan requested changes Oct 30, 2025

View reviewed changes

Sources/ContainerCommands/System/DNS/DNSDelete.swift Outdated Show resolved Hide resolved

DSS3113 force-pushed the custom-mac-address branch from 9c9fa40 to a7b21ae Compare October 30, 2025 16:58

DSS3113 requested a review from jglogan October 30, 2025 17:00

jglogan requested changes Oct 30, 2025

View reviewed changes

DSS3113 force-pushed the custom-mac-address branch 2 times, most recently from 4ed4ac9 to cd7a14f Compare October 30, 2025 21:22

Add MAC address customization

c468fa9

This commit adds support for customizing MAC addresses for containers.

DSS3113 force-pushed the custom-mac-address branch from cd7a14f to c468fa9 Compare October 30, 2025 21:28

DSS3113 requested a review from jglogan October 30, 2025 21:31

jglogan reviewed Oct 30, 2025

View reviewed changes

jglogan approved these changes Oct 30, 2025

View reviewed changes

jglogan merged commit c909cb3 into apple:main Oct 30, 2025
2 checks passed

DSS3113 deleted the custom-mac-address branch October 30, 2025 23:26

Add --mac-address flag to set custom MAC addresses for containers #753

Add --mac-address flag to set custom MAC addresses for containers #753

Uh oh!

Conversation

DSS3113 commented Oct 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of Change

Motivation and Context

Use Cases

Testing

Issue

Uh oh!

Uh oh!

jglogan commented Oct 16, 2025

Uh oh!

jglogan commented Oct 16, 2025

Uh oh!

DSS3113 commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Oct 21, 2025

Uh oh!

DSS3113 commented Oct 22, 2025

Uh oh!

Uh oh!

jglogan commented Oct 24, 2025

Uh oh!

jglogan commented Oct 24, 2025

Uh oh!

jglogan commented Oct 24, 2025

Uh oh!

jglogan commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DSS3113 commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Oct 25, 2025

Uh oh!

DSS3113 commented Oct 25, 2025

Uh oh!

jglogan commented Oct 25, 2025

Uh oh!

DSS3113 commented Oct 25, 2025

Uh oh!

Uh oh!

jglogan left a comment

Choose a reason for hiding this comment

Uh oh!

jglogan Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

DSS3113 Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

jglogan Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

DSS3113 Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

jglogan Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

DSS3113 Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

jglogan Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

DSS3113 commented Oct 12, 2025 •

edited

Loading

DSS3113 commented Oct 18, 2025 •

edited

Loading

jglogan commented Oct 24, 2025 •

edited

Loading

DSS3113 commented Oct 24, 2025 •

edited

Loading