#1 Global Leader in Data Resilience

PowerShell Script Execution Troubleshooting Advice

KB ID: 2183
Product: Veeam Backup & Replication | 10 | 11 | 12 | 12.1 | 12.2
Published: 2016-10-24
Last Modified: 2023-12-15
mailbox
Get weekly article updates
By subscribing, you are agreeing to have your personal information managed in accordance with the terms of Veeam's Privacy Notice.

Cheers for trusting us with the spot in your mailbox!

Now you’re less likely to miss what’s been brewing in our knowledge base with this weekly digest

error icon

Oops! Something went wrong.

Please, try again later.

Veeam Support Scope

Per Veeam Support Policy: Custom script troubleshooting is not supported.

What's in Scope:

  • Confirming that the Veeam task executed the script.
  • Assisting with Veeam PowerShell cmdlets not functioning as intended or documented.

What's Out of Scope:

  • Troubleshooting why a custom script did not function as intended.

Purpose

This article is intended to serve as a helpful resource from the Veeam Support team, offering straightforward guidance for those navigating the complexities of troubleshooting script failures. Please note, the advice provided within this article is given in good faith and without warranty.

This article provides advice on methods to troubleshoot PowerShell scripts that are executed as part of:

 

Solution

PowerShell Script Execution Details

Pre-Freeze and Post-Thaw scripts are:

  • uploaded to the Guest OS of the VM and executed with the command:
    powershell.exe -ExecutionPolicy ByPass -Command try { . 'C:\Windows\{guid}\<script>.ps1'  -ErrorAction Stop } catch { exit 1 }
    
  • executed using the account assigned within the Guest Processing settings.

Pre-Job and Post-Job scripts are:

  • executed on the Veeam Backup Server using the command:
    powershell.exe -ExecutionPolicy ByPass -Command  try {& '<path-to-script>'  -ErrorAction Stop } catch { exit 1 }
    
  • executed using the account assigned to the 'Veeam Backup Service'. By default, that account is 'Local System'.

General Advice

This section will provide advice on changes you can make to your script to help with troubleshooting.

For this example, here is a simple script that identifies the most recently modified file in a folder and then copies it to a folder.

$LatestLog = get-childitem -Path 'C:\MonitoringLogs\' | sort-object LastWriteTime | select-object -last 1
Copy-Item $LatestLog.FullName D:\Backup\
  • Add logging to the PowerShell script itself so that you can check what errors the script may have thrown when being executed. This can be done by adding 'Start-Transcript -path C:\temp\scriptlog.txt' to the first line of the script and adding 'Stop-Transcript' to the last line.
    Start-Transcript -path C:\temp\scriptlog.txt
    $LatestLog = get-childitem -Path 'C:\MonitoringLogs\' | sort-object LastWriteTime | select-object -last 1
    Copy-Item $LatestLog.FullName D:\Backup\
    Stop-Transcript
    
  • After adding the Start-Transcript cmdlet to the script, make the actions within your script more verbose. For example:
    • If the script contains a variable, have the script announce the variable using Write-Host so that it appears in the transcript log. For example:
      Start-Transcript -path C:\temp\scriptlog.txt
      $LatestLog = get-childitem -Path 'C:\MonitoringLogs\' | sort-object LastWriteTime | select-object -last 1
      Write-Host $LatestLog
      Copy-Item $LatestLog.FullName D:\Backup\
      Stop-Transcript
      
    • If the script uses a command that can have a -verbose flag added, add it so that the transcript log will contain more information. For example:
      Start-Transcript -path C:\temp\scriptlog.txt
      $LatestLog = get-childitem -Path 'C:\MonitoringLogs\' | sort-object LastWriteTime | select-object -last 1
      Write-Host $LatestLog
      Copy-Item $LatestLog.FullName D:\Backup\ -verbose
      Stop-Transcript
      
 
Conclusion

Now, this simple script, when run, will also write out a log file containg:

  • Full PowerShell headers documenting what command was used to call it, as well as what user ran it.
  • What file it determined to be the $LatestLog
  • What the outcome of the Copy-Item command was.

Troubleshooting Pre-Freeze/Post-Thaw Scripts

Test running the script from within the Guest OS of the VM using the account assigned within the Guest Processing settings of the job.

  1. Connect to the Guest OS of the VM using the account that Veeam Backup & Replication is configured to use for Guest Processing.
  2. Copy the script manually to the Guest OS.
  3. Open an elevated PowerShell prompt.
  4. Update the 'C:\path\to\script.ps1' path in this example command and execute it.
    This command is the same as the one Veeam Backup & Replication uses to trigger the script.
