Keycyte PAM 3.2 · Deployment Guide

Troubleshooting

This topic describes how to collect information about a problem and how to solve common deployment issues. Run the docker compose commands in this topic in the installation package folder.

Viewing Service Logs

In the Admin Panel

Settings > Services lists the Keycyte PAM containers with their Container, Service, State, CPU, Memory and Uptime. Only MASTER administrators can open this page.

To view the log of a container:

In the Admin Panel, open Settings > Services.
In the Keycyte Services table, click Logs in the row of the container.

The latest log lines of the container appear.

From the same table you can Restart, Stop and Start containers. Stopping or restarting a container interrupts the sessions that it handles. The PAM server cannot stop or start itself; only Restart is available for it.

If the page shows Docker socket not available, the Docker socket is not mounted into the PAM server container. The installation package mounts /var/run/docker.sock read-only; check that docker-compose.yml still contains this mount and that DOCKER_GID in .env matches the group ID of the host’s docker group.

On the Host

To view the logs of a service on the host, use docker compose logs:

sudo docker compose --env-file .env -f docker-compose.yml logs --tail 200 pam

To follow the log continuously, add -f. The service names are pam, ssh-proxy, guacd, password-manager, radius and postgres.

Each container keeps at most three log files of 5 MB each.

Changing the Log Level

To get more detail, set the log level to debug on Settings > General (Log Level). The change takes effect immediately, without a restart. Set it back to info when you have collected the information, because debug produces a large volume of log lines.

You can also set the startup log level with KEYCYTE_LOG_LEVEL. See Configuration Reference.

Resetting the Web TLS Certificate

If a certificate applied on Settings > Web TLS Certificate prevents browsers from connecting (for example, wrong host name together with HSTS, or a certificate that clients do not trust), you can deactivate it from the command line. The PAM server then falls back to the installation keystore or to a temporary self-signed certificate, and you can sign in again to apply a correct certificate.

To reset the Web TLS certificate:

On the host, run the reset command in the PAM server container:
```
sudo docker exec pam keycyte-pam cert reset
```
The command deactivates the active certificate in the database and prints how many rows it changed.

Restart the PAM server:

sudo docker compose --env-file .env -f docker-compose.yml restart pam

Open the Admin Panel, accept the browser warning if one appears, and apply a correct certificate on Settings > Web TLS Certificate.

The applied certificate stays in Upload History; it is only no longer active.

Common Issues

A container does not start

The installer prints the last log lines of every container that is not running. You can show them again with docker compose logs <service>. Typical causes for the PAM server:

Log message contains	Cause and solution
`session secret validation failed`	`SESSION_SECRET_KEY` in `.env` is empty, shorter than 32 bytes, or the built-in value. Set a random value of at least 32 bytes and recreate the containers.
`No AES key configured`	No encryption key is set. Check `KEYSTORE_KEY_HEX` in `.env`.
`Invalid key_hex value`	`KEYSTORE_KEY_HEX` is not a valid hexadecimal string.
`Failed to run ent auto-migration`	The PAM server could not update the database schema. Check the database connection and the rights of the database user.

The installer reports missing images

The installer stops if an expected image is not loaded after extracting keycyte-pam.tar.gz. Check the loaded images with sudo docker images. The images must be tagged keycyte-pam:latest, keycyte-ssh-proxy:latest, keycyte-password-manager:latest, keycyte-radius-server:latest and guacamole/guacd:latest.

If the postgres container cannot start because the image cannot be pulled, the host has no access to Docker Hub. Load postgres:17 manually; see Preparing the Installation Package.

The master account was not created

If the installer printed a warning that the master account script was skipped, run the script manually. See If the Master Account Was Not Created.

The browser shows a certificate warning

The PAM server uses the installation keystore or a temporary self-signed certificate. Check the Source on Settings > Web TLS Certificate, and apply a certificate that is issued for the Keycyte PAM DNS name by a CA that user workstations trust.

The LDAP server certificate is not trusted. Check that its CA is in ~/keycyte/cacerts.pem, or add the certificate from the LDAP configuration in the Admin Panel. After you change cacerts.pem on the host, restart the pam and password-manager services.

Native SSH or web terminal sessions fail

Check the Service AccessKeys card on Settings > Services. If the SSH proxy is shown as not configured, the SSH proxy access key is missing in the PAM server environment. Also check the ssh-proxy log for authentication errors toward the PAM server. See Service Access Keys.

Scheduled password rotation, reports or backups do not run

Scheduled jobs run only on the master node. Check the Master switch on Settings > Replication, or look for the line Running as MASTER node or Running as REPLICA node in the PAM server log after startup. See High Availability.

Users are signed out or sessions fail behind a load balancer

Check that all nodes use the same SESSION_SECRET_KEY and that the load balancer uses session affinity. See High Availability.

Certificate expiry e-mails are not received

Check the mail server settings with Email Test on Settings > Notification, and check that the MASTER administrators have e-mail addresses.