eXo Platform 3.5

## Chapter 3. Configuration

This chapter covers the following topics:

- eXo Platform configuration

- Database configuration

- File system paths

- Mail server

- Email-notification configuration for watching a document

- WebDAV Cache Control

- Chat server

- OpenOffice server

- Log-in

- JCR

- Cache configuration

- User configuration

- Gadget proxy configuration

- Other properties

## eXo Platform configuration

In eXo Platform, the configuration is performed in a folder whose location is controlled by a system property named exo.conf.dir. By default, the gatein.sh startup script sets this property as follows:

    -Dexo.conf.dir.name=gatein/conf

So the main entry point for the eXo Platform configuration is /gatein/conf/. This directory contains the following files:

- configuration.properties: the main system configuration.

- configuration.xml: contains the default portal container configuration.

- portal/portal/configuration.xml: the main external customization entry point for the default portal container.

### Portal Containers, Customization and Configurations

This section explains some parts of the eXo Platform internals so that you can understand the roles of these configuration files.

The eXo Platform Kernel collects runtime components in the portal containers. A portal container holds all components to run a portal instance. It serves portal pages under the servlet context for its name.

The default portal container in eXo Platform is simply called "portal". This explains why the default URL of the samples is http://localhost:8080/portal.

The default portal container can be configured directly inside exo.conf.dir.

However, eXo Platform is capable of running several portal instances simultaneously on the same server. Each instance can be configured and customized independently via files located at: /gatein/conf/portal/$PORTAL_NAME, where $PORTAL_NAME is the name of the portal container.

### Note

The name of the configuration file can be altered. Please refer to the PortalContainer section in the Kernel reference for more details on portal containers and other options to modify the location of the properties.

Services that run inside a portal container are declared via the xml configuration files like configuration.xml. Such files exist in jars, wars and below exo.conf.dir.

The .xml configuration files also serve as the main way to customize the portal via the multiple plugins offered by the eXo Platform components.

Additionally, the .xml files may contain variables that are populated via properties defined in configuration.properties. Hence, the configuration.properties file serves as exposing some selected variables that are necessary to configure eXo Platform in a server environment.

configuration.properties

The system configuration is mostly done in the configuration.properties file. In most cases, this should be the only file for the system administrator to configure.

- In the Tomcat bundle, this file is located at /gatein/conf/configuration.properties.

- In the JBoss server, this file is located at server/default/conf/gatein/configuration.properties.

configuration.xml

This file contains the built-in configuration for the "portal" portal container.

- In most cases, you should not change this file.

- In case you do not want to use "portal" as the default portal for your project, this file can be used to import another PortalContainerDefinition into the root container.

### Note

To learn more about how to configure a new portal container, please refer to the Kernel reference guide.

portal/portal/configuration.xml

This file is empty by default. This is where further customizations can be placed. Generally, custom configurations are provided by extension wars. However, this file is the last loaded by the kernel. It has a higher priority over any other configuration files, including extensions. So, you can override any internal component configuration.

This may turn handy services or configurations that are not exposed in configuration.properties.

For example, you can change the default WebDAV update policy by adding the following code to this configuration.xml file:

      <component>

        <key>org.exoplatform.services.jcr.webdav.WebDavServiceImpl</key>

        <type>org.exoplatform.services.jcr.webdav.WebDavServiceImpl</type>

        <init-params>

          <value-param>

            <name>auto-mix-lockable</name>

            <value>false</value>

          </value-param>

          <value-param>

            <name>def-folder-node-type</name>

            <value>nt:folder</value>

          </value-param>

          <value-param>

            <name>def-file-node-type</name>

            <value>nt:file</value>

          </value-param>

          <value-param>

            <name>def-file-mimetype</name>

            <value>text/plain</value>

          </value-param>

          <value-param>

            <name>update-policy</name>

            <value>replace</value>

          </value-param>

        </init-params>

      </component>

## Database configuration

eXo Platform relies on the application server for its database access, so the database must be configured as a data source at the AS level. The data source is obtained by accessing the Enterprise Naming Context (ENC) through the Java Naming and Directory Interface (JNDI) service.

### Connect to a production database

If you intend to bring your eXo Platform to production, the embedded hsql database will not be appropriate and you will need to configure your app server to use another one. You need to learn how to configure eXo Platform data sources and your app server. If you need to change the data sources name, read the Rename the data source section below.

### Note

The steps below will show you how to configure eXo Platform to use a MySQL database. You need to adapt them to your actual production environment.

### Tip

Refer to the Database FAQ below to find out our sample configuration files for MySQL and other DB systems.

Step 1. Prepare your database server.

You need to prepare two database schema, then do as follows:

1. Connect to your database server using the ssh command:

    ssh root@db.example.org

2. Verify that MySQL is running:

    sudo /etc/init.d/mysqld status

3. Connect to MySQL:

    mysql -u root -p

In this step, you will be prompted for entering your password.

4. Create 2 databases: one for idm ($dbname-idm) and the other for jcr ($dbname-jcr). For example:

i. Create the first database:

    create database _$dbname_;

