Repository Setup

You are reading the CRX 2.3 version of Repository Setup.
This documentation is also available for the following versions: CRX 2.2 CRX 2.1 CRX 2.0 (for CQ 5.3)

The CRX repository settings allow you to configure many aspects of how CRX runs.

The CRX quickstart installation uses predefined repository settings. You should only need to edit the configuration files to modify advanced options.

Note

You can configure the workspace settings separately from the repository settings.

Editing Repository Settings in the Configuration Files

For in-depth configuration changes, you have to edit the CRX configuration files. These are stored in the CRX Web application, and there are two ways to change them:

Use an editor that can edit files in compressed Web application archives. After you have changed a file, you need to delete the runtime folder of your servlet engine to make the changes effective.
Unpack the Web application, so that it is a normal folder named crx-explorer_crx.war instead of a compressed folder. Now you can edit the files using a standard text editor.

To unpack the CRX Web application, proceed as follows on Windows, and with WinZip installed:

In the Windows explorer, go to the folder <crx-quickstart>/server/webapps in your CRX installation folder. The folder contains the file crx-explorer_crx.war, which is a compressed Web application archive.
Rename the file crx-explorer_crx.war to crx-explorer_crx.war.zip. If you have WinZip installed, the file is now displayed as an archive file.
Right-click the file, point to WinZip, and then click Extract to folder ... /crx-explorer_crx.war. WinZip now extracts the archive file, and you have an uncompressed folder named crx-explorer_crx.war.

The configuration files are:

web.xml
located in WEB-INF/ of the war file extracted above (crx-explorer_crx.war/WEB-INF).
repository.xml
located in crx-quickstart/repository/
(crx-explorer_crx.war/WEB-INF contains only a template/default/example configuration - repository-template.xml).
config.xml
located in WEB-INF/ of the war file extracted above (crx-explorer_crx.war/WEB-INF).
cqresource.xml
located in WEB-INF/ of the war file extracted above (crx-explorer_crx.war/WEB-INF).

CRX also provides an option in the console for Checking Repository Integrity. This can be used after you have made your changes.

Note

If you change values in the configuration files, make a note of the values you have changed.

The CRX upgrade does not migrate values changed, so you have to re-enter the changes in the new CRX configuration.

Changing File Locations

If you change the location of CRX repository files, do this before you start CRX for the first time. When CRX starts up, it will create the necessary files at the locations you have specified.

If you change the location of existing files, CRX is unable to access these files, and may be unable to re-create them at the new location. In these cases, the repository is broken, and you have to remove the other existing files, so CRX can start again from scratch.

web.xml

The file WEB-INF/web.xml (from the extracted directory) configures the different servlets that form CRX. Each section of the file has the following structure:

<!-- ================================= -->
<!--   M Y   S E R V L E T             -->
<!-- ================================= -->
<servlet>
   <servlet-name>MyServlet</servlet-name>
   <description>What the servlet does.</description>
   <servlet-class>
      com.day.crx.j2ee.MyServlet
   </servlet-class>
   <init-param>
      <param-name>my-first-parameter</param-name>
      <param-value>my-first-value</param-value>
      <description>
         This is the first configuration parameter.
      </description>
   </init-param>
   <init-param>
      <param-name>my-second-parameter</param-name>
      <param-value>my-second-value</param-value>
      <description>
         This is the second configuration parameter.
      </description>
   </init-param>
</servlet>

You can configure each section by changing the values of <param-value> tags. Do not change any other text in the configuration file. The following sections tell you how you can configure each section of the web.xml file.

Logging

This is a standard Log4J logger that CRX uses to log messages. Usually, you do not have to modify these settings.

Repository

The repository section configures how the CRX repository is set up.

The following parameters are available:

repository-home	The name and path of the folder that stores the CRX repository files. The default is crx-quickstart/repository/. In other configuration files, you can use the environment variable ${rep.home} to point to this folder.
repository-config	The path to the repository configuration file. The default is ${repository-home}/repository.xml.
repository-name	The name of the repository on the JNDI or RMI registry. The default is crx.
bootstrap-config	This can be used to overwrite the static values defined in WEB-INF/web.xml. It is currently used by the cluster join GUI page. The default is bootstrap.properties.
rmi-port	The port number at which the repository is available for RMI access. Omit the parameter to disable RMI access, or use “0” for the default RMI port.
java.naming.provider.url	The class name of the Java naming factory of the JNDI service provider you want to use. By default, CRX uses its own classes. If you run CRX on an application server, you can also use its classes.
java.naming.factory.initial	The class name of the initial context factory of the JNDI service provider you want to use.
license-file	The path to the license file (usually named license.properties). By modifying this value, you can place the license file in the CRX Web application (where it is created by the CRXinstaller), or at another location on the server.

