Networking guide edits

rabbitmq · Sep 10, 2024 · d8d3dd9 · d8d3dd9
1 parent 83c926d
commit d8d3dd9
Show file tree

Hide file tree

Showing 6 changed files with 122 additions and 24 deletions.
diff --git a/docs/cluster-formation.md b/docs/cluster-formation.md
@@ -307,6 +307,10 @@ Podman is one known example of a tool that can perform such host file modificati
 In order to avoid this, set its [`host_containers_internal_ip` setting](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)
 must be set to a blank string.
 
+In environments where container-level settings cannot be tuned, the runtime
+can be [configured to ignore the standard local hosts file](./networking#the-inetrc-file)
+and only use DNS or a pre-configured set of hostname-to-IP address mappings.
+
 
 ## Peer Discovery on AWS (EC2) {#peer-discovery-aws}
 

diff --git a/docs/configure.md b/docs/configure.md
@@ -2174,18 +2174,28 @@ More variables are covered in the [File and Directory Locations guide](./relocat
     <td>
       Standard parameters for the `erl` command used when
       invoking the RabbitMQ Server. This should be overridden for
-      debugging purposes only. Overriding this variable
-      *replaces* the default value.
+      debugging purposes only.
+
+      :::danger
+
+      Setting this variable will replace the defaults provided by RabbitMQ.
+
+      :::
+
+      :::tip
+
+      Consider using `RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS` to add or override individual settings instead.
+
+      :::
 
       <p>
         <strong>Default</strong>:
 
         <ul>
           <li>
-          **Unix*:**
-            `+P 1048576 +t 5000000 +stbt db +zdbbl 128000`
+          **UNIX**: `+P 1048576 +t 5000000 +stbt db +zdbbl 128000`
           </li>
-          <li>**Windows:** None</li>
+          <li>**Windows**: (none)</li>
         </ul>
       </p>
     </td>
@@ -2202,8 +2212,8 @@ More variables are covered in the [File and Directory Locations guide](./relocat
         <strong>Default</strong>:
 
         <ul>
-          <li>**Unix*:** None</li>
-          <li>**Windows:** None</li>
+          <li>**Unix**: (none)</li>
+          <li>**Windows**: (none)</li>
         </ul>
       </p>
     </td>

diff --git a/docs/networking.md b/docs/networking.md
@@ -18,6 +18,9 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Networking and RabbitMQ
 
 ## Overview {#overview}
@@ -53,6 +56,7 @@ There are several areas which can be configured or tuned. Each has a section in
  * Kernel TCP settings and limits (e.g. [TCP keepalives](#tcp-keepalives) and [open file handle limit](#open-file-handle-limit))
  * How to allow Erlang runtime to accept inbound connections
    when [MacOS Application Firewall](#firewalls-mac-os) is enabled
+ * More [advanced settings](#advanced-settings) related to networking
 
 This guide also covers a few topics closely related to networking:
 
@@ -948,10 +952,41 @@ net.ipv4.tcp_keepalive_probes=4
 net.ipv4.tcp_tw_reuse = 1
 ```
 
+## More Advanced Networking Settings {#advanced-settings}
+
+### The inetrc File
+
+The [Erlang runtime](./runtime/) allows for a number of hostname resolution-related settings to be tuned
+using a file known as the [inetrc file](http://erlang.org/doc/apps/erts/inet_cfg.html).
+
+The path to the file can be specified by adding an extra runtime argument using the [`RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS` environment variable](./configure/):
+
+<Tabs groupId="shell-specific">
+<TabItem value="bash" label="bash" default>
+```bash
+export RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS="-kernel inetrc '/path/to/inetrc.file'"
+```
+</TabItem>
+<TabItem value="PowerShell" label="PowerShell">
+```PowerShell
+$env:ERL_INETRC = "-kernel inetrc 'c:\path\to\inetrc.file'"
+```
+</TabItem>
+</Tabs>
+
+The file can be used to configure a number of settings related to hostname resolution on the node (not system-wide):
+
+ * Hostnames and host addresses (similarly to the [local host file](https://en.wikipedia.org/wiki/Hosts_(file)))
+ * Local domain name
+ * Nameservers
+ * Preferred hostname lookup method (e.g. local host file vs. DNS)
+ * Hostname caching interval
+ * Search domains
+
+Please consult the [inetrc file documentation](http://erlang.org/doc/apps/erts/inet_cfg.html) to learn more.
 
-## OS Level Tuning {#os-tuning}
 
-<a id="os-tuning-intro"></a>
+### OS Level Tuning {#os-tuning}
 
 Operating system settings can affect operation of RabbitMQ.
 Some are directly related to networking (e.g. TCP settings), others
@@ -961,7 +996,7 @@ Understanding these limits is important, as they may change depending on
 the workload.
 
 
-<a id="os-tuning-important-options"></a>
+### Key Relevant Kernel Options
 
 A few important configurable kernel options include (note that despite option names they
 are effective for both IPv4 and IPv6 connections):
@@ -1053,7 +1088,7 @@ Note that default values for these vary between Linux kernel releases and distri
 Using a recent kernel version (such as 6.x or later) is recommended.
 
 
-<a id="os-tuning-important-how-to-configure"></a>
+### sysctl-based Configuration
 
 Kernel parameter tuning differs from OS to OS. This guide focuses on Linux.
 To configure a kernel parameter interactively, use `sysctl -w` (requires superuser
@@ -1068,7 +1103,7 @@ To make the changes permanent (stick between reboots), they need to be added to
 and [sysctl.conf(5)](http://man7.org/linux/man-pages/man5/sysctl.conf.5.html)
 for more details.
 
-<a id="os-tuning-outro"></a>
+###
 
 TCP stack tuning is a broad topic that is covered in much detail elsewhere:
 

diff --git a/versioned_docs/version-3.13/cluster-formation.md b/versioned_docs/version-3.13/cluster-formation.md
@@ -307,6 +307,10 @@ Podman is one known example of a tool that can perform such host file modificati
 In order to avoid this, set its [`host_containers_internal_ip` setting](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)
 must be set to a blank string.
 
+In environments where container-level settings cannot be tuned, the runtime
+can be [configured to ignore the standard local hosts file](./networking#the-inetrc-file)
+and only use DNS or a pre-configured set of hostname-to-IP address mappings.
+
 
 ## Peer Discovery on AWS (EC2) {#peer-discovery-aws}
 

diff --git a/versioned_docs/version-3.13/configure.md b/versioned_docs/version-3.13/configure.md
@@ -2162,18 +2162,28 @@ More variables are covered in the [File and Directory Locations guide](./relocat
     <td>
       Standard parameters for the `erl` command used when
       invoking the RabbitMQ Server. This should be overridden for
-      debugging purposes only. Overriding this variable
-      *replaces* the default value.
+      debugging purposes only.
+
+      :::danger
+
+      Setting this variable will replace the defaults provided by RabbitMQ.
+
+      :::
+
+      :::tip
+
+      Consider using `RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS` to add or override individual settings instead.
+
+      :::
 
       <p>
         <strong>Default</strong>:
 
         <ul>
           <li>
-          **Unix*:**
-            `+P 1048576 +t 5000000 +stbt db +zdbbl 128000`
+          **UNIX**: `+P 1048576 +t 5000000 +stbt db +zdbbl 128000`
           </li>
-          <li>**Windows:** None</li>
+          <li>**Windows**: (none)</li>
         </ul>
       </p>
     </td>
@@ -2190,8 +2200,8 @@ More variables are covered in the [File and Directory Locations guide](./relocat
         <strong>Default</strong>:
 
         <ul>
-          <li>**Unix*:** None</li>
-          <li>**Windows:** None</li>
+          <li>**Unix**: (none) </li>
+          <li>**Windows**: (none)</li>
         </ul>
       </p>
     </td>

diff --git a/versioned_docs/version-3.13/networking.md b/versioned_docs/version-3.13/networking.md
@@ -18,6 +18,9 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Networking and RabbitMQ
 
 ## Overview {#overview}
@@ -53,6 +56,7 @@ There are several areas which can be configured or tuned. Each has a section in
  * Kernel TCP settings and limits (e.g. [TCP keepalives](#tcp-keepalives) and [open file handle limit](#open-file-handle-limit))
  * How to allow Erlang runtime to accept inbound connections
    when [MacOS Application Firewall](#firewalls-mac-os) is enabled
+ * More [advanced settings](#advanced-settings) related to networking
 
 This guide also covers a few topics closely related to networking:
 
@@ -948,10 +952,41 @@ net.ipv4.tcp_keepalive_probes=4
 net.ipv4.tcp_tw_reuse = 1
 ```
 
+## More Advanced Networking Settings {#advanced-settings}
+
+### The inetrc File
+
+The [Erlang runtime](./runtime/) allows for a number of hostname resolution-related settings to be tuned
+using a file known as the [inetrc file](http://erlang.org/doc/apps/erts/inet_cfg.html).
+
+The path to the file can be specified by adding an extra runtime argument using the [`RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS` environment variable](./configure/):
+
+<Tabs groupId="shell-specific">
+<TabItem value="bash" label="bash" default>
+```bash
+export RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS="-kernel inetrc '/path/to/inetrc.file'"
+```
+</TabItem>
+<TabItem value="PowerShell" label="PowerShell">
+```PowerShell
+$env:ERL_INETRC = "-kernel inetrc 'c:\path\to\inetrc.file'"
+```
+</TabItem>
+</Tabs>
+
+The file can be used to configure a number of settings related to hostname resolution on the node (not system-wide):
+
+ * Hostnames and host addresses (similarly to the [local host file](https://en.wikipedia.org/wiki/Hosts_(file)))
+ * Local domain name
+ * Nameservers
+ * Preferred hostname lookup method (e.g. local host file vs. DNS)
+ * Hostname caching interval
+ * Search domains
+
+Please consult the [inetrc file documentation](http://erlang.org/doc/apps/erts/inet_cfg.html) to learn more.
 
-## OS Level Tuning {#os-tuning}
 
-<a id="os-tuning-intro"></a>
+### OS Level Tuning {#os-tuning}
 
 Operating system settings can affect operation of RabbitMQ.
 Some are directly related to networking (e.g. TCP settings), others
@@ -961,7 +996,7 @@ Understanding these limits is important, as they may change depending on
 the workload.
 
 
-<a id="os-tuning-important-options"></a>
+### Key Relevant Kernel Options
 
 A few important configurable kernel options include (note that despite option names they
 are effective for both IPv4 and IPv6 connections):
@@ -1053,7 +1088,7 @@ Note that default values for these vary between Linux kernel releases and distri
 Using a recent kernel version (such as 6.x or later) is recommended.
 
 
-<a id="os-tuning-important-how-to-configure"></a>
+### sysctl-based Configuration
 
 Kernel parameter tuning differs from OS to OS. This guide focuses on Linux.
 To configure a kernel parameter interactively, use `sysctl -w` (requires superuser
@@ -1068,7 +1103,7 @@ To make the changes permanent (stick between reboots), they need to be added to
 and [sysctl.conf(5)](http://man7.org/linux/man-pages/man5/sysctl.conf.5.html)
 for more details.
 
-<a id="os-tuning-outro"></a>
+###
 
 TCP stack tuning is a broad topic that is covered in much detail elsewhere: