Installing and Configuring Additional Tools/Modules

Dispatcher

The Dispatcher is Day's caching and/or load balancing tool. This section aims to help you:

  • Configure the Dispatcher for efficient operation.
  • Design your website to optimize operation of the Dispatcher when creating a high-performance website.
  • Fine-tune your Dispatcher settings should performance issues arise.

Using the Dispatcher also helps protect your application server from attack. Therefore, you can increase protection of your CQ instance by using the Dispatcher in conjunction with an industry-strength web server.

The process for deploying the Dispatcher is independent of the web server and OS platform chosen:

Why use the Dispatcher to implement Caching?

There are two basic approaches to web publishing:

  • Static Web Servers: such as Apache or IIS, are very simple, but fast.
  • Content Management Servers: which provide dynamic, real-time, intelligent content, but require much more computation time and other resources.

The Dispatcher helps realize an environment that is both fast and dynamic. It works as part of a static HTML server, such as Apache, with the aim of:

  • storing (or "caching") as much of the site content as is possible, in the form of a static website
  • accessing the layout engine as little as possible.

Which means that:

  • static content is handled with exactly the same speed and ease as on a static web server;additionally you can use the administration and security tools available for your static web server(s).
  • dynamic content is generated as needed, without slowing the system down any more than absolutely necessary.

The Dispatcher contains mechanisms to generate, and update, static HTML based on the content of the dynamic site. You can specify in detail which documents are stored as static files and which are always generated dynamically.

This section illustrates the principles behind this.

Static Web Server

file

A static web server, such as Apache or IIS, serves static HTML files to visitors of your website. Static pages are created once, so the same content will be delivered for each request.

This process is very simple, and thus extremely efficient. If a visitor requests a file (e.g. a HTML page), the file is usually taken directly from memory, at worst it is read from the local drive. Static web servers have been available for quite some time, so there is a wide range of tools for administration and security management, and they are very well integrated with network infrastructures.

Content Management Servers

file

If you use a Content Management Server, such as CQ, an advanced layout engine processes the request from a visitor. The engine reads content from a repository which, combined with styles, formats and access rights, transforms the content into a document that is tailored to the visitor's needs and rights.

This allows you to create richer, dynamic content, which increases the flexibility and functionality of your website. However, the layout engine requires more processing power than a static server, so this setup may be prone to slowdown if many visitors use the system.

How the Dispatcher performs Caching

file
The Cache Directory For caching, the Dispatcher module uses the web server's ability to serve static content. The Dispatcher places the cached documents in the document root of the web server.

Note

Due to this, the Dispatcher stores only the HTML code of the page - it does not store the HTTP headers. This can be an issue if you use different encodings within your website, as these may get lost.

Methods for Caching

The Dispatcher has two primary methods for updating the cache content when changes are made to the website.

  • Content Updates remove the pages that have changed, as well as files that are directly associated with them.
  • Auto-Invalidation automatically invalidates those parts of the cache that may be out of date after an update. i.e. it effectively flags relevant pages as being out of date, without deleting anything.

Content Updates 

In a content update, one or more CQ documents change. CQ sends a syndication request to the Dispatcher, which updates the cache accordingly:

  1. It deletes the modified file(s) from the cache.
  2. It deletes all files that start with the same handle from the cache. For example, if the file /en/index.html is updated, all the files that start with /en/index. are deleted. This mechanism allows you to design cache-efficient sites, especially in regard to picture navigations.
  3. It touches the so-called statfile; this updates the timestamp of the statfile to indicate the date of the last change.

The following points should be noted:

  • Content Updates are typically used in conjunction with an authoring system which "knows" what must be replaced.
  • Files that are affected by a content update are removed, but not replaced immediately. The next time such a file is requested, the Dispatcher fetches the new file from the CQ instance and places it in the cache, thereby overwriting the old content.
  • Typically, automatically generated pictures that incorporate text from a page are stored in picture files starting with the same handle - thus ensuring that the association exists for deletion. For example, you may store the title text of the page mypage.html as the picture mypage.titlePicture.gif in the same folder. This way the picture is automatically deleted from the cache each time the page is updated, so you can be sure that the picture always reflects the current version of the page.
  • You may have several statfiles, for example one per language folder. If a page is updated, CQ looks for the next parent folder containing a statfile, and touches that file.

Auto-invalidation

Auto-invalidation automatically invalidates parts of the cache - without physically deleting any files. At every content update, the so-called statfile is touched, so its timestamp reflects the last content update.

The Dispatcher has a list of files that are subject to auto-invalidation. When a document from that list is requested, the Dispatcher compares the date of the cached document with the timestamp of the statfile:

  • if the cached document is newer, the Dispatcher returns it.
  • if it is older, the Dispatcher retrieves the current version from the CQ instance.

Again, certain points should be noted:

  • Auto invalidation is typically used when the inter-relations are complex e.g. for HTML pages. These pages contain links and navigation entries, so they usually have to be updated after a content update. If you have automatically generated PDF or picture files, you may choose to auto-invalidate those too.
  • Auto-invalidation does not involve any action by the dispatcher at update time, except for touching the statfile. However, touching the statfile automatically renders the cache content obsolete, without physically removing it from the cache.

How the Dispatcher returns Documents

file

Finding out whether a document is subject to caching

You can define which documents the Dispatcher caches in the configuration file. The Dispatcher checks the request against the list of cacheable documents. If the document is not in this list, the Dispatcher requests the document from the CQ instance.

The Dispatcher always requests the document directly from the CQ instance in the following cases:

  • If the HTTP method is not GET. Other common methods are POST for form data and HEAD for the HTTP header.
  • If the request URI contains a question mark "?". This usually indicates a dynamic page, such as a search result, which does not need to be cached.
  • The file extension is missing. The web server needs the extension to determine the document type (the MIME-type).
  • The authentication header is set (this can be configured)

Finding out if a document is cached

The Dispatcher stores the cached files on the web server as if they were part of a static website. If a user requests a cacheable document the Dispatcher checks whether that document exists in the web server's file system:

  • if so, it returns this
  • if not, the Dispatcher requests the document from the CQ instance.

Finding out if a document is up-to-date

To find out if a document is up to date, the Dispatcher performs two steps:

  1. It checks whether the document is subject to auto-invalidation. If not, the document is considered up-to-date.
  2. If the document is configured for auto-invalidation, the Dispatcher checks whether it is older or newer than the last change available. If it is older, the Dispatcher requests the current version from the CQ instance and replaces the version in the cache.

Why implement Load Balancing?

Load Balancing is the practice of distributing the computational load of the website across several instances of CQ.

file

You gain:

  • increased processing power
    In practice this means that the Dispatcher shares document requests between several instances of CQ. Because each instance now has fewer documents to process, you have faster response times. The Dispatcher keeps internal statistics for each document category, so it can estimate the load and distribute the queries efficiently.
  • increased fail-safe coverage
    If the Dispatcher does not receive responses from an instance, it will automatically relay requests to one of the other instance(s). Thus, if an instance becomes unavailable, the only effect is a slowdown of the site, proportionate to the computational power lost. However, all services will continue.
  • you can also manage different websites on the same static web server.

Note

While load balancing spreads the load efficiently, caching helps to reduce the load. Therefore, try to optimize caching and reduce the overall load before you set up load balancing. Good caching may increase the load balancer's performance, or render load balancing unnecessary.

Caution

While a single Dispatcher will usually be able to saturate the capacity of the available Publish instances, for some rare applications it can make sense to additionally balance the load between two Dispatcher instances. Configurations with multiple Dispatchers need to be considered carefully, since an additional Dispatcher will increase the load on the available Publish instances and can easily cause an actual overall performance decrease in most applications.

How the Dispatcher performs Load Balancing

Performance Statistics

The Dispatcher keeps internal statistics about how fast each instance of CQ processes documents. Based on this data, the Dispatcher estimates which instance will provide the quickest response time when answering a request, and so it reserves the necessary computation time on that instance.

Different types of requests may have differing average completion times, so the Dispatcher allows you to specify document categories. These are then considered when computing the time estimates. For example, you can make a distinction between HTML pages and images, as the typical response times may well differ.

If you use an elaborate search function, you may create a new category for search queries. This helps the Dispatcher send search queries to the instance that responds fastest. This prevents a slower instance from stalling when it receives several "expensive" search queries, while the others get the "cheaper" requests.

Personalized content (Sticky Connections)

Sticky connections ensure that documents for one user are all composed on the same instance of CQ. This is important if you use personalized pages and session data. The data is stored on the instance, so subsequent requests from the same user must return to that instance or the data is lost.

Because sticky connections restrict the Dispatcher's ability to optimize the requests, you should use them only when needed. You can specify the folder that contains the "sticky" documents, thus ensuring all documents in that folder are composed on the same instance for each user.

Note

For most pages that use sticky connections you have to switch off caching - otherwise the page looks the same to all users, regardless of the session content.

For a few applications, it can be possible to use both sticky connections and caching; for example, if you display a form that writes data to the session.

Installation

Each Dispatcher installation kit comes as an archive file that can be downloaded from Daycare.

The following naming convention is used:

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

For example, the dispatcher-apache2.2-linux-i686-4.0.6.tgz installation kit contains the dispatcher release 4.0.6 for an Apache 2.2 web server that runs under Linux i686 and is packaged using the tar format.

The naming according to web server is as follows:

 Web Server  Installation Kit
 Apache 2.2  dispatcher-apache2.2-<other parameters>
 Apache 2  dispatcher-apache2-<other parameters>
 Apache 1.3  dispatcher-apache-<other parameters>
 Apache 1.3 EAPI  dispatcher-apache-eapi-<other parameters>
 Microsoft Internet
 Information Server 5, 6, 7
 dispatcher-iis-<other parameters>
 Sun Java Web Server / iPlanet
 dispatcher-ns-<other parameters>

Note

Within the source tree of Apache 1.3 the compiler flag EAPI exists. A dispatcher module built for Apache with EAPI should not be used inside a plain apache server nor vice versa.

In order to determine which version of the dispatcher you should install:

Open a shell, chdir to your apache installation directory and enter:

    # ./httpd -V

This will output information such as:

    Server version: Apache/1.3.27 (Unix)
    Server built: Feb 18 2003 17:46:31
    Server's Module Magic Number: 19990320:13
    Server compiled with.... -D EAPI -D HAVE_MMAP ...

When the flag EAPI is shown, such an installation would need an apache-eapi installation kit.

Historically, Apache with EAPI is often found in binary distributions bundled with an operating system, whereas an apache built from source is a plain one.

Each archive contains the following files:

  • the Dispatcher modules
  • an example configuration file
  • the readme file with installation instructions and last-minute information; the readme file is named as README.dispatcher.<web-server-name> e.g. README.dispatcher.apache
  • release notes

Note

Please check the readme file for any last-minute changes / platform specific notes before starting the installation.

The following sections detail the web server specific installation procedures.

Microsoft Internet Information Server

Microsoft IIS - Installing IIS

For information on how to install this web server, see:

IIS 7 / 7.5

