Install Level with Windows Active Directory Group Policy
This first section covers a script that will automatically set up a GPO to deploy Level to all workstations in an Active Directory Domain. If you would prefer to perform these steps manually see the section below: Manual Setup of Group Policy.
Video Walkthrough
The automatic GPO script, as well as the manual guide below, are provided as a convenience for Level customers. We cannot guarantee these will work in all Active Directory environments and we recommend that you test these before deploying to your production environment.
Creating the Level auto-deploy script
If your Level portal does not contain the Level installer GPO auto-deploy script then create the script with the following 4 steps. If you already have the script in your repository then skip to the next section.
Click on the Scripts link and choose the Scripts tab.
Chose to Create Script and name it Level installer GPO auto-deploy
Enter a description. It's recommended to paste the following description.
Paste your Level installer command at line 17
This script does the following:Checks that the target machine is a Windows Domain Controller
Creates a GPO backup file on the system drive at \temp\Level-Temp\.
A new GPO called "Install Level Agent" is created and linked at the root of the domain.
The contents of the GPO backup are imported into the new object. The backup contains a single script that will run on all domain-joined computers via an immediately scheduled task.
On a client computer, the task will check if Level is installed, and if not, the Level install command (at line 17) will be run.
This script should only be run on a single domain controller per Active Directory environment.
Paste the script below into the script area. Choose PowerShell as the language type and select Create Script.
# Check for Active Directory and halt if not present
$service = Get-Service -Name ntds -ErrorAction SilentlyContinue
if($null -eq $service)
{
Write-Error "This computer is not a domain controller. Please run this script on a domain controller."
exit
}
# Create the Level logon script in \SYSVOL\domain\scripts\Install_Level_Agent.ps1
$Net_Share_Path = $env:systemroot + '\SYSVOL\domain\scripts\Install_Level_Agent.ps1'
Set-Content $Net_Share_Path @'
# Check if the Level service is already present
$service = Get-Service -Name Level -ErrorAction SilentlyContinue
$levelExe = Test-Path "C:\Program Files\Level\level.exe" -ErrorAction SilentlyContinue
$hostname = hostname
# Check if the event log source "Level" already exists
if (!(Get-EventLog -LogName Application -Source "Level" -ErrorAction SilentlyContinue)) {
New-EventLog -LogName Application -Source "Level"
}
# Install if service doesn't exist OR if level.exe doesn't exist
if($service -eq $null -or $levelExe -eq $false) {
# Level is not installed or incomplete. Install/reinstall it
Write-EventLog -LogName "Application" -Source "Level" -EventID 100 -EntryType Information -Message "Installing Level agent on $hostname"
########### REPLACE LEVEL API KEY STRING BELOW ##############
$logFile = Join-Path ([System.IO.Path]::GetTempPath()) level_msiexec_install.log
$args = "LEVEL_API_KEY=API_KEY_HERE LEVEL_FORCE_INSTALL=true LEVEL_LOGS=$logFile"
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$tempFile = Join-Path ([System.IO.Path]::GetTempPath()) "level.msi"
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest -Uri "https://downloads.level.io/level.msi" -OutFile $tempFile
$ProgressPreference = 'Continue'
Start-Process msiexec.exe -Wait -ArgumentList "/i $tempFile $args /qn"
Get-Content -Path $logFile
########### PASTE LEVEL API KEY STRING ABOVE ##############
# Check if installation was successful
$serviceCheck = Get-Service -Name Level -ErrorAction SilentlyContinue
if($serviceCheck -ne $null) {
Write-EventLog -LogName "Application" -Source "Level" -EventID 100 -EntryType Information -Message "Level was successfully installed. Please check the agent page at https://app.level.io and look for the agent called $hostname"
} else {
Write-EventLog -LogName "Application" -Source "Level" -EventID 102 -EntryType Error -Message "Level installation may have failed. Please check installation manually on $hostname"
}
} else {
# Level is already installed, check if it's running
if($service.Status -ne "Running") {
# Service exists but not running, try to start it
try {
Start-Service -Name Level -ErrorAction Stop
Write-EventLog -LogName "Application" -Source "Level" -EventID 103 -EntryType Information -Message "Level service was found but not running. Service has been started on $hostname"
} catch {
Write-EventLog -LogName "Application" -Source "Level" -EventID 104 -EntryType Warning -Message "Level service exists but could not be started on $hostname. Error: $($_.Exception.Message)"
}
} else {
# All good - service exists and is running
Write-EventLog -LogName "Application" -Source "Level" -EventID 101 -EntryType Information -Message "The Level install GPO ran successfully, Level is already installed and running. Look for the agent called $hostname"
}
}
'@
# Create the group policy backup folders and files prior to importing
$GPO_path = $env:systemdrive + '\temp\Level-Temp{920B8A43-A054-4C44-B126-1E057DFFBC4C}\DomainSysvol\GPO\Machine\Preferences\ScheduledTasks'
New-Item $GPO_path -ItemType Directory -Force
# Create Backup.xml
$DomainName = Get-ADDomain | Select-Object -ExpandProperty Forest
$Backup_xml_path = $env:systemdrive + '\temp\Level-Temp{920B8A43-A054-4C44-B126-1E057DFFBC4C}\Backup.xml'
Set-Content $Backup_xml_path @"
<?xml version="1.0" encoding="utf-8"?>
<GroupPolicyBackupScheme bkp:version="2.0" bkp:type="GroupPolicyBackupTemplate" xmlns:bkp="http://www.microsoft.com/GroupPolicy/GPOOperations" xmlns="http://www.microsoft.com/GroupPolicy/GPOOperations">
<GroupPolicyObject><FilePaths/><GroupPolicyCoreSettings><ID><![CDATA[{ADF3CB7A-D977-4F44-9D77-DCAC28426AC2}]]></ID><Domain></Domain><SecurityDescriptor></SecurityDescriptor><DisplayName><![CDATA[Level Install - Task]]></DisplayName><Options><![CDATA[0]]></Options><UserVersionNumber><![CDATA[0]]></UserVersionNumber><MachineVersionNumber><![CDATA[1835036]]></MachineVersionNumber><MachineExtensionGuids><![CDATA[[{00000000-0000-0000-0000-000000000000}{CAB54552-DEEA-4691-817E-ED4A4D1AFC72}][{AADCED64-746C-4633-A97C-D61349046527}{CAB54552-DEEA-4691-817E-ED4A4D1AFC72}]]]></MachineExtensionGuids><UserExtensionGuids/><WMIFilter/></GroupPolicyCoreSettings>
<GroupPolicyExtension bkp:ID="{F15C46CD-82A0-4C2D-A210-5D0D3182A418}" bkp:DescName="Unknown Extension">
<FSObjectFile bkp:Path="%GPO_MACH_FSPATH%\Preferences\ScheduledTasks\ScheduledTasks.xml" bkp:Location="DomainSysvol\GPO\Machine\Preferences\ScheduledTasks\ScheduledTasks.xml"/>
</GroupPolicyExtension>
</GroupPolicyObject>
</GroupPolicyBackupScheme>
"@
# Create bkupInfo.xml
$bkupInfo_xml_path = $env:systemdrive + '\temp\Level-Temp{920B8A43-A054-4C44-B126-1E057DFFBC4C}\bkupInfo.xml'
Set-Content $bkupInfo_xml_path @'
<BackupInst xmlns="http://www.microsoft.com/GroupPolicy/GPOOperations/Manifest"><GPOGuid><![CDATA[{1041B92A-930A-46F9-8942-CA7AB9080D33}]]></GPOGuid><GPODomain><![CDATA[level.local]]></GPODomain><GPODomainGuid><![CDATA[{5ce50db9-5895-43f4-ab58-fb8f5811a29b}]]></GPODomainGuid><GPODomainController><![CDATA[Server.level.local]]></GPODomainController><BackupTime><![CDATA[2022-05-14T21:28:22]]></BackupTime><ID><![CDATA[{920B8A43-A054-4C44-B126-1E057DFFBC4C}]]></ID><Comment><![CDATA[]]></Comment><GPODisplayName><![CDATA[Install Level Agent]]></GPODisplayName></BackupInst>
'@
# Create ScheduledTasks.xml
$ScheduledTasks_xml_path = $env:systemdrive + '\temp\Level-Temp{920B8A43-A054-4C44-B126-1E057DFFBC4C}\DomainSysvol\GPO\Machine\Preferences\ScheduledTasks\ScheduledTasks.xml'
Set-Content $ScheduledTasks_xml_path @"
<?xml version="1.0" encoding="utf-8"?>
<ScheduledTasks clsid="{CC63F200-7309-4ba0-B154-A71CD118DBCC}">
<ImmediateTaskV2 clsid="{9756B581-76EC-4169-9AFC-0CA8D43ADB5F}" name="Install Level Agent" image="0" changed="2022-05-18 04:29:29" uid="{F734F614-77C6-4DFA-B0B0-25D49EE2FE35}" userContext="0" removePolicy="0">
<Properties action="C" name="Install Level Agent" runAs="NT AUTHORITY\System" logonType="S4U">
<Task version="1.3">
<RegistrationInfo>
<Author>LEVEL\Administrator</Author>
<Description>Installs or verifies Level agent installation</Description>
</RegistrationInfo>
<Principals>
<Principal id="Author">
<UserId>NT AUTHORITY\System</UserId>
<LogonType>S4U</LogonType>
<RunLevel>HighestAvailable</RunLevel>
</Principal>
</Principals>
<Settings>
<IdleSettings>
<Duration>PT5M</Duration>
<WaitTimeout>PT1H</WaitTimeout>
<StopOnIdleEnd>false</StopOnIdleEnd>
<RestartOnIdle>false</RestartOnIdle>
</IdleSettings>
<MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
<DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
<StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
<AllowHardTerminate>true</AllowHardTerminate>
<StartWhenAvailable>true</StartWhenAvailable>
<AllowStartOnDemand>true</AllowStartOnDemand>
<Enabled>true</Enabled>
<Hidden>false</Hidden>
<ExecutionTimeLimit>PT1H</ExecutionTimeLimit>
<Priority>7</Priority>
<DeleteExpiredTaskAfter>PT0S</DeleteExpiredTaskAfter>
<RestartOnFailure>
<Interval>PT1M</Interval>
<Count>3</Count>
</RestartOnFailure>
</Settings>
<Triggers>
<TimeTrigger>
<StartBoundary>%LocalTimeXmlEx%</StartBoundary>
<EndBoundary>%LocalTimeXmlEx%</EndBoundary>
<Enabled>true</Enabled>
</TimeTrigger>
<BootTrigger>
<Enabled>true</Enabled>
</BootTrigger>
<LogonTrigger>
<Enabled>true</Enabled>
</LogonTrigger>
</Triggers>
<Actions Context="Author">
<Exec>
<Command>C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe</Command>
<Arguments>-ExecutionPolicy bypass -command "& \\$DomainName\SYSVOL\$DomainName\scripts\Install_Level_Agent.ps1"</Arguments>
</Exec>
</Actions>
</Task>
</Properties>
</ImmediateTaskV2>
</ScheduledTasks>
"@
# Check if the GPO already exists and delete it if it does
$existingGPO = Get-GPO -Name "Install Level Agent" -ErrorAction SilentlyContinue
if($existingGPO) {
Write-Warning "The 'Install Level Agent' GPO already exists. Removing it before creating a new one."
Remove-GPO -Name "Install Level Agent" -Confirm:$false
}
# Create a new GPO "Install Level Agent" and link it to the root of the domain
$DistinguishedName = Get-ADDomain | Select-Object -ExpandProperty DistinguishedName
New-GPO -Name "Install Level Agent" | New-GPLink -Target $DistinguishedName
# Import the GPO settings from the backup files (above) into the new GPO
$GPO_Backup_Location = $env:systemdrive + '\temp\Level-Temp{920B8A43-A054-4C44-B126-1E057DFFBC4C}'
Import-GPO -BackupGpoName "Install Level Agent" -Path $GPO_Backup_Location -TargetName "Install Level Agent"
# Clean up temporary files
Remove-Item ($env:systemdrive + '\temp\Level-Temp{920B8A43-A054-4C44-B126-1E057DFFBC4C}') -Recurse -Force -ErrorAction SilentlyContinue
Write-Host "The 'Install Level Agent' GPO has been created and linked to the domain root." -ForegroundColor Green
Write-Host "Remember to replace the placeholder 'API_KEY_HERE' in the script with your actual Level API key." -ForegroundColor Yellow
Run the Level installer GPO auto-deploy script on a domain controller
Once the script is created you're ready to push the script to a domain controller and Level will start to auto-deploy to all machines on the domain.
Only run this script on a single domain controller per Active Directory environment.
Copy the installation command from the Install Agent window. We will paste this command in a later step.
On the Devices page click the checkbox next to the domain controller and then at the top select Scripts and then Run Saved Script.
In the selection box that appears choose Level installer GPO auto-deploy
On the script review page, paste the Level installer command on the line that states "Paste Level install command here". (At the time of writing this is line 17.) Be sure to paste the text in that line so that it is replaced.
Click Review Job
On the job summary page click Execute Job to start the script. The command output can reviewed by expanded by clicking the arrow in the far right column of the agent table. If there are no errors in red, then your group policy object has been setup and is live. On the next group policy refresh, domain-joined computers will receive the Level agent.
Manual setup of Group Policy
If a manual setup of group policy is preferred then this can be done via an immediate scheduled task.
Create a new GPO and link it to the appropriate OU in Active Directory.
Edit the policy and go to Computer Configuration | Preferences | Control Panel Settings | Scheduled Tasks | Right-click and select New->Immediate Task (At least Windows 7).
Creating a new task in the Group Policy Management Editor
On the general tab
Enter name as Install Level Agent
Click the Change user or Group button, search for SYSTEM, click OK
Select Run whether user is logged on or not.
Check Run with highest privileges.
In the Configure for: select “Windows 7, Windows Server 2008R2”
Configure Level agent properties for Windows Server
On the Actions Tab
Click “ New”
In the Program/script field, enter:
c:\windows\system32\windowspowershell\v1.0\powershell.exe
In the Add argument field, enter the following. Replace "PUT_YOUR_LEVEL_KEY_HERE" with your Level installer key.
-ExecutionPolicy Bypass; $env:LEVEL_API_KEY = 'PUT_YOUR_LEVEL_KEY_HERE'; Set-ExecutionPolicy RemoteSigned -Scope Process -Force; [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; iwr -useb https://downloads.level.io/install_windows.ps1 | iex
Click OK on the New Action window and click OK on the Properties window to close out the windows.
Create a new action and add additional arguments
The GPO is complete. On the next group policy refresh the agent will be installed on the domain-joined computers linked to the OU selected.
The automated script used earlier on this page will drop Windows Event Log messages on the client machines once the installer script has been called in order to aid in troubleshooting. This manual setup just covered will not provide event log messages.