Migration - Upgrades

How to Migrate ColdFusion Admin Settings to New Server

by Aaron Longnion
10 min read
Contents show

Why this Migration/upgrade is important

Moving your ColdFusion Administrator settings to a new server is more than a simple lift-and-shift. It’s a chance to standardize configurations, apply latest Security patches, modernize Java, and formalize “Infrastructure as code” for CF Admin settings. Doing it methodically reduces downtime, avoids broken datasources and Scheduled tasks, and creates a reproducible baseline for future environments (dev, test, prod). When planned properly, you’ll end up with a faster, more secure, and more maintainable ColdFusion platform.

Prerequisites / Before You Start

  • Ensure you have clear change windows and rollback plans.
  • Decide on the Migration method: cfsetup (CF2021/2023), CAR files, copying neo-*.xml, or Admin API scripting.

Supported versions and compatibility considerations

  • Adobe ColdFusion 2018, 2021, 2023 are widely used. Features differ between versions:
    • cfsetup (Admin as Code) is available in CF2021+ (improved in CF2023).
    • ColdFusion Archive (CAR) has been available in Enterprise editions for many versions; compatibility across major versions is limited.
    • Directly copying neo-*.xml is safest across identical versions/builds.
  • Ensure the new server’s JDK/JRE meets your ColdFusion version requirements.
  • Connector compatibility:
    • IIS/Apache connectors must match OS and ColdFusion version/bitness.
  • If moving across major versions, confirm any deprecated settings (e.g., some charting, PDFG, or built-in Solr components have changed).

Inventory Checklist

Create a complete inventory of CF Admin items and related system dependencies:

  • ColdFusion Admin settings:
  • JVM:
    • Heap settings, GC options (jvm.config)
    • Certificates in cacerts/keystores
  • Filesystem:
  • Web server:
    • IIS/Apache connector Configuration
    • Virtual Hosts, Application Pools, rewrite rules
  • Packages/Modules:
    • CF Package Manager (cfpm) components (e.g., spreadsheet, aws, pdf, image)
  • Licensing:
    • Serial numbers or license files for Adobe ColdFusion (Standard/Enterprise).
  • Security:
    • Lockdown status, OS hardening, service account rights

Access and credentials

  • CF Admin password(s) for old and new servers
  • OS admin access to both servers
  • Database credentials for DSNs
  • Mail server credentials
  • SSL/TLS keystore passwords
  • Access to web server (IIS/Apache) and DNS

Backups to capture

  • Full ColdFusion instance directory (e.g., C:\ColdFusion2023\cfusion or /opt/ColdFusion2023/cfusion)
  • neo-*.xml config files (cfusion/lib/)
  • password.properties (encryption seed)
  • jvm.config
  • JDBC drivers and custom jars
  • Certificates/keystores (cacerts and custom keystore files)
  • CAR exports, cfsetup profiles, Admin API export scripts
  • Web server configs and connector config
See also  How to Migrate from ColdFusion 2016 to ColdFusion 2023

Change freeze and Maintenance window

  • Freeze code changes during migration
  • Schedule a Maintenance window for cutover
  • Notify stakeholders and DBAs

Migration strategies at a glance

Strategy A: cfsetup (CF2021/2023) — recommended, scriptable

  • Treat ColdFusion Administrator as code.
  • Export a JSON profile from the old server and import it into the new server.
  • Great for repeatable, version-controlled migrations.

Strategy B: ColdFusion Archive (CAR)

  • Package Admin resources (DSNs, mappings, scheduled tasks) into a CAR file.
  • Enterprise feature; be mindful of cross-Version compatibility.
  • GUI-driven or scriptable via Admin API.

Strategy C: Copying neo-*.xml and password.properties

  • Pragmatic for same-version migrations.
  • Fastest, but brittle across differing versions/builds.
  • Requires copying the password seed to preserve encrypted values.

Strategy D: Admin API scripting

  • Programmatically create DSNs, mail settings, scheduled tasks, etc.
  • Fine-grained control; works across versions with some API changes.
  • Good fallback or for mixed approaches.