ii. Configure the user who has the remote access right (not only from the host server):

    grant all on _$dbname_.* to '_$username_'@'_$IP_' identified by '_$password_';

In which, $IP = AS host name, $IP = IP with wildcard (eg 192.168.1.% = all IPs on 192.168.1.x network) and $username = username that eXo Platform will connect with (i.e. 'dbnameuser').

5. Verify that both databases were created successfully:

    show databases;

6. Quit the server with the exit command.

### Note

eXo Platform does not require tables to be created before it starts because these tables are created automatically on the first startup. If you want to run the DDL script to create the database objects, please contact eXo Support to obtain the script for your database.

Step 2. Configure eXo Platform.

After the database is ready, you need to configure eXo Platform to connect to it. The configuration steps may be different, depending on the application server. Here, instructions are for Tomcat and JBoss.

Tomcat bundle:

In Tomcat, the data sources configuration requires you to edit the server.xml file.

### Tip

Please refer to Tomcat's JNDI Resources How To for more details on the JNDI resources binding in Tomcat.

Edit the server.xml file

1. Open the file following the $TOMCAT_HOME/conf/server.xml path.

2. Declare the binding of the data sources in the GlobalNaming context:

- Change the driver from org.hsqldb.jdbcDriver to com.mysql.jdbc.Driver.

- Change the username and password to the values set above.

- Change the URL to access your DataBase from jdbc:hsqldb:file:../gatein/data/hsql/exo-jcr_portal to jdbc:mysql://_$host_:3306/_$dbname_.

The code now should look like:

    <!-- eXo JCR Datasource for portal -->

    <Resource auth="Container" driverClassName="com.mysql.jdbc.Driver" logAbandoned="true" maxActive="20" maxIdle="10" maxWait="10000" minEvictableIdleTimeMillis="60000" name="exo-jcr_portal" password="_$password_" removeAbandoned="true" removeAbandonedTimeout="10" type="javax.sql.DataSource" url="jdbc:mysql://_$host_:3306/_$dbname-jcr_" username="_$username_"/>

    <!-- eXo IDM Datasource for portal -->

    <Resource auth="Container" driverClassName="com.mysql.jdbc.Driver" logAbandoned="true" maxActive="20" maxIdle="10" maxWait="10000" minEvictableIdleTimeMillis="60000" name="exo-idm_portal" password="_$password_" removeAbandoned="true" removeAbandonedTimeout="10" type="javax.sql.DataSource" url="jdbc:mysql://_$host_:3306/_$dbname-idm_" username="_$username_"/>

3. Add the JDBC driver. In this step, you need to add the MySQL connector to Tomcat by adding mysql-connector-java-5.1.x.jar to $TOMCAT_HOME/lib/.

JBoss:

Configure the data source for eXo Platform under JBoss

- Edit gatein-ds.xml

- Add the JDBC driver

1. Edit the gatein-ds.xml file.

i. Open the file following the $JBOSS_HOME/server/default/deploy/gatein-ds.xml path.

ii. Declare the binding of the data sources in the GlobalNaming context:

- Change the driver: org.hsqldb.jdbcDriver to com.mysql.jdbc.Driver.

- Change the username and password to the values set earlier.

- Change the URL to access your database: <connection-url>jdbc:hsqldb:${jboss.server.data.dir}${/}exo${/}hypersonic${/}exo-xxx_portal-localDB</connection-url> to <connection-url>jdbc:mysql://_$host_:3306/_$dbname_</connection-url>.

The configuration should now look like:

    <datasources>

        <no-tx-datasource>

          <jndi-name>exo-idm_portal</jndi-name>

          <connection-url>jdbc:mysql://_$host_:3306/_$dbname-idm_</connection-url>

          <driver-class>com.mysql.jdbc.Driver</driver-class>

          <user-name>_$username_</user-name>

          <password>_$password_</password>

          <min-pool-size>5</min-pool-size>

          <max-pool-size>20</max-pool-size>

          <idle-timeout-minutes>0</idle-timeout-minutes>

          <prepared-statement-cache-size>32</prepared-statement-cache-size>

       </no-tx-datasource>

    <!-- ...  -->

       <no-tx-datasource>

          <jndi-name>exo-jcr_portal</jndi-name>

          <connection-url>jdbc:mysql://_$host_:3306/_$dbname-jcr_</connection-url>

          <driver-class>com.mysql.jdbc.Driver</driver-class>

          <user-name>_$username_</user-name>

          <password>_$password_</password>

          <min-pool-size>5</min-pool-size>

          <max-pool-size>20</max-pool-size>

          <idle-timeout-minutes>0</idle-timeout-minutes>

          <prepared-statement-cache-size>32</prepared-statement-cache-size>

       </no-tx-datasource>

    </datasources>

2. Add the JDBC driver. In this step, you need to add the MySQL connector library in JBoss by adding mysql-connector-java-5.1.x.jar to $JBOSS_HOME/server/default/lib/.

### Tip

You can get the latest MySQL connector here.

3. Rename the data source.

