Secure DICOM workflows for cloud, on premise and hybrid use support@dicom.link
Knowledge Base

Configuration Reference

Complete reference for all appsettings.json sections, servers.json, environment variables, and logging configuration.

The DICOM Router uses a multi-layered configuration system based on JSON files. Configuration is loaded in this order (later overrides earlier):

  1. Default values (hardcoded)
  2. appsettings.json
  3. appsettings.{Environment}.json
  4. Environment variables
  5. Command-line arguments
  6. Runtime database settings

Configuration files

File Purpose
appsettings.json Main application settings
servers.json External PACS servers
nlog.config Logging (XML)
certificate.pfx HTTPS certificate (optional)
dicomtls.pfx DICOM TLS certificate (optional)

appsettings.json — complete example

{
  "DicomPort": 11112,
  "HttpPort": 8080,
  "HttpsPort": 8443,
  "StoragePath": "C:\\DicomStorage",
  "DatabasePath": "C:\\DicomStorage\\dicom.db",
  "TempPath": "C:\\DicomStorage\\temp",
  "LogPath": "C:\\DicomStorage\\logs",
  "ConfigPath": "C:\\DicomStorage\\config",

  "ThisModality": {
    "AE_Title": "DICOMPROXY",
    "Port": 11112,
    "IPAddress": "0.0.0.0",
    "MaxConnections": 50,
    "MaxPDULength": 16384,
    "RequestTimeout": 30000,
    "IdleTimeout": 300000,
    "EnableCompression": true
  },

  "Security": {
    "EnableTLS": false,
    "CertificatePath": "certificate.pfx",
    "CertificatePassword": "",
    "RequireClientCertificate": false,
    "EnableDicomTLS": false,
    "DicomTLSCertPath": "dicomtls.pfx",
    "RequireAuthentication": false,
    "AllowedAETitles": [],
    "BlockedAETitles": [],
    "EnableAuditLogging": true
  },

  "Storage": {
    "MaxStorageSizeGB": 1000,
    "CleanupEnabled": true,
    "CleanupIntervalHours": 24,
    "RetentionDays": 365,
    "MaxConcurrentWrites": 10,
    "UseAsyncIO": true,
    "BufferSizeKB": 64,
    "EnableCompression": false,
    "CompressionLevel": 6,
    "ValidateStoredFiles": true
  },

  "Performance": {
    "MaxConcurrentConnections": 100,
    "ConnectionPoolSize": 50,
    "RequestTimeoutSeconds": 300,
    "MaxMemoryUsageMB": 4096,
    "EnableCaching": true,
    "CacheExpirationMinutes": 30,
    "ThreadPoolMinThreads": 10,
    "ThreadPoolMaxThreads": 100,
    "GCMode": "server"
  },

  "Proxy": {
    "EnableProxy": true,
    "DefaultServer": "primary_pacs",
    "LoadBalancingMode": "RoundRobin",
    "FailoverEnabled": true,
    "HealthCheckIntervalSeconds": 60,
    "RetryAttempts": 3,
    "RetryDelaySeconds": 5,
    "EnableConnectionPooling": true,
    "MaxConnectionsPerServer": 10
  },

  "Api": {
    "EnableOpenApi": true,
    "EnableCors": true,
    "AllowedOrigins": ["*"],
    "EnableRateLimiting": true,
    "RateLimitRequestsPerHour": 1000,
    "MaxRequestSizeMB": 100,
    "EnableCompression": true,
    "RequestTimeoutSeconds": 300
  },

  "Features": {
    "EnableQIDORS": true,
    "EnableWADORS": true,
    "EnableSTOWRS": true,
    "EnableDicomWeb": true,
    "EnableImageRendering": true,
    "EnableScripting": false,
    "EnableMDNS": true,
    "EnableTUS": true
  },

  "Licensing": {
    "LicenseFile": "dicomproxy.lic",
    "LicenseServer": "https://license.dicom.link",
    "AutoRenewal": true,
    "DemoMode": true,
    "DemoExpirationDays": 30,
    "MaxStudiesInDemo": 100
  },

  "Monitoring": {
    "EnableMetrics": true,
    "MetricsPort": 9090,
    "EnableHealthChecks": true,
    "HealthCheckPort": 8081,
    "EnablePerformanceCounters": true,
    "StatisticsUpdateIntervalSeconds": 60
  }
}

