change wording

docs/PacketFence_Upgrade_Guide.asciidoc

@@ -1479,9 +1479,8 @@ Since 14.0 PacketFence is able to receive events from the FleetDM servers, which
 
 === Domain configuration changes
 
-Since 14.0, we've changed the structure of `domain.conf`, added a hostname prefix on each domain identifier.
-Here is an example of `domain.conf` found on a node joined into 2 different domains: "a.com" and "b.com",
-we assume that the node has a hostname of "pfv14"
+Since 14.0, we've changed the structure of `domain.conf`, added a `host identifier` prefix to each domain profile. +
+Here is an example of a node joined both domain "a.com" and "b.com". The hostname of the node is `pfv14`.
 
 `domain.conf` structure prior to v14.0.0:
 ----
@@ -1513,16 +1512,18 @@ dns_name=b.com
 ....
 ----
 
-This structure change will allow each member in a cluster to have different domain configurations.
-The node now will be able to join into Windows AD using different machine account and password individually without
-having to use the same %h as part of the machine account and same password.
+For a standalone PacketFence, compared with the 2 versions of configuration file, the only change is the hostname prefix. +
+However, when it comes to a PacketFence cluster, you will notice that the content of `domain.conf` "duplicated" several times,
+depending on how many nodes there are in a cluster.
 
-A typical case is when we set up a cluster of 3 nodes, all the nodes will have to use "%h" or "%h-suffix" as the machine account name,
-so on the Windows Domain Controller, there will be 3 different machine account created using the 3 nodes' hostnames / hostnames-prefix as machine account name.
+This structure change will allow each member to have its own configuration: Including individual machine account, password, etc.
+Now all the nodes will be able to join Windows AD using customized machine accounts and passwords without
+having to use %h as part of the machine account name.
 
-Here is another example of `domain.conf` to make this easier to understand:
-Let's assume that the hostnames of each node are: `pfv14-1`, `pfv14-2` and `pfv14-3`, and they all joined into "a.com"
+Here is an example of PacketFence cluster of 3 nodes, the hostnames of each node are: `pfv14-1`, `pfv14-2` and `pfv14-3`, they all joined "a.com" +
+You will see 3 individual machine accounts on Windows Domain Controller, named `pfv14-1`, `pfv14-2` and `pfv14-3` (assuming we are using %h as machine account name).
 
+Now the `domain.conf` looks like the following:
 ----
 [pfv14-1 domainA]
 ntlm_auth_port=5000
@@ -1543,8 +1544,7 @@ dns_name=a.com
 ....
 ----
 
-Now, each node will only find their domain configuration from the section that starts with its hostname.
-If the corresponding section does not exist, the node is considered not having joined a domain.
+A node will try to find their configuration from the section starts with its hostname.
 
 During the upgrading process, the following script will be executed on each node. It will add the hostname prefix to each of the domain sections to match the new `domain.conf` structure.
 
@@ -1556,24 +1556,38 @@ During the upgrading process, the following script will be executed on each node
 If you are upgrading a PacketFence standalone installation prior to v14.0.0, you don't have to do anything else after the
 upgrading script is done.
 
-However, if you are upgrading a PacketFence cluster, it's a little different:
+However, if you are upgrading a PacketFence cluster, there are still several additional steps remaining:
 
-You *might* have to manually merge the domain configuration
-or
-You *might* need to check the joining status and re-join some of the nodes.
+You *might* have to manually merge the domain configuration +
+or +
+You *might* need to check the joining status and re-join some nodes.
 
-It's because PacketFence is able to convert its own `domain.conf` to the new structure, but not able to convert other nodes'
+It's because PacketFence can convert its own `domain.conf` to the new structure, but not able to access other nodes's configuration.
 If you already did a force configuration sync before merging the `domain.conf` on master node, the configuration the nodes that being synced is lost.
 
 We have 2 ways to do this:
 
 ==== option 1: manually merge the domain.conf
  1. check the `domain.conf` on each of the node and make sure if all the nodes have both their own section and sections of other cluster members
- 2. if `domain.conf` has all the member's configuration, nothing need to be done.
- 3. if there's a missing part (e.g., if we synced the configurations before it's all updated on each nodes), copy-paste the missing part to `domain.conf` on master node.
- 4. after all the missing part is merged to master node, do a configuration reload and force sync to other nodes.
+ 2. If there are missing parts, go to each of the node and copy-paste the corresponding part to master node's `domain.conf`.
+ 3. save the changes on master node, do a force configuration sync on other nodes.
 
 ==== option 2: check and rejoin nodes later
+Note:
+You'll still have to use `%h` or `%h` with prefix or suffix as hostnames as you are upgrading from a previous version
+unless you specific individual machine account name for each of the node.
+
+ . Do a configuration sync after upgrade - so all the slave nodes lost their domain config.
+ . Open PacketFence Admin UI, go to "configuration" -> "Policies and Access Control" -> "Active Directory Domains"
+ . Take a note of the configuration if you need, we'll need to replicate all the settings on the slave nodes after.
+ . Use "API redirect" to switch between nodes or directly access the API using node's IP.
+   .. Using API redirect: You can find API redirect from "Admin UI" -> "Status" -> "Services" -> "API redirect" and select the node to handle API request.
+   .. Directly access the node using IP address: you can use "https://node_ip:1443/" to select the node to handle API request.
+   .. After you select a specific node to handle API request, the "Domain Joining" operation will be performed on the node you selected only.
+ . Using either API redirect or manually selection to switch across all the nodes
+ . Fill the identical domain information on each API node, and click "Create", this will create the domain.conf file and join the corresponding machine on Windows AD.
+ . repeat the joining steps on all the nodes to make sure all the nodes are having the same domain profile.
+
 
 === RedHat EL8