You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by ur...@apache.org on 2022/10/27 06:01:38 UTC
[pulsar-site] branch main updated: Docs sync done from apache/pulsar(#2c9e729)
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 f7fd7e2978e Docs sync done from apache/pulsar(#2c9e729)
f7fd7e2978e is described below
commit f7fd7e2978ec0e9c4c50c7d8ca1d623015b7c910
Author: Pulsar Site Updater <de...@pulsar.apache.org>
AuthorDate: Thu Oct 27 06:01:32 2022 +0000
Docs sync done from apache/pulsar(#2c9e729)
---
site2/website-next/docs/about.md | 2 +-
site2/website-next/docs/client-libraries-cpp.md | 2 +-
site2/website-next/docs/client-libraries-java.md | 2 +-
site2/website-next/docs/reference-cli-tools.md | 25 +-
site2/website-next/docs/security-athenz.md | 163 ++++++--
site2/website-next/docs/security-extending.md | 8 +-
site2/website-next/docs/security-jwt.md | 105 +++--
site2/website-next/docs/security-kerberos.md | 432 +++++++++------------
site2/website-next/docs/security-oauth2.md | 169 ++++----
site2/website-next/docs/security-overview.md | 39 +-
.../docs/security-tls-authentication.md | 15 +-
.../version-2.10.x/client-libraries-cpp.md | 370 ++++--------------
.../version-2.7.5/client-libraries-cpp.md | 164 +++-----
.../version-2.8.x/client-libraries-cpp.md | 270 +++----------
.../version-2.9.x/client-libraries-cpp.md | 343 ++++------------
15 files changed, 743 insertions(+), 1366 deletions(-)
diff --git a/site2/website-next/docs/about.md b/site2/website-next/docs/about.md
index f1983734978..6a1dd538372 100644
--- a/site2/website-next/docs/about.md
+++ b/site2/website-next/docs/about.md
@@ -55,7 +55,7 @@ You’ll notice an Edit button at the bottom and top of each page. Click it to o
:::tip
-For how to make contributions to documentation, see [Pulsar Documentation Contribution Guide](https://docs.google.com/document/d/11DTnNPpvcPrebLkMAFcDEIFlD8ARD-k6F-LXoIwdD9Y/edit#).
+For how to make contributions to documentation, see [Pulsar Documentation Contribution Guide](https://github.com/apache/pulsar/blob/master/site2/README.md).
:::
diff --git a/site2/website-next/docs/client-libraries-cpp.md b/site2/website-next/docs/client-libraries-cpp.md
index 58d1cef4b3c..7f56d3cc727 100644
--- a/site2/website-next/docs/client-libraries-cpp.md
+++ b/site2/website-next/docs/client-libraries-cpp.md
@@ -78,7 +78,7 @@ This package contains shared libraries: `libpulsar.so` and `libpulsarnossl.so`.
wget @pulsar:dist_rpm:client-debuginfo@
```
-This package contains debug symbols for `libpulsar.so`
+This package contains debug symbols for `libpulsar.so`.
</TabItem>
<TabItem value="client-devel">
diff --git a/site2/website-next/docs/client-libraries-java.md b/site2/website-next/docs/client-libraries-java.md
index 2135c165a45..e36a3957b1a 100644
--- a/site2/website-next/docs/client-libraries-java.md
+++ b/site2/website-next/docs/client-libraries-java.md
@@ -1262,7 +1262,7 @@ Pulsar currently supports the following authentication mechansims:
* [TLS](security-tls-authentication.md#configure-tls-authentication-in-pulsar-clients)
* [JWT](security-jwt.md#configure-jwt-authentication-in-pulsar-clients)
* [Athenz](security-athenz.md#configure-athenz-authentication-in-pulsar-clients)
-* [Kerberos](security-kerberos.md#java-client-and-java-admin-client)
+* [Kerberos](security-kerberos.md#configure-kerberos-authentication-in-pulsar-clients)
* [OAuth2](security-oauth2.md#configure-oauth2-authentication-in-pulsar-clients)
* [HTTP basic](security-basic-auth.md#configure-basic-authentication-in-pulsar-clients)
diff --git a/site2/website-next/docs/reference-cli-tools.md b/site2/website-next/docs/reference-cli-tools.md
index cde841484a4..7d28866076e 100644
--- a/site2/website-next/docs/reference-cli-tools.md
+++ b/site2/website-next/docs/reference-cli-tools.md
@@ -6,14 +6,19 @@ sidebar_label: "Pulsar CLI tools"
Pulsar offers several command-line tools that you can use for managing Pulsar installations, performance testing, using command-line producers and consumers, and more.
-* [`pulsar-admin`](https://pulsar.apache.org/reference/#/latest/pulsar-admin/)
-* [`pulsar`](https://pulsar.apache.org/reference/#/latest/pulsar/)
-* [`pulsar-client`](https://pulsar.apache.org/reference/#/latest/pulsar-client/)
-* [`pulsar-perf`](https://pulsar.apache.org/reference/#/latest/pulsar-perf/)
-* [`pulsar-daemon`](reference-cli-pulsar-daemon.md)
-* [`pulsar-shell`](reference-cli-pulsar-shell.md)
-* [`bookkeeper`](reference-cli-bookkeeper.md)
-* [`broker-tool`](reference-cli-broker-tool.md)
+* `pulsar-admin`
+* `pulsar`
+* `pulsar-client`
+* `pulsar-daemon`
+* `pulsar-perf`
+* `pulsar-shell`
+* `bookkeeper`
+
+::: tip
+
+For the latest and complete information about command-line tools, including commands, flags, descriptions, and more information, see [Pulsar Reference](https://pulsar.apache.org/reference).
+
+:::
All Pulsar command-line tools can be run from the `bin` directory of your [installed Pulsar package](getting-started-standalone.md).
@@ -21,6 +26,4 @@ You can get help for any CLI tool, command, or subcommand using the `--help` fla
```shell
bin/pulsar broker --help
-```
-
-
+```
\ No newline at end of file
diff --git a/site2/website-next/docs/security-athenz.md b/site2/website-next/docs/security-athenz.md
index 60849db06ab..3bccffd70b7 100644
--- a/site2/website-next/docs/security-athenz.md
+++ b/site2/website-next/docs/security-athenz.md
@@ -6,42 +6,43 @@ sidebar_label: "Authentication using Athenz"
[Athenz](https://github.com/AthenZ/athenz) is a role-based authentication/authorization system. In Pulsar, you can use Athenz role tokens (also known as *z-tokens*) to establish the identity of the client.
-## Enable Athenz authentication
-
A [decentralized Athenz system](https://github.com/AthenZ/athenz/blob/master/docs/decent_authz_flow.md) contains an [authori**Z**ation **M**anagement **S**ystem](https://github.com/AthenZ/athenz/blob/master/docs/setup_zms.md) (ZMS) server and an [authori**Z**ation **T**oken **S**ystem](https://github.com/AthenZ/athenz/blob/master/docs/setup_zts) (ZTS) server.
-To begin, you need to set up Athenz service access control. You need to create domains for the *provider* (which provides some resources to other services with some authentication/authorization policies) and the *tenant* (which is provisioned to access some resources in a provider). In this case, the provider corresponds to the Pulsar service itself and the tenant corresponds to each application using Pulsar (typically, a [tenant](reference-terminology.md#tenant) in Pulsar).
+## Prerequisites
+
+To begin, you need to set up Athenz service access control by creating domains for the *provider* (which provides some resources to other services with some authentication/authorization policies) and the *tenant* (which is provisioned to access some resources in a provider). In this case, the provider corresponds to the Pulsar service itself and the tenant corresponds to each application using Pulsar (typically, a [tenant](reference-terminology.md#tenant) in Pulsar).
-### Create the tenant domain and service
+### Create a tenant domain and service
-On the [tenant](reference-terminology.md#tenant) side, you need to do the following things:
+On the tenant side, do the followings:
-1. Create a domain, such as `shopping`
-2. Generate a private/public key pair
-3. Create a service, such as `some_app`, on the domain with the public key
+1. Create a domain, such as `shopping`.
+2. Generate a private/public key pair.
+3. Create a service, such as `some_app`, on the domain with the public key.
-Note that you need to specify the private key generated in step 2 when the Pulsar client connects to the [broker](reference-terminology.md#broker) (see client configuration examples for [Java](client-libraries-java.md) and [C++](client-libraries-cpp.md)).
+Note that you need to specify the private key generated in step 2 when the Pulsar client connects to the broker.
For more specific steps involving the Athenz UI, refer to [Example Service Access Control Setup](https://github.com/AthenZ/athenz/blob/master/docs/example_service_athenz_setup.md#client-tenant-domain).
-### Create the provider domain and add the tenant service to some role members
+### Create a provider domain and add the tenant service to role members
On the provider side, you need to do the following things:
-1. Create a domain, such as `pulsar`
-2. Create a role
-3. Add the tenant service to members of the role
+1. Create a domain, such as `pulsar`.
+2. Create a role.
+3. Add the tenant service to the members of the role.
Note that you can specify any action and resource in step 2 since they are not used on Pulsar. In other words, Pulsar uses the Athenz role token only for authentication, *not* for authorization.
-For more specific steps involving UI, refer to [Example Service Access Control Setup](https://github.com/AthenZ/athenz/blob/master/docs/example_service_athenz_setup.md#server-provider-domain).
+For more specific steps involving the Athenz UI, refer to [Example Service Access Control Setup](https://github.com/AthenZ/athenz/blob/master/docs/example_service_athenz_setup.md#server-provider-domain).
## Enable Athenz authentication on brokers
-> ### TLS encryption
->
-> Note that when you are using Athenz as an authentication provider, you had better use TLS encryption
-> as it can protect role tokens from being intercepted and reused. (for more details involving TLS encryption see [Architecture - Data Model](https://github.com/AthenZ/athenz/blob/master/docs/data_model)).
+:::note
+
+When you are using Athenz as an authentication provider, it's highly recommended to use [TLS encryption](security-tls-transport.md) as it can protect role tokens from being intercepted and reused. For more details involving TLS encryption, see [Architecture - Data Model](https://github.com/AthenZ/athenz/blob/master/docs/data_model).
+
+:::
In the `conf/broker.conf` configuration file in your Pulsar installation, you need to provide the class name of the Athenz authentication provider as well as a comma-separated list of provider domain names.
@@ -52,11 +53,6 @@ authorizationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderAthenz
athenzDomainNames=pulsar
-# Enable TLS
-tlsEnabled=true
-tlsCertificateFilePath=/path/to/broker-cert.pem
-tlsKeyFilePath=/path/to/broker-key.pem
-
# Authentication settings of the broker itself. Used when the broker connects to other brokers, either in same or other clusters
brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}
@@ -65,18 +61,49 @@ brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":
> A full listing of parameters is available in the `conf/broker.conf` file, you can also find the default
> values for those parameters in [Broker Configuration](reference-configuration.md#broker).
+## Enable Athenz authentication on proxies
+
+Configure the required parameters in the `conf/proxy.conf` file in your Pulsar installation.
+
+```properties
+# Add the Athenz auth provider
+authenticationEnabled=true
+authorizationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderAthenz
+athenzDomainNames=pulsar
+
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
+brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}
+```
+
## Configure Athenz authentication in Pulsar clients
-To use Athenz as an authentication provider, you need to [use TLS](#tls-encryption) and provide values for four parameters in a hash:
+To use Athenz as an authentication provider, you need to provide values for four parameters in a hash:
* `tenantDomain`
* `tenantService`
* `providerDomain`
* `privateKey`
+:::tip
+
+The `privateKey` parameter supports the following three pattern formats:
+* `file:///path/to/file`
+* `file:/path/to/file`
+* `data:application/x-pem-file;base64,<base64-encoded value>`
+
+:::
+
You can also set an optional `keyId`. The following is an example.
+````mdx-code-block
+<Tabs groupId="lang-choice"
+ defaultValue="Java"
+ values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"C++","value":"C++"},{"label":"Node.js","value":"Node.js"},{"label":"Go","value":"Go"}]}>
+<TabItem value="Java">
+
```java
Map<String, String> authParams = new HashMap();
+authParams.put("ztsUrl", "http://localhost:9998");
authParams.put("tenantDomain", "shopping"); // Tenant domain name
authParams.put("tenantService", "some_app"); // Tenant service name
authParams.put("providerDomain", "pulsar"); // Provider domain name
@@ -87,17 +114,88 @@ Authentication athenzAuth = AuthenticationFactory
.create(AuthenticationAthenz.class.getName(), authParams);
PulsarClient client = PulsarClient.builder()
- .serviceUrl("pulsar+ssl://my-broker.com:6651")
- .tlsTrustCertsFilePath("/path/to/cacert.pem")
+ .serviceUrl("pulsar://my-broker.com:6650")
.authentication(athenzAuth)
.build();
```
-#### Supported pattern formats
-The `privateKey` parameter supports the following three pattern formats:
-* `file:///path/to/file`
-* `file:/path/to/file`
-* `data:application/x-pem-file;base64,<base64-encoded value>`
+</TabItem>
+<TabItem value="Python">
+
+```python
+authPlugin = "athenz"
+authParams = """
+{
+"tenantDomain": "shopping",
+"tenantService": "some_app",
+"providerDomain": "pulsar",
+"privateKey": "file:///path/to/private.pem",
+"ztsUrl": "http://localhost:9998"
+}
+"""
+
+client = Client(
+ "pulsar://my-broker.com:6650",
+ authentication=Authentication(authPlugin, authParams),
+)
+```
+
+</TabItem>
+<TabItem value="C++">
+
+```cpp
+std::string params = R"({
+ "tenantDomain": "shopping",
+ "tenantService": "some_app",
+ "providerDomain": "pulsar",
+ "privateKey": "file:///path/to/private.pem",
+ "ztsUrl": "http://localhost:9998"
+ })";
+pulsar::AuthenticationPtr auth = pulsar::AuthAthenz::create(params);
+ClientConfiguration config = ClientConfiguration();
+config.setAuth(auth);
+Client client("pulsar://my-broker.com:6650", config);
+```
+
+</TabItem>
+<TabItem value="Node.js">
+
+```javascript
+const auth = new Pulsar.AuthenticationAthenz({
+ tenantDomain: "shopping",
+ tenantService: "some_app",
+ providerDomain: "pulsar",
+ privateKey: "file:///path/to/private.pem",
+ ztsUrl: "http://localhost:9998"
+});
+
+const client = new Pulsar.Client({
+ serviceUrl: 'pulsar://my-broker.com:6650',
+ authentication: auth
+});
+```
+
+</TabItem>
+<TabItem value="Go">
+
+```go
+provider := pulsar.NewAuthenticationAthenz(
+ "pulsar",
+ "shopping",
+ "some_app",
+ "file:///path/to/private.pem",
+ "v1",
+ "",
+ "http://localhost:9998")
+client, err := pulsarNewClient(ClientOptions{
+ URL: "pulsar://my-broker.com:6650",
+ Authentication: basicAuth,
+ })
+```
+
+</TabItem>
+</Tabs>
+````
## Configure Athenz authentication in CLI tools
@@ -117,5 +215,4 @@ authParams={"tenantDomain":"shopping","tenantService":"some_app","providerDomain
useTls=true
tlsAllowInsecureConnection=false
tlsTrustCertsFilePath=/path/to/cacert.pem
-```
-
+```
\ No newline at end of file
diff --git a/site2/website-next/docs/security-extending.md b/site2/website-next/docs/security-extending.md
index 2955c44a922..b3470307416 100644
--- a/site2/website-next/docs/security-extending.md
+++ b/site2/website-next/docs/security-extending.md
@@ -9,8 +9,8 @@ Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
You can use a custom authentication mechanism by providing the implementation in the form of two plugins.
-* Client authentication plugin
-* Proxy/Broker authentication plugin
+* Client authentication plugin `org.apache.pulsar.client.api.AuthenticationDataProvider` provides the authentication data for broker/proxy.
+* Broker/Proxy authentication plugin `org.apache.pulsar.broker.authentication.AuthenticationProvider` authenticates the authentication data from clients.
### Client authentication plugin
@@ -37,9 +37,9 @@ You can find the following examples for different client authentication plugins:
* [OAuth 2.0](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/AuthenticationOAuth2.java)
* [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationBasic.java)
-### Proxy/Broker authentication plugin
+### Broker/Proxy authentication plugin
-On the proxy/broker side, you need to configure the corresponding plugin to validate the credentials that the client sends. The proxy and broker can support multiple authentication providers at the same time.
+On the broker/proxy side, you need to configure the corresponding plugin to validate the credentials that the client sends. The proxy and broker can support multiple authentication providers at the same time.
In `conf/broker.conf`, you can choose to specify a list of valid providers:
diff --git a/site2/website-next/docs/security-jwt.md b/site2/website-next/docs/security-jwt.md
index 1764887827e..88d0ac408d9 100644
--- a/site2/website-next/docs/security-jwt.md
+++ b/site2/website-next/docs/security-jwt.md
@@ -1,6 +1,6 @@
---
id: security-jwt
-title: Client authentication using tokens based on JSON Web Tokens
+title: Authentication using tokens based on JSON Web Tokens
sidebar_label: "Authentication using JWT"
---
@@ -9,43 +9,34 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
````
+Pulsar supports authenticating clients using security tokens based on [JSON Web Tokens](https://jwt.io/introduction/) ([RFC-7519](https://tools.ietf.org/html/rfc7519)), including all the algorithms that the [Java JWT library](https://github.com/jwtk/jjwt#signature-algorithms-keys) supports.
-## Token authentication overview
+A token is a credential associated with a user. The association is done through a "principal" or "role". In the case of JWT tokens, it typically refers to a **subject**. You can use a token to identify a Pulsar client and associate it with a **subject** that is permitted to do specific actions, such as publish messages to a topic or consume messages from a topic. An alternative is to pass a "token supplier" (a function that returns the token when the client library needs one).
-Pulsar supports authenticating clients using security tokens that are based on [JSON Web Tokens](https://jwt.io/introduction/) ([RFC-7519](https://tools.ietf.org/html/rfc7519)).
-
-You can use tokens to identify a Pulsar client and associate with some "principal" (or "role") that
-is permitted to do some actions (eg: publish to a topic or consume from a topic).
-
-A user typically gets a token string from the administrator (or some automated service).
-
-The compact representation of a signed JWT is a string that looks like the following:
+The application specifies the token when you create the client instance. The user typically gets the token string from the administrator. The compact representation of a signed JWT is a string that looks like the following:
```
eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
```
-Application specifies the token when you create the client instance. An alternative is to pass a "token supplier" (a function that returns the token when the client library needs one).
-
:::note
-Always use TLS transport encryption when you connect to the Pulsar service, because sending a token is equivalent to sending a password over the wire. See [Transport Encryption using TLS](security-tls-transport.md) for more details.
+Always use [TLS encryption](security-tls-transport.md) when connecting to the Pulsar service, because sending a token is equivalent to sending a password over the wire.
:::
-## Enable token authentication
+## Create client certificates
-JWT supports two different kinds of keys to generate and validate the tokens:
+JWT authentication supports two different kinds of keys to generate and validate the tokens:
- * Symmetric:
- - You can use a single ***Secret*** key to generate and validate tokens.
- * Asymmetric: A pair of keys consists of the Private key and the Public key.
- - You can use ***Private*** key to generate tokens.
- - You can use ***Public*** key to validate tokens.
+- Symmetric: A single ***secret*** key.
+- Asymmetric: A key pair, including:
+ - a ***private*** key to generate tokens.
+ - a ***public*** key to validate tokens.
### Create a secret key
-When you use a secret key, the administrator creates the key and uses the key to generate the client tokens. You can also configure this key to brokers to validate the clients.
+The administrators create the secret key and use it to generate the client tokens. You can also configure this key for brokers to validate the clients.
The output file is generated in the root of your Pulsar installation directory. You can also provide an absolute path for the output file using the command below.
@@ -53,7 +44,7 @@ The output file is generated in the root of your Pulsar installation directory.
bin/pulsar tokens create-secret-key --output my-secret.key
```
-Enter this command to generate a base64 encoded private key.
+To generate a base64-encoded private key, enter the following command.
```shell
bin/pulsar tokens create-secret-key --output /opt/my-secret.key --base64
@@ -61,54 +52,48 @@ bin/pulsar tokens create-secret-key --output /opt/my-secret.key --base64
### Create a key pair
-With Public and Private keys, you need to create a pair of keys. Pulsar supports all algorithms that the Java JWT library (shown [here](https://github.com/jwtk/jjwt#signature-algorithms-keys)) supports.
-
-The output file is generated in the root of your Pulsar installation directory. You can also provide an absolute path for the output file using the command below.
+To use asymmetric key encryption, you need to create a pair of keys. The output file is generated in the root of your Pulsar installation directory. You can also provide an absolute path for the output file using the command below.
```shell
bin/pulsar tokens create-key-pair --output-private-key my-private.key --output-public-key my-public.key
```
- * Store `my-private.key` in a safe location and only administrators can use `my-private.key` to generate new tokens.
- * `my-public.key` is distributed to all Pulsar brokers. You can publicly share this file without any security concerns.
+ * Store `my-private.key` in a safe location and only the administrators can use this private key to generate new tokens.
+ * The public key file `my-public.key` is distributed to all Pulsar brokers. You can publicly share it without any security concerns.
### Generate tokens
-A token is a credential associated with a user. The association is done through the "principal" or "role". In the case of JWT tokens, this field is typically referred as **subject**, though they are the same concept.
-
-Then, you need to use this command to require the generated token to have a **subject** fieldset.
-
-```shell
-bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \
- --subject test-user
-```
+1. Use this command to require the generated token to have a **subject** fieldset. This command prints the token string on `stdout`.
-This command prints the token string on stdout.
+ ```shell
+ bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \
+ --subject test-user
+ ```
-Similarly, you can create a token by passing the "private" key using the command below:
+2. Create a token by passing the "private" key using the command below:
-```shell
-bin/pulsar tokens create --private-key file:///path/to/my-private.key \
- --subject test-user
-```
+ ```shell
+ bin/pulsar tokens create --private-key file:///path/to/my-private.key \
+ --subject test-user
+ ```
-Finally, you can enter the following command to create a token with a pre-defined TTL. And then the token is automatically invalidated.
+3. Create a token with a pre-defined TTL. Then the token is automatically invalidated.
-```shell
-bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \
- --subject test-user \
- --expiry-time 1y
-```
+ ```shell
+ bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \
+ --subject test-user \
+ --expiry-time 1y
+ ```
:::tip
-The token itself does not have any permission associated. The authorization engine determines whether the token can have permissions or not. You need to [enable authorization and assign superusers](security-authorization.md#enable-authorization-and-assign-superusers), and then use the `bin/pulsar-admin namespaces grant-permission` command to grant permissions for tokens.
+The token itself does not have any permission associated. You need to [enable authorization and assign superusers](security-authorization.md#enable-authorization-and-assign-superusers), and use the `bin/pulsar-admin namespaces grant-permission` command to grant permissions to the token.
:::
-### Enable token authentication on brokers
+## Enable JWT authentication on brokers
-To configure brokers to authenticate clients, add the following parameters to the `conf/broker.conf` or `conf/standalone.conf` file.
+To configure brokers to authenticate clients using JWT, add the following parameters to the `conf/broker.conf` or `conf/standalone.conf` file.
```properties
# Configuration to enable authentication
@@ -143,9 +128,9 @@ Equivalent to `brokerClientAuthenticationParameters`, you need to configure `aut
:::
-### Enable token authentication on proxies
+## Enable JWT authentication on proxies
-To configure proxies to authenticate clients, add the following parameters to the `conf/proxy.conf` file.
+To configure proxies to authenticate clients using JWT, add the following parameters to the `conf/proxy.conf` file.
```properties
# For clients connecting to the proxy
@@ -162,16 +147,20 @@ brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0
# brokerClientAuthenticationParameters=file:///path/to/token
```
+:::note
+
The proxy uses its own token when connecting to brokers. You need to configure the role token for this key pair in the `proxyRoles` of the brokers. For more details, see [authorization](security-authorization.md).
-### Configure JWT authentication in CLI Tools
+:::
+
+## Configure JWT authentication in CLI Tools
[Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](/tools/pulsar-admin/), [`pulsar-perf`](reference-cli-tools.md), and [`pulsar-client`](reference-cli-tools.md) use the `conf/client.conf` config file in a Pulsar installation.
-You need to add the following parameters to that file to use the token authentication with CLI tools of Pulsar:
+You need to add the following parameters to the `conf/client.conf` config file to use the JWT authentication with CLI tools of Pulsar:
-```conf
-webServiceUrl=http://broker.example.com:8080/
+```properties
+webServiceUrl=https://broker.example.com:8443/
brokerServiceUrl=pulsar://broker.example.com:6650/
authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
authParams=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
@@ -179,11 +168,11 @@ authParams=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPt
The token string can also be read from a file, for example:
-```conf
+```properties
authParams=file:///path/to/token/file
```
-### Configure JWT authentication in Pulsar clients
+## Configure JWT authentication in Pulsar clients
You can use tokens to authenticate the following Pulsar clients.
diff --git a/site2/website-next/docs/security-kerberos.md b/site2/website-next/docs/security-kerberos.md
index 506dc1573c6..9d7b7ddf1aa 100644
--- a/site2/website-next/docs/security-kerberos.md
+++ b/site2/website-next/docs/security-kerberos.md
@@ -4,28 +4,34 @@ title: Authentication using Kerberos
sidebar_label: "Authentication using Kerberos"
---
-[Kerberos](https://web.mit.edu/kerberos/) is a network authentication protocol. By using secret-key cryptography, [Kerberos](https://web.mit.edu/kerberos/) is designed to provide strong authentication for client applications and server applications.
+[Kerberos](https://web.mit.edu/kerberos/) is a network authentication protocol designed to provide strong authentication for client applications and server applications by using secret-key cryptography.
-In Pulsar, you can use Kerberos with [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) as a choice for authentication. And Pulsar uses the [Java Authentication and Authorization Service (JAAS)](https://en.wikipedia.org/wiki/Java_Authentication_and_Authorization_Service) for SASL configuration. You need to provide JAAS configurations for Kerberos authentication.
+In Pulsar, you can use Kerberos with [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) as a choice for authentication. Since Pulsar uses the [Java Authentication and Authorization Service (JAAS)](https://en.wikipedia.org/wiki/Java_Authentication_and_Authorization_Service) for SASL configuration, you need to provide JAAS configurations for Kerberos authentication.
-This document introduces how to configure `Kerberos` with `SASL` between Pulsar clients and brokers and how to configure Kerberos for Pulsar proxy in detail.
+:::note
-## Configure Kerberos between client and broker
+Kerberos authentication uses the authenticated principal as the role token for [Pulsar authorization](security-authorization.md). If you've enabled `authorizationEnabled`, you need to set `superUserRoles` in `broker.conf` that corresponds to the name registered in KDC. For example:
-### Prerequisites
+```bash
+superUserRoles=client/{clientIp}@EXAMPLE.COM
+```
-To begin, you need to set up (or already have) a [Key Distribution Center(KDC)](https://en.wikipedia.org/wiki/Key_distribution_center). Also you need to configure and run the [Key Distribution Center(KDC)](https://en.wikipedia.org/wiki/Key_distribution_center)in advance.
+:::
-If your organization already uses a Kerberos server (for example, by using `Active Directory`), you do not have to install a new server for Pulsar. If your organization does not use a Kerberos server, you need to install one. Your Linux vendor might have packages for `Kerberos`. On how to install and configure Kerberos, refer to [Ubuntu](https://help.ubuntu.com/community/Kerberos),
+## Prerequisites
+
+- Set up and run a [Key Distribution Center(KDC)](https://en.wikipedia.org/wiki/Key_distribution_center).
+- Install a Kerberos server if your organization doesn't have one. Your Linux vendor might have packages for `Kerberos`. For how to install and configure Kerberos, see [Ubuntu](https://help.ubuntu.com/community/Kerberos) and
[Redhat](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/installing-kerberos.html).
+- If you use Oracle Java, you need to download JCE policy files for your Java version and copy them to the `$JAVA_HOME/jre/lib/security` directory.
-Note that if you use Oracle Java, you need to download JCE policy files for your Java version and copy them to the `$JAVA_HOME/jre/lib/security` directory.
+## Enable Kerberos authentication on brokers
-#### Kerberos principals
+### Create Kerberos principals
-If you use the existing Kerberos system, ask your Kerberos administrator for a principal for each brokers in your cluster and for every operating system user that accesses Pulsar with Kerberos authentication(via clients and tools).
+If you use the existing Kerberos system, ask your Kerberos administrator to obtain a principal for each broker in your cluster and for every operating system user that accesses Pulsar with Kerberos authentication (via clients and CLI tools).
-If you have installed your own Kerberos system, you can create these principals with the following commands:
+If you have installed your own Kerberos system, you need to create these principals with the following commands:
```shell
### add Principals for broker
@@ -36,35 +42,32 @@ sudo /usr/sbin/kadmin.local -q 'addprinc -randkey client/{hostname}@{REALM}'
sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{client-keytabname}.keytab client/{hostname}@{REALM}"
```
-Note that *Kerberos* requires that all your hosts can be resolved with their FQDNs.
-
-The first part of broker principal (for example, `broker` in `broker/{hostname}@{REALM}`) is the `serverType` of each host. The suggested values of `serverType` are `broker` (host machine runs service Pulsar brokers) and `proxy` (host machine runs service Pulsar Proxy).
+The first part of broker principal (for example, `broker` in `broker/{hostname}@{REALM}`) is the `serverType` of each host. The suggested values of `serverType` are `broker` (host machine runs Pulsar broker service) and `proxy` (host machine runs Pulsar Proxy service).
-#### Connect to KDC
-
-You need to enter the command below to specify the path to the `krb5.conf` file for the client side and the broker side. The content of `krb5.conf` file indicates the default Realm and KDC information. See [JDK’s Kerberos Requirements](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/KerberosReq.html) for more details.
-
-```shell
--Djava.security.krb5.conf=/etc/pulsar/krb5.conf
-```
+Note that *Kerberos* requires that all your hosts can be resolved with their FQDNs.
-Here is an example of the krb5.conf file. `EXAMPLE.COM` is the default realm; `kdc = localhost:62037` is the kdc server URL for realm `EXAMPLE.COM `.
+### Configure brokers
+
+In the `broker.conf` file, set Kerberos-related configurations. Here is an example:
```conf
-[libdefaults]
- default_realm = EXAMPLE.COM
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
+saslJaasClientAllowedIds=.*client.* ## regex for principals that are allowed to connect to brokers
+saslJaasServerSectionName=PulsarBroker ## corresponds to the section in the JAAS configuration file for brokers
-[realms]
- EXAMPLE.COM = {
- kdc = localhost:62037
- }
+## Authentication settings of the broker itself. Used when the broker connects to other brokers
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
+brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}
```
-Usually machines configured with kerberos already have a system-wide configuration and this configuration is optional.
+To make Pulsar internal admin client work properly, you need to:
+- Set `brokerClientAuthenticationPlugin` to client plugin `AuthenticationSasl`;
+- Set `brokerClientAuthenticationParameters` to value in JSON string `{"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}`, in which `PulsarClient` is the section name in the `pulsar_jaas.conf` file, and `"serverType":"broker"` indicates that the internal admin client connects to a broker.
-#### Configure JAAS configuration file
+### Configure JAAS
-You need the JAAS configuration file for the client side and the broker side. JAAS configuration file provides the section of information that is used to connect KDC. Here is an example named `pulsar_jaas.conf`:
+JAAS configuration file provides the information to connect KDC. Here is an example named `pulsar_jaas.conf`:
```conf
PulsarBroker {
@@ -86,174 +89,90 @@ You need the JAAS configuration file for the client side and the broker side. JA
};
```
-You need to set the `JAAS` configuration file path as JVM parameter for client and broker. For example:
+In the above example:
+- `PulsarBroker` is a section name in the JAAS file that each broker uses. This section tells the broker to use which principal inside Kerberos and the location of the keytab where the principal is stored.
+- `PulsarClient` is a section name in the JASS file that each client uses. This section tells the client to use which principal inside Kerberos and the location of the keytab where the principal is stored.
+
+You need to set the `pulsar_jaas.conf` file path as a JVM parameter. For example:
```shell
-Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf
```
-In the `pulsar_jaas.conf` file above
-
-1. `PulsarBroker` is a section name in the JAAS file that each broker uses. This section tells the broker to use which principal inside Kerberos and the location of the keytab where the principal is stored. `PulsarBroker` allows the broker to use the keytab specified in this section.
-2. `PulsarClient` is a section name in the JASS file that each broker uses. This section tells the client to use which principal inside Kerberos and the location of the keytab where the principal is stored. `PulsarClient` allows the client to use the keytab specified in this section.
- The following example also reuses this `PulsarClient` section in both the Pulsar internal admin configuration and in CLI command of `bin/pulsar-client`, `bin/pulsar-perf` and `bin/pulsar-admin`. You can also add different sections for different use cases.
-
-You can have 2 separate JAAS configuration files:
-* the file for a broker that has sections of both `PulsarBroker` and `PulsarClient`;
-* the file for a client that only has a `PulsarClient` section.
-
-
-### Configure Kerberos authentication for brokers
+### Connect to KDC
-#### Configure the `broker.conf` file
-
-In the `broker.conf` file, set Kerberos-related configurations.
-
-- Set `authenticationEnabled` to `true`;
-- Set `authenticationProviders` to choose `AuthenticationProviderSasl`;
-- Set `saslJaasClientAllowedIds` regex for principals that are allowed to connect to brokers;
-- Set `saslJaasServerSectionName` that corresponds to the section in the JAAS configuration file for brokers;
-
-To make Pulsar internal admin client work properly, you need to set the configuration in the `broker.conf` file as below:
-- Set `brokerClientAuthenticationPlugin` to client plugin `AuthenticationSasl`;
-- Set `brokerClientAuthenticationParameters` to value in JSON string `{"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}`, in which `PulsarClient` is the section name in the `pulsar_jaas.conf` file, and `"serverType":"broker"` indicates that the internal admin client connects to a Pulsar Broker;
-
-Here is an example:
+:::note
-```conf
-authenticationEnabled=true
-authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
-saslJaasClientAllowedIds=.*client.*
-saslJaasServerSectionName=PulsarBroker
+If your machines configured with Kerberos already have a system-wide configuration, you can skip this configuration.
-## Authentication settings of the broker itself. Used when the broker connects to other brokers
-brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
-brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}
-```
+:::
-#### Set broker JVM parameters
+The content of `krb5.conf` file indicates the default Realm and KDC information. See [JDK’s Kerberos Requirements](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/KerberosReq.html) for more details.
-Set JVM parameters for the JAAS configuration file and krb5 configuration file with additional options.
+To specify the path to the `krb5.conf` file for brokers, enter the command below.
```shell
--Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf
+-Djava.security.krb5.conf=/etc/pulsar/krb5.conf
```
-You can add this at the end of `PULSAR_EXTRA_OPTS` in the file [`pulsar_env.sh`](https://github.com/apache/pulsar/blob/master/conf/pulsar_env.sh)
-
-You must ensure that the operating system user who starts broker can reach the keytabs configured in the `pulsar_jaas.conf` file and kdc server in the `krb5.conf` file.
-
-### Configure Kerberos authentication for clients
+Here is an example of the `krb5.conf` file.
-#### Java Client and Java Admin Client
-
-In client applications, include `pulsar-client-auth-sasl` in your project dependency.
+```conf
+[libdefaults]
+ default_realm = EXAMPLE.COM
-```xml
- <dependency>
- <groupId>org.apache.pulsar</groupId>
- <artifactId>pulsar-client-auth-sasl</artifactId>
- <version>${pulsar.version}</version>
- </dependency>
+[realms]
+ EXAMPLE.COM = {
+ kdc = localhost:62037
+ }
```
-Configure the authentication type to use `AuthenticationSasl`, and also provide the authentication parameters to it.
-
-You need 2 parameters:
-- `saslJaasClientSectionName`. This parameter corresponds to the section in the JAAS configuration file for clients;
-- `serverType`. This parameter stands for whether this client connects to brokers or proxies. And client uses this parameter to know which server-side principal should be used.
-
-When you authenticate between client and broker with the setting in the above JAAS configuration file, we need to set `saslJaasClientSectionName` to `PulsarClient` and set `serverType` to `broker`.
+In the above example:
+- `EXAMPLE.COM` is the default Realm;
+- `kdc = localhost:62037` is the KDC server URL for the `EXAMPLE.COM` Realm.
-The following is an example of creating a Java client:
+## Enable Kerberos authentication on proxies
- ```java
- System.setProperty("java.security.auth.login.config", "/etc/pulsar/pulsar_jaas.conf");
- System.setProperty("java.security.krb5.conf", "/etc/pulsar/krb5.conf");
+If you want to use proxies between brokers and clients, Pulsar proxies (as a SASL server in Kerberos) will authenticate clients (as a SASL client in Kerberos) before brokers authenticate proxies.
- Map<String, String> authParams = Maps.newHashMap();
- authParams.put("saslJaasClientSectionName", "PulsarClient");
- authParams.put("serverType", "broker");
+### Create Kerberos principals
- Authentication saslAuth = AuthenticationFactory
- .create(org.apache.pulsar.client.impl.auth.AuthenticationSasl.class.getName(), authParams);
-
- PulsarClient client = PulsarClient.builder()
- .serviceUrl("pulsar://my-broker.com:6650")
- .authentication(saslAuth)
- .build();
- ```
-
-> The first two lines in the example above are hard-coded. Alternatively, you can set additional JVM parameters for JAAS and krb5 configuration file when you run the application like below:
+Add new principals for Pulsar proxies.
```shell
-java -cp -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf $APP-jar-with-dependencies.jar $CLASSNAME
+### add Principals for Pulsar Proxy
+sudo /usr/sbin/kadmin.local -q 'addprinc -randkey proxy/{hostname}@{REALM}'
+sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{proxy-keytabname}.keytab proxy/{hostname}@{REALM}"
```
-You must ensure that the operating system user who starts Pulsar client can reach the keytabs configured in the `pulsar_jaas.conf` file and kdc server in the `krb5.conf` file.
+For principals set for brokers and clients, see [here](#create-kerberos-principals).
-#### Configure CLI tools
+### Configure proxies
-If you use a command-line tool (such as `bin/pulsar-client`, `bin/pulsar-perf` and `bin/pulsar-admin`), you need to perform the following steps:
-
-Step 1. Enter the command below to configure your `client.conf`.
-
-```shell
-authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
-authParams={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}
-```
-
-Step 2. Enter the command below to set JVM parameters for the JAAS configuration file and krb5 configuration file with additional options.
+In the `proxy.conf` file, set Kerberos-related configuration.
```shell
--Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf
-```
-
-You can add this at the end of `PULSAR_EXTRA_OPTS` in the file [`pulsar_tools_env.sh`](https://github.com/apache/pulsar/blob/master/conf/pulsar_tools_env.sh),
-or add this line `OPTS="$OPTS -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf "` directly to the CLI tool script.
-
-The meaning of configurations is the same as the meaning of configurations in Java client section.
-
-## Configure Kerberos authentication for proxies
-
-With the above configuration, clients and brokers can do authentication using Kerberos.
-
-A client that connects to Pulsar Proxy is a little different. Pulsar Proxy (as a SASL Server in Kerberos) authenticates Client (as a SASL client in Kerberos) first, and then Pulsar broker authenticates Pulsar Proxy.
-
-Now in comparison with the above configuration between client and broker, we show you how to configure Pulsar Proxy as follows.
-
-### Create principals in Kerberos
-
-You need to add new principals for Pulsar proxy compared with the above configuration. If you already have principals for client and broker, you only need to add the proxy principal here.
+## related to authenticate client.
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
+saslJaasClientAllowedIds=.*client.*
+saslJaasServerSectionName=PulsarProxy
-```shell
-### add Principals for Pulsar Proxy
-sudo /usr/sbin/kadmin.local -q 'addprinc -randkey proxy/{hostname}@{REALM}'
-sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{proxy-keytabname}.keytab proxy/{hostname}@{REALM}"
-### add Principals for broker
-sudo /usr/sbin/kadmin.local -q 'addprinc -randkey broker/{hostname}@{REALM}'
-sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{broker-keytabname}.keytab broker/{hostname}@{REALM}"
-### add Principals for client
-sudo /usr/sbin/kadmin.local -q 'addprinc -randkey client/{hostname}@{REALM}'
-sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{client-keytabname}.keytab client/{hostname}@{REALM}"
+## related to be authenticated by broker
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
+brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarProxy", "serverType":"broker"}
+forwardAuthorizationCredentials=true
```
-### Add a section in JAAS configuration file
+In the above example:
+- The first part relates to the authentication between clients and proxies. In this phase, clients work as SASL clients, while proxies work as SASL servers.
+- The second part relates to the authentication between proxies and brokers. In this phase, proxies work as SASL clients, while brokers work as SASL servers.
-In comparison with the above configuration, add a new section for Pulsar Proxy in the JAAS configuration file.
+### Configure JAAS
-Here is an example named `pulsar_jaas.conf`:
+Add a new section for proxies in the `pulsar_jaas.conf` file. Here is an example:
```conf
- PulsarBroker {
- com.sun.security.auth.module.Krb5LoginModule required
- useKeyTab=true
- storeKey=true
- useTicketCache=false
- keyTab="/etc/security/keytabs/pulsarbroker.keytab"
- principal="broker/localhost@EXAMPLE.COM";
-};
-
PulsarProxy {
com.sun.security.auth.module.Krb5LoginModule required
useKeyTab=true
@@ -262,133 +181,134 @@ Here is an example named `pulsar_jaas.conf`:
keyTab="/etc/security/keytabs/pulsarproxy.keytab"
principal="proxy/localhost@EXAMPLE.COM";
};
-
- PulsarClient {
- com.sun.security.auth.module.Krb5LoginModule required
- useKeyTab=true
- storeKey=true
- useTicketCache=false
- keyTab="/etc/security/keytabs/pulsarclient.keytab"
- principal="client/localhost@EXAMPLE.COM";
-};
```
-### Configure proxy clients
+## Configure Kerberos authentication in Java clients
-Pulsar client configuration is similar to client and broker configuration, except that you need to set `serverType` to `proxy` instead of `broker`, for the reason that you need to do the Kerberos authentication between client and proxy.
+:::note
- ```java
- System.setProperty("java.security.auth.login.config", "/etc/pulsar/pulsar_jaas.conf");
- System.setProperty("java.security.krb5.conf", "/etc/pulsar/krb5.conf");
+Ensure that the operating system user who starts Pulsar clients can access the keytabs configured in the `pulsar_jaas.conf` file and the KDC server configured in the `krb5.conf` file.
- Map<String, String> authParams = Maps.newHashMap();
- authParams.put("saslJaasClientSectionName", "PulsarClient");
- authParams.put("serverType", "proxy"); // ** here is the different **
+:::
- Authentication saslAuth = AuthenticationFactory
- .create(org.apache.pulsar.client.impl.auth.AuthenticationSasl.class.getName(), authParams);
-
- PulsarClient client = PulsarClient.builder()
- .serviceUrl("pulsar://my-broker.com:6650")
- .authentication(saslAuth)
- .build();
- ```
+1. In client applications, include `pulsar-client-auth-sasl` in your project dependency.
-> The first two lines in the example above are hard coded, alternatively, you can set additional JVM parameters for JAAS and krb5 configuration file when you run the application like below:
+ ```xml
+ <dependency>
+ <groupId>org.apache.pulsar</groupId>
+ <artifactId>pulsar-client-auth-sasl</artifactId>
+ <version>${pulsar.version}</version>
+ </dependency>
+ ```
-```shell
-java -cp -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf $APP-jar-with-dependencies.jar $CLASSNAME
-```
+2. Configure the authentication type to use `AuthenticationSasl` and provide the following parameters.
+ - set `saslJaasClientSectionName` to `PulsarClient`;
+ - set `serverType` to `broker`. `serverType` stands for whether this client connects to brokers or proxies. Clients use this parameter to know which server-side principal should be used.
-### Configure proxy service
+ The following is an example of configuring a Java client:
-In the `proxy.conf` file, set Kerberos-related configuration. Here is an example:
+ ```java
+ System.setProperty("java.security.auth.login.config", "/etc/pulsar/pulsar_jaas.conf");
+ System.setProperty("java.security.krb5.conf", "/etc/pulsar/krb5.conf");
-```shell
-## related to authenticate client.
-authenticationEnabled=true
-authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
-saslJaasClientAllowedIds=.*client.*
-saslJaasServerSectionName=PulsarProxy
+ Map<String, String> authParams = Maps.newHashMap();
+ authParams.put("saslJaasClientSectionName", "PulsarClient");
+ authParams.put("serverType", "broker");
-## related to be authenticated by broker
-brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
-brokerClientAuthenticationParameters={"saslJaasClientSectionName":"PulsarProxy", "serverType":"broker"}
-forwardAuthorizationCredentials=true
-```
+ Authentication saslAuth = AuthenticationFactory
+ .create(org.apache.pulsar.client.impl.auth.AuthenticationSasl.class.getName(), authParams);
+
+ PulsarClient client = PulsarClient.builder()
+ .serviceUrl("pulsar://my-broker.com:6650")
+ .authentication(saslAuth)
+ .build();
+ ```
-The first part relates to authenticating between clients and Pulsar proxies. In this phase, client works as SASL client, while Pulsar Proxy works as SASL server.
+ :::note
+
+ - To configure clients for proxies, you need to set `serverType` to `proxy` instead of `broker`.
+ - The first two lines in the above example are hard-coded. Alternatively, you can set additional JVM parameters for `pulsar_jaas.conf` and `krb5.conf` files when you run the application like below:
-The second part relates to authenticating between Pulsar proxies and Pulsar brokers. In this phase, Pulsar Proxy works as SASL client, while Pulsar broker works as SASL server.
+ ```shell
+ java -cp -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf $APP-jar-with-dependencies.jar $CLASSNAME
+ ```
-### Configure brokers
+ :::
-The broker-side configuration file is the same as the above `broker.conf`, you do not need special configurations for Pulsar Proxy.
+## Configure Kerberos authentication in CLI tools
-```conf
-authenticationEnabled=true
-authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderSasl
-saslJaasClientAllowedIds=.*client.*
-saslJaasServerSectionName=PulsarBroker
-```
+[Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](/tools/pulsar-admin/), [`pulsar-perf`](reference-cli-tools.md#pulsar-perf), and [`pulsar-client`](reference-cli-tools.md#pulsar-client) use the `conf/client.conf` file in a Pulsar installation.
-## Authorization and role token
+When using command-line tools, you need to perform the following steps:
-For Kerberos authentication, we usually use the authenticated principal as the role token for Pulsar authorization. For more information on authorization in Pulsar, see [security authorization](security-authorization.md).
+1. Configure the `conf/client.conf` file.
-If you enable 'authorizationEnabled', you need to set `superUserRoles` in `broker.conf` that corresponds to the name registered in kdc.
+ ```shell
+ authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationSasl
+ authParams={"saslJaasClientSectionName":"PulsarClient", "serverType":"broker"}
+ ```
-For example:
+2. Set JVM parameters for the `pulsar_jaas.conf` file and `krb5.conf` files with additional options.
-```bash
-superUserRoles=client/{clientIp}@EXAMPLE.COM
-```
+ ```shell
+ -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf
+ ```
+
+ You can add this at the end of `PULSAR_EXTRA_OPTS` in the file [`pulsar_tools_env.sh`](https://github.com/apache/pulsar/blob/master/conf/pulsar_tools_env.sh), or add this line `OPTS="$OPTS -Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf -Djava.security.krb5.conf=/etc/pulsar/krb5.conf"` directly to the CLI tool script. The meaning of configurations is the same as the meaning of configurations in Java client section.
## Configure Kerberos authentication between ZooKeeper and broker
-Pulsar broker acts as a Kerberos client when you authenticate with Zookeeper. According to [ZooKeeper document](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Client-Server+mutual+authentication), you need these settings in `conf/zookeeper.conf`:
+Pulsar broker acts as a Kerberos client when authenticating with Zookeeper.
-```conf
-authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
-requireClientAuthScheme=sasl
-```
+1. Add the settings in `conf/zookeeper.conf`.
-Enter the following commands to add a section of `Client` configurations in the file `pulsar_jaas.conf`, which Pulsar broker uses:
+ ```conf
+ authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
+ requireClientAuthScheme=sasl
+ ```
-```
- Client {
- com.sun.security.auth.module.Krb5LoginModule required
- useKeyTab=true
- storeKey=true
- useTicketCache=false
- keyTab="/etc/security/keytabs/pulsarbroker.keytab"
- principal="broker/localhost@EXAMPLE.COM";
-};
-```
+2. Enter the following commands to add a section of `Client` configurations in `pulsar_jaas.conf` that Pulsar broker uses:
-In this setting, the principal of Pulsar broker and keyTab file indicates the role of brokers when you authenticate with ZooKeeper.
+ ```
+ Client {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarbroker.keytab"
+ principal="broker/localhost@EXAMPLE.COM";
+ };
+ ```
-## Configure Kerberos authentication between BookKeeper and broker
+ In this setting, the principal of Pulsar broker and keytab file indicates the role of brokers when you authenticate with ZooKeeper.
-Pulsar broker acts as a Kerberos client when you authenticate with Bookie. According to [BookKeeper document](https://bookkeeper.apache.org/docs/next/security/sasl/), you need to add `bookkeeperClientAuthenticationPlugin` parameter in `broker.conf`:
+For more information, see [ZooKeeper document](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Client-Server+mutual+authentication)
-```conf
-bookkeeperClientAuthenticationPlugin=org.apache.bookkeeper.sasl.SASLClientProviderFactory
-```
+## Configure Kerberos authentication for BookKeeper and broker
-In this setting, `SASLClientProviderFactory` creates a BookKeeper SASL client in a broker, and the broker uses the created SASL client to authenticate with a Bookie node.
+Pulsar broker acts as a Kerberos client when authenticating with Bookie.
-Enter the following commands to add a section of `BookKeeper` configurations in the `pulsar_jaas.conf` that Pulsar broker uses:
+1. Add the `bookkeeperClientAuthenticationPlugin` parameter in `broker.conf`.
-```conf
- BookKeeper {
- com.sun.security.auth.module.Krb5LoginModule required
- useKeyTab=true
- storeKey=true
- useTicketCache=false
- keyTab="/etc/security/keytabs/pulsarbroker.keytab"
- principal="broker/localhost@EXAMPLE.COM";
-};
-```
+ ```conf
+ bookkeeperClientAuthenticationPlugin=org.apache.bookkeeper.sasl.SASLClientProviderFactory
+ ```
+
+ `SASLClientProviderFactory` creates a BookKeeper SASL client in a broker, and the broker uses the created SASL client to authenticate with a Bookie node.
+
+2. Add a section of `BookKeeper` configurations in the `pulsar_jaas.conf` file that broker/proxy uses.
+
+ ```conf
+ BookKeeper {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ useTicketCache=false
+ keyTab="/etc/security/keytabs/pulsarbroker.keytab"
+ principal="broker/localhost@EXAMPLE.COM";
+ };
+ ```
+
+ In this setting, the principal of Pulsar broker and keytab file indicates the role of brokers when you authenticate with Bookie.
-In this setting, the principal of Pulsar broker and keytab file indicates the role of brokers when you authenticate with Bookie.
+For more information, see [BookKeeper document](https://bookkeeper.apache.org/docs/next/security/sasl/).
\ No newline at end of file
diff --git a/site2/website-next/docs/security-oauth2.md b/site2/website-next/docs/security-oauth2.md
index ddb7bb4fc07..abedc3bba57 100644
--- a/site2/website-next/docs/security-oauth2.md
+++ b/site2/website-next/docs/security-oauth2.md
@@ -1,74 +1,34 @@
---
id: security-oauth2
-title: Client authentication using OAuth 2.0 access tokens
+title: Authentication using OAuth 2.0 access tokens
sidebar_label: "Authentication using OAuth 2.0 access tokens"
---
-Pulsar supports authenticating clients using OAuth 2.0 access tokens. You can use OAuth 2.0 access tokens to identify a Pulsar client and associate the Pulsar client with some "principal" (or "role"), which is permitted to do some actions, such as publishing messages to a topic or consuming messages from a topic.
-
-This module is used to support the [Pulsar client authentication plugin](security-extending.md#client-authentication-plugin) for OAuth 2.0. After communicating with the OAuth 2.0 server, the Pulsar client gets an `access token` from the OAuth 2.0 server, and passes this `access token` to the Pulsar broker to do the authentication. The broker can use the `org.apache.pulsar.broker.authentication.AuthenticationProviderToken`. Or, you can add your own `AuthenticationProvider` to make it with [...]
-
-## Authentication provider configuration
-
-This library allows you to authenticate the Pulsar client by using an access token that is obtained from an OAuth 2.0 authorization service, which acts as a _token issuer_.
-
-### Authentication types
-
-The authentication type determines how to obtain an access token through an OAuth 2.0 authorization flow.
-
-:::note
-
-Currently, the Pulsar Java client only supports the `client_credentials` authentication type.
-
-:::
-
-#### Client credentials
-
-The following table lists parameters supported for the `client credentials` authentication type.
-
-| Parameter | Description | Example | Required or not |
-| --- | --- | --- | --- |
-| `type` | OAuth 2.0 authentication type. | `client_credentials` (default) | Optional |
-| `issuerUrl` | URL of the authentication provider which allows the Pulsar client to obtain an access token | `https://accounts.google.com` | Required |
-| `privateKey` | URL to a JSON credentials file | Support the following pattern formats: <br /> <li> `file:///path/to/file` </li><li>`file:/path/to/file` </li><li> `data:application/json;base64,<base64-encoded value>` </li>| Required |
-| `audience` | An OAuth 2.0 "resource server" identifier for the Pulsar cluster | `https://broker.example.com` | Optional |
-| `scope` | Scope of an access request. <br />For more information, see [access token scope](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3). | api://pulsar-cluster-1/.default | Optional |
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
-The credentials file contains service account credentials used with the client authentication type. The following shows an example of a credentials file `credentials_file.json`.
+Pulsar supports authenticating clients using OAuth 2.0 access tokens. Using an access token obtained from an OAuth 2.0 authorization service (acts as a token issuer), you can identify a Pulsar client and associate it with a "principal" (or "role") that is permitted to do some actions, such as publishing messages to a topic or consuming messages from a topic.
-```json
-{
- "type": "client_credentials",
- "client_id": "d9ZyX97q1ef8Cr81WHVC4hFQ64vSlDK3",
- "client_secret": "on1uJ...k6F6R",
- "client_email": "1234567890-abcdefghijklmnopqrstuvwxyz@developer.gserviceaccount.com",
- "issuer_url": "https://accounts.google.com"
-}
-```
+After communicating with the OAuth 2.0 server, the Pulsar client gets an access token from the server and passes this access token to brokers for authentication. By default, brokers can use the `org.apache.pulsar.broker.authentication.AuthenticationProviderToken`. Alternatively, you can customize the value of `AuthenticationProvider`.
-In the above example, the authentication type is set to `client_credentials` by default. And the fields "client_id" and "client_secret" are required.
+## Enable OAuth2 authentication on brokers/proxies
-### Typical original OAuth2 request mapping
+To configure brokers to authenticate clients using OAuth2， add the following parameters to the `conf/broker.conf` and `conf/proxy.conf` file.
-The following shows a typical original OAuth2 request, which is used to obtain the access token from the OAuth2 server.
-
-```bash
-curl --request POST \
- --url https://dev-kt-aa9ne.us.auth0.com/oauth/token \
- --header 'content-type: application/json' \
- --data '{
- "client_id":"Xd23RHsUnvUlP7wchjNYOaIfazgeHd9x",
- "client_secret":"rT7ps7WY8uhdVuBTKWZkttwLdQotmdEliaM5rLfmgNibvqziZ-g07ZH52N_poGAb",
- "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/",
- "grant_type":"client_credentials"}'
+```properties
+# Configuration to enable authentication
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
+tokenPublicKey=/path/to/publicKey
+# Authentication settings of the broker itself. Used when the broker connects to other brokers,
+# either in same or other clusters
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2
+brokerClientAuthenticationParameters={"privateKey":"/path/to/privateKey",\
+ "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/","issuerUrl":"https://dev-kt-aa9ne.us.auth0.com"}
```
-In the above example, the mapping relationship is shown as below.
-
-- The `issuerUrl` parameter in this plugin is mapped to `--url https://dev-kt-aa9ne.us.auth0.com`.
-- The `privateKey` file parameter in this plugin should at least contains the `client_id` and `client_secret` fields.
-- The `audience` parameter in this plugin is mapped to `"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"`. This field is only used by some identity providers.
-
## Configure OAuth2 authentication in Pulsar clients
You can use the OAuth2 authentication provider with the following Pulsar clients.
@@ -204,28 +164,15 @@ client, err := pulsar.NewClient(pulsar.ClientOptions{
</Tabs>
````
-## Broker configuration
-To enable OAuth2 authentication in brokers, add the following parameters to the `broker.conf` or `standalone.conf` file.
-
-```properties
-# Configuration to enable authentication
-authenticationEnabled=true
-authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
-tokenPublicKey=/path/to/publicKey
-# Authentication settings of the broker itself. Used when the broker connects to other brokers,
-# either in same or other clusters
-brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2
-brokerClientAuthenticationParameters={"privateKey":"/path/to/privateKey",\
- "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/","issuerUrl":"https://dev-kt-aa9ne.us.auth0.com"}
-```
-
## Configure OAuth2 authentication in CLI tools
This section describes how to use Pulsar CLI tools to connect a cluster through OAuth2 authentication plugin.
-### pulsar-admin
-
-This example shows how to use pulsar-admin to connect to a cluster through OAuth2 authentication plugin.
+````mdx-code-block
+<Tabs groupId="lang-choice"
+ defaultValue="pulsar-admin"
+ values={[{"label":"pulsar-admin","value":"pulsar-admin"},{"label":"pulsar-client","value":"pulsar-client"},{"label":"pulsar-perf","value":"pulsar-perf"}]}>
+<TabItem value="pulsar-admin">
```shell
bin/pulsar-admin --admin-url https://streamnative.cloud:443 \
@@ -236,12 +183,8 @@ bin/pulsar-admin --admin-url https://streamnative.cloud:443 \
tenants list
```
-Set the `admin-url` parameter to the Web service URL. A Web service URL is a combination of the protocol, hostname and port ID, such as `pulsar://localhost:6650`.
-Set the `privateKey`, `issuerUrl`, and `audience` parameters to the values based on the configuration in the key file. For details, see [authentication types](#authentication-types).
-
-### pulsar-client
-
-This example shows how to use pulsar-client to connect to a cluster through OAuth2 authentication plugin.
+</TabItem>
+<TabItem value="pulsar-client">
```shell
bin/pulsar-client \
@@ -253,12 +196,8 @@ bin/pulsar-client \
produce test-topic -m "test-message" -n 10
```
-Set the `admin-url` parameter to the Web service URL. A Web service URL is a combination of the protocol, hostname and port ID, such as `pulsar://localhost:6650`.
-Set the `privateKey`, `issuerUrl`, and `audience` parameters to the values based on the configuration in the key file. For details, see [authentication types](#authentication-types).
-
-### pulsar-perf
-
-This example shows how to use pulsar-perf to connect to a cluster through OAuth2 authentication plugin.
+</TabItem>
+<TabItem value="pulsar-perf">
```shell
bin/pulsar-perf produce --service-url pulsar+ssl://streamnative.cloud:6651 \
@@ -269,5 +208,53 @@ bin/pulsar-perf produce --service-url pulsar+ssl://streamnative.cloud:6651 \
-r 1000 -s 1024 test-topic
```
-Set the `admin-url` parameter to the Web service URL. A Web service URL is a combination of the protocol, hostname and port ID, such as `pulsar://localhost:6650`.
-Set the `privateKey`, `issuerUrl`, and `audience` parameters to the values based on the configuration in the key file. For details, see [authentication types](#authentication-types).
+</TabItem>
+</Tabs>
+````
+
+* Set the `admin-url` parameter to the Web service URL. A Web service URL is a combination of the protocol, hostname and port ID, such as `pulsar://localhost:6650`.
+* Set the `privateKey`, `issuerUrl`, and `audience` parameters to the values based on the configuration in the key file. For details, see [authentication types](#authentication-types).
+
+#### Authentication types
+
+Currently, Pulsar clients only support the `client_credentials` authentication type. The authentication type determines how to obtain an access token through an OAuth 2.0 authorization service.
+
+The following table outlines the parameters of the `client_credentials` authentication type.
+
+| Parameter | Description | Example | Required or not |
+| --- | --- | --- | --- |
+| `type` | OAuth 2.0 authentication type. | `client_credentials` (default) | Optional |
+| `issuerUrl` | The URL of the authentication provider which allows the Pulsar client to obtain an access token. | `https://accounts.google.com` | Required |
+| `privateKey` | The URL to the JSON credentials file. | Support the following pattern formats: <br /> <li> `file:///path/to/file` </li><li>`file:/path/to/file` </li><li> `data:application/json;base64,<base64-encoded value>` </li>| Required |
+| `audience` | The OAuth 2.0 "resource server" identifier for a Pulsar cluster. | `https://broker.example.com` | Optional |
+| `scope` | The scope of an access request. <br />For more information, see [access token scope](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3). | api://pulsar-cluster-1/.default | Optional |
+
+The credentials file `credentials_file.json` contains the service account credentials used with the client authentication type. The following is an example of the credentials file. The authentication type is set to `client_credentials` by default. And the fields "client_id" and "client_secret" are required.
+
+```json
+{
+ "type": "client_credentials",
+ "client_id": "d9ZyX97q1ef8Cr81WHVC4hFQ64vSlDK3",
+ "client_secret": "on1uJ...k6F6R",
+ "client_email": "1234567890-abcdefghijklmnopqrstuvwxyz@developer.gserviceaccount.com",
+ "issuer_url": "https://accounts.google.com"
+}
+```
+
+The following is an example of a typical original OAuth2 request, which is used to obtain an access token from the OAuth2 server.
+
+```bash
+curl --request POST \
+ --url https://dev-kt-aa9ne.us.auth0.com/oauth/token \
+ --header 'content-type: application/json' \
+ --data '{
+ "client_id":"Xd23RHsUnvUlP7wchjNYOaIfazgeHd9x",
+ "client_secret":"rT7ps7WY8uhdVuBTKWZkttwLdQotmdEliaM5rLfmgNibvqziZ-g07ZH52N_poGAb",
+ "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/",
+ "grant_type":"client_credentials"}'
+```
+
+In the above example, the mapping relationship is shown below.
+- The `issuerUrl` parameter is mapped to `--url https://dev-kt-aa9ne.us.auth0.com`.
+- The `privateKey` parameter should contain the `client_id` and `client_secret` fields at least.
+- The `audience` parameter is mapped to `"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"`. This field is only used by some identity providers.
diff --git a/site2/website-next/docs/security-overview.md b/site2/website-next/docs/security-overview.md
index 37d96d65b01..917b7ac7af2 100644
--- a/site2/website-next/docs/security-overview.md
+++ b/site2/website-next/docs/security-overview.md
@@ -21,28 +21,41 @@ Encryption ensures that if an attacker gets access to your data, the attacker ca
**What's next?**
-* To configure end-to-end encryption, see [End-to-end encryption](security-encryption.md) for more details.
-* To configure transport layer encryption, see [TLS encryption](security-tls-transport.md) for more details.
+- To configure end-to-end encryption, see [End-to-end encryption](security-encryption.md) for more details.
+- To configure transport layer encryption, see [TLS encryption](security-tls-transport.md) for more details.
## Authentication
-Authentication is the process of verifying the identity of clients. In Pulsar, the authentication provider is responsible for properly identifying clients and associating the clients with role tokens. If you only enable authentication, an authenticated role token can access all resources in the cluster.
+Authentication is the process of verifying the identity of clients. In Pulsar, the authentication provider is responsible for properly identifying clients and associating them with role tokens. Note that if you only enable authentication, an authenticated role token can access all resources in the cluster.
-Pulsar supports a pluggable authentication mechanism, and Pulsar clients use this mechanism to authenticate with brokers and proxies.
+**How it works in Pulsar**
-Pulsar broker validates the authentication credentials when a connection is established. After the initial connection is authenticated, the "principal" token is stored for authorization though the connection is not re-authenticated. The broker periodically checks the expiration status of every `ServerCnx` object. By default, the `authenticationRefreshCheckSeconds` is set to 60s. When the authentication is expired, the broker re-authenticates the connection. If the re-authentication fails [...]
+Pulsar provides a pluggable authentication framework, and Pulsar brokers/proxies use this mechanism to authenticate clients.
-Pulsar broker supports learning whether a particular client supports authentication refreshing. If a client supports authentication refreshing and the credential is expired, the authentication provider calls the `refreshAuthentication` method to initiate the refreshing process. If a client does not support authentication refreshing and the credential is expired, the broker disconnects the client.
+The way how each client passes its authentication data to brokers varies depending on the protocols it uses. Brokers validate the authentication credentials when a connection is established and check whether the authentication data is expired.
+- When using HTTP/HTTPS protocol for cluster management, each client passes the authentication data based on the HTTP/HTTPS request header, and brokers check the data upon request.
+- When using [Pulsar protocol](developing-binary-protocol.md) for productions/consumptions, each client passes the authentication data by sending the `CommandConnect` command when connecting to brokers. Brokers cache the data and periodically check whether the data has expired and learn whether the client supports authentication refreshing. By default, the `authenticationRefreshCheckSeconds` is set to 60s.
+ - If a client supports authentication refreshing and the credential is expired, brokers send the `CommandAuthChallenge` command to exchange the authentication data with the client. If the next check finds that the previous authentication exchange has not been returned, brokers disconnect the client.
+ - If a client does not support authentication refreshing and the credential is expired, brokers disconnect the client.
+
+:::note
+
+When you use proxies between clients and brokers, brokers only authenticate proxies (known as **self-authentication**) by default. To forward the authentication data from clients to brokers for client authentication (known as **original authentication**), you need to:
+1. Set `forwardAuthorizationCredentials` to `true` in the `conf/proxy.conf` file.
+2. Set `authenticateOriginalAuthData` to `true` in the `conf/broker.conf` file, which ensures that brokers recheck the client authentication.
+
+:::
**What's next?**
-Pulsar supports the following authentication providers, and you can configure multiple authentication providers.
-- [TLS authentication](security-tls-authentication.md)
-- [Athenz authentication](security-athenz.md)
-- [Kerberos authentication](security-kerberos.md)
-- [JSON Web Token (JWT) authentication](security-jwt.md)
-- [OAuth 2.0 authentication](security-oauth2.md)
-- [HTTP basic authentication](security-basic-auth.md)
+- To configure built-in authentication plugins, read:
+ - [TLS authentication](security-tls-authentication.md)
+ - [Athenz authentication](security-athenz.md)
+ - [Kerberos authentication](security-kerberos.md)
+ - [JSON Web Token (JWT) authentication](security-jwt.md)
+ - [OAuth 2.0 authentication](security-oauth2.md)
+ - [HTTP basic authentication](security-basic-auth.md)
+- To customize an authentication plugin, read [extended authentication](security-extending).
:::note
diff --git a/site2/website-next/docs/security-tls-authentication.md b/site2/website-next/docs/security-tls-authentication.md
index 4f907933abe..7b86ca8e906 100644
--- a/site2/website-next/docs/security-tls-authentication.md
+++ b/site2/website-next/docs/security-tls-authentication.md
@@ -102,12 +102,12 @@ brokerClientAuthenticationParameters=tlsCertFile:/path/to/proxy.cert.pem,tlsKeyF
## Configure TLS authentication in Pulsar clients
-When you use TLS authentication, client connects via TLS transport. You need to configure the client to use `https://` and 8443 port for the web service URL, `pulsar+ssl://` and 6651 port for the broker service URL.
+When using TLS authentication, clients connect via TLS transport. You need to configure clients to use `https://` and the `8443` port for the web service URL, use `pulsar+ssl://` and the `6651` port for the broker service URL.
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
- values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"C++","value":"C++"},{"label":"Node.js","value":"Node.js"},{"label":"C#","value":"C#"}]}>
+ values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"C++","value":"C++"},{"label":"Node.js","value":"Node.js"},{"label":"Go","value":"Go"},{"label":"C#","value":"C#"}]}>
<TabItem value="Java">
```java
@@ -172,6 +172,17 @@ const Pulsar = require('pulsar-client');
})();
```
+</TabItem>
+<TabItem value="Go">
+
+```go
+client, err := pulsar.NewClient(ClientOptions{
+ URL: "pulsar+ssl://broker.example.com:6651/",
+ TLSTrustCertsFilePath: "/path/to/ca.cert.pem",
+ Authentication: pulsar.NewAuthenticationTLS("/path/to/my-role.cert.pem", "/path/to/my-role.key-pk8.pem"),
+ })
+```
+
</TabItem>
<TabItem value="C#">
diff --git a/site2/website-next/versioned_docs/version-2.10.x/client-libraries-cpp.md b/site2/website-next/versioned_docs/version-2.10.x/client-libraries-cpp.md
index e8bcfa0abe1..e88df87b654 100644
--- a/site2/website-next/versioned_docs/version-2.10.x/client-libraries-cpp.md
+++ b/site2/website-next/versioned_docs/version-2.10.x/client-libraries-cpp.md
@@ -5,341 +5,111 @@ sidebar_label: "C++"
original_id: client-libraries-cpp
---
-You can use Pulsar C++ client to create Pulsar producers and consumers in C++.
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
-All the methods in producer, consumer, and reader of a C++ client are thread-safe.
+You can use a Pulsar C++ client to create producers, consumers, and readers.
-## Supported platforms
+All the methods in producer, consumer, and reader of a C++ client are thread-safe. You can read the [API docs](/api/cpp) for the C++ client.
-Pulsar C++ client is supported on **Linux** ,**macOS** and **Windows** platforms.
+## Installation
-[Doxygen](http://www.doxygen.nl/)-generated API docs for the C++ client are available [here](/api/cpp).
+Use one of the following methods to install a Pulsar C++ client.
+### Brew
-## Linux
-
-:::note
-
-You can choose one of the following installation methods based on your needs: Compilation, Install RPM or Install Debian.
-
-:::
-
-### Compilation
-
-#### System requirements
-
-You need to install the following components before using the C++ client:
-
-* [CMake](https://cmake.org/)
-* [Boost](http://www.boost.org/)
-* [Protocol Buffers](https://developers.google.com/protocol-buffers/) >= 3
-* [libcurl](https://curl.se/libcurl/)
-* [Google Test](https://github.com/google/googletest)
-
-1. Clone the Pulsar repository.
-
-```shell
-
-$ git clone https://github.com/apache/pulsar
-
-```
-
-2. Install all necessary dependencies.
-
-```shell
-
-$ apt-get install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \
- libprotobuf-dev protobuf-compiler libboost-all-dev google-mock libgtest-dev libjsoncpp-dev
-
-```
-
-3. Compile and install [Google Test](https://github.com/google/googletest).
-
-```shell
-
-# libgtest-dev version is 1.18.0 or above
-$ cd /usr/src/googletest
-$ sudo cmake .
-$ sudo make
-$ sudo cp ./googlemock/libgmock.a ./googlemock/gtest/libgtest.a /usr/lib/
-
-# less than 1.18.0
-$ cd /usr/src/gtest
-$ sudo cmake .
-$ sudo make
-$ sudo cp libgtest.a /usr/lib
-
-$ cd /usr/src/gmock
-$ sudo cmake .
-$ sudo make
-$ sudo cp libgmock.a /usr/lib
-
-```
-
-4. Compile the Pulsar client library for C++ inside the Pulsar repository.
-
-```shell
-
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
-
-```
-
-After you install the components successfully, the files `libpulsar.so` and `libpulsar.a` are in the `lib` folder of the repository. The tools `perfProducer` and `perfConsumer` are in the `perf` directory.
-
-### Install Dependencies
-
-> Since 2.1.0 release, Pulsar ships pre-built RPM and Debian packages. You can download and install those packages directly.
-
-After you download and install RPM or DEB, the `libpulsar.so`, `libpulsarnossl.so`, `libpulsar.a`, and `libpulsarwithdeps.a` libraries are in your `/usr/lib` directory.
-
-By default, they are built in code path `${PULSAR_HOME}/pulsar-client-cpp`. You can build with the command below.
-
- `cmake . -DBUILD_TESTS=OFF -DLINK_STATIC=ON && make pulsarShared pulsarSharedNossl pulsarStatic pulsarStaticWithDeps -j 3`.
-
-These libraries rely on some other libraries. If you want to get detailed version of dependencies, see [RPM](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/rpm/Dockerfile) or [DEB](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/deb/Dockerfile) files.
-
-1. `libpulsar.so` is a shared library, containing statically linked `boost` and `openssl`. It also dynamically links all other necessary libraries. You can use this Pulsar library with the command below.
+Use [Homebrew](http://brew.sh/) to install the latest tagged version with the library and headers:
```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.so -I/usr/local/ssl/include
-
-```
-
-2. `libpulsarnossl.so` is a shared library, similar to `libpulsar.so` except that the libraries `openssl` and `crypto` are dynamically linked. You can use this Pulsar library with the command below.
-
-```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarnossl.so -lssl -lcrypto -I/usr/local/ssl/include -L/usr/local/ssl/lib
-
+brew install libpulsar
```
-3. `libpulsar.a` is a static library. You need to load dependencies before using this library. You can use this Pulsar library with the command below.
+### Deb
-```bash
+1. Download any one of the Deb packages:
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.a -lssl -lcrypto -ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib -lboost_system -lboost_regex -lcurl -lprotobuf -lzstd -lz
-
-```
-
-4. `libpulsarwithdeps.a` is a static library, based on `libpulsar.a`. It is archived in the dependencies of `libboost_regex`, `libboost_system`, `libcurl`, `libprotobuf`, `libzstd` and `libz`. You can use this Pulsar library with the command below.
+<Tabs>
+<TabItem value="client">
```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarwithdeps.a -lssl -lcrypto -ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib
-
+wget @pulsar:deb:client@
```
-The `libpulsarwithdeps.a` does not include library openssl related libraries `libssl` and `libcrypto`, because these two libraries are related to security. It is more reasonable and easier to use the versions provided by the local system to handle security issues and upgrade libraries.
-
-### Install RPM
+This package contains shared libraries `libpulsar.so` and `libpulsarnossl.so`.
-1. Download an RPM package from the links in the table.
-
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:dist_rpm:client@) | [asc](@pulsar:dist_rpm:client@.asc), [sha512](@pulsar:dist_rpm:client@.sha512) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) | [asc](@pulsar:dist_rpm:client-debuginfo@.asc), [sha512](@pulsar:dist_rpm:client-debuginfo@.sha512) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) | [asc](@pulsar:dist_rpm:client-devel@.asc), [sha512](@pulsar:dist_rpm:client-devel@.sha512) |
-
-2. Install the package using the following command.
+</TabItem>
+<TabItem value="client-devel">
```bash
-
-$ rpm -ivh apache-pulsar-client*.rpm
-
-```
-
-After you install RPM successfully, Pulsar libraries are in the `/usr/lib` directory, for example：
-
-```bash
-
-lrwxrwxrwx 1 root root 18 Dec 30 22:21 libpulsar.so -> libpulsar.so.2.9.1
-lrwxrwxrwx 1 root root 23 Dec 30 22:21 libpulsarnossl.so -> libpulsarnossl.so.2.9.1
-
+wget @pulsar:deb:client-devel@
```
-:::note
+This package contains static libraries: `libpulsar.a`, `libpulsarwithdeps.a` and C/C++ headers.
-If you get the error that `libpulsar.so: cannot open shared object file: No such file or directory` when starting Pulsar client, you may need to run `ldconfig` first.
+</TabItem>
+</Tabs>
-:::
-
-2. Install the GCC and g++ using the following command, otherwise errors would occur in installing Node.js.
+2. Install the package using the following command:
```bash
-
-$ sudo yum -y install gcc automake autoconf libtool make
-$ sudo yum -y install gcc-c++
-
+apt install ./apache-pulsar-client*.deb
```
-### Install Debian
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
-1. Download a Debian package from the links in the table.
+### RPM
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:deb:client@) | [asc](@pulsar:dist_deb:client@.asc), [sha512](@pulsar:dist_deb:client@.sha512) |
-| [client-devel](@pulsar:deb:client-devel@) | [asc](@pulsar:dist_deb:client-devel@.asc), [sha512](@pulsar:dist_deb:client-devel@.sha512) |
+1. Download any one of the RPM packages:
-2. Install the package using the following command.
+<Tabs>
+<TabItem value="client">
```bash
-
-$ apt install ./apache-pulsar-client*.deb
-
+wget @pulsar:dist_rpm:client@
```
-After you install DEB successfully, Pulsar libraries are in the `/usr/lib` directory.
-
-### Build
+This package contains shared libraries: `libpulsar.so` and `libpulsarnossl.so`.
-> If you want to build RPM and Debian packages from the latest master, follow the instructions below. You should run all the instructions at the root directory of your cloned Pulsar repository.
-
-There are recipes that build RPM and Debian packages containing a
-statically linked `libpulsar.so` / `libpulsarnossl.so` / `libpulsar.a` / `libpulsarwithdeps.a` with all required dependencies.
-
-To build the C++ library packages, you need to build the Java packages first.
-
-```shell
-
-mvn install -DskipTests
-
-```
-
-#### RPM
-
-To build the RPM inside a Docker container, use the command below. The RPMs are in the `pulsar-client-cpp/pkg/rpm/RPMS/x86_64/` path.
-
-```shell
-
-pulsar-client-cpp/pkg/rpm/docker-build-rpm.sh
-
-```
-
-| Package name | Content |
-|-----|-----|
-| pulsar-client | Shared library `libpulsar.so` and `libpulsarnossl.so` |
-| pulsar-client-devel | Static library `libpulsar.a`, `libpulsarwithdeps.a`and C++ and C headers |
-| pulsar-client-debuginfo | Debug symbols for `libpulsar.so` |
-
-#### Debian
-
-To build Debian packages, enter the following command.
-
-```shell
-
-pulsar-client-cpp/pkg/deb/docker-build-deb.sh
-
-```
-
-Debian packages are created in the `pulsar-client-cpp/pkg/deb/BUILD/DEB/` path.
-
-| Package name | Content |
-|-----|-----|
-| pulsar-client | Shared library `libpulsar.so` and `libpulsarnossl.so` |
-| pulsar-client-dev | Static library `libpulsar.a`, `libpulsarwithdeps.a` and C++ and C headers |
-
-## MacOS
-
-### Compilation
-
-1. Clone the Pulsar repository.
-
-```shell
-
-$ git clone https://github.com/apache/pulsar
-
-```
-
-2. Install all necessary dependencies.
-
-```shell
-
-# OpenSSL installation
-$ brew install openssl
-$ export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/
-$ export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/
-
-# Protocol Buffers installation
-$ brew install protobuf boost boost-python log4cxx
-# If you are using python3, you need to install boost-python3
-
-# Google Test installation
-$ git clone https://github.com/google/googletest.git
-$ cd googletest
-$ git checkout release-1.12.1
-$ cmake .
-$ make install
-
-```
-
-3. Compile the Pulsar client library in the repository that you cloned.
-
-```shell
-
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
-
-```
-
-### Install `libpulsar`
-
-Pulsar releases are available in the [Homebrew](https://brew.sh/) core repository. You can install the C++ client library with the following command. The package is installed with the library and headers.
-
-```shell
-
-brew install libpulsar
+</TabItem>
+<TabItem value="client-debuginfo">
+```bash
+wget @pulsar:dist_rpm:client-debuginfo@
```
-## Windows (64-bit)
-
-### Compilation
-
-1. Clone the Pulsar repository.
+This package contains debug symbols for `libpulsar.so`.
-```shell
-
-$ git clone https://github.com/apache/pulsar
+</TabItem>
+<TabItem value="client-devel">
+```bash
+wget @pulsar:dist_rpm:client-devel@
```
-2. Install all necessary dependencies.
+This package contains static libraries: `libpulsar.a`, `libpulsarwithdeps.a` and C/C++ headers.
-```shell
+</TabItem>
+</Tabs>
-cd ${PULSAR_HOME}/pulsar-client-cpp
-vcpkg install --feature-flags=manifests --triplet x64-windows
+2. Install the package using the following command:
+```bash
+rpm -ivh apache-pulsar-client*.rpm
```
-3. Build C++ libraries.
-
-```shell
-
-cmake -B ./build -A x64 -DBUILD_PYTHON_WRAPPER=OFF -DBUILD_TESTS=OFF -DVCPKG_TRIPLET=x64-windows -DCMAKE_BUILD_TYPE=Release -S .
-cmake --build ./build --config Release
-
-```
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
-> **NOTE**
->
-> 1. For Windows 32-bit, you need to use `-A Win32` and `-DVCPKG_TRIPLET=x86-windows`.
-> 2. For MSVC Debug mode, you need to replace `Release` with `Debug` for both `CMAKE_BUILD_TYPE` variable and `--config` option.
+:::note
-4. Client libraries are available in the following places.
+If you get an error like "libpulsar.so: cannot open shared object file: No such file or directory" when starting a Pulsar client, you need to run `ldconfig` first.
-```
+:::
-${PULSAR_HOME}/pulsar-client-cpp/build/lib/Release/pulsar.lib
-${PULSAR_HOME}/pulsar-client-cpp/build/lib/Release/pulsar.dll
+### Source
-```
+For how to build Pulsar C++ client on different platforms from source code, see [compliation](https://github.com/apache/pulsar-client-cpp#compilation).
## Connection URLs
@@ -353,7 +123,7 @@ pulsar://localhost:6650
```
-In a Pulsar cluster in production, the URL looks as follows.
+In a Pulsar cluster in production, the URL looks as follows.
```http
@@ -504,7 +274,7 @@ producerConf.setLazyStartPartitionedProducers(true);
### Enable chunking
-Message [chunking](concepts-messaging.md#chunking) enables Pulsar to process large payload messages by splitting the message into chunks at the producer side and aggregating chunked messages at the consumer side.
+Message [chunking](concepts-messaging.md#chunking) enables Pulsar to process large payload messages by splitting the message into chunks at the producer side and aggregating chunked messages at the consumer side.
The message chunking feature is OFF by default. The following is an example about how to enable message chunking when creating a producer.
@@ -624,7 +394,7 @@ int main() {
### Configure chunking
-You can limit the maximum number of chunked messages a consumer maintains concurrently by configuring the `setMaxPendingChunkedMessage` and `setAutoAckOldestChunkedMessageOnQueueFull` parameters. When the threshold is reached, the consumer drops pending messages by silently acknowledging them or asking the broker to redeliver them later.
+You can limit the maximum number of chunked messages a consumer maintains concurrently by configuring the `setMaxPendingChunkedMessage` and `setAutoAckOldestChunkedMessageOnQueueFull` parameters. When the threshold is reached, the consumer drops pending messages by silently acknowledging them or asking the broker to redeliver them later.
The following is an example of how to configure message chunking.
@@ -666,7 +436,7 @@ schema, see [Pulsar schema](schema-get-started.md).
- The following example shows how to create a producer with an Avro schema.
```cpp
-
+
static const std::string exampleSchema =
"{\"type\":\"record\",\"name\":\"Example\",\"namespace\":\"test\","
"\"fields\":[{\"name\":\"a\",\"type\":\"int\"},{\"name\":\"b\",\"type\":\"int\"}]}";
@@ -674,13 +444,13 @@ schema, see [Pulsar schema](schema-get-started.md).
ProducerConfiguration producerConf;
producerConf.setSchema(SchemaInfo(AVRO, "Avro", exampleSchema));
client.createProducer("topic-avro", producerConf, producer);
-
+
```
- The following example shows how to create a consumer with an Avro schema.
```cpp
-
+
static const std::string exampleSchema =
"{\"type\":\"record\",\"name\":\"Example\",\"namespace\":\"test\","
"\"fields\":[{\"name\":\"a\",\"type\":\"int\"},{\"name\":\"b\",\"type\":\"int\"}]}";
@@ -688,14 +458,14 @@ schema, see [Pulsar schema](schema-get-started.md).
Consumer consumer;
consumerConf.setSchema(SchemaInfo(AVRO, "Avro", exampleSchema));
client.subscribe("topic-avro", "sub-2", consumerConf, consumer)
-
+
```
### ProtobufNative schema
The following example shows how to create a producer and a consumer with a ProtobufNative schema.
-1. Generate the `User` class using Protobuf3.
+1. Generate the `User` class using Protobuf3.
:::note
@@ -706,14 +476,14 @@ The following example shows how to create a producer and a consumer with a Proto
```protobuf
-
+
syntax = "proto3";
-
+
message User {
string name = 1;
int32 age = 2;
}
-
+
```
@@ -721,9 +491,9 @@ The following example shows how to create a producer and a consumer with a Proto
```cpp
-
+
#include <pulsar/ProtobufNativeSchema.h>
-
+
```
@@ -731,7 +501,7 @@ The following example shows how to create a producer and a consumer with a Proto
```cpp
-
+
ProducerConfiguration producerConf;
producerConf.setSchema(createProtobufNativeSchema(User::GetDescriptor()));
Producer producer;
@@ -742,7 +512,7 @@ The following example shows how to create a producer and a consumer with a Proto
std::string content;
user.SerializeToString(&content);
producer.send(MessageBuilder().setContent(content).build());
-
+
```
@@ -750,7 +520,7 @@ The following example shows how to create a producer and a consumer with a Proto
```cpp
-
+
ConsumerConfiguration consumerConf;
consumerConf.setSchema(createProtobufNativeSchema(User::GetDescriptor()));
consumerConf.setSubscriptionInitialPosition(InitialPositionEarliest);
@@ -760,6 +530,6 @@ The following example shows how to create a producer and a consumer with a Proto
consumer.receive(msg);
User user2;
user2.ParseFromArray(msg.getData(), msg.getLength());
-
+
```
diff --git a/site2/website-next/versioned_docs/version-2.7.5/client-libraries-cpp.md b/site2/website-next/versioned_docs/version-2.7.5/client-libraries-cpp.md
index 71dbaa19c15..204b63f3442 100644
--- a/site2/website-next/versioned_docs/version-2.7.5/client-libraries-cpp.md
+++ b/site2/website-next/versioned_docs/version-2.7.5/client-libraries-cpp.md
@@ -5,161 +5,111 @@ sidebar_label: "C++"
original_id: client-libraries-cpp
---
-You can use Pulsar C++ client to create Pulsar producers and consumers in C++.
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
-All the methods in producer, consumer, and reader of a C++ client are thread-safe.
+You can use a Pulsar C++ client to create producers, consumers, and readers.
-## Supported platforms
+All the methods in producer, consumer, and reader of a C++ client are thread-safe. You can read the [API docs](/api/cpp) for the C++ client.
-Pulsar C++ client is supported on **Linux** and **MacOS** platforms.
+## Installation
-[Doxygen](http://www.doxygen.nl/)-generated API docs for the C++ client are available [here](/api/cpp).
+Use one of the following methods to install a Pulsar C++ client.
-## Linux
+### Brew
-> Since 2.1.0 release, Pulsar ships pre-built RPM and Debian packages. You can download and install those packages directly.
-
-Four kind of libraries `libpulsar.so` / `libpulsarnossl.so` / `libpulsar.a` / `libpulsarwithdeps.a` are included in your `/usr/lib` after rpm/deb download and install.
-By default, they are build under code path `${PULSAR_HOME}/pulsar-client-cpp`, using command
- `cmake . -DBUILD_TESTS=OFF -DLINK_STATIC=ON && make pulsarShared pulsarSharedNossl pulsarStatic pulsarStaticWithDeps -j 3`
-These libraries rely on some other libraries, if you want to get detailed version of dependencies libraries, please reference [these](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/rpm/Dockerfile) [files](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/deb/Dockerfile).
-
-1. `libpulsar.so` is the Shared library, it contains statically linked `boost` and `openssl`, and will also dynamically link all other needed libraries.
-The command the when use this pulsar library is like this:
-
-```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.so -I/usr/local/ssl/include
-
-```
-
-2. `libpulsarnossl.so` is the Shared library that similar to `libpulsar.so` except that the library `openssl` and `crypto` are dynamically linked.
-The command the when use this pulsar library is like this:
+Use [Homebrew](http://brew.sh/) to install the latest tagged version with the library and headers:
```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarnossl.so -lssl -lcrypto -I/usr/local/ssl/include -L/usr/local/ssl/lib
-
+brew install libpulsar
```
-3. `libpulsar.a` is the Static library, it need to load some dependencies library when using it.
-The command the when use this pulsar library is like this:
-
-```bash
+### Deb
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.a -lssl -lcrypto -ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib -lboost_system -lboost_regex -lcurl -lprotobuf -lzstd -lz
-
-```
+1. Download any one of the Deb packages:
-4. `libpulsarwithdeps.a` is the Static library, base on `libpulsar.a`, and archived in the dependencies libraries of `libboost_regex`, `libboost_system`, `libcurl`, `libprotobuf`, `libzstd` and `libz`,
-The command the when use this pulsar library is like this:
+<Tabs>
+<TabItem value="client">
```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarwithdeps.a -lssl -lcrypto -ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib
-
+wget @pulsar:deb:client@
```
-`libpulsarwithdeps.a` does not include library openssl related libraries: `libssl` and `libcrypto`, because these 2 library is related to security,
-by using user local system provided version is more reasonable, and more easy for user to handling security issue and library upgrade.
-
-### Install RPM
-
-1. Download a RPM package from the links in the table.
-
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:dist_rpm:client@) | [asc](@pulsar:dist_rpm:client@.asc), [sha512](@pulsar:dist_rpm:client@.sha512) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) | [asc](@pulsar:dist_rpm:client-debuginfo@.asc), [sha512](@pulsar:dist_rpm:client-debuginfo@.sha512) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) | [asc](@pulsar:dist_rpm:client-devel@.asc), [sha512](@pulsar:dist_rpm:client-devel@.sha512) |
+This package contains shared libraries `libpulsar.so` and `libpulsarnossl.so`.
-2. Install the package using the following command.
+</TabItem>
+<TabItem value="client-devel">
```bash
-
-$ rpm -ivh apache-pulsar-client*.rpm
-
+wget @pulsar:deb:client-devel@
```
-After install, Pulsar libraries will be placed under `/usr/lib`.
-
-### Install Debian
+This package contains static libraries: `libpulsar.a`, `libpulsarwithdeps.a` and C/C++ headers.
-1. Download a Debian package from the links in the table.
-
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:deb:client@) | [asc](@pulsar:dist_deb:client@.asc), [sha512](@pulsar:dist_deb:client@.sha512) |
-| [client-devel](@pulsar:deb:client-devel@) | [asc](@pulsar:dist_deb:client-devel@.asc), [sha512](@pulsar:dist_deb:client-devel@.sha512) |
+</TabItem>
+</Tabs>
2. Install the package using the following command:
```bash
-
-$ apt install ./apache-pulsar-client*.deb
-
+apt install ./apache-pulsar-client*.deb
```
-After install, Pulsar libraries will be placed under `/usr/lib`.
-
-### Build
-
-> If you want to build RPM and Debian packages from the latest master, follow the instructions below. All the instructions are run at the root directory of your cloned Pulsar repository.
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
-There are recipes that build RPM and Debian packages containing a
-statically linked `libpulsar.so` / `libpulsarnossl.so` / `libpulsar.a` / `libpulsarwithdeps.a` with all the required
-dependencies.
+### RPM
-To build the C++ library packages, build the Java packages first.
+1. Download any one of the RPM packages:
-```shell
-
-mvn install -DskipTests
+<Tabs>
+<TabItem value="client">
+```bash
+wget @pulsar:dist_rpm:client@
```
-#### RPM
+This package contains shared libraries: `libpulsar.so` and `libpulsarnossl.so`.
-```shell
-
-pulsar-client-cpp/pkg/rpm/docker-build-rpm.sh
+</TabItem>
+<TabItem value="client-debuginfo">
+```bash
+wget @pulsar:dist_rpm:client-debuginfo@
```
-This builds the RPM inside a Docker container and it leaves the RPMs in `pulsar-client-cpp/pkg/rpm/RPMS/x86_64/`.
+This package contains debug symbols for `libpulsar.so`.
-| Package name | Content |
-|-----|-----|
-| pulsar-client | Shared library `libpulsar.so` and `libpulsarnossl.so` |
-| pulsar-client-devel | Static library `libpulsar.a`, `libpulsarwithdeps.a`and C++ and C headers |
-| pulsar-client-debuginfo | Debug symbols for `libpulsar.so` |
+</TabItem>
+<TabItem value="client-devel">
-#### Debian
+```bash
+wget @pulsar:dist_rpm:client-devel@
+```
-To build Debian packages, enter the following command.
+This package contains static libraries: `libpulsar.a`, `libpulsarwithdeps.a` and C/C++ headers.
-```shell
+</TabItem>
+</Tabs>
-pulsar-client-cpp/pkg/deb/docker-build-deb.sh
+2. Install the package using the following command:
+```bash
+rpm -ivh apache-pulsar-client*.rpm
```
-Debian packages are created at `pulsar-client-cpp/pkg/deb/BUILD/DEB/`.
-
-| Package name | Content |
-|-----|-----|
-| pulsar-client | Shared library `libpulsar.so` and `libpulsarnossl.so` |
-| pulsar-client-dev | Static library `libpulsar.a`, `libpulsarwithdeps.a` and C++ and C headers |
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
-## MacOS
+:::note
-Pulsar releases are available in the [Homebrew](https://brew.sh/) core repository. You can install the C++ client library with the following command. The package is installed with the library and headers.
+If you get an error like "libpulsar.so: cannot open shared object file: No such file or directory" when starting a Pulsar client, you need to run `ldconfig` first.
-```shell
+:::
-brew install libpulsar
+### Source
-```
+For how to build Pulsar C++ client on different platforms from source code, see [compliation](https://github.com/apache/pulsar-client-cpp#compilation).
## Connection URLs
@@ -173,7 +123,7 @@ pulsar://localhost:6650
```
-In a Pulsar cluster in production, the URL looks as follows:
+In a Pulsar cluster in production, the URL looks as follows:
```http
@@ -190,7 +140,7 @@ pulsar+ssl://pulsar.us-west.example.com:6651
```
## Create a consumer
-To connect to Pulsar as a consumer, you need to create a consumer on the C++ client. The following is an example.
+To connect to Pulsar as a consumer, you need to create a consumer on the C++ client. The following is an example.
```c++
@@ -218,7 +168,7 @@ client.close();
```
## Create a producer
-To connect to Pulsar as a producer, you need to create a producer on the C++ client. The following is an example.
+To connect to Pulsar as a producer, you need to create a producer on the C++ client. The following is an example.
```c++
diff --git a/site2/website-next/versioned_docs/version-2.8.x/client-libraries-cpp.md b/site2/website-next/versioned_docs/version-2.8.x/client-libraries-cpp.md
index b4fe26e3d37..4f8903ae0b0 100644
--- a/site2/website-next/versioned_docs/version-2.8.x/client-libraries-cpp.md
+++ b/site2/website-next/versioned_docs/version-2.8.x/client-libraries-cpp.md
@@ -5,267 +5,111 @@ sidebar_label: "C++"
original_id: client-libraries-cpp
---
-You can use Pulsar C++ client to create Pulsar producers and consumers in C++.
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
-All the methods in producer, consumer, and reader of a C++ client are thread-safe.
+You can use a Pulsar C++ client to create producers, consumers, and readers.
-## Supported platforms
+All the methods in producer, consumer, and reader of a C++ client are thread-safe. You can read the [API docs](/api/cpp) for the C++ client.
-Pulsar C++ client is supported on **Linux** and **macOS** platforms.
+## Installation
-[Doxygen](http://www.doxygen.nl/)-generated API docs for the C++ client are available [here](/api/cpp).
+Use one of the following methods to install a Pulsar C++ client.
-## System requirements
+### Brew
-You need to install the following components before using the C++ client:
-
-* [CMake](https://cmake.org/)
-* [Boost](http://www.boost.org/)
-* [Protocol Buffers](https://developers.google.com/protocol-buffers/) 2.6
-* [libcurl](https://curl.haxx.se/libcurl/)
-* [Google Test](https://github.com/google/googletest)
-
-## Linux
-
-### Compilation
-
-1. Clone the Pulsar repository.
-
-```shell
-
-$ git clone https://github.com/apache/pulsar
-
-```
-
-2. Install all necessary dependencies.
-
-```shell
-
-$ apt-get install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \
- libprotobuf-dev protobuf-compiler libboost-all-dev google-mock libgtest-dev libjsoncpp-dev
-
-```
-
-3. Compile and install [Google Test](https://github.com/google/googletest).
-
-```shell
-
-# libgtest-dev version is 1.18.0 or above
-$ cd /usr/src/googletest
-$ sudo cmake .
-$ sudo make
-$ sudo cp ./googlemock/libgmock.a ./googlemock/gtest/libgtest.a /usr/lib/
-
-# less than 1.18.0
-$ cd /usr/src/gtest
-$ sudo cmake .
-$ sudo make
-$ sudo cp libgtest.a /usr/lib
-
-$ cd /usr/src/gmock
-$ sudo cmake .
-$ sudo make
-$ sudo cp libgmock.a /usr/lib
-
-```
-
-4. Compile the Pulsar client library for C++ inside the Pulsar repository.
-
-```shell
-
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
-
-```
-
-After you install the components successfully, the files `libpulsar.so` and `libpulsar.a` are in the `lib` folder of the repository. The tools `perfProducer` and `perfConsumer` are in the `perf` directory.
-
-### Install Dependencies
-
-> Since 2.1.0 release, Pulsar ships pre-built RPM and Debian packages. You can download and install those packages directly.
-
-After you download and install RPM or DEB, the `libpulsar.so`, `libpulsarnossl.so`, `libpulsar.a`, and `libpulsarwithdeps.a` libraries are in your `/usr/lib` directory.
-
-By default, they are built in code path `${PULSAR_HOME}/pulsar-client-cpp`. You can build with the command below.
-
- `cmake . -DBUILD_TESTS=OFF -DLINK_STATIC=ON && make pulsarShared pulsarSharedNossl pulsarStatic pulsarStaticWithDeps -j 3`.
-
-These libraries rely on some other libraries. If you want to get detailed version of dependencies, see [RPM](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/rpm/Dockerfile) or [DEB](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/deb/Dockerfile) files.
-
-1. `libpulsar.so` is a shared library, containing statically linked `boost` and `openssl`. It also dynamically links all other necessary libraries. You can use this Pulsar library with the command below.
+Use [Homebrew](http://brew.sh/) to install the latest tagged version with the library and headers:
```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.so -I/usr/local/ssl/include
-
-```
-
-2. `libpulsarnossl.so` is a shared library, similar to `libpulsar.so` except that the libraries `openssl` and `crypto` are dynamically linked. You can use this Pulsar library with the command below.
-
-```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarnossl.so -lssl -lcrypto -I/usr/local/ssl/include -L/usr/local/ssl/lib
-
+brew install libpulsar
```
-3. `libpulsar.a` is a static library. You need to load dependencies before using this library. You can use this Pulsar library with the command below.
-
-```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.a -lssl -lcrypto -ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib -lboost_system -lboost_regex -lcurl -lprotobuf -lzstd -lz
+### Deb
-```
+1. Download any one of the Deb packages:
-4. `libpulsarwithdeps.a` is a static library, based on `libpulsar.a`. It is archived in the dependencies of `libboost_regex`, `libboost_system`, `libcurl`, `libprotobuf`, `libzstd` and `libz`. You can use this Pulsar library with the command below.
+<Tabs>
+<TabItem value="client">
```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarwithdeps.a -lssl -lcrypto -ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib
-
+wget @pulsar:deb:client@
```
-The `libpulsarwithdeps.a` does not include library openssl related libraries `libssl` and `libcrypto`, because these two libraries are related to security. It is more reasonable and easier to use the versions provided by the local system to handle security issues and upgrade libraries.
-
-### Install RPM
+This package contains shared libraries `libpulsar.so` and `libpulsarnossl.so`.
-1. Download an RPM package from the links in the table.
-
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:dist_rpm:client@) | [asc](@pulsar:dist_rpm:client@.asc), [sha512](@pulsar:dist_rpm:client@.sha512) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) | [asc](@pulsar:dist_rpm:client-debuginfo@.asc), [sha512](@pulsar:dist_rpm:client-debuginfo@.sha512) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) | [asc](@pulsar:dist_rpm:client-devel@.asc), [sha512](@pulsar:dist_rpm:client-devel@.sha512) |
-
-2. Install the package using the following command.
+</TabItem>
+<TabItem value="client-devel">
```bash
-
-$ rpm -ivh apache-pulsar-client*.rpm
-
+wget @pulsar:deb:client-devel@
```
-After you install RPM successfully, Pulsar libraries are in the `/usr/lib` directory.
-
-### Install Debian
+This package contains static libraries: `libpulsar.a`, `libpulsarwithdeps.a` and C/C++ headers.
-1. Download a Debian package from the links in the table.
+</TabItem>
+</Tabs>
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:deb:client@) | [asc](@pulsar:dist_deb:client@.asc), [sha512](@pulsar:dist_deb:client@.sha512) |
-| [client-devel](@pulsar:deb:client-devel@) | [asc](@pulsar:dist_deb:client-devel@.asc), [sha512](@pulsar:dist_deb:client-devel@.sha512) |
-
-2. Install the package using the following command.
+2. Install the package using the following command:
```bash
-
-$ apt install ./apache-pulsar-client*.deb
-
+apt install ./apache-pulsar-client*.deb
```
-After you install DEB successfully, Pulsar libraries are in the `/usr/lib` directory.
-
-### Build
-
-> If you want to build RPM and Debian packages from the latest master, follow the instructions below. You should run all the instructions at the root directory of your cloned Pulsar repository.
-
-There are recipes that build RPM and Debian packages containing a
-statically linked `libpulsar.so` / `libpulsarnossl.so` / `libpulsar.a` / `libpulsarwithdeps.a` with all required dependencies.
-
-To build the C++ library packages, you need to build the Java packages first.
-
-```shell
-
-mvn install -DskipTests
-
-```
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
-#### RPM
+### RPM
-To build the RPM inside a Docker container, use the command below. The RPMs are in the `pulsar-client-cpp/pkg/rpm/RPMS/x86_64/` path.
+1. Download any one of the RPM packages:
-```shell
-
-pulsar-client-cpp/pkg/rpm/docker-build-rpm.sh
+<Tabs>
+<TabItem value="client">
+```bash
+wget @pulsar:dist_rpm:client@
```
-| Package name | Content |
-|-----|-----|
-| pulsar-client | Shared library `libpulsar.so` and `libpulsarnossl.so` |
-| pulsar-client-devel | Static library `libpulsar.a`, `libpulsarwithdeps.a`and C++ and C headers |
-| pulsar-client-debuginfo | Debug symbols for `libpulsar.so` |
-
-#### Debian
+This package contains shared libraries: `libpulsar.so` and `libpulsarnossl.so`.
-To build Debian packages, enter the following command.
-
-```shell
-
-pulsar-client-cpp/pkg/deb/docker-build-deb.sh
+</TabItem>
+<TabItem value="client-debuginfo">
+```bash
+wget @pulsar:dist_rpm:client-debuginfo@
```
-Debian packages are created in the `pulsar-client-cpp/pkg/deb/BUILD/DEB/` path.
-
-| Package name | Content |
-|-----|-----|
-| pulsar-client | Shared library `libpulsar.so` and `libpulsarnossl.so` |
-| pulsar-client-dev | Static library `libpulsar.a`, `libpulsarwithdeps.a` and C++ and C headers |
-
-## MacOS
-
-### Compilation
-
-1. Clone the Pulsar repository.
-
-```shell
+This package contains debug symbols for `libpulsar.so`.
-$ git clone https://github.com/apache/pulsar
+</TabItem>
+<TabItem value="client-devel">
+```bash
+wget @pulsar:dist_rpm:client-devel@
```
-2. Install all necessary dependencies.
-
-```shell
-
-# OpenSSL installation
-$ brew install openssl
-$ export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/
-$ export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/
+This package contains static libraries: `libpulsar.a`, `libpulsarwithdeps.a` and C/C++ headers.
-$ brew install protobuf boost boost-python log4cxx
-# If you are using python3, you need to install boost-python3
+</TabItem>
+</Tabs>
-# Google Test installation
-$ git clone https://github.com/google/googletest.git
-$ cd googletest
-$ git checkout release-1.12.1
-$ cmake .
-$ make install
+2. Install the package using the following command:
+```bash
+rpm -ivh apache-pulsar-client*.rpm
```
-3. Compile the Pulsar client library in the repository that you cloned.
-
-```shell
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
+:::note
-```
-
-### Install `libpulsar`
+If you get an error like "libpulsar.so: cannot open shared object file: No such file or directory" when starting a Pulsar client, you need to run `ldconfig` first.
-Pulsar releases are available in the [Homebrew](https://brew.sh/) core repository. You can install the C++ client library with the following command. The package is installed with the library and headers.
+:::
-```shell
+### Source
-brew install libpulsar
-
-```
+For how to build Pulsar C++ client on different platforms from source code, see [compliation](https://github.com/apache/pulsar-client-cpp#compilation).
## Connection URLs
@@ -279,7 +123,7 @@ pulsar://localhost:6650
```
-In a Pulsar cluster in production, the URL looks as follows.
+In a Pulsar cluster in production, the URL looks as follows.
```http
@@ -297,7 +141,7 @@ pulsar+ssl://pulsar.us-west.example.com:6651
## Create a consumer
-To use Pulsar as a consumer, you need to create a consumer on the C++ client. The following is an example.
+To use Pulsar as a consumer, you need to create a consumer on the C++ client. The following is an example.
```cpp
@@ -326,7 +170,7 @@ client.close();
## Create a producer
-To use Pulsar as a producer, you need to create a producer on the C++ client. The following is an example.
+To use Pulsar as a producer, you need to create a producer on the C++ client. The following is an example.
```cpp
diff --git a/site2/website-next/versioned_docs/version-2.9.x/client-libraries-cpp.md b/site2/website-next/versioned_docs/version-2.9.x/client-libraries-cpp.md
index 59a33b74349..aabf7f0969b 100644
--- a/site2/website-next/versioned_docs/version-2.9.x/client-libraries-cpp.md
+++ b/site2/website-next/versioned_docs/version-2.9.x/client-libraries-cpp.md
@@ -5,318 +5,111 @@ sidebar_label: "C++"
original_id: client-libraries-cpp
---
-You can use Pulsar C++ client to create Pulsar producers and consumers in C++.
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
-All the methods in producer, consumer, and reader of a C++ client are thread-safe.
+You can use a Pulsar C++ client to create producers, consumers, and readers.
-## Supported platforms
+All the methods in producer, consumer, and reader of a C++ client are thread-safe. You can read the [API docs](/api/cpp) for the C++ client.
-Pulsar C++ client is supported on **Linux** ,**macOS** and **Windows** platforms.
+## Installation
-[Doxygen](http://www.doxygen.nl/)-generated API docs for the C++ client are available [here](/api/cpp).
+Use one of the following methods to install a Pulsar C++ client.
-## System requirements
+### Brew
-You need to install the following components before using the C++ client:
-
-* [CMake](https://cmake.org/)
-* [Boost](http://www.boost.org/)
-* [Protocol Buffers](https://developers.google.com/protocol-buffers/) >= 3
-* [libcurl](https://curl.se/libcurl/)
-* [Google Test](https://github.com/google/googletest)
-
-## Linux
-
-### Compilation
-
-1. Clone the Pulsar repository.
-
-```shell
-
-$ git clone https://github.com/apache/pulsar
+Use [Homebrew](http://brew.sh/) to install the latest tagged version with the library and headers:
+```bash
+brew install libpulsar
```
-2. Install all necessary dependencies.
+### Deb
-```shell
+1. Download any one of the Deb packages:
-$ apt-get install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \
- libprotobuf-dev protobuf-compiler libboost-all-dev google-mock libgtest-dev libjsoncpp-dev
+<Tabs>
+<TabItem value="client">
+```bash
+wget @pulsar:deb:client@
```
-3. Compile and install [Google Test](https://github.com/google/googletest).
-
-```shell
-
-# libgtest-dev version is 1.18.0 or above
-$ cd /usr/src/googletest
-$ sudo cmake .
-$ sudo make
-$ sudo cp ./googlemock/libgmock.a ./googlemock/gtest/libgtest.a /usr/lib/
-
-# less than 1.18.0
-$ cd /usr/src/gtest
-$ sudo cmake .
-$ sudo make
-$ sudo cp libgtest.a /usr/lib
+This package contains shared libraries `libpulsar.so` and `libpulsarnossl.so`.
-$ cd /usr/src/gmock
-$ sudo cmake .
-$ sudo make
-$ sudo cp libgmock.a /usr/lib
+</TabItem>
+<TabItem value="client-devel">
+```bash
+wget @pulsar:deb:client-devel@
```
-4. Compile the Pulsar client library for C++ inside the Pulsar repository.
+This package contains static libraries: `libpulsar.a`, `libpulsarwithdeps.a` and C/C++ headers.
-```shell
+</TabItem>
+</Tabs>
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
+2. Install the package using the following command:
+```bash
+apt install ./apache-pulsar-client*.deb
```
-After you install the components successfully, the files `libpulsar.so` and `libpulsar.a` are in the `lib` folder of the repository. The tools `perfProducer` and `perfConsumer` are in the `perf` directory.
-
-### Install Dependencies
-
-> Since 2.1.0 release, Pulsar ships pre-built RPM and Debian packages. You can download and install those packages directly.
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
-After you download and install RPM or DEB, the `libpulsar.so`, `libpulsarnossl.so`, `libpulsar.a`, and `libpulsarwithdeps.a` libraries are in your `/usr/lib` directory.
+### RPM
-By default, they are built in code path `${PULSAR_HOME}/pulsar-client-cpp`. You can build with the command below.
+1. Download any one of the RPM packages:
- `cmake . -DBUILD_TESTS=OFF -DLINK_STATIC=ON && make pulsarShared pulsarSharedNossl pulsarStatic pulsarStaticWithDeps -j 3`.
-
-These libraries rely on some other libraries. If you want to get detailed version of dependencies, see [RPM](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/rpm/Dockerfile) or [DEB](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/deb/Dockerfile) files.
-
-1. `libpulsar.so` is a shared library, containing statically linked `boost` and `openssl`. It also dynamically links all other necessary libraries. You can use this Pulsar library with the command below.
+<Tabs>
+<TabItem value="client">
```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.so -I/usr/local/ssl/include
-
+wget @pulsar:dist_rpm:client@
```
-2. `libpulsarnossl.so` is a shared library, similar to `libpulsar.so` except that the libraries `openssl` and `crypto` are dynamically linked. You can use this Pulsar library with the command below.
-
-```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarnossl.so -lssl -lcrypto -I/usr/local/ssl/include -L/usr/local/ssl/lib
-
-```
+This package contains shared libraries: `libpulsar.so` and `libpulsarnossl.so`.
-3. `libpulsar.a` is a static library. You need to load dependencies before using this library. You can use this Pulsar library with the command below.
+</TabItem>
+<TabItem value="client-debuginfo">
```bash
-
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.a -lssl -lcrypto -ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib -lboost_system -lboost_regex -lcurl -lprotobuf -lzstd -lz
-
+wget @pulsar:dist_rpm:client-debuginfo@
```
-4. `libpulsarwithdeps.a` is a static library, based on `libpulsar.a`. It is archived in the dependencies of `libboost_regex`, `libboost_system`, `libcurl`, `libprotobuf`, `libzstd` and `libz`. You can use this Pulsar library with the command below.
-
-```bash
+This package contains debug symbols for `libpulsar.so`.
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarwithdeps.a -lssl -lcrypto -ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib
+</TabItem>
+<TabItem value="client-devel">
+```bash
+wget @pulsar:dist_rpm:client-devel@
```
-The `libpulsarwithdeps.a` does not include library openssl related libraries `libssl` and `libcrypto`, because these two libraries are related to security. It is more reasonable and easier to use the versions provided by the local system to handle security issues and upgrade libraries.
-
-### Install RPM
-
-1. Download a RPM package from the links in the table.
+This package contains static libraries: `libpulsar.a`, `libpulsarwithdeps.a` and C/C++ headers.
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:dist_rpm:client@) | [asc](@pulsar:dist_rpm:client@.asc), [sha512](@pulsar:dist_rpm:client@.sha512) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) | [asc](@pulsar:dist_rpm:client-debuginfo@.asc), [sha512](@pulsar:dist_rpm:client-debuginfo@.sha512) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) | [asc](@pulsar:dist_rpm:client-devel@.asc), [sha512](@pulsar:dist_rpm:client-devel@.sha512) |
+</TabItem>
+</Tabs>
-2. Install the package using the following command.
+2. Install the package using the following command:
```bash
-
-$ rpm -ivh apache-pulsar-client*.rpm
-
+rpm -ivh apache-pulsar-client*.rpm
```
-After you install RPM successfully, Pulsar libraries are in the `/usr/lib` directory.
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
:::note
-If you get the error that `libpulsar.so: cannot open shared object file: No such file or directory` when starting Pulsar client, you may need to run `ldconfig` first.
+If you get an error like "libpulsar.so: cannot open shared object file: No such file or directory" when starting a Pulsar client, you need to run `ldconfig` first.
:::
-### Install Debian
-
-1. Download a Debian package from the links in the table.
-
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:deb:client@) | [asc](@pulsar:dist_deb:client@.asc), [sha512](@pulsar:dist_deb:client@.sha512) |
-| [client-devel](@pulsar:deb:client-devel@) | [asc](@pulsar:dist_deb:client-devel@.asc), [sha512](@pulsar:dist_deb:client-devel@.sha512) |
-
-2. Install the package using the following command.
-
-```bash
-
-$ apt install ./apache-pulsar-client*.deb
-
-```
-
-After you install DEB successfully, Pulsar libraries are in the `/usr/lib` directory.
-
-### Build
-
-> If you want to build RPM and Debian packages from the latest master, follow the instructions below. You should run all the instructions at the root directory of your cloned Pulsar repository.
-
-There are recipes that build RPM and Debian packages containing a
-statically linked `libpulsar.so` / `libpulsarnossl.so` / `libpulsar.a` / `libpulsarwithdeps.a` with all required dependencies.
-
-To build the C++ library packages, you need to build the Java packages first.
-
-```shell
-
-mvn install -DskipTests
-
-```
-
-#### RPM
-
-To build the RPM inside a Docker container, use the command below. The RPMs are in the `pulsar-client-cpp/pkg/rpm/RPMS/x86_64/` path.
-
-```shell
-
-pulsar-client-cpp/pkg/rpm/docker-build-rpm.sh
-
-```
-
-| Package name | Content |
-|-----|-----|
-| pulsar-client | Shared library `libpulsar.so` and `libpulsarnossl.so` |
-| pulsar-client-devel | Static library `libpulsar.a`, `libpulsarwithdeps.a`and C++ and C headers |
-| pulsar-client-debuginfo | Debug symbols for `libpulsar.so` |
-
-#### Debian
-
-To build Debian packages, enter the following command.
-
-```shell
-
-pulsar-client-cpp/pkg/deb/docker-build-deb.sh
-
-```
-
-Debian packages are created in the `pulsar-client-cpp/pkg/deb/BUILD/DEB/` path.
-
-| Package name | Content |
-|-----|-----|
-| pulsar-client | Shared library `libpulsar.so` and `libpulsarnossl.so` |
-| pulsar-client-dev | Static library `libpulsar.a`, `libpulsarwithdeps.a` and C++ and C headers |
-
-## MacOS
-
-### Compilation
-
-1. Clone the Pulsar repository.
-
-```shell
-
-$ git clone https://github.com/apache/pulsar
-
-```
-
-2. Install all necessary dependencies.
-
-```shell
-
-# OpenSSL installation
-$ brew install openssl
-$ export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/
-$ export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/
-
-# Protocol Buffers installation
-$ brew install protobuf boost boost-python log4cxx
-# If you are using python3, you need to install boost-python3
-
-# Google Test installation
-$ git clone https://github.com/google/googletest.git
-$ cd googletest
-$ git checkout release-1.12.1
-$ cmake .
-$ make install
-
-```
-
-3. Compile the Pulsar client library in the repository that you cloned.
-
-```shell
-
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
-
-```
-
-### Install `libpulsar`
-
-Pulsar releases are available in the [Homebrew](https://brew.sh/) core repository. You can install the C++ client library with the following command. The package is installed with the library and headers.
-
-```shell
-
-brew install libpulsar
-
-```
-
-## Windows (64-bit)
-
-### Compilation
-
-1. Clone the Pulsar repository.
-
-```shell
+### Source
-$ git clone https://github.com/apache/pulsar
-
-```
-
-2. Install all necessary dependencies.
-
-```shell
-
-cd ${PULSAR_HOME}/pulsar-client-cpp
-vcpkg install --feature-flags=manifests --triplet x64-windows
-
-```
-
-3. Build C++ libraries.
-
-```shell
-
-cmake -B ./build -A x64 -DBUILD_PYTHON_WRAPPER=OFF -DBUILD_TESTS=OFF -DVCPKG_TRIPLET=x64-windows -DCMAKE_BUILD_TYPE=Release -S .
-cmake --build ./build --config Release
-
-```
-
-> **NOTE**
->
-> 1. For Windows 32-bit, you need to use `-A Win32` and `-DVCPKG_TRIPLET=x86-windows`.
-> 2. For MSVC Debug mode, you need to replace `Release` with `Debug` for both `CMAKE_BUILD_TYPE` variable and `--config` option.
-
-4. Client libraries are available in the following places.
-
-```
-
-${PULSAR_HOME}/pulsar-client-cpp/build/lib/Release/pulsar.lib
-${PULSAR_HOME}/pulsar-client-cpp/build/lib/Release/pulsar.dll
-
-```
+For how to build Pulsar C++ client on different platforms from source code, see [compliation](https://github.com/apache/pulsar-client-cpp#compilation).
## Connection URLs
@@ -330,7 +123,7 @@ pulsar://localhost:6650
```
-In a Pulsar cluster in production, the URL looks as follows.
+In a Pulsar cluster in production, the URL looks as follows.
```http
@@ -609,7 +402,7 @@ schema, see [Pulsar schema](schema-get-started.md).
- The following example shows how to create a producer with an Avro schema.
```cpp
-
+
static const std::string exampleSchema =
"{\"type\":\"record\",\"name\":\"Example\",\"namespace\":\"test\","
"\"fields\":[{\"name\":\"a\",\"type\":\"int\"},{\"name\":\"b\",\"type\":\"int\"}]}";
@@ -617,13 +410,13 @@ schema, see [Pulsar schema](schema-get-started.md).
ProducerConfiguration producerConf;
producerConf.setSchema(SchemaInfo(AVRO, "Avro", exampleSchema));
client.createProducer("topic-avro", producerConf, producer);
-
+
```
- The following example shows how to create a consumer with an Avro schema.
```cpp
-
+
static const std::string exampleSchema =
"{\"type\":\"record\",\"name\":\"Example\",\"namespace\":\"test\","
"\"fields\":[{\"name\":\"a\",\"type\":\"int\"},{\"name\":\"b\",\"type\":\"int\"}]}";
@@ -631,14 +424,14 @@ schema, see [Pulsar schema](schema-get-started.md).
Consumer consumer;
consumerConf.setSchema(SchemaInfo(AVRO, "Avro", exampleSchema));
client.subscribe("topic-avro", "sub-2", consumerConf, consumer)
-
+
```
### ProtobufNative schema
The following example shows how to create a producer and a consumer with a ProtobufNative schema.
-1. Generate the `User` class using Protobuf3.
+1. Generate the `User` class using Protobuf3.
:::note
@@ -649,14 +442,14 @@ The following example shows how to create a producer and a consumer with a Proto
```protobuf
-
+
syntax = "proto3";
-
+
message User {
string name = 1;
int32 age = 2;
}
-
+
```
@@ -664,9 +457,9 @@ The following example shows how to create a producer and a consumer with a Proto
```cpp
-
+
#include <pulsar/ProtobufNativeSchema.h>
-
+
```
@@ -674,7 +467,7 @@ The following example shows how to create a producer and a consumer with a Proto
```cpp
-
+
ProducerConfiguration producerConf;
producerConf.setSchema(createProtobufNativeSchema(User::GetDescriptor()));
Producer producer;
@@ -685,7 +478,7 @@ The following example shows how to create a producer and a consumer with a Proto
std::string content;
user.SerializeToString(&content);
producer.send(MessageBuilder().setContent(content).build());
-
+
```
@@ -693,7 +486,7 @@ The following example shows how to create a producer and a consumer with a Proto
```cpp
-
+
ConsumerConfiguration consumerConf;
consumerConf.setSchema(createProtobufNativeSchema(User::GetDescriptor()));
consumerConf.setSubscriptionInitialPosition(InitialPositionEarliest);
@@ -703,6 +496,6 @@ The following example shows how to create a producer and a consumer with a Proto
consumer.receive(msg);
User user2;
user2.ParseFromArray(msg.getData(), msg.getLength());
-
+
```