After installation:

  1. Open the Server Manager and add the role Web Server (IIS).
  2. Ensure the following Role Services are installed:
    • ISAPI Extensions
    • ISAPI Filters
    • IIS 6 Metabase Compatibility

Microsoft IIS - Installing the Dispatcher module

See Installation for information on accessing the installation files. The required archive for Microsoft Internet Information System is:

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

which 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.
 disp_iis.pdb Program database holding program symbols. Can be used for debugging purposes.
 dispatcher.any An example configuration file for the Dispatcher.
 README.dispatcher.iis The readme file holding installation instructions and last-minute information.
Note: Please check this file before starting the installation.
 release-notes.txt
The release notes; listing issues fixed in the current and past releases.

IIS 5 / 6

  1. Extract
    • disp_iis.dll
    • disp_iis.ini
    • dispatcher.any
    • disp_iis.pdb
    from the Dispatch package into the executable directory of the selected website under IIS; 
    i.e. <IIS_INSTALLDIR>\scripts. For example, in a standard IIS installation on a non-server product, the installation directory is C:\Inetpub, with the scripts virtual directory located in C:\Inetpub\Scripts.

IIS 7 / 7.5

To add the Dispatcher to the list of available ISAPI filters use the following steps:

  1. Using the Windows Explorer, create a directory <IIS_INSTALLDIR>/Scripts;
    for example, C:\Inetpub\Scripts.
  2. Extract all files from the scripts directory of the Dispatcher package into this directory:
    • disp_iis.dll
    • disp_iis.ini
    • dispatcher.any
    • disp_iis.pdb

Microsoft IIS - Configure the Dispatcher INI File

  1. Configure disp_iis.ini as required. The basic format of the .ini file is as follows:
[main]
scriptpath=/<virtual root>/disp_iis.dll
configpath=<path to dispatcher.any>
loglevel=1
servervariables=1
where :
Parameter Description
scriptpath This is the URL path of disp_iis.dll within the web server's virtual namespace i.e. /scripts/disp_iis.dll.
configpath The location of dispatcher.any within the local file system (absolute path).
logfile The location of the dispatcher.log file.  If this is not set then log messages will 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:
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 revert to 0 when running in a production environment.
servervariables Defines how server variables are processed.
0: IIS server variables are sent to neither the Dispatcher nor CQ.
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 CQ 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]
scriptpath=/Scripts/disp_iis.dll
configpath=C:\Inetpub\Scripts\dispatcher.any
loglevel=1

Microsoft IIS - Configure IIS

IIS 5 / 6

To add the Dispatcher to the list of available ISAPI filters use the following steps:

  1. Inside the Internet Service Manager, right click the root node of the website under which you want to add the dispatcher, then open its Properties dialog.
  2. Select the tab named ISAPI Filters.
  3. Click Add.. and specify:
    • Filter Name, a name for the filter (i.e. for the Dispatcher).
    • Executable, the location of the filter (i.e. where the dll resides).
  4. Click OK to save.

Access to the cached files must be unrestricted (Anonymous Access). Otherwise the syndication request for cache flushing will be unsuccessful due to missing authentication information.

To ensure access you have to:

  1. Inside the Internet Service Manager, right click the root node of the appropriate website, then open its Properties dialog.
  2. Select the Directory Security tab.
  3. Activate Anonymous access.
  4. To activate the changes you have to restart IIS. Either from the IIS control window or from a command window:
    • net stop w3svc  - will stop the IIS web publishing service
    • net start w3svc - will start it again

IIS 7 / 7.5

To add the Dispatcher to the list of available ISAPI filters perform the following tasks.

Configure the Virtual Directory:

  1. Open Administrative Tools, then select Internet Information Services (IIS) Manager.
  2. Select your site in the tree, then using the context menu (usually right mouse click) select Add Virtual Directory....
  3. Enter the alias Scripts and the physical path of the directory created above (C:\Inetpub\Scripts).

Register the ISAPI filter:

  1. Open Administrative Tools, then select Internet Information Services (IIS) Manager.
  2. Select your site in the tree, then the tab Features View (at the bottom).
  3. Open the feature ISAPI Filters in the view.
  4. Click Add... and enter the following settings:
    • Filter Name: CQ
    • Executable: the path to disp_iis.dll (C:\Inetpub\Scripts)
  5. Click OK to save.

Register the ISAPI handler:

  1. Open Administrative Tools, then select Internet Information Services (IIS) Manager.
  2. Select your site in the tree, then the tab Features View (at the bottom).
  3. Open the feature Handler Mappings in the view.
  4. Click Add Script Map... and enter the following settings:
    • Request Path: /Scripts/disp_iis.dll
    • Executable: the path to disp_iis.dll (C:\Inetpub\Scripts)
    • Name: CQ
  5. Click OK to save.
  6. Open the feature Configuration Editor.
  7. Select the section system.webServer\handlers from Application.config.
  8. Select the first Collection (at the top), then click on ... (at the far right).
  9. The Collection Editor will appear, select the handler CQ (at the top).
  10. Change the value of the allowPathInfo flag (at the bottom) to true.
  11. Close the Collection Editor and click Apply.

Register the .json extension:

  1. Open Administrative Tools, then select Internet Information Services (IIS) Manager.
  2. Select your site in the tree, then the tab Features View (at the bottom).
  3. Open the feature MIME Types in the view.
  4. Click Add... and enter the following settings:
    • File name extension: .json
    • MIME type: application/json
  5. Click OK to save.

IIS 7.5

If your site is not completely new it might contain the hidden segment bin. To remove this:

  1. Open Administrative Tools, then select Internet Information Services (IIS) Manager.
  2. Select your site in the tree, then the tab Features View (at the bottom).
  3. Open the feature Request filtering in the view.
  4. Select the tab Hidden Segments.
  5. Remove the entry bin (if existing).

If you would like the dispatcher to write a log file instead of writing to the event log then do the following:

  1. First, configure a logging location in disp_iis.ini. Open the disp_iis.ini file for editing, this file is most likely stored under C:\inetpub\scripts\disp_iis.ini.
  2. Add the following value:
    logfile=C:\inetpub\logs\dispatcher\dispatcher.log
  3. Using Windows Explorer, go to C:\inetpub\logs directory.
  4. Create a directory named dispatcher
  5. Right click the dispatcher directory and select Properties in the contextual dialog
  6. Select the Security tab
  7. Click Edit
  8. Click Add
  9. Open Administrative Tools, then select Internet Information Services (IIS) Manager.
  10. In the IIS Manager, browse down the tree and select the IIS site where you have configured the dispatcher. On the right side of the window, click Advanced Settings.
  11. Highlight and copy the value under Application Pool (copy by pressing [Ctrl]+c).
  12. Go back to the security Add dialog.
  13. In the editable box, enter IIS AppPool\ then paste the value from step 10. You should have entered something like this IIS AppPool\DefaultAppPool.
  14. Click Check Names (this should cause the user id to be underlined).
  15. Click OK.
  16. For the newly added user, enable all access rights except Full Control.
  17. Click OK.

Next Steps

Before you can start using the Dispatcher you must now:

Apache Web Server

Caution

Instructions for installation under both Windows and Unix are covered here.

Please be careful when selecting which to execute.

Note

Running the following configuration can lead to segmentation faults and httpd problems:

Dispatcher version: 4.0.0-3 on AIX
httpd: IBM IHS 6.0.2.15 on AIX

Apache Web Server - Installing your Apache Web Server

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

Caution

If you are creating an Apache binary by compiling the source files yourself, make sure that you turn on dynamic modules support. This can be done by using any of the --enable-shared options. As minimum include the mod_so module.

More information can be found in the Apache Web Server installation manual.

Apache Web Server - Add the Dispatcher Module

The Dispatcher comes as either:

  • Windows: a Dynamic Link Library (DLL)
  • Unix: a Dynamic Shared Object (DSO)

See Installation for information on accessing the installation archive files, in particular the specific file to select for your environment.

The installation archive files contains the following files - dependent on whether you have selected Windows or Unix:

File Description
disp_apache<x.y>.dll Windows:
The Dispatcher dynamic link library file.
dispatcher-apache<x.y>-<rel-nr>.so Unix:
The Dispatcher shared object library file.
mod_dispatcher.so Unix:
An example link.
http.conf.disp<x> An example configuration file for the Apache server.
dispatcher.any An example configuration file for the Dispatcher.
README.dispatcher.apache Readme file holding installation instructions and last-minute information.
Note: Please check this file before starting the installation.
release-notes.txt
The release notes; listing issues fixed in the current and past releases.

Use the following steps to add the Dispatcher to your Apache Web Server:

  1. Place the Dispatcher file in the appropriate Apache module directory:
    • Windows:
      Place disp_apache<x.y>.dll in <APACHE_ROOT>/modules
    • Unix:
      Locate either the <APACHE_ROOT>/libexec or <APACHE_ROOT>/modules directory according to your installation.
      Copy dispatcher-apache<options>.so into this directory.
      To simplify long-term maintenance you can also create a symbolic link named mod_dispatcher.so to the Dispatcher:
          ln -s dispatcher-apache<x>-<os>-<rel-nr>.so mod_dispatcher.so

Apache Web Server - Configure your Apache Web Server for the Dispatcher

Note

The ModMimeUsePathInfo parameter has been added as of version 4.0.9. So it should only be used and configured if you are using this version, or higher.

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:

  1. Navigate to <APACHE_ROOT>/conf.
  2. Open httpd.conf for editing.
  3. The following configuration entries must be added, in the order listed:
    • LoadModule to load the module on start up.
    • AddModule to enable the module. (Apache 1.3 only).
    • Dispatcher-specific configuration entries, including DispatcherConfig,DispatcherLog and DispatcherLogLevel.
    • SetHandler to activate the Dispatcher. LoadModule.
    • ModMimeUsePathInfo to configure behavior of mod_mime.

The following configuration steps are optional, but recommended:

  1. 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:
          cd <APACHE_ROOT>
          chown -R daemon:daemon htdocs
  2. For Apache 1.3 only:
    Remove the Multiviews option for directories handled by the dispatcher.
    • When a file is requested and its parent directory does not yet exist, the negotation module returns a 403 (FORBIDDEN) response before the dispatcher has the opportunity to create the file and its parent directories. Therefore, you should disable the MultiViews option inside directories that are handled by the dispatcher.
      To do this, remove the following lines in httpd.conf:
          Options Indexes FollowSymLinks
          Options Indexes MultiViews

LoadModule

The following table lists examples that can be used; the exact entries are according to your specific Apache Web Server:

 Windows ...
LoadModule dispatcher_module modules\disp_apache.dll
...
 Unix
 (assuming  symbolic link)
...
LoadModule dispatcher_module libexec/mod_dispatcher.so
...

Note

The first parameter of each statement must be written exactly as in the above examples.

See the example configuration files provided and the Apache Web Server documentation for full details about this command.

AddModule (Apache 1.3 only)

A list of AddModule statements enable modules within the Apache Web Server.

The order of AddModule statements in the configuration file is important if there are interdependencies between the modules. It is recommended to position the AddModule statement for the Dispatcher as the last entry; for example:

AddModule disp_apache.c

Note

