Fixes #21952: Documentation for FQDN overriding

src/reference/modules/usage/pages/advanced_node_management.adoc

@@ -1,5 +1,53 @@
 = Advanced node management
 
+[[override-node-fqdn]]
+== Override node FQDN
+
+Sometime, the node's FQDN reported in inventory is not the correct one. For example, the configured
+FQDN is an internal name, or it's incorrectly set-up by OS or not found in a normalized format by the agent. 
+
+This can be problematic and for example break the possibility for Rudder to trigger an agent run from node's 
+compliance page.
+
+In these cases, you can override the FQDN from the node thanks to a xref:extend-nodes-inventory[node inventory extension].
+
+The inventory extension must define the reserved property key `rudder_override_hostname` with a string value.
+
+If that key is defined, it is preferred to other values retrieved in agent inventory (`<RUDDER><HOSTNAME>` or else
+`<OPERATINGSYSTEM><FQDN>`) as the FQDN for the node. 
+
+When the override is used, an additional inventory extension key `rudder_original_hostname` is also defined. That key's value
+contains the original node hostname which would have been used without an override.
+
+[NOTE]
+
+====
+The value used for overriding FQDN must be legit https://datatracker.ietf.org/doc/html/rfc1123#page-13[as of RFC1123 (section 2.1)]
+else it won't be used in place of the original one.
+====
+
+Example inventory hook script to put on the node so that the node will be
+seen on Rudder with the FQDN `node1-overridden.rudder.local.override`:
+
+----
+
+$ cat /var/rudder/hooks.d/override-hostname.sh
+echo '{"rudder_override_hostname": "node1-overridden.rudder.local.override"}'
+
+----
+
+Example of resulting node properties (in Rudder UI and API):
+
+----
+
+{
+  "rudder_override_hostname": "node1-overridden.rudder.local.override",
+  "rudder_original_hostname": "agent1.rudder.local"
+}
+
+----
+
+
 == Reinitialize policies for a Node
 
 To reinitialize the policies for a Node, delete the local copy of the applied