Configuration Reference

All runtime behaviour is controlled by magento_ultra.ini. The file lives at:

Linux: /etc/accelerate-guru/magento_ultra.ini
macOS (Homebrew): $(brew --prefix)/etc/accelerate-guru/magento_ultra.ini
Custom: pass --from-dir /path/to/dir to the binary

The file is hot-reloaded — most changes take effect on the next request without a restart. Exceptions are noted in the tables below.

Additional live-rule files in the same directory are also hot-reloaded:

blocklist.ini — IP/CIDR deny rules
redirects.ini — URL rewrite rules
text-replace.ini — global HTML text substitutions

#Table of contents

[license]
[server]
[tls_ssl]
[security]
[stats]
[cache]
[magento_redis]
[auth_detection]
[mysql_proxy]
[network]
[service_worker]
[optimization_global]
[optimization_html]
[optimization_assets]
[optimization_fonts]
[optimization_images]
[optimization_speculation]
[domain_masking]
Live rule files
Full default config

#`[license]`

Controls activation. The [license] section is always read from the main magento_ultra.ini — per-domain overlay files cannot override it.

Key	Type	Default	Hot-reload	Description
`key`	string	(empty)	Yes	Your activation token from the account dashboard. Use `dev` for `.test`/`.local`/`.internal` hostnames (always free). Empty = transparent mode (no optimisations).
`store_view_id`	string	`all`	Yes	Restrict activation to a single Magento store view ID, or `all` to cover every store view served by this instance.

[license]
key            = live_xxxxxxxxxxxxxxxxxxxxxxxx
store_view_id  = all

#`[server]`

Core networking settings. Changes to http_port and https_port require a restart; all others are hot-reloaded.

Key	Type	Default	Hot-reload	Description
`http_port`	integer	`80`	No	Port to listen for plain HTTP connections.
`https_port`	integer	`443`	No	Port to listen for HTTPS/TLS connections.
`magento_dir`	path	`/var/www/magento`	Yes	Path to the Magento root directory (where `app/etc/env.php` lives). Used to auto-detect store configuration during `--check` runs.
`upstream_addr`	string	`127.0.0.1`	Yes	IP address or hostname of the Magento HTTP server (origin).
`upstream_port`	integer	`8080`	Yes	Port on which Magento (or your web server like Nginx/Apache) listens for plain HTTP.
`workers`	integer	`0`	No	Number of worker threads. `0` = one per CPU core. Increase only if CPU is not the bottleneck.

[server]
http_port     = 80
https_port    = 443
magento_dir   = /var/www/magento
upstream_addr = 127.0.0.1
upstream_port = 8080
workers       = 0

#`[tls_ssl]`

TLS termination and certificate management. The ssl_mode key controls which certificate source is used.

