Skip to main content

Deploy the Praxis collector with Group Policy

Install praxis-collector across many domain-joined Windows servers at once, using Active Directory Group Policy. Each server installs itself during normal policy refresh — no reboot, and no per-server remote session.

For a single host, run the command from Windows: Praxis collector directly instead. This page is for fleet deployment.

Before you begin​

  • Active Directory — a working domain, with the target servers already domain-joined.
  • An Organizational Unit containing the target servers' computer objects. Group Policy is linked to the OU, so servers outside it are not deployed to.
  • A file server to host a deployment share. A domain controller is acceptable.
  • Privileges — Domain Admin, or delegated rights to create and link a GPO plus create the share.
  • The installation command from the Praxis console. It is self-contained and is retrieved in step 2.
  • Supported OS — as per Windows: Praxis collector. Windows Server 2008 R2 additionally needs SP1 and the three updates listed there before any deployment.
note

Group Policy's Software Installation policy cannot deploy the collector. It passes no MSI properties, so the package would install with no OpAMP URL or credentials, and it applies only at startup. A Preferences scheduled task applies during ordinary policy refresh and runs any command, which is why it is used here.

Values used below​

PlaceholderMeaningExample
<NETBIOS>Domain NetBIOS nameCONTOSO
<FILESERVER-FQDN>Fully qualified name of the share hostfs01.contoso.com
<OU-DN>Distinguished name of the OU holding the target serversOU=Servers,DC=contoso,DC=com

1. Create the deployment share​

Run on the share host, from an elevated PowerShell:

New-Item -Path C:\PraxisDeploy -ItemType Directory

New-SmbShare -Name 'PraxisDeploy$' -Path C:\PraxisDeploy `
  -ReadAccess '<NETBIOS>\Domain Computers','<NETBIOS>\Domain Controllers' `
  -FullAccess '<NETBIOS>\Domain Admins'

icacls C:\PraxisDeploy /grant "<NETBIOS>\Domain Computers:(RX)" /grant "<NETBIOS>\Domain Controllers:(RX)"
caution

Permissions must be granted to computer groups. The task runs as SYSTEM, which authenticates to the network as the machine account (for example SERVER01$) — not as a user. Granting a user group instead causes the script to fail to load, with no useful error.

Both Domain Computers and Domain Controllers are included because promoting a server to a domain controller moves its computer account into the latter. Omit Domain Controllers if no DC is a deployment target.

Share and NTFS permissions are evaluated separately, and network access is the more restrictive of the two — the commands above set both.

Verify:

Get-SmbShareAccess -Name 'PraxisDeploy$'
Test-Path \\<FILESERVER-FQDN>\PraxisDeploy$

Three Allow entries, and True over the UNC path.

2. Create the install script​

Praxis generates the whole command for you. In the console:

  1. Open the pipeline these servers will report to.
  2. Select the Add collector button.
  3. Open the PowerShell script tab.
  4. The tab lists two commands. Copy the installation one.

The command is self-contained — it already carries the OpAMP URL, key, secret, org, tenant, and pipeline id. Nothing needs to be gathered or entered separately.

caution

The command contains a client secret in clear text. Keep it on the restricted share created in step 1. Do not place it in SYSVOL, and do not paste it into the scheduled task's Arguments field — Group Policy stores both in SYSVOL, which is readable by every authenticated domain user.

Paste it — exactly as the console presents it, with no other changes — into:

C:\PraxisDeploy\Install-PraxisCollector.ps1

That is the entire file. If the command spans several statements separated by semicolons or line-continuation backticks, keep it as-is; reformatting risks breaking it.

Verify before wiring it up:

$errors = $null
[void][System.Management.Automation.Language.Parser]::ParseFile(
  'C:\PraxisDeploy\Install-PraxisCollector.ps1', [ref]$null, [ref]$errors)
$errors

Select-String -Path C:\PraxisDeploy\Install-PraxisCollector.ps1 -Pattern 'windows_install|PRX_|OPAMPURL|msiexec'

The first returns nothing (the file parses — this catches a truncated paste). The second must return at least one match, confirming the file holds the command.

note

For proxied environments, add the proxy lines and -HttpsProxy / -NoProxy parameters described in Install behind a corporate proxy to this same file.

On a domain controller, open Server Manager → Tools → Group Policy Management, then:

  1. Expand Forest → Domains → your domain and find the OU holding the target servers.
  2. Right-click that OU → Create a GPO in this domain, and Link it here…
  3. Name it Deploy Praxis Collector → OK.

To include domain controllers, link the same GPO to the Domain Controllers OU as well. Do not move a DC's computer object out of that OU.

Verify:

Get-GPO -Name "Deploy Praxis Collector" | Select-Object DisplayName, Id, GpoStatus
Get-GPInheritance -Target "<OU-DN>" | Select-Object -ExpandProperty GpoLinks

4. Add the deployment task​

Right-click the GPO → Edit, then navigate to:

Computer Configuration → Preferences → Control Panel Settings → Scheduled Tasks

Right-click in the right pane → New → Immediate Task (At least Windows 7).

TabConfiguration
GeneralName Install Praxis Collector. Select Change User or Group… and enter SYSTEM. Select Run whether user is logged on or not. Enable Run with highest privileges.
ActionsNew… → Start a program. Program/script: powershell.exe. Arguments: -ExecutionPolicy Bypass -NoProfile -File "\\<FILESERVER-FQDN>\PraxisDeploy$\Install-PraxisCollector.ps1"
CommonEnable Apply once and do not reapply.

