How It Works: PDQ Deploy

Purpose

You wish to understand how PDQ Deploy installs software. This can be helpful in troubleshooting deployment issues.

Resolution

Depending on your PDQ Deploy preference settings, there may be slight variations in the process outlined below.

Package Files on the PDQ Console Computer:
First, we create/import a PDQ Deploy package for Microsoft Silverlight 5.1. Opening the package and selecting an Install Step, the Install File location is $(Repository)\Microsoft\Silverlight\Silverlight-5.1.50901.0.exe.

From the image above, the Install File is placed in the $(Repository). The Repository is a system variable defined by Options > Preferences > Repository. By default, the Repository folder is located in %PUBLIC%\Documents\Admin Arsenal\PDQ Deploy\Repository.

PDQ Deploy Credentials:
PDQ Deploy utilizes three sets of credentials. They can be the same credentials or different, depending on the needs of your environment, and the article PDQ Credentials Explained covers these in more detail.

Background Service:
The first set of credentials are the Background Service credentials, located in Options > Background Service. These credentials were supplied when PDQ Deploy was first run.

In the above example, the PDQ Deploy Background Service (called PDQDeploy) runs under the domain user account PDQUser in the deadwood.local domain.

NOTE: is not necessary the Background Service credentials have local admin privileges on target machines, but they are required to have local admin privileges on the PDQ console machines regardless whether the consoles are running Central Server or configured to run in Local Mode.

Credentials:
The second set of credentials are the Credentials as found in Options > Credentials. These credentials are the credentials used as the Deploy User and runs the deployments on target machines via the remote runner service.

IMPORTANT: As the Deploy User, the user(s) in Options > Credentials must be a local administrator on all target machines.

Console Users:
The last set of credentials are Console Users in Options > Console Users. These credentials are necessary if a user will be opening the PDQ Deploy console and that user is not the Background Service user. In this example, we’re opening PDQ Deploy using the deadwood.com\Jane.Doe credentials and not the deadwood.local\PDQUser credentials. Because of this, it is necessary to have Jane Doe listed in Console Users.

The deployment Credentials are set to DOMAIN.COM\PDQDeploy (see above). Here's an example using the Deploy Once window:

NOTES:

References to the Background Service apply to the Background Service running on the PDQ Deploy console computer. References to the Runner Service refer to the service running on the remote target computer.
When deploying to targets in child/sub-domains using a domain-specific account, OR to targets in a workgroup, it is necessary to Disable UAC.
For more information on Console Users (Options > Background Service), see Our Handy Video.
In Options > Credentials, the (default) user credentials are the default deployment credentials.

Package Deployment Process:
Using the examples above, there are three target computers: Guinness, Heineken, and Lopan.

Step 1: The PDQ Deploy Background Service attempts to retrieve the installer file, Silverlight_x64-5.1.50901.0.exe from $(Repository)\Microsoft\Silverlight\.

NOTE:
In Enterprise Mode, there is a Copy Mode option (Options > Preferences > Performance). The default method is "Push". If the Copy Mode is changed to "Pull," the Background service will not attempt to copy the files down to each target. Each target will attempt to Pull the files down using the Runner service. In this case, the deployment Credentials (Options > Credentials) MUST have full access to the package files. For more information about Push and Pull, please see the article PDQ Deploy Copy Modes.

Step 2: Using the Deployment Credentials the Background Service attempts to copy Silverlight_x64-5.1.50901.0.exe to the following paths:

\\Guinness.deadwood.local\ADMIN$\AdminArsenal\PDQDeployRunner\service-n\exec\
\\Heineken.deadwood.local\ADMIN$\AdminArsenal\PDQDeployRunner\service-n\exec\
\\Lopan.deadwood.local\ADMIN$\AdminArsenal\PDQDeployRunner\service-n\exec\

IMPORTANT: Some antivirus applications may prevent copying into the ADMIN$ share. You may need to exclude these directories from the antivirus real-time scanning as detailed in the article Recommended Antivirus/Antimalware Exclusions for PDQ Products.

