Lucee 5.4 to 6.2 Upgrade Guide, Tomcat 9 to Tomcat 11

hacking
,
1

Backup first

Make copies of these files

  • lucee-server/context/.CFconfig.json - 6.0+
  • lucee-server/context/lucee-server.xml - 5.x
  • webroot/WEB_INF/lucee/lucee-web.xml.cfm - 5.4 context specific config(s)

In place upgrades

Lucee, unlike Adobe CF has always allowed easy upgrades/downgrades between versions via the admin.

There was a restriction in older Lucee versions which meant you couldn’t downgrade to an older version than your current Lucee loader version, but that restriction has been removed in 6.2 (note to self, I need to update the admin text)

As always, you can simply do an in place upgrade, as Tomcat 9.0 is still supported by 6.2, it’s just java 8 is no longer supported.

There are multiple ways to do an in place upgrade of Lucee

Core update (.lco)

  • via the admin
  • or by dropping a core .lco into the lucee-server/deploy/ folder, i.e https://cdn.lucee.org/6.2.1.77-RC.lco
  • with 6.2, you can just set the env var LUCEE_VERSION=6.2.0.321 and Lucee will load that version on startup

Loader update (lucee.jar aka the fat jar)

Updating your Loader is also recommended

The difference between a Core update and a Loader update?

  • the core .lco only contains the minimum files required to update, Lucee will then dynamically download any missing bundles / jars required.
  • the fat lucee.jar includes all the required bundles / jars to run Lucee, so no additional downloads are required.

During an in place upgrade, Lucee 6 will automatically convert/import your xml and convert it to json.

The original xml files are left in place, so you can also downgrade again, just keep in mind any configuration changes made while running 6 do not update the xml files.

So once you have done an in place upgrade, you’ll have your CFConfig.json available, but you are still running older versions of Java and Tomcat, sooo…

Fresh Install, highly recommended

Generally speaking, the best way to upgrade from Lucee 5.4 is always going to be a new install.

Any 5.4 install is mostly likely already going to be using rather old versions of Tomcat and Java.

Consider doing an in place upgrade via the admin, to grab your running config from lucee-server/context/.CFconfig.json and then doing a fresh install. Just stop the server after installing and copy the .CFconfig.json file into the new server and restart it.

Side by side installs

The Lucee installer has supported side by side installs since a while, i.e. into different folders on different ports.

I have locally, c:\Lucee and c:\lucee6 both pointing to the same webroots

Copying your Configuration over

For most Lucee installs, there are only one or two files needed to duplicate your server config.

  • lucee-server/context/.CFconfig.json - 6.0+
  • lucee-server/context/lucee-server.xml - 5.x
  • webroot/WEB_INF/lucee/lucee-web.xml.cfm - 5.4 context specific config

The only additional files you need to consider are any jars you have installed into Tomcat or context lib dirs, like urlrewrite etc

Have you made any custom configuration changes made to the Tomcat configuration? i.e. tomcat/conf/ use a diff tool to copy them over.

But you had already documented all these additional changes for disaster recovery? If not, I’d highly recommend doing that as part of this upgrade process.

Upgrade Considerations

Lucee 6 only supports Java 11+, with Lucee 6.2 we recommend Java 21, so not java 8.

Also, Lucee 6.2 supports the newer jakarta based servlet API, i.e. Tomcat 10.1 and Tomcat 11, as well as Java 21.

Due to the change to the Jakarta namespace, with Tomcat 10+ you will need updated versions of jars like urlrewrite v5.0 UrlRewriteFilter - Rewrite URL's in Java Web Application Servers

Configuration syntax changes

The Lucee Admin is your friend, use it to configure your server, it will show you the supported configuration with snippets at the bottom of most edit pages.

If something isn’t working like an older datasource connection in an Application.cfc, go and try configuring it in the Lucee Admin and compare to your code.

You can always just grab the running config from your lucee-server/context/.CFconfig.json.

Deploying

I have prepared some detailed documents on how to deploy Lucee configuration.

Rolling your own Tomcat install

Please refer to Lucee Express to see the recommended Tomcat configuration required to run Lucee

Here is the source code for building the installer from the original Tomcat sources

TL;DR? You’ll need to manually add the javax servlets to Tomcat 11, but why not just use our Installers or Lucee Express which are pre configured and known to work?

Questions?

Need professional support? I am available for consultancy, just message me

Ask below!

12 Likes
2

Thank you Zac!

3

I just upgraded to Lucee 6.2.0.321 from 6.0 and am still on Tomcat 9.
I just need to upgrade Tomcat to 11, am I still best to do a full fresh installation of Lucee 6.2 or how best to only upgrade Tomcat?

4

Firstly, I’d really, really ,really recommend using the 6.2.1 RC over 6.2.0.321, there’s at least 112 bug fixes / improvements you’re missing out on!

Myself? I’d just do a fresh install, it’s so much easier and more reliable and performant.

You could grab Lucee express and do diff between it and your install, mess around copying and configuring all that, but IMHO it’s a waste of time, you won’t be deploying that Frankenstein Lucee install to production.

Personally, I always want production to match my dev environment as closely as possible, and for it to be easily reproducible for DR (disaster recovery)

2 Likes
5

Thank you sir.
I’m going to try a full install hopefully tomorrow.

6

Thank you sir, for the replies and advice.
It was very easy to run a fresh install and upgrade to tomcat 11.

1 Like
7

Thanks Zac.

Is there anywhere I can find out how to repeat the exploit so that I can check to see if my servers are vulnerable, and check the fix has worked?

8

just copy a class from your cfclasses directory and save it as a .cfm and try to run it