By default, eXo Platform defines two data sources:

- exo-jcr_portal - for the Java Content Repository (JCR).

- exo-idm_portal - for the organizational model.

You may want to rename the data source as follows:

i. Open and edit the configuration.properties path.

In this step, indicate to eXo name of the data sources.

    # JNDI name of the datasource that will be used by eXo JCR
    gatein.jcr.datasource.name=java:/comp/env/exojcr
    ...
    # JNDI Name of the IDM datasource
    gatein.idm.datasource.name=java:/comp/env/exo-idm

### Note

eXo Platform automatically appends the portal container name ("_portal" by default) to these values before performing a JNDI lookup.

ii. Change the data source name in the application server.

In this step, you need to change the name under which the data sources are bound in the JNDI tree by the app server. This is a dependent application sever.

### FAQs of database configuration

Q1. How to configure eXo Platform to connect to other database systems?

Configuring eXo Platform to connect to other database can be done easily. eXo Platform provides sample configuration files in the folders:

- eXo Platform-3.5.x.zip/conf/db/

  - mysql

  - oracle

  - postgres

In each folder, you will find two sample xml files: gatein-ds.xml for JBoss and server.xml for Tomcat.

Each file contains 2 preconfigured datasources. For example (JCR datasource in mysql/server.xml):

    <Resource auth="Container" driverClassName="com.mysql.jdbc.Driver" maxActive="128" maxIdle="32" maxWait="10000" name="exo-jcr_portal" password="${db.password}" testWhileIdle="true" timeBetweenEvictionRunsMillis="30000" type="javax.sql.DataSource" url="jdbc:mysql://${db.host}:${db.port}/${db.jcr.name}" username="${db.username}" validationQuery="SELECT 1"/>

You simply replace the variables with the expected values:

Variables | Expected values
--- | ---
db.username | The username that connects to the database.
db.password | The password for the above user.
db.host | The hostname or IP address of the DB server.
db.port | The port to connect to the DB.
db.jcr.name | The DB name for the JCR datasource.
db.idm.name | The DB name for the IDM datasource.

Please remember to add the JDBC connector JAR in the classpath of your application server.

You can download the official JDBC connector JARs from the following websites:

- http://www.mysql.com/downloads/connector/j/

- http://jdbc.postgresql.org/download.html

- http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html

Q2. How to remove the idle MySQL connections?

Some RDBMSs, like MySQL, close the idle connections after a period (8 hours on MySQL by default). Thus, a connection from the pool will be invalid and any application SQL command will fail, resulting in errors as below:

    org.hibernate.SessionException: Session is closed!
    at org.hibernate.impl.AbstractSessionImpl.errorIfClosed(AbstractSessionImpl.java:72)
    at org.hibernate.impl.SessionImpl.getTransaction(SessionImpl.java:1342)

To avoid this, you can use DBCP to monitor the idle connections and drop them when they are invalid, with the parameters testWhileIdle, timeBetweenEvictionRunsMillis and validationQuery.

The validation query is specific to your RDBMS. For example, on MySQL, you would use:

    testWhileIdle="true" timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1"

In which:

- testWhileIdle activates idle connections monitoring.

- timeBetweenEvictionRunsMillis defines the time interval between two checks in milliseconds (5 minutes in the example).

- validationQuery provides a simple SQL command to validate the connection to the RDBMS.

You can add these parameters to the data source configuration file of your application server, for example: conf/server.xml on Tomcat.

For more details on the configuration, or some examples on other RDBMS and applications servers, please refer to:

- http://markmail.org/message/a3bszoyqbvi5qer4

- http://stackoverflow.com/questions/15949/javatomcat-dying-databse-connection

- http://confluence.atlassian.com/display/JIRA/Surviving+Connection+Closures

Q3. How to enable managed DataSource?

When you want to use a managed data source (which is the case under JBoss), set "true" for the `gatein.jcr.datasource.managed` property in the `configuration.properties` file

    # indicates if the jcr datasource is using managed transactions.
    # false by default.
    gatein.jcr.datasource.managed=true

## File system paths

eXo Platform requires the read/write access to several paths in the local file system.

    # Arjuna configuration
    com.arjuna.ats.arjuna.objectstore.objectStoreDir=${gatein.data.dir}/jta
    .....

    # Directory for common data (in cluster, mount it as a network shared directory between nodes)
    # On standalone JBoss app server it is assignet to ${jboss.server.data.dir} by default.
    exo.shared.dir=../gatein

    # Configuration directory (in cluster, this directory is per node)
    # Usual locations of configuration directory:
    # for Tomcat app server it is ${catalina.home}/gatein/conf.
    # for JBoss app server it is ${jboss.server.home.dir}/conf/gatein.
    gatein.conf.dir=${catalina.home}/${exo.conf.dir.name}

    # Data directory
    gatein.data.dir=${exo.shared.dir}/data

    # path for any JCR data
    gatein.jcr.data.dir=${gatein.data.dir}/jcr

    # path for file data inserted in JCR
    gatein.jcr.storage.data.dir=${gatein.jcr.data.dir}/values

    # path for the jcr index
    gatein.jcr.index.data.dir=${gatein.jcr.data.dir}/index

