- Overview
- Reference Guide
- Setup & Architecture
- Release Notes
- Workflow
- API Reference
- Integration Guide
- Discovery Agent Setup Guide
F5 Troubleshooting
Installation and Registration Errors
- The service fails to start with Service Control Manager error 1069 (“The service did not start due to a logon failure”). The service account needs the local rights Log on as a service and Log on as a batch job. To check, run secpol.msc on the agent host, go to Security Settings > Local Policies > User Rights Assignment, and confirm the account is listed in both policies. On a domain-joined machine, these rights may be enforced by Group Policy; check with your Active Directory team before changing anything.
- The agent exits with CERTSECURE.HOSTNAME_OR_IP is not configured in conf.ini. The backend address is empty. Set HOSTNAME_OR_IP under [CERTSECURE] and start the service again.
- Registration reports F5 Orchestrator already configured. Only one F5 Orchestrator can be registered per environment. Delete the existing F5 Orchestrator from the Load Balancers tab first if you need to register a new installation. Deleting it removes every device onboarded under it, with its profiles.
- Registration fails with a timeout, a connection error, or an HTTP error. Confirm that HOSTNAME_OR_IP is the address used to reach the CertSecure UI, that the host can reach the backend over HTTPS, and that the registration token is new and unused. Generate a fresh token if in doubt.
- The service stops right after it starts. The agent exits if it is not registered. Run EC_F5_RA.exe debug as the service account and complete the registration.
- The F5 account does not have sufficient rights. tmsh commands fail with a permission or authorization error. Confirm that the account has administrator-level rights and Advanced shell (bash) access, as described in F5 Requirements.
Connectivity Errors
The F5 Orchestrator host must reach the CertSecure backend and each F5 management address on the right ports.
| What | Port |
|---|---|
| SSH from the agent host to the F5 management address | TCP 22 |
| HTTPS from the agent host to the CertSecure backend | The port the backend runs on |
Run these commands from the agent host.
-
Port only. Confirms that the network path is open, nothing more:
Test-NetConnection -ComputerName <f5-management-address> -Port 22 -
SSH itself. Confirms that a real login works with the account you onboarded, not just the port:
ssh <username>@<f5-management-address>
Good to know:
If the SSH login succeeds but the terminal shows the TMOS shell (tmsh) instead of bash, change the account’s terminal access to Advanced shell on the F5.
Sync Errors
A sync that fails, or completes with issues, shows the reason in the Details column of its task. The most common messages are listed below.
| Message in Details | Likely cause | What to do |
|---|---|---|
| SSH account's login shell is not bash | The account's terminal access on the F5 is tmsh. | Set the account's terminal access to Advanced shell on the F5, and choose Request Sync. |
| SSH auth failed for '<user>' on <host> | The username or password stored for the device is wrong. | Right-click the device, choose Edit Details, and enter the correct password. A sync starts on its own. |
| F5 unreachable at <host> or SSH timed out talking to <host> | The F5 management address is not reachable from the agent host on TCP 22. | Check routing and firewall rules, and run the connectivity commands above. |
| password decrypt failed | The device password was stored for a previous registration of the agent. | Re-enter the password with Edit Details. Passwords are encrypted for the specific agent that stored them. |
| ... listing failed or could not parse tmsh output | The F5 rejected a read command or returned output that could not be read. | Read the message that follows, and confirm that the account can read profiles and certificates in all partitions. |
| No progress from F5 Orchestrator for 30 minutes | The F5 Orchestrator stopped or lost its connection during the sync. | Check that the service is running and the Status is Online, and then choose Request Sync. |
| Certificate object <path> not found on the F5 | A profile uses a certificate object that the F5 did not list. | Check the profile and its certificate on the F5. |
| Profile not found on the F5 (still managed in CertSecure) | A managed profile, or its certificate-key-chain entry, was deleted or renamed on the F5. | Restore it on the F5, or choose Move to Staged to remove it from CertSecure. |
Renewal Errors
Check the task history of the device first: right-click the device and choose View Tasks. The Details column carries the failure reason, which starts with the step that failed. The most common messages are listed below.
| Message in Details | Likely cause | What to do |
|---|---|---|
| Could not connect to the F5 - SSH auth failed / F5 unreachable / password decrypt failed | The same causes as for a sync. | See Sync Errors above, and then renew again. |
| Bound certificate changed on the F5 since the last sync | The certificate bound to the profile, the profile, or its certificate-key-chain entry was changed on the F5 after the last sync. | A sync starts on its own. Check the profile once the sync has finished, and renew again if needed. |
| Profile is owned by an iApp application service ... | The profile belongs to an iApp. | Renew the certificate through the iApp. |
| Details of the bound certificate are unavailable - run a sync | CertSecure has no certificate details for the profile. | Choose Request Sync, and then renew again. |
| CSR generation on the F5 failed - tmsh could not create the key and CSR: ... | The F5 rejected the request, for example because of insufficient rights or an invalid subject value. | Read the message that follows, and confirm that the account has administrator-level rights in the profile's partition. |
| Not renewed - the bound certificate has no common name (CN) ... / key type ... is not supported | The current certificate cannot be used as the model for the new CSR. | Replace the certificate on the F5 by hand, or push a new certificate and bind it. |
| CA did not issue a certificate - CertSecure rejected the request: ... | The CA or template is not available, the DigiCert details are missing, or the key length is below the template's minimum key size. | Check the CA connection and the template in CertSecure, and the profile's settings with Update Profile. |
| CA did not issue a certificate - <CA> did not issue the certificate within <n> minutes | The CA is slow, the request is waiting for approval, or the CA failed to issue it. | Check the request on the CA. Raise CA_ISSUE_TIMEOUT_MINUTES if the CA is slow, and renew again. The new key was already removed from the F5. |
| Certificate was issued but could not be installed on the F5 - tmsh could not install the certificate: ... | The F5 could not install the certificate. | Read the message that follows. The new objects were removed; renew again. |
| Certificate installed but binding it to the profile failed - tmsh could not bind the certificate: ... | The F5 rejected the change to the profile. | Read the message that follows. The profile still uses its previous certificate, and the new objects were removed. |
| Profile bound but saving the F5 configuration failed | The profile was updated in the running configuration, but the save did not complete. | Log in to the F5 and run tmsh save sys config. |
| Automated renewal is on for this profile - turn automation off to renew it manually or schedule a renewal | Renew was used on a profile with Automation on. | Let automation renew the profile, or turn Automation off with Update Profile first. |
| A renewal is already queued or running for this profile | Another task holds the profile. | Wait for that task to finish. View Tasks shows it. |
| Partition not found on the F5 - partition /<name> does not exist on the F5 | A push names a partition that is not on the device. | Push to an existing partition. |
Tasks That Do Not Progress
- A task stays Pending. The F5 Orchestrator is offline, or the device is busy. Check that the Status is Online and that the EC_F5_Orchestrator service is running. Each device runs one job at a time, and a renewal waits while a sync of the same device is queued or running.
- A scheduled renewal has not started. It starts at its scheduled time, never earlier.
- A task shows Waiting for <CA> to issue the certificate. The CA has not issued the certificate yet; the number in brackets is how many seconds the F5 Orchestrator has been waiting. After CA_ISSUE_TIMEOUT_MINUTES, the renewal of that profile fails.
- A task stays Processing after the service was stopped. The backend fails a renewal after 60 minutes, and a sync after 30 minutes, without progress. After a failed renewal it also syncs the device to record what is on the F5. Renew again if needed.
- An automated renewal did not run. Automated renewals are queued only at the end of a successful sync, for managed profiles with Automation on whose certificate expires within RENEW_IF_EXPIRING_IN days. A profile is skipped while another task holds it, while a certificate pushed with Renew and Push is waiting to be bound, and until 6 hours after a failed renewal.
- The scheduled time is rejected. A scheduled renewal must be at least 30 minutes from now.
- Move to Staged is refused. A renewal of the profile is queued, scheduled, or running; the message names the task. Try again after it has finished.
Agent Log
- The agent writes a detailed log of every action it takes, successful or not, to
F5 Orchestrator.login the folder set by [LOGGING] LOGDIR in conf.ini (by default the logs folder inside the agent folder). - The file rotates automatically once it passes MAXSIZE_BYTES, and NUM_BACKUP rotated files are kept.
- When the task history does not give enough detail to explain a failure, this file is the next place to look.