The most common problems encountered with the Agent occur during installation. Follow the troubleshooting list in order and then try to reinstall the Agent according to the instructions in the following section. Tips for specific circumstances are in the final section.
Check for each of the following. If the client does not have or has not done one of these things, correct it and then reinstall the Agent following these steps.
- Check that the customers installed as an administrator.
If the client says yes, ask them if they have done anything to increase the security of their operating system. Hardening is a commonly used process that increases the security of a system by removing access to certain critical features. This can cause problems when installing the agent, as a hardened system may prevent the agent from running as a system service. If the client has hardened their system, or if they do not know, ask them to consult with their IT support to ensure the agent has all administrator privileges when it runs. You should not need to go into detail on this; the process they use to secure their system is likely to be specific to their environment, and as such it is their responsibility to sort out any permission issues themselves.
- Check that the customer has Internet connectivity.
The client must be able to contact the following servers:
- TrustKeeper Agent registration server, https://agentregistration.trustwave.com
- TrustKeeper Agent update server, https://agentupdate.trustwave.com
- TrustKeeper Agent message server, https://agentmessage.trustwave.com
- TrustKeeper Agent antivirus server, https://agent-av-mirror.trustwave.com
- TrustKeeper OCSP server, http://ocsp.trustwave.com
- TrustKeeper CRL server, http://crl.trustwave.com
- TrustKeeper CRL server, http://crl.securetrust.com
If the client has a firewall or access control list place on their network, you may need to add these servers to the client’s white list.
- Check the version of the installer.
The most recent version is listed in the Version History tab. If the client is attempting to install with a prior version, be sure they are using the most recent installer available to them through their account. If this is an MSS customer, verify with Provisioning that there is not a later version of the installer available for the client–files uploaded to a client's documents area are not updated automatically and their current installer may be out of date.
To check the version of the client's installer download a copy of it and right-click, selecting Properties from the menu. In the Details tab, you will see the version number listed.
If the client has already installed the agent but was unable to register, you can have them run CSI and then view the version by opening the FileVersions.txt file. You'll see something like this:
"VersionInfo: BUILD=3.0.734,DATE=2014-01-16_22-00-41,PROJ=tkagent-greatwhite-windows-release,TYPE=Release".
- Check if this client active in TrustKeeper Klassic.
If they are, they may need to have their Agent population migrated to the new portal. This process takes about a week and is done by the agent development team in conjunction with IT.
- If the client is seeing an error message when trying to run part of the agent, such as an update or report, consult the list of curl error codes. For HTTP status errors, see this list.
- If you cannot solve the problem with the above steps, escalate the issue to the Agent team by sending an e-mail to Agent@trustwave.com or create a new ticket in the Agent Support RT queue.
If you are replacing an existing agent, fully remove (uninstall) the agent before installing the new one.
- Run the Agent installer as an administrator to remove the TKA files that were just installed.
- Run the Agent installer as an administrator to install the Agent.
An access control list is a list of rules applied by a router or server that govern access to and from specified ports and IP addresses. Clients who do not have a premium router or network security setup generally do not have ACLs. (This means that the average L4 caller, for whom Windows Firewall is the height of security, will not have an ACL).
The Agent needs to connect to seven servers to register and function. If the client blocks access to any of these servers, the Agent will either fail to install or fail to run after installation. Make sure they have whitelisted:
- agentregistration.trustwave.com
- agentupdate.trustwave.com
- agentmessage.trustwave.com
- agent-av-mirror.trustwave.com
- crl.trustwave.com
- crl.securetrust.com
- ocsp.trustwave.com
Note: Some of these servers are not hosted by Trustwave, but are instead hosted by a company called Akamai. To increase availability to clients, these sites may resolve to any one of thousands of IP addresses. As such, the client must whitelist Agent servers using an application layer tool; that is, they need to whitelist using the text domain (for example, "trustwave.com") instead of the IP address (for example, "127.0.0.1"), or the Agent will not be able to reliably reach our servers.
Antivirus detects the Agent
Sometimes, antivirus software will detect the Agent's activity as a malicious intrusion since TKA scans many system critical files. If this happens, the client might see an alert in their antivirus software indicating that the Agent has been quarantined. If so, the client must release the Agent from quarantine and add it to their antivirus software's exclusion list. The process for adding a file to the exclusion list varies from product to product, so it is best to let the client figure it out from there.
If an agent's registration fails, check your firewall settings and then re-run the registration. You can do this without reinstalling the agent by using the TkAgentRegistrant utility. TkSvc.xml must first be present on the host before registration. The TkAgentRegistrant utility requires administrator privileges. To register an agent, use the command on 64-bit machines:
"C:\Program Files (x86)\Trustwave\Agent\"TkAgentRegistrant.exe --retry_registration
or this command on 32-bit machines:
"C:\Program Files\Trustwave\Agent\"TkAgentRegistrant.exe --retry_registration
Installations with GPO (Group Policy Object) Present
GPO (Group Policy Object) is used by system administrators to remote install software on their network(s).
- Elevate privileges on the target machine(s) to administrator level. If the client needs a tool to elevate privileges, this may be helpful http://code.kliu.org/misc/elevate/.
-
Clients must contact Trustwave Support to get the MSI installer which is not publicly available.
-
To install the MSI, pass along a command line parameter that includes their registration code along with silent install switches. For instance:
msiexec /I "C:\[installation directory]\TrustKeeper Agent.msi" TKREGCODE={[code]} /quiet /qn
NOTE: The MSI cannot be used to later uninstall the TrustKeeper Agent. You must either use the standard Add/Remove Programs dialog to remove the Agent or trigger an uninstall from the portal in the My Agents application.
Invalid Installer
If an invalid installer is downloaded or the installer’s hash is wrong, some part of the installer is missing. Download the installer again.
Linux
When installing on Linux, only use the 32-bit installer on 32-bit systems and the 64-bit installer on 64-bit systems.
The 64-bit Agent installer for Linux fails to install on Suse Linux 10 x 64. Check if the 32-bit libraries have installed. If they have and you still get this message, try installing with the 32-bit installer instead of the 64-bit installer; that should work.
Satellite Internet Connections
Some satellite providers (notably HughesNet) provide 'SSL enhancement' (most often an SSL proxy) services to their business clients. These products work by detecting any outgoing SSL requests and forwarding them to a dedicated SSL server owned by the ISP. To register the agent, any SSL proxy service must be disabled. This is because the connection forwarding process replaces the agent's SSL certificate with one signed by the ISP, which causes TrustKeeper to reject the connection as invalid. Once an agent has registered, clients can re-activate the SSL enhancement service and the agent will function as normal.
When an SSL proxy is causing problems, the client will get an error during agent installation "CURL CODE 60". This means that we were unable to verify the agent's connection request with the provided SSL certificate.
So far this has been documented with HughesNet, who call their SSL proxy "Turbo Page". Clients will need to contact HughesNet directly to disable this feature.
If the client is unsure whether their problem is caused by an SSL proxy, they can run the following OpenSSL command from the command line to verify that the proper certificate chain is in use:
To verifying a SSL Proxy Error
Issue the command on a 64-bit machine:
"C:\Program Files (x86)\Trustwave\Agent\"openssl s_client -CAfile C:\ProgramData\Trustwave\Agent\certs\tkagent_CA.pem -connect agentregistration.trustwave.com:443 -verify 5
or on a 32-bit machine:
"C:\Program Files\Trustwave\Agent\"openssl s_client -CAfile C:\ProgramData\Trustwave\Agent\certs\tkagent_CA.pem -connect agentregistration.trustwave.com:443 -verify 5
The correct certificate chain is
s:/CN=agentregistration.trustwave.com/O=Trustwave Holdings, Inc./L=Chicago/ST=Illinois/C=US i:/C=US/ST=Illinois/L=Chicago/O=Trustwave Holdings, Inc./CN=Trustwave Organization Validation CA, Level 2/emailAddress=ca@trustwave.com
s:/C=US/ST=Illinois/L=Chicago/O=Trustwave Holdings, Inc./CN=Trustwave Organization Validation CA, Level 2/emailAddress=ca@trustwave.com i:/C=US/O=SecureTrust Corporation/CN=SecureTrust CA
Any certificate chain that shows a different signing organization is proof positive of an SSL proxy.
