diff --git a/addons/upgrade/to-14.0-update-domain-config-section.pl b/addons/upgrade/to-14.0-update-domain-config-section.pl index 46279510def..598dabf4ed9 100755 --- a/addons/upgrade/to-14.0-update-domain-config-section.pl +++ b/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."); } diff --git a/docs/PacketFence_Upgrade_Guide.asciidoc b/docs/PacketFence_Upgrade_Guide.asciidoc index 1dcc2328bce..dfe253796a1 100644 --- a/docs/PacketFence_Upgrade_Guide.asciidoc +++ b/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 <>. diff --git a/docs/images/api-redirect.jpg b/docs/images/api-redirect.jpg new file mode 100644 index 00000000000..ce4e02fd732 Binary files /dev/null and b/docs/images/api-redirect.jpg differ diff --git a/docs/installation/authentication_mechanisms.asciidoc b/docs/installation/authentication_mechanisms.asciidoc index 324088910c4..c2ca8aad28d 100644 --- a/docs/installation/authentication_mechanisms.asciidoc +++ b/docs/installation/authentication_mechanisms.asciidoc @@ -61,6 +61,46 @@ 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 updated the structure of `domain.conf` file since v14.0, +the section name stored in `domain.conf` file has been changed from `domain identifier` to `hostname + domain identifier` combination. +This change causes a node in a cluster to read domain settings from its own individual section identified by its unique hostname. +Therefore, it is not required to use `%h` as (or as a prefix / suffix of) the machine account anymore and +it's technically possible to have customized settings for a specific node. + +If you are running a PacketFence cluster of v14.0 and need a domain profile, you'll have to repeat the profile creation on each of the node because +the domain profile creation will *only* create a profile (and add a machine account) for the node that you are working on (the node that handles the request). + +NOTE: It is required to use individual machine account for each node to avoid secure connection binding issues. + +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.