How to troubleshoot problems when attempting to use agent push to push an agent updates from the Unitrends system to its protected Windows clients. This article may be used to troubleshoot the error "Windows installer encountered error 1603 during agent uninstall. Ensure account used is a domain administrator or the local Administrator account. See Unitrends KB 693"
Agent Push is a feature in which our system can “push” install an agent as part of the setup of a Windows client. With agent push, a user no longer has to manually download and install the agent on a Windows system before adding it as a client on our system. It is a Windows-only feature, and supported Windows versions are Windows XP Pro 64bit/2003 32/64bit and up. (note: this feature is not available on free edition virtual appliances).
In its underlying implementation, Agent Push is performed using the winexe utility. The utility invokes the Windows installer command msiexec, accessing the agent files that have been made accessible to the prospective client through a samba share on the backup system called the windows_agents share.
Alternatively, consider using Group Policy to install and update agent software.
How to install or update the Unitrends agent using Group Policy
The following are required for the Agent Push feature:
• For Windows Vista and later, go to the Network and Sharing Center and make sure File and Printer Sharing is On for the current network profile.
• In Windows Vista and later, if errors persist when adding the client, it is likely related to User Access Control (UAC) remote access restrictions. If the errors persist, the UAC policy will need to be changed. On systems with UAC enabled, one of the following must apply:
- The client trust credentials entered on the Unitrends Client setup page are for a "domain administrator" account.
- The client trust credentials entered on the Unitrends Client setup page are for the systems local 'Administrator' account. Being a different member of the Administrators group is not sufficient, it must be the built-in account to bypass UAC. If the local administrator account is disabled, enable it by executing the following in an elevated command prompt "net user administrator /active:yes"
- If you would like to use a local administrator that is not the 'Administrator' account ensure the Registry DWORD key LocalAccountTokenFilterPolicy exists in the path of HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System and the values is set to 1. For more on this UAC setting, see this link: http://support.microsoft.com/kb/951016.
- The protect server and the Unitrends system must run the same SMB version. To enable SMB2 on the Unitrends system, follow How Unitrends supports SMBv2. Alternately, the protected asset must support SMB1.
• Workstation and Server services are running and set to automatic startup.
• For Windows XP Pro 64bit and 2003, make sure that the network adapter itself has File and Printer Sharing for Windows Networks checked (this is almost always the case, but good to double-check in case an error is seen). To verify, select Control Panel > Network and Sharing Center > Change Adapter Settings, then right-click the adapter, select Properties and check File and Printer Sharing for Microsoft Networks.
• For Windows XP, turn off Simple Sharing. Select Control Panel > Folder Options > View and uncheck Use Simple File Sharing
• Verify Remote IPC and Remote Admin shares are enabled. These shares should be enabled with File and Printer Sharing, but verifying is a good idea if you’re still having trouble. To verify, issue the following command from an elevated command prompt and check the output for ADMIN$ and IPC$: net share
• Firewall rules must allow inbound and outbound traffic between the backup system and Windows client. Default Windows firewall rules limit many services to the subnet. If the backup system is outside the client subnet, modify Firewall Printer and File Sharing settings (TCP ports 139 and 445) to allow communication between the systems.
Installation errors for winexe and msiexec, as well as other related information, are logged in the Agent Push log at /usr/bp/logs.dir/cmc_AgentPush.log.
Agent Push relies on two entries in Samba’s configuration file: /etc/samba/smb.conf. If the following message appears and all other prerequisites have been met, ensure that samba.conf contains the share entries noted below.
Prereq output file /backups/samba/[client].xml is missing.
Either execution succeeded and there was an error writing or reading the log
file, or this is an unknown error. Script output: …
read only = yes
guest ok = yes
browseable = no
writable = no
guest ok = yes
The following script can be run to add the entries.
If samba.conf is edited, it must be reloaded before the changes take effect. Use the following command to reload the configuration file.
The script will have changed the conf file if either of the following output messages are displayed:
AgentUpgradeSambaInsert: Adding windows_agents entry to smb.conf
Windows Group Policy and Samba share access
Agent Push requires communication between client systems and the Unitrends Samba share. To test access to the Samba share, on the client system open Windows Explorer and enter \\IPADDRESS\windows_agents where IPADDRESS is the Unitrends appliances IP address. If agent msi files are not visible the following policy settings are known to cause problems:
Microsoft network server: Digitally sign (always) – “Disabled” recommended
Microsoft network client: Digitally sign (always) – “Disabled” recommended
Network security: LAN Manager authentication level – “Send NTLMv2 response only” recommended
On any given Windows machine the presently applied policies can be seen by running gpedit.msc and drilling down into the following path: Local Computer Policy → Computer Configuration → Windows Settings → Security Settings → Local Policies → Security Options. If the policies are not aligned with the above recommendations (note the defaults with right-click → Properties → Explain when Not Defined is shown) retry after adjusting the local/domain policy and rebooting.
Multiple Network Cards (Release 9.1.0 and newer)
If the Unitrends system has multiple network cards Agent Push will try to use eth0 by default. To force Agent Push to use a different interface, in the Unitrends web UI go to Configure → Appliances → Edit→ Advanced → General Configuration page, and scroll down to the “Configuration Options” section. Set the value for “PushServer” to the IPv4 address of the Ethernet interface Agent Push should communicate over.
Windows Script Host or cscript Issues
The Unitrends prerequisite script used to verify a system is push compatible is executed with Microsofts cscript utility. cscript can be enabled or disabled at a user or system level. If not enabled the following error will appear when pushing:
"Windows Script Host (cscript) does not have permission to run on the client system."
To resolve this issue check the following locations in the client system registry:
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows Script Host\Settings\
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Script Host\Settings\
Ensure the "Enabled" dword32 key exists and its value is 1. The HKEY_CURRENT_USER entry must correspond to the account which matches the push credentials.
It may be necessary to log in to the client system as the push user for these settings to apply.
Release 10.2.0 adds the ability to integrate with an environment where SMB 1.0 is disabled.
To configure your appliance for SMB2 see this KB here.
To configure your Windows systems see Microsoft's article here.
Configuring for SMB2 will prevent pushing to SMB1 only OSs (XP/2003). Additionally pushing to Windows Vista and Windows 2008 (non-R2) is not supported in the SMB2 only configuration.
Windows 2019 - Windows 2019 ships with SMBv1 disabled by default. It is recommended to enable SMBv2 mode on Unitrends appliances to support Agent Push with 2019. If this is not possible due to legacy systems in your environment, SMBv1 can be re-enabled by following the instructions here.