Virtru Private Keystore (VPK) Log & Error Reference

Table of Contents

1. Viewing Container Logs
2. Log File Paths
3. Downloading & Compressing Logs
4. Log Rotation Configuration
5. Exporting Logs to a SIEM
6. Filtering for Errors
7. Enable Debug Logging
8. HTTP API Error Codes
9. ACM → VPK Errors
10. Key Provider Errors
11. Rewrap Errors
12. HSM Errors
13. Authentication Errors
14. Startup/Boot Errors
15. TLS/Certificate Errors
16. Getting Help

Viewing Container Logs

VPK outputs logs to stdout in JSON format. Both Docker and Podman provide commands to view these logs, displaying the stdout (standard output) and stderr (standard error) streams from the running container.

Basic Commands

Log File Paths

Docker

Docker stores logs in a specific path on the host machine:

/var/lib/docker/containers/<containerID>/<containerID>-json.log

Each container has its own directory, and log files are saved as JSON.

Podman

Podman allows you to configure a custom log path using the --log-opt parameter:

podman run \
  --log-opt path=/var/log/Virtru_CKS.log \
  ...

This allows you to specify a custom log location, which is useful for centralized log storage and management.

Kubernetes

Logs are managed by the container runtime and accessible via kubectl logs. For persistent storage, configure a logging sidecar or external log aggregation.

Downloading & Compressing Logs

Export Logs to a File

Docker:

docker logs <container_id> > cks-logs.txt 2>&1

Podman:

podman logs <container_id> > cks-logs.txt 2>&1

Kubernetes:

kubectl logs <pod> -n <namespace> > cks-logs.txt

Transfer Logs from Remote Host

Use scp or other file transfer tools to download log files:

scp user@remote_host:/path/to/cks-logs.txt /local/path/

Compress Logs

Logs can grow quite large. Compressing them makes it easier to store and transfer:

Docker:

docker logs <container_id> 2>&1 | gzip > cks-logs.gz

Podman:

podman logs <container_id> 2>&1 | gzip > cks-logs.gz

Extract compressed logs:

gunzip cks-logs.gz

Log Rotation Configuration

Log rotation prevents container logs from consuming too much disk space.

Docker Log Rotation

Configure log rotation as part of the container setup:

docker run \
  --name Virtru_CKS \
  --interactive --tty --detach \
  --env-file /var/virtru/cks/env/cks.env \
  -v /var/virtru/cks/keys/:/app/keys \
  -v /var/virtru/cks/ssl/:/app/ssl \
  -p 443:9000 \
  --log-opt max-size=100m \
  --log-opt max-file=10 \
  --restart unless-stopped \
  containers.virtru.com/cks:<version>

Podman Log Rotation

Configure log rotation with custom log path:

podman run \
  --name Virtru_CKS \
  --interactive --tty --detach \
  --env-file /var/virtru/cks/env/cks.env \
  -v /var/virtru/cks/keys/:/app/keys \
  -v /var/virtru/cks/ssl/:/app/ssl \
  -p 443:9000 \
  --restart unless-stopped \
  --log-opt path=/var/log/Virtru_CKS.log \
  containers.virtru.com/cks:<version>

For more information on Docker logging drivers, see: Docker Logging Configuration

Exporting Logs to a SIEM

Logs can be forwarded to a remote syslog server for centralized monitoring and analysis.

Docker Syslog Driver

Configure the container to send logs directly to a remote syslog server:

docker run \
  --name Virtru_CKS \
  --interactive --tty --detach \
  --env-file /var/virtru/cks/env/cks.env \
  -v /var/virtru/cks/keys/:/app/keys \
  -v /var/virtru/cks/ssl/:/app/ssl \
  -p 443:9000 \
  --log-driver syslog \
  --log-opt syslog-address=tcp://192.168.10.15:10514 \
  --restart unless-stopped \
  containers.virtru.com/cks:<version>

Host-Level Syslog Forwarding

Alternatively, forward all host syslog entries (including container logs) to a remote server.

Edit /etc/rsyslog.d/50-default.conf:

nano /etc/rsyslog.d/50-default.conf

Add at the top:

*.* action(type="omfwd" target="192.168.10.15" port="10514" protocol="tcp" action.resumeRetryCount="100" queue.type="linkedList" queue.size="10000")

Restart rsyslog after making changes:

sudo systemctl restart rsyslog

Filtering for Errors

Use these patterns to filter logs for specific error types.

Useful Grep Patterns

Example: Filter Errors from Docker

docker logs Virtru_CKS 2>&1 | grep -iE "(error|fatal|failed)"

Example: Parse JSON Logs with jq

docker logs Virtru_CKS 2>&1 | jq 'select(.level == "ERROR")'

Enable Debug Logging

For more verbose output when troubleshooting, set these environment variables:

Available levels: ALL, TRACE, DEBUG, INFO (default), WARN, ERROR, FATAL, OFF

HTTP API Error Codes

API Endpoints

HTTP Status Codes

ACM → VPK Errors

These errors originate from Virtru's Access Control Manager (ACM) when communicating with VPK. You may see these as API responses or in application logs.

Key Type Mismatch Errors (412)

ACM validates that user public keys match your organization's VPK key type:

ECC Curve Weights

Key Provider Errors

NoKeyError (HTTP 409)

UnpairedPublicKeyError (HTTP 409)

KeyError (HTTP 400)

Supported Key Types

Rewrap Errors

RewrapError Types (HTTP 400)

OpenSSL Error Mappings

Common Rewrap Issues

HSM Errors

PKCS#11 Errors

Validate HSM Setup

Use list-keys to verify HSM connectivity before starting VPK:

docker run \
  -e HSM_IP="<hsm_ip>" \
  -e PKCS11_VENDOR="custom" \
  -e PKCS11_LIB_NAME="CloudHSM" \
  -e PKCS11_LIB_PATH="/opt/cloudhsm/lib/libcloudhsm_pkcs11.so" \
  -e PKCS11_SLOT_LBL="<slot_label>" \
  -e PKCS11_KEY_LBL="<key_label>" \
  -e PKCS11_PIN="<user>:<password>" \
  -e KEY_PROVIDER_TYPE="hsm" \
  -e CRYPTO_OPERATIONS_TYPE="hsm" \
  --mount type=bind,source=/path/to/customerCA.crt,target=/opt/cloudhsm/etc/customerCA.crt \
  containers.virtru.com/cks:<version> list-keys

Authentication Errors

Authentication Modes

JWT Errors

HMAC Errors

Configuration Errors

Startup/Boot Errors

Boot Check Failures

No-Keys Rule Options

Common Setup Issues

TLS/Certificate Errors

Getting Help

If you're unable to resolve an issue using this guide, please contact Virtru Support:

Virtru Support Portal: support.virtru.com

When contacting support, please include:

• VPK version
• Deployment type (Docker, Podman, Kubernetes, HSM)
• Relevant log output (filtered for errors)
• Steps to reproduce the issue
• Any recent configuration changes