[Looking for Charlie's main web site?]

How can I keep CF Admin settings in sync between multiple servers or instances?

This question was asked today on the Adobe CF forums. The person had CF instances on multiple servers and lamented having to login to each CF admin to make changes that would apply equally to all instances, in particular creating or changing datasources. They wondered if in fact there was a feature in the CF Admin to "cluster" datasource definitions, like there is (since CF2016) the feature to "cluster" scheduled tasks.

I explained that there was not such a "feature" but that there were at least two options to achieve the goal. The answer was long enough (as is my wont) that I should have probably created a blog post instead. After submitting it, I decided to do just that, here (and I have tweaked here what I said, with some more elaboration and links).

Short answer: there are two tools that can help with this task, the CF Admin API (minimalist and manual), and the CFConfig tool within CommandBox (powerful and automated), as well as some seeming "shortcut" options (copying neo xml files, using symlinks, etc., which I'd advise strong caution against). I also give the CF CAR file feature an honorable mention.

For more on all this, read on.

To be clear, there is sadly no feature (currently) to "cluster" datasources or any other CF admin settings, besides that scheduled task feature. BTW, that was something inherited by Adobe (not created by them), as part of the quartz open source package that provides the sched task mechanism within CF since CF10. It's *quartz* that offers the feature to cluster tasks, based on their definition being stored (and access by CF) in a db that is shared between the instances. There's no other feature in the CF admin that works like that.

So how can you synchronize cf admin settings?

An Adobe-provided solution: CAR files

This first section is an update since I first posted this entry. Mark Gregory commented below that the CF CAR (ColdFusion Archive) mechanism could be used. I hadn't thought of it because I was thinking more of "syncing" settings and in a programmatic way, especially if wanting to "make a change" in some setting across multiple servers.

But it's a fair point that I should have at least mentioned this option. Thanks, Mark.

It's a feature (available in CF Standard since CF11, but Enterprise-only before that) which allows one to use a UI (within the CF Admin, "packaging and deployment" section) to identify any of the many settings in the current CF Admin, to save those into an export file (a .car file). Then you can use the same Admin page to IMPORT those settings into a CF server (even a different version). (I'm not aware of there being an automated way to do the export, but I'd not be surprised that there would be an admin api call to do an import.)

FWIW, I've written more about it here, as well as a post on the Adobe CF Portal, where I also point to other resources introducing the feature in more detail.

An Adobe-provided solution: CF Admin API

As for how to add or change some CF Admin setting (in an automated way), the Adobe-provided solution is the cf "admin API", which was introduced in CF7 but has generally failed to be noticed by most. It's a set of CFCs provided in CF, within the CFIDE folder in the CF wwwroot. Nearly anything one can do in the Admin can be done by calling a certain method (a certain way) in one of the various CFCs, each devoted to a different part of the CF admin.

It's not that it's designed to "sync" the settings, but that one could automate the process of creating (and changing) settings, via CFML, such as if one wanted to change the port, server name, or password for a datasource, as an example.

Sadly, the Admin API has been poorly documented over the years. I think the original developers presumed people would use the feature in CF that allows anyone to browse any CFC, but many never knew of even that.

There was an effort started by Adobe just in recent years to better document the Admin API for us, as I noted in a post in early 2018. Sadly, the effort is still only about half done, two years later. (They ought to open-source that effort! Or someone else may want to take that on.) And if you see the "related blog entries" at the bottom of that post, I have other posts I've done on using the Admin API for various purposes.

If you just google that phrase, CF adminapi, you'll find other discussions about it from over the years, including examples. (I will update this post later with some more specific recommended resources, and I've long wanted to do another post with some more thoughts on leveraging the Admin API.)

Finally, do beware just blindly following examples shown (even from Adobe) for creating a dsn. Make sure you are setting the RIGHT settings for your own dsn needs. Sometimes their examples show settings that would NOT be what you would get in a CF DSN left to its defaults shown in the Admin DSN page.

The Ortus-provided solution: CFConfig tool of CommandBox

Alternatively, you could leverage the cfconfig tool offered as an optional package in the free, open source CommandBox tool.

Some of you may stop right here and say, "I don't use Commandbox to manage my CF instances".

Well let me stop you right there and say that cfconfig can be used even with servers that are NOT started/controlled by CommandBox. All you need to do (after installing commandbox and cfconfig) is to point the cfconfig tool's FROM (or TO) attribute to name the folder within your CF instance containing the lib folder and its neo xml files (more on those files in a moment).

Even better, and specifically for the notion of "syncing" settings across instances, CFConfig offers options to export, import, and even compare settings among instances. And there are of course features to set and get settings, as well, and more. CFConfig (like Commandbox) can be used with Lucee as well as CF (and you can even use it to compare/export/import settings BETWEEN CF and Lucee!)

For more on the tool, including examples, see this great starting page, as well as the CFConfig manual.

While to some CF/Lucee devs these are two vital tools they use daily (especially for local development), they are still unknown to or unused by many. And like the Admin API, I have long planned to do posts with more on leveraging cfconfig. But this question on the forums today at least prompted this post, to get things started.

Other alternatives, that I would advise against (or with great caution)

Finally, some may know that CF admin settings are nearly all saved in a set of neo*.xml files, stored in the lib folder under your CF instance. As such, they may wonder if they can just "manually" sync the Admin settings of CF instances, using either of two means, which I would advocate against.

Don't just copy the neo xml files

The most obvious thought would be, "why can't I just copy the neo xml files between the servers?, or perhaps at least just the neo-datasource.xml where DSN's are stored?"

Copying those neo xml files between servers is not wise, for various reasons.

First, even between two otherwise identical CF instances (same version, same updates, etc.), there are aspects of the files that may NOT be suited to be copied from one instance to another. For instance, I am pretty sure the password stored for a DSN is encrypted using info specific to the instance (and based on info in files other than those neo xml files. Indeed, consider that the neo-datasource.xml is also related directly to the neo-drivers.xml, so they should be regarded as a pair.)

But second, as for instances running DIFFERENT versions of CF, I would STRONGLY recommend against copying the neo xml files between those, as the layout (elements, attributes, values) of the xml files can change. I realize some "have done it" and had "no problem", but I can tell you I have helped people overcome problems that were due to this practice.

Despite these warning, some folks have indeed (out of need) dug in and confirmed that it WAS ok for them to copy some neo xml file, to make it easier to "keep them in sync". Just be very careful.

Don't try to force CF to "share" the setting location between instances

This is a variation on the above. Some admins may try either of a couple possible ways to to somehow point multiple CF instances at a single location for the neo xml files, again whether for all the settings or perhaps the DSNs only. Again, I would strongly advocate against these ideas.

First, more savvy admins will know that both Linux and Windows (and MacOS) offer a way to create a symlink (or junction or alias) for any folder, so that while an app may look for files in a folder named x, there will be no such "real" folder and the OS will instead find its files in some folder y.

And this has been used to "fake out" some app that hard-coded a path, so that instead its files were found elsewhere. While that's a great feature in many cases, it's unwise for the concerns I raised above (about copying neo xml files between two otherwise identical servers). Still another concern would be possible race conditions if somehow changes were made to two instances at once (though I realize one could implement protections against that).

And note that there's no provision in CF for it to auto-reload changes made to the neo xml files, so any change would require that CF be restarted for the change to be picked up by the instance pointing to it. (Some may notice that in the CF Admin "settings" page there's a setting called, "Check Configuration Files for Changes Every (Seconds)", but see the description there which indicates that's a feature unique to Websphere deployments, for some reason.)

Second, some may wonder if there's perhaps a way to configure CF to name/change the folder where it should look for the neo xml files. I am not aware of any such setting, even in an underlying XML file or something. And I'd argue that's for our own good, because if Adobe DID offer that, some would to try to point CF at a folder intending precisely TO share it among more than one CF instance, which would come with all the same risks discussed above.


Anyway, there are several ideas. I think the best choices for this need to sync (or implicitly "cluster") CF admin settings would be the first two, the Admin API or cfconfig. But I share the rest for consideration (and mostly recommending against them, for nearly all folks).

Let me know what you think, and if you may try it, how it goes for you.

For more content like this from Charlie Arehart: Need more help with problems?
  • If you may prefer direct help, rather than digging around here/elsewhere or via comments, he can help via his online consulting services
  • See that page for more on how he can help a) over the web, safely and securely, b) usually very quickly, c) teaching you along the way, and d) with satisfaction guaranteed
I believe one could also create a .car file and apply it, in theory, but I am not certain it would get 100% of the settings one might be applying manually.
Would get tedious with more than a handful of boxes to update though.
# Posted By Mark Gregory | 4/7/20 12:47 PM
Oh, of course. Very good point, Mark. I certainly should have mentioned that. I was thinking more of syncing than migrating, but it's close enough.

I will tweak the post, thanking you for the suggestion.
# Posted By charlie arehart | 4/7/20 12:51 PM
Copyright ©2021 Charlie Arehart
Carehart Logo
BlogCFC was created by Raymond Camden. This blog is running version 5.005.
(Want to validate the html in this page?)

Managed Hosting Services provided by
Managed Dedicated Hosting