The first parameter of each statement must be written exactly as in the above examples.

See the example configuration files provided and the Apache Web Server documentation for full details about this command.

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
and
Unix
 ...
<IfModule disp_apache2.c>
  DispatcherConfig conf/dispatcher.any
  DispatcherLog    logs/dispatcher.log
  DispatcherLogLevel 3
  DispatcherNoServerHeader 0
  DispatcherDeclineRoot 0
  DispatcherUseProcessedURL 0
  DispatcherPassError 0
</IfModule>
...

The individual configuration parameters:

DispatcherConfig Location and name of the configuration file.
DispatcherLog Location and name of the log file.
DispatcherLogLevel Log level for the log file:
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.
DispatcherNoServerHeader Defines the Server Header to be used:
undefined or 0 - the HTTP server header contains the CQ version.
1 - the Apache server header is used.
DispatcherDeclineRoot Defines whether to decline requests to the root "/":
0 - accept requests to /
1 - requests to / are not handled by the dispatcher; use mod_alias for the correct mapping.
DispatcherUseProcessedURL Defines whether to use pre-processed URLs:
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.
See the Apache web site documentation for information about mod_rewrite; for example, Apache 2.2. When using mod_rewrite, it is advisable to use the flag 'passthrough|PT' (pass through to next handler) to force the rewrite engine to set the uri field of the internal request_rec structure to the value of the filename field.
DispatcherPassError
Defines how to support 40x error codes for ErrorDocument handling:
0 - the dispatcher spools all error responses to the client.
1 - the 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.

Note

Path entries are relative to the root directory of the Apache Web Server.

Note

The default settings for the Server Header are:
    ServerTokens               Full

    DispatcherNoServerHeader   0

Which shows the CQ version (for statistical purposes). If you want to disable such information being available in the header you can set:
    ServerTokens               Prod

See the Apache Documentation about ServerTokens Directive (for example, for Apache 2.2) for more information.

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>
...

Note

The parameter of the SetHandler statement must be written exactly as in the above examples, as this is the name of the handler defined in the module.

See the example configuration files provided and the Apache Web Server documentation for full details about this command.

ModMimeUsePathInfo

After the SetHandler statement you should also add the ModMimeUsePathInfo definition.

Note

The ModMimeUsePathInfo parameter has been added in the Dispatcher v 4.0.9. It should only be used for this version, or higher.

The ModMimeUsePathInfo parameter should be set On for all Apache configurations:

    ModMimeUsePathIfo 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>
...

 

Before you can start using the Dispatcher you must:

Sun Java System Web Server / iPlanet

Note

Instructions for both Windows and Unix environments are covered here.

Please be careful when selecting which to execute.

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

The Dispatcher comes as either:

  • Windows: a Dynamic Link Library (DLL)
  • Unix: a Dynamic Shared Object (DSO)

See Installation for information on accessing the installation files; in particular the specific file to select for your environment.

The installation archive files contains the following files - dependent on whether you have selected Windows or Unix:

File Description
disp_ns.dll Windows:
The Dispatcher dynamic link library file.
dispatcher.so Unix:
The Dispatcher shared object library file.
dispatcher.so Unix:
An example link.
obj.conf.disp  An example configuration file for the iPlanet / Sun Java System web server.
dispatcher.any  An example configuration file for the Dispatcher.
README.dispatcher.ns  Readme file holding installation instructions and last-minute information.
Note: Please check this file before starting the installation.
 release-notes.txt The release notes; listing issues fixed in the current and past releases.

Use the following steps to add the Dispatcher to your web server:

  1. Place the Dispatcher file in the web server's plugin directory:
    • Windows:
      Place disp-ns.dll in the directory <WEBSERVER_ROOT>/plugins.
    • Unix:
      Place dispatcher.so in the directory <WEBSERVER_ROOT>/plugins.

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.

  1. Navigate to <WEBSERVER_ROOT>/config.
  2. Open obj.conf for editing.
  3. Copy the line that starts:
        Service fn="dispService"
    from obj.conf.disp to the initialization section of obj.conf.
  4. Save the changes.
  5. Open magnus.conf for editing.
  6. Copy the two lines that start:
      Init funcs="dispService, dispInit"
      and
      Init fn="dispInit"
    from obj.conf.disp to the initialization section of magnus.conf.
  7. Save the changes.

Note

