Installing Dispatcher installing-dispatcher
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 Adobe Experience Manager release numbers and are compatible with Adobe Experience Manager 6.x, 5.x and Adobe CQ 5.x releases.
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:
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
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
- “The Official Microsoft IIS site”
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 components.
Microsoft IIS - Installing the Dispatcher module microsoft-iis-installing-the-dispatcher-module
The required archive for Microsoft Internet Information System is:
dispatcher-iis-<operating-system>-<dispatcher-release-number>.zip
The ZIP file contains the following files:
disp_iis.dll
disp_iis.ini
dispatcher.any
author_dispatcher.any
Use the following procedure to copy the Dispatcher files to the correct location.
-
Use Windows Explorer to create the
<IIS_INSTALLDIR>/Scripts
directory, for example,C:\inetpub\Scripts
. -
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 Dispatcher is working with an AEM author instance or publish instance:
- Author instance:
author_dispatcher.any
- Publish instance:
dispatcher.any
- Author instance:
-
Microsoft IIS - Configure the Dispatcher INI File microsoft-iis-configure-the-dispatcher-ini-file
Edit the disp_iis.ini
file to configure the Dispatcher installation. 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.
dispatcher.any
within the local file system (absolute path).dispatcher.log
file. If this is not set then log messages go to the windows event log.0 - error messages only.
1 - errors and warnings.
2 - errors, warnings and informational messages
3 - errors, warnings, informational and debug messages.
Note: It is recommended to set the log level to 3 during installation and testing, then to 0 when running in a production environment.
0 - Authorization headers are not modified.
1 - Replaces any header named “Authorization” other than “Basic” with its
Basic <IIS:LOGON\_USER>
equivalent.0 - IIS server variables are sent to neither the Dispatcher nor AEM.
1 - all IIS server variables (such as
LOGON\_USER, QUERY\_STRING, ...
) are sent to the Dispatcher, together with the request 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.An example configuration:
[main]
configpath=C:\Inetpub\Scripts\dispatcher.any
loglevel=1
servervariables=1
replaceauthorization=0
Configuring Microsoft IIS configuring-microsoft-iis
Configure IIS to integrate the Dispatcher ISAPI module. In IIS you use wildcard application mapping.
Configuring 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 that you are using a the Dispatcher cache must allow anonymous access.
If your website uses an authentication method, the Flush replication agent must be configured accordingly.
- Open IIS Manager and select the website that you are using as the Dispatcher cache.
- Using Features View mode, in the IIS section double click Authentication.
- If Anonymous Authentication is not enabled, select Anonymous Authentication and in the Actions area click Enable.
Integrating 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.
-
Open IIS Manager.
-
Select the website that you are using as the Dispatcher Cache.
-
Using Features View mode, in the IIS section double click Handler Mappings.
-
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
.
-
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.
-
(IIS 8.0) In the list of handler mappings, select the one that you just created, and in the Actions area click Edit.
-
(IIS 8.0) In the Edit Script Map dialog box, click the Request Restrictions button.
-
(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, and then click OK.
-
(IIS 8.0) On the Edit Script Map dialog box, click OK.
Configuring 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.
-
Right-click the root folder of the website that you are using as the Dispatcher cache and click Properties, such as
C:\inetpub\wwwroot
. -
On the Security tab, click Edit, and then on 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.
-
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.
-
Select the value of the Application Pool property and copy it to the clipboard.
-
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
-
Click the Check Names button. When Windows resolves the user account, click OK.
-
In the Permissions dialog box for the dispatcher folder, select the account that you just added, enable all of the permissions for the account except for Full Control and click OK. Click OK to close the folder Properties dialog box.
Registering 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 Dispatcher to allow JSON calls.
-
In IIS Manager, select your web site and using Features View, double-click Mime Types.
-
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
- File Name Extension:
Removing 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.
- In IIS Manager, select your web site and using Features View, double-click Request Filtering.
- Select the
bin
segment, click Remove, and in the confirmation dialog box click Yes.
Logging 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. You need to configure Dispatcher to use the log file, and provide IIS with write-access to the file.
-
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 isC:\inetpub\logs\dispatcher
. -
Right-click the dispatcher folder and click Properties.
-
On the Security tab, click Edit, and then on 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.
-
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.
-
Select the value of the Application Pool property and copy it to the clipboard.
-
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
-
Click the Check Names button. When Windows resolves the user account, click OK.
-
In the Permissions dialog box for the dispatcher folder, select the account that you just added, enable all of the permissions for the account except for Full Control, and click OK. Click OK to close the folder Properties dialog box.
-
Use a text editor to open the
disp_iis.ini
file. -
Add a line of text similar to the following example to configure the location of the log file and 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:
- Configure Dispatcher
- Confgure AEM to work with Dispatcher.
Apache Web Server apache-web-server
Installing Apache Web Server installing-apache-web-server
For Information about how to install an Apache Web Server read the installation manual - either online or in the distribution.
mod_so
module.Also see the Apache HTTP Server Security Tips and Security Reports.
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)
- Unix: a Dynamic Shared Object (DSO)
The installation archive files contains the following files - dependent on whether you have selected Windows or Unix:
Use the following steps to add Dispatcher to your Apache Web Server:
-
Place the Dispatcher file in the appropriate Apache module directory:
- Windows: Place
disp_apache<x.y>.dll
<APACHE_ROOT>/modules
- Unix: Locate either the
<APACHE_ROOT>/libexec
or<APACHE_ROOT>/modules
directory according to your installation.
Copydispatcher-apache<options>.so
into this directory.
To simplify long-term maintenance you can also create a symbolic link namedmod_dispatcher.so
to the Dispatcher:ln -s dispatcher-apache<x>-<os>-<rel-nr>.so mod_dispatcher.so
- Windows: Place
-
Copy the dispatcher.any file to the
<APACHE_ROOT>/conf
directory.Note: You can place this file in a different location, as long as the DispatcherLog property of the Dispatcher module is configured accordingly. (See Dispatcher-Specific Configuration Entries below.)
Apache Web Server - Configure SELinux Properties apache-web-server-configure-selinux-properties
If you are running Dispatcher on RedHat Linux Kernel 2.6 with SELinux enabled, you might run into error messages like this in the dispatcher logfile.
Mon Jun 30 00:03:59 2013] [E] [16561(139642697451488)] Unable to connect to backend rend01 (10.122.213.248:4502): Permission denied
This is likely due to an enabled SELinux security. Then you you need perform the following tasks:
- Configure the SELinux context of the dispatcher module file.
- Enable HTTPD scripts and modules to make network connections.
- Configure the SELinux context of the docroot, where the cached files are stored.
Enter the following commands in a terminal window, replacing [path to the dispatcher.so file]
with the path to the Dispatcher module that you installed to Apache Web Server, and path to the docroot
with the path where the docroot is located (e.g. /opt/cq/cache
):
semanage fcontext -a -t httpd_modules_t [path to the dispatcher.so file]
setsebool -P httpd_can_network_connect on
chcon -R --type httpd_sys_rw_content_t [path to the docroot]
semanage fcontext -a -t httpd_sys_rw_content_t "[path to the docroot](/.*)?"
Apache Web Server - Configure Apache Web Server for Dispatcher apache-web-server-configure-apache-web-server-for-dispatcher
The Apache Web Server needs to be configured, using httpd.conf
. In the Dispatcher installation kit you will find an example configuration file named httpd.conf.disp<x>
.
These steps are compulsory:
-
Navigate to
<APACHE_ROOT>/conf
. -
Open
httpd.conf
for editing. -
The following configuration entries must be added, in the order listed:
- LoadModule to load the module on start up.
- Dispatcher-specific configuration entries, including DispatcherConfig, DispatcherLog and DispatcherLogLevel.
- SetHandler to activate the Dispatcher. LoadModule.
- ModMimeUsePathInfo to configure behavior of mod_mime.
-
(Optional) It is recommended that you change the owner of the htdocs directory:
-
The apache server starts as root, though the child processes start as daemon (for security purposes). The DocumentRoot (
<APACHE_ROOT>/htdocs
) must belong to the user daemon:code language-xml cd <APACHE_ROOT> chown -R daemon:daemon htdocs
-
LoadModule
The following table lists examples that can be used; the exact entries are according to your specific Apache Web Server:
... LoadModule dispatcher_module modules\disp_apache.dll ...
... LoadModule dispatcher_module libexec/mod_dispatcher.so ...
Dispatcher specific configuration entries
The Dispatcher-specific configuration entries are placed after the LoadModule entry. The following table lists an example configuration that is applicable for both Unix and Windows:
Windows & Unix
...
<IfModule disp_apache2.c>
DispatcherConfig conf/dispatcher.any
DispatcherLog logs/dispatcher.log DispatcherLogLevel 3
DispatcherNoServerHeader 0 DispatcherDeclineRoot 0
DispatcherUseProcessedURL 0
DispatcherPassError 0
DispatcherKeepAliveTimeout 60
</IfModule>
...
The individual configuration parameters:
When this property is located in the main server configuration, all virtual hosts inherit the property value. However, virtual hosts can include a DispatcherConfig property to override the main server configuration.
0 - Errors
1 - Warnings
2 - Infos
3 - Debug
Note: It is recommended to set the log level to 3 during installation and testing, then to 0 when running in a production environment.
This parameter is deprecated and no longer has any effect.
Defines the Server Header to be used:
- undefined or 0 - the HTTP server header contains the AEM version.
- 1 - the Apache server header is used.
0 - accept requests to /
1 - requests to / are not handled by the dispatcher; use mod_alias for the correct mapping.
0 - use the original URL passed to the web server.
1 - the dispatcher uses the URL already processed by the handlers that precede the dispatcher (i.e.
mod_rewrite
) instead of the original URL passed to the web server. For example, either the original or the processed URL is matched with Dispatcher filters. The URL is also used as the basis for the cache file structure. See the Apache web site documentation for information about mod_rewrite; for example, Apache 2.4. When using mod_rewrite, it is advisable to use the flag 'passthrough0 - Dispatcher spools all error responses to the client.
1 - Dispatcher does not spool an error response to the client (where the status code is greater or equal than 400), but passes the status code to Apache, which e.g. allows an ErrorDocument directive to process such a status code.
Code Range - Specify a range of error codes for which the response is passed to Apache. Other error codes are passed to the client. For example, the following configuration passes responses for error 412 to the client, and all other errors are passed to Apache: DispatcherPassError 400-411,413-417
Note: The filter rules in the Dispatcher configuration will always be evaluated against the sanitised URL not the raw URL.
ServerTokens Full
DispatcherNoServerHeader 0
ServerTokens Prod
SetHandler
After these entries you must add a SetHandler statement to the context of your configuration ( <Directory>
, <Location>
) for the Dispatcher to handle the incoming requests. The following example configures the Dispatcher to handle requests for the complete website:
Windows and Unix
...
<Directory />
<IfModule disp_apache2.c>
SetHandler dispatcher-handler
</IfModule>
Options FollowSymLinks
AllowOverride None
</Directory>
...
The following example configures the Dispatcher to handle requests for a virtual domain:
Windows
...
<VirtualHost 123.45.67.89>
ServerName www.mycompany.com
DocumentRoot _\[cache-path\]_\\docs
<Directory _\[cache-path\]_\\docs>
<IfModule disp_apache2.c>
SetHandler dispatcher-handler
</IfModule>
AllowOverride None
</Directory>
</VirtualHost>
...
Unix
...
<VirtualHost 123.45.67.89>
ServerName www.mycompany.com
DocumentRoot /usr/apachecache/docs
<Directory /usr/apachecache/docs>
<IfModule disp_apache2.c>
SetHandler dispatcher-handler
</IfModule>
AllowOverride None
</Directory>
</VirtualHost>
...
ModMimeUsePathInfo
After the SetHandler statement you should also add the ModMimeUsePathInfo definition.
ModMimeUsePathInfo
parameter should only be used and configured if you are using Dispatcher version 4.0.9, or higher.The ModMimeUsePathInfo parameter should be set On
for all Apache configurations:
ModMimeUsePathInfo On
The mod_mime module (see for example, Apache Module mod_mime) is used to assign content metadata to the content selected for an HTTP response. The default setup means that when mod_mime determines the content type, only the part of the URL that maps to a file or directory will be considered.
When On
, the ModMimeUsePathInfo
parameter specifies that mod_mime
is to determine the content type based on the complete URL; this means that virtual resources will have metainformation applied based on their extension.
The following example activates ModMimeUsePathInfo:
Windows and Unix
...
<Directory />
<IfModule disp_apache2.c>
SetHandler dispatcher-handler
ModMimeUsePathInfo On
</IfModule>
Options FollowSymLinks
AllowOverride None
</Directory>
...
Enable Support for HTTPS (Unix and Linux) enable-support-for-https-unix-and-linux
Dispatcher uses OpenSSL to implement secure communication over HTTP. Starting from Dispatcher version 4.2.0, OpenSSL 1.0.0 and OpenSSL 1.0.1 are supported. Dispatcher uses OpenSSL 1.0.0 by default. To use OpenSSL 1.0.1, use the following procedure to create symbolic links so that Dispatcher uses the OpenSSL libraries that are installed.
-
Open a terminal and change the current directory to the directory where the OpenSSL libraries are installed, for example:
code language-shell cd /usr/lib64
-
To create the symbolic links, enter the following commands:
code language-shell ln -s libssl.so libssl.so.1.0.1 ln -s libcrypto.so libcrypto.so.1.0.1
Next Steps next-steps-1
Before you can start using the Dispatcher you must now:
- Configure Dispatcher
- Confgure AEM to work with Dispatcher.
Sun Java System Web Server / iPlanet sun-java-system-web-server-iplanet
Sun Java System Web Server / iPlanet - Installing your Web Server sun-java-system-web-server-iplanet-installing-your-web-server
For full information on how to install these web servers, please refer to their respective documentation:
- Sun Java System Web Server
- iPlanet Web Server
Sun Java System Web Server / iPlanet - Add the Dispatcher Module sun-java-system-web-server-iplanet-add-the-dispatcher-module
The Dispatcher comes as either:
- Windows: a Dynamic Link Library (DLL)
- Unix: a Dynamic Shared Object (DSO)
The installation archive files contains the following files - dependent on whether you have selected Windows or Unix:
disp_ns.dll
dispatcher.so
dispatcher.so
obj.conf.disp
dispatcher.any
Use the following steps to add the Dispatcher to your web server:
- Place the Dispatcher file in the web server’s
plugin
directory:
Sun Java System Web Server / iPlanet - Configure for the Dispatcher sun-java-system-web-server-iplanet-configure-for-the-dispatcher
The web server needs to be configured, using obj.conf
. In the Dispatcher installation kit you will find an example configuration file named obj.conf.disp
.
-
Navigate to
<WEBSERVER_ROOT>/config
. -
Open
obj.conf
for editing. -
Copy the line that starts:
Service fn="dispService"
fromobj.conf.disp
to the initialization section ofobj.conf
. -
Save the changes.
-
Open
magnus.conf
for editing. -
Copy the two lines that start:
Init funcs="dispService, dispInit"
andInit fn="dispInit"
fromobj.conf.disp
to the initialization section ofmagnus.conf
. -
Save the changes.
$(SERVER_ROOT)
and $(PRODUCT_SUBDIR)
must be replaced by the respective values.Init
The following table lists examples that can be used; the exact entries are according to your specific web server:
Windows and Unix
...
Init funcs="dispService,dispInit" fn="load-modules" shlib="$(SERVER\_ROOT)/plugins/dispatcher.so"
Init fn="dispInit" config="$(PRODUCT\_SUBDIR)/dispatcher.any" loglevel="1" logfile="$(PRODUCT\_SUBDIR)/logs/dispatcher.log"
keepalivetimeout="60"
...
where:
dispatcher.any.
0 Errors
1 Warnings
2 Infos
3 Debug
Note: It is recommended to set the log level to 3 during installation and testing and to 0 when running in a production environment.
Depending on your requirements you can define the Dispatcher as a service for your objects. To configure the Dispatcher for your entire website modify the default object:
Windows
...
NameTrans fn="document-root" root="$(PRODUCT\_SUBDIR)\\dispcache"
...
Service fn="dispService" method="(GET|HEAD|POST)" type="\*\\\*"
...
Unix
...
NameTrans fn="document-root" root="$(PRODUCT\_SUBDIR)/dispcache"
...
Service fn="dispService" method="(GET|HEAD|POST)" type="\*/\*"
...
Next Steps next-steps-2
Before you can start using the Dispatcher you must now:
- Configure Dispatcher
- Confgure AEM to work with Dispatcher.