Key	Type	Default	Hot-reload	Description
`upstream_tls`	bool	`false`	Yes	Set to `true` if the upstream Magento server itself requires HTTPS (rare; only needed when Magento is on a remote server with a valid cert).
`ssl_mode`	enum	`self_signed`	No	Certificate source: `self_signed` (auto-generates a multi-SAN cert), `manual` (provide your own cert/key), `local_ca` (sign with a local CA you trust), `acme` (auto-provision via Let's Encrypt).
`ssl_cert`	path	(empty)	No	Path to PEM certificate file. Used when `ssl_mode = manual`.
`ssl_key`	path	(empty)	No	Path to PEM private key file. Used when `ssl_mode = manual`.
`ssl_cache_dir`	path	`./cache/ssl`	No	Directory where generated PEM material is stored (for `self_signed`, `local_ca`, `acme`).
`ssl_extra_sans`	string	(empty)	No	Comma-separated additional Subject Alternative Names to include in generated certificates (e.g. `shop.example.com,api.example.com`).
`acme_email`	string	(empty)	No	Email address for ACME (Let's Encrypt) account registration. Required when `ssl_mode = acme`.
`acme_directory`	URL	Let's Encrypt prod	No	ACME directory URL. Defaults to Let's Encrypt production. Use `https://acme-staging-v02.api.letsencrypt.org/directory` for testing.

[tls_ssl]
upstream_tls    = false
ssl_mode        = self_signed
ssl_cert        =
ssl_key         =
ssl_cache_dir   = ./cache/ssl
ssl_extra_sans  =
acme_email      =

Tip

For local development, ssl_mode = self_signed is ideal — Accelerate Guru generates a certificate automatically for every hostname it serves. Add the local CA to your browser's trust store once to avoid security warnings.

#`[security]`

WAF, bot detection, admin authentication, and access control. See Smart WAF & Security for the full deep-dive.

Key	Type	Default	Hot-reload	Description
`auth_mode`	integer	`0`	Yes	HTTP Basic Auth enforcement: `0` = off, `1` = admin paths only, `2` = entire site. Use `2` on staging environments to gate access.
`auth_user`	string	`admin`	Yes	Username for HTTP Basic Auth (when `auth_mode` ≥ 1).
`auth_pass`	string	(empty)	Yes	Password for HTTP Basic Auth. Leave empty to disable auth even when `auth_mode` is set.
`enable_smart_waf`	bool	`true`	Yes	Enable the in-process WAF. Scores every request for SQL injection, path traversal, bot fingerprints, and rate violations.
`disable_waf_on_admin`	bool	`true`	Yes	Skip WAF checks on the admin path. Admin POST bodies often resemble injection patterns (product descriptions with special chars); this avoids false positives.
`admin_path`	string	`/admin`	Yes	Your Magento admin URL path. Used for `disable_waf_on_admin` scoping and `auth_mode = 1`.
`block_threshold`	integer	`3`	Yes	Number of WAF violations from one IP before it is added to the runtime blocklist automatically.
`log_file`	path	`/var/log/accelerate-guru/waf.log`	Yes	Path where WAF block events are logged.
`enable_bot_detection`	bool	`true`	Yes	Enable heuristic bot detection (user-agent analysis, header coherence, TLS fingerprint checks). Detected bots are challenged or blocked depending on their score.
`bypass_ips`	string	(empty)	Yes	Comma-separated IPs that bypass the cache and all optimisations. For debugging only — do not use in production.

[security]
auth_mode           = 0
auth_user           = admin
auth_pass           =
enable_smart_waf    = true
disable_waf_on_admin = true
admin_path          = /admin
block_threshold     = 3
log_file            = /var/log/accelerate-guru/waf.log
enable_bot_detection = true
bypass_ips          =

#`[stats]`

Controls the /stats-ag live dashboard.

Key	Type	Default	Hot-reload	Description
`enabled`	bool	`true`	Yes	Enable the dashboard. Set to `false` to disable entirely.
`allowed_ips`	string	`127.0.0.1`	Yes	Comma-separated IP addresses allowed to access `/stats-ag`. Requests from other IPs receive `403 Forbidden`. Add your office IP or VPN IP here.

[stats]
enabled     = true
allowed_ips = 127.0.0.1, 10.0.0.5

#`[cache]`

Page caching via DragonflyDB. See DragonflyDB Power for the deep-dive.

Key	Type	Default	Hot-reload	Description
`enabled`	bool	`true`	Yes	Master cache switch.
`redis_host`	string	`127.0.0.1`	No	DragonflyDB (or Redis) hostname or IP.
`redis_port`	integer	`6379`	No	DragonflyDB port.
`redis_password`	string	(empty)	No	DragonflyDB authentication password (leave empty if none).
`redis_db`	integer	`0`	No	DragonflyDB database index (0–15).
`cache_ttl_fallback`	integer	`86400`	Yes	Page TTL in seconds when MySQL proxy invalidation is disabled. Default: 24 hours.
`cache_exclude_params`	string	see below	Yes	Comma-separated query parameters stripped from the URL before computing the cache key. Marketing/tracking params should be listed here.
`cache_exclude_paths`	string	see below	Yes	Comma-separated URL prefixes that bypass the cache entirely (e.g. checkout, account).
`graphql_cache`	bool	`false`	Yes	Cache GraphQL POST responses. Disabled by default because GraphQL queries can contain session-specific data.
`static_asset_cache`	bool	`true`	Yes	Cache optimised JS/CSS bytes so minification is not repeated on every request.
`static_asset_cache_ttl`	integer	`604800`	Yes	TTL in seconds for cached static assets. Default: 7 days.
`vary_cookies`	string	see below	Yes	Comma-separated cookie names whose values are used to segment the cache (not bypass it). Used for multi-currency/multi-locale stores.
`customer_cache_ttl_secs`	integer	`30`	Yes	TTL in seconds for per-customer page cache entries (logged-in visitors). Shorter than the anonymous TTL because logged-in pages can change frequently.
`customer_data_endpoint_ttl_secs`	integer	`10`	Yes	TTL in seconds for customer-data JSON responses (e.g. `/customer/section/load/`). Very short to keep cart and messages fresh.
`customer_data_endpoints`	string	see below	Yes	Comma-separated URL prefixes treated as per-customer data endpoints and cached with `customer_data_endpoint_ttl_secs`.

Default excluded params: gclid, utm_source, utm_medium, utm_campaign, utm_content, utm_term, fbclid

Default excluded paths: /customer/, /checkout/, /wishlist/, /sales/, /newsletter/, /paypal/, /multishipping/

Default vary cookies: esw-currency, esw-location, store

Default customer data endpoints: /customer/section/load/

[cache]
enabled               = true
redis_host            = 127.0.0.1
redis_port            = 6379
redis_password        =
redis_db              = 0
cache_ttl_fallback    = 86400
cache_exclude_params  = gclid,utm_source,utm_medium,utm_campaign,utm_content,utm_term,fbclid
cache_exclude_paths   = /customer/,/checkout/,/wishlist/,/sales/,/newsletter/,/paypal/,/multishipping/
graphql_cache         = false
static_asset_cache    = true
static_asset_cache_ttl = 604800
vary_cookies          = esw-currency,esw-location,store
customer_cache_ttl_secs              = 30
customer_data_endpoint_ttl_secs      = 10
customer_data_endpoints              = /customer/section/load/

#`[magento_redis]`

Read-only connection to Magento's own Redis/DragonflyDB Full Page Cache. Used for tag-based cache invalidation — when Magento evicts a tag, Accelerate Guru receives the signal and evicts its own matching entries. Disabled by default.

Not the same as session storage. Magento uses separate Redis databases for FPC (typically db 1) and PHP sessions (typically db 2). The [auth_detection] section below connects to the session database.

Key	Type	Default	Hot-reload	Description
`enabled`	bool	`false`	Yes	Enable Magento Redis FPC integration.
`host`	string	`127.0.0.1`	No	Magento's Redis host.
`port`	integer	`6379`	No	Magento's Redis port.
`password`	string	(empty)	No	Magento's Redis password.
`db`	integer	`1`	No	Magento typically uses database `1` for FPC.

#`[auth_detection]`

Controls how Accelerate Guru classifies each incoming request as Anonymous, Customer, or Admin. The classification drives cache key selection (anonymous requests share one slot; each logged-in customer gets their own) and cache-bypass logic (admin requests are never cached).

The primary method (mode = auto) reads Magento's PHP session directly from Redis using the address declared in app/etc/env.php. This is authoritative — it works even when the browser has cleared frontend_cid or other client-side cookies that AG previously relied on. When the session Redis is unavailable or sessions are file-based, AG falls back to cookie-based heuristics.

Key	Type	Default	Hot-reload	Description
`mode`	string	`auto`	No	Detection strategy. `auto` = read session Redis from `env.php` (recommended). `cookies` = legacy cookie heuristic only.
`session_redis_host`	string	(empty)	No	Override for Magento's session Redis host. Leave blank to use what `env.php` declares. This connects to the session database (e.g. db 2), not the FPC database in `[magento_redis]`.
`session_redis_port`	integer	`6379`	No	Override for Magento's session Redis port.
`session_redis_db`	integer	`0`	No	Override for Magento's session Redis database index.
`session_redis_password`	string	(empty)	No	Override for Magento's session Redis password.
`session_state_lru_size`	integer	`5000`	No	Maximum number of `PHPSESSID → state` entries kept in process memory. Reduces Redis round-trips on burst traffic.
`session_state_lru_ttl_secs`	integer	`5`	No	How long a cached classification is considered valid. A freshly-logged-in customer is recognised within this many seconds.
`enable_per_customer_cache`	bool	`true`	Yes	Give each logged-in customer their own cache slot. When disabled, logged-in pages bypass the cache entirely (they always hit Magento).
`enable_cache_poisoning_sanity_check`	bool	`true`	Yes	Scan the first 64 KiB of every response before storing it as anonymous. If logged-in markers are found, the entry is rejected and a counter is incremented. Cheap, highly recommended.

[auth_detection]
mode                               = auto
session_redis_host                 =
session_redis_port                 = 6379
session_redis_db                   = 0
session_redis_password             =
session_state_lru_size             = 5000
session_state_lru_ttl_secs         = 5
enable_per_customer_cache          = true
enable_cache_poisoning_sanity_check = true

#How it works

Incoming request (with PHPSESSID cookie)
  │
  ├─► In-process LRU hit? → use cached state (no Redis call)
  │
  ├─► Read sess_<PHPSESSID> from Magento session Redis
  │       ├─ customer_id > 0  → Customer { id, group }  → per-customer cache key
  │       ├─ user_id in admin block → Admin              → bypass cache
  │       └─ none of the above   → Anonymous             → shared cache key
  │
  └─► Session Redis unreachable or file-based sessions?
          → Cookie heuristic fallback (frontend_cid, admin= cookie)

After an anonymous response is received from upstream, the sanity check scans for markers like "isLoggedIn":true before committing the entry to the shared anonymous cache. This prevents a race condition where Magento returns logged-in HTML for a session that the proxy just classified as anonymous.

#`[mysql_proxy]`

An optional MySQL query cache that sits between Magento's PHP application and the MySQL database. Point Magento's env.php at listen_port instead of the real MySQL port to enable it. See DragonflyDB Power for the architecture.

Key	Type	Default	Hot-reload	Description
`enabled`	bool	`false`	No	Enable the MySQL proxy. Requires a restart.
`listen_port`	integer	`3307`	No	Port on which the MySQL proxy listens. Point Magento at this port.
`mysql_host`	string	`127.0.0.1`	No	Actual MySQL/MariaDB host.
`mysql_port`	integer	`3306`	No	Actual MySQL port.
`mysql_user`	string	(empty)	No	MySQL username.
`mysql_password`	string	(empty)	No	MySQL password.
`select_cache_enabled`	bool	`true`	Yes	Cache SELECT query results. Invalidated automatically on INSERT/UPDATE/DELETE/DDL for the same table.
`cache_ttl_fallback`	integer	`0`	Yes	TTL for cached queries in seconds. `0` = never expire (invalidated only by writes).
`warmup_sitemap`	URL	(empty)	Yes	URL of an XML sitemap. At startup, the proxy fetches all URLs and populates the page cache.
`warmup_concurrency`	integer	`2`	Yes	Number of concurrent warmup fetches.

[mysql_proxy]
enabled             = false
listen_port         = 3307
mysql_host          = 127.0.0.1
mysql_port          = 3306
mysql_user          = magento
mysql_password      = secret
select_cache_enabled = true
cache_ttl_fallback  = 0
warmup_sitemap      = https://yourstore.com/sitemap.xml
warmup_concurrency  = 4

#`[network]`

HTTP response headers and compression settings.

Key	Type	Default	Hot-reload	Description
`compression_priority`	string	`zstd,br,gzip`	Yes	Order of preferred compression encodings. The first one the browser supports is used. All three variants are generated at cache-fill time; selection is zero-CPU at request time.
`static_cache_max_age`	integer	`31536000`	Yes	`Cache-Control: max-age` for static assets (CSS, JS, images). Default: 1 year (browsers only re-fetch when the URL changes).
`page_cache_control`	string	`public, max-age=5, stale-while-revalidate=60`	Yes	`Cache-Control` header sent on HTML responses. `stale-while-revalidate` lets browsers serve a stale page while fetching a fresh one — users never see a loading spinner on repeat visits.
`robots_txt_fallback`	bool	`true`	Yes	Serve a permissive `robots.txt` when the upstream returns an error (prevents unnecessary crawl blocks during maintenance).
`learn_early_hints`	bool	`true`	Yes	Collect critical resource URLs from HTML responses and emit them as `HTTP/2 103 Early Hints` on the next request.

#`[service_worker]`

Browser-side caching via a registered Service Worker. See SSE Service Worker for the deep-dive.

Key	Type	Default	Hot-reload	Description
`enabled`	bool	`false`	Yes	Enable the service worker. Test thoroughly on your theme before enabling in production — see the deep-dive guide.
`mode`	enum	`adaptive`	Yes	`off` = inject nothing. `static` = cache JS/CSS/fonts/images only. `html` = also cache HTML pages. `adaptive` = like `html`, but auto-downgrades to `static` when session cookies are detected.
`realtime_invalidation`	bool	`true`	Yes	Push SSE invalidation events to the browser when product prices or stock change. Requires `enabled = true`.
`bypass_paths`	string	see below	Yes	URL prefixes the service worker must never intercept. Always include checkout and account paths.
`html_max_age`	integer	`600`	Yes	Maximum age (seconds) of HTML pages cached in the service worker. After this, the SW serves stale and fetches fresh in the background.
`theme`	enum	`auto`	Yes	`auto` = detect theme from response. `skip` = disable theme-specific compatibility patches entirely. `force` = always apply patches regardless of detection.

Default bypass paths: /checkout, /customer, /admin, /rest/, /graphql, /paypal, /onepage, /sales

#`[optimization_global]`

Master switches for all HTML optimisations.

Key	Type	Default	Hot-reload	Description
`enabled`	bool	`true`	Yes	Master optimisation switch. Set to `false` to disable all HTML rewrites instantly (useful for emergency debugging).
`html_rewrite`	bool	`true`	Yes	Enable HTML response rewriting. When `false`, responses are passed through unchanged (compression and caching still work).

#`[optimization_html]`

Fine-grained HTML transformation controls.

Key	Type	Default	Hot-reload	Description
`enable_dom_flattening`	bool	`true`	Yes	Collapse single-child wrapper elements to reduce DOM depth and improve INP (Interaction to Next Paint).
`max_dom_depth`	integer	`20`	Yes	Maximum DOM depth before flattening is applied.
`add_nofollow`	bool	`false`	Yes	Inject `<meta name="robots" content="noindex,nofollow">`. Warning: this blocks all search engine indexing. Use only on staging/dev environments.
`inject_preconnect`	bool	`true`	Yes	Add `<link rel="preconnect">` and `<link rel="dns-prefetch">` for detected third-party origins (fonts, analytics, payment SDKs).
`enforce_accessibility`	bool	`true`	Yes	Auto-fix common accessibility issues: missing `alt` attributes, broken ARIA roles, missing viewport `user-scalable`.
`fix_aria_roles`	bool	`true`	Yes	Correct invalid or misplaced ARIA role attributes.
`fix_touch_targets`	bool	`false`	Yes	Increase the CSS minimum touch target size to 44×44 px (WCAG 2.5.5). May conflict with theme styles — test before enabling.
`fix_contrast`	bool	`false`	Yes	Increase text contrast to meet WCAG AA minimums where violations are detected. May conflict with brand colours — test before enabling.
`auto_meta_description`	bool	`true`	Yes	Generate a `<meta name="description">` from page content when one is absent.
`remove_unload_handlers`	bool	`true`	Yes	Strip `onunload` event handlers that prevent the page from entering the bfcache (back/forward cache). Significant performance win for repeat navigation.
`esi_enabled`	bool	`false`	Yes	Process `<esi:include>` tags (Varnish/ESI mode). Enable only if your Nginx/Apache is configured to pass ESI syntax.
`luma_block_cache`	bool	`false`	Yes	Cache Luma theme header/footer/navigation blocks separately for faster assembly.
`theme_family`	enum	`auto`	Yes	`auto` = detect per response. Force to `luma`, `hyva`, or `generic` if auto-detection causes issues.
`content_visibility`	bool	`false`	Yes	Inject `content-visibility: auto` on long off-screen lists (PLP grids, reviews, related products, footer). Improves INP and Total Blocking Time. Opt-in — test on custom themes before enabling.
`inject_structured_data`	bool	`false`	Yes	Inject JSON-LD product schema into product pages. Experimental — extraction heuristics may not be accurate for all themes.
`critical_css_extraction`	bool	`false`	Yes	Automatically extract and inline critical CSS. Requires a warmup pass to build the critical CSS database.

#`[optimization_assets]`

JavaScript and CSS optimisation.

Key	Type	Default	Hot-reload	Description
`enable_tree_shaking`	bool	`true`	Yes	Minify and tree-shake JavaScript bundles using the `oxc` compiler. Typically reduces JS size by 20–35%.
`enable_critical_css`	bool	`false`	Yes	Defer non-critical stylesheets. Warning: requires proper critical CSS (see `critical_css_extraction`) or you will see a Flash of Unstyled Content (FOUC).
`force_defer_js`	bool	`true`	Yes	Add `defer` to all `<script>` tags that lack it. Non-blocking JS loading is the single biggest Lighthouse TBT improvement on most Magento stores.
`delay_third_party_js`	bool	`false`	Yes	Delay all third-party JS and iframes until after the first user interaction. Dramatically improves Lighthouse on stores with many trackers/chat widgets. A built-in skiplist protects payment SDKs, anti-fraud tools, and CAPTCHAs.
`delay_third_party_overrides`	string	(empty)	Yes	Force or prevent delay for specific hosts. Prefix with `!` to never delay. Example: `analytics.example.com,!pay.stripe.com`
`css_minify`	bool	`true`	Yes	Minify CSS responses.
`inject_script_preloads`	bool	`true`	Yes	Add `<link rel="preload" as="script">` for critical first-party scripts.
`inline_critical_js`	bool	`false`	Yes	Inline small critical scripts directly into the HTML. Saves a network round-trip but risks serving stale code if the script changes.
`inline_critical_js_max_size`	integer	`32768`	Yes	Maximum size (bytes) of scripts eligible for inlining. Default: 32 KB.

#`[optimization_fonts]`

Self-hosted Google / Bunny font proxying. Eliminates the third-party DNS+TLS round-trip and prevents GDPR-concern IP leakage to Google's servers.

Key	Type	Default	Hot-reload	Description
`enabled`	bool	`false`	Yes	Enable font self-hosting. When enabled, Google/Bunny font CSS is fetched and rewritten to serve fonts from your edge.
`backend`	enum	`google`	Yes	Font source: `google` (fonts.googleapis.com) or `bunny` (fonts.bunny.net — tracker-free mirror).
`cache_dir`	path	`./cache/fonts`	Yes	Directory where downloaded font files are stored.
`preload_top_n`	integer	`2`	Yes	Inject `<link rel="preload" as="font">` for the first N fonts in a page's `@font-face` list.
`force_display`	enum	`swap`	Yes	Value for `font-display` in `@font-face` rules when rewriting external (Google/Bunny) font CSS. `swap` prevents invisible text during load.
`force_font_display`	enum	`swap`	Yes	Value for `font-display` applied when rewriting self-hosted `@font-face` declarations already present in your theme's CSS. Mirrors `force_display` for local fonts.
`keep_unicode_ranges`	string	(empty)	Yes	Comma-separated unicode-range names to retain (e.g. `latin,latin-ext`). Empty = keep all. Use to reduce font download size.
`fetch_timeout_secs`	integer	`8`	Yes	Timeout for fetching font files from the upstream font service.

#`[optimization_images]`

AVIF/WebP encoding and image optimisation pipeline. See Edge Image Pipeline for full details.

Key	Type	Default	Hot-reload	Description
`image_avif`	bool	`true`	Yes	Enable AVIF encoding. Images in HTML responses are rewritten to serve AVIF to browsers that support it.
`avif_quality`	integer	`65`	Yes	AVIF quality (1–100). 65 is an excellent balance of file size and visual quality. Values above 80 produce files nearly as large as JPEG with little visible benefit.
`avif_speed`	integer	`1`	Yes	AVIF encoder speed (1–10). `1` = slowest/smallest, `10` = fastest/largest. In background encoding, slow is always preferred.
`avif_max_size`	integer	`10485760`	Yes	Skip AVIF encoding for images larger than this (bytes). Default: 10 MB.
`image_cache_dir`	path	`./cache/images`	Yes	Directory for storing encoded AVIF/WebP files.
`avif_on_the_fly`	bool	`false`	Yes	`true` = encode AVIF synchronously on the first request (adds latency). `false` = serve original on first request, encode in background (recommended).
`image_placeholders`	bool	`false`	Yes	Generate BlurHash low-resolution placeholders for lazy-loaded images. Provides a pleasant loading experience.
`image_revalidation_interval`	integer	`1800`	Yes	Re-check cached images against the origin every N seconds. Default: 30 minutes.
`freshness_max_age`	integer	`5`	Yes	If an upstream `Age` response header exceeds this (seconds), force a fresh fetch instead of caching the already-stale response. `0` = disabled.
`inject_asset_dimensions`	bool	`true`	Yes	Add `width` and `height` attributes to `<img>` elements that lack them. Eliminates Cumulative Layout Shift (CLS).
`preload_lcp_image`	bool	`true`	Yes	Detect the Largest Contentful Paint image and add `fetchpriority="high"` and a `<link rel="preload">` for it. Largest single LCP improvement available.
`optimize_above_fold`	bool	`true`	Yes	Disable lazy-loading on the first N images so they load immediately.
`above_fold_count`	integer	`3`	Yes	Number of images to treat as above-fold (when `optimize_above_fold = true`).
`responsive_images`	bool	`true`	Yes	Generate `srcset` and `sizes` attributes on product images to serve appropriately sized images for each device.

#`[optimization_speculation]`

Chrome/Edge Speculation Rules for prerendering and prefetching pages before the user clicks. See Smart Speculation.

Key	Type	Default	Hot-reload	Description
`enabled`	bool	`true`	Yes	Enable Speculation Rules injection.
`smart_speculation`	bool	`true`	Yes	Use navigation pattern learning to refine speculation targets.
`home_prerender`	string	see default	Yes	URL patterns eligible for prerendering from the homepage.
`category_prefetch`	string	see default	Yes	URL patterns eligible for prefetching from category pages.
`product_prefetch`	string	see default	Yes	URL patterns eligible for prefetching from product pages.
`eagerness`	enum	`moderate`	Yes	`conservative` = only on explicit hover. `moderate` = hover + visible links. `eager` = all eligible links immediately.

Defaults:

home_prerender = /catalog/category/view/*, /cms/*
category_prefetch = /catalog/product/view/*
product_prefetch = /checkout/cart, /checkout

#`[domain_masking]`

Multi-host configuration. See Domain Masking for the full guide.

Note

The [domain_masking] section is not present in the default magento_ultra.ini because it is only needed when you serve multiple hostnames. To activate it, add the section to your config file (or to a per-domain overlay under domain_masking/hostname.ini). The defaults listed below apply when the section is absent — link rewriting is enabled for all content types by default as soon as you create an overlay file.

Key	Type	Default	Hot-reload	Description
`enabled`	bool	`true`	Yes	Enable domain masking (link rewriting for masked hosts).
`rewrite_html`	bool	`true`	Yes	Rewrite origin host references in HTML responses.
`rewrite_css`	bool	`true`	Yes	Rewrite in CSS (e.g. `background-image: url()` references).
`rewrite_xml`	bool	`true`	Yes	Rewrite in XML (sitemaps, RSS feeds).
`rewrite_json`	bool	`true`	Yes	Rewrite in JSON API responses.
`rewrite_js`	bool	`true`	Yes	Rewrite in JavaScript (careful with minified bundles).
`rewrite_set_cookie`	bool	`true`	Yes	Rewrite `Domain=` attribute in `Set-Cookie` headers.
`rewrite_location`	bool	`true`	Yes	Rewrite `Location:` redirect headers.
`rewrite_link_header`	bool	`true`	Yes	Rewrite `Link:` preload headers.
`rewrite_csp`	bool	`true`	Yes	Rewrite Content-Security-Policy headers to include the public host.
`rewrite_inline_js`	bool	`true`	Yes	Rewrite host references inside inline `<script>` blocks.
`rewrite_request_body`	bool	`false`	Yes	Rewrite the request body (e.g. GraphQL variables containing absolute URLs). Disabled by default for performance.
`strict_misdirected`	bool	`false`	Yes	Reject requests with `421 Misdirected Request` if the `Host` header doesn't match a known masked domain.
`public_host`	string	(empty)	Yes	The public hostname this overlay applies to. Set in per-domain overlay files.
`origin_host`	string	(empty)	Yes	The Magento origin hostname (as it appears in HTML/URLs inside Magento).
`aliases`	string	(empty)	Yes	Extra origin→public host pairs, comma-separated as `origin=public`.

Per-domain overrides live in domain_masking/hostname.ini files and inherit all main config settings.

#Live rule files

#`blocklist.ini`

One rule per line. Hot-reloaded within 500 ms of any change.

; Block a specific IP
203.0.113.42

; Block an entire subnet
198.51.100.0/24

; Allow-override (wins over any block)
!203.0.113.1

; Comments start with ; or #

#`redirects.ini`

One rule per line in the format pattern = target [status]. Patterns are regular expressions. Hot-reloaded on every request.

; Simple path redirect (301 permanent)
^/old-product-url$ = /new-product-url 301

; Regex with capture group (302 temporary)
^/blog/(\d{4})/(.+)$ = /articles/$1/$2 302

; Redirect old category URL
^/category\.html$ = /new-category 301

Note

Redirects are evaluated before the cache lookup. This means redirecting is always fast, even on cache misses.

#`text-replace.ini`

Global find-and-replace applied to every HTML response. One pair per line.

; Replace a phone number across all pages
+1 (555) 000-0000 = +1 (555) 123-4567

; Update a brand name after rebranding
Old Company Name = New Company Name

; Fix a typo that appears in many places
recieve = receive

#Full default config

; Accelerate Guru — magento_ultra.ini
; Hot-reloaded. Most changes take effect on the next request.

[license]
key            =
store_view_id  = all

[server]
http_port      = 80
https_port     = 443
magento_dir    = /var/www/magento
upstream_addr  = 127.0.0.1
upstream_port  = 8080
workers        = 0

[tls_ssl]
upstream_tls   = false
ssl_mode       = self_signed
ssl_cert       =
ssl_key        =
ssl_cache_dir  = ./cache/ssl
ssl_extra_sans =
acme_email     =
acme_directory = https://acme-v02.api.letsencrypt.org/directory

[security]
auth_mode            = 0
auth_user            = admin
auth_pass            =
enable_smart_waf     = true
disable_waf_on_admin = true
admin_path           = /admin
block_threshold      = 3
log_file             = /var/log/accelerate-guru/waf.log
enable_bot_detection = true
bypass_ips           =

[stats]
enabled     = true
allowed_ips = 127.0.0.1

[cache]
enabled               = true
redis_host            = 127.0.0.1
redis_port            = 6379
redis_password        =
redis_db              = 0
cache_ttl_fallback    = 86400
cache_exclude_params  = gclid,utm_source,utm_medium,utm_campaign,utm_content,utm_term,fbclid
cache_exclude_paths   = /customer/,/checkout/,/wishlist/,/sales/,/newsletter/,/paypal/,/multishipping/
graphql_cache         = false
static_asset_cache    = true
static_asset_cache_ttl = 604800
vary_cookies          = esw-currency,esw-location,store
customer_cache_ttl_secs              = 30
customer_data_endpoint_ttl_secs      = 10
customer_data_endpoints              = /customer/section/load/

[magento_redis]
enabled  = false
host     = 127.0.0.1
port     = 6379
password =
db       = 1

[auth_detection]
mode                               = auto
session_redis_host                 =
session_redis_port                 = 6379
session_redis_db                   = 0
session_redis_password             =
session_state_lru_size             = 5000
session_state_lru_ttl_secs         = 5
enable_per_customer_cache          = true
enable_cache_poisoning_sanity_check = true

[mysql_proxy]
enabled              = false
listen_port          = 3307
mysql_host           = 127.0.0.1
mysql_port           = 3306
mysql_user           =
mysql_password       =
select_cache_enabled = true
cache_ttl_fallback   = 0
warmup_sitemap       =
warmup_concurrency   = 2

[network]
compression_priority  = zstd,br,gzip
static_cache_max_age  = 31536000
page_cache_control    = public, max-age=5, stale-while-revalidate=60
robots_txt_fallback   = true
learn_early_hints     = true

[service_worker]
enabled              = false
mode                 = adaptive
realtime_invalidation = true
bypass_paths         = /checkout,/customer,/admin,/rest/,/graphql,/paypal,/onepage,/sales
html_max_age         = 600
theme                = auto   ; auto | skip | force

[optimization_global]
enabled      = true
html_rewrite = true

[optimization_html]
enable_dom_flattening    = true
max_dom_depth            = 20
add_nofollow             = false
inject_preconnect        = true
enforce_accessibility    = true
fix_aria_roles           = true
fix_touch_targets        = false
fix_contrast             = false
auto_meta_description    = true
remove_unload_handlers   = true
esi_enabled              = false
luma_block_cache         = false
theme_family             = auto
content_visibility       = false
inject_structured_data   = false
critical_css_extraction  = false

[optimization_assets]
enable_tree_shaking       = true
enable_critical_css       = false
force_defer_js            = true
delay_third_party_js      = false
delay_third_party_overrides =
css_minify                = true
inject_script_preloads    = true
inline_critical_js        = false
inline_critical_js_max_size = 32768

[optimization_fonts]
enabled            = false
backend            = google
cache_dir          = ./cache/fonts
preload_top_n      = 2
force_display      = swap
force_font_display = swap
keep_unicode_ranges =
fetch_timeout_secs = 8

[optimization_images]
image_avif                  = true
avif_quality                = 65
avif_speed                  = 1
avif_max_size               = 10485760
image_cache_dir             = ./cache/images
avif_on_the_fly             = false
image_placeholders          = false
image_revalidation_interval = 1800
freshness_max_age           = 5
inject_asset_dimensions     = true
preload_lcp_image           = true
optimize_above_fold         = true
above_fold_count            = 3
responsive_images           = true

[optimization_speculation]
enabled           = true
smart_speculation = true
home_prerender    = /catalog/category/view/*, /cms/*
category_prefetch = /catalog/product/view/*
product_prefetch  = /checkout/cart, /checkout
eagerness         = moderate

[domain_masking]
enabled              = true
rewrite_html         = true
rewrite_css          = true
rewrite_xml          = true
rewrite_json         = true
rewrite_js           = true
rewrite_set_cookie   = true
rewrite_location     = true
rewrite_link_header  = true
rewrite_csp          = true
rewrite_inline_js    = true
rewrite_request_body = false
strict_misdirected   = false

; ---- [domain_masking] is OPTIONAL — add it only when using multi-host setups ----
; [domain_masking]
; public_host  = shop.example.com
; origin_host  = origin.example.com
; aliases      =

#Table of contents

#[license]

#[server]

#[tls_ssl]

#[security]

#[stats]

#[cache]

#[magento_redis]

#[auth_detection]

#How it works

#[mysql_proxy]

#[network]

#[service_worker]

#[optimization_global]

#[optimization_html]

#[optimization_assets]

#[optimization_fonts]

#[optimization_images]

#[optimization_speculation]

#[domain_masking]