docs: document the new replace_node_first_boot option

And mention that replacing a node using the legacy
replace_addr* options is deprecated.

Signed-off-by: Benny Halevy <bhalevy@scylladb.com>

docs/operating-scylla/admin.rst

@@ -80,8 +80,8 @@ The following addresses can be configured in scylla.yaml:
      - Address for REST API requests. See api_port in the :ref:`Networking <cqlsh-networking>` parameters.
    * - prometheus_address
      - Address for Prometheus queries. See prometheus_port in the :ref:`Networking <cqlsh-networking>` parameters and `ScyllaDB Monitoring Stack <https://monitoring.docs.scylladb.com/stable/>`_ for more details.
-   * - replace_address_first_boot
-     - Address of the node this Scylla instance is meant to replace. Refer to :doc:`Replace a Dead Node in a Scylla Cluster </operating-scylla/procedures/cluster-management/replace-dead-node>` for more details.
+   * - replace_node_first_boot
+     - Host ID of a dead node this Scylla node is replacing. Refer to :doc:`Replace a Dead Node in a Scylla Cluster </operating-scylla/procedures/cluster-management/replace-dead-node>` for more details.
 
 .. note:: When the listen_address, rpc_address, broadcast_address, and broadcast_rpc_address parameters are not set correctly, Scylla does not work as expected.
 

docs/operating-scylla/procedures/cluster-management/rebuild-node.rst

@@ -17,8 +17,8 @@ To recover the data and rebuild the node, follow this procedure:
 
    .. note:: If the ``auto_bootstrap`` parameter is missing from ``/etc/scylla/scylla.yaml``, default setting ``true`` is applied.
 
-#. With the yaml file still open, add, if not present,else edit, the ``replace_address_first_boot`` parameter and change it to the
-   IP of the node before it restarted it might be the same IP after restart.
+#. With the yaml file still open, add, if not present, else edit, the ``replace_node_first_boot`` parameter and change it to the
+   Host ID of the node before it restarted.
 #. Stop Scylla Server
 
    .. include:: /rst_include/scylla-commands-stop-index.rst
@@ -28,6 +28,6 @@ To recover the data and rebuild the node, follow this procedure:
 
    .. include:: /rst_include/scylla-commands-start-index.rst
 
-#. Revert the ``auto_bootstrap`` and ``replace_address_first_boot`` settings to what they were before you ran this procedure.
-   For ease of use, you can comment out the ``replace_address_first_boot`` parameter.
+#. Revert the ``auto_bootstrap`` setting to what it was before you ran this procedure.
+   For ease of use, you can comment out the ``replace_node_first_boot`` parameter.
 

docs/operating-scylla/procedures/cluster-management/replace-dead-node.rst

@@ -68,11 +68,11 @@ Procedure
 
     - **rpc_address** - Address for client connection (Thrift, CQL)
 
-#. Add the ``replace_address_first_boot`` parameter to the ``scylla.yaml`` config file on the new node. This line can be added to any place in the config file. After a successful node replacement, there is no need to remove it from the ``scylla.yaml`` file. (Note: The obsolete parameter "replace_address" is not supported and should not be used). The value of the ``replace_address_first_boot`` parameter should be the IP address of the node to be replaced.
+#. Add the ``replace_node_first_boot`` parameter to the ``scylla.yaml`` config file on the new node. This line can be added to any place in the config file. After a successful node replacement, there is no need to remove it from the ``scylla.yaml`` file. (Note: The obsolete parameters "replace_address" and "replace_address_first_boot" are not supported and should not be used). The value of the ``replace_node_first_boot`` parameter should be the Host ID of the node to be replaced.
 
-    For example (using the address of the failed node from above):
+    For example (using the Host ID of the failed node from above):
 
-    ``replace_address_first_boot: 192.168.1.203``   
+    ``replace_node_first_boot: 675ed9f4-6564-6dbd-can8-43fddce952gy``
 
 #. Start Scylla node.
 
@@ -179,11 +179,18 @@ In this case, the node's data will be cleaned after restart. To remedy this, you
 
       sudo sed -e '/auto_bootstrap:.*/s/False/True/g' -i /etc/scylla/scylla.yaml
 
-#. Run the following command, replacing 172.30.0.186 with the listen_address / rpc_address of the node that you are restarting:
+#. Run the following command to configure replacement of the node that lost its data when the current node restarts.
 
    .. code-block:: none
 
-      echo 'replace_address_first_boot: 172.30.0.186' | sudo tee --append /etc/scylla/scylla.yaml
+      echo 'replace_node_first_boot: <host-id>' | sudo tee --append /etc/scylla/scylla.yaml
+
+   Use ``nodetool status`` on a live node to obtain the dead node's current Host ID, as described above.
+   Note that the restarted node will be assigned a new random Host ID.
+
+   For example (using the Host ID of the failed node from above):
+
+    ``echo 'replace_node_first_boot: 675ed9f4-6564-6dbd-can8-43fddce952gy' | sudo tee --append /etc/scylla/scylla.yaml``
 
 #. Run the following command to re-setup RAID