Which one should you choose?

  • CF2021/2023 to CF2021/2023: cfsetup is usually best.
  • Older to newer versions: CAR or Admin API reduce risk; test carefully.
  • Same version/build: copying neo-*.xml plus password.properties is feasible.
  • Complex/regulated environments: Admin API/cfsetup for auditable code.

Step-by-step Migration guide

  1. Align versions, updates, and platform
  • Patch the old and new ColdFusion servers to the latest available update for their major versions.
  • Align JDK versions supported by your CF version.
  • Confirm OS-level dependencies (prereqs for IIS/Apache, firewall, permissions).
  1. Export settings from the old server

  • Option A — cfsetup export (CF2021+):

    • On the old server, create a profile:

      cfsetup profile export \
      –host http://localhost:8500 \
      –username admin \
      –password “YourAdminPassword” \
      oldserver-profile.json

    • Consider splitting into multiple profiles or excluding secrets if you’ll re-enter them.

  • Option B — CAR file (CF Enterprise):

    • In the ColdFusion Administrator, use Packaging & Deployment > ColdFusion Archives.
    • Create a CAR selecting components (Datasources, Mappings, CF Admin settings, Scheduled Tasks).
    • Save the .car file.

  • Option C — Copy Configuration files (same version/build):

    • Copy from cfusion/lib/:
      • password.properties (encryption seed)
      • neo-datasource.xml, neo-mail.xml, neo-cron.xml, neo-mapping.xml, neo-runtime.xml, neo-security.xml, neo-logging.xml, neo-monitoring.xml, etc.
    • Note any absolute paths that will differ on the new server.

  • Option D — Admin API extraction (script your export if needed):

    • Write CFML to enumerate DSNs, mappings, tasks, and write to JSON.
    • This is custom but provides maximum control.
  1. Prepare the new server environment

  • Install the same or target ColdFusion version.

  • Apply all updates.

  • Set JVM options in jvm.config (heap, GC, -D flags).

  • Install JDBC drivers into {cf_instance}/lib/ or proper location.

  • Install needed CF packages with cfpm:

    cfpm list
    cfpm install spreadsheet,aws,pdf,image

  • Harden the OS and CF (consider Adobe Lockdown Tool).

  • Create service account(s) and file permissions for logs, temp, and application directories.

  1. Import settings into the new server

  • Option A — cfsetup import:

    cfsetup profile import oldserver-profile.json \
    –host http://newserver:8500 \
    –username admin \
    –password “NewAdminPassword”

    • Review any items flagged as incompatible.

  • Option B — CAR Deployment:

    • In the new server’s Admin, import the .car file.
    • Map any path differences during import.

  • Option C — Copy neo-*.xml and password.properties:

    • Stop ColdFusion service on the new server.
    • Backup existing cfusion/lib.
    • Copy the selected neo-*.xml files and password.properties.
    • Start ColdFusion; review logs for errors.

  • Option D — Admin API scripts:

    • Run your CFML scripts to create DSNs, mappings, scheduled tasks, and mail settings.
    • Store these scripts in Version control for repeatability.
  1. Recreate web server connectors (IIS/Apache)

  • On Windows (IIS):

    “C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -list
    “C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -add -ws iis -siteid 1

  • On Linux (Apache):

    /opt/ColdFusion2023/cfusion/runtime/bin/wsconfig.sh -list
    /opt/ColdFusion2023/cfusion/runtime/bin/wsconfig.sh -add -ws Apache \
    -bin /usr/sbin/httpd \
    -dir /etc/httpd/conf

  • Restart IIS/Apache and ColdFusion.

  • Validate connector logs and test a simple CFM.

  1. Restore secrets and certificates

  • If copying neo-*.xml, ensure password.properties is moved so encrypted passwords (DSNs, mail) resolve correctly.

  • Import CA certificates your apps need:

    keytool -importcert -keystore /path/to/cacerts -storepass changeit -alias myca -file myca.crt

  • If using client certificates or custom keystores, copy them and update jvm.config -Djavax.net.ssl.keyStore settings.

  1. Align filesystem assets and paths
  • Recreate directories for logs, temp, and custom libs.
  • Deploy Custom tags/components to mapped folders.
  • Verify absolute paths in mappings and scheduled tasks.
  • Ensure service accounts have read/write permissions where needed.
  1. Validate datasources and mail
  • Use ColdFusion Admin to verify DSN connections (or script via Admin API).
  • Send a test email from CF Admin > Mail.
  • Confirm any integrated services (Redis, Solr, external APIs).
  1. Tune JVM and CF settings
  • Set heap sizes (-Xms, -Xmx) and GC flags appropriate to your workload.
  • Adjust CF Admin settings: request timeouts, Session management, caching.
  • Verify logging levels.
  1. Restart and smoke tests
  • Restart CF and web server.
  • Run smoke tests for key endpoints.
  • Review application.log, exception.log, coldfusion-out.log for warnings/errors.
  1. Cutover and DNS
  • Lower TTL ahead of time.
  • Switch DNS or load balancer to point to the new server.
  • Monitor Performance and errors closely.
