Skip to content

Commit 4bd58c7

Browse files
stgmsastgmsa
authored
Update documents for node-specific domain configuration file (#8437)
* generate other cluster member's domain config during upgrade. adds background info / FAQs for upgrading prior to v14.0 * change wording * adds notes and suggested steps to create a new domain * adds api redirect image to docs * document domain profile creation steps. * rename example config file host nade name * detail the steps of domain profile creation for a PacketFence cluster v14.0 * adds subdomain joining limitations doc adds authentication best practise with trusted domain relations.
1 parent 0a84fd1 commit 4bd58c7

File tree

4 files changed

+220
-0
lines changed

4 files changed

+220
-0
lines changed

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,9 @@ =head1 DESCRIPTION
4646

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

5154

‎docs/PacketFence_Upgrade_Guide.asciidoc

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1477,6 +1477,118 @@ Since 14.0 PacketFence is able to receive events from the FleetDM servers, which
14771477
/usr/local/pf/addons/upgrade/to-14.0-adds-admin-roles-fleetdm.pl
14781478
----
14791479
1480+
=== Domain configuration changes
1481+
1482+
Since 14.0, we've changed the structure of `domain.conf`, added a `host identifier` prefix to each domain profile. +
1483+
Here is an example of a node joined both domain "a.com" and "b.com". The hostname of the node is `pfv14`.
1484+
1485+
`domain.conf` structure prior to v14.0.0:
1486+
----
1487+
[domainA]
1488+
ntlm_auth_port=5000
1489+
server_name=%h
1490+
dns_name=a.com
1491+
....
1492+
1493+
[domainB]
1494+
ntlm_auth_port=5001
1495+
server_name=%h
1496+
dns_name=b.com
1497+
....
1498+
----
1499+
1500+
`domain.conf` structure after v14.0.0:
1501+
----
1502+
[pfv14 domainA]
1503+
ntlm_auth_port=5000
1504+
server_name=%h
1505+
dns_name=a.com
1506+
....
1507+
1508+
[pfv14 domainB]
1509+
ntlm_auth_port=5001
1510+
server_name=%h
1511+
dns_name=b.com
1512+
....
1513+
----
1514+
1515+
For a standalone PacketFence, compared with the 2 versions of configuration file, the only change is the hostname prefix. +
1516+
However, when it comes to a PacketFence cluster, you will notice that the content of `domain.conf` "duplicated" several times,
1517+
depending on how many nodes there are in a cluster.
1518+
1519+
This structure change will allow each member to have its own configuration: Including individual machine account, password, etc.
1520+
Now all the nodes will be able to join Windows AD using customized machine accounts and passwords without
1521+
having to use %h as part of the machine account name.
1522+
1523+
Here is an example of PacketFence cluster of 3 nodes, the hostnames of each node are: `pf-node1`, `pf-node2` and `pf-node3`, they all joined "a.com" +
1524+
You will see 3 individual machine accounts on Windows Domain Controller, named `pf-node1`, `pf-node2` and `pf-node3` (assuming we are using %h as machine account name).
1525+
1526+
Now the `domain.conf` looks like the following:
1527+
----
1528+
[pf-node1 domainA]
1529+
ntlm_auth_port=5000
1530+
server_name=node1
1531+
dns_name=a.com
1532+
....
1533+
1534+
[pf-node2 domainA]
1535+
ntlm_auth_port=5000
1536+
server_name=node2
1537+
dns_name=a.com
1538+
....
1539+
1540+
[pf-node3 domainA]
1541+
ntlm_auth_port=5000
1542+
server_name=node3
1543+
dns_name=a.com
1544+
....
1545+
----
1546+
1547+
A node will try to find their configuration from the section starts with its hostname.
1548+
1549+
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.
1550+
1551+
[source,bash]
1552+
----
1553+
/usr/local/pf/addons/upgrade/to-14.0-update-domain-config-section.pl
1554+
----
1555+
1556+
If you are upgrading a PacketFence standalone installation prior to v14.0.0, you don't have to do anything else after the
1557+
upgrading script is done.
1558+
1559+
However, if you are upgrading a PacketFence cluster, there are still several additional steps remaining:
1560+
1561+
You *might* have to manually merge the domain configuration +
1562+
or +
1563+
You *might* need to check the joining status and re-join some nodes.
1564+
1565+
It's because PacketFence can convert its own `domain.conf` to the new structure, but not able to access other nodes's configuration.
1566+
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.
1567+
1568+
We have 2 ways to do this:
1569+
1570+
==== option 1: manually merge the domain.conf
1571+
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
1572+
2. If there are missing parts, go to each of the node and copy-paste the corresponding part to master node's `domain.conf`.
1573+
3. save the changes on master node, do a force configuration sync on other nodes.
1574+
1575+
==== option 2: check and rejoin nodes later
1576+
Note:
1577+
You'll still have to use `%h` or `%h` with prefix or suffix as hostnames as you are upgrading from a previous version
1578+
unless you specific individual machine account name for each of the node.
1579+
1580+
. Do a configuration sync after upgrade - so all the slave nodes lost their domain config.
1581+
. Open PacketFence Admin UI, go to "configuration" -> "Policies and Access Control" -> "Active Directory Domains"
1582+
. Take a note of the configuration if you need, we'll need to replicate all the settings on the slave nodes after.
1583+
. Use "API redirect" to switch between nodes or directly access the API using node's IP.
1584+
.. Using API redirect: You can find API redirect from "Admin UI" -> "Status" -> "Services" -> "API redirect" and select the node to handle API request.
1585+
.. Directly access the node using IP address: you can use "https://node_ip:1443/" to select the node to handle API request.
1586+
.. After you select a specific node to handle API request, the "Domain Joining" operation will be performed on the node you selected only.
1587+
. Using either API redirect or manually selection to switch across all the nodes
1588+
. 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.
1589+
. repeat the joining steps on all the nodes to make sure all the nodes are having the same domain profile.
1590+
1591+
14801592
=== RedHat EL8
14811593
14821594
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/images/api-redirect.jpg

104 KB
Loading

‎docs/installation/authentication_mechanisms.asciidoc

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,88 @@ NOTE: If you are using PacketFence in cluster mode, you must save the domain set
6161
6262
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.
6363
64+
==== Domain Joining on A PacketFence cluster (v14.x)
65+
66+
We've updated the structure of `domain.conf` file since v14.0,
67+
the section name stored in `domain.conf` file has been changed from `domain identifier` to `hostname + domain identifier` combination.
68+
This change causes a node in a cluster to read domain settings from its own individual section identified by its unique hostname.
69+
Therefore, it is not required to use `%h` as (or as a prefix / suffix of) the machine account anymore.
70+
Now it's technically possible to have fully customized domain settings for a specific node.
71+
72+
===== Setting up a new cluster
73+
There's a difference in domain profile creation for PacketFence cluster running PacketFence v14.x: +
74+
When you create the domain profile from Admin UI for a PacketFence cluster, The profile is actually created *only* on the node that handles the API request.
75+
Therefore, you'll have to go through all the nodes and create a domain profile for each of them.
76+
77+
During the domain profile creation, a machine account used for NTLM authentication is also created in Windows domain controller.
78+
Due to the limitation of secure connection binding, we are not able to establish multiple secure connections using a shared machine account.
79+
Please make sure the machine account names are unique if you are not using `%h` as (or as part of) the machine account name.
80+
81+
There are 2 ways of creating the domain profile on a selected node:
82+
83+
. Using API Redirect
84+
. Login into Admin Panel using real IP
85+
86+
To use API Redirect, login into *PacketFence Admin Panel*, navigate to *"Status"* -> *"Services"* -> *"API redirect"*, choose a node that handles the API request.
87+
And you will create the domain profile for the node you selected.
88+
89+
Login into Admin Panel using real IP is also simple: Login into *PacketFence Admin Panel* using the node's real management IP instead of virtual IP.
90+
For example, a cluster consists of 3 nodes with a VIP = 192.168.4.70, and real IP = 192.168.4.71, 192.168.4.72, 192.168.4.73.
91+
simply iterate the 3 real IPs, login into Admin Panel from https://real_ip:1443.
92+
93+
94+
===== Upgrade from a version prior to v14.0
95+
If you are doing an upgrade, please refer to the upgrade guide section for v14,
96+
you might need to manually combine the domain configuration file and sync them to all cluster members.
97+
98+
NOTE: It is required to use individual machine account for each node to avoid secure connection binding issues.
99+
100+
101+
===== Domain config file structure and example
102+
Assuming that we have a PacketFence cluster of 3 nodes with hostnames of `pf-node1`, `pf-node2` and `pf-node3` and we joined "domainA"
103+
an example of `domain.conf` for a cluster looks like this:
104+
105+
----
106+
[pf-node1 domainA]
107+
ntlm_auth_port=5000
108+
server_name=node1
109+
dns_name=a.com
110+
....
111+
112+
[pf-node2 domainA]
113+
ntlm_auth_port=5000
114+
server_name=node2
115+
dns_name=a.com
116+
....
117+
118+
[pf-node3 domainA]
119+
ntlm_auth_port=5000
120+
server_name=node3
121+
dns_name=a.com
122+
....
123+
----
124+
125+
image::api-redirect.jpg[scaledwidth="100%",alt="API redirect in configuration"]
126+
127+
Either the steps will allow you to create the domain profile on the selected node.
128+
129+
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.
130+
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
131+
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,
132+
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.
133+
134+
After we changed the node that handles the API request or we choosed the node manually (method 2), do the following steps:
135+
136+
. navigate to "Configuration" -> "Policies and Access Control" -> "Active Directory Domains"
137+
. fill in the information required to create the domain profile and then click "Create".
138+
. PacketFence will create the domain profile for the node *only* that handles the API request.
139+
. switch back to API redirect and select another node in the cluster
140+
. back to "Configuration" -> "Policies and Access Control" -> "Active Directory Domains" and create the domain profile for another node.
141+
. Repeat the previous steps until all the nodes are done with domain profile creation.
142+
143+
144+
145+
64146
==== Troubleshooting
65147
66148
* 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.
@@ -116,6 +198,29 @@ You should now have the following realm configuration
116198
117199
image::domain-realms-index.png[scaledwidth="100%",alt="Realms"]
118200
201+
==== Windows subdomain joining limitations
202+
203+
PacketFence supports multiple domain authentications as well as authentications performed against domains and subdomains.
204+
205+
But please be aware that according to Windows Domain Controller's architecture and implementation,
206+
you can not join PacketFence on a subdomainif your subdomain shares the Domain Controller with the existing parent domain. +
207+
208+
The only way to join PacketFence on a subdomain is to join it on a subdomain who has its own Domain Controller that belongs to a parent domain.
209+
210+
Please check Microsoft's Learn, FAQ and discussions about subdomain computer joining. +
211+
https://learn.microsoft.com/en-us/answers/questions/342052/can-create-an-sub-domain-and-add-user-uder-the-cre
212+
213+
214+
==== Authenticating using Windows Trusted Domains
215+
PacketFence supports domain trust relations to be passed to the correct Domain Controller.
216+
However, there isn't a way to configure the trusted domain settings from the Admin UI.
217+
218+
If you'd like to authentication resources on a trusted domain, please use the "--domain=" option in ntlm_auth_wrapper.
219+
You'll need to manually modify PacketFence's FreeRADIUS mschap module template file located at `/usr/local/pf/conf/radiusd/mschap.conf`
220+
Locate the best mschap section works for your situation and add a `--domain=_YOUR_DOMAIN_TRUST_SETTINGS_` to your ntlm_auth_wrapper executable path.
221+
222+
After saving the changes, please re-generate the FreeRADIUS configuration by restarting radius services and test if it works.
223+
119224
120225
=== OAuth2 Authentication
121226

0 commit comments

Comments
 (0)