Introduction

inter.broker.listener.name tells a Kafka broker which named listener it should use when talking to other brokers. In SSL setups, the confusion usually comes from mixing up the listener name with the actual security protocol, or from setting inter.broker.listener.name and security.inter.broker.protocol in ways that conflict.

The Important Distinction

Kafka listener configuration has two related but different ideas:

• a listener name, such as INTERNAL or EXTERNAL
• a security protocol, such as PLAINTEXT, SSL, or SASL_SSL

When you define multiple listeners, the name is just a label. Kafka maps that label to a real protocol through listener.security.protocol.map.

For example:

1listeners=INTERNAL://:9093,EXTERNAL://:9094
2advertised.listeners=INTERNAL://broker1:9093,EXTERNAL://broker1.example.com:9094
3listener.security.protocol.map=INTERNAL:SSL,EXTERNAL:SSL
4inter.broker.listener.name=INTERNAL

Here, INTERNAL is the listener name. SSL is the protocol that listener uses.

Why inter.broker.listener.name Exists

If a broker exposes more than one listener, Kafka needs to know which one should be used for broker-to-broker communication. That is what inter.broker.listener.name decides.

In a secure cluster, you often want:

• one internal listener for broker communication
• one external listener for clients

The internal one is then referenced by name:

inter.broker.listener.name=INTERNAL

Not:

inter.broker.listener.name=SSL

unless your listener was literally named SSL.

Do Not Mix It with security.inter.broker.protocol

This is a classic source of confusion. Kafka supports two styles:

1. use security.inter.broker.protocol
2. use inter.broker.listener.name

When you are using named listeners in a multi-listener setup, inter.broker.listener.name is usually the better choice. Setting both can lead to inconsistent configuration or startup failure.

A clean SSL-oriented example looks like this:

1listeners=INTERNAL://:9093
2advertised.listeners=INTERNAL://broker1:9093
3listener.security.protocol.map=INTERNAL:SSL
4inter.broker.listener.name=INTERNAL
5
6ssl.keystore.location=/var/private/ssl/kafka.keystore.jks
7ssl.keystore.password=changeit
8ssl.key.password=changeit
9ssl.truststore.location=/var/private/ssl/kafka.truststore.jks
10ssl.truststore.password=changeit

That tells Kafka to use the listener named INTERNAL, and that listener speaks SSL.

Multi-Listener Example

A more realistic setup may separate internal and external traffic:

1listeners=INTERNAL://:9093,EXTERNAL://:9094
2advertised.listeners=INTERNAL://broker1:9093,EXTERNAL://broker1.example.com:9094
3listener.security.protocol.map=INTERNAL:SSL,EXTERNAL:SSL
4inter.broker.listener.name=INTERNAL

Clients connect to EXTERNAL, but brokers talk to each other on INTERNAL.

This separation is useful because inter-broker traffic often has different DNS names, ports, and trust assumptions from client traffic.

How to Choose the Value

Pick the listener name that should carry cluster-internal traffic. In many deployments that is something like:

• 'INTERNAL'
• 'BROKER'
• 'REPLICATION'

The name is up to you. What matters is that:

1. it exists in listeners
2. it appears in listener.security.protocol.map
3. its protocol and certificates are valid for broker-to-broker connections

If brokers cannot connect after this is set, inspect the listener name first, then verify certificate trust, hostnames, and whether the advertised address on that listener is reachable from peer brokers in both DNS and firewall terms during actual cluster startup across the whole cluster under real network conditions.

Common Pitfalls

One common mistake is setting inter.broker.listener.name=SSL because SSL is the protocol. That only works if the listener was actually named SSL.

Another issue is setting both security.inter.broker.protocol=SSL and inter.broker.listener.name=INTERNAL in a multi-listener configuration without understanding which one Kafka should honor. Keep the configuration model consistent.

A third problem is configuring SSL keystores correctly but advertising the wrong hostname. In that case, the listener choice may be correct while certificate or network identity still causes connection failures.

Summary

• 'inter.broker.listener.name expects a listener name, not a protocol keyword.'
• The listener name is mapped to a real protocol through listener.security.protocol.map.
• In SSL setups, the internal listener is often something like INTERNAL, mapped to SSL.
• Avoid mixing inter.broker.listener.name and security.inter.broker.protocol carelessly.
• Make sure the chosen internal listener has correct SSL certificates, hostnames, and advertised addresses.