Connectivity for Agent, Portal, and Elasticsearch

The Waratek Agent requires TCP/IP connectivity to both the Portal and Elasticsearch. The default ports are:

• Portal (SaaS): 443 (HTTPS)
• Portal Dedicated: 8443 (HTTPS) — customizable on Portal Dedicated deployments
• Elasticsearch: 9200 — customizable on Portal Dedicated deployments

Network troubleshooting between the Waratek Agent and the Portal, as well as Elasticsearch, can be a complex task as there are many factors that can impact the connection. Firewall settings can block connections, so ensure that the appropriate ports are open. You may also need to configure your firewall to allow traffic through specific ports or protocols. To troubleshoot, first check the network settings on the Waratek Agent and the Portal server, as well as Elasticsearch, to ensure that the IP addresses, FQDNs, and port numbers are all correct. If you are unsure about any of these settings, consult your network administrator for assistance.

Network-level diagnostics

Before looking at Agent-specific debug flags, verify basic network connectivity from the host where the Waratek Agent is running.

DNS resolution

Confirm the Portal and Elasticsearch hostnames resolve correctly:

nslookup <portal-host>

or for more detail (Linux):

dig <portal-host>

If DNS fails, check /etc/resolv.conf (Linux) or your OS DNS settings, and verify that the host can reach the configured DNS server. On Windows, review the active DNS configuration with:

Get-DnsClientServerAddress

Port connectivity

Verify the target port is reachable using nc (netcat) on Linux:

nc -zv <portal-host> 443

A successful result looks like:

Connection to <portal-host> 443 port [tcp/https] succeeded!

On Windows, use PowerShell's Test-NetConnection:

Test-NetConnection -ComputerName <portal-host> -Port 443

A successful result shows TcpTestSucceeded : True.

If neither tool is available, curl with a connection timeout works as well:

curl -v --connect-timeout 5 https://<portal-host>

TLS handshake verification

Use openssl to inspect the TLS connection and certificate chain independently of Java (Linux):

openssl s_client -connect <portal-host>:443 -servername <portal-host> </dev/null

Check the output for:

• Verify return code: 0 (ok) — the certificate chain is trusted.
• The subject and issuer lines match the expected Portal certificate.
• The protocol and cipher are acceptable (TLSv1.2 or TLSv1.3).

note

For Portal Dedicated deployments, the use of a wildcard SSL certificate (e.g. *.example.com) is supported. When a wildcard certificate is in use, the subject field will show the wildcard pattern rather than the exact hostname of the Portal Dedicated server.

On Windows where openssl is not installed, use PowerShell to test the TLS handshake:

$tcp = New-Object Net.Sockets.TcpClient("<portal-host>", 443)
$ssl = New-Object Net.Security.SslStream($tcp.GetStream())
$ssl.AuthenticateAsClient("<portal-host>")
$ssl.SslProtocol
$ssl.RemoteCertificate | Format-List Subject, Issuer, NotBefore, NotAfter
$ssl.Close(); $tcp.Close()

If the certificate verification fails, the host may be missing a required CA certificate in its trust store, or a network appliance (proxy, firewall) may be intercepting TLS traffic.

Java trust store (cacerts)

The JVM maintains its own CA trust store (cacerts), separate from the operating system's trust store. A common cause of curl succeeding while the Agent fails is a missing CA certificate in cacerts.

List the certificates in the Java trust store:

/path/to/java/bin/keytool -list -cacerts

On older JDKs that do not support the -cacerts flag, specify the path directly:

/path/to/java/bin/keytool -list -keystore /path/to/java/lib/security/cacerts

The default password is changeit.

To check whether a specific CA is present (for example, the Amazon Root CA used by the SaaS Portal):

/path/to/java/bin/keytool -list -cacerts | grep -i amazon

On Windows:

& "\path\to\java\bin\keytool" -list -cacerts | Select-String -Pattern "amazon"

If the required CA is missing, import it:

/path/to/java/bin/keytool -importcert -cacerts -alias <alias> -file <ca-cert.pem>

Proxy detection

In corporate environments, outbound HTTPS traffic may be routed through a proxy. If a proxy is required, the Agent's JVM must be configured to use it.

Check whether proxy environment variables are set on the host:

env | grep -i proxy

On Windows, check both environment variables and the system proxy configuration:

Get-ChildItem Env: | Where-Object { $_.Name -match "proxy" }

Get-ItemProperty "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings" | Select-Object ProxyEnable, ProxyServer

Common variables include http_proxy, https_proxy, and no_proxy. If a proxy is in use, pass the proxy settings to the JVM:

-Dhttps.proxyHost=<proxy-host> -Dhttps.proxyPort=<proxy-port>

