This is an automated email from the ASF dual-hosted git repository.
urfree pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 15b6532b0da Docs sync done from apache/pulsar(#b03ee23)
15b6532b0da is described below
commit 15b6532b0da9bf2e0d5425138910da488babccc1
Author: Pulsar Site Updater <[email protected]>
AuthorDate: Fri Sep 23 18:02:34 2022 +0000
Docs sync done from apache/pulsar(#b03ee23)
---
site2/website-next/docs/administration-proxy.md | 45 +++++++++++-
.../docs/sql-deployment-configurations.md | 78 +++++++-------------
site2/website-next/docs/sql-getting-started.md | 85 ++++------------------
site2/website-next/docs/sql-overview.md | 8 +-
site2/website-next/docs/sql-rest-api.md | 45 ++++++++----
.../administration-proxy.md | 55 +++++++++++---
.../administration-proxy.md | 55 +++++++++++---
.../version-2.10.x/administration-proxy.md | 55 +++++++++++---
.../version-2.7.5/administration-proxy.md | 79 +++++++++++++++-----
.../administration-proxy.md | 79 +++++++++++++++-----
.../version-2.8.x/administration-proxy.md | 79 +++++++++++++++-----
.../administration-proxy.md | 77 +++++++++++++++-----
.../administration-proxy.md | 77 +++++++++++++++-----
.../version-2.9.x/administration-proxy.md | 77 +++++++++++++++-----
14 files changed, 610 insertions(+), 284 deletions(-)
diff --git a/site2/website-next/docs/administration-proxy.md
b/site2/website-next/docs/administration-proxy.md
index 9f0915d7cdd..62f9612a5bd 100644
--- a/site2/website-next/docs/administration-proxy.md
+++ b/site2/website-next/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 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.
@@ -51,7 +55,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-next/docs/sql-deployment-configurations.md
b/site2/website-next/docs/sql-deployment-configurations.md
index 7cc8e024dfd..8c1362e5637 100644
--- a/site2/website-next/docs/sql-deployment-configurations.md
+++ b/site2/website-next/docs/sql-deployment-configurations.md
@@ -4,10 +4,11 @@ title: Pulsar SQL configuration and deployment
sidebar_label: "Configuration and deployment"
---
-You can configure the Presto Pulsar connector and deploy a cluster with the
following instruction.
+You can configure the Pulsar Trino plugin and deploy a cluster with the
following instruction.
-## Configure Presto Pulsar Connector
-You can configure Presto Pulsar Connector in the
`${project.root}/conf/presto/catalog/pulsar.properties` properties file. The
configuration for the connector and the default values are as follows.
+## Configure Pulsar Trino plugin
+
+You can configure the Pulsar Trino plugin in the
`${project.root}/trino/conf/catalog/pulsar.properties` properties file. The
configuration for the connector and the default values are as follows.
```properties
# name of the connector to be displayed in the catalog
@@ -114,16 +115,17 @@
pulsar.nar-extraction-directory=System.getProperty("java.io.tmpdir")
By default, the authentication and authorization between Pulsar and Pulsar SQL
are disabled.
-To enable it, set the following configurations in the
`${project.root}/conf/presto/catalog/pulsar.properties` properties file:
+To enable it, set the following configurations in the
`${project.root}/trino/conf/catalog/pulsar.properties` properties file:
```properties
pulsar.authorization-enabled=true
pulsar.broker-binary-service-url=pulsar://localhost:6650
```
-### Connect Presto to Pulsar with multiple hosts
+### Connect Trino to Pulsar with multiple hosts
+
+You can connect Trino to a Pulsar cluster with multiple hosts.
-You can connect Presto to a Pulsar cluster with multiple hosts.
* To configure multiple hosts for brokers, add multiple URLs to
`pulsar.web-service-url`.
* To configure multiple hosts for ZooKeeper, add multiple URIs to
`pulsar.zookeeper-uri`.
@@ -146,13 +148,13 @@ If you want to get the last message in a topic, set the
following configurations
1. For the broker configuration, set `bookkeeperExplicitLacIntervalInMills` >
0 in `broker.conf` or `standalone.conf`.
-2. For the Presto configuration, set `pulsar.bookkeeper-explicit-interval` > 0
and `pulsar.bookkeeper-use-v2-protocol=false`.
+2. For the Trino configuration, set `pulsar.bookkeeper-explicit-interval` > 0
and `pulsar.bookkeeper-use-v2-protocol=false`.
However, using BookKeeper V3 protocol introduces additional GC overhead to BK
as it uses Protobuf.
-## Query data from existing Presto clusters
+## Query data from existing Trino clusters
-If you already have a Presto cluster, you can copy the Presto Pulsar connector
plugin to your existing cluster. Download the archived plugin package with the
following command.
+If you already have a Trino cluster compatible to version 363, you can copy
the Pulsar Trino plugin to your existing cluster. Download the archived plugin
package with the following command.
```bash
wget pulsar:binary_release_url
@@ -160,7 +162,7 @@ wget pulsar:binary_release_url
## Deploy a new cluster
-Since Pulsar SQL is powered by [Trino (formerly Presto
SQL)](https://trino.io), the configuration for deployment is the same for the
Pulsar SQL worker.
+Since Pulsar SQL is powered by Trino, the configuration for deployment is the
same for the Pulsar SQL worker.
:::note
@@ -168,42 +170,14 @@ For how to set up a standalone single node environment,
refer to [Query data](sq
:::
-You can use the same CLI args as the Presto launcher.
-
-```bash
-./bin/pulsar sql-worker --help
-Usage: launcher [options] command
-
-Commands: run, start, stop, restart, kill, status
-
-Options:
- -h, --help show this help message and exit
- -v, --verbose Run verbosely
- --etc-dir=DIR Defaults to INSTALL_PATH/etc
- --launcher-config=FILE
- Defaults to INSTALL_PATH/bin/launcher.properties
- --node-config=FILE Defaults to ETC_DIR/node.properties
- --jvm-config=FILE Defaults to ETC_DIR/jvm.config
- --config=FILE Defaults to ETC_DIR/config.properties
- --log-levels-file=FILE
- Defaults to ETC_DIR/log.properties
- --data-dir=DIR Defaults to INSTALL_PATH
- --pid-file=FILE Defaults to DATA_DIR/var/run/launcher.pid
- --launcher-log-file=FILE
- Defaults to DATA_DIR/var/log/launcher.log (only in
- daemon mode)
- --server-log-file=FILE
- Defaults to DATA_DIR/var/log/server.log (only in
- daemon mode)
- -D NAME=VALUE Set a Java system property
-```
+You can use the same CLI args as the Trino launcher.
-The default configuration for the cluster is located in
`${project.root}/conf/presto`. You can customize your deployment by modifying
the default configuration.
+The default configuration for the cluster is located in
`${project.root}/trino/conf`. You can customize your deployment by modifying
the default configuration.
You can set the worker to read from a different configuration directory, or
set a different directory to write data.
```bash
-./bin/pulsar sql-worker run --etc-dir /tmp/incubator-pulsar/conf/presto
--data-dir /tmp/presto-1
+./bin/pulsar sql-worker run --etc-dir /tmp/pulsar/trino/conf --data-dir
/tmp/trino-1
```
You can start the worker as daemon process.
@@ -214,11 +188,11 @@ You can start the worker as daemon process.
### Deploy a cluster on multiple nodes
-You can deploy a Pulsar SQL cluster or Presto cluster on multiple nodes. The
following example shows how to deploy a cluster on three-node cluster.
+You can deploy a Pulsar SQL cluster or Trino cluster on multiple nodes. The
following example shows how to deploy a cluster on three-node cluster.
1. Copy the Pulsar binary distribution to three nodes.
-The first node runs as Presto coordinator. The minimal configuration required
in the `${project.root}/conf/presto/config.properties` file is as follows.
+The first node runs as Trino coordinator. The minimal configuration required
in the `${project.root}/trino/conf/config.properties` file is as follows.
```properties
coordinator=true
@@ -240,30 +214,30 @@ query.max-memory-per-node=1GB
discovery.uri=<coordinator-url>
```
-2. Modify `pulsar.web-service-url` and `pulsar.zookeeper-uri` configuration
in the `${project.root}/conf/presto/catalog/pulsar.properties` file accordingly
for the three nodes.
+2. Modify `pulsar.web-service-url` and `pulsar.zookeeper-uri` configuration
in the `${project.root}/trino/conf/catalog/pulsar.properties` file accordingly
for the three nodes.
-3. Start the coordinator node.
+3. Start the coordinator node:
-```
+```bash
./bin/pulsar sql-worker run
```
-4. Start worker nodes.
+4. Start worker nodes:
-```
+```bash
./bin/pulsar sql-worker run
```
-5. Start the SQL CLI and check the status of your cluster.
+5. Start the SQL CLI and check the status of your cluster:
```bash
./bin/pulsar sql --server <coordinate_url>
```
-6. Check the status of your nodes.
+6. Check the status of your nodes:
```bash
-presto> SELECT * FROM system.runtime.nodes;
+trino> SELECT * FROM system.runtime.nodes;
node_id | http_uri | node_version | coordinator | state
---------+-------------------------+--------------+-------------+--------
1 | http://192.168.2.1:8081 | testversion | true | active
@@ -271,7 +245,7 @@ presto> SELECT * FROM system.runtime.nodes;
2 | http://192.168.2.3:8081 | testversion | false | active
```
-For more information about the deployment in Presto, refer to [Presto
deployment](https://trino.io/docs/current/installation/deployment.html).
+For more information about the deployment in Trino, refer to [Trino
deployment](https://trino.io/docs/363/installation/deployment.html).
:::note
diff --git a/site2/website-next/docs/sql-getting-started.md
b/site2/website-next/docs/sql-getting-started.md
index 0732682df32..a49d43c48ff 100644
--- a/site2/website-next/docs/sql-getting-started.md
+++ b/site2/website-next/docs/sql-getting-started.md
@@ -15,7 +15,7 @@ Before querying data in Pulsar, you need to install Pulsar
and built-in connecto
To query data in Pulsar with Pulsar SQL, complete the following steps.
-1. Start a Pulsar standalone cluster.
+1. Start a Pulsar standalone cluster:
```bash
PULSAR_STANDALONE_USE_ZOOKEEPER=1 ./bin/pulsar standalone
@@ -23,27 +23,26 @@ PULSAR_STANDALONE_USE_ZOOKEEPER=1 ./bin/pulsar standalone
:::note
-Starting the Pulsar standalone cluster from scratch doesn't enable ZooKeeper
by default.
-However, the Pulsar SQL depends on ZooKeeper. Therefore, you need to set
`PULSAR_STANDALONE_USE_ZOOKEEPER=1` to enable ZooKeeper.
+Starting the Pulsar standalone cluster from scratch doesn't enable ZooKeeper
by default. However, the Pulsar SQL depends on ZooKeeper. Therefore, you need
to set `PULSAR_STANDALONE_USE_ZOOKEEPER=1` to enable ZooKeeper.
:::
-2. Start a Pulsar SQL worker.
+2. Start a Pulsar SQL worker:
```bash
./bin/pulsar sql-worker run
```
-3. After initializing Pulsar standalone cluster and the SQL worker, run SQL
CLI.
+3. After initializing Pulsar standalone cluster and the SQL worker, run SQL
CLI:
```bash
./bin/pulsar sql
```
-4. Test with SQL commands.
+4. Test with SQL commands:
```bash
-presto> show catalogs;
+trino> show catalogs;
Catalog
---------
pulsar
@@ -55,7 +54,7 @@ Splits: 19 total, 19 done (100.00%)
0:00 [0 rows, 0B] [0 rows/s, 0B/s]
-presto> show schemas in pulsar;
+trino> show schemas in pulsar;
Schema
-----------------------
information_schema
@@ -68,7 +67,7 @@ Splits: 19 total, 19 done (100.00%)
0:00 [4 rows, 89B] [21 rows/s, 471B/s]
-presto> show tables in pulsar."public/default";
+trino> show tables in pulsar."public/default";
Table
-------
(0 rows)
@@ -80,16 +79,16 @@ Splits: 19 total, 19 done (100.00%)
Since there is no data in Pulsar, no records are returned.
-5. Start the built-in connector _DataGeneratorSource_ and ingest some mock
data.
+5. Start the built-in connector `DataGeneratorSource` and ingest some mock
data:
```bash
./bin/pulsar-admin sources create --name generator --destinationTopicName
generator_test --source-type data-generator
```
-And then you can query a topic in the namespace "public/default".
+And then you can query a topic in the namespace "public/default":
```bash
-presto> show tables in pulsar."public/default";
+trino> show tables in pulsar."public/default";
Table
----------------
generator_test
@@ -100,10 +99,10 @@ Splits: 19 total, 19 done (100.00%)
0:02 [1 rows, 38B] [0 rows/s, 17B/s]
```
-You can now query the data within the topic "generator_test".
+You can now query the data within the topic "generator_test":
```bash
-presto> select * from pulsar."public/default".generator_test;
+trino> select * from pulsar."public/default".generator_test;
firstname | middlename | lastname | email |
username | password | telephonenumber | age | companyemail
| nationalidentitycardnumber |
-------------+-------------+-------------+----------------------------------+--------------+----------+-----------------+-----+-----------------------------------------------+----------------------------+
@@ -117,61 +116,3 @@ presto> select * from
pulsar."public/default".generator_test;
```
You can query the mock data.
-
-## Query your own data
-
-If you want to query your own data, you need to ingest your own data first.
You can write a simple producer and write custom defined data to Pulsar. The
following is an example.
-
-```java
-public class TestProducer {
-
- public static class Foo {
- private int field1 = 1;
- private String field2;
- private long field3;
-
- public Foo() {
- }
-
- public int getField1() {
- return field1;
- }
-
- public void setField1(int field1) {
- this.field1 = field1;
- }
-
- public String getField2() {
- return field2;
- }
-
- public void setField2(String field2) {
- this.field2 = field2;
- }
-
- public long getField3() {
- return field3;
- }
-
- public void setField3(long field3) {
- this.field3 = field3;
- }
- }
-
- public static void main(String[] args) throws Exception {
- PulsarClient pulsarClient =
PulsarClient.builder().serviceUrl("pulsar://localhost:6650").build();
- Producer<Foo> producer =
pulsarClient.newProducer(AvroSchema.of(Foo.class)).topic("test_topic").create();
-
- for (int i = 0; i < 1000; i++) {
- Foo foo = new Foo();
- foo.setField1(i);
- foo.setField2("foo" + i);
- foo.setField3(System.currentTimeMillis());
- producer.newMessage().value(foo).send();
- }
- producer.close();
- pulsarClient.close();
- }
-}
-```
-
diff --git a/site2/website-next/docs/sql-overview.md
b/site2/website-next/docs/sql-overview.md
index 5c860a7e28e..f320e6a7291 100644
--- a/site2/website-next/docs/sql-overview.md
+++ b/site2/website-next/docs/sql-overview.md
@@ -6,12 +6,16 @@ sidebar_label: "Overview"
Apache Pulsar is used to store streams of event data, and the event data is
structured with predefined fields. With the implementation of the [Schema
Registry](schema-get-started.md), you can store structured data in Pulsar and
query the data by using [Trino (formerly Presto SQL)](https://trino.io/).
-As the core of Pulsar SQL, the Presto Pulsar connector enables Presto workers
within a Presto cluster to query data from Pulsar.
+As the core of Pulsar SQL, the Pulsar Trino plugin enables Trino workers
within a Trino cluster to query data from Pulsar.
The query performance is efficient and highly scalable, because Pulsar adopts
[two-level-segment-based
architecture](concepts-architecture-overview.md#apache-bookkeeper).
-Topics in Pulsar are stored as segments in [Apache
BookKeeper](https://bookkeeper.apache.org/). Each topic segment is replicated
to some BookKeeper nodes, which enables concurrent reads and high read
throughput. You can configure the number of BookKeeper nodes, and the default
number is `3`. In Presto Pulsar connector, data is read directly from
BookKeeper, so Presto workers can read concurrently from a horizontally
scalable number of BookKeeper nodes.
+Topics in Pulsar are stored as segments in [Apache
BookKeeper](https://bookkeeper.apache.org/). Each topic segment is replicated
to some BookKeeper nodes, which enables concurrent reads and high read
throughput. In the Pulsar Trino connector, data is read directly from
BookKeeper, so Trino workers can read concurrently from a horizontally scalable
number of BookKeeper nodes.
+
+# Caveat
+
+If you're upgrading Pulsar SQL from 2.11 or early, you should copy config
files from `conf/presto` to `trino/conf`. If you're downgrading Pulsar SQL to
2.11 or early from newer versions, do verse visa.
diff --git a/site2/website-next/docs/sql-rest-api.md
b/site2/website-next/docs/sql-rest-api.md
index 606966552f7..39e23a8d003 100644
--- a/site2/website-next/docs/sql-rest-api.md
+++ b/site2/website-next/docs/sql-rest-api.md
@@ -4,21 +4,21 @@ title: Pulsar SQL REST APIs
sidebar_label: "REST APIs"
---
-This section lists resources that make up the Presto REST API v1.
+This section lists resources that make up the Trino REST API v1.
-## Request for Presto services
+## Request for Trino services
-All requests for Presto services should use Presto REST API v1 version.
+All requests for Trino services should use Trino REST API v1 version.
-To request services, use the explicit URL `http://presto.service:8081/v1``.
You need to update `presto.service:8081` with your real Presto address before
sending requests.
+To request services, use the explicit URL `http://trino.service:8081/v1``. You
need to update `trino.service:8081` with your real Trino address before sending
requests.
-`POST` requests require the `X-Presto-User` header. If you use authentication,
you must use the same `username` that is specified in the authentication
configuration. If you do not use authentication, you can specify anything for
`username`.
+`POST` requests require the `X-Trino-User` header. If you use authentication,
you must use the same `username` that is specified in the authentication
configuration. If you do not use authentication, you can specify anything for
`username`.
-```properties
-X-Presto-User: username
+```http
+X-Trino-User: username
```
-For more information about headers, refer to
[PrestoHeaders](https://github.com/trinodb/trino).
+For more information about headers, refer to [client request
headers](https://trino.io/docs/363/develop/client-protocol.html#client-request-headers).
## Schema
@@ -26,8 +26,13 @@ You can use statement in the HTTP body. All data is received
as JSON document th
The following is an example of `show catalogs`. The query continues until the
received JSON document does not contain a `nextUri` link. Since no `error` is
displayed in `stats`, it means that the query completes successfully.
-```powershell
-➜ ~ curl --header "X-Presto-User: test-user" --request POST --data 'show
catalogs' http://localhost:8081/v1/statement
+```bash
+curl --header "X-Trino-User: test-user" --request POST --data 'show catalogs'
http://localhost:8081/v1/statement
+```
+
+Output:
+
+```json
{
"infoUri" :
"http://localhost:8081/ui/query.html?20191113_033653_00006_dg6hb";,
"stats" : {
@@ -51,8 +56,15 @@ The following is an example of `show catalogs`. The query
continues until the re
"id" : "20191113_033653_00006_dg6hb",
"nextUri" :
"http://localhost:8081/v1/statement/20191113_033653_00006_dg6hb/1";
}
+```
+
+```bash
+curl http://localhost:8081/v1/statement/20191113_033653_00006_dg6hb/1
+```
-➜ ~ curl http://localhost:8081/v1/statement/20191113_033653_00006_dg6hb/1
+Output:
+
+```json
{
"infoUri" :
"http://localhost:8081/ui/query.html?20191113_033653_00006_dg6hb";,
"nextUri" :
"http://localhost:8081/v1/statement/20191113_033653_00006_dg6hb/2";,
@@ -76,8 +88,15 @@ The following is an example of `show catalogs`. The query
continues until the re
"peakMemoryBytes" : 0
}
}
+```
+
+```bash
+curl http://localhost:8081/v1/statement/20191113_033653_00006_dg6hb/2
+```
+
+Output:
-➜ ~ curl http://localhost:8081/v1/statement/20191113_033653_00006_dg6hb/2
+```json
{
"id" : "20191113_033653_00006_dg6hb",
"data" : [
@@ -184,4 +203,4 @@ Since the response data is not in sync with the query state
from the perspective
:::
-For more information about Presto REST API, refer to [Presto HTTP
Protocol](https://github.com/prestosql/presto/wiki/HTTP-Protocol).
+For more information about Trino REST API, refer to [Trino client REST
API](https://trino.io/docs/363/develop/client-protocol.html).
diff --git
a/site2/website-next/versioned_docs/version-2.10.0-deprecated/administration-proxy.md
b/site2/website-next/versioned_docs/version-2.10.0-deprecated/administration-proxy.md
index f45185dc45b..202d7d64343 100644
---
a/site2/website-next/versioned_docs/version-2.10.0-deprecated/administration-proxy.md
+++
b/site2/website-next/versioned_docs/version-2.10.0-deprecated/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-next/versioned_docs/version-2.10.1-deprecated/administration-proxy.md
b/site2/website-next/versioned_docs/version-2.10.1-deprecated/administration-proxy.md
index f45185dc45b..202d7d64343 100644
---
a/site2/website-next/versioned_docs/version-2.10.1-deprecated/administration-proxy.md
+++
b/site2/website-next/versioned_docs/version-2.10.1-deprecated/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-next/versioned_docs/version-2.10.x/administration-proxy.md
b/site2/website-next/versioned_docs/version-2.10.x/administration-proxy.md
index f45185dc45b..202d7d64343 100644
--- a/site2/website-next/versioned_docs/version-2.10.x/administration-proxy.md
+++ b/site2/website-next/versioned_docs/version-2.10.x/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-next/versioned_docs/version-2.7.5/administration-proxy.md
b/site2/website-next/versioned_docs/version-2.7.5/administration-proxy.md
index c046ed34d46..577eff7db02 100644
--- a/site2/website-next/versioned_docs/version-2.7.5/administration-proxy.md
+++ b/site2/website-next/versioned_docs/version-2.7.5/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-next/versioned_docs/version-2.8.3-deprecated/administration-proxy.md
b/site2/website-next/versioned_docs/version-2.8.3-deprecated/administration-proxy.md
index c046ed34d46..577eff7db02 100644
---
a/site2/website-next/versioned_docs/version-2.8.3-deprecated/administration-proxy.md
+++
b/site2/website-next/versioned_docs/version-2.8.3-deprecated/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-next/versioned_docs/version-2.8.x/administration-proxy.md
b/site2/website-next/versioned_docs/version-2.8.x/administration-proxy.md
index c046ed34d46..577eff7db02 100644
--- a/site2/website-next/versioned_docs/version-2.8.x/administration-proxy.md
+++ b/site2/website-next/versioned_docs/version-2.8.x/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-next/versioned_docs/version-2.9.2-deprecated/administration-proxy.md
b/site2/website-next/versioned_docs/version-2.9.2-deprecated/administration-proxy.md
index 1657e4f88ce..577eff7db02 100644
---
a/site2/website-next/versioned_docs/version-2.9.2-deprecated/administration-proxy.md
+++
b/site2/website-next/versioned_docs/version-2.9.2-deprecated/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-next/versioned_docs/version-2.9.3-deprecated/administration-proxy.md
b/site2/website-next/versioned_docs/version-2.9.3-deprecated/administration-proxy.md
index 1657e4f88ce..577eff7db02 100644
---
a/site2/website-next/versioned_docs/version-2.9.3-deprecated/administration-proxy.md
+++
b/site2/website-next/versioned_docs/version-2.9.3-deprecated/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-next/versioned_docs/version-2.9.x/administration-proxy.md
b/site2/website-next/versioned_docs/version-2.9.x/administration-proxy.md
index 1657e4f88ce..577eff7db02 100644
--- a/site2/website-next/versioned_docs/version-2.9.x/administration-proxy.md
+++ b/site2/website-next/versioned_docs/version-2.9.x/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:
