Merge branch 'master' into rabbitmq-server-995

1 files changed, 81 insertions, 53 deletions

diff --git a/docs/rabbitmq.config.example b/docs/rabbitmq.config.example
index 60af5b7eea..3d41ae138c 100644
--- a/docs/rabbitmq.config.example
+++ b/docs/rabbitmq.config.example
@@ -2,14 +2,16 @@
 %% ----------------------------------------------------------------------------
 %% RabbitMQ Sample Configuration File.
 %%
-%% See http://www.rabbitmq.com/configure.html for details.
+%% Related doc guide: http://www.rabbitmq.com/configure.html. See
+%% http://rabbitmq.com/documentation.html for documentation ToC.
 %% ----------------------------------------------------------------------------
 [
  {rabbit,
   [%%
-   %% Network Connectivity
+   %% Networking
    %% ====================
    %%
+   %% Related doc guide: http://www.rabbitmq.com/networking.html.
 
    %% By default, RabbitMQ will listen on all interfaces, using
    %% the standard (reserved) AMQP port.
@@ -22,19 +24,19 @@
    %% {tcp_listeners, [{"127.0.0.1", 5672},
    %%                  {"::1",       5672}]},
 
-   %% SSL listeners are configured in the same fashion as TCP listeners,
+   %% TLS listeners are configured in the same fashion as TCP listeners,
    %% including the option to control the choice of interface.
    %%
    %% {ssl_listeners, [5671]},
 
    %% Number of Erlang processes that will accept connections for the TCP
-   %% and SSL listeners.
+   %% and TLS listeners.
    %%
    %% {num_tcp_acceptors, 10},
    %% {num_ssl_acceptors, 1},
 
    %% Maximum time for AMQP 0-8/0-9/0-9-1 handshake (after socket connection
-   %% and SSL handshake), in milliseconds.
+   %% and TLS handshake), in milliseconds.
    %%
    %% {handshake_timeout, 10000},
 
@@ -45,9 +47,10 @@
    %% {reverse_dns_lookups, false},
 
    %%
-   %% Security / AAA
-   %% ==============
+   %% Security, Access Control
+   %% ========================
    %%
+   %% Related doc guide: http://www.rabbitmq.com/access-control.html.
 
    %% The default "guest" user is only permitted to access the server
    %% via a loopback interface (e.g. localhost).
@@ -57,8 +60,10 @@
    %% guest user from anywhere on the network.
    %% {loopback_users, []},
 
-   %% Configuring SSL.
-   %% See http://www.rabbitmq.com/ssl.html for full documentation.
+
+   %% TLS configuration.
+   %%
+   %% Related doc guide: http://www.rabbitmq.com/ssl.html.
    %%
    %% {ssl_options, [{cacertfile,           "/path/to/testca/cacert.pem"},
    %%                {certfile,             "/path/to/server/cert.pem"},
@@ -71,7 +76,7 @@
    %% 'AMQPLAIN'. Additional mechanisms can be added via
    %% plugins.
    %%
-   %% See http://www.rabbitmq.com/authentication.html for more details.
+   %% Related doc guide: http://www.rabbitmq.com/authentication.html.
    %%
    %% {auth_mechanisms, ['PLAIN', 'AMQPLAIN']},
 
@@ -84,10 +89,10 @@
    %% rabbitmq_auth_backend_ldap plugins.
    %%
    %% NB: These options require that the relevant plugin is enabled.
-   %% See http://www.rabbitmq.com/plugins.html for further details.
+   %% Related doc guide: http://www.rabbitmq.com/plugins.html for further details.
 
    %% The RabbitMQ-auth-mechanism-ssl plugin makes it possible to
-   %% authenticate a user based on the client's SSL certificate.
+   %% authenticate a user based on the client's TLS certificate.
    %%
    %% To use auth-mechanism-ssl, add to or replace the auth_mechanisms
    %% list with the entry 'EXTERNAL'.
@@ -112,11 +117,11 @@
    %% https://github.com/rabbitmq/rabbitmq-auth-mechanism-ssl for further
    %% details.
    %%
-   %% To use the SSL cert's CN instead of its DN as the username
+   %% To use the TLS cert's CN instead of its DN as the username
    %%
    %% {ssl_cert_login_from, distinguished_name},
 
-   %% SSL handshake timeout, in milliseconds.
+   %% TLS handshake timeout, in milliseconds.
    %%
    %% {ssl_handshake_timeout, 5000},
 
@@ -138,7 +143,7 @@
    %% {password_hashing_module, rabbit_password_hashing_sha256},
 
    %% Configuration entry encryption.
-   %% See http://www.rabbitmq.com/configure.html#configuration-encryption
+   %% Related doc guide: http://www.rabbitmq.com/configure.html#configuration-encryption
    %%
    %% To specify the passphrase in the configuration file:
    %%
@@ -175,8 +180,7 @@
 
    %% Tags for default user
    %%
-   %% For more details about tags, see the documentation for the
-   %% Management Plugin at http://www.rabbitmq.com/management.html.
+   %% Related doc guide: http://www.rabbitmq.com/management.html.
    %%
    %% {default_user_tags, [administrator]},
 
@@ -188,7 +192,11 @@
    %% Sets the default AMQP 0-9-1 heartbeat timeout in seconds.
    %% Values lower than 6 can produce false positives and are not
    %% recommended.
-   %% See http://www.rabbitmq.com/heartbeats.html.
+   %%
+   %% Related doc guides:
+   %%
+   %%  * http://www.rabbitmq.com/heartbeats.html
+   %%  * http://www.rabbitmq.com/networking.html
    %%
    %% {heartbeat, 60},
 
@@ -206,9 +214,28 @@
    %%
    %% {channel_max, 0},
 
+   %% Set the max permissible number of client connections to the node.
+   %% `infinity` means "no limit".
+   %%
+   %% This limit applies to client connections to all listeners (regardless of
+   %% the protocol, whether TLS is used and so on). CLI tools and inter-node
+   %% connections are exempt.
+   %%
+   %% When client connections are rapidly opened in succession, it is possible
+   %% for the total connection count to go slightly higher than the configured limit.
+   %% The limit works well as a general safety measure.
+   %%
+   %% Clients that are hitting the limit will see their TCP connections fail or time out.
+   %%
+   %% Introduced in 3.6.13.
+   %%
+   %% Related doc guide: http://www.rabbitmq.com/networking.html.
+   %%
+   %% {connection_max, infinity},
+
    %% TCP socket options.
    %%
-   %% See http://www.rabbitmq.com/networking.html.
+   %% Related doc guide: http://www.rabbitmq.com/networking.html.
    %%
    %% {tcp_listen_options, [{backlog,       128},
    %%                       {nodelay,       true},
@@ -218,7 +245,7 @@
    %% Resource Limits & Flow Control
    %% ==============================
    %%
-   %% See http://www.rabbitmq.com/memory.html for full details.
+   %% Related doc guide: http://www.rabbitmq.com/memory.html, http://www.rabbitmq.com/memory-use.html.
 
    %% Memory-based Flow Control threshold.
    %%
@@ -258,9 +285,9 @@
    %%
    %% {vm_memory_high_watermark_paging_ratio, 0.5},
 
-   %% Selects Erlang VM memory consumption calculation strategy. Can be `rss` or `erlang`,
-   %% `rss` is the default. Introduced in 3.6.11.
-   %% See https://github.com/rabbitmq/rabbitmq-server/issues/1223 for background.
+   %% Selects Erlang VM memory consumption calculation strategy. Can be `allocated`, `rss` or `legacy` (aliased as `erlang`),
+   %% Introduced in 3.6.11. `rss` is the default as of 3.6.12.
+   %% See https://github.com/rabbitmq/rabbitmq-server/issues/1223 and rabbitmq/rabbitmq-common#224 for background.
    %% {vm_memory_calculation_strategy, rss},
 
    %% Interval (in milliseconds) at which we perform the check of the memory
@@ -298,12 +325,13 @@
    %%   * <<"min-masters">>
    %%   * <<"client-local">>
    %%   * <<"random">>
-   %% See https://www.rabbitmq.com/ha.html#queue-master-location
+   %%
+   %% Related doc guide: https://www.rabbitmq.com/ha.html#queue-master-location
    %%
    %% {queue_master_locator, <<"client-local">>},
 
    %% Batch size (number of messages) used during eager queue mirror synchronisation.
-   %% See https://www.rabbitmq.com/ha.html#batch-sync. When average message size is relatively large
+   %% Related doc guide: https://www.rabbitmq.com/ha.html#batch-sync. When average message size is relatively large
    %% (say, 10s of kilobytes or greater), reducing this value will decrease peak amount
    %% of RAM used by newly joining nodes that need eager synchronisation.
    %%
@@ -321,7 +349,7 @@
    %% {server_properties, []},
 
    %% How to respond to cluster partitions.
-   %% See http://www.rabbitmq.com/partitions.html
+   %% Related doc guide: http://www.rabbitmq.com/partitions.html
    %%
    %% {cluster_partition_handling, ignore},
 
@@ -333,7 +361,7 @@
 
    %% Make clustering happen *automatically* at startup - only applied
    %% to nodes that have just been reset or started for the first time.
-   %% See http://www.rabbitmq.com/clustering.html#auto-config
+   %% Related doc guide: http://www.rabbitmq.com/clustering.html#auto-config
    %%
    %% {cluster_nodes, {['rabbit@my.host.com'], disc}},
 
@@ -385,12 +413,12 @@
    %% {mnesia_table_loading_retry_timeout, 30000},
 
    %% Size in bytes below which to embed messages in the queue index.
-   %% See http://www.rabbitmq.com/persistence-conf.html
+   %% Related doc guide: http://www.rabbitmq.com/persistence-conf.html
    %%
    %% {queue_index_embed_msgs_below, 4096},
 
    %% Maximum number of queue index entries to keep in journal
-   %% See http://www.rabbitmq.com/persistence-conf.html.
+   %% Related doc guide: http://www.rabbitmq.com/persistence-conf.html.
    %%
    %% {queue_index_max_journal_entries, 32768},
 
@@ -415,7 +443,7 @@
    %% Increasing these values may help with throughput but also can be dangerous:
    %% high credit flow values are no different from not having flow control at all.
    %%
-   %% See https://www.rabbitmq.com/blog/2015/10/06/new-credit-flow-settings-on-rabbitmq-3-5-5/
+   %% Related doc guide: https://www.rabbitmq.com/blog/2015/10/06/new-credit-flow-settings-on-rabbitmq-3-5-5/
    %% and http://alvaro-videla.com/2013/09/rabbitmq-internals-credit-flow-for-erlang-processes.html.
    %%
    %% {credit_flow_default_credit, {400, 200}},
@@ -473,7 +501,7 @@
  %% ----------------------------------------------------------------------------
  %% Advanced Erlang Networking/Clustering Options.
  %%
- %% See http://www.rabbitmq.com/clustering.html for details
+ %% Related doc guide: http://www.rabbitmq.com/clustering.html
  %% ----------------------------------------------------------------------------
  {kernel,
   [%% Sets the net_kernel tick time.
@@ -486,22 +514,22 @@
  %% ----------------------------------------------------------------------------
  %% RabbitMQ Management Plugin
  %%
- %% See http://www.rabbitmq.com/management.html for details
+ %% Related doc guide: http://www.rabbitmq.com/management.html
  %% ----------------------------------------------------------------------------
 
  {rabbitmq_management,
-  [%% Pre-Load schema definitions from the following JSON file. See
+  [%% Preload schema definitions from a previously exported definitions file. See
    %% http://www.rabbitmq.com/management.html#load-definitions
    %%
-   %% {load_definitions, "/path/to/schema.json"},
+   %% {load_definitions, "/path/to/exported/definitions.json"},
 
-   %% Log all requests to the management HTTP API to a file.
+   %% Log all requests to the management HTTP API to a directory.
    %%
-   %% {http_log_dir, "/path/to/access.log"},
+   %% {http_log_dir, "/path/to/rabbitmq/logs/http"},
 
    %% Change the port on which the HTTP listener listens,
    %% specifying an interface for the web server to bind to.
-   %% Also set the listener to use SSL and provide SSL options.
+   %% Also set the listener to use TLS and provide TLS options.
    %%
    %% {listener, [{port,     12345},
    %%             {ip,       "127.0.0.1"},
@@ -528,7 +556,7 @@
  %% ----------------------------------------------------------------------------
  %% RabbitMQ Shovel Plugin
  %%
- %% See http://www.rabbitmq.com/shovel.html for details
+ %% Related doc guide: http://www.rabbitmq.com/shovel.html
  %% ----------------------------------------------------------------------------
 
  {rabbitmq_shovel,
@@ -594,9 +622,9 @@
   ]},
 
  %% ----------------------------------------------------------------------------
- %% RabbitMQ Stomp Adapter
+ %% RabbitMQ STOMP Plugin
  %%
- %% See http://www.rabbitmq.com/stomp.html for details
+ %% Related doc guide: http://www.rabbitmq.com/stomp.html
  %% ----------------------------------------------------------------------------
 
  {rabbitmq_stomp,
@@ -606,18 +634,18 @@
    %% {tcp_listeners, [{"127.0.0.1", 61613},
    %%                  {"::1",       61613}]},
 
-   %% Listen for SSL connections on a specific port.
+   %% Listen for TLS connections on a specific port.
    %% {ssl_listeners, [61614]},
 
    %% Number of Erlang processes that will accept connections for the TCP
-   %% and SSL listeners.
+   %% and TLS listeners.
    %%
    %% {num_tcp_acceptors, 10},
    %% {num_ssl_acceptors, 1},
 
-   %% Additional SSL options
+   %% Additional TLS options
 
-   %% Extract a name from the client's certificate when using SSL.
+   %% Extract a name from the client's certificate when using TLS.
    %%
    %% {ssl_cert_login, true},
 
@@ -630,11 +658,11 @@
    %% {default_user, [{login,    "guest"},
    %%                 {passcode, "guest"}]},
 
-   %% If a default user is configured, or you have configured use SSL client
+   %% If a default user is configured, or you have configured use TLS client
    %% certificate based authentication, you can choose to allow clients to
    %% omit the CONNECT frame entirely. If set to true, the client is
    %% automatically connected as the default user or user supplied in the
-   %% SSL certificate whenever the first frame sent on a session is not a
+   %% TLS certificate whenever the first frame sent on a session is not a
    %% CONNECT frame.
    %%
    %% {implicit_connect, true},
@@ -651,10 +679,10 @@
   ]},
 
  %% ----------------------------------------------------------------------------
- %% RabbitMQ MQTT Adapter
+ %% RabbitMQ MQTT Plugin
+ %%
+ %% Related doc guide: https://github.com/rabbitmq/rabbitmq-mqtt/blob/stable/README.md
  %%
- %% See https://github.com/rabbitmq/rabbitmq-mqtt/blob/stable/README.md
- %% for details
  %% ----------------------------------------------------------------------------
 
  {rabbitmq_mqtt,
@@ -727,8 +755,8 @@
  %% ----------------------------------------------------------------------------
  %% RabbitMQ AMQP 1.0 Support
  %%
- %% See https://github.com/rabbitmq/rabbitmq-amqp1.0/blob/stable/README.md
- %% for details
+ %% Related doc guide: https://github.com/rabbitmq/rabbitmq-amqp1.0/blob/stable/README.md
+ %%
  %% ----------------------------------------------------------------------------
 
  {rabbitmq_amqp1_0,
@@ -748,7 +776,7 @@
  %% ----------------------------------------------------------------------------
  %% RabbitMQ LDAP Plugin
  %%
- %% See http://www.rabbitmq.com/ldap.html for details.
+ %% Related doc guide: http://www.rabbitmq.com/ldap.html.
  %%
  %% ----------------------------------------------------------------------------
 
@@ -763,7 +791,7 @@
    %%
    %% {servers, ["your-server-name-goes-here"]},
 
-   %% Connect to the LDAP server using SSL
+   %% Connect to the LDAP server using TLS
    %%
    %% {use_ssl, false},