The following table explains what goes in which path. The Temporary column indicates if the data are temporary or persistent (V: temporary, X: persistent).

Variable | Content | Temporary
--- | --- | ---
`com.arjuna.ats.arjuna.objectstore.objectStoreDir` | JTA transactional data. | V
`gatein.jcr.data.dir` | Directory for JCR data. | X
`gatein.jcr.data.dir`/swap | Directory for swapped data of JCR | V
`gatein.jcr.storage.data.dir` | Binary value storage for JCR. | X
`gatein.jcr.index.data.dir` | Lucene index for JCR. | X

Each variable can be defined as an absolute or a relative path. The default configuration combines them to obtain a compact tree:

    /gatein       # gatein.data.dir
      /data
        /hsql
        /jcr      # gatein.jcr.data.dir
          /index  # gatein.jcr.index.data.dir
          /swap
          /values # gatein.jcr.storage.data.dir
        /jta

## JCR system and default Workspaces

The following is the configuration of workspaces (default and system) for JCR repository.

    # JCR system and default workspaces
    gatein.jcr.workspace.default=collaboration
    gatein.jcr.workspace.system=system

## Transaction Service

JCR transaction default timeout configured for 7 mins (420 sec) by default. If your application runs longer transactions, you might need a bigger timeout.

    # JCR Transaction Service
    # TransactionService default timeout (in seconds), set it to one hour here:
    gatein.jcr.transaction.timeout=3600

## Mail server

### Note

The Mail portlet and its services are deprecated. It remains fully supported for eXo customers, however it will not receive any enhancement and will be removed from the product scope in the future.

eXo Platform requires the SMTP server to send emails, such as notifications or password reminders.

The Email service can use any SMTP account that needs to be configured in /server/default/conf/gatein/configuration.properties (Or $TOMCAT_HOME/ gatein/conf/configuration.properties if you are using Tomcat).

The relevant section looks like:

    #EMail
    # Domain name: Help for sending links from email notifications. The default domain name is http://localhost:8080.
    gatein.email.domain.url=http://localhost:8080
    # Email display in "from" field of email notification.
    gatein.email.smtp.from=noreply@exoplatform.com
    gatein.email.smtp.username=
    gatein.email.smtp.password=
    gatein.email.smtp.host=smtp.gmail.com
    gatein.email.smtp.port=465
    gatein.email.smtp.starttls.enable=true
    gatein.email.smtp.auth=true
    gatein.email.smtp.socketFactory.port=465
    gatein.email.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

Some authenticated SMTP systems, such as GMail, GMX, MS Exchange, require the value for 'sender' or 'from' in the email message that must be identical to the SMTP user and host.

The Forum application uses it in the notification phase as the default sender. If it is not set, the sender will be empty.

gatein.email.domain.url | Domain name.
gatein.email.smtp.from | Sender's email address.
gatein.email.smtp.host | SMTP hostname.
gatein.email.smtp.port | SMTP port.
gatein.email.smtp.starttls.enable | True to enable the secure (TLS) SMTP. See RFC 3207.
gatein.email.smtp.auth | True to enable the SMTP authentication.
gatein.email.smtp.username | Username to send for authentication.
gatein.email.smtp.password | Password to send for authentication.
gatein.email.smtp.socketFactory.port | Specify the port to connect to when using the specified socket factory.
gatein.email.smtp.socketFactory.class | This class will be used to create SMTP sockets.

To see more details, refer to JavaMail API documentation.

For Knowledge, you have to modify the following properties to the configuration file /gatein/conf/configuration.properties to make sure that this mail service works with the authenticated SMTP systems:

    gatein.email.domain.url=http://localhost:8080
    gatein.email.smtp.from=noreply@exoplatform.com

### Note

The value of email address should be in a valid format.

## Email-notification configuration for watching a document

eXo Platform 3.5 provides the Watch document function in Sites Explorer that allows you to receive email notifications of changes on your selected documents. In this section, you will know how to configure such an email notification.

The email notification is configured in the core-services-configuration.xml file which is in /tomcat/webapps/ecm-wcm-core/WEB-INF/conf/wcm-core.

Configure the email notification

1. Open the core-services-configuration.xml file, then customize the messageConfig init-param of the WatchDocumentService component.

    <component>

       <key>org.exoplatform.services.cms.watch.WatchDocumentService</key>

       <type>org.exoplatform.services.cms.watch.impl.WatchDocumentServiceImpl</type>

       <init-params>

          <object-param>

            <name>messageConfig</name>

            <description>description</description>

            <object type="org.exoplatform.services.cms.watch.impl.MessageConfig">

              <field name="sender"><string>support@exoplatform.com</string></field>

              <field name="subject"><string>Your watching document is changed</string></field>

              <field name="mimeType"><string>text/html</string></field>

              <field name="content">

                <string>

                        Dear $user_name,&lt;br&gt;

                        &lt;br&gt;

                        The document $doc_name ($doc_title) has changed.&lt;br&gt;

                        &lt;br&gt;

                        Please go to &lt;a href="$doc_url"&gt;$doc_title&lt;/a&gt; to see this change.&lt;br&gt;

                        &lt;br&gt;

                </string>

              </field>

            </object>

          </object-param>

        </init-params>

     </component>

