How It Works: PDQ Deploy

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

Overview

First, we create/import a PDQ Deploy package for Notepad++. Opening the package and selecting an Install Step, the Install File location is $(Repository)/Notepad++/8.6.5/Notepad++_64bit_8.6.5.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.

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.
• 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.

Additional information:

• 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

Step 1: The PDQ Deploy Background Service attempts to retrieve the installer file, Notepad++_64bit_8.6.5.exe from $(Repository)/Notepad++/8.6.5/.

• 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 Notepad++_64bit_8.6.5.exe to the following path on a remote device:

\\TARGETMACHINE\ADMIN$\AdminArsenal\PDQDeployRunner\service-n\exec\

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.

• 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 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".

• 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 Notepad++ install, when a Step runs and meets all conditions, it executes the files or commands from %WINDIR%\AdminArsenal\PDQDeployRunner\service-1\exec\Notepad++_64bit_8.6.5.exe on the target computer and passes the /S parameter (the /S in the Install Step’s Parameters field).

• 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 Notepad++ installation to finish. A return code (also known as an Error Code or Exit Code) is sent from the Notepad++ 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.
  
  
   

  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 Notepad++ 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.