Server Settings - Java and JVM

Overview

ColdFusion runs on the Java Virtual Machine (JVM), and proper JVM configuration is critical for optimal performance, stability, and scalability. The Java and JVM settings page allows you to configure the Java version, JVM arguments, heap memory, garbage collection, and class paths that ColdFusion uses.

Understanding JVM tuning is essential for running production ColdFusion applications. Poor JVM configuration can lead to out-of-memory errors, long garbage collection pauses, and poor performance. This guide provides best practices for configuring the JVM for ColdFusion 2021 and 2023 (ColdFusion 2025).

Java Virtual Machine Path

Java Home Directory

• Purpose: Specifies the Java installation directory ColdFusion uses
• Location: Path to JRE or JDK root directory
• Example (Windows): C:\Program Files\Java\jdk-11.0.18
• Example (Linux): /usr/lib/jvm/java-11-openjdk
• Requirement: Must be compatible Java version for your CF version

Supported Java Versions

• ColdFusion 2023 (2025): Java 11, 17, or 21 (21 recommended)
• ColdFusion 2021: Java 11 (11.0.12 or higher)
• ColdFusion 2018: Java 8 or 11
• Recommendation: Use latest LTS version supported by your CF version
• Updates: Keep Java updated for security patches

JRE vs JDK

• JRE (Java Runtime Environment): Sufficient for running ColdFusion
• JDK (Java Development Kit): Required for certain features
• Java-based debugging tools
• JSP compilation
• Dynamic proxy generation
• Recommendation: Install JDK for full functionality

Changing Java Version

• Update Java Home path in administrator
• Restart ColdFusion for changes to take effect
• Verify compatibility with your ColdFusion version
• Test thoroughly before deploying to production
• Update JVM arguments as needed for new Java version

JVM Heap Memory Settings

Initial Heap Size (-Xms)

• Purpose: Starting heap memory allocation
• Argument: -Xms<size> (e.g., -Xms2048m or -Xms2g)
• Default: Varies by system (often 256MB-512MB)
• Recommendation: Set equal to maximum heap size (-Xmx)
• Benefit: Prevents heap resizing overhead during startup
• Example: -Xms4g (4 gigabytes)

Maximum Heap Size (-Xmx)

• Purpose: Maximum heap memory JVM can use
• Argument: -Xmx<size> (e.g., -Xmx4096m or -Xmx4g)
• Default: 512MB (CF 2018) or 1GB (CF 2021+)
• Recommendation: 2-8GB for typical applications, 8-16GB for high-traffic sites
• Maximum: 75% of available system RAM (leave room for OS and other processes)
• 32-bit Limit: ~1.5GB on Windows, ~2GB on Linux (use 64-bit Java)

Heap Sizing Best Practices

• Always use 64-bit Java for production (no 4GB heap limit)
• Set -Xms equal to -Xmx to avoid heap resizing
• Start with 2-4GB for small applications, increase as needed
• Monitor heap usage and adjust based on actual needs
• Leave 25-50% of system RAM for OS, file system cache, and other apps
• Larger heaps mean longer garbage collection pauses (diminishing returns beyond 8-16GB)

Calculating Heap Size

• Formula: Max Heap = (Peak Memory Usage × 1.5) + headroom
• Example: Peak 2GB usage → 3-4GB max heap
• Rule of Thumb: Heap should be ~50-70% utilized at peak load
• Too Small: Frequent OutOfMemoryErrors
• Too Large: Long GC pauses, wasted memory

Metaspace (Java 8+)

• Purpose: Stores class metadata (replaced PermGen in Java 8+)
• Initial Size: -XX:MetaspaceSize=512m
• Maximum Size: -XX:MaxMetaspaceSize=512m
• Default: Unlimited (grows as needed)
• Recommendation: Set explicit limit (256-512MB typical)
• Consideration: Increase for applications with many classes/JARs

Garbage Collection Settings

Garbage Collection Overview

• Purpose: Automatically reclaim memory from unused objects
• Impact: GC pauses can cause request delays
• Goal: Minimize pause times while maintaining throughput
• Tuning: Choose appropriate GC algorithm for your workload

G1GC (Garbage First Collector) - Recommended

• Enable: -XX:+UseG1GC
• Default: ColdFusion 2021+ (Java 11+)
• Benefits:
• Low pause times (typically <1 second)
• Good for heaps 4GB+ (up to 64GB+)
• Predictable pause time targets
• Better for multi-core systems
• Recommended For: All modern ColdFusion applications

G1GC Configuration

• -XX:+UseG1GC: Enable G1 garbage collector
• -XX:MaxGCPauseMillis=200: Target max pause time (default 200ms)
• -XX:G1ReservePercent=20: Reserve memory to prevent to-space overflow
• -XX:InitiatingHeapOccupancyPercent=45: Start concurrent GC at 45% heap usage
• -XX:G1HeapRegionSize=16m: Region size (auto-calculated by default)

Other Garbage Collectors