In which:

- sender: The email address of the sender.

- subject: The subject of the notification email.

- mimeType: The mimeType used to writing the notification email. There are two types: text/html and text/plain.

- content: The content of the notification email.

At present, eXo Platform supports 4 following parameters in the content of the email:

- - $user_name: The full name of the receiver.

  - $doc_name: The name of the document.

  - $doc_title: The title of the document.

  - $doc_url: The link to view the document in Sites Explorer.

2. Save the file.

## WebDAV cache control

The embedded WebDAV server lets you control the cache-control http header that transmits to clients by the MIME type. This is useful for fine-tuning your website.

The configuration property is exo.webdav.cache-control.

    exo.webdav.cache-control=text/*:max-age=3600;image/*:max-age=1800;*/*:no-cache;

The property expects a comma-separated list of key=pair values, where keys are a list of MIME types followed by the cache-control value to set.

## Chat server

### Note

The Chat portlet and its services are deprecated. It remains fully supported for eXo customers, however it will not receive any enhancement and will be removed from the product scope in the future.

### XMPPMessenger

If you change the host name and port for the Chat server, you will need to edit two properties:

    # IP or hostname for the eXo Chat XMPP server
    exo.chat.server=127.0.0.1

    # TCP port for where the eXo Chat server listens for XMPP calls
    exo.chat.port=5222

### Chat server configuration

The standalone Chat server is configured in the $CHATSERVER/conf/openfire.xml file.

Configuration is based on properties expressed in the XML syntax. For example, to set the prop.name.is.blah=value property, you would write this xml snippet:

    <prop>

      <name>

        <is>

          <blah>value</blah>

        </is>

      </name>

    </prop>

Openfire has an extensive list of configuration properties. Please read the list of all properties in Openfire documentation for more details.

The Chat server is an Openfire server bundled with plugins and configurations that allow connectivity to eXo Platform. The following properties are used to configure it.

Property | Description | Default value
--- | --- | ---
env |  |
serverbaseURL | Base URL for all URLs below. | http://localhost:8080/
restContextName | Name of the rest context. | rest
provider |  |
authorizedUser.name | Username to authenticate against the HTTP REST service. | root
authorizedUser.password | Password matching with provider.authorizeduser.name. | password
eXoAuthProvider |  |
authenticationURL | URL to authenticate users. | /organization/authenticate/
authenticationMethod | HTTP method used to pass parameters. | POST
eXoUserProvider |  |
findUsersURL | URL to find all users. | /organization/xml/user/find-all/
findUsersMethod | HTTP method for user/find-all. | GET
getUsersURL | URL to retrieve a range of users. | /organization/xml/user/view-range/
getUsersMethod | HTTP method for user/view-range. | GET
usersCountURL | URL to count users. | /organization/xml/user/count/
usersCountMethod | HTTP method for user/count. | GET
userInfoURL | URL to get user information. | /organization/xml/user/info/
userInfoMethod | HTTP method for user/information. | GET
eXoGroupProvider |  |
groupInfoURL | URL to get group information. | /organization/xml/group/info/
groupInfoMethod | HTTP method for information. | GET
getGroupsAllURL | URL to view all groups. | /organization/xml/group/view-all/
getGroupsAllMethod | HTTP method for group/view-all. | GET
getGroupsRangeURL | URL to view a group range. | /organization/xml/group/view-from-to/
getGroupsRangeMethod | HTTP method for group/view-from-to. | GET
getGroupsForUserURL | URL to get groups for a user. | /organization/xml/group/groups-for-user/
getGroupsForUserMethod | HTTP method for groups-for-user. | GET
groupsCountURL | URL to count groups. | organization/xml/group/count
groupsCountMethod | HTTP method for group/count. | GET

#### Ports

To run the chat server properly, several ports must be opened in the firewall.

Port | Type | Description
--- | --- | ---
5222 (1) | Client to server (xmpp) | The standard port for clients is to connect to the server. Connections may or may not be encrypted. You can update the security settings for this port with the exo.chat.port property.
9090 & 9091 | Admin Console (http) | The ports used for accessing the unsecured and secured Openfire Admin Console respectively.
3478 & 3479 | STUN service | The port used for the service that ensures connectivity between entities behind a NAT.

## OpenOffice server

eXo Platform allows users to view documents of various types directly on the content explorer through the OpenOffice server. To do so, the OpenOffice application must be available in your local device first. Next, start the OpenOffice server by running the command below:

    soffice -headless -accept="socket,host=127.0.0.1,port=8100;urp;" -nofirststartwizard

## Log-in

The login to eXo Platform is controlled by the Java Logging API.

By default, the login is configured to:

- log errors and warnings on the console.

