What defines an “optimal” Adobe Experience Manager (AEM) Dispatcher configuration? And if there really is such a thing, why not just print it here in place of this post? Better yet, prevent anyone from actually configuring the Dispatcher at all, and only support the optimal configuration!
Unfortunately, it’s not quite that simple. While the exact property values, number of farms and vhosts, and contents of the /filter set will vary between each AEM implementation, there does exist a common set of goals which all optimal Dispatcher setups seek to achieve. At a high level, an optimal configuration will:
- Maximize the cache hit ratio of the public facing site
- Reduce the impact of unexpected or malicious requests
- Limit the effect of activations on the contents of the cache
At Adobe, we’ve been working on a tool to help you optimize your use of the Dispatcher in pursuit of these 3 goals. In this post I’ll be introducing you to the AEM Dispatcher Optimizer Tool, or DOT for short.
What is the AEM Dispatcher Optimizer Tool (DOT)?
In its initial release, the DOT will be available in two forms:
- A Maven plugin for static configuration analysis during development
- A code quality step in the Adobe Managed Services (AMS) Cloud Manager pipeline
The DOT works by parsing the Dispatcher module of an AEM archetype-based Maven project, analyzes it based on an extensible set of rules, and returns actionable details on all issues that are identified.
Its also completely open source! You can find the code here: github.com/adobe/aem-dispatcher-optimizer-tool
What kind of issues can it identify?
The issues which the DOT identifies can be broken down into two main categories of rules: Syntax, and Best Practice.
Syntax rules
This group of rules all relate to how syntactically correct the Dispatcher configuration is. For example, are there properties set in a section where they don’t belong? Is there an extra brace? A missing brace? Mismatched quotes? Is there an Include directive in the Apache Httpd config which references a file that doesn’t exist?
Can you spot the issue with this /filter configuration? The DOT can!
/filter {
/00 { /url "/*" /type "deny" }
/01 { /type "allow" /extension '(html)' /path "/content/*" } }
/02 { /type "deny" /selectors '(feed|rss|pages)'
}
(hint: })
Best Practice rules
Configurations which are syntactically valid from the Dispatcher (or Apache’s) perspective may still have other opportunities for improvement. The next group of rules detects violations of AEM best practices.
Value checks
These rules look for the presence of specific values in the configuration, and can also check that a property value is above (or below) a given threshold. For example, are all the out-of-the-box filter deny rules from the archetype still present? Is /serveStaleOnError enabled? Are /statfileslevel and /gracePeriod set, and with values greater than or equal to 2?
These rules primarily help achieve goals 1. “Maximize the cache hit ratio” and 3. “Limit the effect of activations on the contents of the cache”.
Shameless plug: if you’re curious how /statfileslevel and /gracePeriod can limit the effect of activations, or you’d otherwise like to experiment with these properties in a controlled environment (read: not your public site), check out the lab format AEM Dispatcher Experiments repository.
Need a quick refresher on the role of these properties? The official Dispatcher documentation is an excellent resource to keep handy: AEM documentation on Configuring the Dispatcher
Allow list checks
The allow list rules are all about reducing the impact of unexpected requests made to your public facing site.
What is an unexpected request? I would classify any traffic which is not generated by legitimate users browsing your site, or otherwise related to the authoring of content, as “unexpected.”
The 3 core allow list rules help achieve goals 1. “Maximize the cache hit ratio” and 2. “Reduce the impact of unexpected or malicious requests” by preventing requests containing unexpected query parameters (utm_*, anyone?) from being treated as cache misses, and by outright blocking requests containing unexpected Sling selectors and suffixes.
Can I run the DOT on my project today?
You bet! The best way to get started is to check out the DOT experiment for a thorough walk-through: Using the Dispatcher Optimizer Tool (DOT).
If you’re a Maven pro and just want to run the tool in as few steps as possible, head to the DOT plugin README on GitHub: Dispatcher Optimizer Tool Maven Plugin
Can the rule set be extended?
The 9 “core” best practice rules that ship with the Maven plugin can absolutely be extended, customized, and replaced. Each of the Best Practice rules are specified in core-rules.json, and the core README has more details on the rules spec.
Interested in walking through an example? The DOT experiment covers this use case in Test #5 - Overlay some rules.
Summary
It’s important to remember that there is no singular “optimal” Dispatcher configuration out there. However, we believe that there is an optimal configuration for your unique AEM implementation.
The purpose of the Dispatcher Optimizer Tool is to provide guidance to help you find it, and point you to resources that can build your understanding of this critical component of a performant and resilient AEM deployment.
Our team will be watching the GitHub issues closely, so please reach out if you have any questions or concerns!
