Configuring OSGi
Configuring OSGi
Overview / CQ / Adobe Experience Manager 5.6.1 / Deploying /
OSGi is a fundamental element in the technology stack of Adobe Experience Manager (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.
You can manage the configuration settings for such bundles by either:
• using the Adobe CQ Web console
• configuring content-nodes (sling:OsgiConfig) in the repository
Either method can be used though there are subtle differences, primarily in relation to Run Modes:
• Adobe CQ Web console
• The Web Console is the standard interface for OSGi configuration. It provides a UI for editing the
various properties, where possible values can be selected from predefined lists.
As such it is the easiest method to use.
• Any configurations made with the Web Console are applied immediately and applicable to the
current instance, irrespective of the current run mode, or any subsequent changes to the run mode.
• content-nodes (sling:osgiConfig) in the repository
• This requires manual configuration using CRXDE Lite.
• Due to the naming conventions of the sling:OsgiConfig nodes, you can tie the configuration to a
specific run mode. You can even save configurations for more than one run mode in the same
repository.
• Any appropriate configurations are applied immediately (dependent on the run mode).
Whichever method you use, both of these configuration methods:
•
•
•
•
Ensure that copying or replicating the repository contents recreates identical configurations.
Allow you to check configurations out to FileVault or Subversion; either for security or further updates.
Can be saved in packages for use when setting up other instances.
Allow you to perform configuration rollouts using scripts to propogate the configuration details.
NOTE
Details of certain important settings are listed under OSGi Configuration Settings.
OSGi Configuration with the Web Console
The Web console in AEM provides a standardized interface for configuring the bundles. The Configuration
tab is used for configuring the OSGi bundles, and is therefore the underlying mechanism for configuring AEM
system parameters.
Any changes made are immediately applied to the relevant OSGi configuration, no restart is required. They
can also be located for saving in packages for re-use in further installations.
NOTE
On the Web console any descriptions that mention default settings relate to Sling defaults.
Adobe Experience Manager has its own defaults and so the defaults set might differ from those
documented on the console.
UPDATING A CONFIGURATION WITH THE WEB CONSOLE
1.
Access the Configuration tab of the Web Console by either:
• Opening the console from the link on the Tool menu. After logging into the console you can use the
drop-down menu of:
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 1
Created on 2015-03-01
Configuring OSGi
OSGi >
The direct URL; for example:
http://localhost:4502/system/console/configMgr
A list will be shown.
•
2.
3.
Select the bundle that you want to configure by either:
• clicking on the Edit icon for that bundle
• clicking on the Name of the bundle
A dialog will open. Here you can edit as required; for example, set the Log Level to INFO:
NOTE
If you want to locate the configuration in repository afterwards (for use in a package)
then make a note of the persistent identity (PID).
4.
Click Save.
Your changes are immediately applied to the relevant OSGi configuration of the running system, no
restart is required.
LOCATING YOUR CHANGES TO A CONFIGURATION
Configuration changes made in the Web Console are persisted in the repository under:
/apps
The Web Console does not show you where in the repository that your changes have been saved, but they
can be easily located:
1.
2.
3.
Open CRXDE Lite.
In the Tools menu select Query ... .
Submit a query of Type SQL to search for the PID of the configuration that you have updated.
For example, Apache Felix OSGi Management Console has the persistent identity (PID) of:
org.apache.felix.webconsole.internal.servlet.OsgiManager
So the SQL query could be:
select * from nt:base where jcr:path like '/apps/%' and contains(*,
'org.apache.felix.webconsole.internal.servlet.OsgiManager')
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 2
Created on 2015-03-01
Configuring OSGi
4.
The configuration node will be shown. For the above example:
/apps/system/config/org.apache.felix.webconsole.internal.servlet.OsgiManager.config
You can open this to view your changes (but to avoid typing errors, actual changes should be made
with the console).
OSGi Configuration in the Repository
In addition to using the Web console, you can also define configuration details in the repository. This allows
you to easily configure your differing run modes.
These configurations are made by creating sling:OsgiConfig nodes in the repository for the system to
reference. These nodes mirror the OSGi configurations, and form a user interface to them. To update the
configuration data you update the node properties.
If you modify the configuration data in the repository the changes are immediately applied to the relevant
OSGi configuration as if the changes had been made using the Web console, with the appropriate validation
and consistency checks. This also applies to the action of copying a configuration from /libs/ to /apps/.
As the same configuration parameter can be located in several places, the system:
• searches for all nodes of type sling:OsgiConfig
• filters according to service name
• filters according to run mode
NOTE
Read also how to define a repository based confinguration for a specific instance only.
ADDING A NEW CONFIGURATION TO THE REPOSITORY
What You Need to Know
To add a new configuration to the repository you need to know the following:
1.
The Persistent Identity (PID) of the service.
Reference the Configurations field in the Web console. The name is shown in brackets after the
bundle name (or in the Configuration Information towards the bottom of the page).
For example, create a node com.day.cq.wcm.core.impl.VersionManagerImpl. to configure AEM WCM
Version Manager.
2.
Whether a specific run mode is required. Create the folder:
• config - for all run modes
• config.author - for the author environment
• config.publish - for the publish environment
• config.<run-mode> - as appropriate
Whether a Configuration or Factory Configuration is necessary.
The individual parameters to be configured; including any existing parameter definitions that will need
to be recreated.
Reference the individual parameter field in the Web console. The name is shown in brackets for each
parameter.
For example, create a property versionmanager.createVersionOnActivation to configure Create
Version on Activation.
3.
4.
5.
Does a configuration already exist in /libs? To list all configurations in your instance, use the Query tool
in CRXDE Lite to submit the following SQL query:
select * from sling:OsgiConfig
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 3
Created on 2015-03-01
Configuring OSGi
If so, this configuration can be copied to /apps/<yourProject>/, then customized in the new location.
Creating the Configuration in the Repository
To actually add the new configuration to the repository:
1.
2.
3.
Use CRXDE Lite to navigate to:
/apps/<yourProject>
If not already existing, create the config folder (sling:Folder):
• config - applicable to all run modes
• config.<run-mode> - specific to a particular run mode
Under this folder create a node:
• Type: sling:OsgiConfig
• Name: the persistent identity (PID);
for example for AEM WCM Version Manager use com.day.cq.wcm.core.impl.VersionManagerImpl
NOTE
4.
5.
When making a Factory Configuration append -<identifier> to the name.
As in: org.apache.sling.commons.log.LogManager.factory.config-<identifier>
Where <identifier> is replaced by free text that you (must) enter to identify the instance
(you cannot omit this information); for example:
org.apache.sling.commons.log.LogManager.factory.config-MINE
For each parameter that you want to configure, create a property on this node:
• Name: the parameter name as shown in the Web console; the name is shown in brackets
at the end of the field description. For example, for Create Version on Activation use
versionmanager.createVersionOnActivation
• Type: as appropriate.
• Value: as required.
You only need to create properties for the parameters that you want to configure, others will still take
the default values as set by AEM.
Save all changes.
Changes are applied as soon as the node is updated by restarting the service (as with changes made
in the Web console).
CAUTION
You must not change anything in the /libs path.
CAUTION
The full path of a configuration must be correct for it to be read at startup.
Configuration Details
RESOLUTION ORDER AT STARTUP
The following order of precedence is used:
1. Repository nodes under /apps/*/config....either with type sling:OsgiConfig or property files (CHECK)
2. Repository nodes with type sling:OsgiConfig under /libs/*/config.... (ootb defns)
3. Any .config files from <cq-installation-dir>/crx-quickstart/launchpad/config/.... on the local file system.
This means that a generic configuration in /libs can be masked by a project specific configuration in /apps.
RESOLUTION ORDER AT RUNTIME
Configuration changes made while the system is running trigger a reload with the modified configuration.
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 4
Created on 2015-03-01
Configuring OSGi
Then the following order of precedence applies:
1. Modifying a configuration in the Web console will take immediate effect as it takes precedence at
runtime.
2. Modifying a configuration in /apps will take immediate effect.
3. Modifying a configuration in /libs will take immediate effect, unless it is masked by a configuration in /
apps.
STANDARD CONFIGURATIONS
The following list shows a small selection of the configurations available (in a standard installation) in the
repository:
•
•
•
Author - AEM WCM Filter:
libs/wcm/core/config.author/com.day.cq.wcm.core.WCMRequestFilter
Publish - AEM WCM Filter:
libs/wcm/core/config.publish/com.day.cq.wcm.core.WCMRequestFilter
Publish - AEM WCM Page Statistics:
libs/wcm/core/config.publish/com.day.cq.wcm.core.stats.PageViewStatistics
NOTE
As these configurations reside in /libs they must not be edited directly, but copied to your
application area (/apps) before customization.
To list all configurations in your instance, use the Query functionality in CRXDE Lite to submit the following
SQL query:
select * from sling:OsgiConfig
CONFIGURATION PERSISTENCE
•
If you change a configuration through the Web console, it is (usually) written into the repository at:
/apps/{somewhere}
• By default {somewhere} is system/config so the configuration is written to
/apps/system/config
• However, if you are editing a configuration which initially came from elsewhere in the repository: for
example:
/libs/foo/config/someconfig
Then the updated configuration is written under the original location; for example:
/apps/foo/config/someconfig
•
Settings that are changed by admin are saved in *.config files under:
/crx-quickstart/launchpad/config
• This is the private data area of the OSGi configuration admin and holds all configuration details
specified by admin, regardless how they entered the system.
• This is an implementation detail and you must never edit this directory directly.
• However, it is useful to know the location of these configuration files so that copies can be taken for
backup and/or multiple installation:
• Apache Felix OSGi Management Console
../crx/org/apache/felix/webconsole/internal/servlet/OsgiManager.config
• CRX Sling Client Repository
../com/day/crx/sling/client/impl/CRXSlingClientRepository/<pid-nr>.config
CAUTION
You must never edit the folders or files under:
/crx-quickstart/launchpad/config
© 2012 Adobe Systems Incorporated.
All rights reserved.
Page 5
Created on 2015-03-01