• ParallelGC: High throughput, longer pauses
• Good for batch processing, not web apps
• -XX:+UseParallelGC
• CMS (Deprecated): Concurrent Mark Sweep
• Removed in Java 14+
• Legacy applications only
• ZGC/Shenandoah: Ultra-low latency (Java 11+)
• Experimental, not widely tested with CF
• Consider for very large heaps (>64GB)

GC Logging (Essential for Tuning)

• Java 11+ Syntax:
• -Xlog:gc*:file=/path/to/gc.log:time,uptime,level,tags
• -Xlog:gc*=info:file=/path/to/gc.log:time
• Java 8 Syntax:
• -XX:+PrintGCDetails
• -XX:+PrintGCDateStamps
• -Xloggc:/path/to/gc.log
• Log Rotation: -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=20M
• Analysis Tools: GCViewer, GCEasy.io, VisualVM

JVM Arguments

What Are JVM Arguments?

• Purpose: Command-line options that control JVM behavior
• Categories: Standard (-X), experimental (-XX), debugging (-D)
• Application: Set in administrator or jvm.config file
• Effect: Require server restart to apply

Essential Production JVM Arguments

• Heap Memory:
• -Xms4g -Xmx4g (adjust size as needed)
• Garbage Collection:
• -XX:+UseG1GC
• -XX:MaxGCPauseMillis=200
• Metaspace:
• -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=512m
• GC Logging:
• -Xlog:gc*:file=/var/log/coldfusion/gc.log:time
• Heap Dumps on OOM:
• -XX:+HeapDumpOnOutOfMemoryError
• -XX:HeapDumpPath=/var/log/coldfusion/heapdumps/

Performance Tuning Arguments

• -server: Use server JVM (optimized for long-running processes)
• -XX:+AggressiveOpts: Enable experimental performance optimizations (use cautiously)
• -XX:+UseBiasedLocking: Improve synchronization performance (default in most JVMs)
• -XX:+OptimizeStringConcat: Optimize string concatenation
• -Djava.awt.headless=true: Headless mode (no GUI, required for servers)

Debugging and Monitoring Arguments

• Remote JMX Monitoring:
• -Dcom.sun.management.jmxremote
• -Dcom.sun.management.jmxremote.port=9999
• -Dcom.sun.management.jmxremote.authenticate=false
• -Dcom.sun.management.jmxremote.ssl=false
• Note: Secure JMX in production (enable auth/SSL)
• Flight Recorder (Java 11+):
• -XX:StartFlightRecording=duration=60s,filename=/tmp/recording.jfr

Security Arguments

• -Djava.security.egd=file:/dev/./urandom: Use non-blocking random for faster startup
• -Dcoldfusion.disablejmxsockets=true: Disable JMX sockets if not needed
• -Djdk.tls.client.protocols=TLSv1.2,TLSv1.3: Restrict TLS versions

ColdFusion-Specific Arguments

• -Dcoldfusion.home=/opt/coldfusion/cfusion: CF installation directory
• -Dcoldfusion.rootdir=/opt/coldfusion/cfusion: CF root directory
• -Dcoldfusion.libdir=/opt/coldfusion/cfusion/lib: CF library directory
• -Dcoldfusion.classPath=/path/to/custom.jar: Add custom JARs to classpath

Class Path Configuration

What Is the Class Path?

• Purpose: Directories and JAR files where JVM searches for classes
• Default: ColdFusion automatically includes its libraries
• Custom: Add third-party JARs and custom Java classes
• Separator: Semicolon (;) on Windows, colon (:) on Linux/Unix

Adding Custom JARs

• Option 1: Place JARs in /cfusion/lib/ directory (auto-loaded)
• Option 2: Add to class path via administrator
• Option 3: Use -Dcoldfusion.classPath argument
• Recommendation: Use /lib directory for simplicity
• Restart Required: Server restart needed after adding JARs

Common Class Path Additions

• JDBC Drivers: Custom database drivers
• External Libraries: Apache POI, iText, etc.
• Custom Java Classes: Java utilities called from CFML
• Framework JARs: Spring, Hibernate, etc.

Class Path Best Practices

• Keep JARs organized in /lib directory when possible
• Document all custom JARs and their versions
• Check for version conflicts between JARs
• Remove unused JARs to reduce memory footprint
• Test thoroughly after adding new JARs

Recommended JVM Settings by Environment

Development Environment

• Heap: -Xms1g -Xmx2g (smaller is fine)
• GC: -XX:+UseG1GC (default is fine)
• Debugging: Enable JMX, verbose GC logging
• Metaspace: -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m
• Focus: Ease of debugging over performance

Test/Staging Environment

• Heap: Match production settings
• GC: -XX:+UseG1GC with production tuning
• Logging: Full GC logging for analysis
• Monitoring: Enable all monitoring for performance testing
• Focus: Replicate production as closely as possible

Production Environment - Small Application

• Heap: -Xms2g -Xmx2g
• GC: -XX:+UseG1GC -XX:MaxGCPauseMillis=200
• Metaspace: -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m
• GC Log: -Xlog:gc*:file=/var/log/coldfusion/gc.log:time
• OOM Dumps: -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/coldfusion/

Production Environment - Medium Application

• Heap: -Xms4g -Xmx4g
• GC: -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:G1ReservePercent=20
• Metaspace: -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=512m
• GC Log: -Xlog:gc*:file=/var/log/coldfusion/gc.log:time (with rotation)
• Additional: -XX:+UseStringDeduplication (saves memory with many duplicate strings)

Production Environment - Large Application

• Heap: -Xms8g -Xmx8g (or higher based on needs)
• GC: -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:G1ReservePercent=20
• Metaspace: -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=1g
• GC Tuning: -XX:InitiatingHeapOccupancyPercent=45
• Large Pages: -XX:+UseLargePages (if OS configured)
• String Dedup: -XX:+UseStringDeduplication

Common Issues and Troubleshooting

OutOfMemoryError: Java Heap Space

• Symptom: Application crashes with heap space error
• Causes:
• Heap size too small for application load
• Memory leak in application code
• Too many concurrent sessions
• Large objects stored in memory
• Solutions:
• Increase heap size (-Xmx)
• Analyze heap dump to find memory leaks
• Reduce session timeout or session data size
• Implement object pooling or caching strategies

OutOfMemoryError: Metaspace

• Symptom: Metaspace exhausted
• Causes:
• Too many classes loaded
• Class loader leak (classes not unloaded)
• Excessive use of dynamic proxies
• Solutions:
• Increase MaxMetaspaceSize
• Investigate class loader leaks
• Reduce number of loaded classes

Long Garbage Collection Pauses

• Symptom: Application becomes unresponsive periodically
• Causes:
• Heap too large (GC takes longer)
• Wrong GC algorithm for workload
• Heap nearly full (frequent full GCs)
• Solutions:
• Switch to G1GC if not already using
• Tune MaxGCPauseMillis target
• Increase heap size if utilization >80%
• Reduce heap size if pauses exceed targets

High CPU Usage from GC

• Symptom: CPU constantly high, mostly GC activity
• Cause: Heap too small or memory leak
• Solutions:
• Increase heap size
• Analyze GC logs to identify pattern
• Check for memory leaks with heap dump

ColdFusion Won't Start After JVM Changes

• Symptom: Service fails to start
• Causes:
• Invalid JVM argument syntax
• Heap size exceeds available memory
• Incompatible Java version
• Solutions:
• Check ColdFusion logs for error details
• Verify JVM argument syntax
• Reduce heap size if too large
• Manually edit jvm.config to revert changes

JVM Monitoring and Analysis

Key Metrics to Monitor

• Heap Usage: Current vs max, utilization percentage
• GC Frequency: Minor and major GC events per minute
• GC Pause Time: Duration of GC pauses
• Metaspace Usage: Class metadata memory consumption
• Thread Count: Active threads and thread pool usage
• CPU Usage: Overall and GC-related CPU time

Monitoring Tools

• VisualVM: Free JVM monitoring and profiling tool
• JConsole: Built-in JMX console (comes with JDK)
• Java Mission Control: Advanced profiling (JDK 11+)
• FusionReactor: Commercial CF/JVM monitoring (comprehensive)
• SeeFusion: Real-time CF monitoring
• GCViewer: GC log analysis tool
• GCEasy.io: Online GC log analyzer

Analyzing Heap Dumps

• When to Capture: Memory leaks, OOM errors, high memory usage
• How to Capture:
• Automatic: -XX:+HeapDumpOnOutOfMemoryError
• Manual: jmap -dump:live,format=b,file=heap.hprof <pid>
• Analysis Tools:
• Eclipse Memory Analyzer (MAT)
• VisualVM
• YourKit Java Profiler
• What to Look For: Large object retention, leak suspects, dominator tree

GC Log Analysis

• Upload logs to GCEasy.io for automated analysis
• Look for frequent full GCs (indicates heap pressure)
• Check pause times against MaxGCPauseMillis target
• Identify memory allocation patterns
• Monitor heap occupancy before/after GC

Best Practices

Configuration Best Practices

• Always set -Xms equal to -Xmx (prevents heap resizing)
• Use G1GC for all modern ColdFusion applications
• Enable heap dump on OOM for troubleshooting
• Configure GC logging with rotation
• Set explicit Metaspace limits
• Use 64-bit Java for production (no heap limitations)
• Document all JVM arguments in deployment procedures

Performance Tuning Best Practices

• Start with conservative settings and tune based on metrics
• Monitor GC behavior under load before tuning
• Make one change at a time and measure impact
• Test changes in staging before production
• Keep heap size reasonable (4-16GB typical, rarely >32GB)
• Leave 25-50% RAM for OS and file system cache

Security Best Practices

• Keep Java updated with latest security patches
• Secure JMX access with authentication and SSL
• Restrict file system access to heap dump directory
• Use non-blocking random number generator
• Disable unnecessary JVM features

Maintenance Best Practices

• Review GC logs monthly for degradation
• Monitor heap usage trends over time
• Plan for periodic server restarts (weekly/monthly)
• Keep backup of working jvm.config
• Test Java updates in non-production first

Related Resources