See also  How to Validate Security After ColdFusion Migration

Configuration reference: where settings live

  • Datasources (DSN): cfusion/lib/neo-datasource.xml
  • Mail server: cfusion/lib/neo-mail.xml
  • Scheduled tasks: cfusion/lib/neo-cron.xml
  • Mappings: cfusion/lib/neo-mapping.xml
  • Security/Sandboxes: cfusion/lib/neo-security.xml
  • General runtime: cfusion/lib/neo-runtime.xml
  • Logging config: cfusion/lib/neo-logging.xml
  • Admin password seed: cfusion/lib/password.properties
  • JVM settings: cfusion/bin/jvm.config
  • Web connectors: wsconfig tool (runtime/bin), IIS/Apache config files
  • cfsetup profiles: export/import JSON (CF2021+)
  • CAR packages: .car files from Admin (Enterprise)

Tip: Always keep a versioned backup of these files and document changes.

Risks, Common Issues, and How to Avoid Them

  • Mismatched ColdFusion versions/builds

    • Risk: neo-*.xml incompatibilities or missing settings.
    • Avoid: use cfsetup or Admin API across versions; keep versions aligned.

  • Password encryption seed mismatch

    • Risk: DSN/mail passwords fail if password.properties not copied.
    • Avoid: copy password.properties; or re-enter secrets post-import.

  • Missing JDBC drivers or classpath entries

    • Risk: DSN validation fails.
    • Avoid: copy drivers; verify in lib/ and jvm.config classpath.

  • Web server connector mismatch

    • Risk: 500 errors or .cfm not executing.
    • Avoid: reinstall connector using wsconfig; match 64-bit/bitness and CF version.

  • Broken absolute paths in mappings and tasks

    • Risk: file not found, task failures.
    • Avoid: update paths during import; prefer relative paths where possible.

  • Certificates not migrated

    • Risk: SSL handshake failures to DB/APIs or mail servers.
    • Avoid: import CAs and client certs into the correct keystores.

  • Package/module gaps (cfpm)

    • Risk: PDF/image/spreadsheet Features missing.
    • Avoid: cfpm install required modules and verify with test scripts.

  • Permissions and SELinux/AppArmor

    • Risk: access denied to files or temp dirs.
    • Avoid: set correct ownership and SELinux contexts; test write paths.

  • Scheduled tasks Authentication

    • Risk: tasks fail due to changed credentials/context.
    • Avoid: re-enter credentials; test each task; check history/logs.

  • Security regressions

    • Risk: exposed CFIDE, default passwords, insufficient lockdown.
    • Avoid: run Lockdown Tool, IP restrict CF Admin, enforce secure profiles.
See also  How to Handle ORM Schema Changes in Migration

Post-Migration Checklist / Validation Steps

  • Administrator access:
    • Can you log into CF Admin? Is it IP restricted?
  • Datasources:
    • Validate each DSN; run a sample query from ColdFusion.
  • Email:
    • Send a test email; verify delivery via SMTP log.
  • Mappings and custom tags:
    • Confirm that mapped code loads and custom tags resolve.
  • Scheduled tasks:
    • Run each task; verify logs and next run times.
  • Web server connector:
    • Load a .cfm page through IIS/Apache; check response times and logs.
  • Certificates:
    • Test outbound HTTPS calls (DBs with SSL, APIs).
  • JVM/CF logs:
    • Review for WARN/ERROR messages after 30–60 minutes of typical load.
  • Packages:
    • Run small tests for PDF, Image, Spreadsheet as relevant.
  • Performance:
    • Compare throughput/latency with baseline; adjust JVM/CF settings if needed.
  • Backups and monitoring:
    • Enable backups of config and logs; ensure APM/monitoring agents are installed.
  • Security:
    • Confirm Lockdown, headers, secure cookies, and minimal attack surface.

