How to troubleshoot the Configure Target OS (CTOS) action in Provisioning templates

One of the most common uses of Provisioning is to extend the capacities and functions of imaging or new device deployments to include the installation of the OS as well as configuration settings and software installations. In order to bridge the gap between WinPE and the new OS, LANDESK uses a process called Configure Target OS (abbreviated as CTOS). This is a separate action that needs to be added to the template for a template that installs an image, and is included as part of the Scripted Install action. This article covers the function and troubleshooting of the Configure Target OS action

Configure Target OS overview

The Configure Target OS (CTOS) action is available only in the Post-OS installation section of the provisioning template. It needs to be the final action in the template before the System Configuration section, no actions can come after the CTOS action. The CTOS prepares the device to resume provisioning after the client boots into the target OS, then restarts the device, leaving WinPE and allowing the computer to boot normally. In order for the CTOS action to work, the image that was deployed to the client MUST be sysprepped.

The Configure Target OS takes advantage of a few Microsoft technologies in order to resume when the device completes booting into the target OS (Windows XP, 2003, 2008, 7, 8, 8.1, 2012). Files are injected to the root of the OS drive (C:\ldprovision) and commands are added to the appropriate files such that they are run during the mini-setup just prior to booting into the target OS.

Windows XP/2003

1. All needed files are copied to C:\sysprep\i386\ldprovision directory on the client device. The C:\sysprep\i386 directory must exist and be accessible
   
   Note: Sysprep is responsible for creating the i386 folder.  If the folder is not getting created, you can get around the issue by creating a new action in the script, putting the action in front of the CTOS action, that creates this folder.  If this folder does not exist it will cause the failure of any additional action after CTOS runs and reboots the client.
   
   
2. The cmdlines.txt file in the OEM folder on the client device is created or modified. A line is added to call ldprovisioning.cmd. Windows will run cmdlines.txt at the end of the mini-setup, calling ldprovisioning.cmd.

Windows 7, 8, 8.1, 2008, 2012

1. All needed files are copied to C:\ldprovisioning directory on the client device.
2. The unattend.xml is modified and commands are added to call ldprovisioning.cmd from the C:\ldprovisioning directory.

LDProvision.cmd

When run, ldprovisioning.cmd installs the basic LANDESK CBA agent in C:\Program Files\LANDESK\LDClient and configures it as a service to start on OS boot. It also modifies the actions.ini file in C:\Program Files\LANDESK\Shared Files\cbaroot to contain a line pointing to C:\ldprovision\ldprovision.exe with the needed command line options. The actions.ini file is used by the LANDESK CBA agent as instructions when starting, so the commands contained therein are run when the service starts.

Troubleshooting Configure Target OS

Troubleshooting the CTOS action can be especially difficult. Because of the nature of the operation and how it works, LANDesk must give up control to the Windows installation processes for a time, and then resume afterwards. This can sometime make it difficult to determine where the problem is occurring. The problem can be in WinPE trying to copy and modify files, it can be somewhere in the mini-setup of the OS, and it can be after the OS has completed all setup tasks and has fully booted.

The first step to troubleshoot the CTOS action is to determine where in the process the failure is occurring. The CTOS action will not always get marked as failed. Often provisioning just fails to continue through the rest of the template.

WinPE

This is where it is most likely to see an actual failure of the template. Usually this means something could not be copied correctly or modified. The device will stay in WinPE after the template fails so troubleshooting can be done in the exact condition the device is in when it fails.

1. Open a new console in WinPE.
2. Check to make sure that the C: drive is accessible.
3. Change to the C: drive and look around. Does it look like the image was put down correctly?
4. Check for the ConfigTargetOSHandler.log in SystemDrive\Windows\Temp. This will normally show where the failure may have occurred if you get errors during file copy/creation.

If you deployed:

     Windows XP/2003

1. Change to C:\sysprep directory. Verify that the I386 directory exists. Look to see if the ldprovision folder was created and populated

   1. Note: Sysprep is responsible for creating the i386 folder.  If the folder is not getting created, you can get around the issue by creating a new action in the script, putting the action in front of the CTOS action, that creates this folder.  If this folder does not exist it will cause the failure of any additional action after CTOS runs and reboots the client.  This also prevents the $OEM$ directory from being created in the i386 folder.
      

