make sure important settings are represented in reference content

docs/reference/modules/cluster/misc.asciidoc

@@ -1,6 +1,9 @@
 [[misc-cluster-settings]]
 === Miscellaneous cluster settings
 
+[[cluster-name]]
+include::{es-ref-dir}/setup/important-settings/cluster-name.asciidoc[]
+
 [discrete]
 [[cluster-read-only]]
 ==== Metadata

docs/reference/modules/network.asciidoc

@@ -286,3 +286,22 @@ include::remote-cluster-network.asciidoc[]
 include::network/tracers.asciidoc[]
 
 include::network/threading.asciidoc[]
+
+[[readiness-tcp-port]]
+==== TCP readiness port
+
+preview::[]
+
+If configured, a node can open a TCP port when the node is in a ready state. A node is deemed
+ready when it has successfully joined a cluster. In a single node configuration, the node is
+said to be ready, when it's able to accept requests.
+
+To enable the readiness TCP port, use the `readiness.port` setting. The readiness service will bind to
+all host addresses.
+
+If the node leaves the cluster, or the <<put-shutdown,Shutdown API>> is used to mark the node
+for shutdown, the readiness port is immediately closed.
+
+A successful connection to the readiness TCP port signals that the {es} node is ready. When a client
+connects to the readiness port, the server simply terminates the socket connection. No data is sent back
+to the client. If a client cannot connect to the readiness port, the node is not ready.

docs/reference/modules/node.asciidoc

@@ -18,6 +18,11 @@ TIP: The performance of an {es} node is often limited by the performance of the
 Review our recommendations for optimizing your storage for <<indexing-use-faster-hardware,indexing>> and 
 <<search-use-faster-hardware,search>>.
 
+[[node-name-settings]]
+==== Node name setting
+
+include::{es-ref-dir}/setup/important-settings/node-name.asciidoc[]
+
 [[node-roles]]
 ==== Node role settings
 

docs/reference/path-settings-overview.asciidoc

