Repository Setup

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.

Remarque

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:

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

Remarque

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>
        

Les exemples de code sont fournis à titre d’illustration seulement.

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.

Remarque

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

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

Remarque

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.

Remarque

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
        

Les exemples de code sont fournis à titre d’illustration seulement.

Remarque

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.

  1. Open Device Manager.
  2. In the View menu, select Show hidden devices. The entry Non-Plug and Play Drivers appears in the tree.
  3. Open Non-Plug and Play Drivers.
  4. Right-click Netbios over TCP/IP.
  5. Select Disable.
  6. 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.

Attention

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>
        

Les exemples de code sont fournis à titre d’illustration seulement.

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.

Attention

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.

Remarque

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>
        

Les exemples de code sont fournis à titre d’illustration seulement.

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>
        

Les exemples de code sont fournis à titre d’illustration seulement.

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

Remarque

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>
        

Les exemples de code sont fournis à titre d’illustration seulement.

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.

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.

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.

Remarque

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>
        

Les exemples de code sont fournis à titre d’illustration seulement.

Remarque

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

The Apache Lucene handler relies on Apache Tika when indexing binary files (e.g. Open Document, Microsoft Office Documents, Compressed files, etc). A custom Tika configuration file can be provided by using the tikaConfigPath parameter.

 <SearchIndex class="com.day.crx.query.lucene.LuceneHandler">
     <param name="path" value="${wsp.home}/index"/>
     <param name="resultFetchSize" value="50"/>
     <param name="tikaConfigPath" value="${wsp.home}/tika-config.xml"/>
</SearchIndex>
        

Les exemples de code sont fournis à titre d’illustration seulement.

Remarque

The Apache Tika configuration path parameter is supported from CQ 5 Service Pack 2.1 onwards. 

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>
        

Les exemples de code sont fournis à titre d’illustration seulement.

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>
        

Les exemples de code sont fournis à titre d’illustration seulement.

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.

Attention

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

​