powershell.exe -ExecutionPolicy ByPass -Command "& {try {& 'C:\scripts\testscript.ps1' -ErrorAction Stop } catch { exit 1 }}"
  1. Observe the outcome. If it fails, resolve the errors shown, save the script, and test it again.

Troubleshooting Pre-Job/Post-Job Scripts

Pre-Job/Post-Job scripts are executed on the Veeam Backup Server, using the account assigned to the Veeam Backup Service.

To begin direct script troubleshooting you will first need to identify which account Veeam will use to run the script, that way you can test your script using the same account.

 

Identify Veeam Backup Service Account

Open services and check which account is listed in the 'Log On As' column for the Veeam Backup Service.

Or, check via PowerShell using:

Get-WmiObject Win32_Service -Filter "Name='VeeamBackupSvc'" | Select-Object Name,StartName

Service Account is Local or Domain User

If the Veeam Backup Service is running under an actual user account, login as that account and test the script using the following command. This command is directly based on the method Veeam Backup & Replication uses to call the script:

powershell.exe -ExecutionPolicy ByPass -Command "& {try {& 'C:\scripts\testscript.ps1' -ErrorAction Stop } catch { exit 1 }}"

Service Account is LocalSystem

If the account assigned to the Veeam Backup Service is Local System, which is the most common configuration, testing the scripts manually will be a bit more difficult. There are two options for causing a script to be run using the account Local System.

The Local System account (aka 'SYSTEM' or 'NT Authority\SYSTEM') has the highest privileges possible. Using PsExec, as documented below, will allow you to run commands as that superuser; please be very careful what commands you run. You and you alone are responsible for the actions you take. Veeam Support will not assist you in running commands as SYSTEM.
Option 1: Test the Script As SYSTEM Using PsExec

This option will allow you to see any errors that are thrown immediately and allow you to rapidly rerun the script after modification to perform iterative testing more efficiently.

PsExec is available from Microsoft here: PsExec

To simulate the execution action Veeam Backup & Replication would perform as SYSTEM:

  1. Launch an Administrative Command Prompt and run the following command to open a PowerShell console as SYSTEM:
PsExec64.exe -s -i powershell.exe
  1. A new PowerShell prompt will appear.
  2. Update the "C:\path\to\script.ps1" in this example command and execute it.
    This command is the same as the one Veeam Backup & Replication uses to trigger the script.
powershell.exe -ExecutionPolicy ByPass -Command "& {try {& 'C:\path\to\script.ps1' -ErrorAction Stop } catch { exit 1 }}"
  1. Observe the outcome. If it fails, resolve the errors shown, save the script, and test it again.
Option 2: Test the Script Using Task Scheduler to Run the Script As SYSTEM
  1. Open Task Scheduler.
  2. Create a New Task.
    • Name the Task.
    • On the General tab, in the Security options section, click 'Change User or Group...' and enter the username SYSTEM.
    • On the Actions tab, add an action to "Start a program." 
      • For the Program/script, enter: powershell.exe
      • For the Arguments field, update the 'C:\path\to\script.ps1' in the following example and insert it.
        -ExecutionPolicy ByPass -Command "& {try {& 'C:\path\to\script.ps1' -ErrorAction Stop } catch { exit 1 }}"
        
  3. Run the Task.
To submit feedback regarding this article, please click this link: Send Article Feedback
To report a typo on this page, highlight the typo with your mouse and press CTRL + Enter.

Spelling error in text

This site is protected by hCaptcha and its Privacy Policy and Terms of Service apply except as noted in our Privacy Policy.
Thank you!

Thank you!

Your feedback has been received and will be reviewed.

Oops! Something went wrong.

Please, try again later.

You have selected too large block!

Please try select less.

KB Feedback/Suggestion

This form is only for KB Feedback/Suggestions, if you need help with the software open a support case

By submitting, you are agreeing to have your personal information managed in accordance with the terms of Veeam's Privacy Notice.
This site is protected by hCaptcha and its Privacy Policy and Terms of Service apply except as noted in our Privacy Policy.
Verify your email to continue your product download
We've sent a verification code to:
  • Incorrect verification code. Please try again.
An email with a verification code was just sent to
Didn't receive the code? Click to resend in sec
Didn't receive the code? Click to resend
Thank you!

Thank you!

Your feedback has been received and will be reviewed.

error icon

Oops! Something went wrong.

Please, try again later.