@@ -0,0 +1,112 @@
+[[path-settings-overview]]
+=== Path settings
+
+include::{es-ref-dir}/setup/important-settings/path-settings.asciidoc[]
+
+[[multiple-data-paths]]
+==== Multiple data paths
+deprecated::[7.13.0]
+
+If needed, you can specify multiple paths in `path.data`. {es} stores the node's
+data across all provided paths but keeps each shard's data on the same path.
+
+{es} does not balance shards across a node's data paths. High disk
+usage in a single path can trigger a <<disk-based-shard-allocation,high disk
+usage watermark>> for the entire node. If triggered, {es} will not add shards to
+the node, even if the node’s other paths have available disk space. If you need
+additional disk space, we recommend you add a new node rather than additional
+data paths.
+
+include::{es-ref-dir}/tab-widgets/multi-data-path-widget.asciidoc[]
+
+[[mdp-migrate]]
+===== Migrate from multiple data paths
+
+Support for multiple data paths was deprecated in 7.13 and will be removed
+in a future release.
+
+As an alternative to multiple data paths, you can create a filesystem which
+spans multiple disks with a hardware virtualisation layer such as RAID, or a
+software virtualisation layer such as Logical Volume Manager (LVM) on Linux or
+Storage Spaces on Windows. If you wish to use multiple data paths on a single
+machine then you must run one node for each data path.
+
+If you currently use multiple data paths in a
+{ref}/high-availability-cluster-design.html[highly available cluster] then you
+can migrate to a setup that uses a single path for each node without downtime
+using a process similar to a
+{ref}/restart-cluster.html#restart-cluster-rolling[rolling restart]: shut each
+node down in turn and replace it with one or more nodes each configured to use
+a single data path. In more detail, for each node that currently has multiple
+data paths you should follow the following process. In principle you can
+perform this migration during a rolling upgrade to 8.0, but we recommend
+migrating to a single-data-path setup before starting to upgrade.
+
+1. Take a snapshot to protect your data in case of disaster.
+
+2. Optionally, migrate the data away from the target node by using an
+{ref}/modules-cluster.html#cluster-shard-allocation-filtering[allocation filter]:
++
+[source,console]
+--------------------------------------------------
+PUT _cluster/settings
+{
+  "persistent": {
+    "cluster.routing.allocation.exclude._name": "target-node-name"
+  }
+}
+--------------------------------------------------
++
+You can use the {ref}/cat-allocation.html[cat allocation API] to track progress
+of this data migration. If some shards do not migrate then the
+{ref}/cluster-allocation-explain.html[cluster allocation explain API] will help
+you to determine why.
+
+3. Follow the steps in the
+{ref}/restart-cluster.html#restart-cluster-rolling[rolling restart process]
+up to and including shutting the target node down.
+
+4. Ensure your cluster health is `yellow` or `green`, so that there is a copy
+of every shard assigned to at least one of the other nodes in your cluster.
+
+5. If applicable, remove the allocation filter applied in the earlier step.
++
+[source,console]
+--------------------------------------------------
+PUT _cluster/settings
+{
+  "persistent": {
+    "cluster.routing.allocation.exclude._name": null
+  }
+}
+--------------------------------------------------
+
+6. Discard the data held by the stopped node by deleting the contents of its
+data paths.
+
+7. Reconfigure your storage. For instance, combine your disks into a single
+filesystem using LVM or Storage Spaces. Ensure that your reconfigured storage
+has sufficient space for the data that it will hold.
+
+8. Reconfigure your node by adjusting the `path.data` setting in its
+`elasticsearch.yml` file. If needed, install more nodes each with their own
+`path.data` setting pointing at a separate data path.
+
+9. Start the new nodes and follow the rest of the
+{ref}/restart-cluster.html#restart-cluster-rolling[rolling restart process] for
+them.
+
+10. Ensure your cluster health is `green`, so that every shard has been
+assigned.
+
+You can alternatively add some number of single-data-path nodes to your
+cluster, migrate all your data over to these new nodes using
+{ref}/modules-cluster.html#cluster-shard-allocation-filtering[allocation filters],
+and then remove the old nodes from the cluster. This approach will temporarily
+double the size of your cluster so it will only work if you have the capacity to
+expand your cluster like this.
+
+If you currently use multiple data paths but your cluster is not highly
+available then you can migrate to a non-deprecated configuration by taking
+a snapshot, creating a new cluster with the desired configuration and restoring
+the snapshot into it.

docs/reference/setup.asciidoc

@@ -27,6 +27,8 @@ the only resource-intensive application on the host or container. For example,
 you might run {metricbeat} alongside {es} for cluster statistics, but a
 resource-heavy {ls} deployment should be on its own host.
 
+// alphabetized
+
 include::run-elasticsearch-locally.asciidoc[]
 
 include::setup/install.asciidoc[]
@@ -47,28 +49,28 @@ include::settings/ccr-settings.asciidoc[]
 
 include::modules/discovery/discovery-settings.asciidoc[]
 
+include::settings/data-stream-lifecycle-settings.asciidoc[]
+
 include::modules/indices/fielddata.asciidoc[]
 
+include::modules/gateway.asciidoc[]
+
 include::settings/health-diagnostic-settings.asciidoc[]
 
 include::settings/ilm-settings.asciidoc[]
 
-include::settings/data-stream-lifecycle-settings.asciidoc[]
-
 include::modules/indices/index_management.asciidoc[]
 
 include::modules/indices/recovery.asciidoc[]
 
 include::modules/indices/indexing_buffer.asciidoc[]
 
-include::settings/license-settings.asciidoc[]
+include::settings/inference-settings.asciidoc[]
 
-include::modules/gateway.asciidoc[]
+include::settings/license-settings.asciidoc[]
 
 include::settings/ml-settings.asciidoc[]
 
-include::settings/inference-settings.asciidoc[]
-
 include::settings/monitoring-settings.asciidoc[]
 
 include::modules/node.asciidoc[]