- logs /gatein/logs/gatein-YYYY-MM-DD.log.

In Tomcat, the login is configured via the conf/logging.properties file. Please refer to Tomcat's Logging Documentation for more information on how to adjust this file to your needs.

## JCR

The set of properties controls the JCR behaviour.

    # Type of JCR configuration to use. Possible values are:
    # local : local JBC configuration
    # cluster : cluster JBC configuration
    gatein.jcr.config.type=local

    ....

    # JCR dialect.
    # auto : enabled auto detection
    gatein.jcr.datasource.dialect=auto

    # JCR Session Registry configuration
    # Define here the Max Age of the JCR Session in the session registry (in seconds)
    gatein.jcr.sessionregistry.sessionmaxage=300

    # JCR cache configuration
    gatein.jcr.cache.config=file:${gatein.conf.dir}/jcr/jbosscache/${gatein.jcr.config.type}/cache-config.xml
    gatein.jcr.cache.expiration.time=15m

    # JCR Locks configuration
    gatein.jcr.lock.cache.config=file:${gatein.conf.dir}/jcr/jbosscache/${gatein.jcr.config.type}/lock-config.xml

    # JCR Index configuration
    gatein.jcr.index.cache.config=file:${gatein.conf.dir}/jcr/jbosscache/${gatein.jcr.config.type}/indexer-config.xml

    # JGroups configuration
    # for eXo Cache and IDM org-service (in cluster cache-config.xml files)
    gatein.jgroups.config=${gatein.conf.dir}/jgroups/jgroups-udp.xml
    # for JCR
    gatein.jcr.jgroups.config=file:${gatein.jgroups.config}

Details:

`gatein.jcr.config.type` | Set to cluster if you want to use eXo Platform in the cluster mode. Otherwise, leave local.
`gatein.jcr.cache.config` | Path to the JBoss Cache configuration for the JCR cache.
`gatein.jcr.cache.expiration.time` | JCR cache expiration time.
`gatein.jcr.lock.cache.config` | Path to the JBoss Cache configuration for the JCR lock.
`gatein.jcr.index.cache.config` | Path to the JBoss Cache configuration for the JCR index.
`gatein.jgroups.config` | Path to the JGroups configuration to use for the cluster mode of eXo Cache and PicketLink IDM organization service (see below in IDM caches).
`gatein.jcr.jgroups.config` | Path to the JGroups configuration to use for the cluster mode.

For more details on configuring these files, please refer to the eXo JCR reference guide.

## Cache configuration

Please refer to the Cache management view to see the description about the cache configuration.

### Portal Cache Configuration

    # Portal Cache Configuration - TemplateService
    cache.exo.portal.TemplateService.capacity=3000
    cache.exo.portal.TemplateService.liveTime=600

    # Portal Cache Configuration - ResourceBundleData
    cache.exo.portal.ResourceBundleData.capacity=3000
    cache.exo.portal.ResourceBundleData.liveTime=600

    # Portal Cache Configuration - MOPSessionManager
    cache.exo.portal.MOPSessionManager.Capacity=5000
    cache.exo.portal.MOPSessionManager.TimeToLive=60000
    cache.exo.portal.MOPSessionManager.ExpirationTimeout=60000

### Social Cache Configuration

    # Social Cache Configuration - ActivityManager
    ## ActivityManager.ActivityCache
    cache.exo.social.ActivityManager.ActivityCache.Capacity=4000
    cache.exo.social.ActivityManager.ActivityCache.TimeToLive=43200

    ## ActivityManager.ActivityListCache
    cache.exo.social.ActivityManager.ActivityListCache.Capacity=1000
    cache.exo.social.ActivityManager.ActivityListCache.TimeToLive=7200

    ## ActivityManager.CommentsCache
    cache.exo.social.ActivityManager.CommentsCache.Capacity=1000
    cache.exo.social.ActivityManager.CommentsCache.TimeToLive=86400

    # Social Cache Configuration - IdentityManager
    ## IdentityManager.IdentityCache
    cache.exo.social.IdentityManager.IdentityCache.Capacity=1000
    cache.exo.social.IdentityManager.IdentityCache.TimeToLive=3600

    ## IdentityManager.IdentityCacheById
    cache.exo.social.IdentityManager.IdentityCacheById.Capacity=3000
    cache.exo.social.IdentityManager.IdentityCacheById.TimeToLive=3600

    ## IdentityManager.IdentityListCache
    cache.exo.social.IdentityManager.IdentityListCache.Capacity=300
    cache.exo.social.IdentityManager.IdentityListCache.TimeToLive=600

    # Social Cache Configuration - RelationshipManager
    ##  RelationshipManager.RelationshipIdCache
    cache.exo.social.RelationshipManager.RelationshipIdCache.Capacity=300
    cache.exo.social.RelationshipManager.RelationshipIdCache.TimeToLive=600

    ## RelationshipManager.RelationshipListCache
    cache.exo.social.RelationshipManager.RelationshipListCache.Capacity=1000
    cache.exo.social.RelationshipManager.RelationshipListCache.TimeToLive=3600

    # Social Cache Configuration - SpaceStorage
    cache.exo.social.SpaceStorage.SpaceCache.Capacity=300
    cache.exo.social.SpaceStorage.SpaceCache.TimeToLive=7200

