Cfinclude ACF vs Lucee [Linux, Apache]

Hello! I’m currently trying out Lucee over ACF and am having an issue with the way our app is including files.

All of our sites’ index.cfm and Application.cfc files are actually symbolic links to shared files. Example:

/var/www/ → /usr/app/engine/index.cfm
/var/www/ → /usr/app/engine/Application.cfc

Within the Application.cfc file we have <cfinclude template="app_ips.cfm"> (this is the first <cfinclude> that the code hits, from what I can tell and is located at /usr/app/engine/app_ips.cfm) but Lucee shows an error:

Page /index.cfm [/var/www/index.cfm] not found

The error also mentions "Mapping: / " which I do have a mapping setup:

/ --> /var/www

Removing the mapping changes the error:

Page /app_ips.cfm [/var/www/] not found

Within httpd.conf I have the following (which I honestly don’t know what it’s doing, if anything):

<IfModule mod_proxy.c>
    ProxyPreserveHost On
    ProxyPassMatch ^/([cm])(/.)?$$1$2
    ProxyPassMatch ^/(.+.cfml)(/.)?$$1$2
    ProxyPassReverse /

Any thoughts as to what could be happening? Any additional info I can provide?

Thank you!

Don’t forget to tell us about your stack!

OS: AlmaLinux 9
Java Version: 11.0.22
Tomcat Version: 9.0.86
Lucee Version:

My guess is that Lucee doesn’t follow symlinks.

Try mapping directly to the actual folder?

/ --> /usr/app/engine/

he would need follow symlinks in the directory options for apache.

<Directory /var/www/html/someplace>
Options +FollowSymLinks -Indexes

then in the webpath create the symlink

ln -s /name/of/path /target/path/location

then make sure lucee and your web service has permssion to target location. and to at least read the symbolic link

The thing is, the symbolic link includes work totally fine in ACF using Apache, but are you saying Lucee might do it differently?

Without getting into it, you have a permissions issue on your lucee install.

That could certainly be true; ACF runs as the cfmx user, although Lucee is running as root so I would expect it should be able to access it. My gut is leaning more toward the Apache Proxy redirect combined with the mapping. Without changing permissions:

  • If I test a site without those symbolic links (just a direct index.cfm) with the mapping I mentioned, I get Page /test.cfm [/var/www/test.cfm] not found (the document root for this test is /var/www/html).

  • If I remove the mapping, the request redirects to and correctly parses the index.cfm file.

  • If I add <cfinclude template="/usr/app/engine/app_ips.cfm"> it fails with Page /usr/app/engine/app_ips.cfm [/var/www/html/usr/app/engine/app_ips.cfm] not found

  • If I add the symbolic link /var/www/html/engine → /usr/app/engine and set the include to engine/app_ips.cfm it works

  • If I add a mapping of /app/engine → /usr/app/engine and set the include to /app/engine/app_ips.cfm it also works

This is just one example; there is a lot of code that relies on the / → /var/www mapping so I can’t really remove it. There are also 200+ sites that rely on this behavior, so adding symbolic links inside of each site’s directory would not be a trivial matter.

That does indeed get past that error, but it then throws a different, similar, error when trying to cfinclude /app/engine/_globals/someother_file.cfm:

Page /app/engine/_globals/someother_file.cfm [/usr/app/engine/app/engine/_globals/someother_file.cfm] not found

In an effort to get around this one I tried to add a new mapping: /app/engine/ → /usr/app/engine but nothing changed.

Lucee should not run as ROOT

OK that is your permissions issue

Apache is running as apache in group apache for RHEL clones
Lucee may have the permissions to do what ever it likes but httpd can not do what Lucee is asking.

Here is how you fix this

temporarily disable SELINUX
setenforce 0

now add a user for the lucee service, we will call it lucy, but it can be any non reserved user
useradd lucy
now assign the user to the existing group of apache
usermod -a -G apache lucy

remove ability for lucy to login
usermod lucy -s /bin/false

now set the permissions for your cfm/l/c files so that the new “lucy” service user can
chown -R lucy:apache /path/to/your/CFCODE

how both httpd (apache group) and lucee should be able to access your CFfiles

Now here is how your configuration and code merge and affect your mappings

If you have user directory

and you have

The calling service(s) would need to have permission to the /home/user/bob directory

The same would be true if you setup /home/bob/www as bobs Vhost which ran Lucee. Apache and Lucee would still need the correct permissions to access /home/bob/www.

Coldfusion / java server mappings will need the correct file permission for the path you are setting.

Thank you Terry, I really appreciate you taking the time to write that out.

I do want to clarify one thing; from what I’m seeing in the error messages (which are correct), it isn’t that Lucee can’t access/read these includes, but rather Lucee is looking for them in the wrong place.

Example: when including app_ips.cfm from within /usr/app/engine/Application.cfc, Lucee is trying to include /var/www/ (the location of the file I’m wanting it to include is located here: /usr/app/engine/app_ips.cfm).

Everything I’ve tested is doing essentially the same thing; looking for files in the wrong place (and therefore they don’t exist). Which is why I think it’s all stemming from that Apache block above, maybe combined with the mappings I have setup.

I completely agree; do you know how to change this? My thought is just to uninstall/reinstall Lucee, and choosing the correct user there…



I remember seeing a similar issue a while back when we used symbolic links for specific shared files on our CFML codebase. I think this went back to CF v6 and Jrun, but I think it is still the same for Lucee 5/6 and Tomcat - at least we’re still doing it this way now. The issue arises when the JVM/JRE resolves the symbolic links to their canonical paths, which often breaks relative include paths for cfinclude and others. A symbolic link may not be the exact equivalent of a physical path, this entirely depends on how certain applications treat symlinks. There may or may not be some switch in Tomcat/JRE/Lucee that could affect this behaviour, but in our case we got rid of the problem by replacing the specific symbolic links that showed the issue with bind mounts - so in /etc/fstab we’d have something like

/usr/app/sharedCode /var/www/mysite1/sharedCode bind,_netdev,rw 0 0
/usr/app/sharedCode /var/www/mysite2/sharedCode bind,_netdev,rw 0 0

These bind mounts are entirely transparent to the application, so there are no issues with the JVM resolving symlinks to their canonical paths and thus not finding includes where they are supposed to be. I do realize that adding bind mounts and having them set up before your applications start requires a little more tinkering with the OS (you’ll have to access and edit /etc/fstab and maybe tinker with some systemd unit files), but on the whole this approach does work consistently.

Hope that helps.

1 Like