The Advanced Agent consists of client and server components, described in this article.

ERIS (Empirum Remote Installation Service)

ERIS is the central computer component. It runs as a service (LocalSystem) on the computer and communicates with the transport, setup and ERIS_UI. ERIS analyzes installation information (DDC and DDS) and sets up installation schedules (polling and scheduled installation).

ERIS UI (Empirum Remote Installation Service_User Interface)

The security concept on which Vista and younger Windows versions are based does not allow services to communicate with a user desktop. For this reason, ERIS does not have a graphical user interface, but forwards all output to ERIS_UI. ERIS_UI is launched automatically when a user logs in. ERIS_UI also displays the kiosk and the installation dialog.

Transport

Transport is responsible for communications with the Empirum server and is controlled by ERIS. Jobs may, for instance, include the following actions:

• Load package into the cache;
• Send log to the Empirum server;
• Delete package from the cache;
• Check rights for the check files.

Setup

Setup.exe is the installation interpreter and is launched by ERIS. Setup.exe interprets the Empirum script language (the Setup.inf language) used for software installation and configuration.

Agent Configuration XML

All settings of the Advanced Agent are stored in the database as agent templates and as XML file with the same name on the Empirum server under .\Configurator\User\. When the Advanced Agent is installed, this XML file will be copied onto the system and checked and updated during each polling.

Templates are assigned to configuration groups in the Matrix42 Management Console to specify which computer receives which configuration file. As a result, the variable file of the respective system (Computername.ini) also lists the assigned template, which is referenced when the Agent is installed.

The configuration file is stored locally as AgentConfig.xml in the directory .\System32\Empirum\. If a system has not been assigned a template, the default template will be used; this is the first created template and can be modified anytime at a later point in time.

Configuration – Best Practices

The Advanced Agents provides many optional settings. This section will describe a standard configuration; if necessary, alternatives will also be explained, but not all settings. Additional options can be found in the Software Management help.

Specifying Access Accounts

Log-in information must be provided to enable the Advanced Agent to access the Empirum server. The Empirum server and the client are linked through the variables of the assigned Empirum server. The log-in information must be stored in the variables of the Empirum (depot) server, which can be done directly on the Empirum server or through the server's configuration group.

The user-defined "SUBDEPOT" variable contains information on user and password. The user must have access rights for the Empirum servers.

• User_x. For domains, you must specify Domain\Username, for local accounts .\Username in the workgroup.
• Password_x. The entered password is encrypted automatically.

You must specify the Empirum server and a valid user account for the Agent when creating the Agent templates.

Alternative DHCP Options

In distributed environments, it is recommended that you use DHCP options to hand over log-in information. This ensures that the systems use the correct Empirum server automatically, depending on their location, and also receive the required log-in information.

DHCP options are configured in Matrix42 DBUtil and are enabled when the Agent template is configured. If user and password are not specified, the DHCP settings in the template are used for all servers.

The following names for DHCP options are used for all Empirum products:

• EmpirumServer
• EmpUser
• EmpPW

The password (EmpPW) must be encrypted with the Empirum Sync/AES256 encryption (see EmpCrypt in .\Empirum\AddOns\Encrypter).

Agent Template Configuration

The configuration of the assigned Agent template has a major impact on the behavior of the Advanced Agent on the system; configuration is done under Configuration > Software Management > Empirum Agent.

As a rule, the following settings must be configured:

• Behavior when accessing the Empirum server;
• Polling and installation behavior;
• End-user specifications and display.
• Windows Terminal Server / Citrix XenApp settings

Access to the Empirum Server

All Empirum servers can be selected with the appropriate user account; DHCP options can be used alternatively.

We recommend that you use the DHCP options in large or distributed environments with many depot servers.

Protocols (General Settings - Transport Protocols)

There are three primary protocols (SMB, http and https), which can download all data from the server. You can select a secondary protocol, which is only used to transfer the software packages. If this secondary protocol is not able to reach the server, the primary protocol is used automatically.

Experience has shown that SMB is a good choice for desktops in the LAN and http(s) is useful for systems with changing/low-bandwidth network connections.

The subdepot package must be installed on the Empirum server to be able to use the http(s) protocols. http(s) uses the variables described above to configure the log-in information.

Agent Behavior

How often and when the Advanced Agent connects to the server to install packages is dependent on many factors and on the settings made for the user installation dialog.

The two following strategies have proved to be useful for desktops; in most cases, servers must be configured without user prompts, since users do not log onto servers very often.

One-Time Installation - During Log-In or If No User is Logged in