@@ -77,6 +79,8 @@ include::modules/network.asciidoc[]
 
 include::modules/indices/query_cache.asciidoc[]
 
+include::{es-ref-dir}/path-settings-overview.asciidoc[]
+
 include::modules/indices/search-settings.asciidoc[]
 
 include::settings/security-settings.asciidoc[]

docs/reference/setup/advanced-configuration.asciidoc

@@ -1,10 +1,3 @@
-[[advanced-configuration]]
-=== Advanced configuration
-
-Modifying advanced settings is generally not recommended and could negatively
-impact performance and stability. Using the {es}-provided defaults
-is recommended in most circumstances.
-
 [[set-jvm-options]]
 ==== Set JVM options
 
@@ -21,6 +14,10 @@ Where you put the JVM options files depends on the type of installation:
 * Docker: Bind mount custom JVM options files into
 `/usr/share/elasticsearch/config/jvm.options.d/`.
 
+CAUTION: Setting your own JVM options is generally not recommended and could negatively
+impact performance and stability. Using the {es}-provided defaults
+is recommended in most circumstances.
+
 NOTE: Do not modify the root `jvm.options` file. Use files in `jvm.options.d/` instead.
 
 [[jvm-options-syntax]]
@@ -155,23 +152,11 @@ options. We do not recommend using `ES_JAVA_OPTS` in production.
 NOTE: If you are running {es} as a Windows service, you can change the heap size
 using the service manager. See <<windows-service>>.
 
-[[readiness-tcp-port]]
-===== Enable the Elasticsearch TCP readiness port
-
-preview::[]
-
-If configured, a node can open a TCP port when the node is in a ready state. A node is deemed
-ready when it has successfully joined a cluster. In a single node configuration, the node is
-said to be ready, when it's able to accept requests.
-
-To enable the readiness TCP port, use the `readiness.port` setting. The readiness service will bind to
-all host addresses.
-
-If the node leaves the cluster, or the <<put-shutdown,Shutdown API>> is used to mark the node
-for shutdown, the readiness port is immediately closed.
-
-A successful connection to the readiness TCP port signals that the {es} node is ready. When a client
-connects to the readiness port, the server simply terminates the socket connection. No data is sent back
-to the client. If a client cannot connect to the readiness port, the node is not ready.
+[[heap-dump-path]]
+include::important-settings/heap-dump-path.asciidoc[]
 
+[[gc-logging]]
+include::important-settings/gc-logging.asciidoc[]
 
+[[error-file-path]]
+include::important-settings/error-file.asciidoc[]

docs/reference/setup/important-settings.asciidoc

@@ -19,10 +19,18 @@ of items which *must* be considered before using your cluster in production:
 Our {ess-trial}[{ecloud}] service configures these items automatically, making
 your cluster production-ready by default.
 
+[[path-settings]]
+[discrete]
+==== Path settings
+
 include::important-settings/path-settings.asciidoc[]
 
+Elasticsearch offers a deprecated setting that allows you to specify multiple paths in `path.data`. 
+To learn about this setting, and how to migrate away from it, refer to <<multiple-data-paths>>.
+
 include::important-settings/cluster-name.asciidoc[]
 
+[[node-name]]
 include::important-settings/node-name.asciidoc[]
 
 include::important-settings/network-host.asciidoc[]

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

@@ -1,4 +1,3 @@
-[[cluster-name]]
 [discrete]
 ==== Cluster name setting
 

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

@@ -1,4 +1,3 @@
-[[error-file-path]]
 [discrete]
 ==== JVM fatal error log setting
 

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

@@ -1,4 +1,3 @@
-[[gc-logging]]
 [discrete]
 ==== GC logging settings
 
@@ -20,9 +19,8 @@ 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
+===== Examples
 
 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

docs/reference/setup/important-settings/heap-dump-path.asciidoc

@@ -1,4 +1,3 @@
-[[heap-dump-path]]
 [discrete]
 ==== JVM heap dump path setting
 

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

@@ -1,4 +1,3 @@
-[[node-name]]
 [discrete]
 ==== Node name setting