[DOCS] [7.x] Combining important config settings into a single page (#63849) (#63884)

* [DOCS] Combining important config settings into a single page (#63849)

* Combining important config settings into a single page.

* Updating ids for two pages causing link errors and implementing redirects.

* Updating links to use IDs instead of xrefs.

Author: Adam Locke

docs/reference/cluster/nodes-stats.asciidoc

@@ -163,7 +163,7 @@ is not `0`, a reason for the rejection or failure is included in the response.
 
 `cluster_name`::
 (string)
-Name of the cluster. Based on the <<cluster.name>> setting.
+Name of the cluster. Based on the <<cluster-name>> setting.
 
 `nodes`::
 (object)
@@ -186,7 +186,7 @@ since the {wikipedia}/Unix_time[Unix Epoch].
 
 `name`::
 (string)
-Human-readable identifier for the node. Based on the <<node.name>> setting.
+Human-readable identifier for the node. Based on the <<node-name>> setting.
 
 `transport_address`::
 (string)

docs/reference/cluster/stats.asciidoc

@@ -66,7 +66,7 @@ is not `0`, a reason for the rejection or failure is included in the response.
 
 `cluster_name`::
 (string)
-Name of the cluster, based on the <<cluster.name>> setting.
+Name of the cluster, based on the <<cluster-name>> setting.
 
 `cluster_uuid`::
 (string)

docs/reference/modules/discovery/bootstrapping.asciidoc

@@ -15,7 +15,7 @@ The initial set of master-eligible nodes is defined in the
 set to a list containing one of the following items for each master-eligible
 node:
 
-- The <<node.name,node name>> of the node.
+- The <<node-name,node name>> of the node.
 - The node's hostname if `node.name` is not set, because `node.name` defaults
   to the node's hostname. You must use either the fully-qualified hostname or
   the bare hostname <<modules-discovery-bootstrap-cluster-fqdns,depending on
@@ -44,7 +44,7 @@ WARNING: You must set `cluster.initial_master_nodes` to the same list of nodes
 on each node on which it is set in order to be sure that only a single cluster
 forms during bootstrapping and therefore to avoid the risk of data loss.
 
-For a cluster with 3 master-eligible nodes (with <<node.name,node names>>
+For a cluster with 3 master-eligible nodes (with <<node-name,node names>>
 `master-a`, `master-b` and `master-c`) the configuration will look as follows:
 
 [source,yaml]
@@ -97,7 +97,7 @@ match exactly.
 [discrete]
 ==== Choosing a cluster name
 
-The <<cluster.name,`cluster.name`>> setting enables you to create multiple
+The <<cluster-name,`cluster.name`>> setting enables you to create multiple
 clusters which are separated from each other. Nodes verify that they agree on
 their cluster name when they first connect to each other, and Elasticsearch
 will only form a cluster from nodes that all have the same cluster name. The

docs/reference/modules/node.asciidoc

@@ -48,7 +48,7 @@ A node that has the `master` role (default), which makes it eligible to be
 <<data-node,Data node>>::
 
 A node that has the `data` role (default). Data nodes hold data and perform data
-related operations such as CRUD, search, and aggregations. A node with the `data` role can fill any of the specialised data node roles. 
+related operations such as CRUD, search, and aggregations. A node with the `data` role can fill any of the specialised data node roles.
 
 <<node-ingest-node,Ingest node>>::
 
@@ -456,6 +456,6 @@ directory. This can lead to unexpected data loss.
 More node settings can be found in <<settings>> and <<important-settings>>,
 including:
 
-* <<cluster.name,`cluster.name`>>
-* <<node.name,`node.name`>>
+* <<cluster-name,`cluster.name`>>
+* <<node-name,`node.name`>>
 * <<modules-network,network settings>>

docs/reference/redirects.asciidoc

@@ -3,6 +3,16 @@
 
 The following pages have moved or been deleted.
 
+[role="exclude",id="node.name"]
+=== Node name setting
+
+See <<node-name,Node name setting>>.
+
+[role="exclude",id="cluster.name"]
+=== Cluster name setting
+
+See <<cluster-name,Cluster name setting>>.
+
 [role="exclude",id="ccr-remedy-follower-index"]
 === Leader index retaining operations for replication
 

docs/reference/repositories-metering-api/apis/repositories-meterings-body.asciidoc

@@ -22,7 +22,7 @@ is not `0`, a reason for the rejection or failure is included in the response.
 
 `cluster_name`::
 (string)
-Name of the cluster. Based on the <<cluster.name>> setting.
+Name of the cluster. Based on the <<cluster-name>> setting.
 
 `nodes`::
 (object)

docs/reference/settings/audit-settings.asciidoc

@@ -74,7 +74,7 @@ audited in plain text when including the request body in audit events.
 // tag::xpack-sa-lf-emit-node-name-tag[]
 `xpack.security.audit.logfile.emit_node_name`::
 (<<dynamic-cluster-setting,Dynamic>>)
-Specifies whether to include the <<node.name,node name>> as a field in
+Specifies whether to include the <<node-name,node name>> as a field in
 each audit event. The default value is `false`.
 // end::xpack-sa-lf-emit-node-name-tag[]
 
@@ -101,7 +101,7 @@ The default value is `false`.
 Specifies whether to include the node id as a field in each audit event.
 This is available for the new format only. That is to say, this information
 does not exist in the `<clustername>_access.log` file.
-Unlike <<node.name,node name>>, whose value might change if the administrator
+Unlike <<node-name,node name>>, whose value might change if the administrator
 changes the setting in the config file, the node id will persist across cluster
 restarts and the administrator cannot change it.
 The default value is `true`.

docs/reference/setup/important-settings.asciidoc

@@ -7,14 +7,15 @@ settings which need to be considered before going into production.
 The following settings *must* be considered before going to production:
 
 * <<path-settings,Path settings>>
-* <<cluster.name,Cluster name>>
-* <<node.name,Node name>>
-* <<network.host,Network host>>
+* <<cluster-name,Cluster name setting>>
+* <<node-name,Node name setting>>
+* <<network.host,Network host settings>>
 * <<discovery-settings,Discovery settings>>
-* <<heap-size,Heap size>>
-* <<heap-dump-path,Heap dump path>>
-* <<gc-logging,GC logging>>
-* <<es-tmpdir,Temp directory>>
+* <<heap-size,Heap size settings>>
+* <<heap-dump-path,JVM heap dump path setting>>
+* <<gc-logging,GC logging settings>>
+* <<es-tmpdir,Temporary directory settings>>
+* <<error-file-path,JVM fatal error log setting>>
 
 include::important-settings/path-settings.asciidoc[]
 

docs/reference/setup/important-settings/cluster-name.asciidoc

@@ -1,14 +1,15 @@
-[[cluster.name]]
-=== `cluster.name`
+[[cluster-name]]
+[discrete]
+=== Cluster name setting
 
 A node can only join a cluster when it shares its `cluster.name` with all the
 other nodes in the cluster. The default name is `elasticsearch`, but you should
-change it to an appropriate name which describes the purpose of the cluster.
+change it to an appropriate name that describes the purpose of the cluster.
 
 [source,yaml]
 --------------------------------------------------
 cluster.name: logging-prod
 --------------------------------------------------
 
-Make sure that you don't reuse the same cluster names in different environments,
-otherwise you might end up with nodes joining the wrong cluster.
+IMPORTANT: Do not reuse the same cluster names in different environments.
+Otherwise, nodes might join the wrong cluster.

docs/reference/setup/important-settings/discovery-settings.asciidoc

@@ -1,29 +1,28 @@
 [[discovery-settings]]
-=== Important discovery and cluster formation settings
-++++
-<titleabbrev>Discovery and cluster formation settings</titleabbrev>
-++++
+[discrete]
+=== Discovery and cluster formation settings
 
-There are two important discovery and cluster formation settings that should be
-configured before going to production so that nodes in the cluster can discover
-each other and elect a master node.
+Configure two important discovery and cluster formation settings before going
+to production so that nodes in the cluster can discover each other and elect a
+master node.
 
 [discrete]
 [[unicast.hosts]]
 ==== `discovery.seed_hosts`
 
-Out of the box, without any network configuration, Elasticsearch will bind to
-the available loopback addresses and will scan local ports 9300 to 9305 to try
-to connect to other nodes running on the same server. This provides an
+Out of the box, without any network configuration, {es} will bind to
+the available loopback addresses and scan local ports `9300` to `9305` to
+connect with other nodes running on the same server. This behavior provides an
 auto-clustering experience without having to do any configuration.
 
-When you want to form a cluster with nodes on other hosts, you should use the
-<<static-cluster-setting, static>> `discovery.seed_hosts` setting to provide a list of other nodes in the cluster
-that are master-eligible and likely to be live and contactable in order to seed
-the <<modules-discovery-hosts-providers,discovery process>>. This setting value
-should be a YAML sequence or array of the addresses of all the master-eligible
+When you want to form a cluster with nodes on other hosts, use the
+<<static-cluster-setting, static>> `discovery.seed_hosts` setting. This setting
+provides a list of other nodes in the cluster
+that are master-eligible and likely to be live and contactable to seed
+the <<modules-discovery-hosts-providers,discovery process>>. This setting
+accepts a YAML sequence or array of the addresses of all the master-eligible
 nodes in the cluster. Each address can be either an IP address or a hostname
-which resolves to one or more IP addresses via DNS.
+that resolves to one or more IP addresses via DNS.
 
 [source,yaml]
 ----
@@ -33,9 +32,9 @@ discovery.seed_hosts:
    - seeds.mydomain.com <2>
    - [0:0:0:0:0:ffff:c0a8:10c]:9301 <3>
 ----
-<1> The port is optional and usually defaults to `9300`, but this default can
-    be <<built-in-hosts-providers,overridden>> by certain settings.
-<2> If a hostname resolves to multiple IP addresses then the node will attempt to
+<1> The port is optional and defaults to `9300`, but can
+    be <<built-in-hosts-providers,overridden>>.
+<2> If a hostname resolves to multiple IP addresses, the node will attempt to
     discover other nodes at all resolved addresses.
 <3> IPv6 addresses must be enclosed in square brackets.
 
@@ -47,20 +46,22 @@ dynamically.
 [[initial_master_nodes]]
 ==== `cluster.initial_master_nodes`
 
-When you start a brand new Elasticsearch cluster for the very first time, there
-is a <<modules-discovery-bootstrap-cluster,cluster bootstrapping>> step, which
-determines the set of master-eligible nodes whose votes are counted in the very
+When you start an {es} cluster for the first time, a
+<<modules-discovery-bootstrap-cluster,cluster bootstrapping>> step
+determines the set of master-eligible nodes whose votes are counted in the
 first election. In <<dev-vs-prod-mode,development mode>>, with no discovery
-settings configured, this step is automatically performed by the nodes
-themselves. As this auto-bootstrapping is <<modules-discovery-quorums,inherently
-unsafe>>, when you start a brand new cluster in <<dev-vs-prod-mode,production
-mode>>, you must explicitly list the master-eligible nodes whose votes should be
-counted in the very first election. This list is set using the
-`cluster.initial_master_nodes` setting. 
+settings configured, this step is performed automatically by the nodes
+themselves.
+
+Because auto-bootstrapping is <<modules-discovery-quorums,inherently
+unsafe>>, when starting a new cluster in production
+mode, you must explicitly list the master-eligible nodes whose votes should be
+counted in the very first election. You set this list using the
+`cluster.initial_master_nodes` setting.
 
-NOTE: You should remove `cluster.initial_master_nodes` setting from the nodes' configuration
-*once the cluster has successfully formed for the first time*. Do not use this setting when
-restarting a cluster or adding a new node to an existing cluster.  
+IMPORTANT: After the cluster forms successfully for the first time, remove the `cluster.initial_master_nodes` setting from each nodes'
+configuration. Do not use this setting when
+restarting a cluster or adding a new node to an existing cluster.
 
 [source,yaml]
 --------------------------------------------------
@@ -74,14 +75,13 @@ cluster.initial_master_nodes: <1>
    - master-node-b
    - master-node-c
 --------------------------------------------------
-<1> The initial master nodes should be identified by their
-    <<node.name,`node.name`>>, which defaults to their hostname. Make sure that
-    the value in `cluster.initial_master_nodes` matches the `node.name`
-    exactly. If you use a fully-qualified domain name such as
-    `master-node-a.example.com` for your node names then you must use the
-    fully-qualified name in this list; conversely if `node.name` is a bare
-    hostname without any trailing qualifiers then you must also omit the
-    trailing qualifiers in `cluster.initial_master_nodes`.
+<1> Identify the initial master nodes by their <<node-name,`node.name`>>, which
+defaults to their hostname. Ensure that the value in
+`cluster.initial_master_nodes` matches the `node.name` exactly. If you use a
+fully-qualified domain name (FQDN) such as `master-node-a.example.com` for your
+node names, then you must use the FQDN in this list. Conversely, if `node.name`
+is a bare hostname without any trailing qualifiers, you must also omit the
+trailing qualifiers in `cluster.initial_master_nodes`.
 
-For more information, see <<modules-discovery-bootstrap-cluster>> and
-<<modules-discovery-settings>>.
+See <<modules-discovery-bootstrap-cluster,bootstrapping a cluster>> and
+<<modules-discovery-settings,discovery and cluster formation settings>>.

docs/reference/setup/important-settings/error-file.asciidoc

@@ -1,12 +1,12 @@
 [[error-file-path]]
-=== JVM fatal error logs
+[discrete]
+=== JVM fatal error log setting
 
-By default, Elasticsearch configures the JVM to write fatal error logs
-to the default logging directory (this is `/var/log/elasticsearch` for
-the <<rpm,RPM>> and <<deb,Debian>> package distributions, and the `logs`
-directory under the root of the Elasticsearch installation for the
-<<targz,tar>> and <<zip-windows,zip>> archive distributions). These are logs
-produced by the JVM when it encounters a fatal error (e.g., a
-segmentation fault). If this path is not suitable for receiving logs,
-you should modify the entry `-XX:ErrorFile=...` in
-<<jvm-options,`jvm.options`>> to an alternate path.
+By default, {es} configures the JVM to write fatal error logs
+to the default logging directory. On <<rpm,RPM>> and <<deb,Debian>> packages,
+this directory is `/var/log/elasticsearch`. On <<targz,Linux and MacOS>> and <<zip-windows,Windows>> distributions, the `logs`
+directory is located under the root of the {es} installation.
+
+These are logs produced by the JVM when it encounters a fatal error, such as a
+segmentation fault. If this path is not suitable for receiving logs,
+modify the `-XX:ErrorFile=...` entry in <<jvm-options,`jvm.options`>>.

docs/reference/setup/important-settings/es-tmpdir.asciidoc

@@ -1,23 +1,25 @@
 [[es-tmpdir]]
-=== Temp directory
+[discrete]
+=== Temporary directory settings
 
-By default, Elasticsearch uses a private temporary directory that the startup
+By default, {es} uses a private temporary directory that the startup
 script creates immediately below the system temporary directory.
 
-On some Linux distributions a system utility will clean files and directories
-from `/tmp` if they have not been recently accessed. This can lead to the
-private temporary directory being removed while Elasticsearch is running if
+On some Linux distributions, a system utility will clean files and directories
+from `/tmp` if they have not been recently accessed. This behavior can lead to
+the private temporary directory being removed while {es} is running if
 features that require the temporary directory are not used for a long time.
-This causes problems if a feature that requires the temporary directory is
-subsequently used.
+Removing the private temporary directory causes problems if a feature that
+requires this directory is subsequently used.
 
-If you install Elasticsearch using the `.deb` or `.rpm` packages and run it
-under `systemd` then the private temporary directory that Elasticsearch uses
+If you install {es} using the `.deb` or `.rpm` packages and run it
+under `systemd`, the private temporary directory that {es} uses
 is excluded from periodic cleanup.
 
-However, if you intend to run the `.tar.gz` distribution on Linux for an
-extended period then you should consider creating a dedicated temporary
-directory for Elasticsearch that is not under a path that will have old files
+If you intend to run the `.tar.gz` distribution on Linux or MacOS for
+an extended period, consider creating a dedicated temporary
+directory for {es} that is not under a path that will have old files
 and directories cleaned from it. This directory should have permissions set
-so that only the user that Elasticsearch runs as can access it. Then set the
-`$ES_TMPDIR` environment variable to point to it before starting Elasticsearch.
+so that only the user that {es} runs as can access it. Then, set the
+`$ES_TMPDIR` environment variable to point to this directory before starting
+{es}.

docs/reference/setup/important-settings/gc-logging.asciidoc

@@ -1,7 +1,8 @@
 [[gc-logging]]
-=== GC logging
+[discrete]
+=== GC logging settings
 
-By default, {es} enables GC logs. These are configured in
+By default, {es} enables garbage collection (GC) logs. These are configured in
 <<jvm-options,`jvm.options`>> and output to the same default location as
 the {es} logs. The default configuration rotates the logs every 64 MB and
 can consume up to 2 GB of disk space.
@@ -19,14 +20,16 @@ To see further options not contained in the original JEP, see
 https://docs.oracle.com/en/java/javase/13/docs/specs/man/java.html#enable-logging-with-the-jvm-unified-logging-framework[Enable
 Logging with the JVM Unified Logging Framework].
 
+[[gc-logging-examples]]
+[discrete]
 ==== Examples
 
-* Change the default GC log output location to `/opt/my-app/gc.log` by
+Change the default GC log output location to `/opt/my-app/gc.log` by
   creating `$ES_HOME/config/jvm.options.d/gc.options` with some sample
   options:
-+
+
 [source,shell]
---------------------------------------------
+----
 # Turn off all previous logging configuratons
 -Xlog:disable
 
@@ -35,15 +38,15 @@ Logging with the JVM Unified Logging Framework].
 
 # Enable GC logging to a custom location with a variety of options
 -Xlog:gc*,gc+age=trace,safepoint:file=/opt/my-app/gc.log:utctime,pid,tags:filecount=32,filesize=64m
---------------------------------------------
+----
 
-* Configure an {es} <<docker,Docker container>> to send GC debug logs to
+Configure an {es} <<docker,Docker container>> to send GC debug logs to
   standard error (`stderr`). This lets the container orchestrator
   handle the output. If using the `ES_JAVA_OPTS` environment variable,
   specify:
-+
+
 [source,sh]
---------------------------------------------
+----
 MY_OPTS="-Xlog:disable -Xlog:all=warning:stderr:utctime,level,tags -Xlog:gc=debug:stderr:utctime"
 docker run -e ES_JAVA_OPTS="$MY_OPTS" # etc
---------------------------------------------
+----