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 <[email protected]>
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/[email protected]";
-};
-
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/[email protected]";
};
-
- PulsarClient {
- com.sun.security.auth.module.Krb5LoginModule required
- useKeyTab=true
- storeKey=true
- useTicketCache=false
- keyTab="/etc/security/keytabs/pulsarclient.keytab"
- principal="client/[email protected]";
-};
```
-### 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/[email protected]";
-};
-```
+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/[email protected]";
+ };
+ ```
-## 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/[email protected]";
-};
-```
+ ```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/[email protected]";
+ };
+ ```
+
+ 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-abcdefghijklmnopqrstuvw...@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-abcdefghijklmnopqrstuvw...@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:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) |
[asc](@pulsar:dist_rpm:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) |
[asc](@pulsar:dist_rpm:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-
-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:[email protected]),
[sha512](@pulsar:dist_deb:[email protected]) |
-| [client-devel](@pulsar:deb:client-devel@) |
[asc](@pulsar:dist_deb:[email protected]),
[sha512](@pulsar:dist_deb:[email protected]) |
+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:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) |
[asc](@pulsar:dist_rpm:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) |
[asc](@pulsar:dist_rpm:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
+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:[email protected]),
[sha512](@pulsar:dist_deb:[email protected]) |
-| [client-devel](@pulsar:deb:client-devel@) |
[asc](@pulsar:dist_deb:[email protected]),
[sha512](@pulsar:dist_deb:[email protected]) |
+</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:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) |
[asc](@pulsar:dist_rpm:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) |
[asc](@pulsar:dist_rpm:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-
-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:[email protected]),
[sha512](@pulsar:dist_deb:[email protected]) |
-| [client-devel](@pulsar:deb:client-devel@) |
[asc](@pulsar:dist_deb:[email protected]),
[sha512](@pulsar:dist_deb:[email protected]) |
-
-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:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) |
[asc](@pulsar:dist_rpm:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) |
[asc](@pulsar:dist_rpm:[email protected]),
[sha512](@pulsar:dist_rpm:[email protected]) |
+</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:[email protected]),
[sha512](@pulsar:dist_deb:[email protected]) |
-| [client-devel](@pulsar:deb:client-devel@) |
[asc](@pulsar:dist_deb:[email protected]),
[sha512](@pulsar:dist_deb:[email protected]) |
-
-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());
-
+
```
