<a id="usm-networking"></a>

# USM Agent Networking Configuration

The Unified Stream Manager (USM) Agent supports IPv4 and dual-stack (IPv4 + IPv6) network
environments. The agent does not support IPv6-only environments.

For information about agent sizing, high availability, and monitoring, see [USM Agent: Sizing, High Availability, and Monitoring](agent-sizing.md#agent-sizing).

<a id="usm-ipv6-dual-stack"></a>

## IPv6 and dual-stack networking

Starting with USM Agent version 1.1.0 and Confluent Platform 8.2, the USM Agent supports
dual-stack networking. Dual-stack combines IPv4 and IPv6 to allow clients in IPv6-enabled
environments to connect to the agent over IPv6 while preserving compatibility with
IPv4-only deployments.

The agent uses `auto` mode by default, which automatically detects IPv6 support and
configures listeners accordingly. To override this behavior, set the
`confluent.usm-agent.ip.dual.stack.enabled` property to `true` or `false`.

#### NOTE
This feature is backward compatible and requires no configuration changes for existing deployments.

### Dual-stack configuration modes

The `confluent.usm-agent.ip.dual.stack.enabled` property accepts the following values:

| Value                           | Description                                                                                                                                                                               |
|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `auto` (default)                | The agent automatically enables IPv6 support in addition to IPv4 on platforms where<br/>IPv6 is available. If the OS does not support IPv6, the agent uses IPv4-only mode.                |
| `true` (Forced dual-stack mode) | The agent enables IPv6 support in addition to IPv4 without checking for OS support.<br/>Use this value if you want the agent to run in dual-stack mode regardless of automatic detection. |
| `false` (Forced IPv4-only mode) | The agent runs in IPv4-only mode and does not add IPv6 listeners. Use this value to strictly<br/>restrict the agent to IPv4.                                                              |

### Supported environments

Dual-stack support works in the following environments:

* **IPv4-only environments**: The agent continues to operate as before and requires no configuration changes.
* **Dual-stack (IPv4 + IPv6) environments**: When you set the property to `auto` or `true`,
  the agent accepts connections over both IPv4 and IPv6.

The agent does not support IPv6-only environments. The agent requires IPv4 connectivity
to reach Confluent Cloud due to dependencies that are only available over IPv4.

### Configure dual-stack with Confluent for Kubernetes

To configure dual-stack in a CFK deployment, add the property to the `configOverrides.server`
section of your USM Agent custom resource:

```yaml
spec:
  configOverrides:
    server:
      - confluent.usm-agent.ip.dual.stack.enabled=auto
```

Replace `auto` with `true` or `false` to match your environment.

### Configure dual-stack with Ansible Playbooks for Confluent Platform

By default, Ansible Playbooks for Confluent Platform installs USM Agent version 1.0.0. To deploy version 1.1.0,
you must override the package version in your inventory file.

To enable dual-stack, set the package version to 1.1.0 and add the property to the
`usm_agent_custom_properties` section:

```yaml
all:
  vars:
    # Set USM Agent version to 1.1.0
    confluent_usm_agent_package_version: "1.1.0"
    usm_agent_custom_properties:
      confluent.usm-agent.ip.dual.stack.enabled: auto
```

Replace `auto` with `true` or `false` to match your environment.

### Related content

- [Unified Stream Manager (USM) in Confluent Platform](overview.md#usm-overview)
- [Getting Started with USM](get-started.md#usm-start)
- [USM Agent: Sizing, High Availability, and Monitoring](agent-sizing.md#agent-sizing)