Skip to end of metadata
Go to start of metadata

The Lucee Installer does not come with ability to rotate logs built into it. Instead, the Lucee installers ship with Tomcat's default logging mechanism, java.util.logging. This is simple and effective logging that will work in most situations, but if you want more complex features, such as rotation based on date or size, you will need to upgrade Tomcat to use a more advanced logging mechanism, such as Log4j.

Thankfully, upgrading to log4j is NOT DIFFICULT. Download a couple things here, tweak a config file there, and you're all set.

The following is intended to be a guide on how to go about downloading and installing log4J on a system that was built using the Lucee Installers.

Review the Log4j Docs (optional)

Much of the following is adapted from the Log4j documentation, which, if you want to review the original, can be found here.

Installing Log4J Walkthough

The following guide will assume you've installed Lucee to the default location of /opt/lucee, and the directories stated here will be written accordingly. If you installed Lucee to a different location, you will need to update the example directories to match where you installed Lucee.

In the following example, I will be upgrading a Lucee 5 installation on Ubuntu 18.04 LTS. If you're not running this setup (or if you're running on Windows), you may need to interpolate these commands a bit, but the general principals will be the same.

Create the log4j directories

Start out by creating the directories that we'll need for our log4j files. I used the default directories when I installed Lucee with the Lucee installer, so our $CATALINA_HOME value will be /opt/lucee/tomcat/. Using this directory as a base, we now need to create our log4j directories:

Create a new directory in /opt/lucee/tomcat/log4j2/lib/ .

$ sudo mkdir -p /opt/lucee/tomcat/log4j2/lib/
$ sudo mkdir -p /opt/lucee/tomcat/log4j2/conf/

Download and Extract the Log4j JARs

Now that we have the directories we need, we will want to download and extract the log4j JAR's into the lib directory. The download page is here. At the time of this writing, the most recent version is 2.12.1, so that's what I'll download and extract in this example:

$ cd ~
$ wget
$ tar -xzf apache-log4j-2.12.1-bin.tar.gz
$ cd apache-log4j-2.12.1-bin/
$ sudo cp log4j-api-2.12.1.jar log4j-core-2.12.1.jar log4j-appserver-2.12.1.jar /opt/lucee/tomcat/log4j2/lib/
$ ls -al /opt/lucee/tomcat/log4j2/lib/

The last line just ensures the 3 files you need were copied properly.

Create the Log4j Config File

There are several formats that we can use for our Log4j2 config file, but for our purposes, we'll be using XML at the moment. Here is an example XML file that is a good place to get started:

$ sudo vim /opt/lucee/tomcat/log4j2/lib/log4j2-tomcat.xml

<?xml version="1.0" encoding="utf-8"?>
<Configuration status="info">
    <Property name="logdir">${sys:catalina.base}/logs</Property>
    <Property name="layout">%d [%t] %-5p %c- %m%n</Property>
    <Console name="CONSOLE" target="SYSTEM_OUT">
      <PatternLayout pattern="${layout}"/>
    <RollingFile name="CATALINA"
      <PatternLayout pattern="${layout}"/>
        <TimeBasedTriggeringPolicy />
        <SizeBasedTriggeringPolicy size="1 MB"/>
      <DefaultRolloverStrategy max="10"/>
    <RollingFile name="LOCALHOST"
      <PatternLayout pattern="${layout}"/>
        <TimeBasedTriggeringPolicy />
        <SizeBasedTriggeringPolicy size="1 MB"/>
      <DefaultRolloverStrategy max="10"/>
    <Root level="info">
      <AppenderRef ref="CATALINA"/>
    <Logger name="org.apache.catalina.core.ContainerBase.[Catalina].[localhost]"
        level="info" additivity="false">
      <AppenderRef ref="LOCALHOST"/>

Update the Classpath to load

Now that the files and configs are in place, we just need to load the Log4j JAR's at startup. We can do that by adding the following line to the file in the tomcat/bin directory:


For Windows, you can add this line to the "Java Classpath" text field in the "Java" tab of the Lucee Tomcat Service Control.

As an example, my file now looks like this:

# Tomcat memory settings
# -Xms<size> set initial Java heap size
# -Xmx<size> set maximum Java heap size
CATALINA_OPTS="-Xms256m -Xmx512m";

# additional JVM arguments can be added to the above line as needed, such as
# custom Garbage Collection arguments.



Restart to finish up

Restart Tomcat so that the new logger takes affect:

$ sudo /opt/lucee/lucee_ctl restart

You should see new logs (like catalina.log instead of catalina.out) appear in your /opt/lucee/tomcat/logs/ directory.

  • No labels