1. Polling is switched off (Software Depot - Polling Settings - Define Polling Interval (/K).
2. Enable the option Install on Download (SoftwareDepot > Parameters > Install immediately after download).
3. The Installation request setting is set to User interaction possible to allow the user to postpone packages that have been assigned the Postpone distribution option.
   The interval that must expire before the user dialog is closed automatically should be maximized (e.g., 7200, which corresponds to 2 hours) to allow the user to start the installation immediately or to save and finish his current work. After expiration, the packages that have not been assigned the User can postpone option are installed automatically.
4. The distribution options for the software packages are used to control the postpone option.

Scheduled Installation - During Log-In or If No User is Logged in

1. The Polling interval is set to a value that suits the respective environment (1 to 4 hours).
2. Enable the option Install on Download (SoftwareDepot > Parameters > Install immediately after download).
3. The User prompt option User interaction possible must be selected (AgentUI > User Installation Request Interface (Z Dialog) > Default Dialog Behavior).
4. The interval that must expire before automatic close-down should not be too high (e.g., 600 corresponds to 10 minutes). (AgentUI > User Installation Request Interface (Z Dialog) > Close Installation Request after)
5. The distribution options for the software packages are used to control the postpone option.

Advanced Agent Installation

There are several methods to install the Advanced Agent:

• Installation directly after operating system installation;
• Push via the network directly to existing systems;
• Distribution and installation via an Empirum package;
• Creation of a self-extracting package and installation via log-in script.
• Installation of MSI package via group policy or via log-in script.

Installation Directly After Operating System Installation

Installation of Windows operating systems via the Empirum OS-Installer is based on operating system templates. The last configuration point of the OS template refers to the command to be executed after installation. By default, a CMD file is specified; in the past, the EmpirumAgent.bat file in the .\Configurator\User\ directory supplied by Matrix42 was used.

This file is used to launch the Advanced Agent installation package described above and to restart the system afterwards. When the system has been restarted, the Advanced Agent first synchronizes the software packages available for installation and then starts the installation process.

Please ensure that the value for caching the packages locally (Delete Packages after) is sufficiently high to avoid that, for instance, packages are installed Saturday nights and are removed from the cache on Sundays.

Push via the Network Directly to Existing Systems

The context menu in the Matrix42 Management Console can be used to install (push) the Advanced Agent to any system. It is also possible to select several computers via the configuration group. Systems from the network that are not known to the Empirum database can be assigned prior to pushing the Agent via the network browser in the console. Communications with the system is done via the Empirum Agent push service, which needs the respective log-in information to install the Agent and .Net, if necessary, on the target system. After successful installation, the service ERIS.exe (Empirum Remote Installation Service) and ERIS_UI.exe for the user part is launched on the system to distribute the software, based on the configuration assigned to this system.

Distribution and Installation via an Empirum Package

The Empirum Advanced Agent is available in the console as a package. This package can be used to update a system with an older version of the Advanced Agent and to update computers with the Legacy Agent. The required Windows runtime components are also installed automatically.

Creation of a Self-Extracting Package and Installation via Log-in Script

Before creating such self-extracting package, the respective Agent configuration file (XML) from the directory .\Configurator\User\. must be copied into the Empirum Agent Subdirectory Template_SFX. If this is not the default template (defaultAgentConfig.xml), the respective Agent configuration file must be renamed into defaultAgentConfig.xml.

Then you can create a self-extracting package with administrative log-in information under Configuration > Software Management > Depot in the Matrix42 Management Console. Save the EXE file to be created in the directory .\Configurator\User\.

You can use this package to install the Advanced Agent, for instance, via the log-in script.

Add the following lines to your log-in script:

REM Empirum Advanced Agent Installation
If Exist "%WinDir%\System32\Empirum\Eris.exe" Goto :End
\\%EmpirumServer%\Configurator$\User\EmpirumAgent_v15.exe
:End

If you have specified a registry key for one-time execution in the package, an additional query to find out whether the Empirum Advanced Agent has been installed already is not necessary.

Installation of MSI package via group policy or via log-in script

Installation of MSI package via group policy or via log-in script

You can find two MSI packages in the folder Configurator\Packages\matrix42\EmpirumAgent\MSI\Version number of the Empirum installation. They can be used to install the 32 and 64 bit versions of the Agent. They are used for the initial installation on computers where no Empirum Agent is installed. Please use the corresponding Empirum Advanced Agent package for updates.

You can set the following parameters. They are used to configure the agent for the first connection to the server.

• SERVER. Name of the Empirum server.
• USER. User name for the connection to the Empirum server.
• PASSWORD. Encrypted password for the connection. Please use the tool EmpCrypt located under the folderAddonsin order to encrypt the password in the sync format.
• PROTOCOL. Protocol used for the connection. Following values are valid: smb, http and https
• PORT. Port used for the connection with http and https. If the value is not set the default port 80 is used. When using the SMB protocol, no value for port is required.

Example call:

msiexec.exe /i "Empirum Advanced Agent 16.0 Setup 64bit.msi" SERVER="MyServer" USER="MyUser" PASSWORD="85FC516FCF3ACB0A60E09C4D3CB" PROTOCOL="https" PORT="443"

It is also possible to install the Advanced Agent via log-in script using the MSI packages.

Uninstallation

The Empirum Advanced Agent can be uninstalled manually or automatically.

Manual uninstallation:

The Empirum Advanced Agent can be uninstalled via System Control > Software.

Automatic uninstallation:

You can enable the Uninstallation package via the Empirum Management console.

Annotation:

In both cases, the local cache directory remains on the system.

Tips

For trouble-shooting purposes, you need the tool DebugView (can be downloaded free of charge under: https://technet.microsoft.com/en-us/sysinternals/). When you start DebugView on the system, the Empirum Advanced Agent and all other Empirum components provide detailed information on any activities.

The components of the Empirum Advanced Agent are installed under .\Windows\System32\Empirum.

By default, the local cache directory (including subdirectories) of the Empirum Advanced Agent cannot be viewed by the users. The Explorer settings must be adapted accordingly to be able to also view hidden files and directories.

The respective package must be available in the local cache to allow the Empirum Advanced Agent to install the user part or uninstall the software package. Under most unfavorable conditions (value for deleting the cache directory is too small) this might require a renewed download for uninstallation purposes.

Limitation of Errors

Recommended approach:

1. Stop the Empirum Remote Installation Service and then launch DebugView.
2. Restart the Empirum Remote Installation Service.
3. Do not stop the DebugView logs until several polling intervals have expired.

In case of problems with the Empirum Agent push:

1. Start DebugView on the Empirum server with a filter on the EmpAgentPushService service / process and on the client to which the Agent shall be pushed.
2. Start to push the Advanced Agent via the Matrix42 Management Console and then analyze the DebugView log created on the Empirum server and the respective client.

Detection of required Windows reboots

The Agent monitors required windows reboots outside the OS-Install mode. These can be necessary by manual installations or patches via windows update. In the case the file Windows\WinSXS\pending.xml or HKLM,Software\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update\RebootRequired exist, no further software management will be executed until a restart has been made. The Agent sends a log message Reboot Pending and after a successful restart a Reboot Success message. The user recognizes a grey tray-icon if a reboot is required.

This behavior can be deactivated by setting the registry key HKLM,Software\Matrix42\Agent value to 0. In this case the agent ignores reboots required by windows.

FAQs

Why are no packages displayed for the computer in the software kiosk?

• The computer runs in a workgroup environment and on the tabs in the depot the rights check is activated (checked). Such check makes only sense in domain environments.
• The Agent cannot connect to the depot server. Make sure that the server is available, that the correct protocol has been configured or that the log-in information is correct.
• The XML configuration file is not up-to-date or not correct (maybe no template has been assigned).
• Only the N/A option is displayed in the kiosk. The local cache might be defect or rights may have been modified. Delete the EmpirumAgent directory on the client. The Agent will create a new, correct directory.

Why is it not possible to create or update the XML configuration file on the Empirum server in the .\Configurator\User\ directory?

• The Agent push service creates the XML template files; this service must be installed and launched accordingly.

How can the user initiate a DDC or DDS update himself?

• The user launches the software kiosk via the tray icon with the option "Show Software Depot".
• The user can use the tray icon to launch the option "Check for new approved software".

Why can it happen that a package that has been assigned the Is downloaded status hangs up?

• The free space on the client's hard disk is smaller than the limit specified in the configuration. Ensure that sufficient free space is available on the system or reduce the limit. This information is also available in the Matrix42 Management Console in the AgentPush log of the respective client.

Why does the ERIS service not start immediately after manual close-down?

• The IPC port may not have been cleared yet after close-down. Wait some seconds and then restart the service.

What must be done after the log-in information (USER_1, PASSWORD_1) in the variables of the depot has been modified?

• You must store the Agent templates assigned to the depot again (not required when the DHCP option is used).
• The Empirum Advanced Agent must be pushed again to the clients to update the XML configuration file (not required when the DHCP option is used).
• The Empirum subdepot package must be reinstalled on the server (not required when SMB is used).

Why don't normal users have permissions to read files in the local agent cache?

• This was recommended as part of the results of an Empirum penetration test to prevent normal users from reading configuration data or control files. When the agent is started, the NTFS rights of the local agent cache are always set restrictively.
• The behavior can be influenced with the Reg Key SetNTFSCacheRights=0.
• Not available or 1= Restrictive rights are set at each start.
• 0 = No adjustment of NTFS rights

How are the EmpirumServer variables used with the Advanced Agent?

Installation Procedure

Installation With and Without "Installation on Download“ Option

Installation of a Software Package with different versions

If a software package is assigned to a computer in several versions and none is installed, only the highest version will be installed. This also applies if this package cannot be installed because of missing dependencies, scheduling or installation errors.

• If a lower package version is already installed, it can be still uninstalled or reinstalled.
• If an installed lower version of a package should be uninstalled by a higher version with the Setup.inf function "AskUninstallOld", the lower version should not be flagged with a reinstall command if it is queued later in the installation sequence.