Protected Mode

Protected mode keeps a Redpanda cluster without authentication from being open to the network. While it’s on, a listener with no authentication accepts clients only from the broker host, through a loopback address. It covers the Admin API, Kafka API, Schema Registry, and HTTP Proxy listeners. Without it, any client that can reach such a listener connects, and an Admin API client without credentials gets superuser access. Starting in Redpanda 26.3, protected mode is on by default for brokers in development mode on new clusters.

Set protected_mode to true to protect production-mode brokers too, until every listener has authentication. Set it to false only on a trusted network where remote clients must connect without authentication.

After reading this page, you will be able to:

  • Explain which connections protected mode rejects and which it allows

  • Determine whether protected mode is on for a cluster

  • Turn protected mode on or off for a new or existing cluster

How protected mode works

When protected mode is on, Redpanda checks each new connection or request against the listener it arrives on. If the listener has no authentication or mTLS, and the client address isn’t a loopback address (127.0.0.0/8 or ::1), Redpanda rejects it:

  • Admin API, Schema Registry, and HTTP Proxy: Every request gets an HTTP 403 response. The response body says that protected_mode is enabled and how to allow remote clients.

  • Kafka API: The broker closes the connection as soon as it accepts it. Kafka connections that were already open when protected mode turned on stay open.

Protected mode doesn’t affect:

  • Clients that connect from a loopback address.

  • Listeners that have authentication or mTLS configured.

  • The /metrics and /public_metrics endpoints of the Admin API. All other Admin API endpoints are protected, including /v1/status/ready.

  • Broker-to-broker remote procedure call (RPC) traffic.

A listener counts as authenticated when it has one of the following:

Listener Authentication that exempts it

Kafka API

Simple Authentication and Security Layer (SASL) or mtls_identity, or Transport Layer Security (TLS) with require_client_auth: true

Admin API

admin_api_require_auth set to true, or TLS with require_client_auth: true

Schema Registry and HTTP Proxy

authentication_method: http_basic, or TLS with require_client_auth: true

TLS without client certificates doesn’t count as authentication.

Internal clients of Schema Registry and HTTP Proxy

Schema Registry, HTTP Proxy, and audit logging use internal Kafka clients that connect to the brokers' advertised Kafka addresses. If those addresses aren’t loopback addresses and the Kafka listener has no authentication, protected mode rejects the internal clients too. Schema Registry and HTTP Proxy requests then fail or time out, even from localhost, instead of returning a 403. To avoid this, configure authentication on the Kafka listener, or use loopback advertised addresses for a single-host cluster.

Limitations

  • Not a replacement for authentication: Clients on the broker host still connect without credentials. On an Admin API listener without authentication, they get superuser access. To serve clients securely, configure authentication or mTLS on every listener.

  • Self-Managed only: Redpanda Cloud doesn’t support the protected_mode property.

  • Open Kafka connections stay open: Redpanda checks Kafka connections only when it accepts them. Turning protected mode on doesn’t close connections that are already open.

  • TLS alone doesn’t exempt a listener: TLS without client certificates doesn’t count as authentication.

  • Health checks are rejected: Health checks and load balancers that probe /v1/status/ready from another host get an HTTP 403 response. Only /metrics and /public_metrics stay reachable.

  • Internal clients: Schema Registry, HTTP Proxy, and audit logging fail if the Kafka listener has no authentication and the advertised Kafka addresses aren’t loopback. See Internal clients of Schema Registry and HTTP Proxy.

  • Broker-to-broker traffic isn’t covered: Protected mode doesn’t apply to the internal traffic between brokers.

  • The environment variable applies only at first start: The broker reads REDPANDA_PROTECTED_MODE only on its first start. To change protected mode later, use rpk cluster config set.

  • A configuration import can turn it back on: rpk cluster config import resets protected_mode to unset if the imported file omits it. See Protection returns after a configuration import.

When protected mode is on

The protected_mode cluster property controls protected mode. An explicit true or false applies to every broker. When the property is unset (null), each broker follows its own developer_mode setting. Brokers in development mode are protected, and brokers in production mode are not.

Cluster Effective protected mode

Created with Redpanda 26.2 or earlier, then upgraded

Off. Clusters created on 26.2 or earlier default to false.

Created with Redpanda 26.3 or later, developer_mode: false

Off

Created with Redpanda 26.3 or later, developer_mode: true

On

Started from the official Redpanda Docker image, such as with rpk container start or Docker Compose

