Vous êtes sur la page 1sur 206

Adobe CQ™5.

6
System Administration
Student Exercise Workbook

ADOBE TRAINING SERVICES


Table of Contents

Install & Start an Author Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

ADOBE COPYRIGHT PROTECTED


Exercise 1.1- Install CQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
What is an Author instance? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Start the Author Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Graphical Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Command Line Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Once CQ has started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Start and Stop CQ5 Using Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

Edit a Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1


To Edit a Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Browse Related Application/Server Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 3-1


Exercise 3.1- Browse User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
How to browse the CRX interface? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
How to use the Adobe Web Console? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
How to use CRXDE Lite? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

Create & Download a CQ Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1


Why do I need CRX content packages? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
To create, build, and download a CRX package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Automating Package Manager with cURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1


Using cURL to automate content package management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Configuring OSGi Bundles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1


EXERCISE 6.1 - Configuring OSGi Bundles: The Version Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Setting Run modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Configurations per run mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Configurations for Different Run modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Additional Information on Run modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8

Set up Replication Agents; Two Publish Instances . . . . . . . . . . . . . . . . . . . . . 7-1


Exercise 7.1- Setup replication agent for two publish instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Installing Two Publish Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Publish instances folder structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Replication agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
How do I access and configure Replication Agents? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Settings Tab Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5

ii | ii CQ 5.6 System Administration Training


Transport Tab Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
Proxy Tab Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Extended Tab Configuration Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
Triggers Tab Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
How to Monitor Replication Agents? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12

Activate a Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1


Excersise 8.1 Activate a Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Add a Reverse Replication Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1


Excersise 9.1 Add reverse replication agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1
Access the Author Agent’s settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Test Reverse Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3

ADOBE COPYRIGHT PROTECTED


Add the Dispatcher to the IIS WebServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Excersise 10.1-How does the Dispatcher plug in to IIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2

Add the Dispatcher to the Apache WebServer . . . . . . . . . . . . . . . . . . . . . . . 11-1


How does the Dispatcher plug in to Apache? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2

Configure the Dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1


Configuring the “dispatcher.any” file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
To Configure the Dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Complete the Dispatcher configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10
Configuring the Dispatcher Flush Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-13

Optimize the TarJournal PM on Author Instance . . . . . . . . . . . . . . . . . . . . . 13-1


Exercise 13.1- Optimize the TarJournal PM on Author Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Manually optimizing journaled tar pm files using CRX Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Automatically optimizing tar files using workspace.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2

Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
CRX Online Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Target Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Backing up to the default Target Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Backing up to a non-default Target Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Backing up a Shared Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Backing up a Large Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Using JMX (Java Management Extensions) and the MBeans provided by CRX . . . . . . . . . . . . . . . 14-9

Using cURL for Automated Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1


Exercise 15.1 - Automated backup using cURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1

Cluster Two CQ Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1


Clustering Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Exercise 16.1-Cluster Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3

CQ 5.6 System Administration Training  | iii


Manual Cluster Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Steps for Manual Slave Cloning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-5
Testing the Clustering Instance via Content Page modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-8
Verifying the Repository configuration via CRX’s GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-10

Creating Custom Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1


Exercise 17.2- Create a custom Log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Create the Logging Logger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Create the Logging Writer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4
Using custom runmodes with Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6
Create a CRX Logger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-9

User Administration and Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1

ADOBE COPYRIGHT PROTECTED


Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Accessing User Administration with the Security Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
To create a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4
Managing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4
Manage Access Rights for different Websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Manage Access Rights for Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6
Manage replication privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-7
Deny access rights to consoles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-8
To create a new user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-9
Adding a User and a Group to a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-11
Switching to somebody else’s identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-12
Deleting Users or Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-13
Permissions and ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-14
Access Control Lists and how they are evaluated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-16
Concurrent permission on ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-18

Integrating with LDAP and Enabling Single Sign On . . . . . . . . . . . . . . . . . . 19-1


EXERCISE 19.1 – Installing a local LDAP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
LDAP Installation instructions for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
LDAP Installation instructions for MAC OS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
EXERCISE 19.2 - Setting up/configuring the LDAP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
Configuring CQ5 for LDAP Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-8
EXERCISE 19.3 – Configure CQ to integrate with LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-9
Configure repository.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-9
Configure ldap_login.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-10
EXERCISE 19.4 - Assigning Rights to Users imported from LDAP into CRX . . . . . . . . . . 19-12
EXERCISE 19.5 – Purge User007 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-13
EXERCISE 19.6 – Synchonize the CRX with LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-15
Check your ldap_login.conf file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-18
Make sure your ldap_login.conf file is used by the AEM or CRX instance. . . . . . . . . . . . . . . . . . . . 19-18
Increase the log level of the LDAP module to DEBUG and look for messages in crx/error.log 19-18
Set up proxy logging between CRX/AEM and LDAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-19
Extra Credit Exercise 19.7- Configuring LDAP over SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-20
Configuring SSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Service Ranking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Header Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Cookie Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Parameter Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
User Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Removing AEM Sign Out Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-23

iv | iv CQ 5.6 System Administration Training


Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1
Exercise 20.1-Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1
Author Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Publish Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Performance Optimization Methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Planning for Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Stay Relevant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3
Agile Iteration Cycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3
Basic Performance Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-4
To monitor Page response times: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-4
To monitor Component based timing: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-6
To find long lasting requests/responses: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7
To view timing statistics for Page rendering: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-9

ADOBE COPYRIGHT PROTECTED


Find Unclosed JCR Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1
Exercise 21.1-Finding Unclosed Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1

Security Checklists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1


CRX Security Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1
Installation Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1
Issues with Cross-Site Request Forgery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2
CQ Security Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Exercise 22.1-Disable WebDAV & Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Disable Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5

Configuring the CQ 5.5 Dispatcher on MacOS X . . . . . . . . . . . . . . . . . . . . . . . A-1

Installing the Dispatcher module into Apache . . . . . . . . . . . . . . . . . . . . . . . . A-2

Configuring httpd.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4

Update the publish instance port number on the dispatcher.any file . . . . A-5

CQ 5.6 System Administration Training  | v


ADOBE COPYRIGHT PROTECTED
Adobe System Administration Training Student Exercise Workbook
Version CQ56120131129

©1996-2013. Adobe Systems Incorporated. All rights reserved. Adobe, the Adobe logo, Omniture, Adobe
SiteCatalyst and other Adobe product names are either registered trademarks or trademarks of Adobe
Systems Incorporated in the United States and/or other countries.

All rights reserved. No part of this work may be reproduced, transcribed or used in any form or by any
means—graphic, photocopying, recording, taping, Web distribution or information storage and retrieval
systems—without the prior and express written permission of the publisher.

Disclaimer

Adobe reserves the right to revise this publication from time to time, changing content without notice.

vi CQ 5.6 System Administration Training


01
Install & Start an Author Instance

ADOBE COPYRIGHT PROTECTED


Exercise 1.1- Install CQ
Goal

The following instructions explain how to install and start an Author instance. This is important
because you will use this Author instance throughout this training to perform typical development
tasks. To successfully complete and understand these instructions, you will need:

• A CQ5 installation and startup JAR file (contained on the USB stick)
• A valid CQ5 license key “properties” file (contained on the USB stick)
• A JDK version 1.5 or later
• Approximately 800 MB of free space
• Approximately 1 GB of RAM

NOTE: The CQ5 installation and startup JAR file is also known as “quickstart” file. It is used for
both, installing CQ5 and, once CQ5 is installed, as CQ5 startup file. You will notice during
installation that the JAR file will create a root folder called “crx-quickstart”.

CQ 5.6 System Administrator Training Student Workbook Chapter-01 | 1-1


What is an Author instance?

There are two types of CQ instances, a “Publish” instance is the slick and fast performing instance
used by the Internet world and the “Author” instance, which typically resides behind a firewall and
is used by content contributors (aka “Authors”) to build and manage the Web site and its content.
The “Author” instance is managed by a user-friendly GUI. Content authors will login to the in-
stance and use it to manage pages. This includes creating, editing, deleting, moving, etc. In
addition, the author instance is the installation, developers will be developing against, as you can
easily observe both Author and Publish views.

ADOBE COPYRIGHT PROTECTED


How to install an Author instance?

1. Windows: Create a folder structure on your file system where you will store, install, and start
CQ5:
a. C:/adobe/cq5/author
2. MacOS or *x: Create the following structure commonly used for application installations:
a. /opt/adobe/cq5/author
OR
b. /Applications/cq5/author
3. Copy the CQ5 quickstart JAR and license.properties file from <USB>/distribution/cq5_wcm into
the newly created folder structure.

CQ5 author install folder structure

Rename the CQ5 quickstart JAR to cq5-author-4502.jar.


• cq5 = the application
• -author = the WCM mode it will run in (e.g. author or publish)
• -4502 = the port it will run in (e.g. any available port is acceptable)

NOTE: The reason we usually rename the CQ5 “quickstart” file is for installation purposes.
When running for the first time, the quickstart file will notice that it has to install CQ5. By
renaming the file, we use a convention of passing instance name (Webpathcontext) and port
number via file name, so that no user interaction is needed during the installation process.

1-2 | Chapter-01 CQ 5.6 System Administrator Training Student Workbook


If no port number is provided in the file name, CQ5 will select the first available port from the
following list: 1) 4502, 2) 8080, 3) 8081, 4) 8082, 5) 8083, 6) 8084, 7) 8085, 8) 8888, 9) 9362,
10) random.

Start the Author Instance

There are two ways of installing the CQ5: graphical and by command line. The latter is more
powerful since the user has the possibility to provide additional performance-tuning parameters to
the JVM. Please read the section corresponding to your desired installation method.

ADOBE COPYRIGHT PROTECTED


Graphical Start

In a Windows or Mac OS environment, you can simply double-click the cq5-author-4502.jar file.

• Installation will take approximately 3-5 minutes, depending on your system’s capabilities

• A dialog will pop-up similar to the one below


CQ5 install/startup dialog

Continue reading the section “CQ5 Servlet Engine is started”, following the “Command Line
start” section.

Command Line Start

First of all, you may want to know which parameters are available to configure the CQ5 Servlet
Engine (CQSE) prior to running the installation. Therefore, enter the following command to display a
complete list of optional parameters :

• java -jar cq5-author-4502.jar -h

CQ 5.6 System Administrator Training Student Workbook Chapter-01 | 1-3


The CQ5 “quickstart” installer will show all available command line options without starting the
server.
The second thing you must know is that, you will need to tune the JVM used for running CQ5.
Tuning the JVM is a very important and delicate task and requires a more realistic environment in
terms of resources (hardware, operating system, etc.) and workload (content, requests, etc.). For
now, it will be enough to know that you can start your instance (either “author” or “publish”) using
the following parameters:

-Xms --> assigns the initial heap size

Default value 64MB for a JVM running on 32bit machines, or 83MB for 64bit

ADOBE COPYRIGHT PROTECTED


machines
Recommended Specific to physical memory available and expected traffic
Syntax -Xms512m (sets the initial heap size to 512MB)

-Xmx --> assigns the maximum size the heap can grow

Default value 64MB for a JVM running on 32bit machines, or 83MB for 64bit
machines
Recommended Specific to physical memory available and expected traffic, but should
be equal or greater than the initial size. To run CQ5 it’s recommended to
allocate at least 1024MB of heap size.
Syntax -Xmx1024m (sets the maximum size the heap can, in the example we
are letting it grow to 1024MB; however, in production this should be a
higher since CQ5 does consume a lot of resources on this aspect)

-XX:MaxPermSize --> assigns the heap to hold reflective data of the VM


(e.g. Java objects)

Default value 32MB for a JVM running as a client, or 64MB when running as a server
Recommended The “PermSize” should be set to at least 128MB for “normal sized”
Web apps or 256MB for larger Web apps with significant Java activity.
Syntax -XX:MaxPermSize=128m (sets the initial perm gen size to 128MB)

You can now install/start CQ5 from the command line together with increasing the Java heap and
perm gen size, which will improve performance. Please see image below for an example of the
command line.

CQ5 command line start

1-4 | Chapter-01 CQ 5.6 System Administrator Training Student Workbook


For our training, you can start the CQ5 installation process as follows:

• java -XX:MaxPermSize=128m -Xmx1024M -jar cq5-author-4502.jar

NOTE: You can also add the parameter -gui to the end of the command line to provide a
graphical interface which displays the current installation step / status and an on/off button to
easily stop the application like described in the previous section.

You can control the way CQ5 gets installed by using defining properties via file name. The following
file name patterns can be used for the CQ5 “quickstart” JAR file:

ADOBE COPYRIGHT PROTECTED


Optionally, CQ5 can be installed in a third-party application server. The online documentation
under http://dev.day.com/content/docs/en/cq/current/howto/install_application_server.html explains
these steps in more detail.

For more in-depth information regarding the installation process, please visit,
http://dev.day.com/docs/en/cq/current/getting_started/download_and_startworking.html

Once CQ has started

Once CQ has started, your default browser will be automatically opened, pointing to CQ5’s start
URL (where the port number is the one you defined on installation) : http://localhost:4502/ . In case
you already opened the browser, you have to enter the URL manually.

CQ 5.6 System Administrator Training Student Workbook Chapter-01 | 1-5


In the appearing Login screen, enter the default administrator’s credentials (admin/admin), and then
click Sign In.

ADOBE COPYRIGHT PROTECTED


CQ5 login dialog

The Welcome screen appears, displaying the different possibilities to continue. For the next
exercise, we’ll access the Websites console.

CQ5 Welcome Screen

Start and Stop CQ5 Using Scripts

During the installation process, some scripts were extracted in the directory <cq5_install_dir>/
crx-quickstart/bin. Use them to simplify the future startup of CQ5 instance(s). The next table
shows different scripts, which can be used from the appropriate operating system.

1-6 | Chapter-01 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
Learn more about the fine-tuning options accepted by the different scripts by looking at the top part
of the scripts in a text editor.

Congratulations! You have successfully installed and started CQ5.

CQ 5.6 System Administrator Training Student Workbook Chapter-01 | 1-7


02
Edit a Page

ADOBE COPYRIGHT PROTECTED


Goal

The following instructions explain how to use the CQ5 Author Console to load and edit a page. This
is important because, you will use the Web site’s Administrator Console to create and publish
content throughout the course. In addition, you should understand the interfaces used by your
author community.

To successfully complete and understand these instructions, you will need:

• A running CQ5 author instance

What are the available Author (sub-)?

CQ5 uses a web-based graphical user interface; so all you need is a web browser to access the CQ5
console. The graphical user interface is divided into various web-based sub-consoles, where you
can access all of the CQ functionality:

CQ 5.6 System Administrator Training Student Workbook Chapter 02 | 2-1


ADOBE COPYRIGHT PROTECTED
To Edit a Page

Websites Administrator Console

1. Navigate to http://localhost:4502/libs/wcm/core/content/siteadmin.html . This will take you to


the classic Websites Console, where authors manage their content.

2-2 | Chapter 02 CQ 5.6 System Administrator Training Student Workbook


2. In the Navigation pane (left side tree), navigate to the page Geometrixx Demo Site > English >
Company > News.

3. Open the Articles page. You can open a page to be edited by one of several methods:

• From the Websites tab, you can double-click the page title to open it for editing.

• From the Detail pane (right side table), you can right-click the page item, then select Open
from the context menu.

After you have opened a page, you can navigate to other pages within the site to edit them by clicking
the links.

ADOBE COPYRIGHT PROTECTED


Page in Edit Mode

After you open the page, you can start to add content. You do this by adding new paragraphs or
editing existing paragraphs (also known as “Components”).

To insert a new paragraph, double-click the area labeled Drag components or assets here or drag a
component from the floating toolbar (called “Sidekick”) to insert a new paragraph. This area ap-
pears wherever new content can be added, such as at the end of a list of other previously added
paragraphs or at the end of a column.

4. Drag the “Text & Image” icon from the Sidekick pane to the center of the dotted rectangle with
the water-mark text “Drag components or assets here”. The green check mark will indicate
that the drag-and-drop is allowed.

CQ 5.6 System Administrator Training Student Workbook Chapter 02 | 2-3


ADOBE COPYRIGHT PROTECTED
The Web page with the list of available Components in “Sidekick”

5. Double-click the thumbnail placeholder for the component to open the Dialog box.

The Dialog to enter content

2-4 | Chapter 02 CQ 5.6 System Administrator Training Student Workbook


6. Click the Image tab to open the Image pane of the dialog box. Drag-and-drop an image from
the Content Finder (on the left side) to the dialog box.

ADOBE COPYRIGHT PROTECTED


7. Click the Text tab. Enter some text.

Dialog “Text” tab with a WYSIWYG, MS Word-like Editor

CQ 5.6 System Administrator Training Student Workbook Chapter 02 | 2-5


8. Click OK to save the content.

ADOBE COPYRIGHT PROTECTED


The Web page with fresh content

9. Check out the Result.

Congratulations! You have successfully edited a CQ5 page.

2-6 | Chapter 02 CQ 5.6 System Administrator Training Student Workbook


03
Browse Related Application/

ADOBE COPYRIGHT PROTECTED


Server Interfaces

Exercise 3.1- Browse User Interface


Goal

The following instructions explain how to browse the application/server interfaces associated with a
CQ5 installation. This will enable you to use their administrative/configuration capabilities. To
successfully complete and understand these instructions, you will need:

• A running CQ5 Author instance

What interfaces exist?

A typical CQ5 installation consists of a Java Content Repository (CRX) and a Launchpad (Apache
Felix/Apache Sling) application. They each have their own Web interface allowing you to perform
expected administrative/configuration tasks.

How to browse the CRX interface?

1. Enter the URL http://localhost:4502/crx/explorer in your favorite Web browser’s address bar.

CQ 5.6 System Administrator Training Student Workbook Chapter 03 | 3-1


CRX Web Interface

ADOBE COPYRIGHT PROTECTED


2. If you are logged in as “anonymous” user, you can only browse the repository. If you want to
be able to edit content, you would have to login as “admin” user. Click on “Log In” and enter
the default administrator’s credentials (admin/admin) , and then click Submit.

CRX login screen

NOTE: If you already had a CQ authenticated session started, you will be automatically logged in
into CRX, thus the above step may not be required.

3. Select Content Explorer in the Main Console — a new Web browser window will pop-up.

3-2 | Chapter 03 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
As you can see, CRX uses a “file system” like structure to manage content. You can navigate through
the different “nodes” (depicted as folders) to see their contents and manage them. You can apply
many actions such as create, copy, move, delete, and more.

4. Navigate to the “node” /content/geometrixx/en/company/news/articles. This is the page you


modified in the last exercise.

5. Navigate down to the jcr:content and then the par node. You will see all the nodes under par that
represent the paragraphs on the Articles page.

CQ 5.6 System Administrator Training Student Workbook Chapter 03 | 3-3


ADOBE COPYRIGHT PROTECTED

The second interface for interacting with the repository contents is CRXDE Lite. You can access the
CRXDE Lite interface at /localhost:4502/crx/de/.

Congratulations! You have successfully logged in to the Content Explorer; you have browsed a
portion of the node (Web site) structure, and looked over the contents of the repository.

How to use the Adobe Web Console?

1. Enter the URL http://localhost:4502/system/console in your favorite Web browser’s address


bar.

2. Enter the default administrator’s credentials (admin/admin) in the dialog, and then click OK. The
Adobe CQ5 Web Console appears, showing you the Bundles application.

3-4 | Chapter 03 CQ 5.6 System Administrator Training Student Workbook


Apache Felix login dialog

ADOBE COPYRIGHT PROTECTED


3. Click the OSGi drop-down menu and select Configuration.

Apache Sling “Recent requests”

CQ 5.6 System Administrator Training Student Workbook Chapter 03 | 3-5


4. Select the Day CQ Mail Service.

ADOBE COPYRIGHT PROTECTED


Congratulations! You have successfully logged in to the Adobe CQ5 Web Console. From the
Configuration Console, you can see which parts (bundles) of the CQ5 application can be configured.

How to use CRXDE Lite?

CRXDE Lite is a browser-based IDE, loosely based on “Eclipse”. The big difference between using
CRXDE Lite and a common IDE like “Eclipse” or “IntelliJ” is that files created are stored directly via
CRX. However, CRXDE on the other hand cannot check-in files into Subversion instance

1. Enter the URL http://localhost:4502/crx/de/ in your favorite Web browser’s address bar or
select the CRXDE Lite console from the CRX “Welcome” screen.

2. Make sure that you logged in as a user with “write” and “execute” privileges, e.g. like the
“admin” user.

3-6 | Chapter 03 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
The Web console of the IDE CRXDE Lite

3. Navigate to the folder /apps/geometrixx/components to view the custom components created


for the Geometrixx Web site/project.

CQ 5.6 System Administrator Training Student Workbook Chapter 03 | 3-7


ADOBE COPYRIGHT PROTECTED
Viewing the /components folder of the Geometrixx application

Congratulations! You have successfully logged in to CRXDE Lite and have browsed the custom com-
ponents created for the Geometrixx Web site/project. Again, CRXDE Lite is embedded into CQ5/CRX
and enables you to perform standard development tasks in a Web browser.

3-8 | Chapter 03 CQ 5.6 System Administrator Training Student Workbook


04

ADOBE COPYRIGHT PROTECTED


Create & Download a CQ
Package

GOAL

The following instructions explain how to create a CQ package that will combine all elements of the
training project, minus all jpegs. This is a good example of packaging application content, which you
could then distribute to team members for review. To successfully complete and understand these
instructions, you will need:

• A running CQ5 Author instance

• The completed training project with appropriate extensions

Why do I need CRX content packages?

Packages can include content and project-related data. A package is a zip file that contains the
content in the form of a file-system serialization (called filevault serialization) that represents the
content from the repository as an easy-to-use-and-edit representation of files and folders. Content
packages are a good way to, among other things, package application content, which you could then
distribute to team members for review.

CQ 5.6 System Administrator Training Student Workbook Chapter 04 | 4-1


You can perform the following actions with packages:

• Create new packages

• Modify existing packages

• Build packages

• Upload packages

• Install packages

• Download packages from the package share library

ADOBE COPYRIGHT PROTECTED


• Download packages from CQ to a local machine

