This article explains:

• Where to place cache configuration files

• How to reference them in portal-ext.properties

• Real‑world tuning examples for improving performance

 

Background: Ehcache in Liferay

Liferay uses two main cache layers:

• Single‑VM Cache: Local in‑JVM cache used for, Optimized for standalone deployments or clusters with database‑level replication.

  • EntityCache

  • FinderCache

  • Service and request‑level caching

• Multi‑VM Cache: Distributed cache used in clustered environments for:

  • Shared cache invalidation

  • Consistency across nodes

 

Migration to Ehcache 3 (2025.Q2+)

Area	Old (Ehcache 2) < 2025.Q2	New (Ehcache 3) > 2025.Q2
Config format	Ehcache 2 XML	Ehcache 3 XML & schema
File names	liferay-single-vm.xml, liferay-multi-vm.xml	Same names, new syntax
Classes	net.sf.ehcache.*	org.ehcache.*
Expiry	timeToIdle, timeToLive	<expiry><tti/> <ttl/></expiry>
Heap syntax	maxEntriesLocalHeap	<heap>

 

Configuration File Locations

1. Place your custom config files here:

TOMCAT_HOME/webapps/ROOT/WEB-INF/classes/ehcache/

Typical structure:

/ehcache

├── liferay-single-vm-override.xml

└── liferay-multi-vm-override.xml

 

2. Referencing Custom Config in portal-ext.properties:

ehcache.single.vm.config.location=/ehcache/liferay-single-vm-override.xml 
ehcache.multi.vm.config.location=/ehcache/liferay-multi-vm-override.xml

 

Default config files location:

• Located in jar file:

  ${LIFERAY_HOME}/osgi/portal/com.liferay.portal.cache.ehcache.impl.jar
  

• Or in github for each version:

  • liferay-multi-vm.xml: liferay-portal/modules/apps/portal-cache/portal-cache-ehcache-impl/src/main/resources/ehcache/liferay-multi-vm.xml at master · liferay/liferay-portal

  • liferay-single-vm.xml: liferay-portal/modules/apps/portal-cache/portal-cache-ehcache-impl/src/main/resources/ehcache/liferay-single-vm.xml at master · liferay/liferay-portal

 

 

Example: Custom Ehcache 3 Tuning

Below are examples to optimize caching for DDMFieldAttributeImpl, a common hot cache entry in heavily customized DXP installations using Dynamic Data Mapping.

Goal

• Increase heap to support large datasets

• Extend idle expiration for better cache retention

• Reduce DB round trips

Sample XML (Ehcache 3)

 

<cache alias="com.liferay.portal.kernel.dao.orm.EntityCache.com.liferay.dynamic.data.mapping.model.impl.DDMFieldAttributeImpl"> 
   <expiry> 
      <ttl>3600<\/ttl> <!-- expire after 1 hour regardless of usage -->
      <tti>600<\/tti> <!-- expire after 10 minutes idle -->
   </expiry> 
   <heap>200000</heap> 
</cache>

What these settings mean

Setting	Meaning
heap	max entries stored in memory
tti	Time‑to‑Idle (evict if not accessed for X seconds)
ttl	time to live
uses-template="default"	inherits base cache config defined in XML

 

 

Changes should be applied and you can check them in Mbeans JVM section.

 

 

Best Practices

✅ Tune only hot caches (based on log & performance monitoring)

✅ Increase memory gradually (avoid OOM risk)

✅ Longer expiry for read‑heavy, stable data

❌ Do not globally increase all caches

❌ Avoid extreme TTL/TTI in busy clusters

❌ Don't forget GC impact when raising heap entries

 

More Resources

• Ehcache 3 Official Reference Guide