This post is intended to be a central spot for tips on troubleshooting Windows command lines in ActionScript. This post may be updated as I get new pointers.
When troubleshooting a Windows ActionScript, here are some things that may be useful:
- Disable Wow64 Redirection. By default the BigFix Client, and any processes it spawns, are running in 32-bit context. Sometimes this is irrelevant, but some 64-bit installers or commands may fail when they run in 32-bit context. The wow64 redirection can be disabled, switching any commands we launch with the ‘wait’ or ‘run’ commands to execute in the native context.
Add the command
action uses wow64 redirection false
or
action uses wow64 redirection {not x64 of operating system}
to your ActionScript, on any line before the ‘wait’ or ‘run’ command, to disable Wow64 redirection and to run in the native 64-bit mode for the rest of the Action.
-
Test your command lines. Before trying to run an installer or other script command in the BigFix context, first test it out to ensure your command lines work as expected in a Command Prompt.
-
Test in the LocalSystem context. If your installer or script works when run manually, but does not work as expected when run via BigFix, try testing the commands by running in the LocalSystem user account, the way the command will run when BigFix executes it.
The simplest way to test is to download the ‘psexec’ utility from https://www.microsoft.com/sysinternals , and then use psexec to open a command shell in the LocalSystem context by runningpsexec -i -s cmd.exe
To test in a 32-bit command shell, you could also execute
psexec -i -s c:\windows\syswow64\cmd.exe
-
Ensure the script or application does not display any pop-up windows that need to be acknowledged. If the command displays a pop-up window that requires any acknowledgement, that window will not be visible to logged on users by default when the script is run via BigFix. The window will be stuck in the LocalSystem session, cannot be acknowledged, and the ActionScript may never complete as the process is stuck waiting for input.
The best option is to find silent or unattended command lines for the installer or the script. If that cannot be done, you can consider running the script in the context of a logged-on user instead of as the LocalSystem account using theoverridecommands (see Tip - Action Override User settings ) -
Understand the installer type. There are several different popular installer technologies, and each has different command-line options. A software vendor may use one of the popular installers (where command line parameters may be standardized) or may forgo the common installers and produce an installer package unique to their product (with command-line parameters that are not standardized).
Common MSI package installer command lines include
| Syntax | Description |
|---|---|
| msiexec /i “filename.msi” | Install the MSI package |
| ALLUSERS=1 | Install system-wide for all users |
| /qn | Install silently with no user interaction |
| /REBOOT=ReallySuppress | Do not reboot the system after installing |
| /L*v “c:\path\to\logfile.txt” | Create a log of the installation with all information, verbose logging, output to the specified file |
For many other MSIEXEC command lines, see https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/msiexec
Common InstallShield command lines include
| Syntax | Description |
|---|---|
| setup.exe /S | Install the package in silent mode |
| /v"/qn ALLUSERS=1" | If the InstallShield Package contains a bundled MSI package, the parameters after ‘/v’ are passed to MSIEXEC. In this case, install the MSI in Silent Mode and install for all users. |
For more InstallShield command lines, see https://docs.revenera.com/installshield21helplib/helplibrary/IHelpSetup_EXECmdLine.htm
- Log the command output and error messages. The cmd.exe shell has the ability to log all of the output messages, as well as any error messages displayed on the command line, through redirection of the ‘stdout’ and ‘stderr’ output streams. cmd.exe also has specialized handling for quotes on the command line.
To run a command that has spaces in the name, as well as handle output files that may have spaces in the filename, we can combine quote handling and output redirection with a command similar to
wait c:\windows\system32\cmd.exe /C ""__Download\setup.exe" /S /v"/qn Reboot=ReallySuppress ALLUSERS=1 /L*v c:\temp\msi-setup.log" > "c:\temp\command-output.log" 2>&1"
This uses the Command shell to execute a downloaded setup.exe, logging the MSI output as well as the command prompt output and error messages to log files.
- Watch for curly-brackets to escape. Especially when running PowerShell command lines or removing MSI software packages, it is common to have curly-brackets { } on the command line. ActionScript interprets these as Relevance Substitutions in the action and they need to be escaped.
For full details, see Tip: Escaping curly brackets for substitutions in ActionScript
For the short version, change
wait msiexec.exe /x{guid}
to
wait msiexec.exe /x{{guid}
- Check the Logs and Exit Codes
-
check both the BESClient logs and the command and msiexec logs generated above.
-
Check the exit code of the command (visible in the Console’s Action Status result, as well as in the BESClient log itself).
-
An exit code of ‘0’ usually means the command executed successfully (but it is up to the executable itself to provide this return code, and a few cases the command’s exit code may not correctly provide a success/failure result).
-
A positive-number exit code usually means the command failed, and the specific number may indicate a reason for failure. For instance MSI exit codes are standardized and available at https://learn.microsoft.com/en-us/windows/win32/msi/error-codes
-
A large negative-number exit code usually means the installer provided a 32-bit unsigned integer result code that should be interpreted in hexadecimal, but our client expected a signed 32-bit integer. The client reports an exit code such as ‘-2146498497’ that needs to be translated to a hexadecimal value such as ‘0x800f083f’. The conversion can be performed using online calculators like https://www.rapidtables.com/convert/number/decimal-to-hex.html, or you can convert it in the Fixlet Debugger as
q: last 8 of ((-2146498497 as integer) as hexadecimal)
A: 800f083f
(more details on this conversion at Exit codes list )