Off. The image sets REDPANDA_PROTECTED_MODE=false.

protected_mode set to true or false

The set value, on every broker

These defaults affect common deployments in the following ways:

  • Linux packages: The redpanda.yaml that the .deb and .rpm packages install sets developer_mode: true. A fresh package install rejects remote clients on unauthenticated listeners until you run rpk redpanda mode production and restart the broker. The developer_mode broker property takes effect only after a restart.

  • Production mode: Production-mode brokers aren’t protected while protected_mode is unset. Switching to production mode removes the protection without adding authentication. To secure a production cluster, configure authentication or mTLS on every listener, or set protected_mode to true.

  • Kubernetes: The Redpanda Helm chart and Redpanda Operator don’t set developer_mode by default. Brokers run in production mode, so protected mode stays off unless you set it.

To see the current value of the property, run:

rpk cluster config get protected_mode

Turn protected mode on or off

Before you turn protected mode off, configure authentication or mTLS on the listeners that remote clients use. See Configure Authentication. Turn protected mode off only on a trusted network.

Existing cluster

To change protected mode on a running cluster, set the cluster property from a broker host. The change takes effect without a restart.

rpk cluster config set protected_mode false -X admin.hosts=127.0.0.1:9644

This command reaches the Admin API through loopback, so it works while protected mode is on. The Admin API listener must bind 0.0.0.0 or a loopback address. If it binds only another address, protected mode rejects this command too.

To turn protected mode on for every broker, including production-mode brokers, set it to true:

rpk cluster config set protected_mode true

To reset the property to its default, set it to an empty string:

rpk cluster config set protected_mode ""

On a cluster created with Redpanda 26.3 or later, the default is unset, so each broker follows its developer_mode setting again. On a cluster created with Redpanda 26.2 or earlier, the default is false.

New cluster

To create a cluster with protected mode already set, use one of the following:

  • Set protected_mode in the .bootstrap.yaml file:

    protected_mode: false
  • Set the REDPANDA_PROTECTED_MODE environment variable in the broker’s environment. See Environment variables.

The broker reads REDPANDA_PROTECTED_MODE only on its first start, before it has any cluster configuration. In a multi-broker cluster, the value from the broker that bootstraps the cluster configuration applies. A protected_mode entry in .bootstrap.yaml takes precedence, including protected_mode: null. Setting the variable on a running cluster and restarting the broker changes nothing. Use rpk cluster config set instead.

Docker

The official Redpanda Docker image sets REDPANDA_PROTECTED_MODE=false. Clients that reach a container through a published port connect from the Docker bridge network, not from loopback. To turn protected mode on in a container from the official image, set the variable to true the first time you create the container:

docker run -e REDPANDA_PROTECTED_MODE=true ... redpandadata/redpanda:<version>

Troubleshoot protected mode rejections

If a client on the broker host can connect but a remote client can’t, check whether protected mode rejected it.

  • Kafka clients: The connection closes as soon as it opens. Some clients report this as a TLS or SASL problem. For example, rpk prints:

    broker closed the connection immediately during api versions negotiation, which often happens when the broker requires TLS but the client is using plaintext: is TLS missing?
  • Admin API, Schema Registry, and HTTP Proxy clients: Requests return HTTP 403. Health checks and load balancers that probe /v1/status/ready get the same 403, while /metrics scrapes keep working.

The broker logs each rejection at the ERROR level, at most one line every 10 seconds per shard for each API:

Rejected Kafka connection from <addr> on listener <name>: protected_mode is enabled ...
Rejected Admin API request <method> <url> from <addr>: protected_mode is enabled ...
Rejected request <method> <url> from <addr>: protected_mode is enabled ...

The last line comes from Schema Registry and HTTP Proxy. If the log shows Rejected Kafka connection from with a broker’s own address, protected mode is rejecting the internal clients of Schema Registry and HTTP Proxy.

To fix a rejection, try these in order:

  1. Configure authentication or mTLS on the listener that remote clients use. See Configure Authentication.

  2. Connect from the broker host through localhost. For Kafka, this works only if the advertised Kafka addresses are also loopback addresses, because clients reconnect to the advertised addresses.

  3. If the network is trusted, turn protected mode off.

Protection returns after a configuration import

rpk cluster config import resets every property that the imported file omits. If the file has no protected_mode line, the property returns to unset, and brokers in development mode are protected again. This includes Docker clusters started with --mode dev-container, because the image’s environment variable applies only to the first start. To keep protected mode off, add protected_mode: false to the file before you import it.