OSGi Configuration Settings

OSGi is a fundamental element in the technology stack of AEM. It is used to control the composite bundles of AEM and their configuration.

OSGi "provides the standardized primitives that allow applications to be constructed from small, reusable and collaborative components. These components can be composed into an application and deployed".

This allows easy management of bundles as they can be stopped, installed, started individually. The interdependencies are handled automatically. Each OSGi Component (see the OSGi Specification) is contained in one of the various bundles. When working with AEM there are several methods of managing the configuration settings for such bundles; see Configuring OSGi for more details and the recommended practices.

The following OSGi configuration settings (listed according to bundle) are relevant to project implementation. Not all the listed settings need adjusting, some are mentioned to help you understand how AEM operates.

Caution:

The list is intended to act as a guideline and is not exhaustive. Not all bundles are listed, nor all parameters for some of the bundles that are.

The configuration necessary will vary from project to project.

Please see the Web console for values used and detailed information about parameters.

Further bundles may be required for specific areas of functionality within AEM. In these cases, configuration details can be found on the page related to the appropriate functionality.

Apache Felix OSGi Management Console

Configure:

Plugins, the main navigation items (console plugins) to be available in the Apache Felix Web Management Console as top level menu items. Disable any you do not need as each requires space and resources.

Caution:

Be sure to configure the following:

User Name and Password, the credentials for accessing the Apache Felix Web Management Console itself.
The password must be changed after the initial installation to ensure the security of your instance.

Note:

This configuration should be made using the Felix Console as it is needed at startup - before the repository is available.

Apache Sling Customizable Request Data Logger

Configure:

Logger Name and Log Format to configure the location and format of request and access logging (default: request.log). This log file is essential when analyzing performance or debugging functionality related to the web chain.
This is paired with the Apache Sling Request Logger.

Enable (or disable) default renditions, such as HMTL, Plain Text, JSON or XML.
You should not disable JSON.

Note:

This setting is automatically configured for production instances if you run AEM in Production Ready Mode.

Apache Sling Java Script Handler

Configure settings for the compilation of .java files as scripts (servlets).

Certain settings can affect performance, these should be disabled where possible, in particular for a production instance.

Source VM and Target VM, define the JDK version as that used as the runtime JVM

for production instances:

disable Generate Debug Info

Apache Sling JCR Installer

Installation folders name regexp and Max hierarchy depth of install folders - specify where, and to which depth, repository folders are searched for resources to be installed. When a wildcard is used (as in .*/install) all appropriate matches will be searched, for example, /libs/sling/install and /libs/cq/core/install.

Search Path, list of paths that jcrinstall searches for resources to be installed, together with a number indicating the weighting factor for that path.

These parameters probably do not need configuration, but can be useful to know when developing or debugging. For example the installation folder(s) can be useful for checking in/out or creating a package.

Apache Sling JSP Script Handler

Configure performance relevant settings for the JSP script handler. To improve performance you should disable as much as possible.

In particular for production instances:

disable Generate Debug Info

disable Keep Generated Java

disable Mapped Content

disable Display Source Fragments

Note:

This setting is automatically configured for production instances if you run AEM in Production Ready Mode.

Apache Sling Logging Configuration

Configure:

Log Level and Log File, to define the location and log level of the central logging configuration (error.log). The level can be set to one of DEBUG, INFO, WARN, ERROR and FATAL.

Number of Log Files and Log File Threshold to define the size and version rotation of the log file.

Otherwise changes made to URL Mappings using the Felix console might be overwritten by AEM upon the next startup.

Apache Sling Servlet/Script Resolver and Error Handler

The Sling Servlet and Script Resolver has multiple tasks:

It is used as the ServletResolver to select the Servlet or Script to call to handle the request.

It acts as the SlingScriptResolver.

It manages error handling by implementing the ErrorHandler interface using the same algorithm to select error handling servlets and scripts as is used to resolve request processing servlets and scripts.

Various parameters can be set, including:

Execution Paths lists the paths to search for executable scripts; by configuring specific paths you can limit which scripts can be executed. If no path is configured then the default is used (/ = root), this allows the execution of all scripts.
If a configured path value ends with a slash, the whole sub tree is searched. Without such a trailing slash the script will only be executed if it is an exact match.

Script User - this optional property can specify the repository user account used for reading the scripts. If no account is specified the admin user is used by default.

Default Extensions The list of extensions for which the default behavior will be used. This means that the last path segment of the resource type can be used as the script name.

