Skip to content

Commit

Permalink
More Networking guide edits
Browse files Browse the repository at this point in the history
  • Loading branch information
michaelklishin committed Sep 10, 2024
1 parent d8d3dd9 commit a861962
Show file tree
Hide file tree
Showing 4 changed files with 91 additions and 83 deletions.
11 changes: 9 additions & 2 deletions docs/cluster-formation.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,8 +244,8 @@ cluster_formation.classic_config.nodes.2 = rabbit@hostname2.eng.example.local

:::important

This peer discovery mechanism is sensitive to system configuration that
affects hostname resolution changes.
This peer discovery mechanism is sensitive to OS and RabbitMQ configuration that
[affects hostname resolution](./networking#dns).

For example, a deployment tool that modifies the [local host file](https://en.wikipedia.org/wiki/Hosts_(file))
can affect (break) this peer discovery mechanism.
Expand Down Expand Up @@ -495,6 +495,13 @@ In addition, since RabbitMQ nodes [resolve their own and peer hostnames during b
CoreDNS [caching timeout may need to be decreased](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#stable-network-id) from default 30 seconds
to a value in the 5-10 second range.

:::important

CoreDNS [caching timeout may need to be decreased](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#stable-network-id)
from default 30 seconds to a value in the 5-10 second range

:::

If a stateless set is used recreated nodes will not have their persisted data and will start as blank nodes.
This can lead to data loss and higher network traffic volume due to more frequent
data synchronisation of both [quorum queues](./quorum-queues)
Expand Down
75 changes: 36 additions & 39 deletions docs/networking.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +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
* [OS-level tuning](#os-tuning) related to networking

This guide also covers a few topics closely related to networking:

Expand Down Expand Up @@ -952,41 +952,7 @@ 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}
## OS Level Tuning {#os-tuning}

Operating system settings can affect operation of RabbitMQ.
Some are directly related to networking (e.g. TCP settings), others
Expand Down Expand Up @@ -1237,9 +1203,9 @@ It should be pointed out that this is only necessary with very constrained
clients and networks. Handshake timeouts in other circumstances indicate
a problem elsewhere.

### TLS (SSL) Handshake {#tls-handshake}
### TLS Handshake {#tls-handshake}

If TLS/SSL is enabled, it may be necessary to increase also the TLS/SSL
If [TLS is enabled](./ssl), it may be necessary to increase also the TLS
handshake timeout. This can be done via
the `rabbit.ssl_handshake_timeout` (in milliseconds):

Expand Down Expand Up @@ -1300,10 +1266,41 @@ To deactivate reverse DNS lookups:
reverse_dns_lookups = false
```

### 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.

### Verify Hostname Resolution {#dns-verify-resolution}

Since hostname resolution is a [prerequisite for successful inter-node communication](./clustering#hostname-resolution-requirement),
starting with [RabbitMQ `3.8.6`](/release-information), CLI tools provide two commands that help verify
CLI tools provide two commands that help verify
that hostname resolution on a node works as expected. The commands are not meant to replace
[`dig`](https://en.wikipedia.org/wiki/Dig_(command)) and other specialised DNS tools but rather
provide a way to perform most basic checks while taking [Erlang runtime hostname resolver features](https://erlang.org/doc/apps/erts/inet_cfg.html)
Expand Down
13 changes: 10 additions & 3 deletions versioned_docs/version-3.13/cluster-formation.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,8 +244,8 @@ cluster_formation.classic_config.nodes.2 = rabbit@hostname2.eng.example.local

:::important

This peer discovery mechanism is sensitive to system configuration that
affects hostname resolution changes.
This peer discovery mechanism is sensitive to OS and RabbitMQ configuration that
[affects hostname resolution](./networking#dns).

For example, a deployment tool that modifies the [local host file](https://en.wikipedia.org/wiki/Hosts_(file))
can affect (break) this peer discovery mechanism.
Expand Down Expand Up @@ -495,10 +495,17 @@ In addition, since RabbitMQ nodes [resolve their own and peer hostnames during b
CoreDNS [caching timeout may need to be decreased](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#stable-network-id) from default 30 seconds
to a value in the 5-10 second range.

:::important

CoreDNS [caching timeout may need to be decreased](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#stable-network-id)
from default 30 seconds to a value in the 5-10 second range

:::

If a stateless set is used recreated nodes will not have their persisted data and will start as blank nodes.
This can lead to data loss and higher network traffic volume due to more frequent
data synchronisation of both [quorum queues](./quorum-queues)
and [classic queue mirrors](./ha) on newly joining nodes.
and [streams](./streams) on newly joining nodes.

#### Use Persistent Volumes

Expand Down
75 changes: 36 additions & 39 deletions versioned_docs/version-3.13/networking.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +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
* [OS-level tuning](#os-tuning) related to networking

This guide also covers a few topics closely related to networking:

Expand Down Expand Up @@ -952,41 +952,7 @@ 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}
## OS Level Tuning {#os-tuning}

Operating system settings can affect operation of RabbitMQ.
Some are directly related to networking (e.g. TCP settings), others
Expand Down Expand Up @@ -1237,9 +1203,9 @@ It should be pointed out that this is only necessary with very constrained
clients and networks. Handshake timeouts in other circumstances indicate
a problem elsewhere.

### TLS (SSL) Handshake {#tls-handshake}
### TLS Handshake {#tls-handshake}

If TLS/SSL is enabled, it may be necessary to increase also the TLS/SSL
If [TLS is enabled](./ssl), it may be necessary to increase also the TLS
handshake timeout. This can be done via
the `rabbit.ssl_handshake_timeout` (in milliseconds):

Expand Down Expand Up @@ -1300,10 +1266,41 @@ To deactivate reverse DNS lookups:
reverse_dns_lookups = false
```

### 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.

### Verify Hostname Resolution {#dns-verify-resolution}

Since hostname resolution is a [prerequisite for successful inter-node communication](./clustering#hostname-resolution-requirement),
starting with [RabbitMQ `3.8.6`](/release-information), CLI tools provide two commands that help verify
CLI tools provide two commands that help verify
that hostname resolution on a node works as expected. The commands are not meant to replace
[`dig`](https://en.wikipedia.org/wiki/Dig_(command)) and other specialised DNS tools but rather
provide a way to perform most basic checks while taking [Erlang runtime hostname resolver features](https://erlang.org/doc/apps/erts/inet_cfg.html)
Expand Down

0 comments on commit a861962

Please sign in to comment.