Examples and snippets

cfsetup examples

  • Export a profile (old server):

    cfsetup profile export \
    –host http://oldhost:8500 \
    –username admin \
    –password “OldPass!” \
    oldserver.json

  • Import onto new server:

    cfsetup profile import \
    oldserver.json \
    –host http://newhost:8500 \
    –username admin \
    –password “NewPass!”

  • Export only datasources and mail (if supported by your cfsetup version):

    cfsetup profile export –sections datasources,mail –host http://oldhost:8500 –username admin –password “OldPass!” ds_mail.json

Admin API CFML example (create a SQL Server DSN)


admin = createObject(“component”,”cfide.adminapi.administrator”);
admin.login(“AdminPassword”);

ds = createObject(“component”,”cfide.adminapi.datasource”);

// Example: Microsoft SQL Server using the bundled driver
ds.setMSSQL(
name = “MyDSN”,
host = “dbserver01”,
database = “MyDatabase”,
port = 1433,
username = “dbuser”,
password = “dbpass”,
selectmethod = “direct”,
sendstringparametersasunicode = true
);

// Test connection (throws exception on failure)
cfadmin = createObject(“component”,”cfide.adminapi.administrator”);
cfadmin.login(“AdminPassword”);

wsconfig examples

  • List connectors:

    “C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -list
    /opt/ColdFusion2023/cfusion/runtime/bin/wsconfig.sh -list

  • Add IIS connector for Default Web Site (siteid 1):

    “C:\ColdFusion2023\cfusion\runtime\bin\wsconfig.exe” -add -ws iis -siteid 1

  • Add Apache connector:

    /opt/ColdFusion2023/cfusion/runtime/bin/wsconfig.sh -add -ws Apache \
    -bin /usr/sbin/httpd \
    -dir /etc/httpd/conf

cfpm (ColdFusion Package Manager) essentials

  • List installed packages:

    cfpm list

  • Install common modules:

    cfpm install pdf,image,spreadsheet,aws

Frequently Asked Questions

Do I need to copy password.properties to the new server?

Yes, if you are migrating by copying neo-*.xml files and want to preserve existing encrypted passwords (datasource, mail). The encryption seed in password.properties must match. If you use cfsetup or Admin API and re-enter secrets, copying the seed is not required.

Can I use a CAR file to migrate from CF11/2016 to CF2021/2023?

Sometimes, but it’s not guaranteed. CAR files work best within the same major version family. For cross-version moves, prefer cfsetup (if available) or Admin API scripting, and validate each imported resource carefully.

What’s the safest way to migrate scheduled tasks?

If on CF2021/2023, use cfsetup or Admin API to export/import tasks, then manually verify each one. If you copied neo-cron.xml across identical versions, still review paths, Authentication, and SSL endpoints. Run each task once and check logs.

How should I handle JDBC drivers during migration?

Identify drivers on the old server (often in {cf_instance}/lib/ or {cf_instance}/lib/updates). Copy them to the new server and update classpath if needed. Then validate each DSN in CF Admin. If upgrading drivers, test carefully as behavior can change across versions.

About the author

Aaron Longnion

Aaron Longnion

Hey there! I'm Aaron Longnion — an Internet technologist, web software engineer, and ColdFusion expert with more than 24 years of experience. Over the years, I've had the privilege of working with some of the most exciting and fast-growing companies out there, including lynda.com, HomeAway, landsofamerica.com (CoStar Group), and Adobe.com.

I'm a full-stack developer at heart, but what really drives me is designing and building internet architectures that are highly scalable, cost-effective, and fault-tolerant — solutions built to handle rapid growth and stay ahead of the curve.

View all posts

You may also like