Bending the Hydration Kit to Fit an Existing Domain

Posted on by Haakon

If you’ve ever built a ConfigMgr lab from scratch, you know Johan Arwidmark’s name. His Hydration Kit has been saving people from the soul-crushing manual install process for over a decade. You download it, run two scripts, copy some ISOs, and 90 minutes later you have a fully functional ConfigMgr lab with a domain controller, SQL Server, and a primary site. It’s a genuine gift to the community.

So naturally, I decided to use it in the one way it wasn’t designed for.

(Side note: Johan also offers a free mini course on the ViaMonstra Academy that walks through the kit setup and a ton of related lab tips. Worth watching even if you’ve been doing this for years.)

The Starting Point

My lab has been running for a while. Domain controller at 10.50.50.10 (CT-DC01), Enterprise CA, NDES server, pfSense firewall. All of it humming along on the dev.contoso.com domain. When I decided to bolt ConfigMgr onto this setup, the Hydration Kit was the obvious choice. But the kit assumes you’re starting from zero. It wants to build its own DC, its own domain, its own DHCP. I already had all of that.

The kit ships with a customization script by Matt Benninge (CustomizeHydrationKit.ps1) that handles the heavy lifting: domain name, IP addresses, org name, timezone, passwords. It’s a thoughtful piece of work. It backs up every file before modifying it, supports re-runs without breaking anything, and does a thorough sweep across every INI, PS1, WSF, and XML file in the deployment share. For the most part, it works exactly as advertised. It’s great!

Until the script was run by me.

A quick thank you to Matt Benninge (@matbg) for writing the customization script in the first place, and to Andrew Johnson (@andrewjnet) for extending it with client sequence and AD user/OU customization. Without their work, the only option would be hand-editing dozens of files across the deployment share. The script’s existence is what makes this entire approach possible.

The Customization

The script’s variable block is clean and self-explanatory. Map your values, point it at your deployment share, run it. My setup needed:

  • Domain: corp.viamonstra.com to dev.contoso.com
  • Network: 192.168.25.0/24 to 10.50.50.0/24
  • Org name: ViaMonstra to Contoso
  • Timezone: Pacific to W. Europe Standard Time
  • Server IPs: Slotted into the .41-.44 range to avoid my existing infrastructure
  • Hostnames: Prefixed with CT- to match my naming convention (OSDComputerName=CT-CM01)

I also skipped the DC01 task sequence entirely. My domain controller was already built and populated. Instead, I wrote a separate AD prep script that replicates what the DC01 task sequence does: schema extension, System Management container creation, permission delegation, subnet registration, service account creation. That script runs against the existing CT-DC01 before you boot any hydration VMs.

The customization output looked perfect. Every ViaMonstra reference replaced, every IP remapped, every hostname prefixed. I rebuilt the boot ISO, created the VMs, and started deploying.

FS01 hydrated without a hitch. CM01 started strong, installed Windows, joined the domain, installed SQL Server… and then ConfigMgr setup crashed.

Gotcha #1: The FQDN That Didn’t Get Renamed

To be clear: this only surfaces if you rename the server hostnames. If you stick with the default CM01, MDT01, etc. (just changing the domain and IPs), the kit works flawlessly. I was pushing the customization further than most people would, and found an edge case.

The error in ConfigMgrSetup.log was blunt:

CTool::ConfigureSQLAlias() failed to connect to the Registry with error 53
ERROR: Failed to configure SQL alias CM01.dev.contoso.com on server CM01.dev.contoso.com.

Error 53: network path not found. Setup was trying to reach a machine called CM01.dev.contoso.com, but the actual hostname was CT-CM01.dev.contoso.com. The OS got the right name through OSDComputerName. ConfigMgr’s unattend file didn’t.

The customization script correctly turned CM01.corp.viamonstra.com into CM01.dev.contoso.com (domain suffix updated). But it never touched the CM01 hostname portion. Five FQDN variables in ConfigMgrUnattend.ini still pointed at the old server name:

SDKServer=CM01.dev.contoso.com
ManagementPoint=CM01.dev.contoso.com
DistributionPoint=CM01.dev.contoso.com
SQLServerName=CM01.dev.contoso.com
CloudConnectorServer=CM01.dev.contoso.com

The same problem exists in ConfigMgrUnattendWithoutDP.ini.

The fix is a targeted replacement after the main customization runs:

$files = @(
    "$HydrationSource\DS\Applications\Install - ConfigMgr\ConfigMgrUnattend.ini",
    "$HydrationSource\DS\Applications\Install - ConfigMgr\ConfigMgrUnattendWithoutDP.ini"
)
foreach ($file in $files) {
    (Get-Content $file) -replace 'CM01\.dev\.contoso\.com', 'CT-CM01.dev.contoso.com' | Set-Content $file
}

Or better yet, the customization script should accept a $NewCM01ComputerName parameter and handle this automatically.

Gotcha #2: The Org Name That Wasn’t a Domain Name

This one only bites you if your organization name and NetBIOS domain name are different strings, which is actually fairly common in real-world environments. The default kit uses VIAMONSTRA for both, so the script understandably treats them as interchangeable.

The customization script does a blanket replacement of VIAMONSTRA with your org name:

Update-HKContentRecurse -SourceFiles $sourceFiles -pattern 'VIAMONSTRA' -NewValue $NewOrgName -ToUpper

In my setup, the org name is Contoso, but the NetBIOS domain is DEV (derived from dev.contoso.com). The blanket replacement turned VIAMONSTRA\Administrator into CONTOSO\Administrator in three files. That’s wrong. It should be DEV\Administrator.

Affected files:

ConfigurationFile.ini (SQL Server install):

SQLSYSADMINACCOUNTS="CONTOSO\Administrator" "BUILTIN\Administrators"

Install-HYDSQLServer2019.ps1 (has a hardcoded string match that must mirror ConfigurationFile.ini exactly, or the replacement silently fails):

$OriginalSQLSYSADMINACCOUNTS = "SQLSYSADMINACCOUNTS=`"CONTOSO\Administrator`" `"BUILTIN\Administrators`""

HYDCMRSPConfig.ps1 (SSRS reporting):

$SSRSUsername = "CONTOSO\CM_SR"

SQL Server setup fails because CONTOSO\Administrator doesn’t resolve. SSRS configuration fails for the same reason.

The fix: the customization script needs a separate $NewNetBIOSName parameter. References with a trailing backslash (VIAMONSTRA\) are domain qualifiers and should use the NetBIOS name. Everything else (display strings, OU names, descriptions) keeps the org name.

You can find affected lines in any deployment share with:

Get-ChildItem -Recurse "C:\CMLab\DS" -Include *.ini,*.ps1,*.wsf,*.xml | Select-String 'VIAMONSTRA\\' | Select-Object Path, Line

I filed both as issues on the HydrationKitWS2022 GitHub repo with suggested fixes. Hopefully useful for the next person who tries this.

The AD Prep Script

Since we’re skipping the kit’s DC01 task sequence, the domain needs to be prepared manually. I wrote a step-by-step script that runs on CT-DC01 before any hydration VMs are deployed. The key steps:

  1. Extend the AD schema for ConfigMgr using extadsch.exe from the CM source media.
  2. Create the System Management container under CN=System and delegate Full Control to the CM01 computer account.
  3. Register the AD subnet (10.50.50.0/24 in Default-First-Site-Name).
  4. Pre-stage computer accounts in the correct OUs so domain join lands them in the right place.
  5. Create the ConfigMgr service account in the Service Accounts OU.

The important thing is running it before you boot CT-CM01 from the hydration ISO. ConfigMgr setup checks for the schema extensions and System Management container during install.

The Build Order

For anyone doing this with an existing domain:

  1. Run the customization script against the deployment share
  2. Manually fix ConfigMgrUnattend.ini FQDNs (until the upstream fix lands)
  3. Manually fix VIAMONSTRA\ to YOURNETBIOS\ references (until the upstream fix lands)
  4. Run the AD prep script on your domain controller
  5. Rebuild the boot ISO (Update Media Content on MEDIA001 in Deployment Workbench)
  6. Deploy FS01 first (ConfigMgr needs the file server accessible)
  7. Deploy CM01 (the long one: SQL, ConfigMgr, SSRS)
  8. Open the ConfigMgr console, run Updates and Servicing, upgrade to latest current branch
  9. Deploy MDT01 and any other optional servers

A couple of operational notes: run the deployment share setup script (New-HydrationKitSetup.ps1) from Windows PowerShell 5.1, not PowerShell 7. MDT’s snap-in architecture doesn’t exist in pwsh. Also, don’t use dynamic memory on the Hyper-V VMs during hydration. The task sequences get slow or hang. Flip to dynamic after hydration completes.

The VM Creation Script

The kit includes New-LabVMsForHyperV.ps1 which creates all the VMs in one shot. It does what it says on the tin, and for a fresh lab it’s the fastest path. In my case, I already had an existing Hyper-V setup with organized storage paths, vTPM, and Secure Boot on every VM. Rather than retrofitting the created VMs, I used my own creation script that matched my existing conventions. Three calls with the hydration ISO mounted, and the VMs were ready to go.

Was It Worth It?

Absolutely. ConfigMgr is notoriously painful to install manually. Johan’s kit compresses what would be a full day of clicking through wizards into an automated, repeatable process. The task sequences are well-structured, the deployment share layout is logical, and Matt’s customization script covers 95% of what you’d need to change. The fact that I could skip the DC01 task sequence entirely and still have everything else work speaks to how cleanly the kit is architected.

The two gotchas I hit are edge cases that surface only when you push the customization beyond what the defaults expect. Both have simple fixes, and I’ve filed them upstream so the maintainers can decide how to handle them. This is open source working exactly as intended: use it, find the edges, contribute back.

Even with the detours, I went from zero to a working ConfigMgr 2509 site in a few hours. Tear down CM01, rebuild the ISO, deploy again. That repeatability is the real value, and it’s a testament to the work Johan, Matt, and the contributors have put into this kit over the years.

My lab now has a full ConfigMgr primary site integrated with the existing domain, certificate infrastructure, and cloud services. Next up: wiring it to Intune through cloud attach, and setting up Global Secure Access for remote access to the lab.

Related Posts