• Apply package filters

• View package information

To create, build, and download a CRX package

1. Navigate to the classic Welcome Screen. Select Packages on the right pane.
http://localhost:4502/libs/cq/core/content/welcome.html

4-2 | Chapter 04 CQ 5.6 System Administrator Training Student Workbook


2. Click the Create Package button at the top.

ADOBE COPYRIGHT PROTECTED


CQ5 packages - create a new package

3. Enter the “Package Name” (training-project), the “Version” of your package (e.g. 1.0) and the
package “Group” (training) and click “OK”. So you don’t have to first create a folder for your
package, you can enter the folder name (e.g. training) into the “Group Name” field. You can also
create a folder structure by entering the folder path, .e.g., training/exercises

NOTE: The Group name is a folder name where your package will be stored; you can choose an
existing one or create a new one by providing a new name for the Group.

CQ new package dialog

CQ 5.6 System Administrator Training Student Workbook Chapter 04 | 4-3


4. Click the Edit button on the newly created package.

5. Select the Filters tab and click Add filter.

6. Enter the “Root Path” (/apps/geometrixx) and click “Add a Rule”. Define a rule that excludes all
jpg files (Exclude => .+\.jpg). Click Done, and then Save.

So you don’t have to first create a folder, you can enter the folder name (e.g. training) into the “Group
Name” field. You can also create a folder structure by entering .e.g training/exercises.

ADOBE COPYRIGHT PROTECTED


Filter definition dialog

4-4 | Chapter 04 CQ 5.6 System Administrator Training Student Workbook


7. Select Build to build the package.

ADOBE COPYRIGHT PROTECTED


Package build selection

Package build information

NOTE: A=Added Node, U=Updated Node, D=Deleted Node, and E=Error. Always check for
errors in the build process. Although errors are quite seldom, verify and fix them immediately,
since they could cause instability with CRX.

CQ 5.6 System Administrator Training Student Workbook Chapter 04 | 4-5


05

ADOBE COPYRIGHT PROTECTED


Automating Package Manager
with cURL

GOAL

An HTTP service interface is available and allows for managing packages using command-line
clients like “cURL” or “wget”, or automated scripts. In this way, you can automate content package
management through the use of scripts.

In this exercise, you will learn about the cURL syntax for content package management. To successfully
complete and understand these instructions, you will need:

• A running CQ5 Author instance

