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

> Configure custom MTU for container network interfaces in apple container using the network CLI flag or Swift API. Optimize network performance now.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/apple/container/blob/main/Sources/ContainerResource/Network/AttachmentConfiguration.swift) (lines 41-48), the `AttachmentOptions` struct defines the optional `mtu` field as a `UInt32?`:

```swift
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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Flags.swift) (line 289) supports the following syntax for network attachment options:

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

```

The parser in [`Sources/Services/ContainerAPIService/Client/Parser.swift`](https://github.com/apple/container/blob/main/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:

```swift
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`](https://github.com/apple/container/blob/main/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:

```bash
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`](https://github.com/apple/container/blob/main/AttachmentConfiguration.swift)
- Use the **CLI syntax** `--network name,mtu=VALUE` for command-line deployments, parsed by [`Parser.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Attachment.swift)
- Integration tests in [`TestCLINetwork.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Attachment.swift).

### Where is the MTU validation handled?

The source analysis indicates that [`Parser.swift`](https://github.com/apple/container/blob/main/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.