### ECMS Cache Configuration

    # ECMS Cache Configuration - Viewer
    cache.exo.ecms.Viewer.PDFViewer.Capacity=300
    cache.exo.ecms.Viewer.PDFViewer.TimeToLive=3600

    # ECMS Cache Configuration - Drives
    cache.exo.ecms.Drives.ManageDrive.Capacity=300
    cache.exo.ecms.Drives.ManageDrive.TimeToLive=86400

    # ECMS Cache Configuration - Scripts
    cache.exo.ecms.Scripts.ScriptService.Capacity=300
    cache.exo.ecms.Scripts.ScriptService.TimeToLive=86400

    # ECMS Cache Configuration - Templates
    cache.exo.ecms.Templates.TemplateService.Capacity=300
    cache.exo.ecms.Templates.TemplateService.TimeToLive=86400

    # ECMS Cache Configuration - Webcontent
    cache.exo.ecms.Webcontent.InitialWebContentPlugin.Capacity=300
    cache.exo.ecms.Webcontent.InitialWebContentPlugin.TimeToLive=600

    # ECMS Cache Configuration - WCM Composer
    cache.exo.ecms.WCMComposer.Capacity=1000
    cache.exo.ecms.WCMComposer.TimeToLive=3600

## Users configurations

### Super-user configuration

In eXo Platform, the user "root" is defined as the super-admin by default. You could override this configuration by modifying the system property named exo.super.user defined in configuration.properties.

### Default users list definition of eXo Platform

In eXo Platform, the default users, excluding Super-admin user, are defined in "Acme WebSite" and "Office Intranet" extensions. By deleting those extensions, the users "john", "demo", "james" and "mary" will not be created.

### Grant users access to toolbar

#### Grant all users access to toolbar but not CMS

If all new members require access to the toolbar (but NOT the Content Management System (CMS)), administrators can change the default portal behavior to meet your request by doing the following steps:

1. Define the group of new members in the organization-configuration.xml file defined in the path tomcat/webapps/ecmdemo/WEB-INF/conf/sample-portal/portal/organization-configuration.xml.

    <component-plugin>

          <name>wcm.new.user.event.listener</name>

          <set-method>addListenerPlugin</set-method>

          <type>org.exoplatform.services.organization.impl.NewUserEventListener</type>

          <description>this listener assign group and membership to a new created user</description>

          <init-params>

            <object-param>

              <name>configuration</name>

              <description>description</description>

              <object type="org.exoplatform.services.organization.impl.NewUserConfig">

                <field name="group">

                  <collection type="java.util.ArrayList">

                    <value>

                      <object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup">

                        <field name="groupId"><string>/platform/users</string></field>

                        <field name="membership"><string>member</string></field>

                      </object>

                    </value>

                  </collection>

                </field>

                <field name="ignoredUser">

                  <collection type="java.util.HashSet">

                    <value><string>james</string></value>

                  </collection>

                </field>

              </object>

            </object-param>

          </init-params>

    </component-plugin>

The sample configuration above sets the group of new users to the /platform/users group with the member role.

2. Customize the value of `<access-permissions>` in the sharedlayout.xml file defined in the path tomcat/webapps/ecm-wcm-extension/WEB-INF/conf/portal/portal/sharedlayout.xml file as follows:

    <container template="system:/groovy/portal/webui/container/UIContainer.gtmpl">

         <container template="system:/groovy/portal/webui/container/UIToolbarContainer.gtmpl">

              <!-- users containing to the following group can see the top toolbar -->

           <access-permissions>*:/platform/users</access-permissions>

           ...........................

         </container>

    </container>

3. Restart the server.

#### Grant all new users access to toolbar and CMS

If all users require access to both the toolbar and the underlying CMS implementation, administrators can change the default portal behavior to grant the appropriate permissions to newly registered users:

1. Do the same as Step 1 and Step 2 of "Grant all users access to toolbar but not CMS".

2. Edit the organization-configuration.xml file and add /platform/web-contributors to wcm.new.user.event.listener. See the example below:

    <component-plugin>

          <name>wcm.new.user.event.listener</name>

          <set-method>addListenerPlugin</set-method>

          <type>org.exoplatform.services.organization.impl.NewUserEventListener</type>

          <description>this listener assign group and membership to a new created user</description>

          <init-params>

            <object-param>

              <name>configuration</name>

              <description>description</description>

              <object type="org.exoplatform.services.organization.impl.NewUserConfig">

                <field name="group">

                  <collection type="java.util.ArrayList">

                    <value>

                      <object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup">

                        <field name="groupId"><string>/platform/users</string></field>

                        <field name="membership"><string>member</string></field>

                      </object>

                    </value>

                    <!-- new users should also be a member of the web-contributors group to see the top toolbar -->

                    <value>

                      <object type="org.exoplatform.services.organization.impl.NewUserConfig$JoinGroup">

                        <field name="groupId"><string>/platform/web-contributors</string></field>

                        <field name="membership"><string>member</string></field>

                      </object>

                    </value>

                  </collection>

                </field>

                <field name="ignoredUser">

                  <collection type="java.util.HashSet">

                    <value><string>james</string></value>

                  </collection>

                </field>

              </object>

            </object-param>

          </init-params>

    </component-plugin>

3. Restart the server.

## Gadget configuration

### Gadget proxy configuration

In eXo Platform, you could allow gadgets to load remote resources. However, this could be a potential security risk, as it will make the Gadget deployed as an open web proxy. This implies configuring ProxyFilterService.

The default configuration is set as below:

    <component>

      <key>org.exoplatform.web.security.proxy.ProxyFilterService</key>

      <type>org.exoplatform.web.security.proxy.ProxyFilterService</type>

      <init-params>

        <values-param>

          <!-- The white list -->

          <name>white-list</name>

          <!-- Accept anything not black listed -->

          <value>*</value>

        </values-param>

        <values-param>

          <name>black-list</name>

          <value>*.evil.org</value>

        </values-param>

      </init-params>

    </component>

This configuration can be added into <GATEIN_CONF_DIR>/portal/<PORTAL_CONTAINER_NAME>/configuration.xml.

- <GATEIN_CONF_DIR>= TOMCAT_HOME/gatein/conf/ if you are using Tomcat and JBOSS_HOME/server/<PROFILE>/conf/gatein/ if you are using JBoss.

- <PORTAL_CONTAINER_NAME>= the name of the used portal container, by default it is set to portal.

#### How does it work

The proxy service allows accessing any site which matches the white-list domains, unless it belongs to the black-list. If the site is not defined in neither the white list nor black list, access will be denied. Multiple values can be added for each list and wildcards can also be used.

The following is an example of the Gadget Proxy configuration:

    <component>

      <key>org.exoplatform.web.security.proxy.ProxyFilterService</key>

      <type>org.exoplatform.web.security.proxy.ProxyFilterService</type>

      <init-params>

        <values-param>

          <name>white-list</name>

          <value>*.example.com</value>

          <value>www.example.net</value>

        </values-param>

        <values-param>

          <name>black-list</name>

          <value>evil.example.com</value>

        </values-param>

      </init-params>

    </component>

### Default OAuth key configuration

In eXo Platform, OAuth gadgets use a OAuth key to authorize with external service providers. There is always a default key defined in the oauthkey.pem file. This key will be used in case the OAuth gadgets do not indicate a key.

- If you are using Tomcat, the oauthkey.pem file is found at the TOMCAT_HOME/gatein/gadgets path.

- If you are using Jboss, the oauthkey.pem file is found at the JBOSS_HOME/server/<PROFILE>/conf/gatein/gadgets path.

It is strongly recommended that you create your own oauthkey.pem file by using the openssl tool and some commands as follows:

    openssl req -newkey rsa:1024 -days 365 -nodes -x509 -keyout testkey.pem -out testkey.pem -subj '/CN=mytestkey'
    openssl pkcs8 -in testkey.pem -out oauthkey.pem -topk8 -nocrypt -outform PEM

After creating the new oauthkey.pem file, you can use it to replace the default oauthkey.pem file in the gatein/gadgets/ folder.

## JCR Links cleaner job

The links cleaning service deletes all invalid links, which target nodes has been deleted. This property is the "cron expression" of the service that is responsible of JCR links cleaning.

You can schedule the job by adding wcm.linkjob.cron.expression in the configuration.properties file.

    # Clear WCM orphan symlinks at 1.30 a.m every day

    wcm.linkjob.cron.expression=0 30 1 * * ?

### Note

To understand more about CRON expression, refer to http://en.wikipedia.org/wiki/CRON_expression#CRON_expression.

## Other properties

    # navigation controller file
    gatein.portal.controller.config=${gatein.conf.dir}/controller.xml

    # global portlet.xml
    gatein.portlet.config=${gatein.conf.dir}/portlet.xml

    # JNDI Name of the IDM datasource
    # portal name will be appended to this name before the JNDI lookup
    # example : java:/comp/env/exo-idm in "portal" portal will result in a JNDI lookup on context : java:/comp/env/exo-idm_portal
    gatein.idm.datasource.name=java:exo-idm

    # IDM
    gatein.portal.idm.createuserportal=false
    gatein.portal.idm.destroyuserportal=true

    # IDM caches
    gatein.idm.api.cache.config=file:${gatein.conf.dir}/idm/jbosscache/${gatein.jcr.config.type}/api-cache-config.xml
    gatein.idm.store.cache.config=file:${gatein.conf.dir}/idm/jbosscache/${gatein.jcr.config.type}/store-cache-config.xml

    # Key files for gadget
    gatein.gadgets.securitytokenkeyfile=${exo.shared.dir}/gadgets/key.txt
    gatein.gadgets.signingkeyfile=${exo.shared.dir}/gadgets/oauthkey.pem