• Optional: cURL HTTP client (if necessary, you can download cURL from
http://curl.haxx.se/download.html)

Using cURL to automate content package management

The f ollowing Package Manager operations are currently supported from the command line:

• printing the help screen

• listing packages

CQ 5.6 System Administrator Training Student Workbook Chapter 05 | 5-1


• removing packages

• building packages

• installing packages

• uninstalling packages

• downloading packages

• uploading packages

• creating packages

ADOBE COPYRIGHT PROTECTED


• deleting packages

• performing a dryrun installation

• previewing packages

• listing package contents

• rewrapping packages

To trigger the above operations, send requests using the command line client to the CRX repository.
The response is sent back in XML format.

1. To get the help screen: Use the following command in a command line terminal window
(e.g. Putty):

curl -u admin:admin http://localhost:4502/crx/packmgr/service.jsp

You should get the following response:

5-2 | Chapter 05 CQ 5.6 System Administrator Training Student Workbook


<crx version=”2.3.15” user=”admin” workspace=”crx.default”>
<request>
</request>
<response>
<data>
+------------+-----------------------------------------+
| Arguments | Comment |
+------------+-----------------------------------------+
| cmd=help | print this help |
+------------+-----------------------------------------+
| cmd=ls | print a list of all packages |
+------------+-----------------------------------------+
| cmd=rm | remove a package |

ADOBE COPYRIGHT PROTECTED


| name | package name |
| [group] | group name (optional) |
+------------+-----------------------------------------+
| cmd=build | build a package |
| name | package name |
| [group] | group name (optional) |
+------------+-----------------------------------------+
| cmd=ins | installs a package |
| name | package name |
| [group] | group name (optional) |
+------------+-----------------------------------------+
| cmd=unins | uninstalls a package |
| name | package name |
| [group] | group name (optional) |
+------------+-----------------------------------------+
| GET | downloads a package. |
| | (content-disposition header contains |
| | the correct filename) |
| [cmd=get] | optional |
| name | package name |
| [group] | group name (optional) |
+------------+-----------------------------------------+
| POST | upload a new package |
| file | pacakge to upload |
| [name] | optional name |
| [install] | automatically install package if “true” |
+------------+-----------------------------------------+
</data>
<status code=”200”>ok</status>
</response>
</crx>

CQ 5.6 System Administrator Training Student Workbook Chapter 05 | 5-3


2. List the packages currently available on this CQ instance:

curl -u admin:admin http://localhost:4502/crx/packmgr/service.jsp?cmd=ls

You should get a response similar to the following:

<crx version=”2.3.15” user=”admin” workspace=”crx.default”>


<request>

ADOBE COPYRIGHT PROTECTED


<param name=”cmd” value=”ls”/>
</request>
<response>
<data>
<packages>
<package>
<group>adobe/granite</group>
<name>com.adobe.granite.backup.content</name>
<version>0.0.12</version>
<downloadName>com.adobe.granite.backup.content-0.0.12.zip</downloadName>
<size>34283</size>
<created>Fri, 3 Feb 2012 11:46:10 -0600</created>
<createdBy>Adobe Systems Incorporated</createdBy>
<lastModified></lastModified>
<lastModifiedBy>null</lastModifiedBy>
<lastUnpacked>Fri, 9 Mar 2012 15:30:09 -0600</lastUnpacked>
<lastUnpackedBy>admin</lastUnpackedBy>
</package>
<package>
.
.
.
.
</package>
</packages>
</data>
<status code=”200”>ok</status>
</response>
</crx>

5-4 | Chapter 05 CQ 5.6 System Administrator Training Student Workbook


3. Upload a package. You will find a sample package in the memory stick in /exercises/import_
package/training_import.zip.

curl -u admin:admin -F file=@training_import.zip http://localhost:4502/crx/packmgr/service.jsp

You should get a response similar to the following:

<crx version=“2.3.15” user=“admin” workspace=“crx.default”>


<request>

ADOBE COPYRIGHT PROTECTED


<param name=“file” value=“training_import.zip”/>
</request>
<response>
<data>
<package>
<group></group>
<name>training_import</name>
<version>1.0</version>
<downloadName>training_import-1.0.zip</downloadName>
<size>288342</size>
<created></created>
<createdBy>null</createdBy>
<lastModified>Thu, 26 Mar 2009 07:03:50 -0600</lastModified>
<lastModifiedBy>admin</lastModifiedBy>
<lastUnpacked></lastUnpacked>
<lastUnpackedBy>null</lastUnpackedBy>
</package>
</data>
<status code=“200”>ok</status>
</response>
</crx>

CQ 5.6 System Administrator Training Student Workbook Chapter 05 | 5-5


4. Install a package. Enter the following command to install the package you just uploaded.

curl -u admin:admin -F name=training_import http://localhost:4502/crx/packmgr/service.


jsp?cmd=inst

You should get a response similar to the following:

<crx version=“2.3.15” user=“admin” workspace=“crx.default”>


<request>
<param name=“cmd” value=”inst”/>
<param name=“name” value=”training_import”/>
</request>

ADOBE COPYRIGHT PROTECTED


<response>
<data>
<log>
Installing content...
Creating snapshot for package :training_import:1.0
A META-INF
A META-INF/vault
A META-INF/vault/config.xml
A META-INF/vault/filter.xml
A META-INF/vault/nodetypes.cnd
A META-INF/vault/properties.xml
A /.content.xml
A /content
A /content/.content.xml
A /content/dam

...

A/content/dam/photos/people.jpg/jcr:content/renditions/cq5dam.thumbnail.48.48.png/
jcr:content/jcr:data
A/content/dam/photos/people.jpg/jcr:content/renditions/cq5dam.thumbnail.140.100.png
A/content/dam/photos/people.jpg/jcr:content/renditions/cq5dam.thumbnail.140.100.png/
jcr:content
A/content/dam/photos/people.jpg/jcr:content/renditions/cq5dam.thumbnail.140.100.png/
jcr:content/jcr:data
saving approx 71 nodes...
Package imported.
Package installed in 971ms.
</log>
</data>
<status code=“200”>ok</status>
</response>
</crx>

5-6 | Chapter 05 CQ 5.6 System Administrator Training Student Workbook


5. Remove a package. Enter the following command

curl -u admin:admin -F name=training_import http://localhost:4502/crx/packmgr/service.


jsp?cmd=rm

You should get a response similar to the following:

<crx version=“2.3.15” user=“admin” workspace=“crx.default”>


<request>
<param name=“cmd” value=“rm”/>

ADOBE COPYRIGHT PROTECTED


<param name=“name” value=“training_import”/>
</request>
<response>
<status code=“200”>ok</status>
</response>
</crx>

Congratulations! You have successfully automated uploading, installing, and removing content
package. Please refer the documentation for more information on building, uninstalling, and other
cURL commands supported by the Package Manager.

CQ 5.6 System Administrator Training Student Workbook Chapter 05 | 5-7


06

ADOBE COPYRIGHT PROTECTED


Configuring OSGi Bundles

As a best practice, Adobe recommends that OSGi bundles be configured by defining nodes in the
repository. This allows you to easily deploy the application configurations to multiple environments
by placing these nodes in CRX content packages.

at a basic level, this can just be a case of moving a CRX content package to a new environment,
uploading it to the repository, and importing its contents. Alternatively, the package can be activated
using the tools section of the CQ5 Admin Console. However some consideration should be given to
managing this process, to ensure that your applications can be deployed efficiently and without any
problems.

Considerations for deploying applications to other environments

• Make sure your application code is separate from the configuration, as you may need
to use different configurations with the same application for different environments.
Creating separate packages makes it easy to deploy the appropriate configuration for each
environment.

• Make sure your application code does not depend on specific content, as this may not be
present in all environments.

• Code packages will be created in the development environment, and will then travel from
development, to test, and then to production. Content will generally travel from production,
to test, and then to development to be used as test content; so separate packages and
processes may be needed.

CQ 5.6 System Administrator Training Student Workbook Chapter 06 | 6-1


There are two approaches that can be taken when creating packages for deployment, so that the
configuration information can be configured separately from the application code.

Packaging Style 1

Deploy 2 packages:

• One with the application code.

• One with the environment-specific configuration for development/test/production.

Packaging Style 2

ADOBE COPYRIGHT PROTECTED


Deploy one package with the configuration for all relevant environments together with the application
code. With this packaging option, you use different runmodes to select the correct configuration for
the desired environment.

EXERCISE 6.1 - Configuring OSGi Bundles: The Version Manager

1. Navigate to the Adobe CQ5 Web Console. http://localhost:4502/system/console

2. Click the OSGi drop-down menu and select Configuration.

6-2 | Chapter 06 CQ 5.6 System Administrator Training Student Workbook


3. Select the Day CQ WCM Version Manager.

ADOBE COPYRIGHT PROTECTED


Although Adobe does not recommend that you use this console to configure bundles, you can find
the information you need to enter the configuration information into the repository.

Notice the Persistent Identity (PID) -

com.day.cq.wcm.core.impl.VersionManagerImpl.

this will become the name of the node that you create in the repository.

Notice the configurable items, e.g., Enable Purging (versionmanager.purgingEnabled). The items in
the parentheses are the configurable property names.

4. Open CRXDE Lite – http://localhost:4502/crx/de/

5. Right click on /apps/geometrixx.

6. Click Create->Create Node. Create a node of type sling:Folder, named config.author. Save All.

7. Right click on the new folder you just created and choose Create.. Create Node. Create a node of
type sling:OsgiConfig, named com.day.cq.wcm.core.impl.VersionManagerImpl —the PID of the
Version Manager, and Save.

CQ 5.6 System Administrator Training Student Workbook Chapter 06 | 6-3


ADOBE COPYRIGHT PROTECTED
Creating properties in the repository, using CRXDE Lite, is done by adding the property information
in the input fields at the bottom of the screen, and then clicking “Add”. Don’t forget to Save.

6-4 | Chapter 06 CQ 5.6 System Administrator Training Student Workbook


8. Add the following properties to the node you just created:

• Create Version on Activation

o Name: versionmanager.createVersionOnActivation
o Type: Boolean
o Value: true

• Enable Purging

o Name: versionmanager.purgingEnabled
o Type: Boolean
o Value: true

ADOBE COPYRIGHT PROTECTED


• Purge Paths

o Name: versionmanager.purgePaths
o Type: String
o Value: /content

• Implicit Versioning paths

o Name: versionmanager.ivPaths
o Type: String
o Value: /

• Max Version Age

o Name: versionmanager.maxAgeDays
o Type: String
o Value: 30

• Max Number Versions

o Name: versionmanager.maxNumberVersions
o Type: String
o Value: 3

CQ 5.6 System Administrator Training Student Workbook Chapter 06 | 6-5


ADOBE COPYRIGHT PROTECTED
9. Click Save.

10. Test your configuration by opening a page in the Geometrixx website and saving a number of
versions.

6-6 | Chapter 06 CQ 5.6 System Administrator Training Student Workbook


Run modes
CQ has built-in author or publish run modes (Do not remove these). You can add additional custom
run modes if required. For example, you can configure run modes for:

• Environment: local, dev, test, prod

• Location: Berlin, Basel, Timbuktu

• Company: acme, partner, customer

• Special system type: importer

ADOBE COPYRIGHT PROTECTED


Setting Run modes
It is possible to define specific run-mode(s), a specific instance should run on. By default, an author
instance runs on run-mode author and a publish instance runs on run-mode publish. It is possible to
define several run modes for one instance, for example, author, foo, and dev. These run-modes have
to be set as VM options. For example, from the command line:

java -Dsling.run.modes=author,foo,dev -Xmx1024m -jar cq-quickstart-5.6.0.jar

or in the start script:

# default JVM options


CQ_JVM_ OPTS=”-Dsling.run.modes=author,foo,dev”

or by adding entries to the crx-quickstart/conf/sling.properties file, for example:

sling.run.modes=author,dev,berlin

Configurations per run mode


To create separate configuration settings per run mode, Create folder names in the form

config.<runmode> are used, e.g. “config.publish”:


/apps/myapp/config.publish

For systems with run modes publish and berlin:

/apps/myapp/config.publish.berlin

CQ 5.6 System Administrator Training Student Workbook Chapter 06 | 6-7


Configurations for Different Run modes
Some examples of configuration settings that may be needed for different run modes:

Different mailserver configurations per location:

config.basel/com.day.cq.mailer.DefaultMailService

config.berlin/com.day.cq.mailer.DefaultMailService

En-/Disabling debugging per environment:

ADOBE COPYRIGHT PROTECTED


config.prod/com.day.cq.wcm.core.impl.WCMDebugFilter

config.dev/com.day.cq.wcm.core.impl.WCMDebugFilter

Additional Information on Run modes


When using different configurations for separate run modes, the following apply:

• Partial configurations are not supported.

• The configuration with the most matching run modes wins.

To avoid unexpected results:

• Always set all properties to avoid confusion.

• Use a type indicator (e.g. {Boolean}, {String}, etc.) in every property.

6-8 | Chapter 06 CQ 5.6 System Administrator Training Student Workbook


07

ADOBE COPYRIGHT PROTECTED


Set up Replication Agents;
Two Publish Instances

Exercise 7.1- Setup replication agent for two publish instance


Goal

Configure Replication Agents so that they replicate/activate content to Publish instances. Content
replication allows administrators to specify subsets of content, usually in author instances, Which will
be automatically replicated to other repositories, mainly publish instances, elsewhere in a distributed
environment. Replication can also take place when content entered by site visitors in publish
instances has to be replicated into author instances. This is important, because Replication agents are
central to CQ as the mechanism used to:

• Publish (activate) content from an author to a publish environment

• Explicitly flush content from the Dispatcher cache

• Return user input (for example, form input) from the publish environment to the author
environment (under the control of the author environment)
A replication agent is a distinct point-to-point connection between a start point (current instance)
and a specified target instance (usually a Publish instance). You’ll need to specify in your environment
as many Replication Agents as target instances you want to address. You need to create an agent
because content replication has a clearly defined goal (as opposed to discrete tasks) and requires no
continuous direct supervision or control.

CQ 5.6 System Administrator Training Student Workbook Chapter 07 | 7-1


NOTE: Technically, a replication means copying “content” from one repository to the
other. But it’s not like copying files. It’s the typical repository approach with editing nodes
and letting the persistence managers store the content. A replication has a user assigned (to
define the access rights) and replicates to a user on the receiving instance.

The following instructions explain how to create and configure Replication Agents. To successfully
complete and understand these instructions, you will need:
■■ A running CQ5 Author instance

Installing Two Publish Instances

ADOBE COPYRIGHT PROTECTED


To set up a publish instance on port 4503 of the desired host, you perform the same steps as in
installing an author instance except that you create a directory named publish (instead of author) and
you rename the cq5-quickstart-5.5.0.jar file as cq5-publish-4503.jar. You can select any port number.

For our test environment, we will install an additional Publish instance. It will run on port 4505.
Follow the same steps as described above or in Exercise 1 in chapter-1(Installation) to setup a second
Publish instance. It is a common convention to use even port numbers for author instances and odd
port numbers for publish instances.

Publish instances folder structure

1. Windows: Create a folder structure on your file system where you will store, install, and start
CQ5:

a. C:/adobe/cq5/publish/cq5-publish-4503.jar

b. C:/adobe/cq5/publish2/cq5-publish-4505.jar

2. MacOS or *x: Create the following structure commonly used for application installations:

a. /opt/adobe/cq5/publish1/cq5-publish-4503

b. /opt/adobe/cq5/publish2/cq5-publish-4505
OR

c. /Applications/cq5/ publish1/cq5-publish-4503

d. /Applications/cq5/ publish2/cq5-publish-4505

7-2 | Chapter 07 CQ 5.6 System Administrator Training Student Workbook


NOTE: The port number for publish one is the default one which is already set up with the first
replication agent, port number 4503. The second publish instance (publish2) should run
on port 4505. Thus jar files should be named appropriately. If using the startup scripts under
“<installation>/crx-quickstart/bin” update the CQ_PORT and CQ_RUNMODE variables
accordingly.

Replication agents

ADOBE COPYRIGHT PROTECTED


Diagram to illustrate the activation of content from author to publish instances

Replication to a publish instance takes place in several steps:

• The author requires that certain content be published (activated).


This can be initiated by a manual request (when an author user checks the “activate”
button for a page in the CQ SiteAdmin console), or can be initiated automatically by
triggers which have been previously preconfigured as instructed in this exercise.

• The request is passed to any appropriate replication agent.


An environment can have several replication agents. All available and enabled replication
agents will be selected for replication requests.

• The replication agent (in the author instance) “packages” the content and moves it to a
replication queue for further processing (the actual replication).

• After a successful replication the colored status indicator next to the Web pages in the
SiteAdmin console (Websites tab) is set to “green” (“orange” = in process, “red” =
deactivated). This way the author sees at any given time which pages have been replicated.

• The replication queue is processed and the content is copied to the “other” instance
(typically the publish instance) using one of the configurable protocols. Typically, the
replication happens using the HTTP protocol.

CQ 5.6 System Administrator Training Student Workbook Chapter 07 | 7-3


• A servlet running on the receiving (usually publish) instance receives the request and copies
the received content to the exact same location as indicated in the content package.

• First, the receiving servlet creates a new version of the existing content (can be disabled),
then replaces the content elements with the received ones.

How do I access and configure Replication Agents?

1. Access the classic Tools Console at http://localhost:4502/miscadmin ,or by clicking on the Tools
button at the top of the classic Websites Console, or by clicking the Tools button on the classic

ADOBE COPYRIGHT PROTECTED


Welcome Screen.

2. Click Replication (left pane, to open the folder).

3. Double-click Agents on author (either the left or from the right side link).

4. Click the Default Agent (which is a link) to show detailed information on that agent.

5. Click Edit to open the configuration dialog:

7-4 | Chapter 07 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
The Replication Agent configuration Dialog

Settings Tab Configuration Parameters


• Name: A unique name for the replication agent.

• Description: A description of the purpose this replication agent will serve.

• Enabled: Indicates whether the replication agent is currently enabled or disabled.

Serialization Type: The type of serialization:

• Default: Set if agent is to be automatically selected.


• Dispatcher Flush: Select if agent is to be used for flushing the Web server (“Dispatcher
managed”) cache.

Retry Delay: The delay (waiting time in milliseconds) between two retries, should a problem be
encountered.

• Default: 60000

Agent User Id: The agent will use this user account to collect and package the content from the
author environment. Leave this field empty to use the system user account (the account defined in
Apache Sling as the “administrator user”; by default this is “admin”).

CQ 5.6 System Administrator Training Student Workbook Chapter 07 | 7-5


WARNING: This account must have read access to all paths which will be replicated. In
addition, you will want to create a new user for replication purposes and not dispose the
“admin” user for replication.

• Log Level: Specifies the level of detail to be used for log messages:

• Error: only errors will be logged


• Info: errors, warnings, and other informational messages will be logged
• Debug: a high level of detail will be used in the messages, primarily for debug purposes
• Default: Info

ADOBE COPYRIGHT PROTECTED


• Use for Reverse Replication: Indicates whether this agent will be used for reverse
replication; returns user input from the publish to author environment.

6. Choose the Transport Tab

7. Make sure that the server and port specified in the URI are correct for the first Publish instance.

8. Verify that the specified User and Password are correct to access the first Publish instance. You
need to specify here the credentials of the user waiting for data at the destination. In our case,
these are the (default) credentials of admin user on the Publish server.

9. Click OK to save the settings.

Transport Tab Configuration Parameters


• URI: This specifies the receiving servlet at the target location In particular, you can specify
the hostname (or alias) and context path to the target instance here.
For example:

• A Default Agent may replicate to http://localhost:4503/bin/


receive?sling:authRequestLogin=1
• A Dispatcher Flush agent may replicate to http://localhost:80/dispatcher/invalidate.cache

The protocol specified here (HTTP or HTTPS) will determine the transport method.

7-6 | Chapter 07 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
 The Replication Agent configuration Dialog - Transport Settings Tab

• User: User name of the account to be used for accessing the target.

• Password: Password for the account to be used for accessing the target.

• NTLM Domain: Domain for NTLM authentication.

• NTLM Host: Host for NTLM authentication.

• Enable relaxed SSL: Enable if you want self-certified SSL certificates to be accepted.

• Allow expired certs: Enable if you want expired SSL certificates to be accepted.

CQ 5.6 System Administrator Training Student Workbook Chapter 07 | 7-7


Proxy Tab Configuration Parameters

The following settings are only needed if a proxy is configured in the network.

ADOBE COPYRIGHT PROTECTED


The Replication Agent configuration Dialog - Proxy Settings Tab

• Proxy Host: Hostname of the proxy used for transport.

• Proxy Port: Port of the proxy.

• Proxy User: User name of the account to be used.

• Proxy Password: Password of the account to be used.

• Proxy NTLM Domain: The proxy NTLM domain.

• Proxy NTLM Host: The proxy NTLM host.

7-8 | Chapter 07 CQ 5.6 System Administrator Training Student Workbook


Extended Tab Configuration Parameters:

ADOBE COPYRIGHT PROTECTED


The Replication Agent configuration Dialog - Extended Settings Tab

• Interface: Socket interface to bind to.

• HTTP Method: HTTP method to use.

• HTTP Headers: These are used for Dispatcher Flush agents and specify elements that must
be flushed.

{action} indicates a replication action; {path} indicates a path.

• Close Connection: Close the connection after each request.

• Connect Timeout: Timeout (in milliseconds) to be applied when trying to establish a


connection.

• Socket Timeout: Timeout (in milliseconds) to be applied when waiting for traffic after a
connection has been established.

• Protocol Version: Version of the protocol; for example “1.0” for HTTP/1.0.

CQ 5.6 System Administrator Training Student Workbook Chapter 07 | 7-9


Triggers Tab Configuration Parameters

ADOBE COPYRIGHT PROTECTED


The Replication Agent configuration Dialog - Triggers Settings Tab

These settings are used to define triggers for automated replication:

• Ignore default: If checked, the agent is excluded from default replication; this means it will
not be used if a content author issues a replication action.

• On Modification: Here, a replication by this agent will be automatically triggered when


a page is modified. This is mainly used for Dispatcher Flush agents, but also for reverse
replication.

• On Distribute: if checked, the agent will auto-replicate when content marked for
distribution is modified.

• On-/Offtime reached: This will trigger automatic replication (to activate or deactivate a
page as appropriate) when the ontimes or offtimes defined for a page occur. This is primarily
used for Dispatcher Flush agents.

• No Status Update: if checked, agent will not force a replication status update.

• No Versioning: if checked, agent will not force versioning of activated pages.

7-10 | Chapter 07 CQ 5.6 System Administrator Training Student Workbook


The purpose of the “Triggers” tab is to configure the agents to start replication automatically as soon
as certain conditions occur.

Now we want to setup a second Delivery Agent, pointing to our second Publish instance. We can
create a new Delivery Agent from scratch and modify the settings accordingly.

Since our second Delivery Agent differs from the default one only by its destination instance, we can
simply copy the Default Agent to reuse all other settings. To do this:

1. Return to the Tools pane.

ADOBE COPYRIGHT PROTECTED


2. Select the Default Agent.

3. Choose Copy to copy the Default Agent and Paste the new agent.

4. Open the new agent and click on Settings to show the details for that agent.

5. Give the new agent an appropriate name, for example, Publish 2.

6. Select the Transport Tab and set the URL to the correct values for the second Publish instance.
In our case, http://localhost:4505/bin/receive?sling:authRequestLogin=1. Also, make sure that
the User and Password are correct for the second Publish instance.

7. Click OK to save the settings.

For a detailed description of Replication Agents, please refer the online documentation
URL http://dev.day.com/docs/en/cq/current/deploying/configuring_cq.html#Replication Agents .

Now that the second Replication Agent is set up, we can test page activation:

1. Go back to the CQ administrative console and open the Websites panel.

2. Browse to the page Geometrixx Demo Site > English > Products in the navigation panel.

3. Create a new page and open it.

4. Add some text, image, any component you like on your page.

5. In the floating Sidekick panel, select the Page tab (the second tab).

6. Click Activate Page and confirm the activation.

CQ 5.6 System Administrator Training Student Workbook Chapter 07 | 7-11


Your page should now be accessible on both Publish instances. Check it with the browser. Open the
page on the Publish instances:

e.g., http://localhost:4503/content/geometrixx/en/products/<your page>.html


and
http://localhost:4505/content/geometrixx/en/products/<your page>.html

NOTE: If anything went wrong during the publishing process, check on the Author instance for
the related Replication Agent log files using the configuration panel we used as we edited the
settings.

ADOBE COPYRIGHT PROTECTED


How to Monitor Replication Agents?

To monitor a replication agent:

1. Access the Tools tab in the CQ administrative console.

2. Select Replication folder in the left pane to expand.

3. Double-click the link to agents for the appropriate environment (either the left or the right pane);
for example, Agents on author. The resulting window shows an overview of all your replication
agents for the author environment, including their target and status:

Dialog of the Replication Agent

7-12 | Chapter 07 CQ 5.6 System Administrator Training Student Workbook


4. Click the appropriate agent name (which is a link) to show detailed information on that agent.

ADOBE COPYRIGHT PROTECTED


Dialog to edit an individual Replication Agent

Here, you can:

• See whether the agent is enabled.

• See the target of any replications.

• See whether the replication queue is currently active, and if so any items in the queue.

• View Log to access the log of any actions by the replication agent.

• Test Connection to the target instance.

• Refresh, Clear (selectively or entirely), Pause the display of queue entries.

• Force Retry on any queue items if required.

Congratulations! You have successfully created and configured two Replication Agents that will
each replicate/activate to a Publish instance. In addition, you successfully replicated to both Publish
instances.

CQ 5.6 System Administrator Training Student Workbook Chapter 07 | 7-13


08

ADOBE COPYRIGHT PROTECTED


Activate a Tree

Excersise 8.1 Activate a Tree

Goal

From the Websites tab you can activate the individual pages. When you have entered, or updated a
considerable number of content pages — all of which are residing under the same root page — it is
easier to activate the entire tree in one action. You can also perform a Dry Run to emulate an
activation and highlight which pages would be activated.

The following instructions explain how to browse the application/server interfaces associated with a
CQ5 installation. This will enable you to use their administrative/configuration capabilities. To
successfully complete and understand these instructions, you will need:

• A running CQ5 Author instance

• A running CQ5 Publish instance (if not available activation gets queued)

To activate a complete tree of your website:

1. Access the Tools tab in CQ administrative console.

CQ 5.6 System Administrator Training Student Workbook Chapter 08 | 8-1


2. Click on Replication — the folder will expand.

3. Then double-click on Activate Tree.

4. The following page will open.

ADOBE COPYRIGHT PROTECTED


The dialog to define the content tree

5. Enter /content/geometrixx/en into the Start Path or select the link from the drop-down selection.
The “Start Path” specifies the path to the root of the section you want to activate (publish). This
page, and all pages underneath, will be considered for activation (or used in the emulation if a
“Dry Run” is selected).

6. Choose the selection criteria as required:

• Only Modified: only activate pages that have been modified.

• Only Activated: only activate pages that have (already) been activated. Acts as a form of
reactivation.

• Ignore Deactivated: ignore any pages which have been deactivated.

8-2 | Chapter 08 CQ 5.6 System Administrator Training Student Workbook


7. Select Dry Run to check which pages would be activated. This is only an emulation, no pages will
be activated.

ADOBE COPYRIGHT PROTECTED


A “Dry Run” tree activation

8. Select Activate to activate the tree.

Congratulations! You have successfully activated a set (tree) of content pages.

CQ 5.6 System Administrator Training Student Workbook Chapter 08 | 8-3


09

ADOBE COPYRIGHT PROTECTED


Add a Reverse Replication Agent

Excersise 9.1 Add reverse replication agent


Goal

Replication Agents are used to propagate content from an Author instance to a Publish instance. This
kind of content replication occurs in a one way direction only. In a default environment, the Publish
instances are located behind a firewall that prevents Publish instances to send the User Generated
Content on their instances directly to an Author instance. In order to propagate such a content to all
Publish instances, we need to pull that content from the Publish server and spread it via the regular
mechanisms (Default Replication Agents).

In this exercise, we setup two Reverse Replication Agents, one for each installed Publish instance.
The settings of a Reverse Replication Agent are very similar to the ones of a Delivery Agent, which
eases our setup work. In an out-of-the-box installation, there’s already such an agent configured,
pointing to a local Publish instance’s repository.

The following instructions explain how to create and configure Replication Agents. To successfully
complete and understand these instructions, you will need:

• A running CQ5 Author instance

CQ 5.6 System Administrator Training Student Workbook Chapter 09 | 9-1


• Two running CQ5 Publish instances

Access the Author Agent’s settings

1. Access the Tools Console of your Author instance.

2. Select Replication folder in the left pane to expand.

ADOBE COPYRIGHT PROTECTED


3. Double-click the link to agents for the appropriate environment (either the left or the right pane);
for example, Agents on author. The resulting window shows an overview of all your replication
agents for the author environment, including their target and status:

The available Replication Agents

4. Click the Reverse Replication Agent link. The screen shows the status of the Reverse Replication
Agent pointing to a default Publish instance. More setting details can be viewed or modified by
clicking on the button Edit. It’s a good idea to test the connection to the destination point by
following the link labeled Test Connection.

Now let’s create a new Agent for our second Publish instance.

9-2 | Chapter 09 CQ 5.6 System Administrator Training Student Workbook


1. Go back to the Tools tab.

2. In the Navigation pane (left tree), navigate to the node Replication > Agents on author.

3. Copy and paste the default Reverse Replication Agent and adapt its settings.
Rename both Reverse Replication Agents accordingly. Make sure, each of them are pointing to the
desired Publish instance.

Test Reverse Replication

During previous exercise, we replicated the entire Geometrixx > English website. There exists a page,

ADOBE COPYRIGHT PROTECTED


GeoBlog, which is perfectly suitable for our test. It consists of a blog, where every visitor can leave a
comment. Since a visitor is connected with one Publish instance at a time, the Reverse Replication
Agent is responsible to retrieve the entered content (comment, reply) to be redistributed again to all
enclosed recipient Publishers. Feel free to test with other forms as well if desired.

1. On Publish 1, navigate to page http://localhost:4503/content/geometrixx-outdoors/en/


community/hiking.html. The Geometrixx Outdoors Hiking Community page appears.

2. Enter a new comment or reply to an existing one of your choice.

3. After a few seconds (default : 5), your comment should be visible on the Author instance, as well
as on the other Publish instance too.

Congratulations! You have successfully activated two Reverse Replication Agents and tested them.

CQ 5.6 System Administrator Training Student Workbook Chapter 09 | 9-3


10

ADOBE COPYRIGHT PROTECTED


Add the Dispatcher to the IIS
WebServer

Goal

The Dispatcher is Adobe’s caching and/or load balancing tool. 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 CQ Dispatcher is a Web server module. A version is available for Apache Web Server, Microsoft
Internet Information Server, and iPlanet. While the installation of the CQ Dispatcher depends on the
Web server, the configuration is the same on all servers:

• Install the supported web server of your choice according to their own documentation.

• Install the CQ Dispatcher module appropriate to the chosen web server and configure the
web server accordingly.

• Configure the Dispatcher.

• Integrate with CQ to update the cache when the content is changed.

In this exercise, we will install the Dispatcher into an IIS web server.

CQ 5.6 System Administrator Training Student Workbook Chapter 10 | 10-1


To successfully complete and understand these instructions, you will need:

• An IIS Web server, up and running

• A running CQ5 Author instance

• A running CQ5 Publish instance

Excersise 10.1-How does the Dispatcher plug in to IIS

Make sure Internet Information Services is up and running in your system, if not, refer to documentation

ADOBE COPYRIGHT PROTECTED


for installation instructions
(http://msdn.microsoft.com/en-us/library/ms143748%28SQL.90%29.aspx).

Also remember to check that Role Services are installed:

Feature Window of Microsoft ISS

1. Unzip the latest Dispatcher build, appropriate for your operating system, to a temporary directory.
The Dispatcher files are located on the memory stick under /distribution/dispatcher.

2. Add the Dispatcher to the list of available ISAPI filters (by adding the DLL to the IIS) using the
following steps:

NOTE: The ISS_INSTALLDIR is normally the C:\Inetpub folder

10-2 | Chapter 10 CQ 5.6 System Administrator Training Student Workbook


• Extract disp_iis.dll, disp_iis.ini, disp_iss.pdb and dispatcher.any into the executable
directory of the selected website under IIS.

• i.e. <IIS_INSTALLDIR>/scripts

Configure the Virtual Directory

• Open Administrative Tools, then select IIS Manager.

• Select your site in the tree, then from the context menu (usually right mouse click) select
“Add Virtual Directory”.

ADOBE COPYRIGHT PROTECTED


• Enter the alias scripts and the physical path of the directory created above (C:\Inetpub\
scripts).

Register the ISAPI filter

• Select Features View

• Open the feature ISAPI Filters in the view

• Click Add and enter the following settings:

• Filter name: CQ
• Executable: the path to disp_iis.dll (C:\Inetpub\scripts)

• Click OK to save

Register the ISAPI handler

• Open the feature “Handler Mappings” in the view

• Click “Add Script Map” and enter the following settings:

• Request Path: /scripts/disp_iss.dll


• Executable: the path to disp_iis.dll (C:\Inetpub\scirpts)
• Name: CQ

• Click OK to save

• Open the feature “Configuration Editor”

• Select “system.webServer\handlers” from section drop down list

• Select the first row (“Collection” at the top) ,and then click on the “three dots” button (at the
far right)

• The “Collection Editor” will appear, select the handler CQ

CQ 5.6 System Administrator Training Student Workbook Chapter 10 | 10-3


• Change the value of the “allowPathInfo” flag to true

• Close the “Collection Editor” and click “Apply”

Register the json extension

• Open the feature “MIME Types” in the view

• Click “Add” and enter the following settings:

• File name extension: json

ADOBE COPYRIGHT PROTECTED


• MIME type: application/jason

• Click OK to save

3. Place the (example) configuration file disp_iis.ini into the same directory as the DLL disp_iis.dll.
The basic format of the .ini file is as follows:

10-4 | Chapter 10 CQ 5.6 System Administrator Training Student Workbook


; This is the initial configuration file for the ISAPI filter DLL. Its name (without; extension) must match
the base name of the ISAPI filter DLL.

[main]
; scriptpath is the URI pointing to the ISAPI extension DLL
scriptpath=/scripts/disp_iis.dll

; configpath is the physical filesystem path of the dispatcher.any configuration file


configpath=C:\Inetpub\scripts\dispatcher.any

; loglevel is the logging level, values allowed lie between 0 (NONE) and 3 (DEBUG)

ADOBE COPYRIGHT PROTECTED


loglevel=3

; servervariables, if set to 1, forwards IIS server variables as request headers to


; the remote instance.
servervariables=0

; replaceauthorization,
; if set to 1, replaces any header named “Authorization” other than
; “Basic” with its “Basic <IIS:LOGON_USER>” equivalent.
replaceauthorization=0

; declineroot, if set to 1, declines requests to “/” and passes them on to the next
; filter or IIS, it this is the last filter in the filter chain
;declineroot=0

Congratulations! You have successfully integrated the CQ Dispatcher with the IIS web server.

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. Before you can start using the CQ Dispatcher,
you must configure the Dispatcher (see Exercise 10.1, How does the Dispatcher plug in to IIS).

CQ 5.6 System Administrator Training Student Workbook Chapter 10 | 10-5


11

ADOBE COPYRIGHT PROTECTED


Add the Dispatcher to the
Apache WebServer

Goal

The Dispatcher is Adobe’s caching and/or load balancing tool. 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 CQ Dispatcher is a Web server module. A version is available for Apache Web Server, Microsoft
Internet Information Server, and iPlanet. While the installation of the CQ Dispatcher depends on the
Web server, the configuration is the same on all servers:

• Install the supported web server of your choice according to their own documentation.

• Install the CQ Dispatcher module appropriate to the chosen web server and configure the
web server accordingly.

• Configure the Dispatcher.

• Integrate with CQ to update the cache when the content is changed.

In this exercise, we will install the Dispatcher into an Apache web server.

CQ 5.6 System Administrator Training Student Workbook Chapter 11 | 11-1


To successfully complete and understand these instructions, you will need:

• An Apache Web server, up and running

• A running CQ5 Author instance

• A running CQ5 Publish instance

How does the Dispatcher plug in to Apache?

Make sure the Apache Web Server is up and running on your system, if not, download the version that

ADOBE COPYRIGHT PROTECTED


best suits you from (http://httpd.apache.org/download.cgi), and follow the instructions to install and
configure. The binary download is sufficient for this exercise.

Browser proofs Apache Web server is running

How to install the Dispatcher into Apache:

1. Unzip the latest CQ Dispatcher build, appropriate for your operating system and Web server, to a
temporary directory. The Dispatcher files are located on the memory stick under {/USB}/
distribution/dispatcher.

2. Move the file disp_apache2.2.dll (or the one corresponding to your Operating System version)
into the directory <apache_home>/modules.

3. Move the dispatcher configuration file dispatcher.any to the directory <apache_home>/conf.

11-2 | Chapter 11 CQ 5.6 System Administrator Training Student Workbook


The following configuration entries will be added (in steps 4 and 5) to the Apache web server httpd.
conf file, in the order listed:

1. LoadModule statement to load the dispatcher module on startup

2. Dispatcher-specific configuration entries, inside an ifModule, including:

a. DispatcherConfig — Location and name of the configuration file.

b. DispatcherLog — Location and name of the log file.

ADOBE COPYRIGHT PROTECTED


c. DispatcherLogLevel — Log level of the log file.

d. DispatcherNoServerHeader — Indicates that the Apache server header should be used

e. DispatcherDeclineRoot — Defines whether to decline requests to root

f. DispatcherUseProcesseduRL — Defines whether to use the pre-processed (by Apache web


server) URL or the original URL

g. DispatcherPassError — Defines how to support 40x error codes for Error Document
Handling.
3. SetHandler to activate the Dispatcher.LoadModule. This gets placed in the first <Directory>
section after the LoadModule section. The SetHandler statement, we will be using configures
the Dispatcher to handle requests for the complete website.

4. ModMimeUsePathInfo – Should be set “On” for all Apache configurations. After the SetHandler
statement, add an ifModule statement containing the ModMimeUsePathInfo statement. (only
for Dispatcher 4.0.9 and higher.

CQ 5.6 System Administrator Training Student Workbook Chapter 11 | 11-3


4. Add the following text to the httpd.conf file at the end of the Load Module section:

LoadModule dispatcher_module
modules/disp_apache2.2.dll

<IfModule disp_apache2.c>

#location of the configuration file. e.g., “conf/dispatcher.any”


DispatcherConfig conf/dispatcher.any
#location of the dispatcher log file
DispatcherLog logs/dispatcher.log

ADOBE COPYRIGHT PROTECTED


#log level for the dispatcher log file, e.g., “logs/dispatcher.log”
#0 Errors
#1 Warnings
#2 Infos
#3 Debug
DispatcherLogLevel 3

#must be 1, so that the dispatcher looks like a regular module


DispatcherNoServerHeader 1

#if turned to 1, requests to “/” are not handled by the dispatcher


#if turned to 1, use mod_alias for the correct mapping
DispatcherDeclineRoot 0

# if turned to 1, use the URL already processed


#by the handlers that precede the dispatcher
DispatcherUseProcessedURL 1

#if 0, dispatcher spools all error responses to the client


DispatcherPassError 0
</IfModule>

11-4 | Chapter 11 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
5. You must add a SetHandler statement to the context of your configuration (<Directory>,
<Location>) for the Dispatcher to handle the incoming requests. The mode_mime module is
used to assign content metadata to the content selected for an HTTP response. When “On”, the
ModMimeUsePathInfo parameter specifies that mode_mime is to determine the content type
based on the complete URL; this means that virtual resources will have meta information applied
based on their extension.

Make the first <Directory> element, after the LoadModule section look like the following, to
configure the Dispatcher to handle requests for the complete website:

CQ 5.6 System Administrator Training Student Workbook Chapter 11 | 11-5


<Directory />

<IfModule disp_apache2.c>

SetHandler dispatcher-handler
ModMimeUsePathInfo On

</IfModule>

Options FollowSymLinks
AllowOverride None

ADOBE COPYRIGHT PROTECTED


</Directory>

6. Optional, but recommended for Linux and MacOS, is changing 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:

11-6 | Chapter 11 CQ 5.6 System Administrator Training Student Workbook


• cd <APACHE_ROOT>
• chown -R daemon:daemon htdocs

7. You can see the dispatcher has been installed by restarting your Apache web server and checking
the creation of the log file: dispatcher.log.

ADOBE COPYRIGHT PROTECTED


Congratulations! You have successfully integrated the Dispatcher with the Apache web server.

NOTE: Before you can start using the Dispatcher, you must configure the Dispatcher.

CQ 5.6 System Administrator Training Student Workbook Chapter 11 | 11-7


12

ADOBE COPYRIGHT PROTECTED


Configure the Dispatcher

Goal

Now that we have integrated the CQ Dispatcher with the web server, we must configure the Dispatcher
so that it can find its associated Publish instances, knows which pages to cache, and where to cache
them.

In this exercise, we will configure the CQ Dispatcher with appropriate settings to cache pages as
desired, and we will define a Dispatcher Flush agent to “invalidate” the cache in response to content
update. To successfully complete and understand these instructions, you will need:

• A running CQ5 Author instance

• A running CQ5 Publish instance

• A web server with Dispatcher installed

Configuring the “dispatcher.any” file

By default, the CQ Dispatcher configuration is stored in a file named “dispatcher.any”. You can
change the name and location of the configuration file. If you do so, make sure to configure the
module with the new name/location. The “dispatcher.any” file is independent of the Web server and
operating system, so the following instructions are appropriate to both IIS and Apache. The only
difference between the two configurations is the usage of the property /homepage, which is used
only by IIS.

CQ 5.6 System Administrator Training Student Workbook Chapter 12 | 12-1


To Configure the Dispatcher

1. Open the “dispatcher.any” file with the text editor of your choice.

2. Make sure the /farms section matches your infrastructure. The /farms section defines a list of
farms or websites. 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.

ADOBE COPYRIGHT PROTECTED


• Further characteristics including where to cache files and what to cache.

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

12-2 | Chapter 12 CQ 5.6 System Administrator Training Student Workbook


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

The configuration file contains a series of single-valued or multi-valued properties that control the
behavior of Dispatcher:

• Property names are prefixed with a forward slash (“/”).

• Multi-valued properties enclose child items using braces (“{ }”).

The following is an example dispatcher configuration:

ADOBE COPYRIGHT PROTECTED

CQ 5.6 System Administrator Training Student Workbook Chapter 12 | 12-3


If you need to, you can include other files that contribute to the configuration:

• If your configuration file is large, you can split it into several smaller files (that are easier to
manage) ,and 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
{

ADOBE COPYRIGHT PROTECTED


$include “myFarm.any”
}

The clientheaders section defines a list of all HTTP headers passed from the client to the CQ instance.
By default, the CQ 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

12-4 | Chapter 12 CQ 5.6 System Administrator Training Student Workbook


3. Verify the list of client headers in the clientheaders section.

...
# each farm configure a set off (LoadBalanced) renders
/forms
{ |
# first farm entry (label is not important , just for your convenience)
/wesite
{
# client headers which should be passed through to the reader instances
/clientheaders
{
“referer”

ADOBE COPYRIGHT PROTECTED


“user-agent”
“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”
}
...

NOTE: If you add your own header, you have to add all default headers to the configuration
section.

CQ 5.6 System Administrator Training Student Workbook Chapter 12 | 12-5


4. (For IIS-only)  Adapt the homepage property.

...
/farms
{
# first farm entry (label is not important, just for your convenience)
/website
{
...
# url where / request should be redirected to
/homepage */geometrixx/en.html*
...

ADOBE COPYRIGHT PROTECTED


5. The virtualhosts 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.

Adapt the virtualhosts property.

...
/farms
{
# first farm entry (label is not important, just for your convenience)
/website
{
...
/virtualhosts
{
# entries will be compared against the “host” request header
# example : www.company.com
# example : intranet.*
#example : mysite.*/mysite/*
...
}
...

6. The renders section defines where the CQ Dispatcher will allocate requests to render a document.
The Dispatcher will load balance among all the defined renders.
Adapt the renders property for the available publish instances.  This will forward all requests to
the specified publish instance(s) (called renders in the dispatcher configuration). You can define
several renders within a farm for load balancing.

NOTE: Adobe best practices suggest that you let the web server handle virtual hosting.

12-6 | Chapter 12 CQ 5.6 System Administrator Training Student Workbook


7. When configuring the Dispatcher, you should restrict external access as far as possible; for
example, only the following are available to external visitors:

• /content

• miscellaneous content such as designs and client libraries; for example:

• /etc/designs/default*
• /etc/designs/mydesign*

The following is an example /filter section, from the dispatcher.any file. The recommended principle
is to deny access to everything, then allow access to specific (limited) elements:

ADOBE COPYRIGHT PROTECTED

CQ 5.6 System Administrator Training Student Workbook Chapter 12 | 12-7


NOTE: Adobe best practices suggest that you deny access to /libs, /etc, /crx, /admin, /var, /tmp,
/home, /apps, and any other URIs that should not be accessible from outside.  Please see the
Security Checklist for further considerations when restricting access using the CQ Dispatcher.

8. The /cache section specifies some general aspects of how and where the CQ Dispatcher caches
documents. Included in the /cache section are:

/docroot: This link points to the document root of the web server.

ADOBE COPYRIGHT PROTECTED


/statfile and /statfileslevel define which parts of the website tree are invalidated when pages are
activated.

/allowAuthorized: Specifies whether requests (pages) that carry an authentication header are cached.

/rules: A list of cacheable documents determines which documents are cached

/invalidate: Defines a list of all documents that are automatically rendered invalid after a content
update.

The /docroot link points to the document root of the web server. This is where the CQ 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.

Define the location of the web server cache to the CQ Dispatcher.

{
# the cacheroot must be equal to the document of web server
# /docroot “C:/Inetpub/wwwroot”
/docroot “<Apache_document_root>”
...

9. Configuration of the CQ Dispatcher is not yet complete, but at this point we can test the
configuration of the Dispatcher with the web server. Save your changes to the dispatcher.any file.

10. Save dispatcher.any changes.

11. Restart the Web server.

12-8 | Chapter 12 CQ 5.6 System Administrator Training Student Workbook


12. Access the Geometrixx website using the following URLs:

Author instance:   http://localhost:4502/content/geometrixx.html

Publish instance:    http://localhost:4503/content/geometrixx.html

Webserver/Dispatcher:    http://localhost/content/geometrixx.html

Test our Configuration


We have not yet completed the CQ Dispatcher configuration. For example, we still have not defined

ADOBE COPYRIGHT PROTECTED


a way for the CQ Dispatcher to invalidate cached pages. However, the cached pages should be
showing up in the web server’s document root.

If you now navigate to the web server document root directory on disc, you should see directories
and files appear as the CQ Dispatcher and web server begin to cache pages.

If you continue to navigate through the Geometrixx web site, using the web server
(default port 80), you should see the set of cached pages grow.

CQ 5.6 System Administrator Training Student Workbook Chapter 12 | 12-9


Complete the Dispatcher configuration
Now that we know we have a good connection between the Web server, CQ Dispatcher, and publish
instance, we can complete the configuration of the CQ Dispatcher.

1. The /statfile link points to the “statfile”, which the CQ 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.

NOTE: The “statfile” is nothing else than a regular text file. When a page gets replicated, the
Dispatcher Flush agent sends a request to the Web server. The CQ Dispatcher recognizes the

ADOBE COPYRIGHT PROTECTED


request, opens the file, changes 1 byte and saves it. The time stamp of the file is “newer” than
the ones of the cached pages. This is how the CQ Dispatcher “invalidates” the cache.

The /statfileslevel link causes “statfiles” to be created 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 CQ Dispatcher
invalidates the English part of the website, other sections are not affected (for example, the German
and French sections).

You may use /statfile or /statfileslevel, but not both.

Set the /statfileslevel property.

/cache
{
/docroot “C:/apache/htdocs”
/statfileslevel “2”
...

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


Set the /allowAuthorized property.

12-10 | Chapter 12 CQ 5.6 System Administrator Training Student Workbook


/cache
{
/docroot “C:/apache/htdocs”
/statfileslevel “2”
/allowAuthorized “0”
...

3. The /rules property defines which documents are cached, though the Dispatcher never caches a
document in the following circumstances:

• If the HTTP method is not GET.

ADOBE COPYRIGHT PROTECTED


• 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
CQ Dispatcher cache everything.

4. Define the list of cacheable documents:

/cache
{
/docroot “C:/apache/htdocs”
/statfileslevel “2”
/allowAuthorized “0”
/rules
{
/0000
{
/glob “*”
/type “allow”
}
/0001
{
/glob “/en/news/*”
/type “deny”
}
/0002
{
/glob “*/private/*”
/type “deny”
}
}
...

CQ 5.6 System Administrator Training Student Workbook Chapter 12 | 12-11


5. The /invalidate section 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
be safe, you usually auto-invalidate all HTML pages.

ADOBE COPYRIGHT PROTECTED


If you offer automatically generated PDF and ZIP files for download, you might have to auto-invalidate
these as well.

Set the list of documents that are automatically invalidated after any activation:

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

6. Save dispatcher.any changes.

Congratulations! Now you have a fully configured Dispatcher. The accessed web documents are
being cached, but newly activated documents will not replace the cached documents until we have
configured a Dispatcher Flush agent that will invalidate the cache.

12-12 | Chapter 12 CQ 5.6 System Administrator Training Student Workbook


Configuring the Dispatcher Flush Agent

In cases where there are multiple Publish instances, the flushing/invalidating of the cache by the CQ
Dispatcher is controlled by a replication agent, running on the publish instance. However, the
configuration is made on the authoring instance and then transferred to the publish instance(s) by
activating the agent:

1. Open the CQ SiteAdmin console and select the Tools tab.

2. Open the required replication agent; for example, the Dispatcher Flush agent under Agents on

ADOBE COPYRIGHT PROTECTED


Publish, which is part of a standard installation.

3. In the Settings tab, ensure that Enabled is active.

Settings tab of the Dispatcher Flush agent

4. Open the Transport tab and enter the URI needed to access the CQ Dispatcher on the host and
port where the web server is running. Enter http://{host}:port} followed by /bin/receive, for
example: http://localhost/bin/receive.

NOTE: You don’t have to set the User and Password, because this agent communicates with the
CQ Dispatcher and not with another CQ instance.

CQ 5.6 System Administrator Training Student Workbook Chapter 12 | 12-13


ADOBE COPYRIGHT PROTECTED
Transport tab of the Dispatcher Flush agent

5. Replicate the Dispatcher Flush agent to the Publish instance by activating it.

6. Edit and activate a page from author to publish.

7. Make sure the activation of new content was successful by accessing the page from the Publish
instance. For example: http://localhost:4503/content/geometrixx/en/products.html

8. Access the page from the web server. For example: http://localhost/content/geometrixx/en/
products.html.

9. Check the document root for a .stat file.

Congratulations! You have successfully configured the Dispatcher with the web server, cached pages
in the web server document root, and accessed activated content pages from the web server.

12-14 | Chapter 12 CQ 5.6 System Administrator Training Student Workbook


13

ADOBE COPYRIGHT PROTECTED


Optimize the TarJournal PM on
Author Instance

Exercise 13.1- Optimize the TarJournal PM on Author Instance


Goal

As data is never overwritten in a tar file, the disk usage increases even when only updating existing
data. When optimizing, the TarJournal Persistence Manager copies data that is still used from old tar
files into new tar files and deletes the old tar files that contain only old or redundant data.

This exercise will show you multiple ways to optimize the TarJournal PM. To successfully complete
and understand these instructions, you will need:
• A running CQ5 Author instance

Manually optimizing journaled tar pm files using CRX Console

To optimize tar files using the CRX console:

1. In the CRX Console, log in as administrator.

2. Click Repository Configuration.

CQ 5.6 System Administrator Training Student Workbook Chapter 13 | 13-1


3. Select Tar Persistence Manager Optimization and click Start Optimization.
Alternatively, you could go into the Felix console (http://localhost:4502/system/console) ; click the
JMX tab and click Domain: com.adobe.granite, type: Repository.

4. Among the several attributes you can configure, you will find TarOptimizationDelay, which
represents the delay in milliseconds after optimizing a single transaction, the recommended
and default value is 1.

Scroll down until you reach Operations and then click

startTarOptimization().

ADOBE COPYRIGHT PROTECTED


5. Click Invoke on the emerging window.

The startTarOptimization() Window

Since our repository has only 1 tar file (we haven’t made enough changes to the repository), the
optimization will have no effect.

Automatically optimizing tar files using workspace.xml

CRX automatically runs Tar PM optimization between 2 am and 5 am. If the automatic optimization
is not finished at 5 am, then it will stop automatically. It will continue from there the next night (it
doesn’t start from the beginning).

To change the time when automatic optimization is run, use the Tar PM configuration option
“autoOptimizeAt”.

1. Navigate to <CQ5_install_dir>/crx-quickstart/repository/workspaces/crx.default.

13-2 | Chapter 13 CQ 5.6 System Administrator Training Student Workbook


2. Open the file workspace.xml with a text editor of your choice.

3. To set the optimization to run at 1:00 AM every day, make the following change to the
Persistence Manager element:

<PersistenceManager class=”com.day.crx.persistence.tar.TarPersistenceManager”>
<param name=”autoOptimizeAt” value=”01:00” />
</PersistenceManager>

NOTE: In the Out-Of-The-Box product the “PersistenceManager” tag does not include any

ADOBE COPYRIGHT PROTECTED


params, so take special attention and don’t forget to remove the slash at the end of the
“PersistentManager” tag. Other parameters for this configuration can be found here
http://dev.day.com/docs/en/crx/current/administering/persistence_managers.
html#Configuring%20the%20TarPM

4. Save workspace.xml.

5. In order for the changes to take effect, you must restart CQ.

Congratulations! You have successfully optimized the Tar PM of your repository to start the
optimization process automatically in the background.

CQ 5.6 System Administrator Training Student Workbook Chapter 13 | 13-3


14

ADOBE COPYRIGHT PROTECTED


Backup

There are two ways to back up and restore CRX repository content:

1. You can create an external backup of the repository and store it in a safe location. If the reposi-
tory breaks down, you can restore it to the previous state.

2. You can create internal versions of the repository content. These versions are stored in the
repository along with the content, so you can quickly restore nodes and trees you have
changed or deleted.

General
The approach described here applies for system backup and recovery.

If you need to backup and/or recover a small amount of content, which is lost, a recovery of the sys-
tem is not necessarily required:
• Either you can fetch the data from another system via a package, or
• you cam restore the backup on a temporary system, create a content package, and deploy it on
the system, where this content is missing.

Timing
Do not run backup in parallel with the datastore garbage collection, as it might harm the results of
both processes.
Generally, it is recommended to run the Tar Optimizer after the backup has been performed.

CQ 5.6 System Administrator Training Student Workbook Chapter 14 | 14-1


Offline Backup
You can always do an offline backup. This requires a downtime of CRX, but can be quite efficient in
terms of required time compared to an online backup.

In most cases, you will use a filesystem snapshot to create a read-only copy of the storage at that time.
To create an offline backup, perform these steps:
• stop the application
• make a snapshot backup
• start the application

Online Backup

ADOBE COPYRIGHT PROTECTED


This backup method creates a backup of the entire repository, including any applications deployed
under it, such as CQ5. The backup includes content, version history, configuration, software, hotfixes,
custom applications, log files, search indexes, and so on. If you are using clustering and if the shared
folder is a subdirectory of crx-quickstart (either physically, or using a softlink), the shared directory is
also backed up.

You can restore the entire repository (and any applications) at a later point.

This method operates as a hot or online backup so it can be performed while the repository is run-
ning. Therefore the repository is usable while the backup is running. This method works for the de-
fault, TarPM-based, CRX instances.

When creating a backup, you have the following options:


• Creating a backup of the repository (compressed as a zip file).
• Backing up to a directory without creating a zip file.
• Backing up with a time delay (to lessen the impact of the backup on system performance).

Database
The online backup only backs up the file system. If you store the repository content and/or the repos-
itory files in a database, that database needs to backed up separately.

CRX Online Backup

An online backup of your repository lets you create, download, and delete backup files. It is a “hot” or
“online” backup feature, so can be executed while the repository is being used normally in the read-
write mode.

When starting a backup you can specify a Target Path and/or a Delay.

14-2 | Chapter 14 CQ 5.6 System Administrator Training Student Workbook


Target Path

The backup files are usually saved in the parent folder of the folder holding the quickstart jar file (.jar).
For example, if you have the CRX jar file located under /InstallationKits/CRX, then the backup will be
generated under /InstallationKits. You can also specify a target to a location of your choice.

Depending on how you define the Target Path you can either backup to a:
1. Zip file (Target Path specifies a name ending with .zip), With this you can achieve:
• Full Backup
2. Directory (Target Path specifies only a directory name), With this you can achieve:

ADOBE COPYRIGHT PROTECTED


• Full Backup—Backup to an empty target directory
• Incremental Backup— Backup to an existing target directory.
The target directory contents are overwritten, except for files that match exactly. For files
that match, the last modified time in the target directory and the archive bit are not changed.
Existing files that do not match are overwritten, and files that do not exist in the repository
are deleted from the target directory.

Delay
Indicates a time delay (in milliseconds), so that repository performance is not affected.
By default, the CRX backup runs at full speed. You can slow down creating an online backup, so that
it does not slow down other tasks.
A delay of 1 millisecond typically results in 10% CPU usage, and a delay of 10 milliseconds usually
results in less than 3% CPU usage. The total delay in seconds can be estimated as follows:

• Repository size in MB * delay in milliseconds / 2 (if the zip option is used)


• Repository size in MB * delay in milliseconds/ 4 (when backing up to a directory).

That means a backup to a directory of a 200 MB repository with 1 ms delay increases the backup time
by about 50 seconds.

You can access backups (made to both zip files and target directories) from the file system. From here
you can use any kind of backup tool (full backup or incremental backup).

Exercise 14.1-Create a backup


1. Log in to CRX as the administrator (admin) and Choose Backup from the classic Welcome Screen

CQ 5.6 System Administrator Training Student Workbook Chapter 14 | 14-3


ADOBE COPYRIGHT PROTECTED
2. The backup console will open. Specify the Target Path and Delay as required

NOTE: you can also get to the Backup Administration Screen by accessing the following
URL: http://localhost:4502/libs/granite/backup/content/admin.html

14-4 | Chapter 14 CQ 5.6 System Administrator Training Student Workbook


3. Click Start, a progress bar will indicate the progress of the backup. You can Cancel a running
backup at any time.
4. When the backup is complete the zip files are listed in the left pane of the console.

ADOBE COPYRIGHT PROTECTED


Congratulations! You have successfully created a full backup of your Author repository without
taking the instance down.

NOTE: Backup files that are no longer needed can be removed using the console. Select
the backup file in the left pane, then click Delete.
If you have backed up to a directory: after the backup process is finished CRX will not write to the
target directory.

Backing Up the Data Store Separately


If the file data store has been configured outside the main repository, it is not included in the
backup. This will reduce the size of the online backup and the size of the backup zip file. However,
the data store needs to be backed up as well. Since files in the file data store directory are im-
mutable, they can be backed up incrementally (potentially using rsync) or after running the online
backup.

NOTE: Do not run the data store backup and garbage collection concurrently.

Automating Backup Creation


If possible, the online backup should be run when there is little load on the system, for example, in
the morning. By default the Tar PM optimization runs between 2 am and 5 am, which also slows down
the system, that means a good time to run the online backup is 5 am.

CQ 5.6 System Administrator Training Student Workbook Chapter 14 | 14-5


Backups can be automated using the wget or curl HTTP clients. The following show examples of how
to automate backup using curl.

Backing up to the default Target Directory



Caution:
In the following example, various parameters in the curl command might need to be configured for
your instance; for example, the hostname (localhost), port (4502), admin password (xyz), and file name
(backup.zip).

ADOBE COPYRIGHT PROTECTED


curl -u admin:admin -X POST http://localhost:4502/system/console/jmx/com.adobe.
granite:type=Repository/op/startBackup/java.lang.String?target=backup.zip

The backup file/directory is created on the server in the parent folder of the folder containing the
crx-quickstart folder (the same as if you were creating the backup using the browser). For example, if
you have installed CRX in the directory /InstallationKits/crx-quickstart/, then the backup is created in
the /InstallationKits directory.

The curl command returns immediately, so you must monitor this directory to see when the zip file is
ready. While the backup is being created a temp directory (with the name based on that of the final
zip file) can be seen, at the end this will be zipped. For example:
• name of resulting zip file: backup.zip
• name of temporary directory: backup.f4d5.temp

Backing up to a non-default Target Directory


Usually the backup file/directory is created on the server in the parent folder of the folder containing
the crx-quickstart folder.

If you want to save your backup (of either sort) to a different location, you can set an absolute path to
the target parameter in the curl command.

For example, to generate backupJune.zip in the directory /Backups/2012:


curl -u admin:admin -X POST http://localhost:4502/system/console/jmx/com.adobe.
granite:type=Repository/op/startBackup/java.lang.String?target=/Backups/2012/
backupJune.zip”


Caution:
When using a different application server (such as JBoss), the online backup may not work as expected,
because the target directory is not writable. In this case, please contact Support.

Backing up a Shared Directory


If a shared directory should be included in the backup (usually yes, as it contains the data store), then
the shared directory needs to be a subdirectory of the backup source directory (installDir). This is the

14-6 | Chapter 14 CQ 5.6 System Administrator Training Student Workbook


case in the default installation. If this is not the case in your installation, then one solution is to create
a soft link to the shared directory from within the backup source directory.

Backing up a Large Repository


As your repository grows, the size can start to impact the length of time required to make a backup.
This in turn can impact either downtime or performance of the application.

There are various options available for you to consider when making backups of a large repository:

Snapshot Backup

ADOBE COPYRIGHT PROTECTED


A snapshot backup involves taking a read-only copy of a storage device at a given moment. They are
designed to be instantaneous, or as close as possible.

To make a snapshot backup of your application (for example, CRX or CQ), you need to:
1. stop the application
2. make a snapshot backup
3. start the application
As the snapshot backup usually takes only a few seconds, the entire downtime is less than a few min-
utes; and if you are running a cluster, you only need to stop and backup one cluster node so there is
no downtime.

Incremental Backups

The online backup can write to a target directory instead of a zip file. With this you can achieve both
full and incremental backups.

Once the online backup is finished, you can backup this target directory using either a snapshot or a
classical incremental backup tool.

Caution:
Incremental backup of the file data store is supported; when using incremental backup for other com-
ponents (such as Lucene index), please ensure deleted files are also marked as deleted in the backup.

Online Backup with Time Delay

You can also configure a time delay when performing online backups to minimize the impact the
backup has on the performance of CRX (or CQ).

Separate Data Store

Storing your data store outside the repository allows it to be backed up separately. It also allows you
to take incremental backups of the data store, which will be quicker than a full backup (though spo-
radic full backups are recommended to provide a base point, should a restore ever be required).

CQ 5.6 System Administrator Training Student Workbook Chapter 14 | 14-7


The datastore directory can be backed up at runtime, after the repository; datastore garbage
collection must not be run until the backup is finished.

Package Backup
To back up and restore content, you can use one of the following:
1. Package Manager, which uses the Content Package format to back up and restore content. The
Package Manager provides more flexibility in defining and managing packages.
2. Content Zipper, which uses the CRX Package, XML Sys View Package, XML Doc View, or ZIP
format to back up content. You restore content in these package formats with the Content Loader.
See Creating a Backup using the Content Zipper and Restoring a Backup using the Content

ADOBE COPYRIGHT PROTECTED


Loader.
For details on the features and tradeoffs of each of these individual content package formats, see
Importing and Exporting Content in the User Guide at:
http://dev.day.com/docs/en/crx/current/using_crx/content_import_and.html

NOTE:
Since CQ 5.5, CQ Package Manager is completely replaced by CRX Package Manager.

14-8 | Chapter 14 CQ 5.6 System Administrator Training Student Workbook


Using JMX (Java Management Extensions) and the MBeans provided
by CRX
CRX allows external applications to interact with Managed Beans (MBeans) via Java Management
Extensions (JMX). Using generic consoles such as JConsole or domain-specific monitoring applica-
tions, allows getting and setting CRX configurations and properties, as well as the monitoring of
performance and resource usage.

Using JConsole to connect to CRX

ADOBE COPYRIGHT PROTECTED


In order to connect to CRX using JConsole, follow these steps:
1. Open a terminal window.
2. Enter the following command
jconsole

JConsole will start and the JConsole window will appear. JConsole will display a list of local Java
Virtual Machine processes. The list will contain two quickstart processes. Select the quickstart
“CHILD” process from the list of local processes (usually the one with the higher PID).

Connecting to a remote CRX process

In order to connect to a remote CRX process, the JVM that hosts the remote CRX process will need to
be enabled to accept remote JMX connections.
To enable remote JMX connections, the following system property must be set when starting the
JVM:
com.sun.management.jmxremote.port=portNum

In the property above, portNum is the port number through which you want to enable JMX RMI con-
nections. Be sure to specify an unused port number. In addition to publishing an RMI connector for

CQ 5.6 System Administrator Training Student Workbook Chapter 14 | 14-9


local access, setting this property publishes an additional RMI connector in a private read-only regis-
try at the specified port using a well known name, “jmxrmi”

By default, when you enable the JMX agent for remote monitoring, it uses password authentication
based on a password file that needs to be specified using the following system property when start-
ing the Java VM:

com.sun.management.jmxremote.password.file=pwFilePath

See the relevant JMX documentation for detailed instructions on setting up a password file. You can
get more details on http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.
html

ADOBE COPYRIGHT PROTECTED


Example:
$ java
-Dcom.sun.management.jmxremote.password.file=pwFilePath
-Dcom.sun.management.jmxremote.port=8463
-jar ./cq-quickstart.jar

14-10 | Chapter 14 CQ 5.6 System Administrator Training Student Workbook


Using the MBeans provided by CRX

After connecting to the quickstart process, JConsole provides a range of general monitoring tools
for the JVM that CRX is running in.

ADOBE COPYRIGHT PROTECTED


In order to access CRX’s internal monitoring and configuration options, go to the MBeans tab, and
from the hierarchical content tree on the left, select the Attributes or Operations section that you
are interested in. For example, the com.adobe.granite/Repository/Operations section.

Within that section, select the desired attribute or operation in the left pane.

CQ 5.6 System Administrator Training Student Workbook Chapter 14 | 14-11


ADOBE COPYRIGHT PROTECTED

14-12 | Chapter 14 CQ 5.6 System Administrator Training Student Workbook


15

ADOBE COPYRIGHT PROTECTED


Using cURL for Automated
Backup

Exercise 15.1 - Automated backup using cURL


Goal

Backups can be automated using the wget or cURL HTTP clients. This allows you to place the backup
commands in a cron job. In this exercise, you will learn to use the cURL command to automate
backups.

To successfully complete and understand these instructions, you will need:

• A running CQ5 Author instance

• Optional: cURL HTTP client (if necessary you can download cURL from http://curl.haxx.se/
download.html)

The steps described in the previous exercise can also be automated using cURL. Putting all together,
the result is a nice and simple solution to create regular backups.

1. If not already done, open a Command Line window and navigate to the folder where you want
your backup file to be stored.

CQ 5.6 System Administrator Training Student Workbook Chapter 15 | 15-1


NOTE: Make sure that within the URL there are no spaces, otherwise the command will
error out.

2. First, we create a file containing a cookie with our admin user credentials.
Enter the following command (all one line, case-sensitive)

curl –c login.txt –F j_username=admin –F j_password=admin


“http://localhost:4502/libs/granite/core/content/login/j_security_check”

3. Now, create the backup file with the target directory and assign a file name (ending with a .zip

ADOBE COPYRIGHT PROTECTED


extension). Again, all one line and case-sensitive.

curl -b login.txt -F delay=0 -F force=false -F target=<backup’s target directory>/<backup file


name>.zip
“http://localhost:4502/libs/granite/backup/content/admin/backups/”

NOTE: Be sure to use an exact path with no spaces for the Target Directory path.
Or use your cookie:
curl -b login.txt -F delay=0 -F force=false -F
target=/Applications/CQ5.6/1-29-13/backup2.zip
“http://localhost:4502/libs/granite/backup/content/admin/backups/”

More documentation about creating a batch file using curl is available under,
http://dev.day.com/docs/en/cq/current/core/administering/backup_and_restore.html.

The restore procedure is identical to the one described in previous exercise.

NOTE: This URL was still being updated at the time this document was written.

Congratulations! You have successfully created an automated backup script.

15-2 | Chapter 15 CQ 5.6 System Administrator Training Student Workbook


16

ADOBE COPYRIGHT PROTECTED


Cluster Two CQ Instances

A cluster is formed of two or more live servers linked together. Therefore, if one node fails, the other
nodes are active and accessible for your applications and there is no system interruption. This allows you
to recover and re-start failed nodes easily. New nodes can also be added to an existing cluster, allowing
for simple extensibility.

Clustering is beneficial for:

Increased availability

When a server breaks down, or becomes unavailable, the cluster agent relays requests to the
servers that are still running. Service continues without interruption.

Increased performance
Clustering increases system performance and availability even when nodes fail.

While all servers in the cluster are active, you can use their combined computational power.
Therefore, this solution improves performance during normal use. However, if one server breaks
down you lose its performance, so the overall application performance may suffer.

CQ 5.6 System Administrator Training Student Workbook Chapter 16 | 16-1


Goal

The following instructions describe how to set up a cluster in CRX (or CQ) with two cluster nodes on two
separately networked servers.  To successfully complete and understand these instructions, you will
need:

• Two running CQ5 Author instances

Clustering Options

One of the most significant new features within CQ5.4 is in the way CRX Clustering is performed. The

ADOBE COPYRIGHT PROTECTED


shared nothing clustering feature was introduced such that two separate instances of CQ5.4 can run at
the same time without having to share the file-system (e.g. SAN). Both instances are synchronized and
changes made on either one of the instance are replicated to the other one.

In this mode, all the three main storage areas (workspaces, data store, and journal) are stored locally on
each cluster, and synchronized fully over the network.

“Shared Nothing” mode of active clustering complements the existing clustering over a shared
filesystem, and provides system administrators and developers with more flexibility in choosing their
high availability and load balancing architecture:

• Shared Nothing for simple setup, no dependency on network filesystem implementation


and configuration.

• Shared filesystem clustering for managing state of the system on the central networked
filesystem.

• Mixed deployments, where workspace data and journal are in shared nothing mode,
and data store is not in shared nothing mode, then the shared filesystems can be used to
optimize disk space requirements for large deployments.

“Shared Nothing” clustering largely simplifies cloud deployments, as the need to provision and configure
a shared network filesystem for all nodes is removed. Graphical User Interfaces for joining cluster now
only requires a URL to an existing cluster node instead of a path to the shared filesystem.

Share Nothing mode of operation is implemented or enhanced in the following three persistence
modules:

Enhanced: TarPM, which can work in shared nothing mode.

TarJournal PM, which implements journaling using TarPM file format and cluster
synchronization protocol, and works in shared nothing mode.

ClusterDataStore, implementing DataStore persistence working in shared nothing mode.

16-2 | Chapter 16 CQ 5.6 System Administrator Training Student Workbook


Additionally, general clustering stability and performance is improved.

ADOBE COPYRIGHT PROTECTED


With “share nothing”, each instance can live without depending on a shared file-system.

Exercise 16.1-Cluster Setup

There are a few different ways to set up Shared Nothing Clustering , it can be either through:

1. The GUI provided within the CRX settings via the browser

• For instructions of the above, you can follow this link: http://dev.day.com/content/docs/en/
crx/current/administering/cluster.html#GUI%20Setup%20of%20Shared%20Nothing%20
Clustering

2. Or a Manual Cluster Setup.

• For instructions of the above, you can follow this link:


http://dev.day.com/content/docs/en/crx/current/administering/cluster.html#Manual%20
Cluster%20Setup
The documentation for more details on CQ5.4 clustering can be found here:

http://dev.day.com/content/docs/en/crx/current/administering/cluster.html

CQ 5.6 System Administrator Training Student Workbook Chapter 16 | 16-3


NOTE: Although the previous article refers to crx 2.2 much of the information is still relevant to crx 2.3.
The repository configuration console URL has been changed to http://.../crx/explorer/config/index.jsp
and the cluster nodes console to http://.../libs/granite/cluster/content/admin.html.

Manual Cluster Setup

When setting up the Shared Nothing clustering manually, you are able to do this via two different ways
depending on your needs:

ADOBE COPYRIGHT PROTECTED


• Manual Slave Join

• Manual Slave Clone

• A description of both setup types as noted in http://dev.day.com are:

• The first method, manual slave join, is the same as the standard GUI procedure except that it
is done without the GUI. Using this method, when a slave is added, the content of the master
is copied over to it and a new search index on the slave is built from scratch. In cases where
an pre-existing instance with a large amount of content is being “clusterized” this process can
take a long time.

• In such cases, it is recommended to use the second method, manual slave clone. In this
method, the master instance is copied to a new location either at the file system level (i.e., the
crx-quickstart directory is copied over) or using the online backup feature and the new instance
is then adjusted to play the role of slave. This avoids the rebuilding of the index and for large
repositories can save a lot of time.

As already noted, We will do a manual cloning, because this is the most complex set up and will prevent
us from re-indexing our content; this is important and probably a more realistic scenario when either
cloning servers or adding a new cluster node where your main instance already contains a huge amount
of data in it.

Suggested directories:

• <CQ5_Install_dir>/n1/author

• <CQ5_Install_dir>/n2/author

16-4 | Chapter 16 CQ 5.6 System Administrator Training Student Workbook


Steps for Manual Slave Cloning

1. Install an author instance in the “/n1/author” directory by following the steps described in Exercise
1. The difference is that this time we will do the install in the subdirectory “/n1”.

2. Stop the “master” instance found in “/n1” node.

3. Create a new directory called “/n2/author” within the <CQ5_Install_dir>, e.g.: <CQ5_Install_dir>/
n2/author.

ADOBE COPYRIGHT PROTECTED


4. Copy the cq5-author-4502.jar and “license.properties” files from the master to the slave node:

• Copy the following file <CQ5_Install_dir>/n1/author/cq5-author-4502.jar to the <CQ5_


Install_dir>/n2/author/ directory

• For the purpose of training, we are running the slave instance in the same server, therefore
we must run it in a separate port. For this reason, please rename the cq5-author-4502.jar to
use a different port number, let’s use: cq5-author-4504.jar

• Copy the following file <CQ5_Install_dir>/n1/author/license.properties to the <CQ5_Install_


dir>/n2/author/ directory

CQ 5.6 System Administrator Training Student Workbook Chapter 16 | 16-5


5. Copy the crx-quickstart directory of the master to the slave “/n2/author” node

• copy the following directory <CQ5_Install_dir>/n1/author/crx-quickstart to <CQ5_Install_


dir>/n2/author

ADOBE COPYRIGHT PROTECTED


6. In the slave instance “n2/author”

• delete the following file: <CQ5_Install_dir>/n2/author/crx-quickstart/repository/cluster_


node.id

Note that it is necessary to delete this file so that the new instance (SLAVE) can have its own identity.

• Append the IP address of the master instance to the cluster.properties file of the slave:

• Example content of cluster.properties1 file:

16-6 | Chapter 16 CQ 5.6 System Administrator Training Student Workbook


7. Start the Master Instance

ADOBE COPYRIGHT PROTECTED


8. Verify that Master Instance has successfully started

9. Only after the above step has succeeded, you may start the Slave instance. 1

10. You may want to tail the crx/error log files of each instance so that you can see the entries where
each instance is set to its corresponding role, MASTER, SLAVE:

• MASTER error.log entry example:

• SLAVE error.log entry example:

1
The cluster_id property contains the cluster ID, which must be the same for all cluster nodes that
participate in this cluster. By default, this is a randomly generated UUID, but it can be any name.

The addresses property contains a comma separated list of the IP addresses of all nodes in this clus-
ter. This list is used at the startup of each cluster node to connect to the other nodes that are already
running. The list is not needed if all cluster nodes are running on the same computer (which may be
the case in certain circumstances, such as testing).

The members properties (when present) contains a comma separated list of the cluster node IDs that
participate in the cluster. This property is not required for the cluster to work, it is for informational
purposes only.

CQ 5.6 System Administrator Training Student Workbook Chapter 16 | 16-7


Testing the Clustering Instance via Content Page modifications

ADOBE COPYRIGHT PROTECTED


To test that the clustering has been successful, you can do the following test:

1. From the MASTER instance, access the following Content Page:


http://localhost:4502/cf#/content/geometrixx/en.html

2. From the SLAVE instance, access the following Content Page:


http://localhost:4504/cf#/content/geometrixx/en.html

Above images shows the exact same content for both MASTER and SLAVE instances

16-8 | Chapter 16 CQ 5.6 System Administrator Training Student Workbook


3. Make a change in the MASTER instance, change “World Leader in Applied Geometry” to “CHANGE
MADE IN MASTER INSTANCE”

ADOBE COPYRIGHT PROTECTED


In the above diagram, the change has been made in the MASTER instance and the SLAVE has not been
refreshed yet.

4. Refresh the slave instance

Once SLAVE instance has been refreshed, the change is reflected in both instance.

CQ 5.6 System Administrator Training Student Workbook Chapter 16 | 16-9


Verifying the Repository configuration via CRX’s GUI

To finally verify that each CRX instance has been set correctly, you may access each repository’s console
via the following URLs:

1. MASTER: http://localhost:4502/libs/granite/cluster/content/admin.html

ADOBE COPYRIGHT PROTECTED


2. SLAVE: http://localhost:4504/libs/granite/cluster/content/admin.html

Congratulations! You have successfully clustered two Author instances.

16-10 | Chapter 16 CQ 5.6 System Administrator Training Student Workbook


17

ADOBE COPYRIGHT PROTECTED


Creating Custom Log Files

Exercise 17.2- Create a custom Log file


Goal

Various CQ5 log files provide detailed information about the current system state. In addition to the
default system log files, you can also create and customize your own log files. They can help you
better track messages produced by your own applications and to separate them from the default log
entries.

CQ’s logging system is based on SLF4J (Simple Logging Facade for Java), consisting basically of two
elements, a Logging Logger and a Logging Writer. The Writer persists the data provided by the Logger
to a configurable location. Usually, it is a file. The Logger collects data from different components
inside CQ, filters them by requested severity level and redirects the output to configured Writer.

In CQ, we can configure logging for the two major interfaces, CQ and CRX independently. Usually,
we’re more interested what happens under CQ’s cover. In particular cases, we can also setup a higher
verbosity level for the CRX module.

In this example, we will generate a new log file and monitor only messages produced by a specific set
of CQ5 modules. To successfully complete and understand these instructions, you will need:

• A running CQ5 Author instance

CQ 5.6 System Administrator Training Student Workbook Chapter 17 | 17-1


There are 2 ways to configure the CQ’s Logging system: using the Apache Felix web console and CRX.
Adobe recommends to configure everything in CRX and use Apache web console as a viewer only.
The exercise describes both ways.
As an advanced topic, we also configure logging for CRX, to monitor its processes.

To create a custom log file with a specified log level:

First, we create the configuration in CRX, then we review it in the Apache Felix console. A first view
of possible configuration modules in Apache (http://localhost:4502/system/console/configMgr)
shows us two possible configurations: single modules and factory modules. The difference is, a single
module exists only once in CRX, while from a factory module several modules can be created. As an

ADOBE COPYRIGHT PROTECTED


example, the module “Apache Sling Logging Configuration” is a singleton module, while “Apache
Sling Logging Logger Configuration” is a factory module, used to create as many logger modules as
required of the same type.

Create the Logging Logger

In this first example, we create a new logger module based on a factory module (Apache Sling Logging
Logger Configuration) using CRX. It should log protocol messages generated by the modules org.
apache.felix and com.day, filtering out messages with Log severity higher than “Debug”.

1. Open CRXDELite (http://localhost:4502/crx/de/ ) so that you can define a new configuration for
the custom log file.

2. If the folder /apps/geometrixx/config.author doesn’t already exist, do the following:

• Right click on the /apps/geometrixx folder and choose Create...Create Node

o Name: config.author
o Type: sling:Folder

• Save.

3. Using the same steps as described in Step 2, create a subnode of /apps/geometrixxx/config.


author. Use the values:

• Name: org.apache.sling.commons.log.LogManager.factory.config-TRAINING

• Type: sling:OsgiConfig

17-2 | Chapter 17 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
4. Set the following properties on the newly created node:

• Name: org.apache.sling.commons.log.file

• Type: String

• Value: logs/training.log

• Name: org.apache.sling.commons.log.level

• Type: String

• Value: Info

• Name: org.apache.sling.commons.log.pattern

• Type: String

• Value: {0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}] {3} {5}

• Name: org.apache.sling.commons.log.names

• Type: String[] (String Array) (String + Multi)

• Values: org.apache.felix
com.day

CQ 5.6 System Administrator Training Student Workbook Chapter 17 | 17-3


ADOBE COPYRIGHT PROTECTED
Configuration properties for the new log file

5. Don’t forget to save the new properties by clicking Save All.

Create the Logging Writer

A logging writer is only necessary for a configuration that is different to the default one. The default
writer will select a default size of 10MB and 5 as the default number of files. We want to limit the file
size of our logger to 1MB per file and keep 3 log files on the hard disk.

1. Under /apps/geometrixx/config.author, create a node for the new “Apache Sling Logging Writer
Configuration” using the following settings :

• Name: org.apache.sling.commons.log.LogManager.factory.writer-TRAINING

• Type: sling:OsgiConfig

2. Set the following properties on the newly created node:

• Name: org.apache.sling.commons.log.file

• Type: String

• Value: logs/training.log

17-4 | Chapter 17 CQ 5.6 System Administrator Training Student Workbook


■■ Name: org.apache.sling.commons.log.file.size
■■ Type: String
■■ Value: 1MB

■■ Name: org.apache.sling.commons.log.file.number
■■ Type: Long
■■ Value: 3

3. Click Save all to save the settings.

ADOBE COPYRIGHT PROTECTED


Added the Log Writer settings

4. Open some CQ pages to produce log entries and examine your log file.

CQ 5.6 System Administrator Training Student Workbook Chapter 17 | 17-5


Using custom runmodes with Configurations

Now that we know how to configure OSGi bundles and we have author and publish environments, we
can examine how custom runmodes affect bundle configuration. In this next exercise, we will cause
the training log file to have a different name on the publish instance as compared to the author
instance.

1. Copy /apps/geometrixx/config.author to /apps/geometrixx/config.publish.

2. Modify the values of the org.apache.sling.commons.log.file property on the org.

ADOBE COPYRIGHT PROTECTED


apache.sling.commons.log.LogManager.factory.config-TRAINING and org.
apache.sling.commons.log.LogManager.factory.writer-TRAINING nodes

• Name: org.apache.sling.commons.log.file

• Type: String

• Value: logs/mytraining.log

17-6 | Chapter 17 CQ 5.6 System Administrator Training Student Workbook


3. O
pen the Package Manager from the classic Welcome Screen.

ADOBE COPYRIGHT PROTECTED


4. Click Create Package. Name: geometrixxConfig, Group: training.

CQ 5.6 System Administrator Training Student Workbook Chapter 17 | 17-7


5. Define 2 filters: /apps/geometrixx/config.author and /apps/geometrixx/config.publish. Save.

ADOBE COPYRIGHT PROTECTED


6. Build the package.

7. Navigate to the classic Tools console (http://localhost:4502/miscadmin).

8. Expand Packages. Expand training folder.

17-8 | Chapter 17 CQ 5.6 System Administrator Training Student Workbook


9. Select the geometrixxConfig package and Activate.

10. Test your configuration by looking in the crx-quickstart/logs directory to see the training.log file
in the author instance and mytraining.log file in the publish instance.

ADOBE COPYRIGHT PROTECTED


Congratulations! You have deployed application configurations and seen how the instance chooses
the right configuration from the instance runmode.

Create a CRX Logger

In addition to a CQ Logger, we also want to monitor what happens at the CRX level. CRX consists as
well as CQ of different modules. In our example, we’re going to create a new log file to monitor the
activities performed by the indexing service of CRX, which is provided by the underlying JackRabbit
search engine

1. On your browser navigate to http://localhost:4502/system/console/configMgr and look for the


“Apache Sling Logging Logger Configuration”.

2. Click on the button with a plus sign to create a new factory configuration

3. In the section Loggers, add our Logger :

• Log Level: Information

• Log File: logs/lucene.log

• Message Pattern: {0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}] {3} {5}

• Logger: org.apache.jackrabbit.core.query

CQ 5.6 System Administrator Training Student Workbook Chapter 17 | 17-9


ADOBE COPYRIGHT PROTECTED
Logger Configuration
4. Click Save.

After a while, consider to either comment out the additional logger and appender or set its severity
level higher (to Info, Warn, or Error); otherwise, your system is slowed down unnecessarily and a
considerable amount of hard disk space is consumed.

Congratulations! You have successfully created your own custom log files. You can also examine
the configuration of your CQ Logger from the Apache Felix Console at the following URL:

http://localhost:4502/system/console/slinglog

NOTE: Editing a logger configuration created within CRX from the slinglog console is not
recommended as it will replace the configuration nodes corresponding to the logger with a file,
although it will continue to work.

17-10 | Chapter 17 CQ 5.6 System Administrator Training Student Workbook


18

ADOBE COPYRIGHT PROTECTED


User Administration and Security

GOAL

This chapter describes how to configure and manage user authentication and authorization within
the CQ5 scope. To successfully complete and understand these instructions, you will need:

• A running CQ5 author instance

Users and Groups

Users: A user models either a human user or an external system connected to the system. The user
account holds the details needed for accessing CQ. A key purpose of an account is to provide the
information for the authentication and login processes —allowing a user to log in. Each user account
is unique and holds the basic account details, together with the privileges assigned. Users are often
members of Groups, which simplify the allocation of these permissions and/or privileges.

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-1


Groups: Groups are collections of users and/or other groups; these are all called Members of a group.
Their primary purpose is to simplify the maintenance process by reducing the number of entities to
be updated, as a change made to a group is applied to all members of the group.

Both users and groups can be configured using the Security Console. You can manage all users,
groups, and associated permissions using the Security Console. All the procedures described in this
section are performed in this window.

Accessing User Administration with the Security Console

To access CQ WCM security, do one of the following:

ADOBE COPYRIGHT PROTECTED


• From the Welcome screen, or various locations in CQ WCM, click the Users icon

• Navigate directly to http://localhost:4502/libs/cq/security/content/admin.html. Be sure you


log in to CQ SiteAdmin as an administrator.

Security pane used for managing users and groups

The left tree lists all the users and groups currently in the system. You can select the columns you
want displayed, sort the contents of the columns, and even change the order in which the columns
are displayed by dragging the column-header to a new position.

18-2 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
Change order or select what columns to display

Our intention is to create a group and provide some access rights and restrictions as they appear
like in your future projects. After that, we create a user and make him member of the newly created
group. Finally, we test if our environment reacts as expected.

The requirement list for this new group looks like:

• Provide access only to the consoles Websites, Digital Assets, and Inbox. That means, deny
access to the other ones (Campaigns, Community, Tools, Users, Tagging).

• Members of this new group are allowed to modify content of already existing pages located
under Geometrixx > English, add new pages but not delete any.

• Pages located under Geometrixx > French (Français) should be accessed in read-only mode.

• Page Geometrixx > German (Deutsch) is not accessible at all (not visible) to members of the
group.

• Users are allowed to activate/deactivate (replicate) pages located under Geometrixx >
English. Exception is the Services page and all pages stored below. No permission to
replicate pages under Geometrixx > French, except Products page.

• Access to Design mode for Geometrixx pages is allowed.

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-3


To create a Group

Let’s start creating this new group, we call it Legal.

1. In the Security window tree list, click Edit > Create > Create Group.

2. Enter the required details and click Create :

ADOBE COPYRIGHT PROTECTED


Group creation dialog.

Managing Permissions

Warning: please keep in mind that you will be managing permissions for the newly created group Legal
only; although you can manage permissions for any other group or groups, please be careful to restore
them to their original values since you will be needing these permissions for the following exercises.

To add, modify, or delete page permissions, which enable you to allow or deny the right to perform
actions on specific resources.

1. Double-click the Legal group to bring it in to context in the right pane.

2. Click the Permissions tab. The tree map opens.

18-4 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


3. It’s a good idea to provide general read-access to the entire repository. Project-specific restrictions
can be easily added at a later time point. Select the root node. Per default, users have all access
rights denied. To provide read access to the root node, mark the checkbox in the column Read.
Since access rights are automatically inherited to child nodes, all members of the Legal group
have now read access to all nodes in the CRX repository.

4. Click Save.

ADOBE COPYRIGHT PROTECTED


Define the access rights

Manage Access Rights for different Websites

1. Check the checkbox in the column Modify for the start page of the branch you want to provide
access. In our case:/content/geometrixx/en.

2. Do the same for the column Create. The red corner indicates that the item listed has not yet been
saved.

3. Click Save.

4. Navigate to /content/geometrixx/de and uncheck the checkbox in the Read column.

5. Click Save.

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-5


ADOBE COPYRIGHT PROTECTED
Manage access rights for the Web site

Manage Access Rights for Design

1. Check Modify rights on node /etc/designs/geometrixx. Make sure, Read access to designs is still
granted, otherwise, page content cannot be correctly rendered.

2. Click Save to persist your modifications into the CRX repository.

18-6 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
Define access rights for the design pages

Did you notice? We didn’t define any specific access rights for Geometrixx > Francais. They are
automatically set to Read : “allow”, due to inheriting from one of the parent nodes, in our case “/”
(root node). In other words, you need to define access rights only when they differ from the inherited
ones.

Manage replication privileges

Replication privileges are the right to activate or deactivate content, and can be set for groups and
users.

1. Check the Replicate checkbox of the node /content/geometrixx/en. Save to allow all pages
below to be replicable too.

2. Uncheck the Replicate checkbox of /content/geometrixx/en/services. Save.

Now let’s modify the replication privileges for the French branch.

3. Check the Replicate checkbox of the node /content/geometrixx/fr/products.

4. Click Save.

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-7


ADOBE COPYRIGHT PROTECTED
Defining the access rights to replicate pages

As you can see, you can provide fine-grained replication privileges not only for an entire tree branch,
but even at page level.

Users without replication privilege granted still have access to the Activate/Deactivate buttons.
Clicking on them will not have the desired effect immediately. Instead, a workflow is started, which
puts the requested action in the inbox of a privileged user requesting him to approve and finish the
action.

Deny access rights to consoles

We want to deny access to different CQ consoles by simply hiding the icons in the main view. Find a
table below, showing every icon with the corresponding node we need to deny Read access. Feel free
to deny access to any of the console buttons, but don’t forget to display at least one. Otherwise the
users cannot login. Usually it’s the SiteAdmin console, which is accessible to everybody. The
restrictions for different Web sites have already been done in the previous section.

Console Node Path in CRX

Site Admin (Websites) /libs/wcm/core/content/siteadmin

DAM Admin /libs/wcm/core/content/damadmin

Tools /libs/wcm/core/content/misc

18-8 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


NOTE: Be careful when denying access to consoles. If you deny access to all consoles, the user will not
be able to successfully complete the login process.

Console Node Path in CRX

Security (Users) /libs/cq/security/content/admin

Inbox /libs/cq/workflow/content/inbox

Tagging /libs/cq/tagging/content/tagadmin

ADOBE COPYRIGHT PROTECTED


Campaigns /libs/mcm/content/admin

Community /libs/collab/core/content/admin

To create a new user

Add yourself as a user in CQ. Use following steps:

1. In the Security window tree list, click Edit > Create > Create User.

Create a new user

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-9


2. The Create User dialog box appears. Enter the required details and click Create:

ADOBE COPYRIGHT PROTECTED


The “Create User” dialog

3. Double-click your user icon in the left pane. Notice that it is brought into context in the right
pane.

Double-cllick the new user for editing purposes

4. Click the Groups tab. Notice that you don’t belong to any groups.

18-10 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


5. Click the Permissions tab. You will notice that you have no access to any part of the website. The
default permissions policy in CQ5 is “deny all”.

6. No users are specified as potential impersonators of you.

Adding a User and a Group to a Group

The Groups tab shows you which groups the current account belongs to. You can use it to add the
selected account to a group.

1. Double-click the name of your account to assign it to the Legal group.

ADOBE COPYRIGHT PROTECTED


2. Click the Groups tab. Now you will see a list of groups that you already belong to. It is currently
empty.

3. In the tree list, click the Legal group and drag it to the Groups pane. (If you want to add multiple
groups, Shift+click or Control+click those names and drag them.).

Drag the “Legal” group to the Groups pane

4. Click Save.

5. Repeat Steps 1-4 to add the Legal group as a member of the Contributors group.

6. Check your Permissions tab. Why do you now have access to the Geometrixx website?

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-11


ADOBE COPYRIGHT PROTECTED
Displaying the Permissions tab

Now, the User and Groups settings are done.

Switching to somebody else’s identity

We could logout as admin and re-login as another user. It is much easier to impersonate a user to test
its settings.

1. Select Websites console.

2. In the top right-hand corner of the WCM view, open the drop-down menu by the word
Administrator. This menu allows control over logged-in users.

3. In the Impersonate as box, choose your user.

Box to select a user to act on your behalf

18-12 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


The current user is changed to your account.

User on your behalf

ADOBE COPYRIGHT PROTECTED


After you browsed some pages and tested the setting we did, you can finish impersonation by clicking
the impersonated user’s name and selecting Revert to self.

Deleting Users or Groups

To delete a user or a group:

1. In the Security window, select any user or group. If you want to delete multiple items, Shift+click
or Control+click to select them.

2. Click Edit or right-click the item to bring up the context menu. Select Delete. You will be
prompted to confirm that you want to delete.

3. Click OK to confirm

Delete a user from the CQ

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-13


The online documentation http://dev.day.com/content/docs/en/cq/current/administering/security.
html contains more information related to Users and Groups Management.

Congratulations! You have successfully created users and groups and learned to manage those users
and groups. Adobe’s best practices suggest that permissions and privileges be granted and denied on
a group basis. Groups tend to remain stable, whereas users come and go more frequently.

Permissions and Access Control Lists


CQ uses ACLs to determine what actions a user or group can take and where it can perform those
actions.

ADOBE COPYRIGHT PROTECTED


Permissions and ACLs
Permissions define who is allowed to perform which actions on a resource. The permissions are the
result of access control evaluations. You can change the permissions granted/denied to a given user
by selecting or clearing the checkboxes for the individual CQ actions. A check mark indicates that an
action is allowed. No checkmark indicates that an action is denied.

Where the checkmark is located in the grid also indicates what permissions users have in what
locations within CQ (that is, which paths).

The permissions are also applied to any child pages. If a permission is not inherited from the parent
node but has at least one local entry for it, then the following symbols are appended to the check box.
A local entry is one that is created in the CRX 2.3 interface (Wildcard in the path of ACLs currently
can only be created in CRX.)

18-14 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


For an action at a given path:

When you hover over the asterisk or exclamation mark, a tooltip provides more details about the
declared entries. The tooltip is split into two parts:

ADOBE COPYRIGHT PROTECTED


Actions

Actions can be performed on a page (resource). For each page in the hierarchy, you can specify which
action the user is allowed to take on that page. Permissions enable you to allow or deny an action.

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-15


ADOBE COPYRIGHT PROTECTED

Access Control Lists and how they are evaluated


CQ WCM uses Access Control Lists (ACLs) to organize the permissions being applied to the various
pages.

Access Control Lists are made up of the individual permissions and are used to determine the order
in which these permissions are actually applied. The list is formed according to the hierarchy of the
pages under consideration. This list is then scanned bottom-up until the first appropriate permission
to apply to a page is found.

Assume that a user wants to access the following page:

/content/geometrixx/en/products/square

And the ACL list for that page is the following one

18-16 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
The ACL (or permission) that will be applied to the page is ACL 1, related to /content/geometrixx/en/
products/square. In our case, the ACL associated to this page is empty, so CQ will go one level up to
the ACL 2.

ACL 2 will be applied if the user belongs to the group restricted and in this case, the user will have
access denied for this page. If the user is not part of the restricted group, then CQ will go up another
level to ACL 3.

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-17


ACL 3 will be applied if the user belongs to the group geoeditors or double only, in this case the user
will have the access granted to the page. If the user is part of the restricted group, as we saw, the ACL
applied is ACL 2. If the user is not part of the 3 mentioned groups before, CQ will go up one level to
ACL 4.

ACL 4 being empty, if CQ reaches this level it will go up again one level to ACL 5.

ACL 5 will be applied if the user belongs to the author group and then the user will have the access
granted to the page. If the user is not part of the author group, CQ will go up one level to ACL 6.

ACL 6 will be applied if the user belongs to the administrators, contributor, or triple group; if this is the
case, the user will have the access granted to the page. If the user is part of the geoeditors group as
we saw, then CQ would have had already applied ACL 3 and granted access to the page. If the user is

ADOBE COPYRIGHT PROTECTED


not part of any group he will have of course the access denied to the page.

Concurrent Permission on ACLs


When two concurrent (and opposing) permissions are listed on the same ACL for the same resource,
the ACL that is applied for such resource is the one at the bottom:

Suppose we have the following ACL for the same resource under /content/geometrixx/en/products:

If a user is part of the two groups allowed-it and restricted-it, you can see that the access to the page
products is denied, because the ACL deny in read access is the rule at the bottom.

18-18 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


Now if the order of the ACL is the opposite:

ADOBE COPYRIGHT PROTECTED


This time, a user, part of two groups, allowed-it and restricted-it, will have access to the products page
(because the ACL allow in read access is the rule at the bottom).

EXERCISE 18.1 - ACLs


Goal

We are going to create a user who will be part of two groups with two different ACLs, and we will
modify them programmatically.

Steps

1. Create a group “allow-access”; the group should have read access to /content/geometrixx/fr.
Choose the user menu, then on the left pane click on the Edit button. A drop down menu will
allow you to Create your group

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-19


Create the group as following:

ADOBE COPYRIGHT PROTECTED

18-20 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


Open the newly created group and assign read rights to the all the language branches, as following:

ADOBE COPYRIGHT PROTECTED


Don’t forget to click on Save after you’re done.

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-21


2. Create another group “deny-access”, the group should not have read access to /content/
geometrixx/fr.

ADOBE COPYRIGHT PROTECTED


Open the newly created group and assign read rights to the all the language branches, except for the
French one as following.

To do that first provide read access to the /content node

18-22 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


Save your change, refresh your page, expand the content node, and deselect the fr node.

ADOBE COPYRIGHT PROTECTED


Don’t forget to save the changes by clicking on Save.

3. Create the user John Doe; to do that, proceed the same way as you did when creating a new
group, but choose “Create User”

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-23


ADOBE COPYRIGHT PROTECTED
4. Add the user John Doe to the allow-access and deny-access group. For that you’ll have to open
each group, click on Members and Drag & Drop the user John Doe to the member list.

18-24 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


Don’t forget to click on Save each time.

5. Add the user to the group contributors so that he has also access to elements like CSS-JS libraries
as well as the design associated to the page.

6. Open CRX explorer and click on the French node, then in the Security menu choose Access
Control Editor.

ADOBE COPYRIGHT PROTECTED

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-25


You should see the following information:

ADOBE COPYRIGHT PROTECTED


As you can see, the user John Doe doesn’t have access to the French page as the deny rule is the one
at the bottom of the ACL rules applied to the resource /content/geometrixx/fr and therefore takes
precedence.

7. Open the page http://localhost:4502/content/geometrixx/fr.html. in your browser.

Log in as John Doe

18-26 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


As the user John Doe doesn’t have access to the page he will see the following screen:

ADOBE COPYRIGHT PROTECTED


8. Open the ACL editor for the French page. You will change the order of the ACL list by sliding the
deny access ACL on top of the allow access ACL.

CQ 5.6 System Administrator Training Student Workbook Chapter 18 | 18-27


You should see the following:

ADOBE COPYRIGHT PROTECTED


Click on the Apply button, and then Ok.

9. John Doe now should have access to the French page as the ACL rule on the bottom is the one
granting him read access to the node. Get disconnected from the previous session and open the
page http://localhost:4502/content/geometrixx/fr.html. Again, use the user John Doe to log in.

This time you should be able to see the French page.

18-28 | Chapter 18 CQ 5.6 System Administrator Training Student Workbook


19

ADOBE COPYRIGHT PROTECTED


Integrating with LDAP and
Enabling Single Sign On

LDAP (Lightweight Directory Access Protocol) is used for accessing centralized directory services. This
helps reduce the effort required to manage user accounts as they can be accessed by multiple applications.
One such LDAP server is Active Directory. LDAP is often used to achieve Single Sign On, which allows
a user to access multiple applications after logging in once.

LDAP authentication is required to authenticate users stored in a (central) LDAP directory such as
Active Directory. This helps reduce the effort required to manage user accounts. User accounts can be
synchronized between the LDAP server and CRX, with LDAP account details being saved in the CRX
repository. This allows the accounts to be assigned to CRX groups for allocating the required permissions
and privileges.

CRX uses LDAP authentication to authenticate such users, with credentials being passed to the LDAP
server for validation, which is required before allowing access to CRX. To improve performance,
successfully validated credentials can be cached by CRX, with an expiry timeout to ensure that
revalidation does occur after an appropriate period.

When an account is removed from the LDAP server, validation is no longer granted and so access to CRX
is denied. Details of LDAP accounts that are saved in CRX can also be purged from CRX.
Use of such accounts is transparent to your users, they see no difference between user and group accounts
created from LDAP and those created solely in CRX.

You can configure LDAP authentication as a JAAS (Java Authentication and Authorization Service)
module. In this chapter, we will explore integration with an LDAP server and importing users and
groups into the CQ5 instance from the LDAP server.

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-1


EXERCISE 19.1 – Installing a local LDAP Server

Installing and configuring an LDAP server is the first step in integrating CQ5 and an LDAP server. We
will use a local LDAP server in this class for convenience.

LDAP Installation instructions for Windows


1. In the directory distribution/ldap of the training memory stick, you will find a self-extracting
executable named “ApacheDirectoryStudio-win32-x86_<architecture>-<version>”. It contains an
OpenLDAP server that you will configure to be used with CRX. Choose the executable that matches
your Java architecture: 32-bit or 64-bit.

ADOBE COPYRIGHT PROTECTED


2. Double-click on the installer to open it.

3. You may be prompted to confirm that you are sure you want to open the installer. Click Run if such
a popup is displayed.

4. Click Next to follow the instructions and complete the installation. See the next section for
instructions on defining/configuring the LDAP server.

LDAP Installation instructions for MAC OS X


1. In the directory distribution/ldap of the training memory stick, you will find a DMG archive named
“ApacheDirectoryStudio-macosx-<version>.dmg”. It contains an OpenLDAP server that you will
configure to be used with CRX.

2. Double click the DMG file to start the installation process. See the next section for instructions on
defining/configuring the LDAP server.

19-2 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
EXERCISE 19.2 - Setting up/configuring the LDAP server

1. Once installed, go to the server tab and create a new server with the name CQ5LDAP.

Once the server is created, inspect the General tab.

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-3


ADOBE COPYRIGHT PROTECTED
2. Access the partitions tab of the server configuration, click the Add button and enter partitions for
groups (name: Adobe and suffix: ou=groups,dc=adobe,dc=com) and for users (name: Adobe2 and
suffix: ou=users,dc=adobe,dc=com). Save server.xml.

19-4 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


3. Start the server by clicking on the green arrow.

ADOBE COPYRIGHT PROTECTED


4. Create a new connection to the previously created server using the following information:

Connection name: CQ5LDAP


Hostname: localhost
Port: 10389

Click Next.

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-5


5. Fill in the Authentication information:

Bind DN or user: uid=admin, ou=system


Bind password: secret

ADOBE COPYRIGHT PROTECTED


6. Click Finish.

7. In the directory exercises/import_ldap_users_groups of the training memory stick, you will find the
file “users-groups-adobe.ldif”. Import the ldif file into your LDAP server by right-clicking on the
CQ5LDAP connection and selecting Import->LDIF Import from the menu.

19-6 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


8. Browse to the LDIF file and click Finish.

ADOBE COPYRIGHT PROTECTED


9. Now, you have users and groups registered in the LDAP server.

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-7


Configuring CQ5 for LDAP Authentication
CQ5 LDAP configuration information, as presented here and in the documentation, will need to be
adapted to the specifics for your directory server; such as authentication information for logging in to the
directory server, the name of object classes and attributes.

The Java Authentication and Authorization Service (JAAS) works on the basis of “LoginModules”. In
a JAAS configuration file, you can define a sequence of login modules. An incoming request will be
accepted by the first defined login module for authentication. If the login module cannot authenticate,
the request will be passed on to the next login module in the list of definitions.

In this configuration, the first login module that we will configure is the native CRXLoginModule, which

ADOBE COPYRIGHT PROTECTED


tries to authenticate using CRX’s local users:

com.day.crx.core.CRXLoginModule sufficient;

Only if the user of the request cannot be found among the local CRX users, the request will be handed
over to the next login module, which is the LDAP login module:

com.day.crx.security.ldap.LDAPLoginModule required

The LDAP login module will connect to the LDAP server and try to perform a bind
using the given credentials.

To integrate with an LDAP server, you must modify the CRX repository.xml file to configure the
integration. Authenticated users will not be able to log into any workspace when sync mode is set to
“none” and the default security configuration of CRX is used. As a result, if you want to use sync mode,
you need to set the “WorkspaceAccessManager” class to

org.apache.jackrabbit.core.security.simple.SimpleWorkspaceAccessManager

In addition, we will also need to remove the existing <LoginModule> element, as this LoginModule
points to the onboard CRX authentication manager.

The LDAP login module requires some configuration parameters, such as host, port, and authenticated
user of the LDAP server, It also require that which LDAP attribute to translate to a CRX user id, where
to find groups, users, etc. Read the commented section of the “ldap_login.conf” to understand their
meaning.

The LDAP module also has an “autocreate” feature. If enabled, users who were successfully authenticated
on the LDAP server will be imported as local users in CRX. We will use “autocreation” for this class.

19-8 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


EXERCISE 19.3 – Configure CQ to integrate with LDAP

Configure repository.xml

This exercise provides a set of example starting values that you can adapt to your environment.

1. Stop all running CQ5 instances. Create a new CQ5 instance and either start it or simply unpack it.

2. Navigate to the directory <CQ5_install_dir>/crx-quickstart/repository of your CQ5 instance.


Make a copy of repository.xml, e.g., repository.xml.org (just in case you have to revert)

ADOBE COPYRIGHT PROTECTED


3. Open the file repository.xml with a text editor.

4. Add the following bolded code to repository.xml so that users can then login.

<SecurityManager class=”com.day.crx.core.CRXSecurityManager”>
<WorkspaceAccessManager class=”org.apache.jackrabbit.core.
security.simple.SimpleWorkspaceAccessManager”/>
<UserManager class=”com.day.crx.core.CRXUserManagerImpl”>
<param name=”usersPath” value=”/home/users”/>
<param name=”groupsPath” value=”/home/groups”/>
<param name=”defaultDepth” value=”1”/>
</UserManager>
</SecurityManager>
...

5. Remove or comment the <LoginModule> section in the repository configuration

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-9


ADOBE COPYRIGHT PROTECTED
Configure ldap_login.conf
1. Navigate to <CQ5_install_dir>/crx-quickstart/conf. Copy the file <USB stick>/exercises/import_
ldap_users_group/ldap_login.conf into the current directory.

2. Have a look to the provided ldap_login.conf with a text editor of your choice. There you will find the
ldap host, port, user, and password for next time you connect to the LDAP server.

19-10 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


NOTE:
As of CRX 2.0, the CRXLoginModule class is located in new package: com.day.crx.
core.CRXLoginModule. Existing configurations with com.day.crx.security.authentication.
CRXLoginModule are still valid, but deprecated. Users are encouraged to use the login module
from the new package.

The value for the parameter groupRoot cannot contain any spaces. Unnecessary spaces result in a
non-working configuration. For example:
Correct setting: groupRoot=”ou=groups,dc=example,dc=com”
Incorrect setting: groupRoot=”ou=groups, dc=example,dc=com”

The ldap_login.conf configuration information used for this exercise is specific to the LDAP server

ADOBE COPYRIGHT PROTECTED


provided for this exercise. Your configuration information will be different and specific to your
directory server.

3. First, in order for the changes to take effect you will have to shutdown CQ5 and restart it. There are
2 options for restarting CQ5:

a. If you want to start using the start.bat or start batch files, navigate to <CQ5_install_dir>/crx-
quickstart/bin and modify the start/start.bat by changing the bolded line below

* use jaas.config
set CQ_USE_JAAS=true

* config for jaas


set CQ_JAAS_CONFIG=crx-quicsktart/conf/ldap_login.conf

b. You can also start CQ5 from the command line. Navigate to <CQ5_install_dir> and enter

java -Djava.security.auth.login.config=crx-quickstart/conf/ldap_login.
conf -XX:MaxPermSize=128m -Xmx1024M -jar cq5-author-4502.jar –nofork

CRX logs a message in <CQ5_install_dir>/crx-quickstart/logs/error.log confirming which authentication


configuration will be used.

a. Default configuration: default Repository Login configuration

*INFO* [FelixStartLevel]

org.apache.jackrabbit.core.DefaultSecurityManager init: use Repository Login-Configuration
for com.day.crx

b. LDAP: external JAAS configuration

*INFO* [FelixStartLevel] org.apache.jackrabbit.core.DefaultSecurityManager init: use JAAS


login-configuration for com.day.crx

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-11


EXERCISE 19.4 - Assigning Rights to Users imported from LDAP
into CRX

The provided LDAP example configuration file contains 5 groups: ldap-authors, ldap-marketing, ldap-
human-resources, ldap-products, and ldap-management. All 4 other groups are member of the ldap-
authors group.

The users themselves are distributed over the department-specific groups; none of them is explicitly in
the ldap-authors group, since their specific groups are themselves members of the ldap-authors group.
There are 10 users defined in the LDAP server. Usernames: user001 – user010.

ADOBE COPYRIGHT PROTECTED


The password is the same for all users: “1234”. They are organized like this:

1. Log in to CQ5 with any of the test users (e.g., u:user001 p:1234). The user and group information
are imported into CQ5. However, you will receive a login error. At this point, the user does not have
access to any resources in the repository as we have not yet defined permissions for that user.
2. Log in to CQ5 with administrator rights.

NOTE: You may have to clear the browser cache, cookies, and active logins to successfully login
as admin.

3. Refer to the previous exercise and assign appropriate Page Permissions to the ldap-authors group
that was imported from LDAP.

4. Try logging in again as the LDAP user you previously imported, and then try another user (e.g.,
user002)

Purge Users in LDAP


A common situation is to remove a user from the company wide LDAP server. What happens in this case
with the imported CRX users? The CRX status should be synchronized with LDAP, in other words, we
need to remove those users. This can be done in CRX. We simply need to request the list of valid users
from the connected LDAP server.

19-12 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


NOTE: To use all the repository functionality for LDAP synchronization you will need to access
the JMX console.

EXERCISE 19.5 – Purge User007

From our directory, we will remove user007 and synchronize CRX.

1. Access to the LDAP Manager in the LDAP Browser.

ADOBE COPYRIGHT PROTECTED


2. Make sure user007 has previously logged into CQ5 and so has been added as a user in your CQ5
instance. If you can’t log in as that user, go to the LDAP Browser and verify that the user exists and
has a password attribute (userPassword) set.

3. Select and remove user007.

4. Open the Adobe CQ5 Web Console, access the JMX tab and click the link or go directly to
http://localhost:4502/system/console/jmx

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-13


ADOBE COPYRIGHT PROTECTED
5. In the JMX console, select com.adobe.graniteldap.

6. On the resulting LDAP tools page, click the link listOrphanedUsers(). In the popup, click the
Invoke button. A list of users is displayed, which are no longer defined in LDAP and still existing
in the CRX.

19-14 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
7. Close the Orphaned Users window and click the purgeUsers() link. In the emerging window, click
the Invoke button.

Synchronize the CRX with LDAP

In one of the previous scenarios we demonstrated that CRX automatically imports a user, once they are
authorized by LDAP. The drawback was that during a first login attempt, since the user didn’t have any
access control assigned, they got 404 messages. We, as SysAdmins can easily avoid this situation and
prevent users from getting a 404 message upon their first login attempt, if we synchronized the known
groups that are supposed to have access to our site and give them the appropriate ACLs first.

EXERCISE 19.6 – Synchronize the CRX with LDAP

1. For the purpose of this exercise, we will clean up our repository, removing any LDAP users and
groups that we have imported from LDAP.

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-15


ADOBE COPYRIGHT PROTECTED
2. Open the Adobe CQ5 Web Console, access the JMX tab.

3. Click the com.adobe.graniteldap link. In the attributes section, you will see the LDAP server to
which we are currently connected (localhost).

19-16 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


4. We can import a single user to CRX or several users listed as a text file. To
synchronize only user002, you must click syncUser(java.lang.String user) and enter:
cn=user002,ou=users,dc=adobe,dc=com in the user field and click the Invoke button.

ADOBE COPYRIGHT PROTECTED


5. The user will be successfully imported to the CRX, but user002 still has no access permissions. So
we must set the permissions before user002 attempts to log in.

Go to the Users and Groups Console and grant the user’s group (ldap-marketing) with the desired
access rights. We suggest making ldap-marketing a member of the content-authors or contributors
group.

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-17


6. Try to log in to CQ5 with user002. It should work without problems. In case of difficulties, don’t
forget to clear the browser cache or close all browser windows and try again.

Additional Steps
You can also make sure that users are added to a group with appropriate permissions, for example, the
contributors group, when they first log in. You can do this by making a change to the ldap_login.conf
file.

7. Add the line



autocreate.user.membership=”contributor”

to the LDAPLoginModule.

ADOBE COPYRIGHT PROTECTED


8. Restart CQ5 and try logging in with a different user.

LDAP Troubleshooting
When you are having trouble with LDAP, perform the following steps:

Check your ldap_login.conf file.


Use a 3rd-party LDAP browser, for example, JXexplorer, to verify that the provided configuration
parameters are correct and that you can log in and browse your LDAP server.

NOTE:
For Microsoft Active Directory Deployments: On some AD servers, users may
not be able to log in if an LDAP root path for the membership query is not explicitly given. If
this is an issue, add an explicit group path to the ldap_login.conf file: groupRoot=”OU=My
Group,DC=example,DC=com”

Make sure your ldap_login.conf file is used by the AEM or CRX


instance.
Make sure your ldap_login.conf file is used by the AEM or CRX instance. Specifying an absolute path
to the configuration file (with -Djava.security.auth.login.config=...) may help.
If you start the instance with the Quickstart -fork option, specify the path to configuration file using
the -forkargs option.
CRX logs a message (default logging config) confirming that the external JAAS configuration is used:
*INFO * DefaultSecurityManager: init: use JAAS login-configuration for com.day.crx

Increase the log level of the LDAP module to DEBUG and look for
messages in crx/error.log
To track down information, you can increase the log level of the LDAP module to DEBUG and look for
messages in crx/error.log.

19-18 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


Using the Configuration section of the OSGI Console, AEM can be configured to log more detailed
information about LDAP related activity.

1. To do this, under Apache Sling Logging Logger Configuration, add an additional entry with the
following values and click Save:
• Log Level: Debug
• Log File: logs/ldap.log
• Logger: com.day.crx.security.ldap
Optionally, you can use “com.day.crx.security” instead of “com.day.crx.security.ldap” to see all CRX
security-related debug log messages in the logs/crx/ldap.log file.
2. Restart the server.

ADOBE COPYRIGHT PROTECTED


3. Try logging into CRX directly with your LDAP account.
4. Examine the ldap.log and error.log files from CRX to debug for errors.

NOTE:
If you are troubleshooting LDAP for an AEM instance, first try logging CRX at
http://<host>:<port>/crx/explorer. Second, try logging into AEM at http://<host>:<port>. Then
examine the ldap.log and error.log files from CRX and AEM for errors.

Set up proxy logging between CRX/AEM and LDAP.


To set up LDAP proxy debugging:
1. In the terminal, type java -jar crx-quickstart/opt/helpers/proxy.jar <ldap host> <ldap port> <lo-
cal listening port> -b -logfile crx-quickstart/logs/ldapproxy.log.
2. Reconfigure your LDAP host and port in the ldap_login.conf file to point to 127.0.0.1 <local lis-
tening port>.
principal_provider.class=”com.day.crx.security.ldap.principals.LDAPPrincipalProvider”
principal_provider.name=”ldap”
host=”127.0.0.1” port=”3389”

3. Restart the server.


4. Try logging into CRX directly with your LDAP account.
If you are troubleshooting LDAP for an AEM instance, first try logging CRX at
http://<host>:<port>/crx . Second, try logging into AEM at http://<host>:<port>. Then examine
the ldap.log and error.log files from CRX and AEM for errors.
5. Open and examine the ldapproxy.log file for errors.

NOTE:
When proxy logging is configured between CRX/AEM and LDAP, LDAP passwords are sent
and logged in the ldapproxy.log file. Be aware of who views the ldapproxy.log file and who logs in
to the system when the proxy is in use.
Before posting the proxy, log to a Daycare ticket, replace the passwords with something else, for
example asterisks (*).

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-19


Extra Credit Exercise 19.7-Configuring LDAP over SSL
This procedure covers how to configure CRX to authenticate against a LDAP directory server using a
SSL secured connection (also known as Secure LDAP).
1. Configure non-secure LDAP authentication according to the procedure explained in Exercise
19.1-19.2
2. Install the SSL certificates into your Java VM.
This can be done using keytool. More information on this can be found under keytool - Key and
Certificate Management on http://docs.oracle.com/javase/1.4.2/docs/tooldocs/windows/
keytool.html

ADOBE COPYRIGHT PROTECTED


For example, (using the appropriate user account) the following can be used to add certificates to
the Java VM that CRX is running in:
keytool -import -keystore <keystore-location> -file <your-certificate-file>.cer

3. Open ldap_login.conf (in crx-quickstart/conf) and make the following updates:


• Add secure=”true” to the LDAPLoginModule
• Change the port number to the secure ldap port; for example port=”636”
4. (Re-)start CRX with the option
-Djava.security.auth.login.config=crx-quickstart/conf/ldap_login.conf

If you are using SSL, but find that the logins do not work and no users are created, then check your log
file for the following error as this indicates that your SSL certificates are not correctly installed:
LDAPPrincipalProvider: findUser: failed: Cannot connect to the LDAP server
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException:
PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid
certification path to requested target

If you have multiple certificates and they have not installed correctly, add -alias newalias to the key-
tool command.

Configuring LDAP

A standard configuration file looks as follows:


com.day.crx {
com.day.crx.core.CRXLoginModule sufficient;
com.day.crx.security.ldap.LDAPLoginModule required
principal_provider.class=”com.day.crx.security.ldap.principals.
LDAPPrincipalProvider”
host=”ldap.example.com”
port=”389”
secure=”false”
authDn=”uid=admin,ou=system”
authPw=”secret”
userRoot=”ou=users, o=example”
groupRoot=”ou=groups, o=example”
groupMembershipAttribute=”uniquemember”

19-20 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


autocreate=”create”
autocreate.user.membership=”contributor”
autocreate.user.mail=”rep:e-mail”
autocreate.user.cn=”rep:fullname”
autocreate.group.description=”description”
autocreate.group.mail=”rep:e-mail”
autocreate.group.cn=”rep:fullname”
autocreate.path=”direct”
cache.expiration=”600”
cache.maxsize=”100”;
};

ADOBE COPYRIGHT PROTECTED


NOTE:
As of CRX 2.0, the CRXLoginModule class is located in new package: com.day.crx.
core.CRXLoginModule. Existing configurations with com.day.crx.security.authentication.
CRXLoginModule are still valid, but deprecated. Users are encouraged to use the login module
from the new package.

The value for the parameter groupRoot cannot contain any spaces. Unnecessary spaces result in a
non-working configuration. For example:
Correct setting: groupRoot=”ou=groups,dc=example,dc=com”
Incorrect setting: groupRoot=”ou=groups, dc=example,dc=com”

Single Sign on
Single Sign On (SSO) allows a user to access multiple systems after providing authentication creden-
tials (such as a user name and password) once. A separate system (known as the trusted authentica-
tor) performs the authentication and provides Experience Manager with the user credentials.
Experience Manager checks and enforces the access permissions for the user (i.e. determines which
resources the user is allowed to access).

The SSO Authentication Handler service (com.adobe.granite.auth.sso.impl.SsoAuthenticationHandler)


processes the authentication results that the trusted authenticator provides. The SSO Authentication
Handler searches for a ssid (SSO Identifier) as the value of a special attribute in the following locations
in this order:
1. Request Headers
2. Cookies
3. Request Parameters
When a value is found, the search is finished and this value is used.

Configure the following two services to recognize the name of the attribute that stores the ssid:
• The login module.
• The SSO Authentication service.

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-21


You must specify the same attribute name for both services. The attribute is included in the
SimpleCredentials that is provided to Repository.login. The value of the attribute is irrelevant and
ignored, the mere presence of it is important and verified.

Configuring SSO
To configure SSO for a AEM instance, you need to configure the Adobe Granite SSO Authentication
Handler, Various configuration properties are available as follows:

• 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 en-

ADOBE COPYRIGHT PROTECTED


tire 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 es-
caped with a leading “\”.

• Format
Indicates the format in which the user ID is provided. Use:
1. Basic, if the user ID is encoded in the HTTP Basic Authentication format
2. 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

When working with AEM there are several methods of managing the configuration settings for such
services; see *Configuring OSGi for more details and the recommended practices.

For example, for NTLM set:


• Path: as required; for example, /
• Header Names: LOGON_USER
• ID Format: ^<DOMAIN>\\(.+)$

19-22 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


Where <DOMAIN> is replaced by your own domain name.
For CoSign:
• Path: as required; for example, /
• Header Names: remote_user
• ID Format: AsIs

For SiteMinder:
• Path: as required; for example, /
• Header Names: remote_user
• ID Format: AsIs
Confirm that Single Sign On is working as required; including authorization.

ADOBE COPYRIGHT PROTECTED


CAUTION: Make sure that users cannot access AEM directly if SSO is configured.
By requiring users to go through a web server that runs your SSO system’s agent, it is
ensured that no user can directly send a header, cookie, or parameter that will lead the user to be
trusted by AEM, as the agent will filter such information if sent from the outside.
Any user who can directly access your AEM instance without going through the web server will be
able to act as any user by sending the header, cookie, or parameter if the names are known.
Also make sure that of headers, cookies, and request parameter names, you only configure the one
that is required for your SSO setup.

NOTE: Single Sign On is often used in conjunction with LDAP.


If you are also using the Dispatcher with the Microsoft Internet Information Server (IIS), then
additional configuration will be required in:
1. In disp_iis.ini set:
servervariables=1 (forwards IIS server variables as request headers to the remote instance) and
replaceauthorization=1 (replaces any header named “Authorization” other than “Basic” with its
“Basic” equivalent)
2. In IIS:
-Disable Anonymous access
-Enable Integrated Windows authentication

Removing AEM Sign Out Links


When using SSO, sign in and sign out are handled externally, so that AEMs own sign-out links are no
longer applicable and should be removed.

The sign out link on the welcome screen can be removed using the following steps:
1. Overlay /libs/cq/core/components/welcome/welcome.jsp to /apps/cq/core/components/wel-
come/welcome.jsp
2. Remove the following part from the jsp.
<a href=”#” onclick=”signout(‘<%= request.getContextPath() %>’);”
class=”signout”><%= i18n.get(“sign out”, “welcome screen”) %>

To remove the sign out link that is available in the user’s personal menu in the top-right corner, follow
these steps:

CQ 5.6 System Administrator Training Student Workbook Chapter 19 | 19-23


1. Overlay /libs/cq/ui/widgets/source/widgets/UserInfo.js to /apps/cq/ui/widgets/source/widgets/
UserInfo.js
2. Remove the following part from the file:
menu.addMenuItem({
“text”:CQ.I18n.getMessage(“Sign out”),
“cls”: “cq-userinfo-logout”,
“handler”: this.logout
});
menu.addSeparator();

ADOBE COPYRIGHT PROTECTED

19-24 | Chapter 19 CQ 5.6 System Administrator Training Student Workbook


20

ADOBE COPYRIGHT PROTECTED


Performance

Exercise 20.1-Performance Tuning


Goal

The following instructions explain how to monitor Page response times, in addition to finding slow
Page responses. This will allow you to create a more robust/scalable CQ application, even with
limited hardware. To successfully complete and understand these instructions, you will need:

• A running CQ5 Author instance

• An Adobe provided “rlog.jar” tool (already installed with your CQ5 instance -<install dir>/
crx-quickstart/opt/helpers)

What performance optimization concepts should I consider?

A key issue is the time your Web site takes to respond to visitor requests. Although this value will vary
for each request, an average target value can be defined. Once this value is proven to be both
achievable and maintainable, it can be used to monitor the performance of the Web site and indicate
the development of potential problems.

The response times you will be aiming for will be different on the author and publish environments,
reflecting the different characteristics of the target audience:

CQ 5.6 System Administrator Training Student Workbook Chapter 20 | 20-1


Author Environment

This environment is used by authors entering and updating content, so it must  cater for a small
number of users who each generate a high number of performance intensive requests when updating
content pages and the individual elements on those pages.

Publish Environment

This environment contains content that you make available to your users, where the number of
requests is even greater and the speed is just as vital; since the nature of the requests is less dynamic,

ADOBE COPYRIGHT PROTECTED


additional performance enhancing mechanisms can be leveraged, such as that the content is cached
or load-balancing is applied.

Performance Optimization Methodology

A performance optimization methodology for CQ projects can be summed up to five very simple
rules that can be followed to avoid performance issues from the get go.  These rules, to a large degree,
apply to Web projects in general, and are relevant to project managers and system administrators to
ensure that their projects will not face performance challenges when launch time comes.

Planning for Optimization

Around 10% of the project effort should be planned for the performance optimization phase. Of
course, the actual performance optimization requirements will depend on the level of complexity of
a project and the experience of the development team. While your project may ultimately not require
all of the allocated time, it is good practice to always plan for performance optimization in that
suggested range.

Whenever possible, a project should first be soft-launched to a limited audience in order to gather
real-life experience and perform further optimizations, without the additional pressure that follows a
full announcement.

Once you are “live”, performance optimization is not over. This is the point in time when you
experience the “real” load on your system. It is important to plan for additional adjustments after the
launch.

Since your system load changes and the performance profiles of your system shifts over time, a
performance “tune-up” or “health-check” should be scheduled at 6-12 months intervals.

20-2 | Chapter 20 CQ 5.6 System Administrator Training Student Workbook


Simulate Reality

If you go live with a Web site and you find out after the launch that you run into performance issues
there is only one reason for that:—Your load and performance tests did not simulate reality close
enough.

Simulating reality is difficult and how much effort you will reasonably want to invest into getting
“real” depends on the nature of your project. “Real” means not just “real code” and “real traffic”,
but also “real content”, especially regarding content size and structure. Keep in mind that your
templates may behave completely different depending on the size and structure of the repository.

ADOBE COPYRIGHT PROTECTED


Establish Solid Goals

The importance of properly establishing performance goals is not to be underestimated. Often, once


people are focused on specific performance goals, it is very hard to change these goals afterwards, even
if they are based on wild assumptions.

Establishing good, solid performance goals is really one of the trickiest areas. It is often best to collect
real life logs and benchmarks from a comparable Web site (for example the new Web site’s
predecessor).

Stay Relevant

It is important to optimize one bottleneck at a time. If you do things in parallel without validating the
impact of the one optimization, you will lose track of which optimization measure actually helped.

Agile Iteration Cycles

Performance tuning is an iterative process that involves, measuring, analysis, optimization, and
validation until the goal is reached. In order to properly take this aspect into account, implement
an agile validation process in the optimization phase rather than a more heavy-weight testing process
after each iteration.

This largely means that the administrator implementing the optimization should have a quick way to
tell if the optimization has already reached the goal, which is valuable information, because when the
goal is reached, optimization is over.

CQ 5.6 System Administrator Training Student Workbook Chapter 20 | 20-3


Basic Performance Guidelines

Generally speaking, keep your uncached html requests to less than 100ms.  More specifically, the
following may serve as a guideline:

• 70% of the requests for pages should be responded to in less than 100ms.

• 25% of the requests for pages should get a response within 100ms-300ms.

• 4% of the requests for pages should get a response within 300ms-500ms.

ADOBE COPYRIGHT PROTECTED


• 1% of the requests for pages should get a response within 500ms-1000ms.

• No pages should respond slower than 1 second.

The above numbers assume the following conditions:

• measured on publish (no authoring environment and/or CFC overhead)

• measured on the server (no network overhead)

• not cached (no CQ-output cache, no Dispatcher cache)

• only for complex items with many dependencies (HTML, JS, PDF, etc.)

• no other load on the system

There are a certain number of issues that frequently contribute to performance issues which mainly
revolve around (a) dispatcher caching inefficiency and (b) the use of queries in normal display
templates. JVM and OS level tuning usually do not lead to big leaps in performance and should
therefore be performed at the very tail end of the optimization cycle.

Your best friends during a usual performance optimization exercise are the request.log, component
based timing, and last but not least - a Java profiler.

To monitor Page response times:

1. Navigate to and open the file request.log located at <CQ5_install_dir>/crx-quickstart/logs.

2. Request a Page in author that utilizes your Training Template and Components.

• e.g. /content/training_site/english/training_company

20-4 | Chapter 20 CQ 5.6 System Administrator Training Student Workbook


3. Review the response times directly related to the previous step’s request.

• A Page request of /content/training_site/english/training_company

NOTE: If you do not have a training application, then you can use the Geometrixx demo site at
/content/geometrixx/en/company.htm

ADOBE COPYRIGHT PROTECTED


Request.log response time

NOTE: Though this is clearly the response time of a Page while in author, it is good practice to
be able to identify where response times are located (request.log) and how to identify a specific
Page request/ response in the log file itself. Ideally, this test would occur on the publish
instance to get a better idea of its expected behavior in production.

Congratulations! You have successfully reviewed the response time of a Page in CQ using the request.
log. Again, this will aid your development in being able to monitor response times of Pages that
implement custom Templates and Components, and comparing said time to your project goals.

CQ 5.6 System Administrator Training Student Workbook Chapter 20 | 20-5


To monitor Component based timing:

NOTE: If you do not have a training application then you can use the Geometrixx demo site at
/content/geometrixx/en/company.html

1. Request a Page in author that utilizes your Training Template and Components.

• e.g. /content/training_site/english/training_company

ADOBE COPYRIGHT PROTECTED


2. View the HTML source of the Page requested in step 1.

3. Navigate to and select the “Timing chart URL” located in the HTML source.

• You will find this URL most likely near the bottom of the HTML source, as it is generated by
the foundation timing Component

HTML source timing chart url

4. Copy the “Timing chart URL”,and then paste it in the address bar of your favorite Web browser.

5. Investigate the visual output to identify any Component that may be causing a slow response
time.

20-6 | Chapter 20 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
Timing chart component response times

NOTE: The light blue color identifies time consumed by request operations prior to the
Component/JSP execution. The dark blue color identifies how long the Component/JSP took to
respond.

Congratulations! You have successfully monitored component based timing using the foundation
timing component. Again, this will aid your development in being able to monitor the response times
of specific components within the context of an actual page/template request. Next, we will focus on
how to find long lasting requests.

To find long lasting requests/responses:

1. Navigate to the helper tool rlog.jar located in <CQ5_install_dir>/crx-quickstart/opt/helpers


using your command line.

CQ 5.6 System Administrator Training Student Workbook Chapter 20 | 20-7


OS location of the “rlog.jar” file
2. Enter the command java -jar rlog.jar in your command line to get help concerning possible

ADOBE COPYRIGHT PROTECTED


arguments.

DOS rlog.jar help

3. Enter the command java -jar rlog.jar -n 10 ../../logs/request.log in your command line to view
the first 10 requests with the longest response duration.

20-8 | Chapter 20 CQ 5.6 System Administrator Training Student Workbook


ADOBE COPYRIGHT PROTECTED
rlog.jar view of 10 longest requests/responses

NOTE: Essentially, the “rlog.jar” tool is parsing the “request.log” file to find and display the 10 longest
requests/responses cycles. You can use this information to further investigate what may be the cause of
these long response times.

Congratulations! You have successfully found and displayed long lasting requests/responses in CQ. Again,
this is just one of many tools to help you meet your project’s performance goals. Finally, we will view timing
statistics for Page rendering.

To view timing statistics for Page rendering:

1. Request a Page in CQ5 SiteAdmin that implements your Training Template and Components.

• e.g. /content/training_site/english/training_company

2. Press keys Ctrl-Shift-U (same on Mac OS X: Ctrl-Shift-U) to view the timing statistics for that
Page.

CQ 5.6 System Administrator Training Student Workbook Chapter 20 | 20-9


ADOBE COPYRIGHT PROTECTED
Page timing statistics

Congratulations! You have successfully viewed the timing statistics for a Page. Again, this is to help
you in reviewing the performance of specific Pages, so that you may meet your project’s performance
goals.

To investigate a system where some processes are really slow, but not blocking:

A simple CPU profiling tool is included with CRX 2.2.x. To start it, open:
http://localhost:4502/crx/diagnostic/prof.jsp

1. Open the Adobe CQ5 Web Console and navigate to Main -> Profiler.

2. click on Options >

3. Set the sample interval and stack depth (or use the default)

4. Click “Start Collecting” and wait to collect data while your slow process executes

5. Click “Stop” to stop data collection

6. Examine the results

Additional External Tools:

You can purchase YourKit Java Profiler from www.yourkit.com, it’s a very powerful profiler.

20-10 | Chapter 20 CQ 5.6 System Administrator Training Student Workbook


21

ADOBE COPYRIGHT PROTECTED


Find Unclosed JCR Sessions

GOAL

If an application opens JCR sessions explicitly, it is the responsibility of the developer to ensure the
proper closure of these sessions. If not, such sessions will not be subject of garbage collection and
thus will stay in memory, causing above listed symptoms. Each JCR session (CRXSession) creates and
maintains its own set of caches which adds to the overall resource consumption.

In this exercise, we will generate stack traces for the CQ5 instance and analyze those traces with
session_analyzer.jar.  To successfully complete and understand these instructions, you will need:

• A running CQ5 Author instance

• session_analyzer.jar from the USB stick under exercises folder

Exercise 21.1-Finding Unclosed Sessions

1. Discover the process id for the CQ5 process by issuing the following command in a command line
window:

  jps -l (l is a small L)
 

NOTE: This is a Unix command. On Windows platforms, you can use the Task Manager by
configuring its display options to find the process id.

CQ 5.6 System Administrator Training Student Workbook Chapter 21 | 21-1


Displays the process id for the running CQ5 instances

ADOBE COPYRIGHT PROTECTED


2. Run following command to determine the overall number of current CRXSessions held in
memory:

jmap -histo <pid> | grep CRXSessionImpl

Displays the number of current CRXSessions

NOTE: On Windows platforms, grep is not available as standard, but there are some utilities that
work in a similar way such as findstr, or you can pipe the output to a file,
jmap -histo <pid> > somefile.txt and then just search for the string CRXSessionImpl.

jmap is installed as part of the java installation —you may need to specify a path to it.

The second column of the output is the instance count, which means that many sessions are not
closed (and actually reside in-memory). If this number is significantly higher than 500, then there is
a problem with CRXSessions in your application.

Further analysis is required to find out who actually opened CRXSessions and more importantly, did
not close them.  CRX comes with a built-in debug-mode, which allows you to backtrack to the
defect code. What this debug-mode does is dump a complete stack-trace to the error log file
whenever a CRXSession is opened. It also logs an entry whenever a CRXSession is closed again.

21-2 | Chapter 21 CQ 5.6 System Administrator Training Student Workbook


NOTE: Depending on the usage of the system, the standard-out logfile might grow quite fast.

3. To enable the session debug-mode, start CQ5 with an additional parameter:

    java -Dcrx.debug.sessions=true -jar cq5-author-4502.jar -nofork


java –Xmx1024m –XX:MaxPermSize=256 -Dcrx.debug.sessions=true –jar cq5-author-4502.jar

4. As soon as you have gathered enough stacktraces, stop the instance.

5. Run the session_analyzer.jar with the following command:

ADOBE COPYRIGHT PROTECTED


   java -jar session_analyzer.jar <error_log> | sort > output.txt

This will generate a new file output.txt that contains the stack trace of unclosed sessions, sorted by
stack trace content. Each stack trace is one line, and ‘compressed’ a bit (repeated prefixes are
removed). The session id is at the end of the line.

com.day.crx.j2ee.JCRExplorerServlet.login(JCRExplorerServlet.java:521)
ResourceServlet.spoolResource(ResourceServlet.java:148)
java.lang.Thread.run(Thread.java:595): session# 10023

In this example session #10023 was not closed, and the stack trace included the given lines when
the session was opened.  Based on this output, you should be able to find the defect code location
and fix the problem.

Congratulations!  You have successfully found and analyzed unclosed JCR sessions.

CQ 5.6 System Administrator Training Student Workbook Chapter 21 | 21-3


22

ADOBE COPYRIGHT PROTECTED


Security Checklists

CRX Security Checklist

Installation Settings
Determine the Security Level—Make sure that there is no “allow Access Control Entry on the root node
(/) for the principal “everyone”. This would allow everyone to read/write/etc content.

Switch from Low to High Security—To switch from low to high security, you need to remove all access
control policies for the principal everyone on the root node. This will deny the default read/write access
to content available to any logged-in user. After this you will be able to configure authorization for your
repository groups and users according to your needs.

Passwords

Change the CRX Admin Password, before you use CRX productively; we recommend that you change the
default passwords. The default password for the admin account is admin.
Password protect the Anonymous account.

CQ 5.6 System Administrator Training Student Workbook Chapter 23 | 22-1


Issues with Cross-Site Request Forgery

To address known security issues with Cross-Site Request Forgery (CSRF) in CRX WebDAV and Apache
Sling, you need to configure the Referrer filter.

The referrer filter service is an OSGi service that allows you to configure:

• which http methods should be filtered

• whether an empty referrer header is allowed

ADOBE COPYRIGHT PROTECTED


• and a white list of servers to be allowed in addition to the server host

By default, all variations of localhost and the current host names the server is bound to are in the white
list.

- File System Security

Prohibit illegitimate write access to CRX installation—Write access to files in a CRX installation or its
backups must only be allowed to users whose role in CRX is that of an admin. Write access to the
installation folders allows users to reconfigure CRX through OSGi configuration files, which allows
immediate rights elevation to admin.

Prohibit illegitimate read access to log files—Log files can potentially disclose information that reveals
attack vectors. As such, access to read log files must only be granted to trusted entities.

- Securing HTTP Communication

As with any application available on the internet, any confidential information must be secured on a
transport level.

The need for this will vary depending on the content stored in your system.

To ensure that the system cannot be compromised, the following should be secured through SSL for any
CRX system, irrespective of the content in the system.

• Access to the OSGi Console

• Access by the admin user

• Access to user information

• Inter-system communication if it goes over the public internet

22-2 | Chapter 23 CQ 5.6 System Administrator Training Student Workbook


- Sanity Checks prior to Go-Live

- Securing HTTP Communication

As with any application available on the internet, any confidential information must be secured on a
transport level.

The need for this will vary depending on the content stored in your system.

To ensure that the system cannot be compromised, the following should be secured through SSL for any
CRX system, irrespective of the content in the system.

ADOBE COPYRIGHT PROTECTED


• Access to the OSGi Console

• Access by the admin user

• Access to user information

• Inter-system communication if it goes over the public internet.

- Sanity Checks prior to Go-Live

CQ Security Checklist

Various areas are impacted and you should review all (in detail, the following list is meant to provide an
introductory overview) to see, which can be used to help protect your implementation:

• Change Default Passwords


An out-of-the-box installation of CQ includes various accounts to enable you to administrate
and use the instance.
In particular, we strongly recommend that after installation you change the passwords for the
privileged (admin) account(s).

• Configure replication and transport users


Create users with specific, restricted access rights for building replication content (Author
environment) and for receiving content (Publish environments) instead of using the admin
user.

• Disable WebDAV
CRX and CQ come with WebDAV support that lets you display and edit the repository
content. Setting up WebDAV gives you direct access to the content repository through your
desktop.
WebDAV should be disabled on the publish environment.

CQ 5.6 System Administrator Training Student Workbook Chapter 23 | 22-3


• Restrict Access via the Dispatcher
The Dispatcher filter can be used to allow or deny external access to specific areas of CQ. To
protect your instance, you should configure the Dispatcher to restrict external access as far as
possible.

• Protect against Cross-Site Scripting (XSS)


Cross-site scripting (XSS) allows attackers to inject code into web pages viewed by other
users. This security vulnerability can be exploited by malicious web users to bypass access
controls.
CQ applies the principle of filtering all user-supplied content upon output. Additionally, a
web application firewall can be configured to add protection.

ADOBE COPYRIGHT PROTECTED


• Preventing Denial of Service (DoS) Attacks
A denial of service (DoS) attack is an attempt to make a computer resource unavailable to
its intended users. This is often done by overloading the resource.
There are a few methods that can be used with CQ to help prevent such attacks.

• Default Access to User Profile(s) is everyone


By default, everyone (the built-in group) has read access to all user profile(s).
If such access is not appropriate for your installation you can change these default settings.

• Issues with Cross-Site Request Forgery (CSRF)


This is a security issue from the CRX Security Checklist, which is also appropriate to CQ.
To address known security issues with (CSRF) in CRX WebDAV and Apache Sling, you can
configure the Referrer filter.

• Disable the CQ WCM Debug Filter on production systems


This is useful when developing as it allows the use of suffixes, but should be disabled on a
production instance to ensure performance and security.

• Clickjacking
Configuring your webserver can help prevent clickjacking.

In one of the previous exercises, we learned how to protect our CQ instance(s) from unwanted visitors.
Now let’s make our system more secure. Out-of-the-box, CQ is installed to accept any kind of requests,
it’s our responsibility to control what kind of requests we want to provide to visitors and refuse those
requests, which can endanger our data. The Publisher instances are typically exposed directly to visitor’s
access. We did some restrictions to interfaces like /crx, /admin, etc. as we configured the CQ Dispatcher.

22-4 | Chapter 23 CQ 5.6 System Administrator Training Student Workbook


In a default environment, WebDAV access is allowed by CQ and cannot be filtered out by the CQ
Dispatcher, since WebDAV is based on HTTP and requests to / are generally allowed. We want to restrict
only WebDAV access to Publish1.

Exercise 22.1-Disable WebDAV & Debug Mode

1. Open the Adobe CQ5 Web Console on the Publish instance. Click on the OSGi drop-down menu and
Select Configuration. Navigate to the “Day CQ WCM Debug Filter”.

2. Uncheck the checkbox “Enabled”.

ADOBE COPYRIGHT PROTECTED


NOTE: For the purposes of expediency, we are using the Console to set this value. In production,
you will create a sling:Osgi node of the name com.day.cq.wcm.core.impl.WCMDebugFiilter and
set properties on that node. Then you will be able to create different configurations of the
Debug Filter for different environments and distribute them automatically through CRX
Content packages.

Webdav bundle after it’s stopped

Test your modification, try to establish a WebDAV connection to this instance. As expected, you should not
be allowed to connect, while an attempt to connect on the unprotected Publish2 should work.

Disable Debug Mode

Developers can get more detailed information about the scripts running in background to render
the page content as desired. You can test it by appending the parameter “?debug=layout” to any
URL, e.g. http://localhost:4502/content/geometrixx/en.html?debug=layout. The page is now
displayed along with more component details. As you can imagine, we want to prevent visitors to
view the internals of our installation. To disable this “debug mode” on Publisher(s), follow these
steps :

1. Open the OSGi console “Apache Felix” on the Publisher instance and navigate to configuration
module “CQ Day CQ WCM Debug Filter”.

2. Uncheck the checkbox “Enabled”.

CQ 5.6 System Administrator Training Student Workbook Chapter 23 | 22-5


ADOBE COPYRIGHT PROTECTED
Configuration screen of “Day CQ WCM Debug Filter”

3. Save your settings.

Test your modification. You have 2 Publish instances, one protected, one vulnerable. See and
understand the difference.

22-6 | Chapter 23 CQ 5.6 System Administrator Training Student Workbook


Appendix

ADOBE COPYRIGHT PROTECTED


Configuring the CQ 5.5
Dispatcher on MacOS X

The following instructions describe how to configure the Adobe CQ 5.5 Dispatcher on a Mac OS X
version 10.[6-7].X, and the Apache web server 2.2 that comes already installed on Mac OS X. This
section provides instructions that replace Exercise 9 - Add the Dispatcher to the Apache WebServer.

You may want to make sure the Apache Web Server already installed in your MacOS X is up and
running in your system. Enter your system preferences, then click on sharing, and then start your
“Web Sharing” by selecting its checkbox.

CQ 5.6 System Administrator Training Student Workbook Appendix | A-1


ADOBE COPYRIGHT PROTECTED
and you should be able to browse your computer’s Web site:

Installing the Dispatcher module into Apache

1. Open a Terminal (command window). The “Terminal” application is located under /Applications/
Utilities/Terminal.app.

2. Enter the following command to verify the installed apache web server version.
$ httpd -v

3. Unzip the latest CQ Dispatcher build, appropriate for your operating system, to a temporary
directory. The CQ Dispatcher files are located on the memory stick under <USB>/distribution/
dispatcher (dispatcher-apache2.2-darwin-x86-64-4.1.0.tgz). If the appropriate dispatcher is not
in the memory stick you may download it from package share http://localhost:4502/crx/
packageshare/.

4. Open a Terminal (command window).

A-2 | Appendix CQ 5.6 System Administrator Training Student Workbook


5. Enter the following commands to open the normally hidden in the MacOS X Finder, /usr and /
private folders:

• $ open /usr

• $ open /etc

6. In the new Finder window of /usr navigate to the folder /usr/libexec/apache2 . Copy the
dispatcher-apache2.2-4.1.0.so file from the unpacked archive to this location.

7. Once you’ve done this, you should create a symbolic link in order to have an easier name to use
in your scripts, in the terminal window type this:

ADOBE COPYRIGHT PROTECTED


cd /usr/libexec/apache2/

and then create the “symbolic link”:

ln -s dispatcher-apache2.2-4.1.0.so mod_dispatcher.so

NOTE: You may not have the rights to do so, in that case you have to use the command sudo (to
launch commands as root on your machine)

sudo ln -s dispatcher-apache2.2-4.1.0.so mod_dispatcher.so

After doing so, you will be able to see in the finder the file mod_dispatcher.so in the /usr/libexec/
apache2/ folder.

“Finder” showing the CQ Dispatcher module

CQ 5.6 System Administrator Training Student Workbook Appendix | A-3


8. Next, in the finder window of /etc navigate to /etc/apache2 and copy the dispatcher.any file from
the unpacked dispatcher archive to this location.

Configuring httpd.conf

Tell Apache about the Dispatcher. In the folder /private/etc/apache2, you will find the httpd.conf file
(we are using the default apache server that comes with MacOS X). You can also use the httpd.conf
file attached that comes with the dispatcher archive from the USB memory stick.

ADOBE COPYRIGHT PROTECTED


1. Add the following text to the httpd.conf file at the end of the first Load Module section (somewhere
before the #Apple specific modules):
...
# LoadModule foo_module libexec/mod_foo.so
# Add to the end of the LoadModule section
LoadModule dispatcher_module libexec/apache2/mod_dispatcher.so

2. Add the following text to the httpd.conf file at the end of the Load Module section, right after the
ServerAdmin you@example.com setting.

<IfModule disp_apache2.c>
# location of the configuration file. eg: ‘conf/dispatcher.any’
DispatcherConfig /etc/apache2/dispatcher.any
# location of the dispatcher log file. Just an example, use var’
DispatcherLog /etc/apache2/dispatcher.log
# log level for the dispatcher log
# 0 Errors
# 1 Warnings
# 2 Infos
# 3 Debug
DispatcherLogLevel 3.
DispatcherNoServerHeader 1
DispatcherDeclineRoot 0
</IfModule>

3. Also add the SetHandler statement to the context of your configuration (<Directory>, <Location>)
for the Dispatcher to handle the incoming requests. The simplest setting is to replace the entire
default directory configuration.

A-4 | Appendix CQ 5.6 System Administrator Training Student Workbook


First, we configure the “default” to be a very restrictive set of features.

<Directory />

<IfModule disp_apache2.c>

SetHandler dispatcher-handler
ModMimeUsePathInfo On

</IfModule>

ADOBE COPYRIGHT PROTECTED


Options FollowSymLinks
AllowOverride None
</Directory>

Configuring the Dispatcher

Follow the instructions for the Exercise 10 - Configure the Dispatcher with the following exceptions:

When configuring the cache use the following /docroot

/cache
{
# The docroot must be equal to the document root of the webserver. The
# dispatcher will store files relative to this directory and subsequent
# requests may be “declined” by the dispatcher, allowing the webserver
# to deliver them just like static files.
/docroot “/Library/WebServer/Documents”

Update the publish instance port number on the dispatcher.any file

/renders
{
/rend01
{
# Hostname or IP of the render
/hostname “127.0.0.1”
# Port of the render
/port “4503”
# Connect timeout in milliseconds, 0 to wait indefinitely
# /timeout “0”
}
}

CQ 5.6 System Administrator Training Student Workbook Appendix | A-5


The http server process must have read/write access to that folder in order to write the cache files.
You can of course choose another folder but then you have to be sure that the httpd server daemon
has read and write access to /Library/WebServer/Documents (use chown and chgrp if necessary).

4. Restart Apache by issuing the following command from a Terminal window.


$sudo apachectl graceful
Restart “Web Sharing”

5. Access the Geometrixx website using the following URLs:

ADOBE COPYRIGHT PROTECTED


    Author instance: http://localhost:4502/content/geometrixx.html

    Publish instance: http://localhost:4503/content/geometrixx.html

    Webserver/Dispatcher: http://localhost/content/geometrixx.html

Test our configuration: The cached pages should be showing up in the Web server’s document root.
If you now navigate to the Web server document root directory, you should see directories and files
appear as the CQ Dispatcher and Web server begin to cache pages.
Congratulations! You have successfully configured the CQ Dispatcher with the Apache Web server
already installed on your Mac OS X, cached pages in the Web server document root, and accessed
activated content pages from the Web server.

A-6 | Appendix CQ 5.6 System Administrator Training Student Workbook

Vous aimerez peut-être aussi