hachikuji commented on code in PR #12682:
URL: https://github.com/apache/kafka/pull/12682#discussion_r980518429
##########
docs/security.html:
##########
@@ -36,7 +36,104 @@ <h3 class="anchor-heading"><a id="security_overview"
class="anchor-link"></a><a
The guides below explain how to configure and use the security features in
both clients and brokers.
- <h3 class="anchor-heading"><a id="security_ssl" class="anchor-link"></a><a
href="#security_ssl">7.2 Encryption and Authentication using SSL</a></h3>
+ <h3 class="anchor-heading"><a id="listener_configuration"
class="anchor-link"></a><a href="#listener_configuration">7.2 Listener
Configuration</a></h3>
+
+ <p>In order to secure a Kafka cluster, it is necessary to secure the
channels that are used to
+ communicate with the servers. Each node must define the set of listeners
that are used to
+ receive requests from clients as well as other servers. Each listener
may be configured
+ to authenticate clients using various mechanisms and to ensure traffic
between the
+ server and the client is encrypted. This section provides a primer for
the configuration
+ of listeners.</p>
+
+ <p>Kafka brokers support listening for connections on multiple ports. This
is configured through
+ the <code>listeners</code> property in the server configuration, which
accepts a comma-separated
+ list of the listeners to enable. At least one listener must be defined
on each node. The format
+ of each listener defined in <code>listeners</code> is given below:</p>
+
+ <pre class="line-numbers"><code
class="language-text">{LISTENER_NAME}://{hostname}:{port}</code></pre>
+
+ <p>The <code>LISTENER_NAME</code> is usually a descriptive name which
defines the purpose of
+ the listener. For example, many configurations use a separate listener
for client traffic,
+ so they might refer to the corresponding listener as <code>CLIENT</code>
in the configuration:</p
+
+ <pre class="line-numbers"><code
class="language-text">listeners=CLIENT://localhost:9092</code></pre>
+
+ <p>The security protocol of each listener is defined in a separate
configuration:
+ <code>listener.security.protocol.map</code>. The value is a
comma-separated list
+ of each listener mapped to its security protocol. For example, the
follow value
+ configuration specifies that the <code>CLIENT</code> listener will use
SSL while the
+ <code>BROKER</code> listener will use plaintext.</p>
+
+ <pre class="line-numbers"><code
class="language-text">listener.security.protocol.map=CLIENT:SSL,BROKER:PLAINTEXT</code></pre>
+
+ <p>Possible options for the security protocol are given below:</p>
+ <ol>
+ <li>PLAINTEXT</li>
+ <li>SSL</li>
+ <li>SASL_PLAINTEXT</li>
+ <li>SASL_SSL</li>
+ </ol>
+
+ <p>The plaintext protocol provides no security and does not require any
additional configuration.
+ In the following sections, this document covers how to configure the
remaining protocols.</p>
+
+ <p>If each required listener uses a separate security protocol, it is also
possible to use the
+ security protocol name as the listener name in <code>listeners</code>.
Using the example above,
+ we could skip the definition of the <code>CLIENT</code> and
<code>BROKER</code> listeners
+ using the following definition:</p>
+
+ <pre class="line-numbers"><code
class="language-text">listeners=SSL://localhost:9092,PLAINTEXT://localhost:9093</code></pre>
+
+ <p>However, we recommend users to provide explicit names for the listeners
since it
+ makes the intended usage clearer.</p>
Review Comment:
Below we still have references to this approach, so I wanted to mention it.
In a subsequent patch, I was going to clean up those sections as well, so maybe
we can remove this then as well.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscr...@kafka.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
