You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by lh...@apache.org on 2022/09/23 18:12:19 UTC
[pulsar] branch branch-2.11 updated: [doc][proxy] Document how to mitigate CVE-2022-24280 (#17825)
This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch branch-2.11
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/branch-2.11 by this push:
new a5cabbcfeb7 [doc][proxy] Document how to mitigate CVE-2022-24280 (#17825)
a5cabbcfeb7 is described below
commit a5cabbcfeb766516cf76e77db8e71ba1b1aa6cc9
Author: Lari Hotari <lh...@users.noreply.github.com>
AuthorDate: Fri Sep 23 17:22:16 2022 +0300
[doc][proxy] Document how to mitigate CVE-2022-24280 (#17825)
(cherry picked from commit 0c0984a81488f6da0cf46576b50345bb08e78be7)
---
SECURITY.md | 5 +-
site2/docs/administration-proxy.md | 45 +++++++++++-
.../version-2.10.0/administration-proxy.md | 55 ++++++++++++---
.../version-2.10.1/administration-proxy.md | 55 ++++++++++++---
.../version-2.8.0/administration-proxy.md | 79 ++++++++++++++++------
.../version-2.8.1/administration-proxy.md | 79 ++++++++++++++++------
.../version-2.8.2/administration-proxy.md | 79 ++++++++++++++++------
.../version-2.9.0/administration-proxy.md | 77 +++++++++++++++------
.../version-2.9.1/administration-proxy.md | 77 +++++++++++++++------
.../version-2.9.3/administration-proxy.md | 77 +++++++++++++++------
10 files changed, 491 insertions(+), 137 deletions(-)
diff --git a/SECURITY.md b/SECURITY.md
index c474eb7f4bd..43d38063850 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,3 +1,6 @@
# Security Policy
-The security policy and supported versions are outlined on the Pulsar website here: https://pulsar.apache.org/docs/security-policy-and-supported-versions/.
\ No newline at end of file
+The security policy and supported versions are outlined on the Pulsar website here: https://pulsar.apache.org/docs/security-policy-and-supported-versions/.
+## Security Advisories
+
+Please visit the [Security Advisories](https://github.com/apache/pulsar/wiki/Security-advisories) page.
\ No newline at end of file
diff --git a/site2/docs/administration-proxy.md b/site2/docs/administration-proxy.md
index 5228b9a65dd..03776508971 100644
--- a/site2/docs/administration-proxy.md
+++ b/site2/docs/administration-proxy.md
@@ -6,6 +6,10 @@ sidebar_label: "Pulsar proxy"
Pulsar proxy is an optional gateway. Pulsar proxy is used when direct connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
+The Pulsar proxy is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. The requirement of network perimeter security can be achieved with private networks.
+
+If a proxy deployment cannot be protected with network perimeter security, the alternative would be to use [Pulsar's "Proxy SNI routing" feature](concepts-proxy-sni-routing.md) with a properly secured and audited solution. In that case Pulsar proxy component is not used at all.
+
## Configure the proxy
Before using the proxy, you need to configure it with the brokers addresses in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
@@ -57,7 +61,46 @@ configurationMetadataStoreUrl=my-zk-0:2184,my-zk-remote:2184
> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
-> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+
+### Restricting target broker addresses to mitigate CVE-2022-24280
+
+The Pulsar Proxy trusts clients to provide valid target broker addresses to connect to.
+Unless the Pulsar Proxy is explicitly configured to limit access, the Pulsar Proxy is vulnerable as described in the security advisory [Apache Pulsar Proxy target broker address isn't validated (CVE-2022-24280)](https://github.com/apache/pulsar/wiki/CVE-2022-24280).
+
+It is necessary to limit proxied broker connections to known broker addresses by specifying `brokerProxyAllowedHostNames` and `brokerProxyAllowedIPAddresses` settings.
+
+When specifying `brokerProxyAllowedHostNames`, it's possible to use a wildcard.
+Please notice that `*` is a wildcard that matches any character in the hostname. It also matches dot `.` characters.
+
+It is recommended to use a pattern that matches only the desired brokers and no other hosts in the local network. Pulsar lookups will use the default host name of the broker by default. This can be overridden with the `advertisedAddress` setting in `broker.conf`.
+
+To increase security, it is also possible to restrict access with the `brokerProxyAllowedIPAddresses` setting. It is not mandatory to configure `brokerProxyAllowedIPAddresses` when `brokerProxyAllowedHostNames` is properly configured so that the pattern matches only the target brokers.
+`brokerProxyAllowedIPAddresses` setting supports a comma separate list of IP address, IP address ranges and IP address networks [(supported format reference)](https://seancfoley.github.io/IPAddress/IPAddress/apidocs/inet/ipaddr/IPAddressString.html).
+
+Example: limiting by host name in a Kubernetes deployment
+```yaml
+ # example of limiting to Kubernetes statefulset hostnames that contain "broker-"
+ PULSAR_PREFIX_brokerProxyAllowedHostNames: '*broker-*.*.*.svc.cluster.local'
+```
+
+Example: limiting by both host name and ip address in a `proxy.conf` file for host deployment.
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain
+# limit target ip addresses to a specific network
+brokerProxyAllowedIPAddresses=10.0.0.0/8
+```
+
+Example: limiting by multiple host name patterns and multiple ip address ranges in a `proxy.conf` file for host deployment.
+```properties
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain,*broker*.otherdomain
+# limit target ip addresses to a specific network or range demonstrating multiple supported formats
+brokerProxyAllowedIPAddresses=10.10.0.0/16,192.168.1.100-120,172.16.2.*,10.1.2.3
+```
+
## Start the proxy
diff --git a/site2/website/versioned_docs/version-2.10.0/administration-proxy.md b/site2/website/versioned_docs/version-2.10.0/administration-proxy.md
index f45185dc45b..202d7d64343 100644
--- a/site2/website/versioned_docs/version-2.10.0/administration-proxy.md
+++ b/site2/website/versioned_docs/version-2.10.0/administration-proxy.md
@@ -7,9 +7,13 @@ original_id: administration-proxy
Pulsar proxy is an optional gateway. Pulsar proxy is used when direct connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
+The Pulsar proxy is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. The requirement of network perimeter security can be achieved with private networks.
+
+If a proxy deployment cannot be protected with network perimeter security, the alternative would be to use [Pulsar's "Proxy SNI routing" feature](concepts-proxy-sni-routing.md) with a properly secured and audited solution. In that case Pulsar proxy component is not used at all.
+
## Configure the proxy
-Before using the proxy, you need to configure it with the brokers addresses in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
+Before using a proxy, you need to configure it with a broker's address in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
> In a production environment service discovery is not recommended.
@@ -22,24 +26,20 @@ Proxy authorization requires access to ZooKeeper, so if you use these broker URL
You can configure the broker URLs in `conf/proxy.conf` as follows.
```properties
-
brokerServiceURL=pulsar://brokers.example.com:6650
brokerWebServiceURL=http://brokers.example.com:8080
functionWorkerWebServiceURL=http://function-workers.example.com:8080
-
```
If you use TLS, configure the broker URLs in the following way:
```properties
-
brokerServiceURLTLS=pulsar+ssl://brokers.example.com:6651
brokerWebServiceURLTLS=https://brokers.example.com:8443
functionWorkerWebServiceURL=https://function-workers.example.com:8443
-
```
-The hostname in the URLs provided should be a DNS entry which points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
+The hostname in the URLs provided should be a DNS entry that points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
The ports to connect to the brokers (6650 and 8080, or in the case of TLS, 6651 and 8443) should be open in the network ACLs.
@@ -50,15 +50,52 @@ Note that if you do not use functions, you do not need to configure `functionWor
Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
```properties
-
metadataStoreUrl=my-zk-0:2181,my-zk-1:2181,my-zk-2:2181
configurationMetadataStoreUrl=my-zk-0:2184,my-zk-remote:2184
-
```
> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
-> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+
+### Restricting target broker addresses to mitigate CVE-2022-24280
+
+The Pulsar Proxy trusts clients to provide valid target broker addresses to connect to.
+Unless the Pulsar Proxy is explicitly configured to limit access, the Pulsar Proxy is vulnerable as described in the security advisory [Apache Pulsar Proxy target broker address isn't validated (CVE-2022-24280)](https://github.com/apache/pulsar/wiki/CVE-2022-24280).
+
+It is necessary to limit proxied broker connections to known broker addresses by specifying `brokerProxyAllowedHostNames` and `brokerProxyAllowedIPAddresses` settings.
+
+When specifying `brokerProxyAllowedHostNames`, it's possible to use a wildcard.
+Please notice that `*` is a wildcard that matches any character in the hostname. It also matches dot `.` characters.
+
+It is recommended to use a pattern that matches only the desired brokers and no other hosts in the local network. Pulsar lookups will use the default host name of the broker by default. This can be overridden with the `advertisedAddress` setting in `broker.conf`.
+
+To increase security, it is also possible to restrict access with the `brokerProxyAllowedIPAddresses` setting. It is not mandatory to configure `brokerProxyAllowedIPAddresses` when `brokerProxyAllowedHostNames` is properly configured so that the pattern matches only the target brokers.
+`brokerProxyAllowedIPAddresses` setting supports a comma separate list of IP address, IP address ranges and IP address networks [(supported format reference)](https://seancfoley.github.io/IPAddress/IPAddress/apidocs/inet/ipaddr/IPAddressString.html).
+
+Example: limiting by host name in a Kubernetes deployment
+```yaml
+ # example of limiting to Kubernetes statefulset hostnames that contain "broker-"
+ PULSAR_PREFIX_brokerProxyAllowedHostNames: '*broker-*.*.*.svc.cluster.local'
+```
+
+Example: limiting by both host name and ip address in a `proxy.conf` file for host deployment.
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain
+# limit target ip addresses to a specific network
+brokerProxyAllowedIPAddresses=10.0.0.0/8
+```
+
+Example: limiting by multiple host name patterns and multiple ip address ranges in a `proxy.conf` file for host deployment.
+```properties
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain,*broker*.otherdomain
+# limit target ip addresses to a specific network or range demonstrating multiple supported formats
+brokerProxyAllowedIPAddresses=10.10.0.0/16,192.168.1.100-120,172.16.2.*,10.1.2.3
+```
+
## Start the proxy
diff --git a/site2/website/versioned_docs/version-2.10.1/administration-proxy.md b/site2/website/versioned_docs/version-2.10.1/administration-proxy.md
index f45185dc45b..202d7d64343 100644
--- a/site2/website/versioned_docs/version-2.10.1/administration-proxy.md
+++ b/site2/website/versioned_docs/version-2.10.1/administration-proxy.md
@@ -7,9 +7,13 @@ original_id: administration-proxy
Pulsar proxy is an optional gateway. Pulsar proxy is used when direct connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
+The Pulsar proxy is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. The requirement of network perimeter security can be achieved with private networks.
+
+If a proxy deployment cannot be protected with network perimeter security, the alternative would be to use [Pulsar's "Proxy SNI routing" feature](concepts-proxy-sni-routing.md) with a properly secured and audited solution. In that case Pulsar proxy component is not used at all.
+
## Configure the proxy
-Before using the proxy, you need to configure it with the brokers addresses in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
+Before using a proxy, you need to configure it with a broker's address in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
> In a production environment service discovery is not recommended.
@@ -22,24 +26,20 @@ Proxy authorization requires access to ZooKeeper, so if you use these broker URL
You can configure the broker URLs in `conf/proxy.conf` as follows.
```properties
-
brokerServiceURL=pulsar://brokers.example.com:6650
brokerWebServiceURL=http://brokers.example.com:8080
functionWorkerWebServiceURL=http://function-workers.example.com:8080
-
```
If you use TLS, configure the broker URLs in the following way:
```properties
-
brokerServiceURLTLS=pulsar+ssl://brokers.example.com:6651
brokerWebServiceURLTLS=https://brokers.example.com:8443
functionWorkerWebServiceURL=https://function-workers.example.com:8443
-
```
-The hostname in the URLs provided should be a DNS entry which points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
+The hostname in the URLs provided should be a DNS entry that points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
The ports to connect to the brokers (6650 and 8080, or in the case of TLS, 6651 and 8443) should be open in the network ACLs.
@@ -50,15 +50,52 @@ Note that if you do not use functions, you do not need to configure `functionWor
Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
```properties
-
metadataStoreUrl=my-zk-0:2181,my-zk-1:2181,my-zk-2:2181
configurationMetadataStoreUrl=my-zk-0:2184,my-zk-remote:2184
-
```
> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
-> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+
+### Restricting target broker addresses to mitigate CVE-2022-24280
+
+The Pulsar Proxy trusts clients to provide valid target broker addresses to connect to.
+Unless the Pulsar Proxy is explicitly configured to limit access, the Pulsar Proxy is vulnerable as described in the security advisory [Apache Pulsar Proxy target broker address isn't validated (CVE-2022-24280)](https://github.com/apache/pulsar/wiki/CVE-2022-24280).
+
+It is necessary to limit proxied broker connections to known broker addresses by specifying `brokerProxyAllowedHostNames` and `brokerProxyAllowedIPAddresses` settings.
+
+When specifying `brokerProxyAllowedHostNames`, it's possible to use a wildcard.
+Please notice that `*` is a wildcard that matches any character in the hostname. It also matches dot `.` characters.
+
+It is recommended to use a pattern that matches only the desired brokers and no other hosts in the local network. Pulsar lookups will use the default host name of the broker by default. This can be overridden with the `advertisedAddress` setting in `broker.conf`.
+
+To increase security, it is also possible to restrict access with the `brokerProxyAllowedIPAddresses` setting. It is not mandatory to configure `brokerProxyAllowedIPAddresses` when `brokerProxyAllowedHostNames` is properly configured so that the pattern matches only the target brokers.
+`brokerProxyAllowedIPAddresses` setting supports a comma separate list of IP address, IP address ranges and IP address networks [(supported format reference)](https://seancfoley.github.io/IPAddress/IPAddress/apidocs/inet/ipaddr/IPAddressString.html).
+
+Example: limiting by host name in a Kubernetes deployment
+```yaml
+ # example of limiting to Kubernetes statefulset hostnames that contain "broker-"
+ PULSAR_PREFIX_brokerProxyAllowedHostNames: '*broker-*.*.*.svc.cluster.local'
+```
+
+Example: limiting by both host name and ip address in a `proxy.conf` file for host deployment.
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain
+# limit target ip addresses to a specific network
+brokerProxyAllowedIPAddresses=10.0.0.0/8
+```
+
+Example: limiting by multiple host name patterns and multiple ip address ranges in a `proxy.conf` file for host deployment.
+```properties
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain,*broker*.otherdomain
+# limit target ip addresses to a specific network or range demonstrating multiple supported formats
+brokerProxyAllowedIPAddresses=10.10.0.0/16,192.168.1.100-120,172.16.2.*,10.1.2.3
+```
+
## Start the proxy
diff --git a/site2/website/versioned_docs/version-2.8.0/administration-proxy.md b/site2/website/versioned_docs/version-2.8.0/administration-proxy.md
index c046ed34d46..577eff7db02 100644
--- a/site2/website/versioned_docs/version-2.8.0/administration-proxy.md
+++ b/site2/website/versioned_docs/version-2.8.0/administration-proxy.md
@@ -5,26 +5,17 @@ sidebar_label: "Pulsar proxy"
original_id: administration-proxy
---
-Pulsar proxy is an optional gateway. Pulsar proxy is used when direction connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
+Pulsar proxy is an optional gateway. Pulsar proxy is used when direct connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
-## Configure the proxy
-
-Before using the proxy, you need to configure it with the brokers addresses in the cluster. You can configure the proxy to connect directly to service discovery, or specify a broker URL in the configuration.
-
-### Use service discovery
+The Pulsar proxy is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. The requirement of network perimeter security can be achieved with private networks.
-Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+If a proxy deployment cannot be protected with network perimeter security, the alternative would be to use [Pulsar's "Proxy SNI routing" feature](concepts-proxy-sni-routing.md) with a properly secured and audited solution. In that case Pulsar proxy component is not used at all.
-```properties
-
-zookeeperServers=zk-0,zk-1,zk-2
-configurationStoreServers=zk-0:2184,zk-remote:2184
-
-```
+## Configure the proxy
-> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+Before using a proxy, you need to configure it with a broker's address in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
-> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+> In a production environment service discovery is not recommended.
### Use broker URLs
@@ -35,29 +26,77 @@ Proxy authorization requires access to ZooKeeper, so if you use these broker URL
You can configure the broker URLs in `conf/proxy.conf` as follows.
```properties
-
brokerServiceURL=pulsar://brokers.example.com:6650
brokerWebServiceURL=http://brokers.example.com:8080
functionWorkerWebServiceURL=http://function-workers.example.com:8080
-
```
If you use TLS, configure the broker URLs in the following way:
```properties
-
brokerServiceURLTLS=pulsar+ssl://brokers.example.com:6651
brokerWebServiceURLTLS=https://brokers.example.com:8443
functionWorkerWebServiceURL=https://function-workers.example.com:8443
-
```
-The hostname in the URLs provided should be a DNS entry which points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
+The hostname in the URLs provided should be a DNS entry that points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
The ports to connect to the brokers (6650 and 8080, or in the case of TLS, 6651 and 8443) should be open in the network ACLs.
Note that if you do not use functions, you do not need to configure `functionWorkerWebServiceURL`.
+### Use service discovery
+
+Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+
+```properties
+metadataStoreUrl=my-zk-0:2181,my-zk-1:2181,my-zk-2:2181
+configurationMetadataStoreUrl=my-zk-0:2184,my-zk-remote:2184
+```
+
+> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+
+> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+
+### Restricting target broker addresses to mitigate CVE-2022-24280
+
+The Pulsar Proxy trusts clients to provide valid target broker addresses to connect to.
+Unless the Pulsar Proxy is explicitly configured to limit access, the Pulsar Proxy is vulnerable as described in the security advisory [Apache Pulsar Proxy target broker address isn't validated (CVE-2022-24280)](https://github.com/apache/pulsar/wiki/CVE-2022-24280).
+
+It is necessary to limit proxied broker connections to known broker addresses by specifying `brokerProxyAllowedHostNames` and `brokerProxyAllowedIPAddresses` settings.
+
+When specifying `brokerProxyAllowedHostNames`, it's possible to use a wildcard.
+Please notice that `*` is a wildcard that matches any character in the hostname. It also matches dot `.` characters.
+
+It is recommended to use a pattern that matches only the desired brokers and no other hosts in the local network. Pulsar lookups will use the default host name of the broker by default. This can be overridden with the `advertisedAddress` setting in `broker.conf`.
+
+To increase security, it is also possible to restrict access with the `brokerProxyAllowedIPAddresses` setting. It is not mandatory to configure `brokerProxyAllowedIPAddresses` when `brokerProxyAllowedHostNames` is properly configured so that the pattern matches only the target brokers.
+`brokerProxyAllowedIPAddresses` setting supports a comma separate list of IP address, IP address ranges and IP address networks [(supported format reference)](https://seancfoley.github.io/IPAddress/IPAddress/apidocs/inet/ipaddr/IPAddressString.html).
+
+Example: limiting by host name in a Kubernetes deployment
+```yaml
+ # example of limiting to Kubernetes statefulset hostnames that contain "broker-"
+ PULSAR_PREFIX_brokerProxyAllowedHostNames: '*broker-*.*.*.svc.cluster.local'
+```
+
+Example: limiting by both host name and ip address in a `proxy.conf` file for host deployment.
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain
+# limit target ip addresses to a specific network
+brokerProxyAllowedIPAddresses=10.0.0.0/8
+```
+
+Example: limiting by multiple host name patterns and multiple ip address ranges in a `proxy.conf` file for host deployment.
+```properties
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain,*broker*.otherdomain
+# limit target ip addresses to a specific network or range demonstrating multiple supported formats
+brokerProxyAllowedIPAddresses=10.10.0.0/16,192.168.1.100-120,172.16.2.*,10.1.2.3
+```
+
+
## Start the proxy
To start the proxy:
diff --git a/site2/website/versioned_docs/version-2.8.1/administration-proxy.md b/site2/website/versioned_docs/version-2.8.1/administration-proxy.md
index c046ed34d46..577eff7db02 100644
--- a/site2/website/versioned_docs/version-2.8.1/administration-proxy.md
+++ b/site2/website/versioned_docs/version-2.8.1/administration-proxy.md
@@ -5,26 +5,17 @@ sidebar_label: "Pulsar proxy"
original_id: administration-proxy
---
-Pulsar proxy is an optional gateway. Pulsar proxy is used when direction connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
+Pulsar proxy is an optional gateway. Pulsar proxy is used when direct connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
-## Configure the proxy
-
-Before using the proxy, you need to configure it with the brokers addresses in the cluster. You can configure the proxy to connect directly to service discovery, or specify a broker URL in the configuration.
-
-### Use service discovery
+The Pulsar proxy is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. The requirement of network perimeter security can be achieved with private networks.
-Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+If a proxy deployment cannot be protected with network perimeter security, the alternative would be to use [Pulsar's "Proxy SNI routing" feature](concepts-proxy-sni-routing.md) with a properly secured and audited solution. In that case Pulsar proxy component is not used at all.
-```properties
-
-zookeeperServers=zk-0,zk-1,zk-2
-configurationStoreServers=zk-0:2184,zk-remote:2184
-
-```
+## Configure the proxy
-> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+Before using a proxy, you need to configure it with a broker's address in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
-> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+> In a production environment service discovery is not recommended.
### Use broker URLs
@@ -35,29 +26,77 @@ Proxy authorization requires access to ZooKeeper, so if you use these broker URL
You can configure the broker URLs in `conf/proxy.conf` as follows.
```properties
-
brokerServiceURL=pulsar://brokers.example.com:6650
brokerWebServiceURL=http://brokers.example.com:8080
functionWorkerWebServiceURL=http://function-workers.example.com:8080
-
```
If you use TLS, configure the broker URLs in the following way:
```properties
-
brokerServiceURLTLS=pulsar+ssl://brokers.example.com:6651
brokerWebServiceURLTLS=https://brokers.example.com:8443
functionWorkerWebServiceURL=https://function-workers.example.com:8443
-
```
-The hostname in the URLs provided should be a DNS entry which points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
+The hostname in the URLs provided should be a DNS entry that points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
The ports to connect to the brokers (6650 and 8080, or in the case of TLS, 6651 and 8443) should be open in the network ACLs.
Note that if you do not use functions, you do not need to configure `functionWorkerWebServiceURL`.
+### Use service discovery
+
+Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+
+```properties
+metadataStoreUrl=my-zk-0:2181,my-zk-1:2181,my-zk-2:2181
+configurationMetadataStoreUrl=my-zk-0:2184,my-zk-remote:2184
+```
+
+> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+
+> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+
+### Restricting target broker addresses to mitigate CVE-2022-24280
+
+The Pulsar Proxy trusts clients to provide valid target broker addresses to connect to.
+Unless the Pulsar Proxy is explicitly configured to limit access, the Pulsar Proxy is vulnerable as described in the security advisory [Apache Pulsar Proxy target broker address isn't validated (CVE-2022-24280)](https://github.com/apache/pulsar/wiki/CVE-2022-24280).
+
+It is necessary to limit proxied broker connections to known broker addresses by specifying `brokerProxyAllowedHostNames` and `brokerProxyAllowedIPAddresses` settings.
+
+When specifying `brokerProxyAllowedHostNames`, it's possible to use a wildcard.
+Please notice that `*` is a wildcard that matches any character in the hostname. It also matches dot `.` characters.
+
+It is recommended to use a pattern that matches only the desired brokers and no other hosts in the local network. Pulsar lookups will use the default host name of the broker by default. This can be overridden with the `advertisedAddress` setting in `broker.conf`.
+
+To increase security, it is also possible to restrict access with the `brokerProxyAllowedIPAddresses` setting. It is not mandatory to configure `brokerProxyAllowedIPAddresses` when `brokerProxyAllowedHostNames` is properly configured so that the pattern matches only the target brokers.
+`brokerProxyAllowedIPAddresses` setting supports a comma separate list of IP address, IP address ranges and IP address networks [(supported format reference)](https://seancfoley.github.io/IPAddress/IPAddress/apidocs/inet/ipaddr/IPAddressString.html).
+
+Example: limiting by host name in a Kubernetes deployment
+```yaml
+ # example of limiting to Kubernetes statefulset hostnames that contain "broker-"
+ PULSAR_PREFIX_brokerProxyAllowedHostNames: '*broker-*.*.*.svc.cluster.local'
+```
+
+Example: limiting by both host name and ip address in a `proxy.conf` file for host deployment.
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain
+# limit target ip addresses to a specific network
+brokerProxyAllowedIPAddresses=10.0.0.0/8
+```
+
+Example: limiting by multiple host name patterns and multiple ip address ranges in a `proxy.conf` file for host deployment.
+```properties
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain,*broker*.otherdomain
+# limit target ip addresses to a specific network or range demonstrating multiple supported formats
+brokerProxyAllowedIPAddresses=10.10.0.0/16,192.168.1.100-120,172.16.2.*,10.1.2.3
+```
+
+
## Start the proxy
To start the proxy:
diff --git a/site2/website/versioned_docs/version-2.8.2/administration-proxy.md b/site2/website/versioned_docs/version-2.8.2/administration-proxy.md
index c046ed34d46..577eff7db02 100644
--- a/site2/website/versioned_docs/version-2.8.2/administration-proxy.md
+++ b/site2/website/versioned_docs/version-2.8.2/administration-proxy.md
@@ -5,26 +5,17 @@ sidebar_label: "Pulsar proxy"
original_id: administration-proxy
---
-Pulsar proxy is an optional gateway. Pulsar proxy is used when direction connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
+Pulsar proxy is an optional gateway. Pulsar proxy is used when direct connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
-## Configure the proxy
-
-Before using the proxy, you need to configure it with the brokers addresses in the cluster. You can configure the proxy to connect directly to service discovery, or specify a broker URL in the configuration.
-
-### Use service discovery
+The Pulsar proxy is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. The requirement of network perimeter security can be achieved with private networks.
-Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+If a proxy deployment cannot be protected with network perimeter security, the alternative would be to use [Pulsar's "Proxy SNI routing" feature](concepts-proxy-sni-routing.md) with a properly secured and audited solution. In that case Pulsar proxy component is not used at all.
-```properties
-
-zookeeperServers=zk-0,zk-1,zk-2
-configurationStoreServers=zk-0:2184,zk-remote:2184
-
-```
+## Configure the proxy
-> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+Before using a proxy, you need to configure it with a broker's address in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
-> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+> In a production environment service discovery is not recommended.
### Use broker URLs
@@ -35,29 +26,77 @@ Proxy authorization requires access to ZooKeeper, so if you use these broker URL
You can configure the broker URLs in `conf/proxy.conf` as follows.
```properties
-
brokerServiceURL=pulsar://brokers.example.com:6650
brokerWebServiceURL=http://brokers.example.com:8080
functionWorkerWebServiceURL=http://function-workers.example.com:8080
-
```
If you use TLS, configure the broker URLs in the following way:
```properties
-
brokerServiceURLTLS=pulsar+ssl://brokers.example.com:6651
brokerWebServiceURLTLS=https://brokers.example.com:8443
functionWorkerWebServiceURL=https://function-workers.example.com:8443
-
```
-The hostname in the URLs provided should be a DNS entry which points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
+The hostname in the URLs provided should be a DNS entry that points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
The ports to connect to the brokers (6650 and 8080, or in the case of TLS, 6651 and 8443) should be open in the network ACLs.
Note that if you do not use functions, you do not need to configure `functionWorkerWebServiceURL`.
+### Use service discovery
+
+Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+
+```properties
+metadataStoreUrl=my-zk-0:2181,my-zk-1:2181,my-zk-2:2181
+configurationMetadataStoreUrl=my-zk-0:2184,my-zk-remote:2184
+```
+
+> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+
+> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+
+### Restricting target broker addresses to mitigate CVE-2022-24280
+
+The Pulsar Proxy trusts clients to provide valid target broker addresses to connect to.
+Unless the Pulsar Proxy is explicitly configured to limit access, the Pulsar Proxy is vulnerable as described in the security advisory [Apache Pulsar Proxy target broker address isn't validated (CVE-2022-24280)](https://github.com/apache/pulsar/wiki/CVE-2022-24280).
+
+It is necessary to limit proxied broker connections to known broker addresses by specifying `brokerProxyAllowedHostNames` and `brokerProxyAllowedIPAddresses` settings.
+
+When specifying `brokerProxyAllowedHostNames`, it's possible to use a wildcard.
+Please notice that `*` is a wildcard that matches any character in the hostname. It also matches dot `.` characters.
+
+It is recommended to use a pattern that matches only the desired brokers and no other hosts in the local network. Pulsar lookups will use the default host name of the broker by default. This can be overridden with the `advertisedAddress` setting in `broker.conf`.
+
+To increase security, it is also possible to restrict access with the `brokerProxyAllowedIPAddresses` setting. It is not mandatory to configure `brokerProxyAllowedIPAddresses` when `brokerProxyAllowedHostNames` is properly configured so that the pattern matches only the target brokers.
+`brokerProxyAllowedIPAddresses` setting supports a comma separate list of IP address, IP address ranges and IP address networks [(supported format reference)](https://seancfoley.github.io/IPAddress/IPAddress/apidocs/inet/ipaddr/IPAddressString.html).
+
+Example: limiting by host name in a Kubernetes deployment
+```yaml
+ # example of limiting to Kubernetes statefulset hostnames that contain "broker-"
+ PULSAR_PREFIX_brokerProxyAllowedHostNames: '*broker-*.*.*.svc.cluster.local'
+```
+
+Example: limiting by both host name and ip address in a `proxy.conf` file for host deployment.
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain
+# limit target ip addresses to a specific network
+brokerProxyAllowedIPAddresses=10.0.0.0/8
+```
+
+Example: limiting by multiple host name patterns and multiple ip address ranges in a `proxy.conf` file for host deployment.
+```properties
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain,*broker*.otherdomain
+# limit target ip addresses to a specific network or range demonstrating multiple supported formats
+brokerProxyAllowedIPAddresses=10.10.0.0/16,192.168.1.100-120,172.16.2.*,10.1.2.3
+```
+
+
## Start the proxy
To start the proxy:
diff --git a/site2/website/versioned_docs/version-2.9.0/administration-proxy.md b/site2/website/versioned_docs/version-2.9.0/administration-proxy.md
index 1657e4f88ce..577eff7db02 100644
--- a/site2/website/versioned_docs/version-2.9.0/administration-proxy.md
+++ b/site2/website/versioned_docs/version-2.9.0/administration-proxy.md
@@ -7,24 +7,15 @@ original_id: administration-proxy
Pulsar proxy is an optional gateway. Pulsar proxy is used when direct connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
-## Configure the proxy
-
-Before using the proxy, you need to configure it with the brokers addresses in the cluster. You can configure the proxy to connect directly to service discovery, or specify a broker URL in the configuration.
-
-### Use service discovery
+The Pulsar proxy is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. The requirement of network perimeter security can be achieved with private networks.
-Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+If a proxy deployment cannot be protected with network perimeter security, the alternative would be to use [Pulsar's "Proxy SNI routing" feature](concepts-proxy-sni-routing.md) with a properly secured and audited solution. In that case Pulsar proxy component is not used at all.
-```properties
-
-zookeeperServers=zk-0,zk-1,zk-2
-configurationStoreServers=zk-0:2184,zk-remote:2184
-
-```
+## Configure the proxy
-> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+Before using a proxy, you need to configure it with a broker's address in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
-> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+> In a production environment service discovery is not recommended.
### Use broker URLs
@@ -35,29 +26,77 @@ Proxy authorization requires access to ZooKeeper, so if you use these broker URL
You can configure the broker URLs in `conf/proxy.conf` as follows.
```properties
-
brokerServiceURL=pulsar://brokers.example.com:6650
brokerWebServiceURL=http://brokers.example.com:8080
functionWorkerWebServiceURL=http://function-workers.example.com:8080
-
```
If you use TLS, configure the broker URLs in the following way:
```properties
-
brokerServiceURLTLS=pulsar+ssl://brokers.example.com:6651
brokerWebServiceURLTLS=https://brokers.example.com:8443
functionWorkerWebServiceURL=https://function-workers.example.com:8443
-
```
-The hostname in the URLs provided should be a DNS entry which points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
+The hostname in the URLs provided should be a DNS entry that points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
The ports to connect to the brokers (6650 and 8080, or in the case of TLS, 6651 and 8443) should be open in the network ACLs.
Note that if you do not use functions, you do not need to configure `functionWorkerWebServiceURL`.
+### Use service discovery
+
+Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+
+```properties
+metadataStoreUrl=my-zk-0:2181,my-zk-1:2181,my-zk-2:2181
+configurationMetadataStoreUrl=my-zk-0:2184,my-zk-remote:2184
+```
+
+> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+
+> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+
+### Restricting target broker addresses to mitigate CVE-2022-24280
+
+The Pulsar Proxy trusts clients to provide valid target broker addresses to connect to.
+Unless the Pulsar Proxy is explicitly configured to limit access, the Pulsar Proxy is vulnerable as described in the security advisory [Apache Pulsar Proxy target broker address isn't validated (CVE-2022-24280)](https://github.com/apache/pulsar/wiki/CVE-2022-24280).
+
+It is necessary to limit proxied broker connections to known broker addresses by specifying `brokerProxyAllowedHostNames` and `brokerProxyAllowedIPAddresses` settings.
+
+When specifying `brokerProxyAllowedHostNames`, it's possible to use a wildcard.
+Please notice that `*` is a wildcard that matches any character in the hostname. It also matches dot `.` characters.
+
+It is recommended to use a pattern that matches only the desired brokers and no other hosts in the local network. Pulsar lookups will use the default host name of the broker by default. This can be overridden with the `advertisedAddress` setting in `broker.conf`.
+
+To increase security, it is also possible to restrict access with the `brokerProxyAllowedIPAddresses` setting. It is not mandatory to configure `brokerProxyAllowedIPAddresses` when `brokerProxyAllowedHostNames` is properly configured so that the pattern matches only the target brokers.
+`brokerProxyAllowedIPAddresses` setting supports a comma separate list of IP address, IP address ranges and IP address networks [(supported format reference)](https://seancfoley.github.io/IPAddress/IPAddress/apidocs/inet/ipaddr/IPAddressString.html).
+
+Example: limiting by host name in a Kubernetes deployment
+```yaml
+ # example of limiting to Kubernetes statefulset hostnames that contain "broker-"
+ PULSAR_PREFIX_brokerProxyAllowedHostNames: '*broker-*.*.*.svc.cluster.local'
+```
+
+Example: limiting by both host name and ip address in a `proxy.conf` file for host deployment.
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain
+# limit target ip addresses to a specific network
+brokerProxyAllowedIPAddresses=10.0.0.0/8
+```
+
+Example: limiting by multiple host name patterns and multiple ip address ranges in a `proxy.conf` file for host deployment.
+```properties
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain,*broker*.otherdomain
+# limit target ip addresses to a specific network or range demonstrating multiple supported formats
+brokerProxyAllowedIPAddresses=10.10.0.0/16,192.168.1.100-120,172.16.2.*,10.1.2.3
+```
+
+
## Start the proxy
To start the proxy:
diff --git a/site2/website/versioned_docs/version-2.9.1/administration-proxy.md b/site2/website/versioned_docs/version-2.9.1/administration-proxy.md
index 1657e4f88ce..577eff7db02 100644
--- a/site2/website/versioned_docs/version-2.9.1/administration-proxy.md
+++ b/site2/website/versioned_docs/version-2.9.1/administration-proxy.md
@@ -7,24 +7,15 @@ original_id: administration-proxy
Pulsar proxy is an optional gateway. Pulsar proxy is used when direct connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
-## Configure the proxy
-
-Before using the proxy, you need to configure it with the brokers addresses in the cluster. You can configure the proxy to connect directly to service discovery, or specify a broker URL in the configuration.
-
-### Use service discovery
+The Pulsar proxy is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. The requirement of network perimeter security can be achieved with private networks.
-Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+If a proxy deployment cannot be protected with network perimeter security, the alternative would be to use [Pulsar's "Proxy SNI routing" feature](concepts-proxy-sni-routing.md) with a properly secured and audited solution. In that case Pulsar proxy component is not used at all.
-```properties
-
-zookeeperServers=zk-0,zk-1,zk-2
-configurationStoreServers=zk-0:2184,zk-remote:2184
-
-```
+## Configure the proxy
-> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+Before using a proxy, you need to configure it with a broker's address in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
-> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+> In a production environment service discovery is not recommended.
### Use broker URLs
@@ -35,29 +26,77 @@ Proxy authorization requires access to ZooKeeper, so if you use these broker URL
You can configure the broker URLs in `conf/proxy.conf` as follows.
```properties
-
brokerServiceURL=pulsar://brokers.example.com:6650
brokerWebServiceURL=http://brokers.example.com:8080
functionWorkerWebServiceURL=http://function-workers.example.com:8080
-
```
If you use TLS, configure the broker URLs in the following way:
```properties
-
brokerServiceURLTLS=pulsar+ssl://brokers.example.com:6651
brokerWebServiceURLTLS=https://brokers.example.com:8443
functionWorkerWebServiceURL=https://function-workers.example.com:8443
-
```
-The hostname in the URLs provided should be a DNS entry which points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
+The hostname in the URLs provided should be a DNS entry that points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
The ports to connect to the brokers (6650 and 8080, or in the case of TLS, 6651 and 8443) should be open in the network ACLs.
Note that if you do not use functions, you do not need to configure `functionWorkerWebServiceURL`.
+### Use service discovery
+
+Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+
+```properties
+metadataStoreUrl=my-zk-0:2181,my-zk-1:2181,my-zk-2:2181
+configurationMetadataStoreUrl=my-zk-0:2184,my-zk-remote:2184
+```
+
+> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+
+> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+
+### Restricting target broker addresses to mitigate CVE-2022-24280
+
+The Pulsar Proxy trusts clients to provide valid target broker addresses to connect to.
+Unless the Pulsar Proxy is explicitly configured to limit access, the Pulsar Proxy is vulnerable as described in the security advisory [Apache Pulsar Proxy target broker address isn't validated (CVE-2022-24280)](https://github.com/apache/pulsar/wiki/CVE-2022-24280).
+
+It is necessary to limit proxied broker connections to known broker addresses by specifying `brokerProxyAllowedHostNames` and `brokerProxyAllowedIPAddresses` settings.
+
+When specifying `brokerProxyAllowedHostNames`, it's possible to use a wildcard.
+Please notice that `*` is a wildcard that matches any character in the hostname. It also matches dot `.` characters.
+
+It is recommended to use a pattern that matches only the desired brokers and no other hosts in the local network. Pulsar lookups will use the default host name of the broker by default. This can be overridden with the `advertisedAddress` setting in `broker.conf`.
+
+To increase security, it is also possible to restrict access with the `brokerProxyAllowedIPAddresses` setting. It is not mandatory to configure `brokerProxyAllowedIPAddresses` when `brokerProxyAllowedHostNames` is properly configured so that the pattern matches only the target brokers.
+`brokerProxyAllowedIPAddresses` setting supports a comma separate list of IP address, IP address ranges and IP address networks [(supported format reference)](https://seancfoley.github.io/IPAddress/IPAddress/apidocs/inet/ipaddr/IPAddressString.html).
+
+Example: limiting by host name in a Kubernetes deployment
+```yaml
+ # example of limiting to Kubernetes statefulset hostnames that contain "broker-"
+ PULSAR_PREFIX_brokerProxyAllowedHostNames: '*broker-*.*.*.svc.cluster.local'
+```
+
+Example: limiting by both host name and ip address in a `proxy.conf` file for host deployment.
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain
+# limit target ip addresses to a specific network
+brokerProxyAllowedIPAddresses=10.0.0.0/8
+```
+
+Example: limiting by multiple host name patterns and multiple ip address ranges in a `proxy.conf` file for host deployment.
+```properties
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain,*broker*.otherdomain
+# limit target ip addresses to a specific network or range demonstrating multiple supported formats
+brokerProxyAllowedIPAddresses=10.10.0.0/16,192.168.1.100-120,172.16.2.*,10.1.2.3
+```
+
+
## Start the proxy
To start the proxy:
diff --git a/site2/website/versioned_docs/version-2.9.3/administration-proxy.md b/site2/website/versioned_docs/version-2.9.3/administration-proxy.md
index 1657e4f88ce..577eff7db02 100644
--- a/site2/website/versioned_docs/version-2.9.3/administration-proxy.md
+++ b/site2/website/versioned_docs/version-2.9.3/administration-proxy.md
@@ -7,24 +7,15 @@ original_id: administration-proxy
Pulsar proxy is an optional gateway. Pulsar proxy is used when direct connections between clients and Pulsar brokers are either infeasible or undesirable. For example, when you run Pulsar in a cloud environment or on [Kubernetes](https://kubernetes.io) or an analogous platform, you can run Pulsar proxy.
-## Configure the proxy
-
-Before using the proxy, you need to configure it with the brokers addresses in the cluster. You can configure the proxy to connect directly to service discovery, or specify a broker URL in the configuration.
-
-### Use service discovery
+The Pulsar proxy is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. The requirement of network perimeter security can be achieved with private networks.
-Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+If a proxy deployment cannot be protected with network perimeter security, the alternative would be to use [Pulsar's "Proxy SNI routing" feature](concepts-proxy-sni-routing.md) with a properly secured and audited solution. In that case Pulsar proxy component is not used at all.
-```properties
-
-zookeeperServers=zk-0,zk-1,zk-2
-configurationStoreServers=zk-0:2184,zk-remote:2184
-
-```
+## Configure the proxy
-> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+Before using a proxy, you need to configure it with a broker's address in the cluster. You can configure the broker URL in the proxy configuration, or the proxy to connect directly using service discovery.
-> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+> In a production environment service discovery is not recommended.
### Use broker URLs
@@ -35,29 +26,77 @@ Proxy authorization requires access to ZooKeeper, so if you use these broker URL
You can configure the broker URLs in `conf/proxy.conf` as follows.
```properties
-
brokerServiceURL=pulsar://brokers.example.com:6650
brokerWebServiceURL=http://brokers.example.com:8080
functionWorkerWebServiceURL=http://function-workers.example.com:8080
-
```
If you use TLS, configure the broker URLs in the following way:
```properties
-
brokerServiceURLTLS=pulsar+ssl://brokers.example.com:6651
brokerWebServiceURLTLS=https://brokers.example.com:8443
functionWorkerWebServiceURL=https://function-workers.example.com:8443
-
```
-The hostname in the URLs provided should be a DNS entry which points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
+The hostname in the URLs provided should be a DNS entry that points to multiple brokers or a virtual IP address, which is backed by multiple broker IP addresses, so that the proxy does not lose connectivity to Pulsar cluster if a single broker becomes unavailable.
The ports to connect to the brokers (6650 and 8080, or in the case of TLS, 6651 and 8443) should be open in the network ACLs.
Note that if you do not use functions, you do not need to configure `functionWorkerWebServiceURL`.
+### Use service discovery
+
+Pulsar uses [ZooKeeper](https://zookeeper.apache.org) for service discovery. To connect the proxy to ZooKeeper, specify the following in `conf/proxy.conf`.
+
+```properties
+metadataStoreUrl=my-zk-0:2181,my-zk-1:2181,my-zk-2:2181
+configurationMetadataStoreUrl=my-zk-0:2184,my-zk-remote:2184
+```
+
+> To use service discovery, you need to open the network ACLs, so the proxy can connects to the ZooKeeper nodes through the ZooKeeper client port (port `2181`) and the configuration store client port (port `2184`).
+
+> However, it is not secure to use service discovery. Because if the network ACL is open, when someone compromises a proxy, they have full access to ZooKeeper.
+
+### Restricting target broker addresses to mitigate CVE-2022-24280
+
+The Pulsar Proxy trusts clients to provide valid target broker addresses to connect to.
+Unless the Pulsar Proxy is explicitly configured to limit access, the Pulsar Proxy is vulnerable as described in the security advisory [Apache Pulsar Proxy target broker address isn't validated (CVE-2022-24280)](https://github.com/apache/pulsar/wiki/CVE-2022-24280).
+
+It is necessary to limit proxied broker connections to known broker addresses by specifying `brokerProxyAllowedHostNames` and `brokerProxyAllowedIPAddresses` settings.
+
+When specifying `brokerProxyAllowedHostNames`, it's possible to use a wildcard.
+Please notice that `*` is a wildcard that matches any character in the hostname. It also matches dot `.` characters.
+
+It is recommended to use a pattern that matches only the desired brokers and no other hosts in the local network. Pulsar lookups will use the default host name of the broker by default. This can be overridden with the `advertisedAddress` setting in `broker.conf`.
+
+To increase security, it is also possible to restrict access with the `brokerProxyAllowedIPAddresses` setting. It is not mandatory to configure `brokerProxyAllowedIPAddresses` when `brokerProxyAllowedHostNames` is properly configured so that the pattern matches only the target brokers.
+`brokerProxyAllowedIPAddresses` setting supports a comma separate list of IP address, IP address ranges and IP address networks [(supported format reference)](https://seancfoley.github.io/IPAddress/IPAddress/apidocs/inet/ipaddr/IPAddressString.html).
+
+Example: limiting by host name in a Kubernetes deployment
+```yaml
+ # example of limiting to Kubernetes statefulset hostnames that contain "broker-"
+ PULSAR_PREFIX_brokerProxyAllowedHostNames: '*broker-*.*.*.svc.cluster.local'
+```
+
+Example: limiting by both host name and ip address in a `proxy.conf` file for host deployment.
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain
+# limit target ip addresses to a specific network
+brokerProxyAllowedIPAddresses=10.0.0.0/8
+```
+
+Example: limiting by multiple host name patterns and multiple ip address ranges in a `proxy.conf` file for host deployment.
+```properties
+```properties
+# require "broker" in host name
+brokerProxyAllowedHostNames=*broker*.localdomain,*broker*.otherdomain
+# limit target ip addresses to a specific network or range demonstrating multiple supported formats
+brokerProxyAllowedIPAddresses=10.10.0.0/16,192.168.1.100-120,172.16.2.*,10.1.2.3
+```
+
+
## Start the proxy
To start the proxy: