This is an automated email from the ASF dual-hosted git repository.
liuyu 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 0d311d707b5 [improve][doc] SEO for Security and Performance (#697)
0d311d707b5 is described below
commit 0d311d707b5f00441e960fbe0998476f92c75c6f
Author: Zhang Yuxuan <[email protected]>
AuthorDate: Tue Sep 12 10:34:56 2023 +0800
[improve][doc] SEO for Security and Performance (#697)
---
docs/performance-pulsar-perf.md | 3 ++-
docs/security-athenz.md | 1 +
docs/security-authorization.md | 3 ++-
docs/security-basic-auth.md | 6 ++++--
docs/security-bouncy-castle.md | 1 +
docs/security-encryption.md | 13 +++++++++----
docs/security-extending.md | 1 +
docs/security-jwt.md | 5 +++--
docs/security-kerberos.md | 19 ++++++++++++-------
docs/security-oauth2.md | 1 +
docs/security-openid-connect.md | 1 +
docs/security-overview.md | 3 ++-
docs/security-tls-authentication.md | 9 ++++++---
docs/security-tls-transport.md | 25 +++++++++++++++----------
14 files changed, 60 insertions(+), 31 deletions(-)
diff --git a/docs/performance-pulsar-perf.md b/docs/performance-pulsar-perf.md
index 1d231882400..73c6792c9b7 100644
--- a/docs/performance-pulsar-perf.md
+++ b/docs/performance-pulsar-perf.md
@@ -2,6 +2,7 @@
id: performance-pulsar-perf
title: Pulsar Perf
sidebar_label: "Pulsar Perf"
+description: Learn how to use Pulsar Perf for performance testing and
HdrHistogram Plotter for visualizing test results.
---
The Pulsar Perf is a built-in performance test tool for Apache Pulsar. You can
use the Pulsar Perf to test message writing or reading performance. For
detailed information about performance tuning, see
[here](https://streamnative.io/en/blog/tech/2021-01-14-pulsar-architecture-performance-tuning).
@@ -243,4 +244,4 @@ To check test results through the HdrHistogram Plotter,
follow these steps:
6. Check the test result through the Graphical User Interface of the
HdrHistogram Plotter, as shown below.
- 
+ 
diff --git a/docs/security-athenz.md b/docs/security-athenz.md
index 12a0bf403e0..6040f67664c 100644
--- a/docs/security-athenz.md
+++ b/docs/security-athenz.md
@@ -2,6 +2,7 @@
id: security-athenz
title: Authentication using Athenz
sidebar_label: "Authentication using Athenz"
+description: Get a comprehensive understanding of concepts and configuration
methods of Athenz authentication in Pulsar.
---
````mdx-code-block
diff --git a/docs/security-authorization.md b/docs/security-authorization.md
index 37932b71d94..1b3e27c82b9 100644
--- a/docs/security-authorization.md
+++ b/docs/security-authorization.md
@@ -2,6 +2,7 @@
id: security-authorization
title: Authentication and authorization in Pulsar
sidebar_label: "Authorization and ACLs"
+description: Get a comprehensive understanding of authentication and
authorization in Pulsar.
---
@@ -60,7 +61,7 @@ You can manage tenants using the
[`pulsar-admin`](pathname:///reference/#/@pulsa
### Create a new tenant
-The following is an example tenant creation command:
+You can create a new tenant using the following command.
```shell
bin/pulsar-admin tenants create my-tenant \
diff --git a/docs/security-basic-auth.md b/docs/security-basic-auth.md
index 2c2a7951bcc..73a669540e3 100644
--- a/docs/security-basic-auth.md
+++ b/docs/security-basic-auth.md
@@ -2,6 +2,7 @@
id: security-basic-auth
title: Authentication using HTTP basic
sidebar_label: "Authentication using HTTP basic"
+description: Get a comprehensive understanding of concepts and configuration
methods of HTTP basic authentication in Pulsar.
---
````mdx-code-block
@@ -35,7 +36,8 @@ Currently, you can use MD5 (recommended) and CRYPT encryption
to authenticate yo
:::
-Create a password file named `.htpasswd` with a user account `superuser/admin`:
+To create a password file named `.htpasswd` with a user account
`superuser/admin`, you can use the following methods.
+
* Use MD5 encryption (recommended):
```bash
@@ -93,7 +95,7 @@ authParams={"userId":"superuser","password":"admin"}
## Configure basic authentication in Pulsar clients
-The following example shows how to configure basic authentication when using
Pulsar clients.
+To configure basic authentication when using Pulsar clients, you can follow
the example below.
````mdx-code-block
<Tabs groupId="lang-choice"
diff --git a/docs/security-bouncy-castle.md b/docs/security-bouncy-castle.md
index 9e6b1d85912..fd645111ad8 100644
--- a/docs/security-bouncy-castle.md
+++ b/docs/security-bouncy-castle.md
@@ -2,6 +2,7 @@
id: security-bouncy-castle
title: Bouncy Castle Providers
sidebar_label: "Bouncy Castle Providers"
+description: Get a comprehensive understanding of concepts and packaging
methods of BouncyCastle in Pulsar.
---
## BouncyCastle Introduce
diff --git a/docs/security-encryption.md b/docs/security-encryption.md
index adb8b800568..9e4e4f7084e 100644
--- a/docs/security-encryption.md
+++ b/docs/security-encryption.md
@@ -2,6 +2,7 @@
id: security-encryption
title: End-to-End Encryption
sidebar_label: "End-to-End Encryption"
+description: Get a comprehensive understanding of the workflow, usage, and
troubleshooting of end-to-end encryption in Pulsar.
---
````mdx-code-block
@@ -11,13 +12,15 @@ import TabItem from '@theme/TabItem';
Applications can use Pulsar end-to-end encryption (E2EE) to encrypt messages
on the producer side and decrypt messages on the consumer side. You can use the
public and private key pair that the application configures to perform
encryption and decryption. Only the consumers with a valid key can decrypt the
encrypted messages.
-## How it works in Pulsar
+## How end-to-end encryption works in Pulsar
Pulsar uses a dynamically generated symmetric session key to encrypt messages
(data). You can use the application-provided ECDSA (Elliptic Curve Digital
Signature Algorithm) or RSA (Rivest–Shamir–Adleman) key pair to encrypt the
session key (data key), so you do not have to share the secret with everyone.
The following figure illustrates how Pulsar encrypts messages on the producer
side and decrypts messages on the consumer side.
-
+
+
+The workflow of end-to-end encryption in Pulsar is as follows.
1. The producer generates a session key regularly (every 4 hours or after
publishing a certain number of messages) to encrypt the message payload using a
symmetric algorithm, such as AES, and fetches the asymmetric public key every 4
hours. The ciphertext is packed as the message body.
2. The producer uses the consumer’s public key to encrypt the session key
using an asymmetric algorithm, such as RSA, and adds an alias with the
encrypted secret to the message header.
@@ -39,12 +42,14 @@ If the produced messages are consumed across application
boundaries, you need to
## Get started
+To enable end-to-end encryption in Puslar, complete the following steps.
+
### Prerequisites
* Pulsar Java/Python/C++/Node.js client 2.7.1 or later versions.
* Pulsar Go client 0.6.0 or later versions.
-### Configure end-to-end encryption
+### Step 1: Configure end-to-end encryption
1. Create both public and private key pairs.
@@ -357,7 +362,7 @@ If the produced messages are consumed across application
boundaries, you need to
</Tabs>
````
-### Encrypt a message with multiple keys
+### Step 2: Encrypt a message with multiple keys
:::note
diff --git a/docs/security-extending.md b/docs/security-extending.md
index 4da31ebe1c7..9bf6068d869 100644
--- a/docs/security-extending.md
+++ b/docs/security-extending.md
@@ -2,6 +2,7 @@
id: security-extending
title: Extend Authentication and Authorization in Pulsar
sidebar_label: "Extend Authentication and Authorization"
+description: Learn how to use custom authentication and authorization
mechanisms.
---
Pulsar provides a way to use custom authentication and authorization
mechanisms.
diff --git a/docs/security-jwt.md b/docs/security-jwt.md
index 56d1e81948d..b22f3703f3a 100644
--- a/docs/security-jwt.md
+++ b/docs/security-jwt.md
@@ -2,6 +2,7 @@
id: security-jwt
title: Authentication using tokens based on JSON Web Tokens
sidebar_label: "Authentication using JWT"
+description: Get a comprehensive understanding of concepts and configuration
methods of JWT authentication in Pulsar.
---
````mdx-code-block
@@ -38,7 +39,7 @@ JWT authentication supports two different kinds of keys to
generate and validate
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 use the following command to create a secret key. The output file is
generated in the root of your Pulsar installation directory.
```shell
bin/pulsar tokens create-secret-key --output my-secret.key
@@ -58,7 +59,7 @@ bin/pulsar tokens create-secret-key --output my-secret.key
--base64
### Create a key pair
-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.
+To use asymmetric key encryption, you need to create a pair of keys using the
following command. The output file is generated in the root of your Pulsar
installation directory.
```shell
bin/pulsar tokens create-key-pair --output-private-key my-private.key
--output-public-key my-public.key
diff --git a/docs/security-kerberos.md b/docs/security-kerberos.md
index 2ebb6639dad..f86e6221ea6 100644
--- a/docs/security-kerberos.md
+++ b/docs/security-kerberos.md
@@ -2,6 +2,7 @@
id: security-kerberos
title: Authentication using Kerberos
sidebar_label: "Authentication using Kerberos"
+description: Get a comprehensive understanding of concepts and configuration
methods of Kerberos authentication in Pulsar.
---
[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.
@@ -27,7 +28,9 @@ superUserRoles=client/{clientIp}@EXAMPLE.COM
## Enable Kerberos authentication on brokers
-### Create Kerberos principals
+To enable Kerberos authentication on brokers, complete the following steps.
+
+### Step 1: Create Kerberos principals
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).
@@ -46,7 +49,7 @@ The first part of broker principal (for example, `broker` in
`broker/{hostname}@
Note that *Kerberos* requires that all your hosts can be resolved with their
FQDNs.
-### Configure brokers
+### Step 2: Configure brokers
In the `broker.conf` file, set Kerberos-related configurations. Here is an
example:
@@ -65,7 +68,7 @@ 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
+### Step 3: Configure JAAS
JAAS configuration file provides the information to connect KDC. Here is an
example named `pulsar_jaas.conf`:
@@ -99,7 +102,7 @@ You need to set the `pulsar_jaas.conf` file path as a JVM
parameter. For example
-Djava.security.auth.login.config=/etc/pulsar/pulsar_jaas.conf
```
-### Connect to KDC
+### Step 4: Connect to KDC
:::note
@@ -135,7 +138,9 @@ In the above example:
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.
-### Create Kerberos principals
+To enable Kerberos authentication on proxies, complete the following steps.
+
+### Step 1: Create Kerberos principals
Add new principals for Pulsar proxies.
@@ -147,7 +152,7 @@ sudo /usr/sbin/kadmin.local -q "ktadd -k
/etc/security/keytabs/{proxy-keytabname
For principals set for brokers and clients, see
[here](#create-kerberos-principals).
-### Configure proxies
+### Step 2: Configure proxies
In the `proxy.conf` file, set Kerberos-related configuration.
@@ -168,7 +173,7 @@ 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.
-### Configure JAAS
+### Step 3: Configure JAAS
Add a new section for proxies in the `pulsar_jaas.conf` file. Here is an
example:
diff --git a/docs/security-oauth2.md b/docs/security-oauth2.md
index a7b36bdb180..725c83cc1df 100644
--- a/docs/security-oauth2.md
+++ b/docs/security-oauth2.md
@@ -2,6 +2,7 @@
id: security-oauth2
title: Authentication using OAuth 2.0 access tokens
sidebar_label: "Authentication using OAuth 2.0 access tokens"
+description: Get a comprehensive understanding of concepts and configuration
methods of OAuth authentication in Pulsar.
---
````mdx-code-block
diff --git a/docs/security-openid-connect.md b/docs/security-openid-connect.md
index edf51330e6e..65d220b9b3d 100644
--- a/docs/security-openid-connect.md
+++ b/docs/security-openid-connect.md
@@ -2,6 +2,7 @@
id: security-openid-connect
title: Authentication using OpenID Connect
sidebar_label: "Authentication using OpenID Connect"
+description: Get a comprehensive understanding of concepts and configuration
methods of OpenID Connect authentication in Pulsar.
---
Apache Pulsar supports authenticating clients using [OpenID
Connect](https://openid.net/connect), which is an implementation of the OAuth
2.0 Protocol. Using an access token obtained from an OpenID Connect compliant
Identity Provider service acting as the 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 performing some admin
operation.
diff --git a/docs/security-overview.md b/docs/security-overview.md
index cf5304412af..939cea782da 100644
--- a/docs/security-overview.md
+++ b/docs/security-overview.md
@@ -2,6 +2,7 @@
id: security-overview
title: Pulsar security overview
sidebar_label: "Overview"
+description: Get a comprehensive understanding of Pulsar security, including
encryption, authentication, and authorization.
---
As the central message bus for a business, Apache Pulsar is frequently used
for storing mission-critical data. Therefore, enabling security features in
Pulsar is crucial. This chapter describes the main security controls that
Pulsar uses to help protect your data.
@@ -28,7 +29,7 @@ Encryption ensures that if an attacker gets access to your
data, the attacker ca
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.
-### How it works in Pulsar
+### How authentication works in Pulsar
Pulsar provides a pluggable authentication framework, and Pulsar
brokers/proxies use this mechanism to authenticate clients.
diff --git a/docs/security-tls-authentication.md
b/docs/security-tls-authentication.md
index 84296c0f656..707570d979a 100644
--- a/docs/security-tls-authentication.md
+++ b/docs/security-tls-authentication.md
@@ -2,6 +2,7 @@
id: security-tls-authentication
title: Authentication using mTLS
sidebar_label: "Authentication using mTLS"
+description: Get a comprehensive understanding of concepts and configuration
methods of mTLS authentication in Pulsar.
---
````mdx-code-block
@@ -194,9 +195,11 @@
authParams=tlsCertFile:/path/to/my-role.cert.pem,tlsKeyFile:/path/to/my-role.key
## Configure mTLS authentication with KeyStore
-Apache Pulsar supports [TLS encryption](security-tls-transport.md) and [mTLS
authentication](security-tls-authentication.md) between clients and Apache
Pulsar service. By default, it uses PEM format file configuration. This section
describes how to use the
[KeyStore](https://en.wikipedia.org/wiki/Java_KeyStore) type to configure mTLS
authentication.
+Apache Pulsar supports [TLS encryption](security-tls-transport.md) and [mTLS
authentication](security-tls-authentication.md) between clients and Apache
Pulsar service. By default, it uses PEM format file configuration.
-### Configure brokers
+To configure mTLS authentication with
[KeyStore](https://en.wikipedia.org/wiki/Java_KeyStore), complete the following
steps.
+
+### Step 1: Configure brokers
Configure the `broker.conf` file as follows.
@@ -232,7 +235,7 @@ tlsRequireTrustedClientCertOnConnect=true
tlsAllowInsecureConnection=false
```
-### Configure clients
+### Step 2: Configure clients
Besides configuring [TLS encryption](security-tls-transport.md), you need to
configure the KeyStore, which contains a valid CN as client role, for clients.
diff --git a/docs/security-tls-transport.md b/docs/security-tls-transport.md
index f2a2df0834f..a7bc580f17c 100644
--- a/docs/security-tls-transport.md
+++ b/docs/security-tls-transport.md
@@ -2,6 +2,7 @@
id: security-tls-transport
title: TLS Encryption
sidebar_label: "TLS Encryption"
+description: Get a comprehensive understanding of TLS concepts, debugging
methods and mTLS configuration methods in Pulsar.
---
@@ -63,7 +64,9 @@ Moreover, as the administrator has full control of the CA, a
bad actor is unlike
By default, Pulsar uses
[netty-tcnative](https://github.com/netty/netty-tcnative). It includes two
implementations, `OpenSSL` (default) and `JDK`. When `OpenSSL` is unavailable,
`JDK` is used.
-### Create TLS certificates
+To configure mTLS encryption with PEM, complete the following steps.
+
+### Step 1: Create TLS certificates
Creating TLS certificates involves creating a [certificate
authority](#create-a-certificate-authority), a [server
certificate](#create-a-server-certificate), and a [client
certificate](#create-a-client-certificate).
@@ -181,7 +184,7 @@ At this point, you have a cert, `broker.cert.pem`, and a
key, `broker.key-pk8.pe
At this point, you have a cert `client.cert.pem` and a key
`client.key-pk8.pem`, which you can use along with `ca.cert.pem` to configure
TLS encryption for your clients.
-### Configure brokers
+### Step 2: Configure brokers
To configure a Pulsar [broker](reference-terminology.md#broker) to use TLS
encryption, you need to add these values to `broker.conf` in the `conf`
directory of your Pulsar installation. Substitute the appropriate certificate
paths where necessary.
@@ -227,7 +230,7 @@ For JDK 11, you can obtain a list of supported values from
the documentation:
- [TLS
protocol](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2__SUNJSSEPROVIDERPROTOCOLPARAMETERS-BBF75009)
-
[Ciphers](https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2__SUNJSSE_CIPHER_SUITES)
-### Configure proxies
+### Step 3: Configure proxies
Configuring mTLS on proxies includes two directions of connections, from
clients to proxies, and from proxies to brokers.
@@ -251,7 +254,7 @@ brokerClientCertificateFilePath=/path/to/client.cert.pem
brokerClientKeyFilePath=/path/to/client.key-pk8.pem
```
-### Configure clients
+### Step 4: Configure clients
To enable TLS encryption, you need to configure the clients to use `https://`
with port 8443 for the web service URL, and `pulsar+ssl://` with port 6651 for
the broker service URL.
@@ -394,7 +397,7 @@ In addition to the required configurations in the
`conf/client.conf` file, you n
</Tabs>
````
-### Configure CLI tools
+### Step 5: Configure CLI tools
[Command-line tools](reference-cli-tools.md) like
[`pulsar-admin`](pathname:///reference/#/@pulsar:version_reference@/pulsar-admin/),
[`pulsar-perf`](pathname:///reference/#/@pulsar:version_reference@/pulsar-perf/),
and
[`pulsar-client`](pathname:///reference/#/@pulsar:version_reference@/pulsar-client/)
use the `conf/client.conf` config file in a Pulsar installation.
@@ -411,7 +414,9 @@
authParams=tlsCertFile:/path/to/client.cert.pem,tlsKeyFile:/path/to/client.key-p
By default, Pulsar uses [Conscrypt](https://github.com/google/conscrypt) for
both broker service and Web service.
-### Generate JKS certificate
+To configure mTLS encryption with KeyStore, complete the following steps:
+
+### Step 1: Generate JKS certificate
You can use Java's `keytool` utility to generate the key and certificate for
each machine in the cluster.
@@ -442,7 +447,7 @@ To configure [hostname
verification](#hostname-verification), you need to append
:::
-### Configure brokers
+### Step 2: Configure brokers
Configure the following parameters in the `conf/broker.conf` file and restrict
access to the store files via filesystem permissions.
@@ -486,7 +491,7 @@ The default value of `tlsRequireTrustedClientCertOnConnect`
is `false`, which re
:::
-### Configure proxies
+### Step 3: Configure proxies
Configuring mTLS on proxies includes two directions of connections, from
clients to proxies, and from proxies to brokers.
@@ -518,7 +523,7 @@ brokerClientTlsKeyStore=/var/private/tls/client.keystore.jks
brokerClientTlsKeyStorePassword=clientpw
```
-### Configure clients
+### Step 4: Configure clients
Similar to [Configure mTLS encryption with PEM](#configure-clients), you need
to provide the TrustStore information for a minimal configuration.
@@ -573,7 +578,7 @@ If you set `useKeyStoreTls` to `true`, be sure to configure
`tlsTrustStorePath`.
</Tabs>
````
-### Configure CLI tools
+### Step 5: Configure CLI tools
For [Command-line tools](reference-cli-tools.md) like
[`pulsar-admin`](pathname:///reference/#/@pulsar:version_reference@/pulsar-admin/),
[`pulsar-perf`](pathname:///reference/#/@pulsar:version_reference@/pulsar-perf/),
and
[`pulsar-client`](pathname:///reference/#/@pulsar:version_reference@/pulsar-client/),
use the `conf/client.conf` config file in a Pulsar installation.