2. Check the cmdlines.txt in C:\sysprep\$OEM$\ and make sure it contains a line for ldprovisioning.cmd
3. Verify that ldprovisioning.cmd is in C:\sysprep\$OEM$\

     Windows 7, 8, 2008, 2012

1. Change to C:\ldprovisioning directory. Verify the ldprovisioning.cmd is in the folder and the folder is populated. It should contain over 20 files.
2. Verify that the unattend.xml exists in C:\Windows\Panther
3. Verify that the commands calling ldprovisioning.cmd exist in the unattend.xml for the platform (x86, amd64, ia64) you have deployed.

     Windows 8.1

1. Change to C:\ldprovisioning directory. Verify the ldprovisioning.cmd is in the folder and the folder is populated. It should contain over 20 files.
2. Verify that the unattend.xml exists in C:\Windows\Panther
3. Verify that the content of the file %windir%\Windows\Setup\scripts\SetupComplete.cmd contains the following line; %systemdrive%\ldprovisioning\ldprovisioning.cmd

Sometimes all of these will be correct and ready to go, but the device will remain in WinPE. Usually there is not a failure of the task. It is possible that the reboot command didn't run correctly but everything else did. To verify this, simply restart the client and observe the results.

Between WinPE and Windows

After the client reboots out of WinPE it will boot off the hard drive into the target OS. Because the image was sysprepped, it will go through a mini-setup process. If no sysprep file was provided, it will prompt for a number of items such as the computer name, user names, time zone, product key, etc before completing the booting process into the target OS.  LANDesk has no control over this process and is not running at all. Near the end of the mini-setup process Windows executes the commands that LANDesk added during the CTOS action. For Windows XP and 2003 the mini setup executes the commands in the cmdlines.txt at then end of the sysprep steps. For Windows Vista, 2008 and 7 the commands are exeucted during the Specialize pass in the unattend.

Windows XP/2003

The important file here is the cmdlines.txt This file should contain the call to ldprovisioning.cmd. It is here that LANDesk is again introduced into the process. When cmdlines.txt is executed it runs ldprovisioning.cmd from the same directory, which prepares the device to resume provisioning after the whole mini-setup process is complete.

Windows 7, 8, 2008, 2012

Sections are added to the unattend.xml in the Specialize section. This is a special section of the unattend.xml that can also be used for things like setting the home page for Internet Explorer, etc. In this section, the RunSynchronousCommand action is added calling ldprovisioning.cmd from C:\ldprovisioning\. The section of the unattend will look roughly like the following:

<settings pass="specialize" xmlns="" wasPassProcessed="true">
    <component name="Microsoft-Windows-Deployment" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <RunSynchronous>
            <RunSynchronousCommand action="add">
                <Description>LANDesk Provisioning Install</Description>
                <Order>1</Order>
                <Path>cmd /c %systemdrive%\ldprovisioning\ldprovisioning.cmd</Path>
            </RunSynchronousCommand>
        </RunSynchronous>
    </component>
</settings>

Windows 8.1

As mentioned in Add a Custom Script to Windows Setup a command line is injected within the SetupComplete.cmd (%systemdrive%\ldprovisioning\ldprovisioning.cmd) which will then be run after the reboot following the mini-setup phase. Hence, the system will follow the provisioning process when rebooting.

In Windows

Once the device completes the mini-setup section, it will boot into the final OS. As the device boots up, it runs the LANDesk Management Agent service that was installed by ldprovisioning.cmd. As part of the startup process, the LANDesk Management Agent will run the commands in the actions.ini file. The actions.ini file was also modified by ldprovisioning.cmd to contain the following command

C:\ldprovisioning\ldprovision.exe -c <CORE>

Troubleshooting Tip: If you would like to get extra logging for problems you are seeing later in the template, open this file BEFORE the device completes the boot after the mini-setup and change it to the following:

C:\ldprovisioning\ldprovision.exe -c <CORE> -V 255 -L C:\<LOG FILE>

       Note: the -V is a capital V and is case sensitive

Once ldprovision.exe starts, it queries the core server for the next action in the template, and provisioning will continue with the actions in the System Configuration section.

───────────────────────────────────────

See also CTOS action fails after reboot.