How to Configure Custom MTU for Container Network Interfaces in apple/container

Set the MTU using the --network CLI flag with syntax network_name,mtu=VALUE or pass an AttachmentOptions instance with the mtu parameter when creating containers via the Swift API.

Configuring the Maximum Transmission Unit (MTU) for container network interfaces ensures optimal packet sizes across different network topologies. In the apple/container repository, the MTU is configured through the AttachmentOptions model and propagated to the container's virtual NIC during initialization. This guide covers both CLI and programmatic approaches based on the actual source implementation.

Understanding the MTU Configuration Architecture

The AttachmentOptions Model

In Sources/ContainerResource/Network/AttachmentConfiguration.swift (lines 41-48), the AttachmentOptions struct defines the optional mtu field as a UInt32?:

struct AttachmentOptions {
    let hostname: String?
    let macAddress: String?
    let mtu: UInt32?  // Custom MTU value in bytes
}

This struct is serialized into AttachmentConfiguration and sent to the container daemon when establishing network attachments.

Runtime Attachment Representation

The Attachment struct in Sources/ContainerResource/Network/Attachment.swift (lines 34-36) mirrors this value for running containers, exposing the configured MTU to the runtime system. This allows the container daemon to apply the specific MTU value when creating the virtual network interface inside the container namespace.

Setting Custom MTU via Command Line

The CLI implementation in Sources/Services/ContainerAPIService/Client/Flags.swift (line 289) supports the following syntax for network attachment options:

container run --network default,mtu=1500 <image> [command...]

The parser in Sources/Services/ContainerAPIService/Client/Parser.swift (lines 826-827) handles the extraction logic:

• Parses the comma-separated components from the --network flag
• Identifies the mtu key and converts its value to a UInt32 integer
• Populates the AttachmentOptions structure with the parsed value

Configuring MTU Programmatically with Swift

When using the Swift API directly, construct an AttachmentOptions instance with the desired MTU value:

import ContainerizationExtras

let options = AttachmentOptions(
    hostname: "my-container",
    macAddress: nil,
    mtu: 1500  // Custom MTU in bytes
)

let config = AttachmentConfiguration(
    network: "default",
    options: options
)

try client.createContainer(name: "my-container", networks: [config])

Omitting the mtu parameter results in nil, which instructs the system to use the default network MTU.

Verification and End-to-End Flow

The integration test in Tests/IntegrationTests/Network/TestCLINetwork.swift (lines 116-124) validates the complete MTU configuration workflow:

1. User input supplies MTU via CLI (--network default,mtu=1500) or Swift API
2. Flag parser creates AttachmentOptions with mtu: 1500
3. Client builds AttachmentConfiguration and transmits to the daemon
4. Daemon stores the value in the container's network attachment metadata
5. Runtime configures the virtual NIC (typically eth0) with the requested MTU

Verify the configuration inside a running container:

ip link show eth0

The output should contain mtu 1500 (or your specified value) confirming the interface configuration.

Summary

• The MTU is configured through the optional mtu field in AttachmentOptions defined in AttachmentConfiguration.swift
• Use the CLI syntax --network name,mtu=VALUE for command-line deployments, parsed by Parser.swift
• Pass a UInt32 value to AttachmentOptions(mtu:) when using the Swift API
• The value propagates from client to daemon to virtual NIC configuration according to the implementation in Attachment.swift
• Integration tests in TestCLINetwork.swift confirm the MTU is applied correctly to container interfaces

Frequently Asked Questions

What is the default MTU if not specified?

When the mtu parameter is omitted from AttachmentOptions (nil), the system uses the default network MTU configured by the container daemon. The field is defined as UInt32? in AttachmentConfiguration.swift, making it optional in both the struct definition and CLI parsing.

Can I set different MTU values for different networks?

Yes. Since the MTU is specified per network attachment via the --network flag or individual AttachmentConfiguration instances, you can configure different MTU values for each network interface when attaching a container to multiple networks simultaneously.

How does the MTU value propagate from the API to the container?

The value flows through Sources/Services/ContainerAPIService/Client/Parser.swift (lines 826-827) where the CLI string is parsed, then serialized into AttachmentOptions and AttachmentConfiguration. The daemon receives this configuration and applies it when creating the virtual network interface inside the container namespace, as represented by the Attachment model in Attachment.swift.

Where is the MTU validation handled?

The source analysis indicates that Parser.swift handles the extraction and conversion to UInt32. Additional validation regarding acceptable MTU ranges (typically 68-65535 bytes) likely occurs in the daemon when applying the configuration, though the specific validation logic is not detailed in the core network attachment files referenced.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}