Close the editor to save.

caution

Use the file server's FQDN in the UNC path. An IP-address path prevents Kerberos authentication, which the machine account depends on.

5. Apply the policy​

Group Policy applies on its own. Member servers check for changes every 90 minutes, plus a randomized offset of up to 30 minutes, and again at startup (Group Policy refresh). No action is required if you are content to wait; each server installs the collector at its next refresh.

To apply immediately on a particular server, run on that server:

gpupdate /force

Allow two to three minutes for the download and installation.

6. Verify​

Check in order on a target server — each isolates a different stage, so the first failure tells you where to look.

#CheckExpected
1gpresult /r /scope:computerDeploy Praxis Collector under Applied Group Policy Objects
2Get-Content C:\Windows\Temp\praxis-collector-install.logInstaller log present, no errors
3Get-Service praxis-collectorStatus Running
4Get-CimInstance Win32_Service -Filter "Name='praxis-collector'" | Select StartName.\praxiscollector on member servers; LocalSystem on a domain controller
5Praxis consoleThe server appears online with the correct pipeline attached
caution

Check 5 is the definitive one. A running service confirms only that the package installed. If a configuration value is wrong, the service starts normally and never authenticates — the collector's appearance in the console is the only proof of a successful deployment.

Credentials are redacted in praxis-collector-install.log, so it can be shared with Praxis support.

Coverage and limits​

An Immediate Task creates itself, runs once, and deletes itself — no permanent object is left on the server.

  • New servers are covered. Apply once and do not reapply is recorded per server, so a server joining the OU later performs its own single installation at its first refresh.
  • There is no automatic retry. The setting records that the item was processed, not that the installation succeeded. A server whose single attempt fails is not retried, and a collector removed later is not reinstated. Confirm coverage after each rollout.

Troubleshooting​

A failure that occurs before the package installation begins — an unreadable share, no outbound access — leaves no log on the server, because the installer has not started yet. The quickest way to see the cause is to run the same command by hand on the affected server, where errors print to the console:

powershell -ExecutionPolicy Bypass -NoProfile -File "\\<FILESERVER-FQDN>\PraxisDeploy$\Install-PraxisCollector.ps1"
SymptomLikely causeResolution
GPO missing from Applied Group Policy ObjectsLink disabled, security filtering, or the computer object is outside the linked OUgpresult /h C:\gpo.html /f and review the report. Restart servers that were moved between OUs.
GPO applied, collector installed, nothing happens on later refreshesApply once and do not reapply is already recorded for this serverExpected. See Reinstall on a server below.
GPO applied, no collector, no praxis-collector-install.logThe task did not run, or the script could not be readRun the command manually as above to see the error. Also review the Application event log for Group Policy entries and Microsoft-Windows-GroupPolicy/Operational.
Manual run reports the file cannot be foundThe computer account cannot read the shareRe-check the share and NTFS permissions in step 1, and confirm the UNC path uses the FQDN.

Anything that goes wrong after the installer starts — download errors, package failures, or a collector that runs but never registers — is not specific to Group Policy. See Windows: Praxis collector for those.

Removal and reinstallation​

Remove from a single server​

In the console, open the pipeline, select Add collector, and open the PowerShell script tab — the same tab used in step 2. Copy the second command, the uninstallation one.

Run it from an elevated PowerShell on the server you are removing the collector from — not on a domain controller, unless the domain controller is itself the target.

It removes the service, the install and data directories, the dedicated local account, the update task, and the Add/Remove Programs registration. Confirm on that same server:

Get-Service praxis-collector -ErrorAction SilentlyContinue
Test-Path 'C:\Program Files\Netenrich\PraxisCollector'
Test-Path 'C:\ProgramData\PraxisCollector'

Remove the corresponding entry from the Praxis console too, so a later installation registers cleanly.

Remove from many servers​

Deploy the uninstallation the same way the installation was deployed:

  1. Save the uninstallation command to a second file on the share, for example Uninstall-PraxisCollector.ps1.
  2. Unlink the installation GPO from the OU first — see Stop further deployment below. Leaving it linked means the two tasks work against each other.
  3. Create a new GPO linked to the same OU, with an Immediate Task configured exactly as in step 4 but pointing at the uninstallation script.
  4. Apply it, then confirm removal on the target servers using the checks above.

Remove the collectors' entries from the Praxis console once the servers report as offline.

Stop further deployment​

An Immediate Task deletes itself after running, so nothing remains on servers already processed. To stop servers that have not yet been processed, clear Link Enabled on the GPO's link beneath the OU.

Deleting a link does not delete the GPO; deleting the GPO from the Group Policy Objects container removes it permanently. Neither removes collectors already installed.

Reinstall on a server​

Remove the collector as above and delete C:\Windows\Temp\praxis-collector-install.log. The server is already recorded as processed, so the task will not run again on its own.

The simplest fix for a single server is to run the command directly on it:

powershell -ExecutionPolicy Bypass -NoProfile -File "\\<FILESERVER-FQDN>\PraxisDeploy$\Install-PraxisCollector.ps1"
caution

The alternative — clearing Apply once and do not reapply on the task item — affects every server the GPO applies to, reinstalling over working collectors at each refresh. Deleting and recreating the task item has the same fleet-wide effect. Use either only for a deliberate fleet-wide reinstallation.