Hidden Gem in ColdFusion 11: ColdFusion Archive (CAR) support now in Standard
Note: This blog post is from 2014. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.(Post updated July 2021)
Here's a nice surprise for some about a change in CF11: you can now create and read CAR files (ColdFusion archive files, a CF Admin feature) in the STANDARD edition of ColdFusion 11. In prior releases, it was available only in ColdFusion Enterprise.
Read on for more, including a gotcha regarding importing from previous release Standard editions, but for many this news will be a delight and all they need to know.
For more on what the CAR mechanism is, finding more on it, the gotcha (and what NOT to do if you hit that gotcha), and info on still more hidden gems in CF, read on.
What the CAR mechanism is for
I don't want to rehash what's already well-documented in both the CF docs and various blog entries and articles, so I'll point to those in a moment.
But briefly, the CAR mechanism has been a feature in the CF Enterprise Admin "Packaging & Deployment" section, and it allows one to easily export some or all settings of one CF admin into a single zip file (a ".car" file), which can then be imported into another CF admin. It's a point and click interface (though its UI has its challenges, so see the resources below to better understand it before trying to use it.)
It can be great whether you are moving settings from one machine to another. It can even help with migration of settings from one release to another, though CF does that for you if you install a new release on a machine with an old one, in which case the Migration Wizard option is offered as a last step of installation.
Again, though, as for using the CAR feature, one needed a CF Enterprise (or the trial or Developer) edition on both sides (export and import). At least ColdFusion 11 now supports using the feature to import or export settings, even if running ColdFusion 11 Standard.
A gotcha: won't help with exporting Admin settings out of older Standard editions
The change in CF11 is great news going forward, but there is a gotcha: if you're wanting to import CF Admin settings from a previous release that IS ALSO only a Standard edition, this change won't affect THAT earlier release of CF. In other words, you still won't be able to use the CAR feature in THAT older CF Standard edition's CF Admin to export its settings.
I realize to some that will be a sore spot, and may seem a catch-22 (why would Adobe bother with the feature if it can't be used to import older settings). Well, let's not look a gift horse in the mouth. At least we have it going forward. And it WILL be of valuable for CF11 Standard folks to use to move settings to a new machine also running CF11, etc.
And I mentioned above the migration wizard will help with importing settings on an upgrade of a machine having an older release of CF to a newer one, so even someone going from an older CF Standard edition CAN have their settings migrated. This is just about using that specific CAR file feature, which is typically more for moving settings from one machine to another.
Option 1) What you don't want to do: just drop the neo-*.xml files from one CF version into another, or even one machine to another
So what do you do if you NEED to move admin settings from a CF 10 or earlier Standard edition? Or what if you don't want to bother with the CAR feature?
You may be tempted to just grab the neo-*.xml files from one CF version (or another server) and copy them into the appropriate location of a newer CF version or server. I'm not going to detail HOW to do that, because it's unwise. Why?
First, there are nearly always changed in those underlying neo-*.xml files between one CF version and another (and even one update level to another). So while this approach may have "worked for years" for you I would caution against it.
Also, if you try to go from one SERVER to another, if there are any password entries within what's being "copied" (whether datasources, mail server info, scheduled tasks and more), those are encrypted (as a field in the xml) in such a way that they can only be DECRYPTED (loaded by the CF Admin) on THAT server...unless you use the CAR feature, in which case the encryption key is passed along in the export. (For a discussion of the security concerns for that, see a later post I did.)
Option 2)The better solution (when you can't use CAR, to bring CF admin settings from one release to another)
But there's a better solution for this dilemma (when you want to migrate from a CF implementation before CF11 which was running with the Standard license, and does not offer the CAR feature). And it may be useful in other cases, also--and it's a fully supported and documented one. I hinted at it above.
First, I had mentioned that the last step of the CF installer checks to see if there is a previous release of CF installed on the machine. If there is, then the "migration wizard" does the import.
Well, what if you didn't know this when you installed CF11 (or 10, or some earlier release)? Is it too late? No!
It is possible to re-run that migration wizard at any time, by placing the previous release files in a particular place and editing a config file to cause the Admin to re-run the migration wizard. Explaining (and some gotchas) goes beyond the scope of this blog entry, so I have saved it for another that follows (Hidden Gem: Importing CF Admin settings in ANY release via "import wizard", even AFTER installation). Just know that between that and the CAR feature, you should not have to rely on trying to copy/past neo*.xml files directly from one CF instance into another, if that may cause problems.
Finding more about the CAR feature
[Update: I have updated this section in 2021, making sure the links work.]
So I'd mentioned that the CAR feature is documented, but Adobe and others.
First up, docs from Adobe
First up is the Config/Admin manual discussion: CF Docs on the feature. It's pretty paltry really.
Since then, Adobe came out with a Migration Guide for CF2016 and then a Migration Guide for 2018, but again it really gives short shrift to the CAR mechanism.
Finally, there is also online help for the feature, in the CF Admin itself. Many never notice but on any page of the CF Admin, there is a help button in the top right corner which will offer varying levels of detail depending on the feature in question. Again, though, the discussion on the CAR feature is lacking.
Resources from others, more elaborated
If you may prefer a resource that walks you through the process, for years I have recommended a blog post from Adrian Moreno that is quite old but I've not found many posts from others that to do the job as nicely. Sad to say: that's because the UI and steps really have not changed that much:
Yo, Adrian! How do I backup my ColdFusion Admin settings?
A more updated set of screenshots, at least, is also at the useful cfguide.io site page on the CAR feature.
There was also an overview at quackit.com (and as update since posting thi sin 2014: the page and screenshots have been updated for CF2018).
Finally, I myself did a talk in 2020 about migrating settings, where I covered the CAR feature and other options (including cfconfig from Commandbox, for migrating settings via json files it can create from any CF or Lucee server, and also a similar cfsetup feature added in CF2021 to migrate settings via json files). It's available (PDF and recordings) at here.
If anyone wants to share still other resources, feel free to mention it in the comments. (More on the paucity of community resources covering this topic in a moment.)
I'll also note that we covered it in a chapter of the CF Web Application Construction Kit. Here is the chapter including it, available online from at least the CF8 version of the book, as found viewable on Google Books.
Since the CAR feature has been around since CF5, we don't find many people talking about it/blogging about it much in recent years. Of course, some people have simply never used it or perhaps never liked some aspect of it, which also may contribute to the lack of recent coverage.
So folks new to it are at a bit of a disadvantage, but hopefully the first resources above will help get you going. And again, with a new community of people now able to use the feature (those CF Standard users, now on CF11), perhaps it will spark a resurgence of interest in the tool, and in folks showing each other how to use it.
Want More Hidden Gems?
And last, as for this "hidden gem" in CF11, some of you may know that every release I like to discuss what I call "hidden gems"--things that are in the new release but may not get much press from Adobe, and perhaps even others. I've done talks, articles, and/or blog entries on hidden gems in each release over the years, and you can find those here and on my main site's presentations and articles pages.
That said, I often have offered a lot more in the talks or articles that I never got around to blogging. I hope to rectify that by pointing out more of these here, and not just for CF11. What if you skipped from CF9 or 8 right to CF11? You may not have paid attention when others and I were talking about CF10 hidden gems.
So I hope to blog some more of those, too. All of us can always stand to learn still more about CF, even after years of working with it! :-)
For more content like this from Charlie Arehart:Need more help with problems?
- Signup to get his blog posts by email:
- Follow his blog RSS feed
- View the rest of his blog posts
- View his blog posts on the Adobe CF portal
- 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
That said, I installed CF 11 a while ago and this morning created a CAR file. However, I don't see where in the blazes the car file went on my hard disk! I am probably just missing something but I seem to remember that in previous versions, CF gave a dialog box that let us specify where on our computer we wanted the CAR file to be written to.
The fastest is that CF tracks the location, along with other info on the archive created, in a car.log file (in the logs folder with other CF logs). There's also a log for each specific CAR, though it seems to just be the same info.
Now, I don't know when its logging that way started, if perhaps it has not always done that. So I will offer a couple other ways that could have worked, and may be helpful to another reader who hits this problem on an older version. I had already written them when I remembered myself that there was now a car.log. (And the tips may be helpful for other challenges, as well.)
First, you may find (depending on your browser) that if you revisit the interface, when you get to the point when it asks where to save it, that if you press the down arrow key, your browser may show the value you last entered for that form field.
Second, you could also search your entire drive for *.car, since the CAR mechanism does also still ask you to name the extension and you must put car (one more aspect of its continued "clunkiness", I'd agree). If you're on Linux, use grep. On Mac, use Finder. On Windows, while you could use the search feature in WIndows Explorer, which is at least decent for looking for files by name (not has good for looking for files by content), I will note that there are better tools (Ultrasearch and File Locator Lite) and I have blogged about those, among others:
http://www.carehart....
All that said, with regard to this post's topic, we should perhaps be careful to "look a gift horse in the mouth" in complaining too strongly about the tool, in the face of Adobe kindly moving this feature to being included in Standard. Sad to see not one post yet of appreciation, for that news or for my pointing it out, since my pointing out here almost a year ago. You don't even indicate if you appreciate either. :-(
But sure, I do agree it's an interface whose time has come for further improvements (there have been some, though subtle, over the years). And this is yet another area where, as many have requested, it would be nice if Adobe simply open-sourced the Admin UI, so that we who have compelling changes to propose could at least make them and offer them, for Adobe to consider rolling into the released version.
And, you are right regarding the tool that Adobe has provided for CAR files. I’ve used it many times in the past; it’s a huge time saver especially when multiple developers need to ensure that their CF administrator settings are identical between developers.
Regarding the location of the CAR file, I went back after reading your reply and created another file. I seem to remember having to add the fully qualified path to the file so I put “c:\myFolder\myArchiveFile.car” into the text box. When I click the “Create” button, it gives me a notification in red at the top that says “Invalid archive name. Archive names can only contain letters, numbers, dots, underscores and dashes.”
So, I abide by that and just put “myArchiveFile.car” in, click the “Create” button and now it appears directly below while a new window pops simultaneously providing me with the interface for continuing building the file. That’s it! There’s no navigational dialog that pops allowing me to navigate to a location on my hard drive. It’s just that one initial text box.
I used FileLocator Lite to search for the car file and didn’t find it. Yet, it is listed in the CF admin tool. I’m wondering if perhaps CF can’t write the file to disk due to some permissions issue or something?
Ideas?
Thank you
If you're worried about proceeding, you could grab a capture of the entire lib folder (within your instance, where all the neo-*.xml files are, among others) and know that you could revert to them if you needed to.
When you make changes to the CF Admin (or run the CAR import), it's those neo*.xml files that are changed (that and perhaps the jvm.config in the bin directory).
Hope that's helpful. Let us know what you learn.