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_modeis 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
/metricsand/public_metricsendpoints 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 |
Admin API |
|
Schema Registry and HTTP Proxy |
|
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_modeproperty. -
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/readyfrom another host get an HTTP 403 response. Only/metricsand/public_metricsstay 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_MODEonly on its first start. To change protected mode later, userpk cluster config set. -
A configuration import can turn it back on:
rpk cluster config importresetsprotected_modeto 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 |
Created with Redpanda 26.3 or later, |
Off |
Created with Redpanda 26.3 or later, |
On |
Started from the official Redpanda Docker image, such as with |
Off. The image sets |
|
The set value, on every broker |
These defaults affect common deployments in the following ways:
-
Linux packages: The
redpanda.yamlthat the.deband.rpmpackages install setsdeveloper_mode: true. A fresh package install rejects remote clients on unauthenticated listeners until you runrpk redpanda mode productionand restart the broker. Thedeveloper_modebroker property takes effect only after a restart. -
Production mode: Production-mode brokers aren’t protected while
protected_modeis unset. Switching to production mode removes the protection without adding authentication. To secure a production cluster, configure authentication or mTLS on every listener, or setprotected_modetotrue. -
Kubernetes: The Redpanda Helm chart and Redpanda Operator don’t set
developer_modeby 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_modein the.bootstrap.yamlfile:protected_mode: false -
Set the
REDPANDA_PROTECTED_MODEenvironment 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,
rpkprints: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/readyget the same 403, while/metricsscrapes 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:
-
Configure authentication or mTLS on the listener that remote clients use. See Configure Authentication.
-
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. -
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.