Configuration and Operation Issues¶

Issues related to Excalibur setup, connectivity, and runtime behavior — independent of the underlying container runtime.

Prerequisites

Troubleshooting commands require administrative (sudo) privileges and kubectl access to the cluster (for Kubernetes deployments) or Docker CLI access (for Docker deployments).

Dashboard or Setup Page Not Accessible¶

Symptom

Browsing to https://<your-instance-fqdn>/setup returns a connection timeout, ERR_CONNECTION_REFUSED, or a TLS certificate error.

Cause

The setup page is unreachable when DNS, ingress, TLS, or firewall configuration is incorrect:

DNS record for the FQDN does not point to the cluster's ingress IP
Ingress controller is not running or misconfigured
TLS certificate is missing, expired, or does not match the FQDN
Firewall or security group blocking port 443

Diagnostic steps

Verify DNS resolution:
```
nslookup <your-instance-fqdn>
```
Check ingress resource status:
```
kubectl get ingress -n <namespace>
```
Verify the ingress controller pods are running:
```
kubectl get pods -n ingress-nginx
```

Test connectivity to the ingress IP directly:

curl -vk https://<ingress-ip>/ -H "Host: <your-instance-fqdn>"

Resolution

DNS does not resolve — create or update the A/CNAME record to point to the cluster's external IP or load balancer.
Ingress resource shows no address — verify ingress.annotations in .values.yaml matches your ingress controller's requirements.
TLS certificate error — ensure a valid certificate exists for the FQDN. If using cert-manager, check the Certificate and CertificateRequest resources.
Connection refused — open port 443 in the firewall or cloud security group.

After applying the fix, open https://<your-instance-fqdn>/setup in a browser. The Deployment Setup page should load without errors.

License Validation Failure¶

Symptom

During the initial server setup (Step 1), the system displays a license validation error after uploading the .lic file or entering the license key.

Cause

License validation can fail due to formatting issues, network restrictions, or time synchronization problems:

Incorrect license key format (expected: AAAAA-BBBBB-CCCCC-DDDDD-EEEEE)
Corrupted or invalid .lic file
The server cannot reach ca.xclbr.com:443 for online validation
System clock is out of sync, causing certificate or token validation to fail

Diagnostic steps

Verify the license key format matches the expected pattern.
Test outbound connectivity to the Excalibur CA service:
```
curl -v https://ca.xclbr.com
```
Check that the system time is accurate:
```
date -u
```

Resolution

Incorrect key format — re-enter the license key, ensuring no extra spaces or characters.
Cannot reach ca.xclbr.com — allow outbound HTTPS (port 443) to ca.xclbr.com in your firewall.
System clock out of sync — synchronize using NTP:

sudo timedatectl set-ntp true

Corrupted .lic file — request a new copy from your Excalibur representative.

After applying the fix, re-attempt the license validation. The setup wizard should proceed to Step 2 (Server Setup).

Identity Store Connection Failure¶

Symptom

During setup (Step 4) or in the Dashboard, connecting to the Active Directory or LDAP identity store fails with a connection timeout or authentication error.

Cause

Identity store connections fail when the Excalibur instance cannot reach or authenticate against the directory server:

Network connectivity issue between the Excalibur instance and the AD/LDAP server
Incorrect LDAP bind credentials (username or password)
Wrong port or protocol (e.g., LDAP on port 389 instead of LDAPS on port 636)
LDAPS certificate not trusted by the Excalibur server

Warning

Password reset requires the LDAPS protocol. Connections using plain LDAP do not support password changes.

Diagnostic steps

Test network connectivity to the LDAP server:
```
nc -zv <ldap-server> 636
```
Test the LDAPS connection and verify the certificate:
```
openssl s_client -connect <ldap-server>:636
```

Verify bind credentials using ldapsearch:

ldapsearch -H ldaps://<ldap-server>:636 -D "<bind-dn>" -w "<password>" -b "<base-dn>" "(objectClass=user)"

Resolution

Connectivity fails — check firewall rules and ensure the Excalibur instance can reach the AD/LDAP server on port 636.
LDAPS certificate not trusted — import the AD/LDAP server's CA certificate into the Excalibur trust store.
Authentication error — correct the bind DN and password in the Identity Store configuration.
Using plain LDAP — switch to LDAPS (port 636) for full functionality, including password management.

After applying the fix, re-test the Identity Store connection from the Dashboard. The connection status should show as successful.

Device Integrity Check Failures¶

Symptom

Users cannot authenticate. The system returns a device integrity verification error. Logs may reference www.googleapis.com or playintegrity.googleapis.com.

Cause

Device integrity checks fail when the server cannot reach Google APIs or the device does not pass validation:

Network restrictions blocking access to Google APIs from the Excalibur server
Device is rooted, running a custom ROM, or fails Google Play Integrity validation
Google Play Integrity API credentials are misconfigured

Diagnostic steps

Test outbound connectivity to Google APIs from the server:

curl -v https://www.googleapis.com
curl -v https://playintegrity.googleapis.com

Review application logs for integrity check error details.
Confirm whether device integrity checks are enabled in the Security Policies.

Resolution

Server cannot reach Google APIs — allow outbound HTTPS traffic to www.googleapis.com:443 and playintegrity.googleapis.com:443 in your firewall.
Air-gapped or restricted environments — disable device integrity checks in the Security Policies to eliminate the dependency on Google APIs.
Specific devices fail — verify the device is not rooted and has valid Google Play Services installed.

After applying the fix, re-attempt authentication from the affected device. The integrity check should pass. If integrity checks are disabled, authentication proceeds without the check.

Tunnel Connection Failure¶

Symptom

The Excalibur Tunnel Client fails to establish a connection to the Excalibur Cloud. The client reports a connection timeout, TLS handshake failure, or activation error.

Cause

Tunnel connections fail due to invalid activation codes, network restrictions, or version mismatches:

Activation code is invalid or has already been used
Firewall blocking outbound mTLS connections to Excalibur Cloud
System clock is out of sync, causing TLS certificate validation to fail
Tunnel Client version is incompatible with the current Excalibur Cloud version

Diagnostic steps

Check the Tunnel Client help output for available diagnostic flags:
```
sudo excalibur-tunnel --help
```
Verify outbound connectivity to the Excalibur Cloud endpoint.
Check the system time:
```
date -u
```
Verify the Tunnel Client version:
```
excalibur-tunnel --version
```

Resolution

Invalid or consumed activation code — request a new code from the Excalibur Dashboard.
Firewall blocking outbound traffic — allow outbound traffic to the Excalibur Cloud endpoint on the required port.
System clock out of sync — synchronize using NTP.
Outdated Tunnel Client — upgrade to the latest version from the Excalibur Tunnel Client repository.

After applying the fix, re-activate the Tunnel Client. The connection status in the Excalibur Dashboard should show as connected.