Note

repository.xml is now in crx-quickstart/repository/repository.xml

WEB-INF/ contains only a template/default/example configuration: repository-template.xml

Note

The recommended way to configure these settings (except for bootstrap-config) is to use the bootstrap.properties file instead of modifying the web.xml file.

JCR Explorer

The configuration settings for the CRX Repository Explorer. By default, these values correspond to the settings of the repository section and you do not need to change them. If you manually change the settings of the repository section, make sure to update the corresponding settings in this section.

Nodetree

This section has no configurable settings.

Export

This section has no configurable settings.

CIFS Adapter

The SMB/CIFS Adapter exposes the CRX repository via SMB/CIFS. It is configured by the following properties of the SmbServlet in the web application's web.xml.

IP address: specifies the address to bind the SMB listener to. Default: localhost.
port: port number to bind the SMB listener to. Default: 8445.
share: share name to export, the default is crx.

There are two possible server setups, Linux and Windows. You can access:

a Linux server both locally and remotely.
a Windows server only remotely.

Once set up, you can access the SMB share as \\machine\crx.

Note

For a user to be able to connect to a CRX SMB/CIFS Adapter using a CIFS client (e.g. a Windows computer) when a LoginModule other than CRXLoginModule is configured, they need to have logged in to the repository at least once before that.

The reason for this requirement is that CIFS clients only send already hashed credentials as an authentication token, so the repository has to have these hashed credentials to be able to authorize the request. The hash of these credentials is created upon a login to the repository, which uses the internal repository Login Module setup.

The simplest way to ensure successful CIFS access with credentials is to have users log in to the CRX GUI (or through an application that authorizes against the repository). For larger deployments, a custom module can be created to automate this.

Linux

SMB/CIFS clients always try to open a connection to port 445. Since listening on ports numbered lower than 1024 is a privileged operation, it is advisable to configure the CIFS adapter to listen on port 8445. This allows CRX to run as non-root.

To accept connections on port 445 and forward them to 8445 you can use any TCP/IP proxy for Linux. Configure the proxy to redirect connections on port 445 to port 8445, where the CRX CIFS adapter is listening.

A CRX installation contains such a proxy, located at opt/helpers/proxy.jar in the CRX installation directory. To start the proxy for ports 8445 and 445 use the following command:

$ sudo java -jar proxy.jar localhost 8445 445 -q

Note

proxy.jar must be started as root, because it listens on port 445.

Specify -q[uiet] if you are not interested in the actual binary transfer.

Windows

The Windows SMB server listens on port 445 and does not allow other programs to export shares. Therefore, you must stop NetBios over TCP/IP.

Open Device Manager.
In the View menu, select Show hidden devices. The entry Non-Plug and Play Drivers appears in the tree.
Open Non-Plug and Play Drivers.
Right-click Netbios over TCP/IP.
Select Disable.
Restart your Windows machine.

After restarting your machine, the port 445 is no longer allocated so you can specify this as the port that the SmbServlet can listen on. Clients on other machines will be able to connect, but as the local device is disabled you will not be able to access your share locally.

WebDAV

The settings for WebDAV access to CRX. Further configuration settings are stored in the file config.xml.

resource-path-prefix	The folder under which WebDAV content is available. The default is /repository.
authenticate-header	The header information that CRX sends back when it asks a client to identify itself. Typically, this is the so-called “basic realm”, which tells the client who is asking.
resource-config	The location of the WebDAV configuration file. The default is /WEB-INF/config.xml.

WebDAV Server

This servlet is used to return content over a WebDAV or HTTP interface. You do not have to change these settings.

CQ Resource

The settings for WebDAV access to CRX in a Communiqué environment. Further configuration settings are stored in the file cqresource.xml.

Caution

Do not change these settings as the CQResource servlet is obsolete.

repository.xml

The repository.xml file holds general repository settings, such as the location of the workspaces, the search index and the version storage.

repository.xml has the following structure:

<Repository>
    <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
        <param name="p1" value="v1"/>
        <param name="p2" value="v2"/>
    </FileSystem>
   ...
</Repository>

