۶Ƶ

DocumentationAEMDispatcher Guide

Install Dispatcher installing-dispatcher

Last update: Thu Jul 24 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin

Use the Dispatcher Release Notes page to obtain the latest Dispatcher installation file for your operating system and web server. Dispatcher release numbers are independent of the ۶Ƶ Experience Manager release numbers and are compatible with ۶Ƶ Experience Manager 6.x, 5.x and ۶Ƶ CQ 5.x releases.

NOTE
۶Ƶ Experience Manager 6.5 requires Dispatcher version 4.3.2 or higher. That said, Dispatcher versions are independent of AEM, for example, Dispatcher version 4.3.2 is also compatible with ۶Ƶ Experience Manager 6.4.

The following file naming convention is used:

dispatcher-<web-server>-<operating-system>-<dispatcher-version-number>.<file-format>

For example, the dispatcher-apache2.4-linux-x86_64-ssl-4.3.1.tar.gz file contains Dispatcher version 4.3.1 for an Apache 2.4 web server that runs on Linux® i686 and is packaged using the tar format.

The following table lists the web server identifier that is used in file names for each web server:

Web Server
Installation Kit
Apache 2.4
dispatcher-apache**2.4**-<other parameters>
Microsoft® Internet Information Server 7.5, 8, 8.5, 10
dispatcher-**iis**-<other parameters>
Sun Java™ Web Server iPlanet
dispatcher-**ns**-<other parameters>
CAUTION
Be sure you install the latest version of Dispatcher that is available for your platform. On a yearly basis, upgrade your Dispatcher instance to use the latest version to take advantage of product improvements.
NOTE
Customers upgrading specifically from version 4.3.3 to version 4.3.4 should notice a different behavior in how caching headers are set for uncacheable content. To read more about this change, see the Release Notes page.

Each archive contains the following files:

  • the Dispatcher modules
  • an example configuration file
  • the README file that contains installation instructions and last-minute information
  • the CHANGES file that lists issues fixed in current and past releases
NOTE
Check the README file for any last-minute changes / platform-specific notes before starting the installation.

Microsoft® Internet Information Server microsoft-internet-information-server

For information on how to install this Web server, see the following resources:

  • Microsoft®’s own documentation on the Internet Information Server

Required IIS components required-iis-components

IIS versions 8.5 and 10 require that the following IIS components are installed:

  • ISAPI Extensions

Also, you must add the Web server (IIS) role. Use Server Manager to add the role and the components.

Microsoft® IIS - Installing the Dispatcher module microsoft-iis-installing-the-dispatcher-module

The required archive for the Microsoft® Internet Information System is:

  • dispatcher-iis-<operating-system>-<dispatcher-release-number>.zip

The ZIP file contains the following files:

File
Description
disp_iis.dll
The Dispatcher dynamic link library file.
disp_iis.ini
Configuration file for the IIS. This example can be updated with your requirements. Note: The ini file must have the same name-root as the dll.
dispatcher.any
An example configuration file for the Dispatcher.
author_dispatcher.any
An example configuration file for Dispatcher working with the author instance.
README
Readme file that contains installation instructions and last-minute information. Note: Check this file before starting the installation.
CHANGES
Changes a file that lists issues fixed in current and past releases.

Use the following procedure to copy the Dispatcher files to the correct location.

  1. Use Windows Explorer to create the <IIS_INSTALLDIR>/Scripts directory, for example, C:\inetpub\Scripts.

  2. Extract the following files from the Dispatcher package into this Scripts directory:

    • disp_iis.dll

    • disp_iis.ini

    • One of the following files depending on if the Dispatcher is working with an AEM author instance or publish instance:

      • Author instance: author_dispatcher.any
      • Publish instance: dispatcher.any

Microsoft® IIS - Configure the Dispatcher INI file microsoft-iis-configure-the-dispatcher-ini-file

To configure the Dispatcher installation, edit the disp_iis.ini file. The basic format of the .ini file is as follows:


[main]
configpath=<path to dispatcher.any>
loglevel=1|2|3
servervariables=0|1
replaceauthorization=0|1