Apache HTTP Components Proxy Configuration

Proxy configuration for all code using the Apache HTTP client, used when a HTTP is made; for example upon replication.

When creating a new configuration, do not make changes to the factory configuration but instead create a new factory configuration for this component using the configuration manager available here: http://localhost:4502/system/console/configMgr/. The proxy configuration is available in org.apache.http.proxyconfigurator.

Note:

In AEM 6.0 and earlier releases proxy was configured in Day Commons HTTP Client. As of AEM 6.1 and later releases the proxy configuration has moved to the "Apache HTTP Components Proxy Configuration" instead of the 'Day Commons HTTP Client' config.

Adobe Granite HTML Library Manager

Configure this to control the handling of client libraries (css or js); including, for example, how the underlying structure is seen.

For production instances:

enable Minify (to remove CRLF and whitespace characters).

enable Gzip (to allow files to be gzipped and accessed with one request).

disable Debug

disable Timing

For JS development (especially when firebugging/debugging):

disable Minify

enable Debug to separate the files for debugging and use with firebug.

enable Timing in the case of interest in timing.

enable Debug console to see JS console log messages.

Caution:

When changing the setting for either Minify or Gzip you will also need to delete the contents of /var/clientlibs. This is a cached version of the clientlibs and will be rebuilt when next requested.

Note:

This setting is automatically configured for production instances if you run AEM in Production Ready Mode.

Day CQ HTTP Header Authentication Handler

System wide settings for the basic authentication method of the HTTP request.

Using AEM Root Mapping you can configure the UI that you want to have as the default for your instance:

To have the touch-optimized UI as the default UI the Target Path should point to:
/projects.html

To have the classic UI as the default UI the Target Path should point to:
/welcome.html

Note:

Upon a standard installation the touch-optimized UI is the default UI.

Adobe Granite SSO Authentication Handler

Configure Single Sign On (SSO) details; these are often needed in enterprise author setups, often in conjunction with LDAP.

Various configuration properties are available:

Path
Path for which this authentication handler is active. If this parameter is left empty the authentication handler is disabled. For example, the path / causes the authentication handler to be used for the entire repository.

Service Ranking
OSGi Framework Service Ranking value is used to indicate the order used for calling this service. This is an int value where higher values designate higher precedence.
Default value is 0.

Header Names
The name(s) of headers that might contain a user ID.

Cookie Names
The name(s) of cookies that might contain a user ID.

Parameter Names
The name(s) of request parameters that might provide the user ID.

User Map
For selected users, the user name extracted from the HTTP request can be replaced with a different one in the credentials object. The mapping is defined here. If the user name admin appears on either side of the map, the mapping will be ignored. Please be aware that the character "=" has to be escaped with a leading "\".

Format
Indicates the format in which the user ID is provided. Use:

Basic if the user ID is encoded in the HTTP Basic Authentication format

AsIs if the user ID is provided in plain text or any regular expression applied value should be used as is or any regular expression

Day CQ WCM Debug Filter

Disable this on production instances to ensure performance and security.

This is useful when developing as it allows the use of suffixes such as ?debug=layout when accessing a page. For example, http://localhost:4502/cf#/content/geometrixx/en/support.html?debug=layout will provide layout information that may be of interest to the developer.

Day CQ WCM Filter

Configure:

WCM Mode to define the default mode.

On an author instance this might be edit, disable,preview or analytics.
The other modes can be accessed from the sidekick, or the suffix ?wcmmode=disabled can be used to emulate a production environment.

On a publish instance this must be set to disabled to ensure that no other mode is accessible.

Note:

This setting is automatically configured for production instances if you run AEM in Production Ready Mode.

Day CQ WCM Link Checker Configurator

Configure:

List of rewrite configurations to specify a list of locations for content-based linkchecker configurations. The configurations can be based on run mode; this is important to distinguish between author and publish environments, as linkchecker settings may differ.

Day CQ WCM Page Processor

Configure:

Paths, a list of locations where the system listens for page modifications before triggering a jcr:Event.

Adobe Page Impressions Tracker

For an author instance configure:

sling.auth.requirements: set the value of this property to -/libs/wcm/stats/tracker

Caution:

This configuration will allow anonymous requests to the tracking service.

URL to send data to configure the URL used to track page statistics (is vital if a tracker request goes through the dispatcher); for example, the default is http://localhost:4502/libs/wcm/stats/tracker.

Tracking script enabled to enable (true) or disable (false) the inclusion of the tracking script on the pages. The default value is false.