ThisModality parameters

Parameter Type Default Description
AE_Title string "DICOMPROXY" Application Entity title
Port integer 11112 DICOM listener port
IPAddress string "0.0.0.0" Bind IP (0.0.0.0 = all interfaces)
MaxConnections integer 50 Maximum concurrent DICOM connections
MaxPDULength integer 16384 Max PDU length in bytes
RequestTimeout integer 30000 Request timeout in ms
IdleTimeout integer 300000 Idle connection timeout in ms

Security parameters

Parameter Type Default Description
EnableTLS boolean false Enable HTTPS for REST API
RequireClientCertificate boolean false Require client certificates
EnableDicomTLS boolean false Enable secure DICOM communications
RequireAuthentication boolean false Require API authentication
AllowedAETitles array [] AE title whitelist (empty = allow all)
BlockedAETitles array [] AE title blacklist
EnableAuditLogging boolean true Enable security audit logging

Storage parameters

Parameter Type Default Description
MaxStorageSizeGB integer 1000 Maximum storage in GB
CleanupEnabled boolean true Enable automatic cleanup
RetentionDays integer 365 File retention period in days
MaxConcurrentWrites integer 10 Maximum concurrent file writes
UseAsyncIO boolean true Asynchronous I/O
ValidateStoredFiles boolean true Validate files after storage

servers.json

{
  "servers": [
    {
      "id": "primary_pacs",
      "name": "Primary PACS Server",
      "ae_title": "PRIMARYPACS",
      "hostname": "192.168.1.100",
      "port": 11112,
      "enabled": true,
      "priority": 1,
      "max_connections": 20,
      "timeout_seconds": 30,
      "retry_attempts": 3,
      "retry_delay_seconds": 5,
      "health_check_enabled": true,
      "health_check_interval_seconds": 60,
      "supported_services": ["C-STORE", "C-FIND", "C-GET", "C-MOVE", "C-ECHO"],
      "tls_enabled": false,
      "routing_rules": {
        "modality_filter": ["CT", "MR", "US"]
      },
      "load_balancing": {
        "weight": 100,
        "circuit_breaker_enabled": true,
        "failure_threshold": 5
      },
      "storage_mapping": {
        "local_storage_enabled": true,
        "forward_to_server": true,
        "duplicate_handling": "skip"
      }
    }
  ],
  "global_settings": {
    "load_balancing_mode": "weighted_round_robin",
    "failover_enabled": true,
    "connection_pooling_enabled": true
  }
}

Server parameters

Parameter Required Description
id Yes Unique server identifier
ae_title Yes DICOM AE Title
hostname Yes Server hostname or IP
port Yes DICOM port
priority No Routing priority (1 = highest)
supported_services No Supported DICOM services
transfer_syntaxes No Supported transfer syntaxes

Environment variables

DICOMPROXY_DicomPort=11112
DICOMPROXY_HttpPort=8080
DICOMPROXY_StoragePath=D:\DicomStorage

# Nested settings — use double underscores
DICOMPROXY_ThisModality__AE_Title=MYPROXY
DICOMPROXY_Security__EnableTLS=true

Command-line arguments

DicomProxyRTWindows.exe --DicomPort 11113 --HttpPort 8081 --StoragePath "D:\CustomStorage"
DicomProxyRTWindows.exe --ThisModality:AE_Title "CUSTOMPROXY" --Security:EnableTLS true
DicomProxyRTWindows.exe --help

Configuration templates

Minimal

{
  "DicomPort": 11112,
  "HttpPort": 8080,
  "StoragePath": "C:\\DicomStorage",
  "ThisModality": { "AE_Title": "DICOMPROXY" }
}

Production

{
  "DicomPort": 11112,
  "HttpPort": 8080,
  "HttpsPort": 8443,
  "StoragePath": "D:\\DicomStorage",
  "ThisModality": { "AE_Title": "PRODPROXY", "MaxConnections": 100 },
  "Security": {
    "EnableTLS": true,
    "CertificatePath": "certificate.pfx",
    "RequireAuthentication": true,
    "EnableAuditLogging": true
  },
  "Performance": { "MaxConcurrentConnections": 200, "MaxMemoryUsageMB": 8192 },
  "Storage": { "MaxStorageSizeGB": 5000, "RetentionDays": 2555 }
}

Next: API Reference