See Force Portal communication to use Java proxy with UseJavaHttpProxy for how the Agent handles Java proxy properties.

System clock

TLS certificate validation depends on the system clock. If the clock is significantly skewed, certificates may appear expired or not yet valid, causing TLS handshakes to fail silently.

Verify the system time is correct:

date -u

Compare it against a reliable source (e.g. an NTP server). On Linux with timedatectl:

timedatectl status

Look for System clock synchronized: yes.

On Windows, check the time service status:

w32tm /query /status

If the clock is out of sync, correct it before further troubleshooting.

Agent debug flags

Below are the additional debug flags you can set in your waratek.properties file on the agent side to get additional logging. For full details, see the Troubleshooting and debugging options page.

You can safely enable the following parameter all the time as it prints out the start parameters for every application start:

com.waratek.ShowStart=true

This is useful for seeing all configuration parameters for an application in the application logfile.

For connectivity troubleshooting between Waratek Agent and Portal, and Elasticsearch the following can be enabled temporarily. You should disable these config parameters once connectivity is established.

com.waratek.debug.mc=true
com.waratek.debug.transport.file=<debug log file>

These print debug messages into the specified logfile.

Ensure the following property is set to fail:

com.waratek.ControllerUnavailableAction=fail

The ControllerUnavailableAction property controls how the Waratek Agent behaves when the Portal is unavailable at startup. While fail is the default value, your deployment may be configured to use ignore or retry instead. For connectivity troubleshooting, fail should be used because it enables verbose logging during application startup. The other values assume the user is already aware of the connectivity issue and produce less diagnostic output:

• ignore — the JDK starts but the Waratek Agent will not communicate with the Portal or Elasticsearch.
• retry — the Waratek Agent starts and retries communication with the Portal later.

If your waratek.properties currently uses ignore or retry, change it to fail while troubleshooting, then restore the previous value once the issue is resolved.

Agent initially shows Online in the Portal UI, but soon changes to Offline

If the Agent connects to the Portal and shows as Online but drops to Offline within the first few minutes, this is typically caused by application servers (e.g. Oracle WebLogic) that override the default HTTP/HTTPS handlers. See Agent connection to Portal drops for Oracle WebLogic for the cause and fix.

Connectivity troubleshooting to SaaS Waratek Portal

tip

Review Waratek Portal Network Requirements documentation for more details on the network requirements for the Portal.

Setting the debug flags above on the Waratek Agent, and reviewing the resulting logs does not always reveal the issue.

The next step should be to check connectivity from the agent to the SaaS Portal.

Test with curl

Run the following command from the host where the Agent is running:

curl -v "https://agent-api-2.waratek.com/api/2/agents" --data "{\"runtimeLanguage\": \"JAVA\"}"

A successful connection shows a TLS handshake completing and a 403 response:

* Connected to agent-api-2.waratek.com (...) port 443
...
* SSL connection using TLSv1.3 / ...
* SSL certificate verify ok.
...
< HTTP/2 403

Key things to look for in the output:

• DNS resolution succeeded — the host was resolved to an IP address.
• TLS handshake completed — SSL certificate verify ok appears.
• HTTP 403 returned — this is expected because no valid agent credentials were sent. A 403 confirms the Portal is reachable and responding.

If curl fails, refer to the Network-level diagnostics section above to isolate the issue.

Test with Java

If the curl connection works but the Agent still does not connect, the issue may be specific to the Java runtime. A sample PortalRestClient Java class is available in the Troubleshooting and debugging options page. It establishes a connection to the Portal in a similar way to what the Java Agent does internally, without swallowing exceptions, making it more useful for debugging.

Compile it with the same version of Java that the Agent is using:

/path/to/java/bin/javac PortalRestClient.java

Then run it:

/path/to/java/bin/java -cp . PortalRestClient

The expected output should include a 403 response:

start doConnection
Forcing TLSv1.2 was successful
response: 403
end doConnection

SSL/TLS debugging with Java flags

If the PortalRestClient successfully connects, try using additional command line parameters to inspect the SSL handshake and certificate validation in detail:

/path/to/java/bin/java \
  -Djava.security.debug=certpath \
  -Djavax.net.debug=ssl,handshake \
  -cp . PortalRestClient

If this is too noisy in your application output, run it with the PortalRestClient while loading the Waratek Agent and your application’s waratek.properties:

/path/to/java/bin/java \
  -Djava.security.debug=certpath \
  -Djavax.net.debug=ssl,handshake \
  -javaagent:/path/to/waratek_java_agent_jar \
  -Dcom.waratek.WaratekProperties=/path/to/waratek.properties \
  -cp . PortalRestClient