The following table describes each property.

Parameter
Description
configpath
The location of dispatcher.any within the local file system (absolute path).
logfile
The location of the dispatcher.log file. If this location is not set, then log messages go to the Windows event log.
loglevel
Defines the log level used to output messages to the event log. The following values may be specified at the log level for the log file:
0 - error messages only.
1 - errors and warnings.
2 - errors, warnings, and informational messages
3 - errors, warnings, informational messages, and debug messages.
Note: Set the log level to 3 during installation and testing, then to 0 when running in a production environment.
replaceauthorization
Specifies how authorization headers in the HTTP request are handled. The following values are valid:
0 - Authorization headers are not modified.
1 - Replaces any header named “Authorization” other than “Basic” with its Basic <IIS:LOGON\_USER> equivalent.
servervariables
Defines how server variables are processed.
0 - IIS server variables are not sent to the Dispatcher or AEM.
1 - all IIS server variables (such as LOGON\_USER, QUERY\_STRING, ...) are sent to the Dispatcher, together with the requested headers (and also to the AEM instance if not cached).
Server variables include AUTH\_USER, LOGON\_USER, HTTPS\_KEYSIZE and many others. See the IIS documentation for the full list of variables, with details.
enable_chunked_transfer
Defines whether to enable (1) or disable (0) chunk transfer for the client response. The default value is 0.

An example configuration:


[main]
configpath=C:\Inetpub\Scripts\dispatcher.any
loglevel=1
servervariables=1
replaceauthorization=0

Configure Microsoft® IIS configuring-microsoft-iis

Configure IIS to integrate the Dispatcher ISAPI module. In IIS, you use wildcard application mapping.

Configure anonymous access - IIS 8.5 and 10 configuring-anonymous-access-iis-and

The default Flush replication agent on the Author instance is configured so that it does not send security credentials with flush requests. Therefore, the website on which you use the Dispatcher cache must allow anonymous access.

If your website uses an authentication method, the Flush replication agent must be configured accordingly.

  1. Open IIS Manager and select the website that you are using as the Dispatcher cache.
  2. Using Features View mode, in the IIS section double-click Authentication.
  3. If Anonymous Authentication is not enabled, select Anonymous Authentication and in the Actions area click Enable.

Integrate the Dispatcher ISAPI module - IIS 8.5 and 10 integrating-the-dispatcher-isapi-module-iis-and

Use the following procedure to add the Dispatcher ISAPI module to IIS.

  1. Open IIS Manager.

  2. Select the website that you are using as the Dispatcher Cache.

  3. Using Features View mode, in the IIS section double-click Handler Mappings.

  4. In the Actions panel of the Handler Mappings page, click Add Wildcard Script Map, add the following property values, and then click OK:

    • Request Path: *
    • Executable: The absolute path of the disp_iis.dll file, for example C:\inetpub\Scripts\disp_iis.dll.
    • Name: A descriptive name for the handler mapping, for example Dispatcher.

  5. In the dialog box that appears, to add the disp_iis.dll library to the ISAPI and CGI Restrictions list, click Yes.

    For IIS 7.0 and 7.5, the configuration is complete. Continue with the remaining steps if you are configuring IIS 8.0.

  6. (IIS 8.0) In the list of Handler Mappings, select the one that you created, and in the Actions area click Edit.

  7. (IIS 8.0) In the Edit Script Map dialog box, click the Request Restrictions button.

  8. (IIS 8.0) To ensure that the handler is used for files and folders that are not yet cached, deselect Invoke Handler Only If Request Is Mapped To. Click OK.

  9. (IIS 8.0) On the Edit Script Map dialog box, click OK.

Configure access to the cache - IIS 8.5 and 10 configuring-access-to-the-cache-iis-and

