Virtru Private Keystore (for Google Workspace CSE) 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. JWT / Authentication Errors
10. Configuration / Startup Errors
11. S/MIME Errors
12. VPK Communication Errors
13. Upstream Service Errors
14. Getting Help

Viewing Container Logs

Virtru Private Keystore (for Google Workspace CSE) outputs logs to stdout in JSON format using log4js. 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/cse-v<version>.log \
  ...

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

Install Script Default Paths

When using the Virtru install script, files are organized in:

/var/virtru/cse/
├── cse.env           # Environment configuration
├── secrets.json      # Secret keys (standalone mode)
├── server.cert       # SSL certificate
├── server.key        # SSL private key
└── run.sh            # Docker run script

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> > cse-logs.txt 2>&1

Podman:

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

Kubernetes:

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

Transfer Logs from Remote Host

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

scp user@remote_host:/path/to/cse-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 > cse-logs.gz

Podman:

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

Extract compressed logs:

gunzip cse-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 --detach \
  --env-file ./cse.env \
  -p 443:9000 \
  -v /var/virtru/cse/server.cert:/run/secrets/server.cert \
  -v /var/virtru/cse/server.key:/run/secrets/server.key \
  --restart unless-stopped \
  --log-opt max-size=100m \
  --log-opt max-file=10 \
  --name cse-v<version> \
  containers.virtru.com/cse:v<version>

Podman Log Rotation

Configure log rotation with custom log path:

podman run --detach \
  --env-file ./cse.env \
  -p 443:9000 \
  -v /var/virtru/cse/server.cert:/run/secrets/server.cert \
  -v /var/virtru/cse/server.key:/run/secrets/server.key \
  --restart unless-stopped \
  --name cse-v<version> \
  --log-opt path=/var/log/cse-v<version>.log \
  containers.virtru.com/cse:v<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 --detach \
  --env-file ./cse.env \
  -p 443:9000 \
  -v /var/virtru/cse/server.cert:/run/secrets/server.cert \
  -v /var/virtru/cse/server.key:/run/secrets/server.key \
  --restart unless-stopped \
  --name cse-v<version> \
  --log-driver syslog \
  --log-opt syslog-address=tcp://192.168.10.15:10514 \
  containers.virtru.com/cse:v<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 cse 2>&1 | grep -iE "(error|fatal|failed)"

Example: Parse JSON Logs with jq

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

Enable Debug Logging

For more verbose output when troubleshooting, set this environment variable:

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

HTTP API Error Codes

Core Endpoints

S/MIME Endpoints (Gmail)

HTTP Status Codes

Error Classes

JWT / Authentication Errors

Token Validation Errors

Role Requirements

IdP Configuration

Google (Default):

Okta:

Configuration / Startup Errors

Missing Environment Variables

Secret Key Errors (Standalone Mode)

Base64 Encoding Errors

Encoding Example:

# JWKS_AUTHN_ISSUERS
echo '{ "https://accounts.google.com": "https://www.googleapis.com/oauth2/v3/certs" }' | base64 -w 0

# JWT_AUD
echo '{ "authn": "<client-id>", "authz": "cse-authorization" }' | base64 -w 0

S/MIME Errors

Algorithm Errors

Supported Decryption Algorithms:

• RSA/ECB/PKCS1Padding
• RSA/ECB/OAEPwithSHA-1andMGF1Padding
• RSA/ECB/OAEPwithSHA-256andMGF1Padding
• RSA/ECB/OAEPwithSHA-512andMGF1Padding

Supported Signing Algorithms:

• SHA1withRSA
• SHA256withRSA
• SHA1withRSA/PSS
• SHA256withRSA/PSS
• SHA512withRSA/PSS

SPKI Hash Errors

Digest Errors

VPK Communication Errors

When operating with VPK (Virtru Private Keystore for Virtru Solutions), CSE communicates with VPK for key operations.

Upstream Service Errors

ACM Errors

These errors originate from Virtru's Access Control Manager (ACM):

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:

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

Related Documentation:

• Virtru Private Keystore (VPK) Log & Error Reference - For VPK-specific errors