Gateway 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. Postfix/SMTP Error Codes
9. Java Content Filter Errors
10. ACM & Accounts Errors
11. CKS-Related Errors
12. TLS/Certificate Errors
13. Getting Help

Viewing Container Logs

Gateway outputs logs to stdout, which includes both Postfix mail logs and Java content filter logs. 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/gateway.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> > gateway-logs.txt 2>&1

Podman:

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

Kubernetes:

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

Transfer Logs from Remote Host

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

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

Podman:

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

Extract compressed logs:

gunzip gateway-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 \
  --env-file /var/virtru/vg/env/gateway.env \
  -v /var/virtru/vg/tls/:/etc/postfix/tls \
  -v /var/virtru/vg/dkim/:/etc/opendkim/keys \
  --publish 9001:25 \
  --interactive --tty --detach \
  --restart unless-stopped \
  --name gateway \
  --log-opt max-size=100m \
  --log-opt max-file=10 \
  containers.virtru.com/gateway:v<version-number>

Podman Log Rotation

Configure log rotation with custom log path:

podman run \
  --env-file /var/virtru/vg/env/gateway.env \
  -v /var/virtru/vg/tls/:/etc/postfix/tls \
  -v /var/virtru/vg/dkim/:/etc/opendkim/keys \
  --publish 9001:25 \
  --interactive --tty --detach \
  --restart unless-stopped \
  --name gateway \
  --log-opt path=/var/log/gateway.log \
  containers.virtru.com/gateway:v<version-number>

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 \
  --env-file /var/virtru/vg/env/gateway.env \
  -v /var/virtru/vg/tls/:/etc/postfix/tls \
  -v /var/virtru/vg/queue/gateway/:/var/spool/postfix \
  -v /var/virtru/vg/dkim/:/etc/opendkim/keys \
  --name gateway \
  --publish 9001:25 \
  --interactive --tty --detach \
  --restart unless-stopped \
  --log-driver syslog \
  --log-opt syslog-address=tcp://192.168.10.15:10514 \
  containers.virtru.com/gateway:v<version-number>

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 <container_id> 2>&1 | grep -iE "(error|exception|fatal|failed|denied)"

Example: Filter SMTP Codes from Kubernetes

kubectl logs <pod> -n <namespace> | grep -E "status=(deferred|bounced)|[45][0-9]{2} "

Enable Debug Logging

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

Postfix/SMTP Error Codes

4XX - Temporary Failures (Sender Should Retry)

5XX - Permanent Failures (Do Not Retry)

Gateway-Specific SMTP Errors

Postfix Queue Status Messages

Found in logs with status=:

Java Content Filter Errors

Exception Types

Common Stack Trace Patterns

ACM & Accounts Errors

HTTP errors returned when Gateway communicates with Virtru services:

Common 403 Reasons

CKS-Related Errors

For customers using Customer Key Server (CKS), these errors may appear when decrypting content:

TLS/Certificate Errors

TLS Compliance Levels

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:

• Gateway version
• Relevant log output (filtered for errors)
• Steps to reproduce the issue
• Any recent configuration changes