Provide the default App Pool user with write-access to the folder that is being used as the Dispatcher cache.

  1. Right-click the root folder of the website that you are using as the Dispatcher cache and click Properties, such as C:\inetpub\wwwroot.

  2. On the Security tab, click Edit, and then in the Permissions dialog box, click Add. A dialog box opens for selecting user accounts. Click the Locations button, select your computer name, and then click OK.

    Keep this dialog box open while you complete the next step.

  3. in IIS Manager, select the IIS site that you are using for the Dispatcher cache, and on the right side of the window, click Advanced Settings.

  4. Select the value of the Application Pool property and copy it to the clipboard.

  5. Return to the open dialog box. In the Enter The Object Names To Select box, type IIS AppPool\ and then paste the contents of your clipboard. The value should look like the following example:

    IIS AppPool\DefaultAppPool

  6. Click the Check Names button. When Windows resolves the user account, click OK.

  7. In the Permissions dialog box for the Dispatcher folder, select the account that you just added, enable all permissions for the account except for Full Control and click OK. Click OK so you can close the folder Properties dialog box.

Register the JSON mime type - IIS 8.5 and 10 registering-the-json-mime-type-iis-and

Use the following procedure to register the JSON MIME type, when you want the Dispatcher to allow JSON calls.

  1. In IIS Manager, select your website and using Features View, double-click Mime Types.

  2. If the JSON extension is not in the list, in the Actions panel click Add, enter the following property values, and then click OK:

    • File Name Extension: .json
    • MIME Type: application/json

Remove the bin hidden segment - IIS 8.5 and 10 removing-the-bin-hidden-segment-iis-and

Use the following procedure to remove the bin hidden segment. Web sites that are not new can contain this hidden segment.

  1. In IIS Manager, select your website and using Features View, double-click Request Filtering.
  2. Select the bin segment, click Remove, and in the confirmation dialog box click Yes.

Log IIS messages to a file - IIS 8.5 and 10 logging-iis-messages-to-a-file-iis-and

Use the following procedure to write Dispatcher log messages to a log file instead of to the Windows Event log. Configure the Dispatcher to use the log file, and provide IIS with write-access to the file.

  1. Use Windows Explorer to create a folder named dispatcher below the logs folder of the IIS installation. The path of this folder for a typical installation is C:\inetpub\logs\dispatcher.

  2. Right-click the Dispatcher folder and click Properties.

  3. On the Security tab, click Edit.

  4. In the Permissions dialog box, click Add. A dialog box opens for selecting user accounts. Click the Locations button, select your computer name, and then click OK.

    Keep this dialog box open while you complete the next step.

  5. in IIS Manager, select the IIS site that you are using for the Dispatcher cache, and on the right side of the window, click Advanced Settings.

  6. Select the value of the Application Pool property and copy it to the clipboard.

  7. Return to the open dialog box. In the Enter The Object Names To Select box, type IIS AppPool\ and then paste the contents of your clipboard. The value should look like the following example:

    IIS AppPool\DefaultAppPool

  8. Click the Check Names button. When Windows resolves the user account, click OK.

  9. In the Permissions dialog box for the Dispatcher folder, select the account that you just added, enable all permissions for the account except for Full Control, and click OK. Click OK so you can close the folder Properties dialog box.

  10. Use a text editor to open the disp_iis.ini file.

  11. To configure the location of the log file, add a line of text similar to the following example, then save the file:

    code language-xml 
    
logfile=C:\inetpub\logs\dispatcher\dispatcher.log

Next steps next-steps

Before you can start using the Dispatcher, you must know the following:

Apache Web Server apache-web-server

CAUTION
Instructions for installation under both Windows and ® are covered here. Be careful when performing the steps.

Install Apache Web Server installing-apache-web-server

For Information about how to install an Apache Web Server read the installation manual - either or in the distribution.

CAUTION
If you are creating an Apache binary by compiling the source files, make sure that you turn on dynamic modules support. Enabling this option can be done using any of the –eԲ-󲹰 options. At a minimum, include the mod_so module.
More information can be found in the Apache Web Server installation manual.

Also see the Apache HTTP Server and .

Apache Web Server - Add the Dispatcher module apache-web-server-add-the-dispatcher-module

The Dispatcher comes as either:

  • Windows: a Dynamic Link Library (DLL)