> For the complete documentation index, see [llms.txt](https://docs.certinext.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.certinext.io/documentation/troubleshooting-and-faqs/bot-connectivity-issues.md).

# Bot Connectivity Issues

Use this page when a CERTInext Bot stops reporting to CERTInext, or when it reports but cannot reach the servers and platforms it manages. Work through the steps in order. Each step tells you what to check and what the result means.

The full list of host names, ports, proxy settings and TLS inspection settings is in [Network and Firewall Requirements](https://docs.certinext.io/documentation/deployment-and-operations/network-and-firewall-requirements). This page shows how to test them.

***

### Common symptoms <a href="#common-symptoms" id="common-symptoms"></a>

* The Bot shows **Stopped** on the Bots page.
* **Last Bot Update** is not refreshing. A Bot reports at its reporting interval, which is one minute by default.
* A provisioning target shows **Bot Offline - Deployment Pending**.
* Scans do not start, or deployments stay in **Deployment In Progress**.
* **Test Connection** fails for a server or platform.
* The Bot logs show timeout, connection, proxy or certificate errors.

### Step 1: Check the Bot in the console <a href="#step-1-check-the-bot-in-the-console" id="step-1-check-the-bot-in-the-console"></a>

Open the Bots page and check the **Status** of the Bot.

| Status                | What it means                                                                         | What to do                                                                                |
| --------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Active                | The Bot is reporting                                                                  | If tasks still fail, go to Step 3 and then Step 6                                         |
| Stopped               | The last report is older than the reporting interval plus two minutes                 | Go to Step 2                                                                              |
| Inactive              | An administrator deactivated the Bot                                                  | Reactivate it if it should run. Allow up to 15 minutes for the status to return to Active |
| Configuration Pending | The Bot has registered but is not yet configured in the console                       | Finish the Bot configuration in the console                                               |
| Activation Pending    | The configuration is saved and CERTInext is waiting for the first report from the Bot | Check that the Bot service is running (Step 3) and test the connection (Step 2)           |

Also check that **Bot Version** is current.

### Step 2: Test the connection to CERTInext <a href="#step-2-test-the-connection-to-certinext" id="step-2-test-the-connection-to-certinext"></a>

The Bot connects out to CERTInext on HTTPS, TCP 443. No inbound rule to the Bot host is needed. Test from the Bot host itself, using the host name for your deployment.

| Deployment   | Bot host name                                                                               |
| ------------ | ------------------------------------------------------------------------------------------- |
| US region    | `us-discovery-api.certinext.io`                                                             |
| India region | `api-discovery.certinext.io`                                                                |
| Sandbox      | `sandbox-us-discovery.certinext.io`                                                         |
| On-premises  | The Bot host name agreed during installation, for example `discovery.certinext.example.com` |

On a Windows Bot host, in PowerShell:

```
curl.exe -sS -o NUL -w "%{http_code}" https://us-discovery-api.certinext.io/
```

Type `curl.exe`, not `curl`. In Windows PowerShell, `curl` runs a different command and the test fails. Windows Server 2016 has no curl.exe, so use this instead:

```
Invoke-WebRequest -UseBasicParsing https://us-discovery-api.certinext.io/ | Select-Object StatusCode
```

On a Linux Bot host:

```
curl -sS -o /dev/null -w "%{http_code}\n" https://us-discovery-api.certinext.io/
```

If the Bot uses a proxy, test through the proxy. Add `-x http://proxy.example.com:8080` to the curl command, or `-Proxy http://proxy.example.com:8080` to Invoke-WebRequest. A direct test from a host that may only use the proxy fails even when the Bot is set up correctly.

If this Bot relays through another Bot, test TCP 5777 to that Bot host instead, for example `Test-NetConnection relaybot.example.com -Port 5777`.

| Result                        | What it means                                                                              | What to do                                                                                                                                                                                                                   |
| ----------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`                         | The network path to CERTInext works                                                        | Go to Step 3                                                                                                                                                                                                                 |
| Host name not resolved        | DNS on the Bot host cannot resolve the name                                                | Check the DNS servers set on the Bot host. Where internal and public DNS differ, check the answer with `nslookup`                                                                                                            |
| Timeout or connection refused | A firewall rule is missing, or the host must use a proxy and the test did not              | Allow the host name on TCP 443 from the Bot host, or repeat the test through the proxy                                                                                                                                       |
| `407`                         | The proxy requires authentication                                                          | Allow the Bot host address on the proxy for the destinations it needs, or use Digest authentication. Basic authentication is supported for the connection to CERTInext only. For NTLM or Kerberos proxies, use an allow rule |
| Certificate error             | TLS inspection is replacing the CERTInext certificate with one the Bot host does not trust | Trust the inspection CA on the Bot host, or exclude the host name from inspection                                                                                                                                            |

A Bot host must have a route to CERTInext, directly or through a proxy. For networks with no internet route, use an on-premises deployment or place the Bot host in a zone that can reach CERTInext.

### Step 3: Check the Bot host <a href="#step-3-check-the-bot-host" id="step-3-check-the-bot-host"></a>

* The Bot service is running. On Windows, run `Get-Service CERTInextBot` (display name CERTInext Bot Service). On Linux, run `systemctl status certbotd`.
* The clock is in sync with NTP. If the Bot shows Active but scan results and deployments never arrive, check the clock first. A host whose clock is out of sync can keep reporting while its results are rejected.
* The disk has free space for logs and the local database.
* Endpoint protection is not blocking or quarantining files in the Bot program folder or data folder.

### Step 4: Check the installation token <a href="#step-4-check-the-installation-token" id="step-4-check-the-installation-token"></a>

Each installation token has a **Max Enrollments (Bot Limit)**. When the limit is reached, no further Bot can register with that token. Generate a new token, or raise the limit, and set it to the number of Bots you plan to install with the token. If an installation was rejected because the limit was reached, allow up to 15 minutes after you raise the limit before you retry.

Reinstalling the Bot on the same host, under the same account, returns the same Bot with its name and history, unless the Bot was deleted in the console.

Do not clone a virtual machine image that already has the Bot installed. Install the Bot on each host after cloning.

### Step 5: Check the proxy and TLS inspection <a href="#step-5-check-the-proxy-and-tls-inspection" id="step-5-check-the-proxy-and-tls-inspection"></a>

If the Bot connects through a proxy:

* The proxy is an HTTP proxy that allows CONNECT to TCP 443. SOCKS proxies are not supported.
* Idle and response timeouts are at least 180 seconds.
* On Windows the proxy is set during installation. On Linux it is set in the Bot configuration after installation. Restart the Bot service after any proxy change.
* If TLS inspection is on, the inspection CA is trusted on the Bot host. On Windows, add it to the Local Computer Trusted Root store. On Linux, add it to the Bot's Java trust store again after each install and upgrade.

The full proxy and inspection settings are in Section 2.4 of [Network and Firewall Requirements](https://docs.certinext.io/documentation/deployment-and-operations/network-and-firewall-requirements).

### Step 6: Check connections to targets <a href="#step-6-check-connections-to-targets" id="step-6-check-connections-to-targets"></a>

If the Bot is active but scans, deployments or test connections fail, the problem is usually between the Bot host and the target. Run **Test Connection** in the console first, then test the port from the Bot host.

On Windows:

```
Test-NetConnection server01.example.com -Port 5986
```

On Linux:

```
nc -vz server01.example.com 22
```

If `nc` is not installed, which is common on minimal RHEL, Rocky, AlmaLinux and Debian hosts, use:

```
timeout 5 bash -c '</dev/tcp/server01.example.com/22' && echo open
```

| Target                                     | Port to test                              |
| ------------------------------------------ | ----------------------------------------- |
| Linux and Unix servers                     | SSH, TCP 22                               |
| Windows servers                            | WinRM, TCP 5986 or 5985, and SMB, TCP 445 |
| F5 BIG-IP, NetScaler, FortiGate, Palo Alto | Management port, TCP 443 by default       |
| Kubernetes, OpenShift and AKS              | API server, TCP 443 or 6443               |
| Directory servers                          | LDAPS, TCP 636                            |
| Cloud and SaaS platforms                   | HTTPS, TCP 443, to the platform API       |

The full list is in Sections 2.2 and 2.3 of [Network and Firewall Requirements](https://docs.certinext.io/documentation/deployment-and-operations/network-and-firewall-requirements). Also check:

* The firewall on the target allows the Bot host address.
* The Bot host address is in the management access list of the appliance, and in the authorized IP ranges of AKS clusters.
* Cloud API credentials are not limited to source addresses that leave out the Bot host.
* The service account for the target has the rights listed in [CERTInext Bot Workflow](https://docs.certinext.io/documentation/automation-and-devops/certinext-bot-workflow).

**Windows targets.** The Bot signs in to WinRM with the user name and password set for the server in the console, using NTLM. Enter domain accounts in the `user@domain` form. If your policy restricts NTLM, allow it as an exception for connections from the Bot host to the target servers only, and keep it restricted elsewhere. The Bot uses WinRM over HTTPS when the WinRM port of the server is set to 5986. If no port is set it uses TCP 5985, so a server with only an HTTPS listener fails until 5986 is set. With the standard Bot configuration the Bot checks the WinRM listener certificate, so issue it from a CA the Bot host trusts.

**Linux targets.** If the port test passes but Test Connection fails, check that the account set for the server can sign in over SSH from the Bot host and has the rights listed in [CERTInext Bot Workflow](https://docs.certinext.io/documentation/automation-and-devops/certinext-bot-workflow).

### Step 7: Review the Bot logs <a href="#step-7-review-the-bot-logs" id="step-7-review-the-bot-logs"></a>

| Bot host                                     | Log folder                                   |
| -------------------------------------------- | -------------------------------------------- |
| Windows                                      | `C:\ProgramData\Certinext\CERTInextBot\logs` |
| Linux, installed from the DEB or RPM package | `/var/log/certbotd`                          |

The main files are `error.log` and `info.log`. Look for:

* Authentication errors, which point to the token (Step 4) or the clock (Step 3)
* Timeouts and connection errors, which point to the firewall or proxy (Steps 2 and 5)
* Certificate or trust errors, which point to TLS inspection (Step 5)
* Permission errors on a target, which point to the service account for that target (Step 6)

### Step 8: Restart, upgrade or reinstall the Bot <a href="#step-8-restart-upgrade-or-reinstall-the-bot" id="step-8-restart-upgrade-or-reinstall-the-bot"></a>

1. Restart the Bot service and check **Last Bot Update** again after two minutes.
2. If the Bot still does not connect, uninstall it and install it again with a current installation token. After any upgrade or reinstall, apply the standard Bot configuration in Section 2.2 of [Network and Firewall Requirements](https://docs.certinext.io/documentation/deployment-and-operations/network-and-firewall-requirements).
3. If the Bot host cannot download the installer, use the manual installation package. See [Bot Deployment and Management](https://docs.certinext.io/documentation/automation-and-devops/agent-deployment-and-management).

On Windows, run upgrades from an administrator session on the Bot host. The download uses the proxy settings of that session, not the Bot proxy.

On Linux, the Bot may register again after a package upgrade and returns as the same Bot. Keep the Max Enrollments limit of its installation token above the number of installed Bots until the upgrade is done.

### When to contact support <a href="#when-to-contact-support" id="when-to-contact-support"></a>

[Raise a support ticket](https://docs.certinext.io/documentation/support-and-resources/raising-a-support-ticket) and include:

* Bot name, host name and IP address
* **Last Bot Update** time, with the time zone
* The result of the test in Step 2
* The Bot log files from Step 7, with passwords, keys and tokens removed
* Whether a proxy or TLS inspection device sits between the Bot host and CERTInext

### Good practice <a href="#good-practice" id="good-practice"></a>

* Test the connection again after every firewall, proxy or inspection change.
* Keep the Bot version current.
* Place one Bot in each network zone whose targets cannot be reached from another zone.
* Deactivate Bots you no longer use.