The following configurations should all be on one line and the $(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"
...
where:
Parameter Description
config Location and name of the configuration file dispatcher.any.
logfile  Location and name of the log file.
loglevel  Log level for when writing messages to the log file:
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="*/*"
...

Before you can start using the Dispatcher you must:

Configuring the Dispatcher

The following sections describe how to configure various aspects of the Dispatcher.

Including Configuration File(s)

By default the Dispatcher configuration is stored in dispatcher.any, though you can change the name and location of this file during installation.

You can also include files:

  • If your configuration file is large you can split it into several smaller files (that are easier to manage) then include these. 
  • To include files that are generated automatically.

For example, to include the file myFarm.any in the /farms configuration use the following code:

/farms
  {
  $include "myFarm.any"
  }

You can also use the asterisk ("*") as a wildcard to specify a range of files to include.

For example, if the files farm_1.any through to farm_5.any contain the configuration of farms one to five, you can include them as follows:

/farms
  {
  $include "farm_*.any"
  }

Configuration Parameters

One dispatcher can be used with multiple websites; for example:

  • intranet.myCompany.com
  • internet.myCompany.com
  • www.myFlagshipProduct.com

To configure your Dispatcher you:

  • assign a unique /name
  • configure the caching and rending parameters for each /farm
  • configure logging

An example configuration is structured as follows:

# name of the dispatcher
/name "internet-server"

# each farm configures a set off (loadbalanced) renders
/farms
  {
  # first farm entry (label is not important, just for your convenience)
  /website 
    {  
    /clientheaders
      {
      # List of headers that are passed on
      }
    /virtualhosts
      {
      # List of URLs for this Web site
      }
    /sessionmanagement 
      {
      # settings for user authentification
      }
    /renders
      {
      # List of CQ instances that render the documents
      }
    /filter
      {
      # List of filters
      }
    /cache
      {
      # Cache configuration
      /rules
        {
        # List of cachable documents
        }
      /invalidate
        {
        # List of auto-invalidated documents
        }
      }
    /statistics
      {
      /categories
        {
        # The document categories that are used for load balancing estimates
        }
      }
    /stickyConnectionsFor "/myFolder"
    /health_check
      {
      # Page gets contacted when an instance returns a 500
      }
    /retryDelay "1"
    /unavailablePenalty "1"
    }
  }

/name

With the /name parameter you assign a unique name (of your choice) to your Dispatcher instance.

/farms (Farms or Website Global Settings)

The /farms section defines a list of farms or websites; they can have any alphanumeric (a-z, 0-9) name.

Each /farms section defines:

  • A set of load-balanced renderers.
  • The IP addresses and ports of the publish instances to serve and cache content from.
  • Further characteristics including where to cache files, what to cache.

For each farm you can specify separate caching and rendering parameters, some of which have sub-parameters:

Purpose Parameter Sub-parameters
Default homepage
(optional)
/homepage
 
Client Headers /clientheaders
 
Virtual Host /virtualhosts  
Session Management and Authentication /sessionmanagement
/directory (mandatory)
/encode (optional)
/header (optional)
/timeout (optional)
Rendering Allocation /renders  
Filters /filter  
Forward Syndication Requests /propagateSyndPost
 
Cache /cache
/docroot
/statfile
/statfileslevel
/allowAuthorized
Cacheable Documents
/cache
/rules
 
Autoinvalidated Files
/cache
/invalidate  
Flush Requests
/cache
(only allowed from authorized clients)
/allowedClients
 
Internal Response Statistics /statistics
 
Sticky Connection Folder /stickyConnectionsFor  
Health Check /health_check  
Retry Delay /retryDelay  
Unavailable Penalty /unavailablePenalty  

The following example shows the skeleton definition for two farms named /daycom and /docsdaycom:

#name of dispatcher
/name "day sites"

#farms section defines a list of farms or sites
/farms
{
/daycom
{
...
}
/docdaycom
{
...
}
}

If you use more than one render farm, the list is evaluated bottom-up. This is particularly relevant when defining Virtual Hosts for your websites.

/homepage (IIS only; optional)

Caution

This parameter is IIS only and will not have any effect in the other web servers.

For example, when using Apache use mod_rewrite. See the Apache web site documentation for information about mod_rewrite; for example, Apache 2.2. When using mod_rewrite, it is advisable to use the flag 'passthrough|PT' (pass through to next handler) to force the rewrite engine to set the uri field of the internal request_rec structure to the value of the filename field.

This specifies the page that the Dispatcher returns when no specific target page or file is requested.

Typically this is the page returned when a user specifies an URL such as www.myCompany.com. The /homepage parameter is required if there is no automatic redirection from the server (for example IIS) nor from CQ (for example, if you shut CQ down after the content is cached). To display the index.html page in such circumstances, use the following setting:

/homepage "/index.html"

This is defined within the /farms section, for example:

#name of dispatcher
/name "day sites"

#farms section defines a list of farms or sites
/farms
{
/daycom
{
/homepage "/index.html"
...
}
/docdaycom
{
...
}
}

/clientheaders (Client Headers)

This defines a list of all HTTP headers passed from the client to the CQ instance.

By default the Dispatcher forwards the standard HTTP headers to the CQ instance. In some instances, you might want to:

  • add headers: for example, custom headers
  • remove headers: for example, authentication headers which are only relevant to the web server

If you need to customize the set of headers you have to specify the entire set of headers to be forwarded; including any of those forwarded by default. Such a list might look as follows:

/clientheaders
  {
  "referer"
  "user-agent"
  "authorization"
  "from"
  "content-type"
  "content-length"
  "accept-charset"
  "accept-encoding"
  "accept-language"
  "accept"
  "host"
  "if-match"
  "if-none-match"
  "if-range"
  "if-unmodified-since"
  "max-forwards"
  "proxy-authorization"
  "proxy-connection"
  "range"
  "cookie"
  "cq-action"
  "cq-handle"
  "handle"
  "action"
  "cqstats"
  }

/virtualhosts (Virtual Hosts)

The virtual hosts section is a list of all hostname/URI combinations that the Dispatcher accepts for this website. You can also use the asterisk ("*") character as a wildcard. For example, the section:

   /virtualhosts
    {
    "www.myCompany.com"
    "www.myCompany.ch"
    "www.mySubDivison.*"
    }

handles the requests for:

  • myCompany - both the .com and the .ch domains
  • mySubDivision - all domains

To configure the Dispatcher to handle all requests:

   /virtualhosts
    {
    "*"
    }

If you use more than one render farm, the list is evaluated bottom-up.  In the following example (which shows only the relevant sections):

  • all the pages in the /products folder are sent to server 2
  • all other pages to server 1
/farms
  {
  /myProducts 
    { 
    /virtualhosts
      {
      "www.mycompany.com"
      }
    /renders
      {
      /hostname "server1.myCompany.com"
      /port "80"
      }
    }
  /myCompany 
    { 
    /virtualhosts
      {
      "www.mycompany.com/products/*"
      }
    /renders
      {
      /hostname "server2.myCompany.com"
      /port "80"
      }
    }
  }

/sessionmanagement (Session Management and Authentification)

Caution

/allowAuthorized must be set to "0" in the /cache section in order to enable this feature.

This feature allows you to create a secure session for access to the render farm so that users:

  • need to log in before they can access any page in the farm
  • have access to all pages in the farm after logging in

/sessionmanagement is defined within /farms.

Caution

If your website has section with different access requirements you will need to specify multiple farms.

/sessionmanagement has several sub-parameters:

/directory (mandatory)

The directory that stores the session information. If the directory does not exist, it is created.

/encode (optional)

How the session information is encoded. Use "md5" for encryption using the md5 algorithm, or "hex" for hexadecimal encoding. If you encrypt the session data, a user with access to the file system cannot read the session contents. The default is "md5".

/header (optional)

The name of the HTTP header or cookie that stores the authorization information. If you store the information in the http header, use HTTP:<header-name>. To store the information in a cookie, use Cookie:<header-name>. If you do not specify a value HTTP:authorization is used.

/timeout (optional)

The number of seconds until the session times out after it has been used last. If not specified "800" is used, so the session times out a little over 13 minutes after the last request of the user.

An example configuration looks as follows:

/sessionmanagement 
  { 
  /directory "/usr/local/apache/.sessions" 
  /encode "md5" 
  /header "HTTP:authorization" 
  /timeout "800" 
  }

/renders (Rendering Allocations)

This section defines where the Dispatcher will allocate requests to render a document.

If you use a single CQ instance for rendering, you can specify it as in the following example:

/renders
  {
    /myRenderer
      {
      # hostname or IP of the renderer
      /hostname "cq.myCompany.com"
      # port of the renderer
      /port "80"
      # connection timeout in milliseconds, "0" (default) waits indefinitely
      /timeout "0"
      }
  }

If the CQ instance runs on the same computer as the Dispatcher, you can specify it as in the following example:

/renders
  {
    /myRenderer
     {
     /hostname "127.0.0.1"
     /port "3402"
     }
  }

To distribute the workload equally among multiple CQ instances use:

/renders
  {
    /myFirstRenderer
      {
      /hostname "cq.myCompany.com"
      /port "80"
      }
    /mySecondRenderer
      {
      /hostname "127.0.0.1"
      /port "3402"
      }
  }

/filter (Filters)

Using filters, you can specify which requests are accepted by the Dispatcher module. All other requests are sent back to the server, where they are offered to the other modules that run on the web server. 

Caution

Please see the Security Checklist for further considerations when restricting access by using the Dispatcher.

If you want the Dispatcher to handle all files, use:

/filter
  {
  /0001
    {
    /glob "*"
    /type "allow"
    }
  }

Filters also allow you to exclude (deny) access to various elements; for example:

  • ASP pages
  • sensitive areas within a publish instance

Requests to an explicitly denied area result in a 404 error code (page not found) being returned.

The following filter denies access to ASP pages:

/filter
  {
  /0001
    {
    /glob "*"
    /type "allow"
    }
  /0002
    {
    /glob "*.asp *"
    /type "deny"
    }
  }

A match is needed for the entire request line, not just the URI. Therefore the above defines the match as "*.asp *", because the full request line is GET /home.asp HTTP/1.0.

You can also match other parts of the request. The following filter denies access to form data submitted by the POST method:

/filter
  {
  /0001
    {
    /glob "*"
    /type "allow"
    }
  /0002
    {
    /glob "POST *"
    /type "deny"
    }
  }

The following example shows a filter used to deny external access to the Workflow console:

...
/filter
  {
  /0001
    {
    /glob "*"
    /type "allow"
    }
  /0002
    {
    # deny access to CQ Workflow console
    /glob "* /libs/cq/workflow/content/console*"
    /type "deny"
    }
  }
...

If your publish instance uses a web application context (for example publish) this can also be added to your filter definition.

...
/filter
  {
  /0001
    {
    /glob "*"
    /type "allow"
    }
 /0003
    {
    # deny access to CQ Workflow console
    /glob "* /publish/libs/cq/workflow/content/console/archive*"
    /type "deny"
    }
  }
...

If you still need to access single pages within the restricted area, you can allow access to them. For example, to allow access to the Archive tab within the Workflow console add the following section after the previous example:

...
/0004
{
/glob "* /libs/cq/workflow/content/console/archive*"
/type "allow"
}
...

/propagateSyndPost (Forward Syndication Requests)

Syndication requests are usually intended for the Dispatcher only, so by default they are not sent to the CQ instance.

If necessary, you can forward syndication requests to the Dispatcher. This is done by setting this parameter to "1". If set, you must make sure that POST requests are not denied in the filter section.

/cache (Cache)

The /cache section specifies some general aspects of how and where the Dispatcher caches documents.

Various sub-parameters can be defined:

/docroot

This link points to the document root of the web server. This is where the Dispatcher stores the cached documents, and this is where the web server looks for them. If you use multiple render farms, you have to define a different document root on the web server for each farm, and specify the corresponding link here.

/statfile

This link points to the statfile, which the Dispatcher uses to keep track of the last content update. This can be any file on the web server. The file itself is empty, only the timestamp is used.

/statfileslevel

Creates statfiles in all folders down to the level you specify. Use this if you only want to invalidate sections of the cache, not the entire cache. For a default structure with language folders (for example, the English site under /content/myWebsite/en), use /statfileslevel = "2" to invalidate per language. This means that when the Dispatcher invalidates the English part of the website, other sections are not affected (for example, the German and French sections). If you use this parameter, do not specify the /statfile parameter.

/allowAuthorized

By default, requests that carry an authentication header are not cached. This is because authentication is not checked when a document is returned from the cache - so the document would be displayed for a user who does not have the necessary rights. However, in some setups it can be permissible to cache authenticated documents.

Note

/allowAuthorized must be set to "0" in order to enable the /sessionmanagement feature.

An example cache section might look as follows:

/cache
  {
  /docroot "/opt/dispatcher/cache"
  /statfile  "/tmp/dispatcher-website.stat"          
  /allowAuthorized "0"
      
  /rules
    {
    # List of files that are cached
    }

  /invalidate
    {
    # List of files that are auto-invalidated
    }
  }

/rules (within /cache) (Cacheable Documents)

The list of cachable documents determines which documents are cached, though the Dispatcher never caches a document in the following circumstances:

  • If the HTTP method is not GET.
    Other common methods are POST for form data and HEAD for the HTTP header.
  • If the request URI contains a question mark ("?").
    This usually indicates a dynamic page, such as a search result that does not need to be cached.
  • The file extension is missing.
    The web server needs the extension to determine the document type (the MIME-type).
  • The authentication header is set (this can be configured)

If you do not have dynamic pages (beyond those already excluded by the above rules), you can let the Dispatcher cache everything. The rules section for this looks as follows:

/rules
  {
  /0000
    {
    /glob "*"
    /type "allow"
    }
  }

If there are some sections of your page that are dynamic (for example a news application) or within a closed user group, you can define exceptions:

Note

Closed user groups must not be cached as user rights are not checked for cached pages.

/rules
  {
  /0000
    {
    /glob "*"
    /type "allow"
    }
  /0001
    {
    /glob "/en/news/*"
    /type "deny"
    }
  /0002
    {   
    /glob "*/private/*"
    /type "deny"
    }   

Compression (Apache 1.3 only)

On Apache 1.3 web servers you can also compress the cached documents. This allows Apache to return the document in a compressed form if so requested by the client.

Note

Currently only the gzip format is supported.

Only applicable for Apache 1.3.

The following rule caches all documents in compressed form; Apache can return either the uncompressed or the compressed form to the client:

/rules
  {
  /rulelabel
    {
    /glob "*"
    /type "allow"
    /compress "gzip"
    }
  }

/invalidate (within /cache) (Autoinvalidated Files)

This defines a list of all documents that are automatically rendered invalid after a content update.

With auto-invalidation the Dispatcher does not physically delete the pages after a content update, but checks them for validity when they are next requested. Documents in the cache that are not auto-invalidated will remain in the cache until they are deleted by a content update.

Auto-invalidate is typically used for HTML pages. As these often contain navigation elements and links to other pages, it is very hard to determine whether a page is affected by a content update. To stay on the safe side, you usually auto-invalidate all HTML pages. An example configuration for this looks as follows:

  /invalidate
  {
  /0000
    {
    /glob "*"
    /type "deny"
    }
  /0001
    {
    /glob "*.html"
    /type "allow"
    }
  }

If you offer automatically generated PDF and ZIP files for download, you might have to auto-invalidate these as well. A configuration example this looks as follows:

/invalidate
  {
  /0000
    {
    /glob "*"
    /type "deny"
    }
  /0001
    {
    /glob "*.html"
    /type "allow"
    }
  /0002
    {
    /glob "*.zip"
    /type "allow"
    }
  /0003
    {
    /glob "*.pdf"
    /type "allow"
    }
  }

/allowedClients (in /cache) (Flush Requests only allowed from authorized Clients)

An ACL defines specific clients that are allowed to flush the cache. The globbing patterns are matched against the IP.

The following example:

  1. denies access to any client
  2. explicitly allows access to the localhost
/allowedClients
  {
  /0001
    {
    /glob "*.*.*.*"
    /type "deny"
    }
  /0002
    {
    /glob "127.0.0.1"
    /type "allow"
    }
  }

Caution

It is recommended that you define the /allowedClients.

If this is not done, any client can issue a call to clear the cache; if this is done repeatedly it can severely impact the site performance.

/statistics (Internal Response Statistics)

The /statistics section defines the categories that the Dispatcher uses for load balancing estimates.

Note

If you do not use load balancing, you can omit this section.

The Dispatcher keeps a list of typical response times per CQ instance and per request category. When the Dispatcher needs to render a document, it:

  • checks these lists to determine which CQ instance currently has the most resources available to handle it
  • reserves these resources when considering future requests.

The statistics are internal and cannot be accessed from outside. By default, the Dispatcher makes a distinction between HTML documents and everything else. The default /statistics section looks as follows:

/statistics
  {
  /categories
    {
    /html
      {
      /glob "*.html"
      }
    /others
      {
      /glob "*"
      }
    }
  }
If you want to add a special category for search pages, the section would look as follows:

Note

The more specific requests must be stated first.

/statistics
  {
  /categories
    {
    /search
      {
      /glob "*search.html"
      }
    /html
      {
      /glob "*.html"
      }
    /others
      {
      /glob "*"
      }
    }
  }

/stickyConnectionsFor (Sticky Connection Folder)

You can define one folder that contains sticky documents; this will be accessed using the URL.

The Dispatcher sends all requests, from a single user, that are in this folder to the same web server. This ensures that session data is present and consistent for all documents. This mechanism uses the renderid cookie. To define sticky connections (which will also set the cookie as necessary) for the folder /myFolder, use the following line:

/stickyConnectionsFor "/myFolder"

/health_check (Health Check with URL Probing)

When a 500 status code occurs the specified "health check" page is checked. If this page also returns a 500 status code the instance is considered to be unavailable and a configurable time penalty is applied before retrying.

/health_check
{
# Page gets contacted when an instance returns a 500
/url "/health_check.html"
}

/retryDelay (Retry Delay)

/retryDelay "1"

retryDelay is the intermediate sleep time (defined in seconds) that is applied after one render was unresponsive and before contacting the next one in the list of "renders".

"1" is the default value used if not explicitly defined. The default should be applicable in most case, so this setting should hardly ever need changing.

/unavailablePenalty (Unavailable Penalty)

/unavailablePenalty "1"

unavailablePenalty is the number of seconds that is applied to the Dispatcher statistics after a render is unresponsive. In the Dispatcher statistics the total response time for this render is then increased by the appropriate number of seconds, which in turn moves it to the end of the list of renders as they are sorted by increasing response time.

This might happen, for example, when the TCP/IP connection to the designated hostname/port cannot be established, either because CQ5 is not running (and not listening) or because of a network-related problem.

Logging

In the web server configuration, you can set:

  • The location of the Dispatcher log file.
  • The log level.

Refer to the web server documentation and the readme file of your Dispatcher instance for more information.

Apache Rotated / Piped Logs

If using an Apache web server you can use the standard functionality for rotated and/or piped logs. For example, using piped logs:

    DispatcherLog "| /usr/apache/bin/rotatelogs logs/dispatcher.log%Y%m%d 604800"

This will automatically rotate:

  • the dispatcher log file; with a timestamp in the extension (logs/dispatcher.log%Y%m%d).
  • on a weekly basis (60 x 60 x 24 x 7 = 604800 seconds).

Please see the Apache web server documentation on Log Rotation and Piped Logs; for example Apache 2.2.

Note

Upon installation the default log level is high (i.e. level 3 = Debug), so that the Dispatcher logs all errors and warnings. This is very useful in the initial stages.

However, this requires additional resources, so when the Dispatcher is working smoothly according to your requirements, you can(should) lower the log level.

Confirm Basic Operation

To confirm basic operation and interaction of the web server, dispatcher and CQ instance you can use the following steps:

  1. Set the loglevel to 3.
  2. Start the web server; this also starts the Dispatcher.
  3. Start the CQ instance.
  4. Check the log and error files for your web server and the Dispatcher.
    Depending on your web server you should see messages such as:
           [Thu May 30 05:16:36 2002] [notice] Apache/2.0.50 (Unix) configured
    and:
           [Fri Jan 19 17:22:16 2001] [I] [19096] Dispatcher initialized (build XXXX)
  5. Surf the website via the web server. Confirm that content is being shown as required.
    For example, on a local installation where CQ runs on port 4502 and the web server on 80 access the Websites console using both:
        http://localhost:4502/libs/wcm/core/content/siteadmin.html
        http://localhost:80/libs/wcm/core/content/siteadmin.html
    The results should be identical. Confirm access to other pages with the same mechanism.
  6. Check the contents of the cache directory - is it being filled?
  7. Activate a page - check that the cache is being flushed correctly.
  8. If everything is operating correctly you can reduce the loglevel to 0 again.

Integration with CQ

If the Dispatcher is being used with CQ the interaction must be configured to ensure clean cache management.

Dependent on your environment, the configuration selected can also increase performance.

Disabling External Access to Specific Folders

Invalidating Dispatcher Cache from the Authoring Environment

A replication agent is used to send a cache invalidation request from the CQ author environment to the Dispatcher when a page is published; this removes the old page content from the cache when new content is published.

To set up a CQ authoring environment, so that it invalidates the cache upon publication of a page:

  1. Open the CQ Tools console.
  2. Open the required replication agent; for example the Dispatcher Flush agent that is included in a standard installation.
  3. In the Settings tab ensure that Enabled is active.
  4. Open the Transport tab and enter the URI needed to access the dispatcher.
    If you are using the standard Dispatcher Flush agent you will probably need to update the hostname and port; for example, http://<dispatcherHost>:<portApache>/dispatcher/invalidate.cache
  5. Configure other parameters as required.Configure other parameters as required.
  6. Click OK to activate the agent.

Note

The agent for flushing dispatcher cache does not have to have a user name and password, but if configured they will be sent with basic authentication.

There are two potential issues with this approach:
  • The Dispatcher must be reachable from the authoring instance. If your network (e.g. the firewall) is configured such that access between the two is restricted, this may not be the case.
  • Publication and cache invalidation take place at the same time. Depending on the timing, a user may request a page just after it was removed from the cache, and just before the new page is published. CQ now returns the old page, and the Dispatcher caches it again. This is more of an issue for large sites.

Setting up CQ User Accounts

Various default accounts are included within the CQ installation. Those related to the Dispatcher, must be either changed, configured or deleted as appropriate.

For more information see Default Users and Groups.

Invalidating Dispatcher Cache from a Publishing Instance

Under certain circumstances performance gains can be made by transferring cache management from the authoring environment to a publishing instance. It will then be the publishing environment (not the CQ authoring environment) that sends a cache invalidation request to the Dispatcher when a published page is received.

Such circumstances include:

Note

The decision to use this method should be made by an experienced CQ administrator.

The dispatcher flush is controlled by a replication agent operating on the publish instance. However, the configuration is made on the authoring environment and then transferred by activating the agent:

  1. Open the CQ Tools console.
  2. Open the required replication agent; for example the Dispatcher Flush agent under Agents on Publish that is included in a standard installation.
  3. In the Settings tab ensure that Enabled is active.
  4. Open the Transport tab and enter the URI needed to access the dispatcher.
    If you are using the standard Dispatcher Flush agent you will probably need to update the hostname and port; for example, http://<dispatcherHost>:<portApache>/dispatcher/invalidate.cache
  5. Configure other parameters as required.Configure other parameters as required.
  6. Repeat for every publish instance affected.
  7. If you now activate a page from author to publish, you can see that this agent will initiate a standard replication. The log will include entries indicating requests coming from your publish server; for example:
  8. <publishserver> 13:29:47 127.0.0.1 POST /dispatcher/invalidate.cache 200

Using Multiple Dispatchers

In complex setups, you may use multiple Dispatchers. For example, you may use:

  • one Dispatcher to publish a website on the Intranet
  • a second Dispatcher, under a different address and with different security settings, to publish the same content on the Internet.

In such a case, make sure that each request goes through only one Dispatcher. A Dispatcher does not handle requests that come from another Dispatcher. Therefore, make sure that both Dispatchers access the CQ website directly.

Deny Access with Dispatcher Configuration

You can use the Dispatcher to seal off sensitive areas. If a dispatcher is in front of a publish instance, you can define a filter that refuses all requests to specified sensitive areas. Requests to the sensitive area then result in a 404 error code (page not found).

See how to define filters in the dispatcher.any file.

Optimizing a Website for Cache Performance

Troubleshooting

Note

Please check the Dispatcher Knowledge Base for further information.

Check the Basic Configuration

As always the first steps are to check the basics:

  • Confirm Basic Operation
  • Check all log files for your web server and dispatcher. If necessary increase the loglevel used for the dispatcher logging.
  • Check your configuration:
    • Do you have multiple Dispatchers? 
      • Have you determined which Dispatcher is handling the website / page you are investigating?
    • Have you implemented filters?
      • Are these impacting the matter you are investigating?

IIS Diagnostic Tools

IIS provides various trace tools, dependent on the actual version:

  • IIS 6 - IIS diagnostic tools can be downloaded and configured
  • IIS 7 - tracing is fully integrated

These can help you monitor activity.

IIS and 404 Not Found

When using IIS you might experience 404 Not Found being returned in various scenarios. If so, see the following Knowledge Base articles.

Problems Deleting Workflow Models

Symptoms

Problems trying to delete workflow models when accessing a CQ author instance through the Dispatcher.

Steps to reproduce:

  1. Log in to your CQ author instance (confirm that requests are being routed through the dispatcher).
  2. Create a new workflow; for example, with the Title set to workflowToDelete.
  3. Confirm that the workflow was successfully created.
  4. Select and right click on the workflow, then click Delete.
  5. Click Yes to confirm.
  6. An error message box will appear showing:
          "ERROR 'Could not delete workflow model!!".

Resolution

Add the following headers to the /clientheaders section of your dispatcher.any file:

  • x-http-method-override
  • x-requested-with

{
  {
  /clientheaders
    {
    ...
    "x-http-method-override"
    "x-requested-with"
    }

Interference with mod_dir (Apache)

This describes how the dispatcher interacts with mod_dir inside the Apache webserver, as this can lead to various, potentially unexpected effects:

Apache 1.3

In Apache 1.3 mod_dir handles every request where the URL maps to a directory in the file system.

It will either:

  • redirect the request to an existing index.html file 
  • generate a directory listing

When the dispatcher is enabled, it processes such requests by registering itself as a handler for the content type httpd/unix-directory.

Apache 2.x

In Apache 2.x things are different. A module can handle different stages of the request, such as URL fixup. mod_dir handles this stage by redirecting a request (when the URL maps to a directory) to the URL with a / appended.

The dispatcher does not intercept the mod_dir fixup, but it will completely handle the request to the redirected URL (i.e. with / appended). This might pose a problem if the remote server (e.g. CQ5) handles requests to /a_path differently to requests to /a_path/ (when /a_path maps to an existing directory).

If this happens you must either:

  • disable mod_dir for the Directory or Location subtree handled by the dispatcher
  • use DirectorySlash Off to configure mod_dir not to append /

Portals and Portlets

This document describes the following:

  • CQ Portal architecture
  • How to configure CQ content to appear in a portlet
  • How to configure CQ to act as a portal

CQ Portal Architecture

CQ portal architecture includes definitions of portals, portlets, the CQ Portal Container, and the CQ Portal Director.

What is a portal?

A portal is a web application that provides personalization, single sign on, content integration from different sources, and hosts the presentation layer of information systems.

The CQ5 Portal Container lets you run JSR 286-compliant portlets in CQ. The portlet component lets you embed a portlet on the page. 

What is a portlet?

Portlets are web components deployed inside of a container that generate dynamic content. The portlet interface is packaged and deployed as a .war file inside of a portlet container. If you are running CQ as a portal, you need the portlet's .war file to run the portlet.

To configure CQ content to appear in a portal, see Installing, Configuring, and Using CQ in a portlet.

CQ Portal Director

The CQ5 Portal Director provides a content portlet that lets you display content from the publish instance, preview content from the author instance, and provides a link within the content to open the corresponding page in a new browser window. The portlet is located at /crx-quickstart/opt/portal after the quickstart is extracted.

The content portlet is based on the JSR 286 (portlet API 2.0) and can run in any compliant portal.

Deploying the CQ Content Portlet

The CQ content portlet, available at /crx-quickstart/opt/portal, can be customized in various ways. To function properly, it needs a configuration of the CQ author and publish instance together with the content path to display on startup.

Some of the configurations can be changed through portlet preferences and others through OSGi service configurations. You change these configurations using config files or the OSGi web console.

Portlet Preferences

Porlet preferences can be configured at deployment time in the portal server or by editing the WEB-INF/portlet.xml file before deploying the portlet web application. The portlet.xml file appears as follows by default:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd /opt/SUNWps/dtd/portlet.xsd"
version="1.0">
<portlet>
<portlet-name>RSSWeatherPortlet</portlet-name>
<portlet-class>org.jboss.portlet.weather.WeatherPortlet</portlet-class>
<init-param>
<name>default_zipcode</name>
<value>05673</value>
</init-param>
<init-param>
<name>RSS_XSL</name>
<value>/WEB-INF/Rss.xsl</value>
</init-param>
<init-param>
<name>base_url</name>
<value>http://xml.weather.yahoo.com/forecastrss?p=</value>
</init-param>
<expiration-cache>180</expiration-cache>
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>VIEW</portlet-mode>
<portlet-mode>EDIT</portlet-mode>
</supports>
<portlet-info>
<title>Weather Portlet</title>
</portlet-info>
<portlet-preferences>
<preference>
<name>expires</name>
<value>180</value>
</preference>
<preference>
<name>RssXml</name>
<value>http://xml.weather.yahoo.com/forecastrss?p=33145</value>
<read-only>false</read-only>
</preference>
</portlet-preferences>
</portlet>
</portlet-app>

The portlet can be configured with the following preferences:

startPath This is the start path of the portlet: it defines the content that is initially displayed.
htmlSelector The selector that is appended to each url. By default this is portlet,  so all requests to html pages use urls ending in .portlet.html. This allows the use of custom scripts within CQ for portlet rendering.
addCssToPortalHeader

By default css files included in the HTML page from CQ are included in the portlet. Disabling this option excludes the default css files.

If this option is enabled, the CSS files are either added to the head of the html page or embedded in the html page depending on the behavior of the portal.

includeToolbar By default, a toolbar is rendered inside the content portlet for management functionality. By disabling this option, no toolbar is rendered.
urlParameterNames

List of alternative URL parameter names that might contain the new content URL to display for the portlet. The list is processed top to bottom, the first parameter containing a value is used. If no URL is found, the default URL parameter is used. The provided URL is used, as is, without any further modification.

This setting is per deployed portlet - it is also to globally configure some url parameters in the OSGi configuration for the "Day Portal Director Portlet Bridge".

preferenceDialog Path to the preferences dialog in CQ - if left empty, the built-in preferences dialog will be used. This defaults to /libs/portal/content/prefs.html.
initialRedirect By default, the portlet performs a javascript redirect of the whole portal page on the first invocation. This is to support the drag and drop scenario of modern portal servers. In production this redirect is rarely needed and can therefore be turned off with this preference being set to false.

OSGi Web Console

Assuming the portal server runs on host localhost, port 8080 and the CQ portlet web application is mounted in the web application context cqportlet, the url to for the web console is http://localhost:8080/cqportlet/cqbridge/system/console. The default user and password is admin.

Open the Configurations tab and select Day Portal Directory CQ Server Configuration. Here you specify the base URL to the author and the publish instance. This procedure is described in Configuring the Portlet.

Note

The OSGi web console is only meant for changing configurations during development (or testing). Make sure to block requests to the console for production systems.

Providing Configurations

To support automated deployments and configuration provisioning, the CQ content portlet has built-in configuration support that tries to read configurations from the classpath provided to the portlet application.

On startup, the system property com.day.cq.portet.config is read to detect the current environment. Usually, the value of this property is something like dev, prod, test and so on. If no environment is set, no configurations are read.

If an environment is set, a config file is searched in the classpath at com/day/cq/portlet/{env}.config where env is replaced with the actual value for the environment. This file should list all configuration files for this environment. These files are searched relative to the location of the config file. For example, if the file contains a line my.service.xml, this file is read from the classpath at com/day/cq/portlet/my.service.config. The name of the file consists of the persistence ID of the service, followed by .config. In the previous example, the persistence ID is my.service. The format of the configuration file, is the format used by the Apache Sling OSGi installer.

This means, for each environment, a corresponding config file needs to be added. A configuration that should be applied to all environments needs to be entered in all these files - if it is just for a single environment, it is just entered in that file. This mechanism ensures full control over which configuration is read in which environment.

It is possible to use a different system property to detect the environment. Specify the system property com.day.cq.portet.configproperty containing the name of the system property to use instead of com.day.cq.portet.config.

Caching

By default, the CQ content portlet does not cache any content. It relies on the infrastructure of CQ and the portal server in this respect.

The portlet can be configured with its own cache, so that the content in the portlet displays without requiring access to CQ. A file-based cache implementation can be found as a bundle in the /crx-quickstart/opt/portal directory. You can either deploy this bundle at runtime or add it to the portlet web application at WEB-INF/lib/resources/bundles before the deployment.

After the cache is deployed, the portlet caches contents from the publish instance. The portlet cache can be invalidated with a dispatcher flush from CQ. To configure the portlet to use its own cache:

  1. Configure a replication agent in author that targets the portal server. 
  2. Assuming that the portal server runs on host localhost, port 8080 and the CQ portlet web application is mounted in the context cqportlet, the url to flush the cache is http://localhost:8080/cqportlet/cqbridge/cqpcache?Path=$(path). Use GET as the method.
    Note: Instead of using a request parameter, you can send an http header named Path.

Portal Security

The portal is the driving authentication mechanism. You can log into CQ either with a technical user, the portal user, a group, and so on. The portlet has no access to the password for the user in the portal, so if the portlet does not know all the credentials to successfully log in a user, an SSO solution must be used. In this case, the CQ portlet forwards all required information to CQ, which in turn forwards this information to the underlying CRX. This behavior is pluggable and can be customized.

Authentication on Publish

By default no user information is sent to the publish instance of CQ; the content is always displayed as the anonymous user. If user specific information should be delivered from CQ or if user authentication for publish is required, this has to be turned on.

Authentication on publish can be turned on through the OSGi web console by changing the configuration for the Day Portal Directory Authenticator.

SSO

The portlet supports SSO with CQ5 out of the box. The authenticator service can be configured to use SSO and transmit the current portal user with format Basic as a cookie named cqpsso to CQ. CQ should be configured to use the SSO authentication handler for path /. The cookie name needs to be configured here as well. 

The crx-quickstart/repository/repository.xml for CRX needs to be configured accordingly:

<LoginModule class="com.day.crx.security.authentication.CRXLoginModule">
...
<param name="trust_credentials_attribute" value="TrustedInfo"/>
<param name="anonymous_principal" value="anonymous"/>
</LoginModule>

Enabling PIN authentication

If you are not using the default inline editing features of the CQ content portlet, but want the authoring and administration part of the portlet outside the portal directly in the CQ author instance, you should enable PIN authentication. You also need to change the configuration of the management buttons.

To open the website administration page or to edit a page from the portlet, the CQ content portlet uses the new pin authentication. By default, the pin authentication is disabled, therefore, the following configuration changes have to be made in CQ:

1.  Enable trusted authentication in CRX by adding the trusted info in the repository.xml file:

<pre>
<LoginModule class="com.day.crx.security.authentication.CRXLoginModule">
...
<param name="trust_credentials_attribute" value="TrustedInfo"/>
</LoginModule>
</pre>

2. In the OSGi configuration console, by default located at http://localhost:4502/system/console/configMgr, select CQ PIN Authentication Handler from the drop-down menu.

3. Edit the URL Root Path parameter to just contain the single value /.

Privileges

Some functions of the portlet are protected by privileges. The current user needs to have this privilege in order to be able to access this function. There are the following privileges pre-defined:

  • "toolbar" : This is the general privilege to see/use the toolbar in the portlet.
  • "prefs" : If the user has this privilege, the user is allowed to see/change the preferences of the portlet.
  • "cq-author:edit" : With this privilege, the user is allowed to invoke the edit view of the content.
  • "cq-author:preview" : With this privilege, the user is allowed to see the preview.
  • "cq-author:siteadmin" : With this privlege, the user is allowed to open the siteadmin within CQ.

The best approach to manage the privileges is to use portal roles and assign roles to these privileges. This can be done through an OSGi configuration. The "Day Portal Director Privilege Manager" can be configured with a set of roles for each privilege. If the user has one of the roles, the user has the corresponding privilege.

In addition it is possible to define this role based access on a per portlet instance base. The preferences dialog of the portlet contains an input field for each of the above privileges. For each privilege a comma-separated list of portlet roles can be configured. If a value is configured, this overrides the global configuration from the "Day Portal Director Privilege Manager" service and it might be required to add the same roles from this global setting as the roles are not merged! If no value is specified, the global configuration is used.

Customizing the CQ portlet application

The provided CQ portlet application starts an OSGi container inside the web application just as CQ5 does. This architecture lets you make use of all of the benefits of OSGi:

  • Easy to update and extend
  • Provides hot updates of the portlet without any interaction of the portal server
  • Easy to customize the portlet

Toolbar Buttons

The toolbar and its buttons are configurable and can be customized. You can add your own buttons to the toolbar or define which buttons are displayed in which mode. Each button is an OSGi service configurable through an OSGi configuration.

The OSGi web console lists all button configurations on the Configuration tab. For each button, you can define in which mode this button is displayed. This lets you disable a button by removing all modes for example.

By default, the CQ content portlet uses the inline editing functionality. However, if you prefer to switch into the CQ author instance for editing, enable the SiteAdmin Button and the ContentFinder Button, but disable the Edit Button. In this case, make sure to correctly configure the PIN authentication in CQ.

Link Handling

All links are rewritten to work within the portal context. By default links with render parameters are used. The Day Portal Director HTML Rewriter can be configured to use action links instead.

You can also define additional request parameters to be queried for the content path to be displayed. This is useful, for example, if there is a link from the outside to specific content.

In addition, the Day Portal Director HTML Rewriter can be configured with a list of regular expressions defined excludes for link rewriting. For example, if you have relative links to external systems, you should add them to this exclude list.

Localization

The CQ content portlet has a built-in localization feature, which ensures that the content from CQ is in the correct language.

This is done in two steps:

  1. The Day Portal Directory Locale Detector detects the locale of the portal user by getting the locale setting from the portal. This service must be configured with the list of available languages in CQ.
  2. The Day Portal Director Locale Handler handles the localization of the current request. It takes the path of the requested content, for example /content/geometrixx/en/company.html and according to the configuration, it rewrites the en with the actual locale of the user.

The Day Portal Director Locale Handler can be configured with the paths to check for locale information - usually this includes everything under /content and with the position of the locale information in the path. By default, the locale handler follows the recommondation of structuring multi-language sites within CQ.

If your site has no strict rule for handling the locale information within the path, it is possible to replace the locale handler with your own implementation.

Optional OSGi Services

Optional OSGi services can be implemented to customize various parts of the portlet. Each service corresponds to a Java interface. This interface can be implemented and deployed through a bundle into the portlet.

RequestTracker The request tracker gets notified whenever content is displayed by the portlet. This allows you to keep track of the invocations of the portlet.
InvocationContextListener Listener that is invoked at the beginning and end of each request to the portlet. The listener can be used to change or add information for the current request.
ErrorHandler Custom error handler for errors during the render phase.
HttpProcessor This service can be used to add information to each http invocation to CQ.
PortletAction Add an own action to the portlet - this action can be invoked through a portlet action link.
PortletDecoratorService This service can be used to decorate the contents of the portlet.
ResourceProvider Add your own resource provider to deliver some resource through a portlet resource link to the client.
TextMapper Allows you to post process HTML, CSS and Javascript files.
ToolbarButton Add your own button to the toolbar.
UrlMapper Add a service to apply a custom url mapping or rewriting.
UserInfoProvider Add your own information about the user. This service can be used to get information from the portal to the portlet.

Replacing Default Services

The following services have a default implementation in the content portlet (with a corresponding Java interface). To customize, a bundle containing the new service implementation needs to be deployed into the portlet application.

When implementing such a service, make sure to set the service.ranking property of the service to a positive value. The default implementation uses the ranking 0 and the portlet uses the service with the highest ranking.

Name Description Default Behavior
Authenticator Provides the authentication information to CQ Uses a configurable technical user for both author and publish. Or SSO can be used.
HTMLRewriter Rewrites links, images etc. Rewrites CQ links to portal links, can be extended by a UrlMapper and a TextMapper
HttpClientService Handles all http connections Standard implementation
LocaleHandler Handles the locale info Rewrites a link to the content with respect to the locale.
LocaleDetector Detects the locale of the user. Uses the locale provided by the portal.
PrivilegeManager Checks user rights Checks access to author instance if user is allowed to edit contents
ToolbarRenderer Renders the toolbar Adds a toolbar functionality

Portlet Events

The portlet API (JSR-286) specifies portlet events. The CQ content portlet has an integrated bridge, distributing portlet events for the CQ portlet as OSGi events - this makes handling of portlet events pluggable.

If you want to handle specific events, declare these as receiving events in the deployment descriptor (or configure it through your portal server) and implement an OSGi service declaring the EventHandler interface (see OSGi EventAdmin specification).

Whenever a portlet event occurs, a specific OSGi event is sent invoking your handler. The handler gets all context information and can update the status of the portlet accordingly or sent new events. Basically, inside the handle method all functionality of the portlet event phase can be used.

Installing, Configuring, and Using CQ in a Portlet

To access content provided by CQ5 WCM, the portal server needs to be fitted with the CQ5 Portal Director Portlet. You do this by installing, configuring, and adding the portlet to the portal page by using the steps provided in this section.

By default, the portlet connects to the publish instance at localhost:4503 and to the author instance at localhost:4502. These values can be changed during deployment of the portlet by changing the according preferences. The portal director can be found in the opt directory after CQ quickstart has been started for the first time.

Note

These procedures use the Websphere portal as an example although they are as generic as possible; please be aware that procedures vary for other web portals. Although the steps are essentially identical for all web portals, you need to repurpose the steps for your particular web portal.

Installing the portlet

To install the portlet:

  1. Log in to the portal with administrator privileges.

  2. Navigate to the Portlet Management part of your web portal.

  3. Click Install and browse to the supplied CQ5 portlet application (cqportlet.war) located in the opt director of the crx quickstart folder and enter other important information about the portlet. 

    For other essential portlet information, you can either accept the defaults or change the values. If you accept the default values, the portlet is available at http://<wps-host>:<port>/wps/PA_CQ5_Portlet. The OSGi administration console provided by the portlet is available at http://<wps-host>:<port>/wps/ PA_CQ5_Portlet/cqbridge/system/console (default username/password is admin/admin).

  4. Ensure that the portlet application automatically starts by selecting that option or check box and save your changes. You see a message that your installation was successful.

Configuring the Portlet

After you install the portlet, you need to configure it so that it knows the URLs of the underlying CQ5 instances (author and publish). You also can configure other options.

To configure the portlet:

  1. In the Portal administration window of the app server, navigate to portlet management, where all portlets are listed and select the CQ Portal Director portlet.

  2. Configure the portlet, as necessary. For example, you may need to change the URL for the author and publish instances and the URL for the start path. Default configurations are described in Portlet Preferences.

  3. Save the configuration changes in the app server.

  4. Navigate to the OSGI admin console for the portlet. The default location is http://<wps-host>:<port>/wps/PA_CQ5_Portlet/cqbridge/system/console/configMgr. The default username/password is admin/admin.

  5. Select the Day Portal Director CQ Server Configuration configuration and edit the following values:

    • Author Base URL: The base URL for the CQ author instance.
    • Publish Base URL: The base URL for the CQ publish instance.
    • Author Is Used As Publish: Is the author instance used as a publish
      instance (for development)?
    file
  6. Click Save. You can now add the portlet to portal pages and use the portal.

Content URLs

When content is requested from CQ, the portlet uses the current display mode (publish or author) and the current path to assemble a complete URL. With the default values, the first url is http://localhost:4503/content/geometrixx/en.portlet.html. The value of the htmlSelector is automatically added to the URL before the extension.

If the portlet switches to the help mode and the appendHelpViewModeAsSelector is selected, then the help selector is appended as well, for example, http://localhost:4503/content/geometrixx/en.portlet.html.help. If the portlet window is maximized and the appendMaxWindowStateAsSelector is selected, then the selector is appended as well, for example, http://localhost:4503/content/geometrixx/en.portlet.max.help.

The selectors can be evaluated in CQ and a different template can be used for different selectors.

Using a Content Url Map in CQ

Usually the start path points directly to the content in CQ. However if you want to maintain start paths in CQ rather than in the portlet preferences, you can point the start path to a content map in CQ, like /var/portlets. In this case, a script running in CQ can use the submitted information from the portlet to decide which url is the start url. It should issue a redirect to the correct url.

Adding the Portlet to the Portal Page

To add the portlet to the portal page:

  1. Be sure you are in the administration window of your app server and navigate to the location where you manage pages. (for example, in WebSphere 6.1, click Manage Pages).

  2. Select the name of the portlet and then select an existing page or create a new page.

  3. Edit the page layout.

  4. Select the portlet and add it to a container. 

  5. Save your changes.

Using the Portlet

To access the page you added to the portlet in Adding the Portlet to the Portal Page:

  1. In the portlet's personalization menu, configure the portlet as you configured it in the portal.

  2. Open the configuration (The portlet displays the publish start URL configured in the portlet’s configuration) and make edits as necessary, then save them.

Using CQ as a Portal

To configure to use CQ as a portal, you need to do the following:

  1. Configure the portlet component in CQ WCM.
  2. Deploy the portlet.
  3. Configure the portlet.

Configuring the Portlet component

You need to add the portlet component to the paragraph system by adding it in the Designer.

To add the portlet component to the existing paragraph system:

  1. In the sidekick, select the ruler icon (Designer).
  2. In Design of par above the first paragraph, click Edit.
  3. In the General component category, select the check box next to the Portlet component to make it part of the paragraph system.
  4. In Edit mode, drag the portlet component on the page or double-click the component and choose Portlet from General in the sidekick.
file

Deploying portlets

Deploying portlets includes rewriting the portlet application's web.xml file and deploying the application. 

Adding the servlet configuration to the web.xml file

To work properly in the CQ portal container, the portlet application's web.xml needs to be rewritten before you deploy it. 

Note

If CQSE is used as the servlet container, CQSE does the rewriting and you do not have to rewrite the web.xml file.

 

To add the servlet configuration when CQSE is not used as the servlet container:

  1. Open the .war file (jar xf nameofapp.war extracts the files) to access the application's web.xml file.
  2. Add the following servlet configuration to the web.xml file:

 <servlet>
<servlet-name>slingportal</servlet-name>
<servlet-class>org.apache.sling.portal.container.api.ContainerServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>slingportal</servlet-name>
<url-pattern>/SlingPortletInvoker</url-pattern>
</servlet-mapping>

Deploying the application

After configuring the portlet application's web.xml file, deploy the portlet through the admin console.

To deploy the application:

  1. Navigate to the admin console at http://<host>:<port>/admin/webapps.
  2. Navigate to the portlet by clicking Choose File and browsing to the .war file.
  3. In the Context field, add a context, for example, /portlet.
file

Adding portlets to your CQ page

After the portlet is deployed, you can add it to your page.

To add a portlet component to your web page:

1. On the web page, drag the Portlet component from the sidekick (General) to the page.

Note

After you drag the component to the page, reload the page to ensure that it works properly.

file

2. In the Portlet Entity drop-down menu, select the portlet from the list.

3. Select or clear the Hide Title Bar check box depending on whether you want to see the portlet's title bar.

4. In the Portlet Window field, enter a unique Portlet Window ID, if desired.

Note

If you plan to use the same portlet more than once on the same page, give each portlet a different window ID.

5. Click OK. The portlet displays on your CQ page.

file

Caching and Cache Invalidation

The portlet, in its default configuration, caches the responses it receives from CQ WCM in a user-specific cache. The caches need to be invalidated when changes occur in the content of the publish instance. For this purpose, in CQ WCM a replication agent must be configured on the author instance. The cache can also be flushed manually. This section describes both of those procedures.

Flushing the Cache via Replication Agent

Just like the normal dispatcher invalidation, a replication agent can be configured to target the portal's CQ5 portlet cache. After you configure the replication agent, every regular page activation flushes the portal cache.

If you operate several portal nodes running the CQ portlet, you need to create an agent for each node as described in this procedure.

To configure a replication agent for the portal:

  1. Log in to the author instance.

  2. In the Websites tab, click the Tools tab.

  3. Click New Page... in the replication agents New... menu.

  4. In Template, select Replication Agent, and enter a name for the agent. Click Create.

  5. Double-click the replication agent you just created. It displays as invalid as it has not yet been configured.

  6. Click Edit.

  7. In the Settings tab, select the Enabled check box, select Dispatcher Flush as the serialization type, and enter a retry timeout (for example, 60000).

  8. Click the Transport tab.

  9. In the URI field, enter the flush URI (URL) of the portlet. The URI is in the following form:

    http://<wps-host>:<port>/<wps-context>/<cq5-portlet-context>/cqbridge/cqpcache
  10. Click the Extended tab.

  11. In the HTTP Method field, type GET.

  12. In the HTTP Headers field, click + to add a new entry and type Path: {path}.

  13. If necessary, click the Proxy tab and enter proxy information to the agent.

  14. Click OK to save changes.

  15. To test the connection, click the Test Connection link. A log message appears that indicates whether the replication test succeeded. For example:

Manually Flushing the Portlet Cache

You can manually flush the portlet cache by accessing the same URL configured for the replication agent. See Flushing the Cache for the form of the URL. In addition, the URL needs to be extended with a URL parameter Path=<path> to indicate what to flush.

For example:

http://10.0.20.99:10040/wps/PA_CQ5_Portlet/cqbridge/cqpcache?Path=* flushes the complete cache. http://10.0.20.99:10040/wps/PA_CQ5_Portlet/cqbridge/cqpcache?Path=/content/mypage/xyz flushes /content/mypage/xyz from the cache.

Authentication

This section describes the available authentication modes the portlet can use in communicating with the underlying CQ WCM instances.

Accessing the Portlet's Authentication Configuration

Authentication configuration options that the portlet uses in CQ WCM instances are available in the Apache Felix Web Management console (OSGi configuration),

To access the portlet's authentication configuration:

  1. Access the Apache Felix Web Management console at the following URL:

    http://:///cqbridge/system/console

    For example, in its default configuration:

    http://wps-host:10040/wps/PA_CQ5_Portlet/cqbridge/system/console
  2. Log in to the Apache Felix console. The default credentials are admin/admin. The Apache Felix Web Management Console opens:

  3. In the Apache Felix Console, select Configuration.

  4. In the Configuration menu, select a particular service to configure. Services are provided by the portlet in the OSGi framework.

    The following services can be configured:

    Services that can be configured

    Service Name Description 
    Day Portal Director Authenticator Configure which authentication mode is used for CQ WCM instances. Depending on the selected mode, a technical user or the name of the SSO cookie can be specified. Also, authentication for CQ WCM publish instances can be enabled.
    Day Portal Director File Cache Configure the parameters of how the portlet caches responses it receives from CQ WCM instances.
    Day Portal Director HTTP Client Service Configure how the portlet connects via HTTP to underlying CQ WCM instances. You can, for example, specify a proxy server.
    Day Portal Director Locale Handler Configure which locales the portlet supports. Requests to CQ WCM instances are based on the user locale; for example, user language German would request /content/geometrixx/de/....
    Day Portal Director Privilege Manager Configure whether the portlet should test the Websites tab based on the currently logged in user.
    Day Portal Director Toolbar Renderer Customize the rendering of the portlet's toolbar.

  5. In addition, you can configure the OSGi management console and the logging service. For example, you can change the admin credentials for the Apache Felix Console by clicking the OSGi Management Console link.

Technical User Mode

In default mode, all requests issued by the portlet for the CQ WCM author instance are authenticated using the same technical user, regardless of the current portal user. Technical User mode is enabled by default. You enable/disable this mode in the respective configuration screen in the OSGi management console:

The technical user specified must exist on the CQ WCM author instance and on the publish instance if Authenticate on Publish is enabled. Be sure to give the user access privileges sufficient for authoring work.

SSO Authentication Mode

The portlet can authenticate for CQ WCM using the Single Sign On (SSO) scheme. In this mode, the user currently logged in to the portal is forwarded to CQ WCM in the form of an SSO cookie. If SSO mode is used, all portal users with access to the CQ portlet must be known to the underlying CQ WCM instances, most commonly in the form of CQ WCM being connected to LDAP, or by having manually created the users beforehand. Also, before enabling SSO in the portlet, the underlying CQ WCM author instance (and the publish instance, ifAuthenticate on Publish is enabled) needs to be configured to accept SSO-based requests.

To configure the portlet to use SSO authentication mode, complete the following steps (described in detail in the following sections):

  • Enable CQ WCM's CRX to accept trusted credentials.
  • Enable SSO authentication in the CQ WCM.
  • Enable SSO Authentication in the CQ portlet.

Enabling CQ WCM's CRX to accept trusted credentials

Before SSO can be enabled for CQ WCM, the underlying CRX instance needs to be configured to accept the trusted credentials provided by CQ WCM. To do this, you configure CRX's repository.xml.

To enable CRX to accept trusted credentials:

  1. In the file system where CQ WCM is installed, open the following file:

    //crx-quickstart/repository/repository.xml
  2. In the XML file, find the entry for the LoginModule and add the trust_credentials_attribute to its configuration:

    <LoginModule class="com.day.crx.security.authentication.CRXLoginModule"> <!-- configuration options: - deny_anonymous_access (true|false) Per default this login-module allows anonymous access. This can be turned off by setting this parameter to true - trust_credentials_attribute [credential attribute name] Set the name of the SimpleCredential attribute, which indicates that LoginModule should trust credentials without further authentication. This can be used to let CRX participate in an SSO environment Defaults to empty - anonymous_principal [principal-name] Set the principal's name to be assigned to an anonymous authentication request. This can be used to assign more elaborted access-rights for anonymous users. Defaults to "anonymous" --> <param name="trust_credentials_attribute" value="TrustedInfo"/> <param name="anonymous_principal" value="anonymous"/> </LoginModule>
  3. Restart CQ WCM for the changes to take effect.

Enabling SSO authentication in the CQ WCM

To enable SSO in CQ WCM, access the relevant configuration entry in the CQ WCM's Apache Felix Web Management Console (OSGi):

  1. Access the console through its URI at http://<cq5-host>:<port>/system/console.

  2. In the Configuration menu, select SSO Authentication Handler. In this example, the SSO handler accepts SSO requests for all paths based on the cookie provided by the CQ portlet. Your configuration may vary.

    Example configuration parameters
    Path / Enables SSO handler for all requests
    Cookie Names cqpsso Name of the cookie provided by the portlet as configured in the portlet's OSGi console
  3. Click Save to enable SSO. SSO is now the primary authentication scheme.

For every request CQ WCM receives, first the SSO-based authentication is attempted. Upon failure, a fallback to the usual basic authentication scheme is performed. As such, normal connections to CQ WCM without SSO remain possible.

Enabling SSO Authentication in a CQ Portlet

In order for the underlying CQ WCM instance to accept SSO requests, the portlet’s authentication mode has to be switched from Technical to SSO.

To enable SSO authentication in a CQ portlet:

  1. Access the console through its URI at http://<cq5-host>:<port>/system/console.

  2. In the Configuration menu, select Day Portal Director Authenticator from the list of available configurations.

  3. In Mode, select SSO. Leave the other parameters with their default values.

  4. Click Save to enable SSO for the portlet.

    For testing purposes, access the portlet with your portal's administrative user, after you create the same user in CQ WCM with administrator privileges.

After performing this procedure, requests are authenticated using SSO. A typical snippet from the HTTP communication reveals the presence of the following SSO and Portlet specific headers:

C-12-#001898 -> [GET /mynet/en/_jcr_content/par/textimage/image.img.png HTTP/1.1 ]
C-12-#001963 -> [cq5:locale: en ]
C-12-#001979 -> [cq5:used-locale: en ]
C-12-#002000 -> [cq5:locales: en,en_US ]
C-12-#002023 -> [cqp:user: wpadmin ]
C-12-#002042 -> [cqp:portal: IBM WebSphere Portal/6.1 ]
C-12-#002080 -> [cqp:windowid: 7_CGAH47L000CE302V2KFNOG0084 ]
C-12-#002124 -> [cqp:windowstate: normal ]
C-12-#002149 -> [cqp:portletmode: view ]
C-12-#002172 -> [User-Agent: Jakarta Commons-HttpClient/3.1 ]
C-12-#002216 -> [Host: 10.0.0.68:4502 ]
C-12-#002238 -> [Cookie: $Version=0; cqpsso=Basic+d3BhZG1pbg%3D%3D ]
C-12-#002289 -> [ ]

Customizing the Portlet Toolbar

The portlet's toolbar layout can be customized by installing a bundle through the portlet's Felix Web Console, which contains custom CSS/HTML at a predefined location.

Bundle Structure

The following is an example bundle structure:

$ jar tvf target/toolbarlayout-0.0.1-SNAPSHOT.jar | awk '{print $8}'
META-INF/
META-INF/MANIFEST.MF
/com/day/cq/portlet/toolbar/layout/
/com/day/cq/portlet/toolbar/layout/author.gif
/com/day/cq/portlet/toolbar/layout/back.gif
/com/day/cq/portlet/toolbar/layout/button.html
/com/day/cq/portlet/toolbar/layout/edit.gif
/com/day/cq/portlet/toolbar/layout/manage.html
/com/day/cq/portlet/toolbar/layout/publish.html
/com/day/cq/portlet/toolbar/layout/refresh.gif
/com/day/cq/portlet/toolbar/layout/siteadmin.gif
/com/day/cq/portlet/toolbar/layout/toolbar.css

The META-INF folder contains the MANIFEST.MF file required by OSGi to identify it as a bundle. It appears as follows:

Manifest-Version: 1.0
Built-By: djaeggi
Created-By: Apache Maven Bundle Plugin
Import-Package: com.day.cq.portlet.toolbar.layout
Bnd-LastModified: 1234178347159
Export-Package: com.day.cq.portlet.toolbar.layout
Bundle-Version: 0.0.1.SNAPSHOT
Bundle-Name: Company CQ5 Portal Director Portlet Toolbar Layout
Bundle-Description: This bundle provides a custom layout for the CQ5 P
ortal Director Portlet Toolbar.
Build-Jdk: 1.5.0_16
Bundle-ManifestVersion: 2
Bundle-SymbolicName: com.day.cq.portlet.company.toolbarlayout
Tool: Bnd-0.0.255

The fact that the HTML/CSS/images are within the /com/day/cq/portlet/toolbar/layout folder is mandated by the portlet and cannot be changed. Along the same lines, the Import-Package and Export-Package headers in MANIFEST.MF must be called /com/day/cq/portlet/toolbar/layout as well. The Bundle-SymbolicName must be a unique, fully qualified package name.

You can build it using a tool such as maven or manually create such a jar file with the relevant header set as shown in this section.

Portlet Toolbar Views

The portlet's toolbar basically has two view states. Each view and associated buttons can be customized with a respective HTML file.

Publish View

The publish view only has one button that switches the toolbar to the Manage view. The publish view is represented by the publish.html file in previous bundle. In the HTML, you can use the following placeholders, which are replaced by the portlet with the respective contents when rendered:

Publish View Placeholders

Placeholder  String Description 
{buttonManage} Placeholder is replaced by the Manage button, which switches the portlet state into the management state.

Manage View

The manage view has four buttons: Edit, Websites tab, Refresh and Back. The manage view is represented by the manage.html file in the previous bundle. In the HTML, you can use the following placeholders, which are replaced by the portlet with the respective contents when rendered:

Manage View Placeholders

Placeholder String  Description 
{buttonEdit} Placeholder is replaced by the Edit button, which opens a new window with the current page in CQ's edit mode.
{buttonWebsites tab} Placeholder, replaced by a button which opens the Websites tab of CQ WCM.
{buttonRefresh} Refreshes the current view.
{buttonBack} Switches the portlet back into the publish view.

Buttons

Buttons, on whichever view they appear, use the same common HTML, defined in button.html.

In the HTML, you can use the following placeholders, which are replaced by the portlet with the respective contents when rendered:

Manage and Publish View Buttons

Placeholder String  Description 
{name} Name of the button, for example, author, back, refresh, and so on.
{id} CSS id of the button.
{url} URL for the button's target.
{text} Label of the button.
{onclick} Javascript onclick function (contains {url}).

Example of a button.html file:

<div class="cqp_button">

<a href="#" onclick="{onclick}">

<img src="/wps/PA_CQ5_Portlet/cqbridge/static/{id}.gif" alt="{text}"
title="{text}"/>

</a>
</div>

Installing a Custom Layout

To install a custom layout, access the portlet’s OSGI Web console Bundles section and upload the bundle.

Packages

If you need to upload, or create, packages for your installation, then see Package Manager in the CRX documentation for detailed instructions.