Each section (such as <FileSystem>) points to a Java class, for which you can define multiple parameters. The JavaDoc documents the available classes, including the parameters you can define in repository.xml.

FileSystem

The <FileSystem> element specifies the file system where CRX stores the repository files. You can use a so-called “virtual file system” to store the repository files in a database.

See the JavaDocs for the classes that implement the FileSystem interface and how to use them to configure your file system. The parameters differ for each class.

Caution

Repository files are harder to manage if they are stored in a database.

Security

The security settings for CRX. The security is handled by a login module (LoginModule) and an access manager (AccessManager).

The login module retrieves the user’s credentials (typically the user name and password), then the access manager checks the access rights that go with those credentials.

Note

There are also SecurityManager and UserManager configuration sections, but their default configurations should not need changing.

Login Module Configuration

The login module configuration element looks as follows:

<LoginModule class="com.day.crx.core.CRXLoginModule">
   <param name="anonymousId" value="anonymous"/>
   <param name="adminId" value="admin"/>
</LoginModule>

anonymousId	The user name (or "principal") used for anonymous users.
adminId	The user name (or “principal”) that has administrator access.
disableTokenAuth	Disables token authentication if set to "true". It is "false" by default.

Token-based authentication. By default, the CRX login module uses token-based authentication. If you need to disable this, please add the disableTokenAuth parameter to the LoginModule configuration and set the value to true:

<LoginModule class="com.day.crx.core.CRXLoginModule">
   <param name="anonymousId" value="anonymous"/>
   <param name="adminId" value="admin"/>
   <!-- turn off token-based authorization -->
   <param name="disableTokenAuth" value="true"/>
</LoginModule>

When Token-based authentication is disabled in the repository configuration, then authentication functions by taking the credentials for login from either:

the "authorization" request header (i.e. normal Basic Authorization)
used by CRXDE Lite and Package Manager.
a login form
CRX Explorer uses a login form and caches the JCR sessions on the server side (sessionID in the http session).

Note

If you use JAAS (Java Authentication and Authorization Service) authentication setup (for example, to set up LDAP authentication) and need a specialized configuration for the CRXLoginModule, you need to configure it in a separate JAAS configuration file. You can then use the same CRXLoginModule parameter names as specified here.

See Custom Login Modules and LDAP authentication for more information.

Access Manager Configuration

The access manager associates access rights with a user’s log-in information. The configuration looks as follows:

<AccessManager class="org.apache.jackrabbit.core.security.DefaultAccessManager">
</AccessManager>

class

The Java class that checks access rights. The default access manager implements the access control mechanism used by CRX. You only need to change this setting if you need a custom access control mechanism and have an implementation of the JackrabbitAccessControlManager interface for doing so.

User Manager Configuration

An impact on performance can sometimes be seen when registering new users in installations that have a high number of both:

users
groups with many members

In such cases the performance can be improved by setting lower values for:

groupMembershipSplitSize
autoExpandSize

<param name="autoExpandSize" value="100"/>
<param name="groupMembershipSplitSize" value="20"/>

Workspaces

The <Workspaces> element specifies the location of the workspace root folder and name of the default workspace.

root-path	The path of the folder that contains the workspace(s). The default is ${rep.home}/workspaces, meaning that the workspaces are stored in the folder workspaces in the repository installation folder.
defaultWorkspace	The name of the default workspace. The default name is crx.default.

Workspace

The <Workspace> element serves as a template for new workspaces that CRX creates. See the workspace configuration documentation for information on how to set up the workspace.

The following elements are available in the <Workspace> section:

FileSystem	The class and parameters of the real or virtual file system that CRX uses for the workspace files.
PersistenceManager	The persistence manager used to store the workspace content.
SearchIndex	The search index used to index the repository content.

Note

There are also WorkspaceSecurity and Import configuration sections, but their default configurations should not need changing.

Versions

The file system and persistence manager you want CRX to use for storing the version history.

FileSystem	The class and parameters of the real or virtual file system that CRX uses for the version history files.
PersistenceManager	The persistence manager used to store the version history content.

Search Index

The SearchIndex element specifies the configuration of the search engine.

By default the search index is managed by the text search engine Apache Lucene. To configure Lucene to use the analyzer that supports the language of your texts, update your configuration as follows (e.g: the german analyzer):

<SearchIndex class="com.day.crx.query.lucene.LuceneHandler">
     <param name="path" value="${wsp.home}/index"/>
     <param name="resultFetchSize" value="50"/>
     <param name="analyzer" value="org.apache.lucene.analysis.de.GermanAnalyzer"/>
