Troubleshoot ePolicy Orchestrator Agent Handler certificate regeneration issues
Technical Articles ID:
KB90821
Last Modified: 2023-07-26 08:38:42 Etc/GMT
Environment
ePolicy Orchestrator (ePO) 5.10.x
Summary
This article helps you troubleshoot several issues commonly faced when you try to regenerate Agent Handler certificates.
There are several issues that can cause regeneration of ePO Agent Handler certificates to fail. The solutions below describe the symptoms, causes, and resolutions.
Solution
1
| Symptom |
The ahsetup_<ePO_server_name>.log records entries similar to the following:
AHSETUP Creating Agent Handler Certs.
AHSETUP Using existing certificate files found in C:\Program Files (x86)\McAfee\ePolicy Orchestrator\Apache2\conf\ssl.crt
AHSETUP Adding begin/end pair to file 'C:\Program Files (x86)\McAfee\ePolicy Orchestrator\Apache2\conf\ssl.crt\ahCert.crt'
AHSETUP File does not need begin/end fixup
AHSETUP Adding begin/end pair to file 'C:\Program Files (x86)\McAfee\ePolicy Orchestrator\Apache2\conf\ssl.crt\ahpriv.key'
AHSETUP File does not need begin/end fixup
AHSETUP Existing Certificates will be used, for complete regeneration delete the files and try again
|
| Cause |
The ssl.crt folder is not empty.
If the ssl.crt folder isn't empty, new certificates aren't created; existing certificates are reused. |
| Solution |
Make sure that the ssl.crt folder is empty, and then run the command again. |
Solution
2
| Symptom |
The error below is displayed:
AHStup error
Failed to connect to the ePO server '<ePO_Server_Name>:<port>'.
The ahsetup_<ePO_server_name>.log records entries similar to the following:
AHSETUP Creating Agent Handler Certs.
AHSETUP Checking to see if the ePO server (ePOServer:8443) is available. We will try 5 times.
MCUPLOAD SecureHttp.cpp(694): Failed to send HTTP request to server ePO59-1 for command name epo.command.isAdmin on port 8443. (error=12029)
MCUPLOAD SecureHttp.cpp(883): Failed to process the secure communication request (error=12029)
MCUPLOAD SecureHttp.cpp(694): Failed to send HTTP request to server ePO59-1 for command name epo.command.isAdmin on port 8443. (error=12029)
MCUPLOAD SecureHttp.cpp(883): Failed to process the secure communication request (error=12029)
MCUPLOAD SecureHttp.cpp(694): Failed to send HTTP request to server ePO59-1 for command name epo.command.isAdmin on port 8443. (error=12029)
MCUPLOAD SecureHttp.cpp(883): Failed to process the secure communication request (error=12029)
MCUPLOAD SecureHttp.cpp(694): Failed to send HTTP request to server ePO59-1 for command name epo.command.isAdmin on port 8443. (error=12029)
MCUPLOAD SecureHttp.cpp(883): Failed to process the secure communication request (error=12029)
MCUPLOAD SecureHttp.cpp(694): Failed to send HTTP request to server ePO59-1 for command name epo.command.isAdmin on port 8443. (error=12029)
MCUPLOAD SecureHttp.cpp(883): Failed to process the secure communication request (error=12029)
AHSETUP The Agent Handler failed to connect to the ePO server.
AHSETUP certificates.cpp(768): Failed to connect to the ePO server 'ePOServer:8443'
|
| Cause |
The ePO Application Server service isn't running or a wrong port is specified in the regeneration command.
The regeneration command must access the ePO Application Server service on the console port, which is 8443 by default. If the service isn't started, the process fails when the port specified in the command isn't the correct port. |
| Solution |
Ensure the following:
- The ePO Application Server service is started.
- You can log on the console on the correct port.
- The correct port is specified in the regeneration command.
|
Solution
3
| Symptom |
The ahsetup_<ePO_server_name>.log records entries similar to the following:
AHSETUP Creating Agent Handler Certs.
AHSETUP Checking to see if the ePO server (ePOServer:8443) is available. We will try 5 times.
MCUPLOAD SecureHttp.cpp(863): Failed to query auth schemes (error=4317)
..
..
MCUPLOAD SecureHttp.cpp(863): Failed to query auth schemes (error=4317)
AHSETUP The Agent Handler failed to connect to the ePO server.
AHSETUP certificates.cpp(768): Failed to connect to the ePO server 'ePOServer:8443'
|
| Cause |
Incorrect credentials, either username or password, are specified in the regeneration command. |
| Solution |
Make sure that correct credentials are specified in the command parameters. |
Solution
4
| Symptom |
The error below is displayed:
AHStup error
Error 0: Authorization failed.
The ahsetup_<ePO_server_name>.log records entries similar to the following:
AHSETUP Creating Agent Handler Certs.
AHSETUP Checking to see if the ePO server (ePO59-1:8443) is available. We will try 5 times.
AHSETUP The Agent Handler successfully connected to the ePO server.
AHSETUP certificates.cpp(880): Received an unexpected error from the server 'ePO59-1': Error 0 :
AHSETUP Authorization failed
AHSETUP certificates.cpp(538): Received an unexpected error from the server 'ePO59-1': Error 0 :
AHSETUP Authorization failed |
|
Cause
|
A non-administrator user account is used in the regeneration command.
If the account used in the command isn't an ePO administrator, the command fails. |
| Solution |
Make sure that you're using an account with ePO administrator rights. |
Solution
5
| Symptom |
The exact error that you see depends on the characters in use:
If the password contains the < character, the command fails with the message below:
The system cannot find the file specified.
If the password contains the > or & character, the following is displayed:
HSETUP is displayed,
Wrong number of arguments
|
| Cause |
A username or password contains reserved characters that cause the command to fail.
As stated in step 3 of the regeneration process documented in KB90760 - How to regenerate the certificates used by the ePO server service, there are certain characters that are valid in a password. But if they're present, they cause the regeneration command to fail.
This is because the characters are reserved characters that have special meanings for the command shell. Examples of such characters are &, <, and >. |
| Solution |
The preferred solution is to do either of the following:
- Change the ePO administrator's password to a simple alphanumeric string.
- Create a new temporary administrator account with a simple password, and use these credentials to perform the regeneration.
If this solution isn't possible, you can escape the reserved characters in the command. Prefix each reserved character with the caret symbol ^.
Example: If the ePO administrator account is called admin, and the password is P<assw>ord, you can specify the password parameter as P^<assw^>ord. |
Solution
6
| Symptom |
The error below is displayed:
RunDLL
There was a problem starting ahsetup.dll. The specified module could not be found.
|
| Cause |
The command has been run from the wrong folder, and is unable to locate ahsetup.dll. |
| Solution |
Make sure that you're running the command from the correct folder. Run from the root ePO installation folder, where ahsetup.dll is located. The default location is as follows:
C:\Program Files (x86)\McAfee\ePolicy Orchestrator
|
Solution
7
| Symptom |
The error below is displayed:
RunDLL
There was a problem starting ahsetup.dll. The specified module could not be found.
|
| Cause |
System policy prevents DLLs from loading.
The regeneration command fails if the CWDIllegalInDllSearch registry value has been set to remove the current working folder from the default DLL search order.
For more details about the CWDIllegalInDllSearch setting, see this Microsoft documentation.
|
| Solution |
Set the data for the CWDIllegalInDllSearch registry value to 0 and restart the ePO server.
Once restarted, run the regeneration command again.
CAUTION: This article contains information about opening or modifying the registry.
- The following information is intended for System Administrators. Registry modifications are irreversible and could cause system failure if done incorrectly.
- Before proceeding, Technical Support strongly recommends that you back up your registry and understand the restore process. For more information, see the Microsoft Windows registry information for advanced users article.
- Do not run a REG file that is not confirmed to be a genuine registry import file.
|
|
