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

- Closes #752.
- 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

Author: DSS3113

.gitignore

@@ -13,6 +13,7 @@ api-docs/
 workdir/
 installer/
 .venv/
+.claude/
 .clitests/
 test_results/
 *.pid

Sources/ContainerClient/Core/ContainerConfiguration.swift

@@ -89,7 +89,9 @@ public struct ContainerConfiguration: Sendable, Codable {
                 networks = try container.decode([AttachmentConfiguration].self, forKey: .networks)
             } catch {
                 let networkIds = try container.decode([String].self, forKey: .networks)
-                networks = try Utility.getAttachmentConfigurations(containerId: id, networkIds: networkIds)
+                // Parse old network IDs as simple network names without properties
+                let parsedNetworks = networkIds.map { Parser.ParsedNetwork(name: $0, macAddress: nil) }
+                networks = try Utility.getAttachmentConfigurations(containerId: id, networks: parsedNetworks)
             }
         } else {
             networks = []

Sources/ContainerClient/Flags.swift

@@ -151,7 +151,7 @@ public struct Flags {
         @Option(name: .long, help: "Use the specified name as the container ID")
         public var name: String?
 
-        @Option(name: [.customLong("network")], help: "Attach the container to a network")
+        @Option(name: [.customLong("network")], help: "Attach the container to a network (format: <name>[,mac=XX:XX:XX:XX:XX:XX])")
         public var networks: [String] = []
 
         @Flag(name: [.customLong("no-dns")], help: "Do not configure DNS in the container")

Sources/ContainerClient/Parser.swift

@@ -712,6 +712,76 @@ public struct Parser {
         }
     }
 
+    // MARK: Networks
+
+    /// Parsed network attachment with optional properties
+    public struct ParsedNetwork {
+        public let name: String
+        public let macAddress: String?
+
+        public init(name: String, macAddress: String? = nil) {
+            self.name = name
+            self.macAddress = macAddress
+        }
+    }
+
+    /// Parse network attachment with optional properties
+    /// Format: network_name[,mac=XX:XX:XX:XX:XX:XX]
+    /// Example: "backend,mac=02:42:ac:11:00:02"
+    public static func network(_ networkSpec: String) throws -> ParsedNetwork {
+        guard !networkSpec.isEmpty else {
+            throw ContainerizationError(.invalidArgument, message: "network specification cannot be empty")
+        }
+
+        let parts = networkSpec.split(separator: ",", omittingEmptySubsequences: false)
+
+        guard !parts.isEmpty else {
+            throw ContainerizationError(.invalidArgument, message: "network specification cannot be empty")
+        }
+
+        let networkName = String(parts[0])
+        if networkName.isEmpty {
+            throw ContainerizationError(.invalidArgument, message: "network name cannot be empty")
+        }
+
+        var macAddress: String?
+
+        // Parse properties if any
+        for part in parts.dropFirst() {
+            let keyVal = part.split(separator: "=", maxSplits: 2, omittingEmptySubsequences: false)
+
+            let key: String
+            let value: String
+
+            guard keyVal.count == 2 else {
+                throw ContainerizationError(
+                    .invalidArgument,
+                    message: "invalid property format '\(part)' in network specification '\(networkSpec)'"
+                )
+            }
+            key = String(keyVal[0])
+            value = String(keyVal[1])
+
+            switch key {
+            case "mac":
+                if value.isEmpty {
+                    throw ContainerizationError(
+                        .invalidArgument,
+                        message: "mac address value cannot be empty"
+                    )
+                }
+                macAddress = value
+            default:
+                throw ContainerizationError(
+                    .invalidArgument,
+                    message: "unknown network property '\(key)'. Available properties: mac"
+                )
+            }
+        }
+
+        return ParsedNetwork(name: networkName, macAddress: macAddress)
+    }
+
     // MARK: DNS
 
     public static func isValidDomainName(_ name: String) -> Bool {

Sources/ContainerClient/Utility.swift

@@ -62,6 +62,14 @@ public struct Utility {
         }
     }
 
+    public static func validMACAddress(_ macAddress: String) throws {
+        let pattern = #"^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$"#
+        let regex = try Regex(pattern)
+        if try regex.firstMatch(in: macAddress) == nil {
+            throw ContainerizationError(.invalidArgument, message: "invalid MAC address format \(macAddress), expected format: XX:XX:XX:XX:XX:XX")
+        }
+    }
+
     public static func containerConfigFromFlags(
         id: String,
         image: String,
@@ -176,13 +184,15 @@ public struct Utility {
 
         config.virtualization = management.virtualization
 
+        // Parse network specifications with properties
+        let parsedNetworks = try management.networks.map { try Parser.network($0) }
         if management.networks.contains(ClientNetwork.noNetworkName) {
             guard management.networks.count == 1 else {
                 throw ContainerizationError(.unsupported, message: "no other networks may be created along with network \(ClientNetwork.noNetworkName)")
             }
             config.networks = []
         } else {
-            config.networks = try getAttachmentConfigurations(containerId: config.id, networkIds: management.networks)
+            config.networks = try getAttachmentConfigurations(containerId: config.id, networks: parsedNetworks)
             for attachmentConfiguration in config.networks {
                 let network: NetworkState = try await ClientNetwork.get(id: attachmentConfiguration.network)
                 guard case .running(_, _) = network else {
@@ -220,7 +230,14 @@ public struct Utility {
         return (config, kernel)
     }
 
-    static func getAttachmentConfigurations(containerId: String, networkIds: [String]) throws -> [AttachmentConfiguration] {
+    static func getAttachmentConfigurations(containerId: String, networks: [Parser.ParsedNetwork]) throws -> [AttachmentConfiguration] {
+        // Validate MAC addresses if provided
+        for network in networks {
+            if let mac = network.macAddress {
+                try validMACAddress(mac)
+            }
+        }
+
         // make an FQDN for the first interface
         let fqdn: String?
         if !containerId.contains(".") {
@@ -235,22 +252,33 @@ public struct Utility {
             fqdn = "\(containerId)."
         }
 
-        guard networkIds.isEmpty else {
-            // networks may only be specified for macOS 26+
-            guard #available(macOS 26, *) else {
-                throw ContainerizationError(.invalidArgument, message: "non-default network configuration requires macOS 26 or newer")
+        guard networks.isEmpty else {
+            // Check if this is only the default network with properties (e.g., MAC address)
+            let isOnlyDefaultNetwork = networks.count == 1 && networks[0].name == ClientNetwork.defaultNetworkName
+
+            // networks may only be specified for macOS 26+ (except for default network with properties)
+            if !isOnlyDefaultNetwork {
+                guard #available(macOS 26, *) else {
+                    throw ContainerizationError(.invalidArgument, message: "non-default network configuration requires macOS 26 or newer")
+                }
             }
 
             // attach the first network using the fqdn, and the rest using just the container ID
-            return networkIds.enumerated().map { item in
+            return networks.enumerated().map { item in
                 guard item.offset == 0 else {
-                    return AttachmentConfiguration(network: item.element, options: AttachmentOptions(hostname: containerId))
+                    return AttachmentConfiguration(
+                        network: item.element.name,
+                        options: AttachmentOptions(hostname: containerId, macAddress: item.element.macAddress)
+                    )
                 }
-                return AttachmentConfiguration(network: item.element, options: AttachmentOptions(hostname: fqdn ?? containerId))
+                return AttachmentConfiguration(
+                    network: item.element.name,
+                    options: AttachmentOptions(hostname: fqdn ?? containerId, macAddress: item.element.macAddress)
+                )
             }
         }
         // if no networks specified, attach to the default network
-        return [AttachmentConfiguration(network: ClientNetwork.defaultNetworkName, options: AttachmentOptions(hostname: fqdn ?? containerId))]
+        return [AttachmentConfiguration(network: ClientNetwork.defaultNetworkName, options: AttachmentOptions(hostname: fqdn ?? containerId, macAddress: nil))]
     }
 
     private static func getKernel(management: Flags.Management) async throws -> Kernel {

Sources/Helpers/RuntimeLinux/IsolatedInterfaceStrategy.swift

@@ -25,6 +25,6 @@ import Containerization
 struct IsolatedInterfaceStrategy: InterfaceStrategy {
     public func toInterface(attachment: Attachment, interfaceIndex: Int, additionalData: XPCMessage?) -> Interface {
         let gateway = interfaceIndex == 0 ? attachment.gateway : nil
-        return NATInterface(address: attachment.address, gateway: gateway)
+        return NATInterface(address: attachment.address, gateway: gateway, macAddress: attachment.macAddress)
     }
 }

Sources/Helpers/RuntimeLinux/NonisolatedInterfaceStrategy.swift

@@ -44,6 +44,6 @@ struct NonisolatedInterfaceStrategy: InterfaceStrategy {
 
         log.info("creating NATNetworkInterface with network reference")
         let gateway = interfaceIndex == 0 ? attachment.gateway : nil
-        return NATNetworkInterface(address: attachment.address, gateway: gateway, reference: networkRef)
+        return NATNetworkInterface(address: attachment.address, gateway: gateway, reference: networkRef, macAddress: attachment.macAddress)
     }
 }

Sources/Services/ContainerNetworkService/Attachment.swift

@@ -24,11 +24,14 @@ public struct Attachment: Codable, Sendable {
     public let address: String
     /// The IPv4 gateway address.
     public let gateway: String
+    /// The MAC address associated with the attachment (optional).
+    public let macAddress: String?
 
-    public init(network: String, hostname: String, address: String, gateway: String) {
+    public init(network: String, hostname: String, address: String, gateway: String, macAddress: String? = nil) {
         self.network = network
         self.hostname = hostname
         self.address = address
         self.gateway = gateway
+        self.macAddress = macAddress
     }
 }

Sources/Services/ContainerNetworkService/AttachmentConfiguration.swift

@@ -33,7 +33,11 @@ public struct AttachmentOptions: Codable, Sendable {
     /// The hostname associated with the attachment.
     public let hostname: String
 
-    public init(hostname: String) {
+    /// The MAC address associated with the attachment (optional).
+    public let macAddress: String?
+
+    public init(hostname: String, macAddress: String? = nil) {
         self.hostname = hostname
+        self.macAddress = macAddress
     }
 }

Sources/Services/ContainerNetworkService/NetworkClient.swift

@@ -46,9 +46,12 @@ extension NetworkClient {
         return state
     }
 
-    public func allocate(hostname: String) async throws -> (attachment: Attachment, additionalData: XPCMessage?) {
+    public func allocate(hostname: String, macAddress: String? = nil) async throws -> (attachment: Attachment, additionalData: XPCMessage?) {
         let request = XPCMessage(route: NetworkRoutes.allocate.rawValue)
         request.set(key: NetworkKeys.hostname.rawValue, value: hostname)
+        if let macAddress = macAddress {
+            request.set(key: NetworkKeys.macAddress.rawValue, value: macAddress)
+        }
 
         let client = createClient()