Caddy

Caddy Setup Guide

This guide explains how to configure Caddy to produce access logs in JSON format that LogLynx can parse and analyze.

Prerequisites

• Caddy 2.x installed and running
• LogLynx configured to monitor Caddy logs

Configuration

1. Caddyfile Configuration

Add the following log directive to your Caddyfile to enable JSON access logging:

# Global log configuration
{
    log {
        format json
        level INFO
    }
}

# Your site configuration
example.com {
    # Your directives here...

    # Access logging
    log {
        output file /var/log/caddy/access.log {
            roll_size 10mb
            roll_keep 5
        }
        format json
        level INFO
    }
}

2. Alternative: Docker Compose Configuration

If you're running Caddy in Docker, mount the log directory and configure logging:

version: '3.8'
services:
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy/logs:/var/log/caddy
      - caddy_data:/data
      - caddy_config:/config
    restart: unless-stopped

volumes:
  caddy_data:
  caddy_config:

3. LogLynx Configuration

Configure LogLynx to monitor your Caddy logs by setting the following environment variables:

# Path to Caddy access log file
CADDY_LOG_PATH=/var/log/caddy/access.log

# Enable auto-discovery (optional, default: true)
LOG_AUTO_DISCOVER=true

Or in your .env file:

CADDY_LOG_PATH=caddy/logs/access.log
LOG_AUTO_DISCOVER=true

Log Format

Caddy will produce JSON logs with the following structure that LogLynx can parse:

{
  "level": "info",
  "ts": 1640995200.123456,
  "logger": "http.log.access",
  "msg": "handled request",
  "request": {
    "remote_ip": "192.168.1.100",
    "remote_port": "12345",
    "client_ip": "192.168.1.100",
    "proto": "HTTP/1.1",
    "method": "GET",
    "host": "example.com",
    "uri": "/path?query=value",
    "headers": {
      "User-Agent": ["Mozilla/5.0..."],
      "Referer": ["https://referrer.com"]
    },
    "tls": {
      "version": 772,
      "cipher_suite": 4865,
      "server_name": "example.com"
    }
  },
  "user_id": "",
  "bytes_read": 0,
  "status": 200,
  "size": 1024,
  "duration": 0.001234,
  "upstream": {
    "address": "127.0.0.1:8080",
    "status": 200,
    "duration": 0.000987
  }
}

Supported Fields

LogLynx extracts the following information from Caddy JSON logs:

• Timestamp: Request timestamp (Unix float)
• Client Info: IP address, port, user ID
• Request Details: Method, protocol, host, path, query string, scheme
• Response Info: Status code, response size, content type, response time
• TLS Info: Version, cipher suite, server name
• Upstream Info: Backend URL, upstream status, upstream response time
• Headers: User-Agent, Referer
• Additional: Bytes read, request duration

Troubleshooting

Log File Not Detected

1. Verify the log file path in LogLynx configuration matches your Caddy log output
2. Check file permissions - LogLynx needs read access to the log file
3. Ensure Caddy is writing logs in JSON format
4. Check LogLynx logs for detection messages

Invalid Log Format

1. Confirm your Caddyfile includes format json in the log directive
2. Verify the log level is set to INFO or higher
3. Check that the logger field contains "http.log.access"

Permission Issues

If running in Docker, ensure proper volume mounting:

volumes:
  - ./caddy/logs:/var/log/caddy

And set appropriate permissions on the host directory.

Advanced Configuration

Custom Log Fields

You can add custom fields to your Caddy logs that LogLynx will store in the ProxyMetadata field:

log {
    output file /var/log/caddy/access.log
    format json {
        time_format "2006-01-02T15:04:05Z07:00"
        time_key "timestamp"
        message_key "message"
        level_key "level"
        name_key "logger"
    }
    level INFO
}

Multiple Sites

For multiple sites, you can either:

1. Use a single global log file
2. Configure separate log files per site and add multiple sources in LogLynx

site1.com {
    log {
        output file /var/log/caddy/site1.log
        format json
    }
    # ... directives
}

site2.com {
    log {
        output file /var/log/caddy/site2.log
        format json
    }
    # ... directives
}