8.7 - Plugin Quick Install Feature explanation and Troubleshooting

Products

• IT Management Suite
• Deployment Solution
• Client Management Suite

Issue/Introduction

Starting with 8.7 SMA is able to quickly install, upgrade, or uninstall client plugins without involving policies and tasks.

The information about the plugins that need to be processed is passed to the agent via the install XML file. This is the same install XML that is being used to provide SMA with the connection profile and CEM settings.

Install XML sample containing Deployment Plugin info is below. The important fields include plugin name, version, package GUID, and installer's command-line.

There are a few ways install XML can be passed to the agent:

1. Manual agent installation using AENSC.exe package, few samples are below:
   1. AEXNSC.exe /installxml=<xml path>
   2. AEXNSC.exe /reinstall /installxml=<xml path>
   3. AEXNSC.exe /nsweb=https://server.com /installxml=<xml path>
2. Agent push installation. NS console page is used to select the list of plugins to process and then install XML gets pushed along with the agent package to the client and gets executed via the command line above.
3. Agent upgrade policy execution. If the plugin upgrade option is checked then install XML gets created and passed as a part of the agent package to the client and gets executed.
4. Unified plugin rollout policy execution. Install XML gets passed as part of client policy to the client and gets executed.
5. Deployment Solution tasks execution. SOI and image deployment tasks allow a user to select the list of plugins. Install XML gets delivered to the client as part of the task XML.

Install XML processing sequence.

In all the scenarios above the install xml file named AEXNSC.xml is created in the agent installation folder or copied in there and then SMA is restarted. All the scenarios work exactly the same way after that:

1. SMA detects AEXNSC.xml in the agent folder and checks if the plugins list is in there.
2. If the plugin list is there, then SMA starts in special "quick install" mode. All the steps below are specific to quick install mode where SMA executes a very limited set of actions.
3. SMA first checks if the agent is registered and registers on the NS server if it is not. The whole sequence is aborted if SMA cannot register in 20 minutes.
4. SMA then sends basic inventory and receives the policies. The policies are used to get ACC credentials and various download settings. The whole sequence is aborted if SMA cannot receive the policy in 20 minutes.
5. SMA does not load any plugin in quick install mode, so no tasks or policies get actually processed even if they are received.
6. SMA does not show any UI elements, it does not show a tray icon and UI cannot be invoked.
7. When SMA is running in quick install mode then both AEXNSAGENT.exe and AEAGENTUIHOST.exe processes can be seen in Task Manager.
8. SMA validates the list of plugins from install XML and downloads the ones that can be installed one by one. The plugins can be downloaded from NS, site servers, or peers. All download and package delivery settings, like throttling are applied.
9. SMA creates a quick installer XML that contains the list of plugins that need to be installed. This list can contain fewer plugins than the list from install XML. Quick install XML is named QuickInstall.xml and is located in the agent installation folder.
10. SMA starts a quick installer module when all applicable plugins are downloaded.
11. The quick installer does the rest of the processing. The quick installer is hosted inside the AEXAGENTUTIL.exe process. Only AEXAGENT.exe is visible in Task Manager during this stage. No UI is available.
12. The quick installer stops SMA service
13. Quick installer validates a list of plugins from quick install xml and executes plugin installers one by one.
14. Plugin installers running in quick install mode do not start or stop SMA service and do not send basic inventory. If some installer starts SMA service, then SMA service will be stopped by quick installer before the next plugin installer start.
15. Quick installer starts SMA service and quits when plugin list is completely processed.
16. SMA service starts, detects the end if quick installation sequence and sends basic inventory that will contain the list f installed or updated plugins.

 

Environment

Release: 8.7

Resolution

Quick Installer troubleshooting

When the quick installer starts at step #11 (see above) it creates the following registry entries under HKEY_LOCAL_MACHINE\SOFTWARE\Altiris\Altiris Agent

1. AEX_QUICK_INSTALL_RUNNING : REG_SZ  = "1"
2. AEX_QUICK_INSTALL : REG_SZ  = "1"

The first one is removed at the end of the quick install sequence at step #15 and can be used to detect if the quick installer is currently running or if it was running before and crashed for some reason. The crash dump should be created in the later case.

The second registry entry is meant for plugin installers usage, they use this registry entry to detect if they are running in "quick install" mode and that they should not start or stop SMA service or send basic inventory. The second registry entry is also used by the SMA service at step #16 to detect that the installation sequence has ended and that it should send the basic inventory.

Quick Installer copies both AEXNSC.xml and QuickInstall.xml that were used during the installation sequence to the "InstallLogs" folder, see sample below. There could be multiple XMLs in case a quick installation sequence was running multiple times, pay attention to the time stamp in the name. These files are never cleaned up.

Sequence sample

Below is the installation sequence sample obtained by using the filter "QuickInstaller" in the log viewer. Two plugins get validated, downloaded, and installed.

Loading and plugin validation stages go first - AEXNSC.ml gets loaded, and plugins get checked one by one.

Downloading stages go then - two plugins get downloaded one by one, which can take some time, the download timeout for each package is set to 10 minutes, if the plugin download cannot be started in 10 minutes, then that plugin will be skipped.

Then SMA service starts the quick installer by passing the path to QuickInstall.xml to AEAGENTUTIL.exe using /quickinstall parameter

The quick installer then stops SMA service

The quick installer then validates and installs plugins one by one starting SMA service at the end

 

Unified policy processing

Unified policy allows the admin to schedule plugin updates via policy, The policy with the specified plugins in the list is processed only once. In order to process the same policy again the admin should change the plugins list.

This policy tracking mechanism is based on a policy run history, which is stored as a set of files in the "Quick Installer" folder, see below.

Each file name consists of policy GUID and policy content hash. You can force SMA to run the policy again by removing the history file.

Each history file contains XML describing the policy rollout result, see below. By matching the time to XML files in the "InstallLogs" folder you can find AEXNSC.xml and QuickInstall.xml files that were used during particular policy rollout.

So generally, SMA logs should be gathered from the Agent, and then we can check the mentioned folders if data was generated there.

Also, note that only the current list of Agents on 8.7 supports Quick Install method: