Contents show

Why backing up before migrating ColdFusion matters

Upgrading or migrating your ColdFusion stack improves Security, Performance, and supportability. Newer Adobe ColdFusion releases (and Lucee, if you are switching engines) bring updated JVM support, Security patches, better TLS/cipher defaults, and modern Features. But every upgrade carries risk. The only reliable safeguard is a comprehensive, verified backup that lets you roll back quickly if something breaks. The guide below explains precisely what to capture and provides practical steps to create consistent, restorable backups of your ColdFusion applications, Configuration, and related services before you migrate.

Prerequisites / Before You Start

Clarify scope and timeline
- Define what you will migrate: single server, clustered nodes, Scheduled tasks, Solr, PDFg, PMT, Redis, or external Microservices.
- Decide the Migration style: in‑place upgrade vs. side‑by‑side (blue‑green) Deployment.
- Establish a Maintenance window and a rollback plan with an acceptable RTO/RPO.
Validate Version compatibility
- Review the Adobe ColdFusion Support Matrix for JVM/JDK versions and OS/web server compatibility.
- Check dependent driver versions (JDBC for SQL Server/Oracle/MySQL/PostgreSQL), web server connectors (IIS/Apache), and third‑party libraries.
- Note any Deprecated tags/functions between your current CFML version and the target version.
Access, credentials, and tools
- Admin/root or appropriate privileges on OS, databases, ColdFusion Administrator (CFAdmin).
- Access to web servers (IIS Manager, Apache/Nginx conf), reverse proxies, and load balancers.
- Backup tools: tar/zip, PowerShell, cloud snapshot tools, and database clients (sqlcmd, mysqldump, pg_dump, RMAN).
- Optional: CommandBox with CFConfig for Configuration export/import.
- Disk space in a separate volume or remote storage for backups.
Change management
- Freeze feature releases before backup to keep the state stable.
- Communicate downtime windows; notify stakeholders and support.
Test environment
- Prepare a staging server that mirrors production (OS, filesystem semantics, web server, JVM) to validate backup integrity and test the Migration.

What to back up (scope and anatomy of a ColdFusion stack)

Backups must include application code, ColdFusion configuration, connectors, JVM and JEE container settings, databases, certificates/keystores, and environment variables. The following table highlights common items and default locations (adjust for your version or custom installs):

Item	What to back up	Typical paths (Windows)	Typical paths (Linux)
Application code and assets	CFML, CFCs, Custom tags, static assets, WEB-INF if JEE WAR/EAR	C:\inetpub\wwwroot\yourapp\	/var/www/yourapp/ or app path
ColdFusion Admin config (neo files)	neo-*.xml, cfusion/lib configuration	C:\ColdFusion2021\cfusion\lib\	/opt/ColdFusion2021/cfusion/lib/
JVM settings	jvm.config, jre/jdk version info	C:\ColdFusion2021\cfusion\bin\jvm.config	/opt/ColdFusion2021/cfusion/bin/jvm.config
Tomcat/JEE config	server.xml, web.xml, context.xml	C:\ColdFusion2021\cfusion\runtime\conf\	/opt/ColdFusion2021/cfusion/runtime/conf/
Web server connector config	wsconfig directories, IIS sites, httpd.conf	C:\ColdFusion2021\cfusion\config\wsconfig\ and IIS applicationHost.config	/opt/ColdFusion2021/cfusion/config/wsconfig/ and Apache conf
CF packages/modules	cfpm list (PDFg, Solr, Image, etc.)	C:\ColdFusion2021\cfusion\bin\cfpm.bat	/opt/ColdFusion2021/cfusion/bin/cfpm.sh
Logs	server and application logs	C:\ColdFusion2021\cfusion\logs\	/opt/ColdFusion2021/cfusion/logs/
Scheduled tasks	task definitions and files	neo-cron.xml, related local paths	neo-cron.xml, related local paths
Datasources and mail	connection settings	neo-datasource.xml, neo-mail.xml	neo-datasource.xml, neo-mail.xml
Certificates/keystores	cacerts, custom keystores	jre\lib\security\cacerts or custom .jks	jre/lib/security/cacerts or custom .jks
Environment and secrets	.env, service accounts, OS env vars	System/user environment, secret stores	Shell env, systemd Environment files
Databases	consistent dumps / snapshots	SQL Server backups, flat files	MySQL/Postgres/Oracle dumps or snapshots

Also consider Solr collections, PMT configuration/data, Redis, and any file-based blob stores or S3 buckets your app relies on.

Step-by-step backup and Pre-migration procedure

1) Freeze changes and notify

Put deployments on hold; tag the current commit in Git (e.g., release/Pre-migration).
Announce the Maintenance window and outline the rollback plan.

2) Create system snapshots

If running on VMware/Hyper‑V or cloud (AWS EBS, Azure Managed Disks), create VM/disk snapshots first. This gives a fast, coarse-grained rollback option.
Ensure application services are in a quiescent state for the snapshot if you rely on it as a primary backup.

3) Back up application code and binary assets

Include CFML files, components (CFC), Custom tags, Application.cfc, frameworks (ColdBox, FW/1), static assets, and build artifacts.
Example (Linux):

tar –exclude=’*.log’ -czf /backups/app-$(date +%F).tar.gz /var/www/yourapp
sha256sum /backups/app-$(date +%F).tar.gz > /backups/app-$(date +%F).sha256

Example (Windows PowerShell):

$Date=(Get-Date -Format yyyy-MM-dd)
Compress-Archive -Path “C:\inetpub\wwwroot\yourapp*” -DestinationPath “D:\backups\app-$Date.zip”
Get-FileHash “D:\backups\app-$Date.zip” -Algorithm SHA256 | Out-File “D:\backups\app-$Date.sha256”

4) Export ColdFusion Administrator configuration

Back up via at least one of these methods (two is better):

Using CAR (ColdFusion Archive), if available on your version
- CFAdmin > Packaging & Deployment > ColdFusion Archives.
- Create a new archive; include datasources, mappings, mail, caches, scheduled tasks, Security settings, and custom tag paths.
- Save the CAR file and copy it to backup storage.
- Note: Some secrets and passwords may not export in plaintext. Retain notes on those.
Using CFConfig (CommandBox)
- Install CommandBox and CFConfig.
- Export CFAdmin settings to a JSON/YAML file:

box install commandbox-cfconfig
cfconfig export –from=/opt/ColdFusion2021/cfusion –to=/backups/cfadmin-2021.json –engine=adobe@2021

You can later import to a clean server or a newer version with:

cfconfig import –to=/opt/ColdFusion2023/cfusion –from=/backups/cfadmin-2021.json –engine=adobe@2023

Manual copy of neo-*.xml and related files
- Stop ColdFusion to ensure consistency.
- Copy the contents of cfusion/lib where configuration lives:

systemctl stop coldFusion2021
tar -czf /backups/cfusion-lib-$(date +%F).tar.gz /opt/ColdFusion2021/cfusion/lib
systemctl start coldFusion2021

Key files: neo-datasource.xml, neo-mail.xml, neo-cron.xml, neo-runtime.xml, neo-security.xml.
Keep the encryption seed/password files that ColdFusion uses for secrets intact (back them up with the lib directory). Without these, encrypted passwords may not restore cleanly.

5) Back up web server connectors and configuration

Copy ColdFusion connector directories:
- {cf_home}/cfusion/config/wsconfig//
Back up the web Server configuration:
- IIS: applicationHost.config and site bindings, SSL certificates.
- Apache: httpd.conf, conf.d/*.conf, vhost files, modules, and SSL certs.
Example (Linux, Apache):

tar -czf /backups/apache-conf-$(date +%F).tar.gz /etc/httpd/conf /etc/httpd/conf.d /opt/ColdFusion2021/cfusion/config/wsconfig

6) Back up JEE/Tomcat and JVM configs

Tomcat configuration:
- server.xml, web.xml, context.xml under cfusion/runtime/conf.
JVM configuration:
- jvm.config under cfusion/bin (heap sizes, GC flags, JVM args).
Example:

tar -czf /backups/cf-runtime-conf-$(date +%F).tar.gz /opt/ColdFusion2021/cfusion/runtime/conf /opt/ColdFusion2021/cfusion/bin/jvm.config

7) Capture ColdFusion Package Manager state (cfpm)

List installed modules (PDFg, Solr, Image, SAML, etc.) and save the output:

/opt/ColdFusion2021/cfusion/bin/cfpm.sh list > /backups/cfpm-packages-$(date +%F).txt
“C:\ColdFusion2021\cfusion\bin\cfpm.bat” list > D:\backups\cfpm-packages-%date:~10,4%-%date:~4,2%-%date:~7,2%.txt

8) Back up scheduled tasks and their targets

The definitions live in neo-cron.xml; also capture any folders where tasks read/write files (exports, temp, FTP mirrors).
If tasks use OS schedulers (cron, Task Scheduler), export those too.

9) Capture logs and monitoring data

ColdFusion logs assist with post-migration Troubleshooting; compress cfusion/logs.
If using the Performance Monitoring Toolset (PMT), export its configuration/database.

10) Perform consistent database backups

Prefer native tools for consistency and point-in-time recovery.
SQL Server:

sqlcmd -S yourserver -Q “BACKUP DATABASE [YourDB] TO DISK=’D:\backups\YourDB_full.bak’ WITH INIT, COPY_ONLY”

MySQL/MariaDB:

mysqldump –single-transaction –routines –triggers -h dbhost -u backup -p YourDB | gzip > /backups/YourDB-$(date +%F).sql.gz

PostgreSQL:

pg_dump -h dbhost -U backup -F c -f /backups/YourDB-$(date +%F).dump YourDB

Oracle: use RMAN or expdp/impdp as per policy.

11) Verify backup integrity

Compute checksums (SHA256) for all archives and verify.
Test-restore on staging: unpack, import CFConfig/CAR, start ColdFusion, and run smoke tests. A backup is only as good as a successful restore.

12) Securely store and document

Store backups offsite and immutable (object lock or WORM when possible).
Document versions:
- ColdFusion build number and Update level.
- JVM vendor and version.
- Connector version.
- Web server version.
- Database versions and JDBC driver versions.
Record the exact commands used and locations so anyone can execute a rollback quickly.

Risks, common issues, and how to avoid them

Encrypted credentials don’t restore across seeds
- Risk: Datasource/mail passwords are encrypted using a seed unique to the installation; moving only neo-*.xml to a fresh server can break decryption.
- Avoidance: Back up the entire cfusion/lib directory (including encryption seed files) or use CFConfig with environment variable substitution to re‑inject secrets on import.
Connector and JVM incompatibility
- Risk: Mismatched IIS/Apache connector with the new runtime or an unsupported JDK causes 500 errors or HTTP 503.
- Avoidance: Use the wsconfig tool matching the target ColdFusion build. Validate with the support matrix; upgrade the JDK as recommended for the target CF version.
Missing ColdFusion packages After migration
- Risk: Features like PDFg, Solr collections, or Image functions fail if packages weren’t reinstalled.
- Avoidance: Capture cfpm list and reinstall with cfpm on the new server; export/import Solr cores where applicable.
File permission and SELinux issues
- Risk: New hosts enforce stricter permissions; ColdFusion can’t read/write temp, logs, or task directories.
- Avoidance: Replicate permissions/ownerships and SELinux contexts; validate with restorecon and Audit logs.
Path changes and case sensitivity
- Risk: Moving from Windows to Linux can break code that assumes case-insensitive paths or backslashes.
- Avoidance: Standardize path handling in code; test thoroughly on a case-sensitive filesystem in staging.
32/64-bit driver mismatches
- Risk: ODBC/JDBC drivers differ across architectures; legacy 32‑bit DSNs fail.
- Avoidance: Replace with supported 64‑bit JDBC drivers; test connectivity in CFAdmin before cutover.
TLS/certificate problems
- Risk: Outbound mail, web service calls, or database SSL break due to missing CA roots or keystore changes.
- Avoidance: Export/import keystores; validate outbound HTTPS and SMTPS with test calls.
Duplicate or missing scheduled tasks
- Risk: Tasks may run twice in a clustered migration or not at all.
- Avoidance: Disable tasks on old nodes during cutover; verify schedules and “Unique ID”s on the new node(s).
Performance regressions due to GC or heap changes
- Risk: Different JVM/G1 settings alter GC behavior.
- Avoidance: Mirror jvm.config flags; baseline and tune heap/GC After migration with monitoring.

Post‑migration Checklist / validation steps

ColdFusion Administrator
- Confirm you can log in; verify license, Administrator password, and Security settings.
- Check all mappings, custom tag paths, and client/session settings.
- Validate packages installed (cfpm list).
Datasources
- Test each datasource in CFAdmin.
- Run representative queries from the app and check connection pools.
Scheduled tasks
- Confirm task list and schedules; run a manual execution for a sample.
- Ensure duplicate tasks are disabled on old nodes.
Email and integrations
- Send a test email through configured SMTP.
- Test external service calls (REST/SOAP), S3, Payment gateways, and Message queues.
Web server and connectors
- Confirm site bindings (HTTP/HTTPS), SSL certificates, and connector status.
- Review web Server logs and ColdFusion logs for errors or 500s.
Application smoke tests
- Critical paths: login, search, create/update/delete, File upload/Download, PDF generation, Image processing.
- Validate caching behavior and session stickiness in clusters.
Performance and stability
- Compare response times and error rates to pre‑migration baselines.
- Monitor heap usage, GC pauses, and thread pools.
Security and Compliance
- Verify TLS versions/ciphers, HSTS, and headers.
- Ensure CF Admin lockdown settings mirrored; confirm file/folder permissions.
Backups and monitoring
- Re-enable routine backups on the new environment.
- Ensure alerts and PMT/monitoring dashboards reflect the new hosts.
Rollback ready
- Keep old environment intact (but isolated) until you pass burn‑in and soak tests.
- Validate that your pre‑migration backup can restore in staging.

Examples: backup scripts and configuration snippets

Linux: minimalist ColdFusion backup script

!/usr/bin/env bash

set -euo pipefail

DATE=$(date +%F)
BKP=/backups/$DATE
CFHOME=/opt/ColdFusion2021/cfusion

mkdir -p “$BKP”

Stop CF for consistent neo files (optional if using CAR/CFConfig)

systemctl stop coldFusion2021 || true

tar -czf “$BKP/cfusion-lib.tgz” “$CFHOME/lib”
tar -czf “$BKP/cf-runtime-conf.tgz” “$CFHOME/runtime/conf” “$CFHOME/bin/jvm.config”
tar -czf “$BKP/wsconfig.tgz” “$CFHOME/config/wsconfig”
tar -czf “$BKP/cf-logs.tgz” “$CFHOME/logs”

Start CF again

systemctl start coldFusion2021

Application code

tar -czf “$BKP/app.tgz” /var/www/yourapp

Web server (Apache)

tar -czf “$BKP/apache.tgz” /etc/httpd/conf /etc/httpd/conf.d

CF packages list

$CFHOME/bin/cfpm.sh list > “$BKP/cfpm-packages.txt”

Checksums

sha256sum “$BKP”/*.tgz > “$BKP/SHA256SUMS”

Windows: PowerShell snapshot of ColdFusion config

$Date = Get-Date -Format “yyyy-MM-dd”
$Bkp = “D:\backups\$Date”
$CF = “C:\ColdFusion2021\cfusion”

New-Item -ItemType Directory -Force -Path $Bkp | Out-Null

Optionally stop service for consistent files

Stop-Service -Name “ColdFusion 2021 Application Server” -ErrorAction SilentlyContinue

Compress-Archive -Path “$CF\lib*” -DestinationPath “$Bkp\cfusion-lib.zip”
Compress-Archive -Path “$CF\runtime\conf*” -DestinationPath “$Bkp\cf-runtime-conf.zip”
Copy-Item “$CF\bin\jvm.config” “$Bkp\jvm.config”
Compress-Archive -Path “$CF\config\wsconfig*” -DestinationPath “$Bkp\wsconfig.zip”
Compress-Archive -Path “$CF\logs*” -DestinationPath “$Bkp\logs.zip”

Start-Service -Name “ColdFusion 2021 Application Server”

App code and IIS config

Compress-Archive -Path “C:\inetpub\wwwroot\yourapp*” -DestinationPath “$Bkp\app.zip”
Copy-Item “C:\Windows\System32\inetsrv\config\applicationHost.config” “$Bkp\applicationHost.config”

Packages

& “$CF\bin\cfpm.bat” list | Out-File “$Bkp\cfpm-packages.txt”

Example: noting critical JVM options (jvm.config excerpt)

Xmx and GC settings matter; mirror them on the new server initially

-java.home=C:\ColdFusion2021\jre
-XX:+UseG1GC
-Xms4g
-Xmx4g
-XX:MaxGCPauseMillis=200
-Dcoldfusion.home=C:\ColdFusion2021\cfusion
-Dfile.encoding=UTF-8

Tip: Keep heap and GC identical for initial parity; tune after migration.

Additional guidance and Best practices

Keep secrets out of backups where feasible
- Use environment variables or a secrets manager and re-inject at restore time.
- If backups contain secrets (e.g., neo-*.xml with encrypted values), enforce encryption-at-rest and strict access controls.
Prefer side-by-side migrations
- Build a new ColdFusion node with the target version, restore backups, and cut traffic over with a load balancer or DNS switch. This minimizes downtime and preserves rollback.
Document everything
- Maintain a migration runbook: commands, versions, paths, contacts, and acceptance criteria.
Test early with representative data
- Restore database snapshots and a subset of files to staging; measure functionality and performance.

FAQ

How do I migrate ColdFusion Admin settings between different versions safely?

Use a combination of CFConfig and CAR files. CFConfig exports CFAdmin settings to a portable JSON/YAML that can be imported into another version (adobe@2016 → adobe@2021/adobe@2023). For items CFConfig can’t handle or when you prefer native tooling, a CAR export helps. Always validate on staging, and be mindful that encrypted passwords may need to be re-entered or injected via environment variables.

Should I stop ColdFusion before copying neo-*.xml configuration files?

It’s safer to stop the service to avoid partially written XML. If downtime isn’t acceptable, use CFConfig or CAR to export live, then later stop CF briefly to take a consistent filesystem backup. In all cases, test restoration in staging.

What’s the best way to back up IIS/Apache connectors?

Back up both the connector’s wsconfig directories and the web server’s own configuration. For IIS, export applicationHost.config and any SSL certificates; for Apache, capture httpd.conf, conf.d/vhost files, and the ColdFusion mod_jk or AJP connector configs within cfusion/config/wsconfig.

Can I rely on virtual machine snapshots alone?

Snapshots are great for fast rollback but shouldn’t be your only backup. Use application-consistent database backups and file archives too. Test a full restore to a clean server to ensure you’re not depending on VM-specific state.

Will my datasource passwords work after migration?

They will if you migrate the entire cfusion/lib directory (keeping the encryption seed) or if you re-enter the passwords on the new server. If you export via CFConfig, consider using environment variable placeholders for secrets and inject them during import to avoid seed-related issues.