> For the complete documentation index, see [llms.txt](https://docs.we360.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.we360.ai/deployment-and-it-ops/deploy/agent-deployment-hub/mass-deployment/active-directory-gpo.md).
# Active Directory GPO
Deploy MyZen to domain-joined Windows computers with Group Policy, and troubleshoot package import and installation failures.
Use this guide to deploy MyZen to domain-joined Windows computers through Active Directory Group Policy. Start with a small pilot before deploying to more computers.
**Quick choice:** For a one-time EXE rollout without waiting for computer startup, use a [Group Policy Preferences Immediate Task](#alternative-deployment-through-a-group-policy-preferences-task) with apply-once enabled; use MSI assignment when your deployment requires it, or a startup script when installation must run at boot. A task doesn't guarantee immediate delivery or eliminate an installer-required restart.
## Choose a deployment method
| Method | Package | When to choose it | Installation starts |
| ------------------------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------------------------- | ------------------------------------------- |
| [Computer-assigned Software Installation](#step-1-prepare-the-distribution-share) | MSI | You want native MSI assignment | Computer startup |
| [Group Policy Preferences task](#alternative-deployment-through-a-group-policy-preferences-task) | EXE or reviewed PowerShell script | You want execution at policy refresh or an approved time | Preference processing or the task's trigger |
| [Startup script](#alternative-deployment-through-a-startup-script) | Reviewed EXE deployment script | You want scripted installation at boot | Computer startup |
An executable (EXE) can't be assigned through **Software installation**. Tasks and startup scripts are separate deployment methods, not fixes for an invalid MSI. Never rename an EXE to `.msi`.
Use Steps 1–4 for MSI assignment. For EXE deployment, use one of the alternative sections. Use only one installation method for each target computer: don't overlap MSI assignments, EXE tasks, and startup installers, even when they come from different Group Policy objects linked to the same OU.
Before switching methods, review the computer's applied policies and retire the previous deployment configuration in a controlled pilot. Removing an MSI assignment can either uninstall the software or leave it installed while preventing new installations; review that choice before changing it. Verify the installed version and check for unintended reinstall or uninstall after another policy refresh and restart. See Microsoft's [package-removal guidance](https://learn.microsoft.com/en-us/troubleshoot/windows-server/group-policy/use-group-policy-to-install-software#remove-a-package).
## Before you start
You need:
* Windows computers joined to your Active Directory domain.
* **Group Policy Management Console (GPMC)** on Windows Server or a workstation with Remote Server Administration Tools (RSAT), and permission to create, edit, and link a Group Policy object (GPO).
* An organizational unit (OU) containing the target **computer accounts**, with a pilot OU or computer security group to limit the rollout.
* The correct MSI or EXE for the intended Standard or Stealth deployment. For Stealth, use your organization's installer filename. Follow [Verify Downloaded Installers](/deployment-and-it-ops/deploy/agent-deployment-hub/verify-downloads.md) before distributing it.
* Access to the installation source in the computer's **SYSTEM** context. Share-based deployment needs both share and NTFS permissions for the target computer accounts, as described in Step 1. Downloading through a script also needs access to the download URL without a signed-in user's credentials.
For MSI assignment and startup scripts, the source must be reachable during startup. A virtual private network (VPN) that connects only after user sign-in may not provide that access. A task can run later, when its source is reachable; it doesn't require an MSI share if its reviewed script downloads the EXE.
Before a boot-time deployment that depends on domain network access, have your administrator enable **Always wait for the network at computer startup and logon** in the pilot GPO under **Computer Configuration > Policies > Administrative Templates > System > Logon**, and verify it has applied before testing the deployment startup. This requests synchronous foreground policy processing and can delay startup and sign-in; it doesn't guarantee that the installer share or download URL is reachable, or fix a missing pre-sign-in VPN, authentication failure, or incorrect permissions. See Microsoft's [network-wait guidance](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/policy/logon-optimization).
Test source access as SYSTEM during an actual pilot startup, not only after sign-in. If the source is available only later, choose a task scheduled for an approved time when connectivity is available.
The current Standard and Stealth MSI downloads are **x64 (64-bit)** packages and don't install on 32-bit Windows. Confirm the package and endpoint architecture before rollout. The **Make this 32-bit X86 application available to Win64 machines** option under **Deployment > Advanced** applies only to 32-bit packages, not these x64 installers. See Microsoft's [MSI platform compatibility reference](https://learn.microsoft.com/en-us/windows/win32/msi/template-summary).
{% hint style="danger" %}
**Preserve the organization-specific Stealth installer filename.** Its name is tied to your organization's license. Don't give a portal download or prepared installer a different name, and don't allow duplicate-download suffixes such as `(1)` or `(2)`. A generic public download must first receive your organization's filename or configuration through [Stealth installer preparation](https://github.com/zenstack-we360/documentation/tree/main/docs-we360-ai/it-ops/deployment/agent-deployment-hub/download-links.md#important-notes-for-stealth-installer-downloads).
{% endhint %}
## Step 1: Prepare the distribution share
1. Create a dedicated deployment folder on a file server, rather than using a personal or temporary folder.
2. Share the folder and copy the MSI into it, keeping its original filename.
3. Grant the target computer security group access at **both** permission layers:
| Permission layer | Where to configure it | Target computers need |
| ---------------- | --------------------------------------------------------- | ---------------------------------------------------------- |
| Share | **Properties > Sharing > Advanced Sharing > Permissions** | **Read** |
| NTFS | **Properties > Security** | **Read & execute**, including access to the folder and MSI |
Keep write access limited to administrators who manage the installers. `Domain Computers` can be used if all domain computers should have read access; use a narrower computer security group for a limited deployment. Replacing a broad share grant such as `Everyone` isn't enough unless the resulting share and NTFS permissions allow the intended access.
Computer-context installation accesses a domain share using the computer account, such as `DOMAIN\PC123$`, not the signed-in administrator. Opening the share as an administrator doesn't prove the computer can read it. See Microsoft's [LocalSystem account documentation](https://learn.microsoft.com/en-us/windows/win32/ad/the-localsystem-account).
After adding a computer to the deployment security group, allow time for Active Directory replication and restart that computer before testing share access. The restart refreshes the computer's group membership and Kerberos tickets. Running `gpupdate` alone doesn't refresh this membership.
Administrator alternative: refresh computer Kerberos tickets without restarting
After replication, an administrator can refresh the LocalSystem Kerberos ticket cache on the pilot computer from an elevated Command Prompt:
```cmd
klist -li 0x3e7 purge
gpupdate /target:computer /force
```
This purges the computer-context tickets, not the signed-in user's tickets. Subsequent Kerberos authentication obtains new tickets that can reflect the changed domain security-group membership. It doesn't refresh every existing access token or network session, and it doesn't replace the startup required for computer-assigned MSI installation. Recheck computer-context share access and GPO filtering; restart if the new membership still isn't effective.
Purging tickets can disrupt computer-context access to network resources. Use this only during an approved pilot window with a domain controller reachable and appropriate administrative rights. Restarting remains the simpler default. See Microsoft's [`klist` reference](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/klist).
Use a stable Universal Naming Convention (UNC) path with the file server's Domain Name System (DNS) name, preferably its fully qualified domain name (FQDN):
```
\\fileserver.example.com\SoftwareDeploy\.msi
```
Don't use a local path such as `C:\Software\...` or a mapped drive such as `Z:\...`. Keep the source available after installation for maintenance operations.
{% hint style="info" %}
Prefer a DNS name over an IP address. By default, Windows doesn't attempt domain-ticket authentication for an IP-address hostname and can fall back to NTLM. Access can then fail where NTLM is blocked. An FQDN alone doesn't guarantee successful authentication, and requiring SMB signing doesn't mean all NTLM connections are blocked. Have your domain administrator investigate authentication failures rather than disabling security protections. See [IP-address authentication guidance](https://learn.microsoft.com/en-us/windows-server/security/kerberos/configuring-kerberos-over-ip), [SMB signing](https://learn.microsoft.com/en-us/windows-server/storage/file-server/smb-signing), and [SMB NTLM blocking](https://learn.microsoft.com/en-us/windows-server/storage/file-server/smb-ntlm-blocking).
{% endhint %}
## Step 2: Create and scope the policy
Choose the instructions that match your administration console, rather than the age of the domain alone. Use GPMC when available. If your console still exposes the older **Group Policy** tab, use the legacy navigation below.
1. Open **Group Policy Management Console** (`gpmc.msc`).
2. Find the OU containing the target computer accounts.
3. Right-click the OU and select **Create a GPO in this domain, and Link it here**.
4. Name the GPO, for example `MyZen - Pilot`.
5. Confirm the link is enabled and the **Computer Configuration** settings on the GPO are enabled.
6. If using a pilot computer security group, configure **Scope > Security Filtering** so that group has **Read** and **Apply Group Policy**. Remove **Apply Group Policy** from broader groups if it would expand the intended scope; preserve required read access.
GPO permissions determine which computers receive the policy. They don't grant access to the MSI share. For details, see Microsoft's [GPMC guide](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/group-policy/group-policy-management-console) and [Group Policy scope](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/group-policy/group-policy-scope).
If you just added a pilot computer to the security-filtering group, allow time for replication and restart it before testing policy application, or use the [administrator Kerberos alternative in Step 1](#step-1-prepare-the-distribution-share). Until its computer group membership refreshes, it may appear filtered out even when the GPO permissions are correct.
Legacy console: Active Directory Users and Computers
Use this route only if **Properties > Group Policy** is available in your console. If that tab is absent, use the GPMC instructions instead.
1. Open **Active Directory Users and Computers**.
2. Right-click the target **OU containing the pilot computer accounts** and select **Properties**. Avoid creating a domain-wide deployment just to follow an older example.
3. Select **Group Policy > New**, name the policy, and press **Enter**.
4. Select the policy in **Group Policy Object Links**. Open its **Properties > Security** and confirm the intended computer group has **Read** and **Apply Group Policy**, using the same scope restrictions described above.
5. Select the policy and click **Edit**, then continue with **Step 3, item 2** in the editor.
Microsoft documents this OU-based navigation in its [Windows Server 2003 console instructions](https://learn.microsoft.com/en-us/troubleshoot/windows-server/group-policy/configure-group-policies-set-security). These navigation instructions don't extend the agent's supported Windows endpoint versions. Confirm endpoint and installer compatibility before rollout.
## Step 3: Assign the installer package
1. Right-click the GPO and select **Edit**.
2. Go to **Computer Configuration > Policies > Software Settings > Software installation**.
* In an older editor without a **Policies** node, use **Computer Configuration > Software Settings > Software installation**.
3. Right-click **Software installation** and select **New > Package**.
4. Enter the **full UNC path**, including the original MSI filename. Don't browse to a local copy or use a mapped drive.
5. Click **Open**, select **Assigned**, and click **OK**.
6. Confirm the package appears in the list with the intended source path.
**Published** is a user-deployment option, not an alternative for computer assignment. This applies to both console routes. See Microsoft's [Group Policy software installation guide](https://learn.microsoft.com/en-us/troubleshoot/windows-server/group-policy/use-group-policy-to-install-software).
If GPMC can't add the package, resolve the [package-import error](#cant-add-the-package-in-group-policy-management) before troubleshooting a target computer.
{% hint style="warning" %}
If an existing assignment points to an old share or IP address, moving the MSI doesn't update its stored source path. Have your domain administrator follow Microsoft's [MSI source-location migration guidance](https://learn.microsoft.com/en-us/troubleshoot/windows-server/group-policy/change-msi-file-location-in-software-deployment-gpo). Review reinstall and uninstall consequences before removing, replacing, or redeploying a package.
{% endhint %}
## Step 4: Refresh, restart, and verify
On a pilot computer, open **Command Prompt as administrator** and run:
```cmd
gpupdate /target:computer /force
```
After `gpupdate` finishes, save the user's work and restart the pilot computer manually. Alternatively, during an approved deployment window, save their work and use this **single command instead of the command above**:
```cmd
gpupdate /target:computer /force /boot
```
`/boot` restarts the computer after policy processing if a policy extension requires a restart, including computer-targeted Software Installation. It has no effect if none of the processed extensions requires a restart.
Computer-assigned software installation is processed at startup, not during an ordinary background refresh. The default background refresh interval is 90 minutes plus a random offset of up to 30 minutes, not an installation deadline. Network readiness, policy replication, and synchronous processing can require another startup cycle. See [Group Policy processing](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/group-policy/group-policy-processing) and [`gpupdate`](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/gpupdate).
After restarting:
1. Confirm the GPO appears in the computer's applied policies:
```cmd
gpresult /scope computer /r
```
2. Confirm the expected MyZen version is installed. For Stealth deployments, also check the background service using [Windows Installation Validation](/deployment-and-it-ops/deploy/agent-deployment-hub/manual-installation/windows-validation.md).
3. After the intended user signs in, verify the agent is running for that user and check its reporting in the portal.
4. Test another restart before expanding the rollout, checking for failures or unintended repeated installation.
An applied GPO isn't proof of successful installation. Installation and service startup are also separate from user-session tracking. Don't rely on a particular startup progress message or assume that choosing EXE instead of MSI guarantees immediate tracking.
## Alternative deployment through a Group Policy Preferences task
Group Policy Preferences (GPP) can distribute a task to the computers in your pilot GPO. You don't need to create the task manually on every computer. An **Immediate Task** runs when the preference item is processed; a **Scheduled Task** runs on its configured trigger. Neither requires a computer startup just to launch the action, but the installer can still require a restart.
### Prepare the EXE or script
1. Obtain the correct Standard or organization-specific Stealth EXE. If you use a generic Stealth download, complete [Stealth installer preparation](/deployment-and-it-ops/deploy/agent-deployment-hub/download-links.md#important-notes-for-stealth-installer-downloads) first.
2. Place the verified EXE or administrator-reviewed script in a deployment folder that target computer accounts can read. Restrict write access to deployment administrators: this code will run as SYSTEM. Use a DNS-based UNC path, not a mapped drive.
3. For a script that downloads the installer, verify connectivity in the SYSTEM context. Your interactive browser's access doesn't prove that the task can download it.
4. Pilot the [silent-install command](/deployment-and-it-ops/deploy/agent-deployment-hub/mass-deployment/command-line-msi.md#silent-install), installer architecture, result codes, and required restarts on a supported Windows computer. Don't assume the EXE has the same architecture or return codes as an MSI.
For the supplied Stealth helper, follow [PowerShell helper configuration](/deployment-and-it-ops/deploy/agent-deployment-hub/download-links.md#powershell-stealth-install-helper). Save and review a local copy before deploying it; don't execute a remote gist directly from the task.
### Create and scope the task
1. Create and scope a pilot GPO as described in [Step 2](#step-2-create-and-scope-the-policy), including the computer-group restart guidance.
2. Edit the GPO and go to **Computer Configuration > Preferences > Control Panel Settings > Scheduled Tasks**.
3. Right-click **Scheduled Tasks > New** and choose:
* **Immediate Task (At least Windows 7)** to run when the preference is processed.
* **Scheduled Task (At least Windows 7)** to run during an approved deployment window.
4. Give the task a functional name, such as `Endpoint agent deployment`. Don't put an organization key or license-bearing installer filename in the task name or description.
5. On **General**, select **NT AUTHORITY\SYSTEM** and **Run with highest privileges**. The task must run without a user signed in. Don't store administrator credentials in the GPO.
6. On **Actions**, select **Start a program** and configure one of these actions:
| Field | Direct EXE installation | Reviewed PowerShell script |
| ------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Program/script** | `\\fileserver.example.com\SoftwareDeploy\.exe` | `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe` |
| **Add arguments** | `--silent` | `-NoProfile -NonInteractive -File "\\fileserver.example.com\SoftwareDeploy\Deploy-Agent.ps1"` |
| **Start in** | Leave blank when using the full path | Leave blank when the script uses full paths |
Replace the example paths with your administrator-controlled sources. The script action uses Windows PowerShell 5.1 for the supplied helper; don't assume that helper works in PowerShell 7. For installer evidence, use the [logging instructions](/deployment-and-it-ops/deploy/agent-deployment-hub/mass-deployment/command-line-msi.md#install-with-logging-for-troubleshooting) and an existing administrator-controlled log folder when running as SYSTEM.
### PowerShell execution policy
Before rollout, check the **effective execution policy on a pilot client in the task's SYSTEM context**, not only on the server or in your interactive session. `Get-ExecutionPolicy` shows the effective policy; `Get-ExecutionPolicy -List` shows the scopes that determine it. Windows clients default to **Restricted**, which blocks the `-File` action. Domain-enforced **MachinePolicy** and **UserPolicy** take precedence over **Process**, **CurrentUser**, and **LocalMachine** settings.
Creating a GPP task doesn't itself change that precedence: a local `Set-ExecutionPolicy` change or a command-line `-ExecutionPolicy` option can't override an enforced policy. Have your domain administrator review **Turn on Script Execution** under **Administrative Templates > Windows Components > Windows PowerShell** rather than weakening the client policy.
Under **RemoteSigned**, an unsigned script on an FQDN-based UNC path can still be blocked: Windows can classify a dotted hostname as the Internet zone unless the host is assigned to the Local Intranet zone. Keep the DNS-based source path, but have your administrator ensure the reviewed script is appropriately signed and trusted, or that the effective policy and zone assignment permit that exact source. Test non-interactive execution from that path on the pilot client as SYSTEM before distributing the task. Don't add a blanket execution-policy bypass. See Microsoft's [execution-policy guidance](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-5.1) and [FQDN security-zone guidance](https://learn.microsoft.com/en-us/troubleshoot/windows-client/networking/intranet-site-identified-as-an-internet-site).
### Control execution and repeat runs
For a one-time **Immediate Task**, on **Common**, select `Apply once and do not reapply`. The temporary task is removed after it runs. **Without apply-once, the installer can run at every background policy refresh—normally every 90–120 minutes—as well as at other preference-processing events.** Removing the temporary task doesn't prevent the preference from creating it again. Apply-once records preference application, not verified installation success; a failed or condition-blocked installation may need a new, narrowly scoped preference item rather than another policy refresh.
For either task type, check **Conditions > Start the task only if the computer is on AC power**. This default condition prevents a battery-powered laptop from starting the task. Connect the pilot to AC power, or clear the condition only if battery-powered installation is approved. Also review **Stop if the computer switches to battery power** so an approved run isn't interrupted. Test the intended power conditions before rollout; see Microsoft's [task power-condition reference](https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-disallowstartifonbatteries-settingstype-element).
For a **Scheduled Task**:
* Set **Action** to **Update**, not **Replace**, so policy refresh doesn't repeatedly delete and recreate it.
* Configure a one-time trigger during the approved window. On **Settings**, select **Run task as soon as possible after a scheduled start is missed** if late execution is acceptable.
* Select `Do not start a new instance` if the task is already running. Review network conditions as well as the power conditions above.
* Don't enable a recurring trigger until the reviewed script safely skips the intended installation when it's already present. The supplied helper isn't suitable unchanged for recurring execution.
If an installation fails, investigate before rerunning it. For an apply-once Immediate Task, use a new preference item scoped only to the failed computers; another `gpupdate /force` doesn't override apply-once. For a persistent task, correct the problem and rerun it during an approved window.
After the rollout, explicitly remove the preference item and, for persistent tasks, deploy a **Delete** preference item for the same task name to the target computers. Verify removal before retiring that cleanup item. Removing the GPO link alone doesn't guarantee task removal, and deleting a task doesn't uninstall the agent.
Don't select `Remove this item when it is no longer applied` for the deployment task: it forces the preference action to **Replace**, which deletes and recreates the task during policy application. Explicit **Delete** cleanup lets the deployment task retain **Update** while it remains in scope.
### Refresh and verify
On a pilot computer, run the following from an elevated Command Prompt:
```cmd
gpupdate /target:computer /force
```
Don't add `/sync` or `/boot` merely to start this task route. Confirm the task's action and result, then verify the installed version, background service, and reporting for the intended signed-in user with [Windows Installation Validation](/deployment-and-it-ops/deploy/agent-deployment-hub/manual-installation/windows-validation.md).
Test another policy refresh and restart to check for unintended repeat installation. Confirm that a computer outside the pilot scope receives no deployment task before expanding the rollout.
Microsoft's [current Group Policy onboarding example](https://learn.microsoft.com/en-us/defender-endpoint/configure-endpoints-gp#onboard-devices-by-using-group-policy) uses **Immediate Task (At least Windows 7)**. Older consoles may show **Immediate Task (Windows Vista and later)** and **Scheduled Task (Windows Vista and later)** instead. These operating-system names are console labels, not a statement that the agent supports those endpoint versions. See also Microsoft's archived [GPP scheduled and immediate tasks](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-r2-and-2012/dn789200%28v%3Dws.11%29#scheduled-tasks-extension) and [preference common options](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc772371%28v%3Dws.11%29).
## Troubleshooting
### Can't add the package in Group Policy Management
**Message:** "Add operation failed. Unable to extract deployment information from the package. Run validation on the package to ensure that the package is correct."
This is a **package-import failure in GPMC**, before a target computer attempts installation. It doesn't by itself identify an NTLM, boot-timing, or target-computer permissions problem.
1. Confirm you selected the actual MSI and verify the download's signature and checksum using [Verify Downloaded Installers](/deployment-and-it-ops/deploy/agent-deployment-hub/verify-downloads.md).
2. Confirm the machine and account running GPMC can read the exact UNC source. This is separate from the target computer's startup access.
3. Have your administrator validate a **copy** of the MSI with Microsoft's Windows SDK tools, [Orca](https://learn.microsoft.com/en-us/windows/win32/msi/orca-exe) or [Msival2](https://learn.microsoft.com/en-us/windows/win32/msi/msival2-exe). Retain the validation results; don't edit or repackage the distributed installer to suppress errors.
4. If necessary, compare with a known-good MSI from the same share in an **unlinked test GPO**. Don't link the test GPO to production computers.
5. If the package still can't be added, contact support with the installer version, checksum, validation output, Windows version, and error details.
Microsoft documents [MSI package validation](https://learn.microsoft.com/en-us/windows/win32/msi/package-validation), but successful validation doesn't guarantee GPMC acceptance or endpoint installation. Running `msiexec /i` installs software; it's not a read-only validation command.
To check this error, download and review [msi-gpo-diagnose.ps1](https://portal.we360.ai/static/scripts/msi-gpo-diagnose.ps1). Run it from an elevated Windows PowerShell session under the same account you use for GPMC. If possible, run it on the file server that hosts the share:
```powershell
.\msi-gpo-diagnose.ps1 -MsiPath '\\server\share\installer.msi'
```
The diagnostic reads MSI summary information without running the installer. For comparison, it copies the MSI to a temporary local file and removes that copy when it exits. It doesn't install or repair the package. Treat the results as clues, not final diagnoses:
| Result | What it tells you | What to check next |
| -------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The UNC path can't be read | The account running the diagnostic can't read that path in this context. | Confirm the GPMC administrator's access to the path, since this check doesn't test the target computer's SYSTEM access. |
| UNC open fails but the local copy opens | Opening the MSI over the supplied path failed, but opening the local copy succeeded. | A successful local copy doesn't establish the cause or MSI validity, so ask an administrator to review the UNC path, SMB access, permissions, and security software. |
| Both opens fail | The diagnostic couldn't read MSI summary information from either location. | Because neither location yielded readable MSI summary information, ask an administrator to validate a copy with Orca or Msival2 rather than assuming the MSI is corrupt. |
| File is below 10 MB | The diagnostic flags the file as possibly truncated or a placeholder. | Compare its size and checksum with the official download. The 10 MB threshold is a heuristic and doesn't establish validity. |
| No signature or an unexpected signature status | PowerShell didn't report a signer as expected. | Check the official signature and checksum guidance because this result alone doesn't establish whether the MSI is trusted or altered. |
| Antivirus products or share permissions are listed | The diagnostic found product/service names or queried the share ACL. | Because antivirus presence doesn't prove a file lock and the reported share ACL doesn't show effective NTFS permissions, ask your administrator to investigate suspected file locks or access problems. |
The diagnostic output includes the computer name, account, MSI path, signer, antivirus product/service names, and share ACL entries. Redact organization names, usernames, server/share names, and tenant-specific filenames before sharing it. Send the results only through your approved private support channel.
### The policy is missing or filtered out
Run the following from an elevated Command Prompt:
```cmd
gpresult /scope computer /h "%TEMP%\MyZen-GPResult.html" /f
```
Open the report and check the computer's OU, GPO link, enabled computer settings, security filtering, and any WMI filter. Also check domain-controller connectivity and policy replication. A missing GPO doesn't prove that the computer is simply in the wrong OU. See [`gpresult`](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/gpresult).
### The computer can't read the installer
Verify the exact source path, DNS resolution, startup network access, and **both** share and NTFS permissions for the computer account. Don't substitute an administrator's successful share access for a computer-context check.
A folder name such as `Temporary` or a user's name isn't proof of an access failure. Check the actual permissions and authentication results.
### Installation is deferred with error 1274
Error **1274** means the Group Policy extension needs **synchronous foreground processing**. It's not a generic network error or proof of a corrupt MSI. See Microsoft's [system error definitions](https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--1000-1299-).
For a controlled pilot, configure the next computer startup to process policy synchronously:
```cmd
gpupdate /target:computer /sync
```
`/sync` doesn't apply policy immediately or restart the computer. Save the user's work and restart the computer so that the next startup processes policy synchronously and attempts package installation. `/force` and `/wait` are ignored if combined with `/sync`. See Microsoft's [`gpupdate` reference](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/gpupdate).
Review the [startup network prerequisites](#before-you-start) before the next pilot startup, including **Always wait for the network at computer startup and logon**. Synchronous policy processing doesn't fix an unreachable source or incorrect permissions.
### Windows Installer reports error 1603
Error **1603** means a fatal installation failure. It has multiple possible causes and doesn't prove the share permissions are wrong. See Microsoft's [1603 troubleshooting guidance](https://learn.microsoft.com/en-us/troubleshoot/windows-server/application-management/msi-installation-error-1603).
Use [Install with Logging](/deployment-and-it-ops/deploy/agent-deployment-hub/mass-deployment/command-line-msi.md#install-with-logging-for-troubleshooting) to investigate on an approved test computer. A manual installation changes that computer and doesn't prove the GPO installation context works.
For MSI results, **3010** means success with a restart required and **1641** means success with a restart initiated—not installation failure. These are [Windows Installer return codes](https://learn.microsoft.com/en-us/windows/win32/msi/error-codes); don't assume every EXE uses the same codes.
### A deployment task doesn't install the agent
Separate preference application, task execution, and installer success:
1. Check the computer's applied policies and security filtering with `gpresult`. Confirm the preference created the intended task.
2. In **Task Scheduler**, inspect the account, action, trigger, conditions, **Last Run Time**, and **Last Run Result**. If history is disabled, select **Enable All Tasks History** before reproducing the pilot failure. This enables **Applications and Services Logs > Microsoft > Windows > TaskScheduler > Operational** in Event Viewer; it isn't a separate logging switch. Use that log to inspect task execution. An Immediate Task can disappear after running, so its absence alone doesn't prove it never ran.
3. Check **Applications and Services Logs > Microsoft > Windows > GroupPolicy > Operational** separately for preference-processing errors.
4. Check the installer log and the exact EXE result code. A task that launched successfully isn't proof that installation or organization enrollment succeeded.
5. Test source access and download connectivity as SYSTEM. Check share and NTFS permissions, DNS, proxy requirements, and script-signing or execution-policy errors.
6. If the helper reports a nonzero result, retain the code and installer evidence. It treats every nonzero EXE code as failure; don't automatically reinterpret it using MSI return-code meanings.
### Collect evidence for support
Check **Event Viewer** around the failure time:
* **Windows Logs > System** for Group Policy and **Application Management Group Policy** messages.
* **Windows Logs > Application** for Windows Installer messages from **MsiInstaller**.
* **Applications and Services Logs > Microsoft > Windows > GroupPolicy > Operational** for policy-processing details.
For file-based evidence, distinguish policy processing from the deployment script and installer:
| Evidence | Where to look | Requirement |
| --------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Standard EXE installer | `%ProgramData%\zs-install\myzen-installer\logs` | Default timestamped installer logs, unless `--log-file` overrides the path |
| Stealth EXE installer | `%ProgramData%\zs-install\zs-installer\logs` | Default timestamped installer logs, unless `--log-file` overrides the path |
| Script output and result code | Your administrator-configured local file, for example `%ProgramData%\EndpointDeployment\deployment.log` | Configure the reviewed wrapper to record output and results in an administrator-controlled folder writable by SYSTEM; this file isn't created automatically |
| Group Policy service debug output | `%windir%\debug\usermode\gpsvc.log` | Available only after an administrator enables Group Policy service debug logging; it isn't the script's output or installer log |
If the default EXE log folder isn't writable, check the executing account's temporary folder. For a custom EXE log, use `--log-file`; for verbose MSI evidence, use `/l*v` during an approved pilot. Follow [Install with Logging](/deployment-and-it-ops/deploy/agent-deployment-hub/mass-deployment/command-line-msi.md#install-with-logging-for-troubleshooting) for the commands, and don't assume SYSTEM writes into your signed-in user's `%TEMP%`.
Use [Microsoft's Group Policy service debug-logging procedure](https://learn.microsoft.com/en-us/troubleshoot/windows-server/group-policy/applying-group-policy-troubleshooting-guidance#enable-group-policy-service-gpsvc-logging) only when the event logs aren't sufficient. It requires a registry change and an existing `%windir%\debug\usermode` folder. Back up the affected registry configuration, enable logging only for the approved diagnostic window, and restore the previous configuration afterward; verbose logging can consume disk space and reduce performance.
Record the full message, provider, event ID, error code, and timestamp. An event ID alone isn't a diagnosis. Include the computer-scope policy report and relevant installer or validation log. Remove organization keys, credentials, and sensitive installer filenames before sharing evidence. See Microsoft's [Group Policy troubleshooting guidance](https://learn.microsoft.com/en-us/troubleshoot/windows-server/group-policy/applying-group-policy-troubleshooting-guidance).
## Alternative deployment through a startup script
Use this separate route only when your administrator has chosen scripted deployment. Don't add an EXE under **Software installation** or rename it to `.msi`.
1. Obtain the correct EXE and complete [Stealth installer preparation](/deployment-and-it-ops/deploy/agent-deployment-hub/download-links.md#important-notes-for-stealth-installer-downloads) if using a generic Stealth download.
2. Use an administrator-reviewed deployment script and the appropriate [silent-install instructions](/deployment-and-it-ops/deploy/agent-deployment-hub/mass-deployment/command-line-msi.md#silent-install). For the supplied Stealth helper, follow [PowerShell helper configuration](/deployment-and-it-ops/deploy/agent-deployment-hub/download-links.md#powershell-stealth-install-helper).
3. Ensure the script can run non-interactively as **LocalSystem**, read its source files, and reach any required download URL without an interactive user's credentials. Verify the [startup network prerequisites](#before-you-start), and have your administrator check the [domain execution-policy and signing requirements](#powershell-execution-policy) on the pilot client in the SYSTEM context.
4. In the pilot GPO, go to **Computer Configuration > Policies > Windows Settings > Scripts (Startup/Shutdown) > Startup** and add the reviewed script using the **PowerShell Scripts** tab.
5. Verify installation and a second restart before wider deployment.
The [helper's repeat-run warning](/deployment-and-it-ops/deploy/agent-deployment-hub/download-links.md#powershell-stealth-install-helper) applies to startup scripts too. Every restart can run a startup script again; review installation detection and repeat-run behavior before rollout.
Microsoft's archived [Group Policy startup-script guide](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-r2-and-2012/dn789196%28v%3Dws.11%29) explains the startup-script location and LocalSystem execution context.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.we360.ai/deployment-and-it-ops/deploy/agent-deployment-hub/mass-deployment/active-directory-gpo.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.