</SearchIndex>

Note

The available analyzers can be found by browsing the javadoc documentation of Lucene. Each supported language has its own subpackage under org.apache.lucene.analysis (e.g. The german language package is org.apache.lucene.analysis.de).

Cache Manager

To configure the Cache Manager limits, add the CacheManagerModule; the example below shows the default configuration settings:

<Module class="com.day.crx.core.util.CacheManagerModule">
    <param name="maxMemory" value="16777216"/>
    <param name="minMemoryPerCache" value="13056"/>
    <param name="maxMemoryPerCache" value="4194304"/>
    <param name="resizeInterval" value="1000"/>
</Module>

config.xml

This file stores the configuration settings for WebDAV access. The settings map the nodes and properties of CRX to a file structure, based on files and folders. The configuration looks as follows:

<config>
   <iomanager>
      <class name="com.day.crx.io.CrxIOManager" />
   </iomanager>
   <collection>
      <nodetypes>
         <nodetype>nt:folder</nodetype>
      </nodetypes>
   </collection>
   <noncollection>
      <nodetypes>
         <nodetype>nt:file</nodetype>
         <nodetype>nt:resource</nodetype>
      </nodetypes>
   </noncollection>
   <filter>
      <class name="com.day.crx.webdav.simple.DefaultItemFilter" />
      
      <nodetypes>
         <nodetype>rep:root</nodetype>
      </nodetypes>
      <namespaces>
         <prefix>rep</prefix>
         <prefix>jcr</prefix>
      </namespaces>
   </filter>
</config>

You can configure the following elements:

iomanager	The Java class that returns the files over WebDAV.
collection	A list of node types that are displayed as folders. The nodes below a folder node are displayed as the folder content.
noncollection	A list of node types that are displayed as files. The nodes and properties below such a node make up the file content.
filter	You can specify a filter to omit nodes from the WebDAV view. This is useful to hide CRX-internal nodes.
nodetypes	A list of node types that are not displayed over WebDAV.
namespaces	A list of namespaces that are not displayed over WebDAV.

cqresource.xml

This file contains the settings of WebDAV access in a Communiqué environment.

Caution

Do not change these settings as the CQResource servlet is obsolete.

Checking Repository Integrity

For procedures to check repository integrity, please see the documentation on Persistence Managers.

Checking Datastore Consistency

For a procedure to check Datastore Consistency, see here.

bootstrap.properties

bootstrap.properties is a file you can create to hold definitions of certain repository parameters. These will be read at either installation or startup time and overwrite the default definitions (from web.xml). You can use this file for such tasks as relocating the repository (before installation) or specifying a customized version of repository.xml.

The recommended location for bootstrap.properties is in <crx-installation-dir>; the folder that holds the quickstart jar file and license.properties.

The following parameters can be used in bootstrap.properties (as in the repository section of web.xml, but using "." in place of "-"):

repository.home
repository.config
repository.name

For an illustration of using bootstrap.properties see Relocating or Preconfiguring the Repository.

Your comments are welcome!

Did you notice a way we could improve the documentation on this page? Is something unclear or insufficiently explained? Please leave your comments below and we will make the appropriate changes. Comments that have been addressed, by improving the documentation accordingly, will then be removed.

COMMENTS

By Oliver - 3:46 PM on Nov 29, 2011 Reply
Regarding: Checking Repository Integrity
Here you say:
-----------
CRX can check and provide information about repository integrity, but it does not repair the repository if there are any problems:
-----------

Now I have with Hotfixpack 2.2.0.43 an option called "Fix inconsistencies".
I can imagine what this option does in CRX.

But could you describe this also in your documentation? And are there some risks when enabling this check-box?

I would want to run this checks automatically every day - are there any sideeffects besides performance-impacts?

Thanks and best regards,
Oliver

BTW:
I do not get any mails when somenbody replies to my comments, though I have noted my correct e-mail.
Can you have a look at it, eventually?
Thanks!
By Puni - 7:51 PM on Mar 20, 2012 Reply
Is this method of checking the repository as reliable as the offline method?
By vithuran rahul - 9:21 PM on Sep 28, 2012 Reply
In CQ5.5 i could not find crx-explorer_crx.war location. if any one knows please share the path.

ADD A COMMENT

In order to post a comment, you need to sign-in.

Note: Customers with DayCare user accounts need to create a new account for use on day.com.