NTP Query Logging

Overview

CodexDNS separates NTP logging into two distinct logs to provide better visibility into NTP server operations and individual client requests.

Log Files

1. NTP Server Log (ntp_log_path)

Default: logs/ntp-server.log

Purpose: Server lifecycle events and operations

Contains:

  • Server start/stop events
  • Configuration changes
  • Time synchronization events
  • Server errors and warnings
  • General operational messages

Example entries:

2025/01/25 10:30:15 [INFO] [NTP] NTP server started on 0.0.0.0:123
2025/01/25 10:30:16 [INFO] [NTP] Time synchronized with upstream server pool.ntp.org
2025/01/25 10:35:22 [INFO] [NTP] Request from 192.168.1.100 version=4 mode=3
2025/01/25 10:40:45 [ERROR] [NTP] Failed to sync with upstream: connection timeout

2. NTP Query Log (ntp_query_log_path)

Default: logs/ntp-queries.log

Purpose: Individual NTP client requests (NEW)

Contains:

  • Every NTP client request with detailed parameters
  • Client IP and port
  • NTP version, mode, stratum
  • Request payload size

Format: timestamp client_ip:port v=VERSION mode=MODE stratum=STRATUM len=LENGTH

Example entries:

2025/01/25 10:35:22.123456 192.168.1.100:52341 v=4 mode=3 stratum=0 len=48
2025/01/25 10:35:25.456789 192.168.1.101:51234 v=4 mode=3 stratum=0 len=48
2025/01/25 10:35:28.789012 10.0.0.50:49152 v=3 mode=3 stratum=0 len=48

Configuration

Via config.json

{
  "ntp_log_path": "logs/ntp-server.log",
  "ntp_query_log_path": "logs/ntp-queries.log",
  "log_rotation": {
    "max_size_mb": 100,
    "max_backups": 10,
    "max_age_days": 30,
    "compress": true
  }
}

Via Web UI

Navigate to Settings → Logging Configuration and configure:

  • NTP Server: Path to NTP server operations log
  • NTP Queries: Path to NTP client queries log

Via Environment Variables

export CODEXDNS_NTP_LOG_PATH="logs/ntp-server.log"
export CODEXDNS_NTP_QUERY_LOG_PATH="logs/ntp-queries.log"

NTP Field Reference

Mode Values

  • 0 - Reserved
  • 1 - Symmetric active
  • 2 - Symmetric passive
  • 3 - Client
  • 4 - Server
  • 5 - Broadcast
  • 6 - NTP control message
  • 7 - Reserved for private use

Version Values

  • 3 - NTP version 3
  • 4 - NTP version 4 (most common)

Stratum Values

  • 0 - Unspecified/invalid
  • 1 - Primary reference (e.g., GPS, atomic clock)
  • 2-15 - Secondary reference (distance from primary)
  • 16 - Unsynchronized

Use Cases

Troubleshooting NTP Issues

Check the NTP Server Log for operational problems:

grep ERROR logs/ntp-server.log

Monitoring Client Activity

Check the NTP Queries Log for client patterns:

# Count requests per client
awk '{print $2}' logs/ntp-queries.log | cut -d: -f1 | sort | uniq -c | sort -rn

# Find non-NTPv4 clients
grep -v "v=4" logs/ntp-queries.log

# Monitor request rate
tail -f logs/ntp-queries.log

Analyzing Time Sync Patterns

# Group requests by hour
awk '{print substr($1, 1, 13)}' logs/ntp-queries.log | sort | uniq -c

# Find clients with unusual stratum values
grep -v "stratum=0" logs/ntp-queries.log

Log Rotation

Both logs use the same rotation settings from log_rotation configuration:

  • max_size_mb: Rotate when file reaches this size (default: 100MB)
  • max_backups: Number of old log files to keep (default: 10)
  • max_age_days: Delete files older than this (default: 30 days)
  • compress: Gzip old files asynchronously (default: true)

Rotated files are named:

  • ntp-server.log.1, ntp-server.log.2.gz, etc.
  • ntp-queries.log.1, ntp-queries.log.2.gz, etc.