Correct auth_mechanisms examples for rabbitmq.conf

Author: michaelklishin

docs/access-control.md

@@ -814,7 +814,7 @@ The built-in mechanisms are:
       configured in <code>anonymous_login_user</code> and <code>anonymous_login_pass</code> (both are set to <code>guest</code> by default).
       In other words, any unauthenticated client will be able to connect and act as the configured <code>anonymous_login_user</code>.
       <strong>For production environments, remove this mechanism.</strong>
-      See the [production checklist](http://localhost:3000/docs/next/production-checklist#anonymous-login) documentation.
+      See the [Deployment Guidelines](http://localhost:3000/docs/next/production-checklist#anonymous-login) documentation.
     </td>
   </tr>
 
@@ -838,12 +838,20 @@ The built-in mechanisms are:
 
 ### Mechanism Configuration in the Server {#server-mechanism-configuration}
 
-The configuration variable <code>auth_mechanisms</code> in
-the <code>rabbit</code> application determines which of the
-installed mechanisms are offered to connecting clients. This
-variable should be a list of atoms corresponding to
-mechanism names, for example
-<code>['PLAIN', 'AMQPLAIN', 'ANONYMOUS']</code> by default.
+The <code>auth_mechanisms</code> configuration key determines which of the
+installed mechanisms are offered to connecting clients.
+
+This variable should be a list of accepted values corresponding to
+mechanism names, for example, the following list
+
+``` ini
+auth_mechanisms.1 = PLAIN
+auth_mechanisms.2 = AMQPLAIN
+auth_mechanisms.3 = ANONYMOUS
+```
+
+is used by default.
+
 The server mechanisms are ordered in decreasing level of preference.
 See the [configuration file](./configure#configuration-files) documentation.
 

docs/configure.md

@@ -48,7 +48,7 @@ and more.
 
 Since configuration affects many areas of the system, including plugins, individual [documentation guides](./index.md)
 dive deeper into what can be configured. [Runtime Tuning](./runtime) is a companion to this guide that focuses
-on the configurable parameters in the runtime. [Production Checklist](./production-checklist) is a related guide
+on the configurable parameters in the runtime. [Deployment Guidelines](./production-checklist) is a related guide
 that outlines what settings will likely need tuning in most production environments.
 
 
@@ -1113,8 +1113,10 @@ management_db_cache_multiplier = 5
       <p>
         Default:
 ```ini
+# see the Access Control guide to learn more
 auth_mechanisms.1 = PLAIN
 auth_mechanisms.2 = AMQPLAIN
+# see the Access Control and Deployment Guidelines guides to learn more
 auth_mechanisms.3 = ANONYMOUS
 ```
       </p>
@@ -2305,7 +2307,7 @@ and more. To Linux users these limits can be known as "ulimit limits".
 
 RabbitMQ nodes are most commonly affected by the maximum [open file handle limit](./networking#open-file-handle-limit).
 Default limit value on most Linux distributions is usually 1024, which is very low for a messaging broker (or generally, any data service).
-See [Production Checklist](./production-checklist) for recommended values.
+See [Deployment Guidelines](./production-checklist) for recommended values.
 
 ### Modifying Limits
 

docs/ec2.md

@@ -118,5 +118,5 @@ Several other guides cover topics highly relevant for running RabbitMQ clusters
  * [Peer Discovery](./cluster-formation)
  * [Configuration](./configure)
  * [Monitoring](./monitoring)
- * [Production Checklist](./production-checklist)
+ * [Deployment Guidelines](./production-checklist)
  * [File and Directory Locations](./relocate)

docs/install-debian.md

@@ -892,7 +892,7 @@ systemctl start rabbitmq-server
 
 On most systems, a node should be able to start and run with all defaults.
 Please refer to the [Configuration guide](./configure) to learn more
-and [Production Checklist](./production-checklist) for guidelines beyond
+and [Deployment Guidelines](./production-checklist) for guidelines beyond
 development environments.
 
 Note: the node is set up to run as system user `rabbitmq`.

docs/install-rpm.md

@@ -520,7 +520,7 @@ systemctl stop rabbitmq-server
 
 On most systems, a node should be able to start and run with all defaults.
 Please refer to the [Configuration guide](./configure) to learn more
-and [Production Checklist](./production-checklist) for guidelines beyond
+and [Deployment Guidelines](./production-checklist) for guidelines beyond
 development environments.
 
 Note: the node is set up to run as system user `rabbitmq`.

docs/management/index.md

@@ -194,7 +194,7 @@ it from connecting clients. In addition to successful authentication, management
 The tags are managed using [rabbitmqctl](./man/rabbitmqctl.8#set_user_tags).
 Newly created users do not have any tags set on them by default.
 
-See [Production Checklist](./production-checklist) for general recommendations on user and credential
+See [Deployment Guidelines](./production-checklist) for general recommendations on user and credential
 management.
 
 <table>
@@ -355,7 +355,7 @@ rabbitmqctl set_permissions --vhost "vhost-name" "monitoring" "^$" "^$" "^$"
 
 ## Authenticating with OAuth 2 {#oauth2-authentication}
 
-You can configure RabbitMQ to use [JWT-encoded OAuth 2.0 access tokens](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_auth_backend_oauth2) to authenticate client applications, however, to use OAuth 2.0 authentication in the management UI, you have to configure it separately. 
+You can configure RabbitMQ to use [JWT-encoded OAuth 2.0 access tokens](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_auth_backend_oauth2) to authenticate client applications, however, to use OAuth 2.0 authentication in the management UI, you have to configure it separately.
 
 There are two ways to initiate OAuth 2.0 authentication in the management UI:
 - *Service-Provided Initiated login*. The is the OAuth method and the default way to initiate authentication in the management UI. It uses the [OAuth 2.0 Authorization Code Flow with PKCE](https://datatracker.ietf.org/doc/html/rfc7636) to redirect users to the configured OAuth 2.0 provider to authenticate. When they are authenticated, users get an access token, and are then returned back to the management UI where they are automatically logged in. The management UI is tested against these OAuth 2.0 providers:
@@ -403,13 +403,13 @@ management.oauth_scopes = <SPACE-SEPARATED LIST OF SCOPES. See below>
 - `oauth_scopes` is a mandatory field which must be set at all times except in the case when OAuth providers automatically grant scopes associated to the `oauth_client_id`. `oauth_scopes` is a list of space-separated strings that indicate which permissions the application is requesting. Most OAuth providers only issue tokens with the scopes requested during the user authentication. RabbitMQ sends this field along with its `oauth_client_id` during the user authentication. If this field is not set, RabbitMQ defaults to `openid profile`.
 
 Given above configuration, when a user visits the management UI, the following two events take place:
-1. RabbitMQ uses the URL found in `auth_oauth2.issuer` followed by the path `/.well-known/openid-configuration` to download the OpenID Provider configuration. It contains information about other endpoints such as the `jwks_uri` (used to download the keys to validate the token's signature) or the `token_endpoint`. 
+1. RabbitMQ uses the URL found in `auth_oauth2.issuer` followed by the path `/.well-known/openid-configuration` to download the OpenID Provider configuration. It contains information about other endpoints such as the `jwks_uri` (used to download the keys to validate the token's signature) or the `token_endpoint`.
 
     :::warning
     If RabbitMQ cannot download the OpenID provider configuration, it shows an error message and OAuth 2.0 authentication is disabled in the management UI.
     :::
 
-2. RabbitMQ displays a button with the label "Click here to login". When the user clicks on the button, the management UI initiates the OAuth 2.0 Authorization Code Flow, which redirects the user to the identity provider to authenticate and get a token. 
+2. RabbitMQ displays a button with the label "Click here to login". When the user clicks on the button, the management UI initiates the OAuth 2.0 Authorization Code Flow, which redirects the user to the identity provider to authenticate and get a token.
 
 ### Configure client secret {#configure-client-secret}
 
@@ -490,7 +490,7 @@ The management UI shows now a username/password login form for Basic Authenticat
 RabbitMQ implements the [OpenID Connect RP-Initiated Logout 1.0](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)
 specification to logout users from the management UI and from the OAuth Provider. It works as follows:
 
-  1. The user clicks **Logout**. 
+  1. The user clicks **Logout**.
   2. If the [OpenId Connect Discovery endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest) returns an `end_session_endpoint`, the management UI sends a logout request to that endpoint to close the user's session in the OAuth Provider. When the request completes, the user is also logged out from the management ui.
   3. If there is no `end_session_endpoint` returned, then the user is only logged out from the management UI.
 
@@ -499,7 +499,7 @@ If the [OpenId Connect Discovery endpoint](https://openid.net/specs/openid-conne
 :::
 
 :::warning
-RabbitMQ 3.13.1 and earlier versions require the [OpenId Connect Discovery endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest) `end_session_endpoint` returned for OAuth 2.0 authentication to work. 
+RabbitMQ 3.13.1 and earlier versions require the [OpenId Connect Discovery endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest) `end_session_endpoint` returned for OAuth 2.0 authentication to work.
 :::
 
 There are other two additional scenarios which can trigger a logout. One scenario occurs when the OAuth Token expires. Although RabbitMQ renews the token in the background before it expires, if the token expires, the user is logged out.

docs/memory.md

@@ -252,7 +252,7 @@ want RabbitMQ to throttle producers when the server is using
 above 3GB, set `vm_memory_high_watermark` to 3.
 
 For guidelines on recommended RAM watermark settings,
-see [Production Checklist](./production-checklist#resource-limits-ram).
+see [Deployment Guidelines](./production-checklist#resource-limits-ram).
 
 
 ## CQv1: Configuring the Paging Threshold {#paging}

docs/production-checklist.md

@@ -30,7 +30,7 @@ important to assess system configuration and have a plan for "day two operations
 activities such as [upgrades](./upgrade) before going into production.
 
 
-## Overview {#toc}
+## Table of Contents {#toc}
 
 Production systems have concerns that go beyond configuration: system observability,
 security, application development practices, resource usage, [release support timeline](/release-information), and more.
@@ -145,12 +145,14 @@ function and having fixed IP addresses, it may make sense to [authenticate using
 
 ### Anonymous Login
 
-For production environments, prohibit anonymous logins.
+For production environments, it is almost always a good idea to disable anonymous logins.
 
-You can disallow [SASL mechansim](access-control#mechanisms) `ANONYMOUS` in [rabbitmq.conf](configure#config-file) as follows:
-```
-# Remove 'ANONYMOUS' from the list of advertised SASL mechanisms, e.g.
-auth_mechanisms = ['PLAIN', 'AMQPLAIN']
+You can disable the `ANONYMOUS` [SASL mechansim](access-control#mechanisms) in [rabbitmq.conf](configure#config-file) as follows:
+
+``` ini
+auth_mechanisms.1 = PLAIN
+auth_mechanisms.2 = AMQPLAIN
+# note: the ANONYMOUS mechanism is not listed
 
 # Value none has a special meaning that no user is configured for anonymous logins.
 anonymous_login_user = none
@@ -361,17 +363,17 @@ Production environments may require network configuration
 tuning, for example, to sustain a high number of concurrent clients.
 Please refer to the [Networking Guide](./networking) for details.
 
-### <a id="networking-throughput" class="anchor" href="#networking-throughput">Minimum Available Network Throughput Estimate</a>
+### Minimum Available Network Throughput Estimate {#networking-throughput}
 
 With higher message rates and large message payloads, traffic bandwidth available to cluster nodes becomes an important
 factor.
 
 The following (intentionally oversimplified) formula can be used to compute the **minimum amount of bandwidth**
 that must be available to cluster nodes, in bits per second:
 
-<pre class="lang-ini">
+``` ini
 MR * MS * 110% * 8
-</pre>
+```
 
 where
 
@@ -382,9 +384,9 @@ where
 
 For example, with a message rate (`MR`) of 20K per second and 6 KB message payloads (`MS`):
 
-<pre class="lang-ini">
+``` ini
 20K * 6 KB * 110% * 8 bit/B = 20000 * 6000 * 1.1 * 8 = 1.056 (gigabit/second)
-</pre>
+```
 
 With the above inputs, cluster nodes must have network links with throughput of at least 1.056 gigabit per second.
 

docs/queues.md

@@ -372,7 +372,7 @@ via a message property (<code>delivery_mode</code> or, in some clients, <code>pe
 
 Other relevant guides on the topic are [Quorum Queues](./quorum-queues#resource-use), [Streams](./streams#feature-comparison),
 [Reasoning About Memory Usage](./memory-use), [Alarms](./alarms), [Memory Alarms](./memory), [Free Disk Space Alarms](./disk-alarms),
-[Production Checklist](./production-checklist), and [Message Store Configuration](./persistence-conf).
+[Deployment Guidelines](./production-checklist), and [Message Store Configuration](./persistence-conf).
 
 
 ## Priorities {#priorities}

versioned_docs/version-3.13/configure.md

@@ -48,7 +48,7 @@ and more.
 
 Since configuration affects many areas of the system, including plugins, individual [documentation guides](./index.md)
 dive deeper into what can be configured. [Runtime Tuning](./runtime) is a companion to this guide that focuses
-on the configurable parameters in the runtime. [Production Checklist](./production-checklist) is a related guide
+on the configurable parameters in the runtime. [Deployment Guidelines](./production-checklist) is a related guide
 that outlines what settings will likely need tuning in most production environments.
 
 
@@ -2320,7 +2320,7 @@ and more. To Linux users these limits can be known as "ulimit limits".
 
 RabbitMQ nodes are most commonly affected by the maximum [open file handle limit](./networking#open-file-handle-limit).
 Default limit value on most Linux distributions is usually 1024, which is very low for a messaging broker (or generally, any data service).
-See [Production Checklist](./production-checklist) for recommended values.
+See [Deployment Guidelines](./production-checklist) for recommended values.
 
 ### Modifying Limits
 

versioned_docs/version-3.13/ec2.md

@@ -118,5 +118,5 @@ Several other guides cover topics highly relevant for running RabbitMQ clusters
  * [Peer Discovery](./cluster-formation)
  * [Configuration](./configure)
  * [Monitoring](./monitoring)
- * [Production Checklist](./production-checklist)
+ * [Deployment Guidelines](./production-checklist)
  * [File and Directory Locations](./relocate)

versioned_docs/version-3.13/install-debian.md

@@ -892,7 +892,7 @@ systemctl start rabbitmq-server
 
 On most systems, a node should be able to start and run with all defaults.
 Please refer to the [Configuration guide](./configure) to learn more
-and [Production Checklist](./production-checklist) for guidelines beyond
+and [Deployment Guidelines](./production-checklist) for guidelines beyond
 development environments.
 
 Note: the node is set up to run as system user `rabbitmq`.

versioned_docs/version-3.13/install-rpm.md

@@ -520,7 +520,7 @@ systemctl stop rabbitmq-server
 
 On most systems, a node should be able to start and run with all defaults.
 Please refer to the [Configuration guide](./configure) to learn more
-and [Production Checklist](./production-checklist) for guidelines beyond
+and [Deployment Guidelines](./production-checklist) for guidelines beyond
 development environments.
 
 Note: the node is set up to run as system user `rabbitmq`.