In this series of posts, I want to look at practical ways to troubleshoot ConfigMgr client migrations, and include a number of Powershell scripts to help in the process. These processes were tested on a client migration from ConfigMgr 2007 R3 to 2012 R2.
In my experience the majority of client migrations work well using the out-of-box client upgrade methods, but there always seem to be clients that do not migrate. In the company I work for, even after allowing some days for computers that were not connected to the network because people were travelling, or on vacation etc, there remained a good number of client machines that did not migrate. Of course, it would be lovely for ConfigMgr to monitor all the upgrade installations, then give you a report like, ‘Yo, ConfigMgr admin dude! These clients did not upgrade successfully, this is why, and this is how to fix them.’ Better still, a big button that says ‘Yes Please!’ to the question ‘Do you want me to fix these machines?’
But back in the real world, we must go through a process to troubleshoot each machine that didn’t upgrade successfully, and I’ve discovered Powershell can make this a lot easier!
The Client Installation Process (a Broad Overview)
Once the ConfigMgr client has been ‘pushed’ to a machine using the SCCM console, the site server will attempt to connect to that machine using the admin$ share (typically C:\Windows) using the Client Push account credentials. It will then copy two files to the %windir%\ccmsetup directory: ccmsetup.exe and MobileClient.tcf. It will create a service for ccmsetup.exe and start it. The ccmsetup service will contact the local distribution point to get the package files it needs for the SCCM client and copy them to the ccmsetup directory. If you selected to uninstall any previous client, it will do that, then install the new client.
This is described further, along with some troubleshooting tips, in the following articles:
http://support.microsoft.com/kb/925282
Troubleshooting – the Basics
The two most useful places to look for client upgrade failures are in the CCM.log on the Site Server, and the logs created by the ccmsetup process on the client machine. Not everyone will agree that using the out-of-the box client installation methods are the best way to install or upgrade a client, but they do have a big benefit – they log to the CCM.log on the Site Server, and this contains some useful information about ConfigMgr’s attempts to install the client on a remote machine. If it cannot find the machine on the network, or cannot connect to the admin$ share with the provided credentials for example, you can find that recorded in this log file.
Much more detailed logging of the installation process takes place on the client itself. ConfigMgr copies the required files to the client machine in the ccmsetup directory, eg C:\Windows\ccmsetup, and runs the ccmsetup.exe as a service, using any installation properties specified in the ConfigMgr console (Client Push Installation). It creates a subfolder for the logs, which include:
- ccmsetup.log. Usually the last line in this log file indicates whether the installation was successful, for example ‘CcmSetup is exiting with return code 0‘ indicates a successful installation.
- client.msi.log. The client.msi is the client installer itself and this logfile contains very detailed information. Almost at the end of the log file, you will find lines like ‘Product: Configuration Manager Client — Installation operation completed successfully.’ and ‘Windows Installer installed the product. Product Name: Configuration Manager Client. Product Version: 5.00.7958.1000. Product Language: 1033. Manufacturer: Microsoft Corporation. Installation success or error status: 0.‘ that indicate a successful installation.
- client.msi_uninstall.log. If you chose the option to uninstall previous clients during the installation, this process will be recorded here. Near the end of the log file you will find lines like ‘ Product: Configuration Manager Client — Removal completed successfully.’ and ‘Windows Installer removed the product. Product Name: Configuration Manager Client. Product Version: 5.00.7958.1000. Product Language: 1033. Manufacturer: Microsoft Corporation. Removal success or error status: 0.’ that indicate the successful removal of older clients.
Application Event Log
Installation success or failure is also recorded in the client’s Application event log using the same event messages that are mentioned in the log files above. For example, if the client installation succeeds, you will find the following event IDs:
Client Installation Success
- 11707: Product: Configuration Manager Client — Installation operation completed successfully.
- 1033: Windows Installer installed the product. Product Name: Configuration Manager Client. Product Version: 5.00.7958.1000. Product Language: 1033. Manufacturer: Microsoft Corporation. Installation success or error status: 0.
Or if the previous client failed to uninstall:
Previous Client Removal Failure
- 11725: Product: Configuration Manager Client — Removal failed.
- 1034: Product: Configuration Manager Client — Removal failed.
Follow the Checklist
Now that we know where to look to identify potential problems, we need to run some simple checks against a machine to help narrow down where the client installation is failing. This is the checklist I follow:
- Ping the machine. If I can’t ping the machine, then probably it’s not connected to the network at the moment, or there is a firewall issue. I can’t do anything until I can connect to the machine on the network.
- Connect to the admin$ share. If we can’t connect to the admin$ share, then ConfigMgr cannot copy packages to the client, or do anything much.
- Check if the %systemRoot%\CCM directory exists. If it does, ConfigMgr has likely installed the new client successfully as it places most of the client files here, so this folder shouldn’t exist if the installation was unsuccessful.
- Check if the %SystemRoot%\ccmsetup directory exists. If it does, there’s a good chance ConfigMgr has been able to copy at least the ccmsetup.exe to the client.
- Check if %SystemRoot%\ccmsetup\ScepInstall.exe exists. ConfigMgr copies some additional files to the ccmsetup directory before it begins the client installation. One of those is the Scepinstall.exe, which is the Endpoint Protection Client. If this doesn’t exist, then there is probably a connectivity issue, for example the client cannot access the distribution point to get the client package.
- Review the client logs. If the %SystemRoot%\ccmsetup\Logs directory exists, then the ccmsetup process has attempted to run, and will have created some logs here. Review the logs mentioned previously using the CMTrace utility to identify errors.
Checking Multiple Machines
That’s well and good, you may say, but it’s a lot of work to manually check every computer that failed to install the new SCCM client. Isn’t there something easier?
Powershell to the rescue! Next time we’ll look at a script that performs all these checks against multiple machines, so you can sit back, relax and let your computer do all the hard work 🙂