Step 3: A Windows Service is created on each target and is called PDQDeployRunner-n (-n will usually be "1"). As explained above, this is referred to as the "Runner" service. The Runner service is set to run under the Deployment Credentials. For this example, we've used deadwood.local\DeployUser (see image below).

NOTE:
There are options available when deploying a package to have each step Run As either Deploy User (use package settings), Deploy User, Deploy User (Interactive), Local System or Logged On User. We recommend using Deploy User (use package settings) or Deploy User but there may be times to change this behavior. If a step's Run As option is set to Local System, the Runner service is created using the Deployment Credentials (deadwood.local\DeployUser) but the service runs as Local System (or whatever Run As option was selected).

Step 4: The Runner service is created and performs an evaluation on the Conditions for the step. If the Conditions are met, the Runner service begins to run the first Step in the package. If any Conditions are not met, the step is skipped and the process (evaluation) is replicated on the second step. Conditions are evaluated as Local System, which can cause curious results if a file condition exists to look for something within a user profile using a variable like %userprofile% even if the step is set to run as "Logged on user".

In this example a 64-bit OS would not pass the first step’s Conditions but it would pass the second step’s.

NOTE:
An evaluation of step conditions is performed on each package step, since there are cases where the conditions might change from one step to a later step (e.g. updated PowerShell version, logged on state, a file or registry condition).

Step 5: In the case of our Silverlight install, when a Step runs and meets all conditions, it executes the files or commands from %WINDIR%\AdminArsenal\PDQDeployRunner\service-1\exec\Silverlight_x64-5.1.50901.0.exe on the target computer and passes the /q parameter (the /q in the Install Step’s Parameters field).

NOTE:
While MSI (and friends) have relatively standard silent parameters that are included in those Install steps, executable (*.exe) installers can vary widely. Please see this video, Finding Silent Parameters for Your Deployments (Using Google Fu), on how to find silent parameters/command line switches for your executable installer. For more information, see Considerations below.

Step 6: The Runner service waits for Silverlight installation to finish. A return code (also known as an Error Code or Exit Code) is sent from the Silverlight exe file and is returned to the Runner service on the target computer.

Step 7: At regular intervals, The PDQ console computer’s PDQDeploy service has been polling the Runner service on each target. When it detects the installation is complete (based on the return code) it returns the information to the PDQ Deploy database.

Step 8: The PDQ Deploy Console detects the change in Deployment status in the database and displays the deploy status (Success, Fail) based on the Success Return Codes specified in the Installer.

Step 9: Cleanup occurs, and the previously created directory, copied files, and runner service on the target machine are deleted.

Considerations:

Install Step files with .MSI, .MSU or .MSP extensions are automatically passed the parameters needed to run silently. As explained above, If your installer file has another extension (such as .exe), you will likely need to include parameters/command line arguments in the Install Step, Parameters (Details tab). The parameters to run silently depend on the application being installed and are determined by the vendor of the application.

IMPORTANT: If the PDQ package requires a silent parameter for the installer file and no silent parameter is provided, your deployment will likely hang or result in an error.

When an application is installed from PDQ Deploy, windows that are normally shown when an application is installed (such as accepting a EULA or choosing an installation path) cannot be viewed. If the Installation is expecting user input, nothing can provide that input since all installation windows are hidden.
A return code is defined by the Vendor of the application your are deploying or the OS. In the Silverlight example, the return codes are provided by Microsoft. Return codes help determine the installation state. In many cases, the standard return code for a Success is 0. Other non-zero Success codes are 3010 and 1641. If any code is returned that is NOT specified in the Success Codes field (Details tab), the installation will be marked as a failure.

The vast majority of error codes deal with problems outside of PDQ Deploy and deal with the specifics of the application being deployed.

Microsoft has a list of Return Codes returned by the Windows Installer. You can find other Microsoft Return Codes here.

Purpose

Resolution

See Also

Related articles