Update documents for node-specific domain configuration file

addons/upgrade/to-14.0-update-domain-config-section.pl

@@ -46,6 +46,9 @@ =head1 DESCRIPTION
 
 if ($updated == 1) {
     $ini->RewriteConfig();
+    print("Note: if you are running PacketFence in cluster mode, after this upgrade script,");
+    print("You'll have to manually merge the domain.conf and do a forced configuration sync.");
+    print("Please see the official documention on Authentication / Windows AD section for detailed steps.");
 }
 
 

docs/PacketFence_Upgrade_Guide.asciidoc

@@ -1477,6 +1477,118 @@ Since 14.0 PacketFence is able to receive events from the FleetDM servers, which
 /usr/local/pf/addons/upgrade/to-14.0-adds-admin-roles-fleetdm.pl
 ----
 
+=== Domain configuration changes
+
+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:
+----
+[domainA]
+ntlm_auth_port=5000
+server_name=%h
+dns_name=a.com
+....
+
+[domainB]
+ntlm_auth_port=5001
+server_name=%h
+dns_name=b.com
+....
+----
+
+`domain.conf` structure after v14.0.0:
+----
+[pfv14 domainA]
+ntlm_auth_port=5000
+server_name=%h
+dns_name=a.com
+....
+
+[pfv14 domainB]
+ntlm_auth_port=5001
+server_name=%h
+dns_name=b.com
+....
+----
+
+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.
+
+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 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
+server_name=node1
+dns_name=a.com
+....
+
+[pfv14-2 domainA]
+ntlm_auth_port=5000
+server_name=node2
+dns_name=a.com
+....
+
+[pfv14-3 domainA]
+ntlm_auth_port=5000
+server_name=node3
+dns_name=a.com
+....
+----
+
+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.
+
+[source,bash]
+----
+/usr/local/pf/addons/upgrade/to-14.0-update-domain-config-section.pl
+----
+
+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, 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 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 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
 
 In place upgrades are supported for Redhat EL8. You can follow up the current <<PacketFence_Upgrade_Guide.asciidoc#_upgrade_to_another_version_major_or_minor,Upgrade to another version (major or minor)>>.

docs/installation/authentication_mechanisms.asciidoc

@@ -61,6 +61,43 @@ NOTE: If you are using PacketFence in cluster mode, you must save the domain set
 
 NOTE: after version 14.0, the PacketFence domain.conf will be updated, domain identifier is changed from previously single identifier to "hostname + identifier". If you are running PacketFence in a cluster, please check the corresponding sections for each node.
 
+==== Domain Joining on A PacketFence cluster
+
+We've changed the structure of `domain.conf` configuration file. Since v14.0, each node in a cluster will have their own section.
+They will find and store their domain configurations under sections starts with their hostnames. +
+This change allows each node in a cluster have their indivudual domain configuration. For example, a node doesn't have to use %h as part of the machine
+account created on the domain controller, they now have the ability to fully customize the machine account name. +
+However, due to the isolation of domain.conf on each of the node, they also lost the ability of sharing configuration across the nodes.
+If you are running PacketFence cluster of v14.0, you'll have to join Windows AD on each of the node - this will create a corresponding machine account
+for each of the node when you create the domain profile.
+
+Here is the steps you'll need to follow to create a domain profile in cluster after v14.0:
+Assuming that we have a PacketFence cluster of 3 nodes, and we are about to join "domain.com"
+
+ . Open PacketFence Admin UI, and navigate to "Status" -> "Services" -> "API redirect" or
+ . Access the Admin UI form "https://node_ip:1443" directly.
+
+image::api-redirect.jpg[scaledwidth="100%",alt="API redirect in configuration"]
+
+Either the steps will allow you to create the domain profile on the selected node.
+
+NOTE: Windows does not allow machine account to be shared when initialize secure connection. Therefore, each node in a cluster has to use a unique machine account.
+You can either include %h as part of the machine account or use a unique fully customized machine account name for each of the node. For example, if you use "A" as
+machine account name in node1's domain profile creation, and continued using "A" as machine account name to create a domain profile from another node,
+this will eventually cause node1 and node2 trying to bind the same machine onto its own secure connection, and cause NTLM authentication interruptions and failures.
+
+After we changed the node that handles the API request or we choosed the node manually (method 2), do the following steps:
+
+ . navigate to "Configuration" -> "Policies and Access Control" -> "Active Directory Domains"
+ . fill in the information required to create the domain profile and then click "Create".
+ . PacketFence will create the domain profile for the node *only* that handles the API request.
+ . switch back to API redirect and select another node in the cluster
+ . back to "Configuration" -> "Policies and Access Control" -> "Active Directory Domains" and create the domain profile for another node.
+ . Repeat the previous steps until all the nodes are done with domain profile creation.
+
+
+
+
 ==== Troubleshooting
 
 * In order to troubleshoot unsuccessful binds, please refer to the following file : `/usr/local/pf/log/packetfence.log`. Search for "ntlm-auth-api-domain" for all ntlm-auth-api entries.