XL Release - System Administration Manual

This manual describes how to install, configure, and upgrade the XL Release server.

Installing XL Release

This section contains information about installing the XL Release server.

Prerequisites

Server requirements

To install the XL Release server, the following prerequisites must be met:

Operating system: Microsoft Windows or Unix-family operating system running Java 7
Java runtime environment: JDK 1.7 (Oracle or IBM)
RAM: At least 2GB of RAM available for XL Release
Hard disk space: At least 2GB of hard disk space to store the XL Release repository (this depends on your usage of XL Release)

Depending on the environment, the following may also be required:

Database: XL Release's repository may be stored in a database; for more information, see Configure the repository
LDAP: To enable group-based security, an LDAP x.509 compliant registry is required; for more information, see Configuring LDAP security

Client requirements

The following web browsers are supported for the XL Release GUI:

Internet Explorer 8.0 or higher
Firefox
Chrome
Safari

Installation procedure

Note: See The upgrade process for instructions on how to upgrade XL Release from a previous version.

To install the XL Release server application:

Log in to the server where the XL Release Server will be installed. It is recommended to install XL Release server as a non-root user such as xl-release.
Create an installation directory such as /opt/xebialabs/xl-release.
Copy the XL Release server archive to the directory.
Extract the archive into the directory.

XL Release server directory structure

After the XL Release installation file is extracted, the following directory structure exists in the installation directory:

bin: Contains the server binaries
conf: Contains server configuration files
ext: Contains server Java extensions
hotfix: Contains hotfixes that correct issues with the server software
lib: Contains libraries that the server needs
log: contains server log files

Throughout this document, the installation directory is referred to as XL_RELEASE_SERVER_HOME_.

Installing the license

XL Release requires a valid license to operate. Your XebiaLabs representative will provide a license.

To activate the license, save the xl-release-license.lic file in the XL_RELEASE_SERVER_HOME/conf directory.

Running the server Setup Wizard

Run the XL Release Setup Wizard to start the XL Release server and prepare it for use. The command server.sh -setup starts the wizard. If you want to stop the Setup Wizard at any time, enter exitsetup. All changes to the configuration will be discarded.

The Setup Wizard displays the following welcome message:

Welcome to the XL Release setup.
You can always exit by typing 'exitsetup'.
To re-run this setup and make changes to the XL Release server configuration
you can run server.cmd -setup on Windows or server.sh -setup on Unix.

Do you want to use the simple setup?
Default values are used for all properties. To make changes to the default
properties, please answer no.
Options are yes or no.
[yes]:

Answer yes or press ENTER to use the simple setup. Simple setup makes it easy to quickly get started with XL Release and to use the product's default configuration. See Simple setup for more information.

Answer no to use the manual setup. Manual setup provides explicit control over all XL Release settings. See Manual setup for more information.

Edit an existing configuration

If you have installed XL Release in the same location before, the Setup Wizard will ask you whether you want to edit the existing configuration or create a new one. Answer yes or press ENTER to edit the existing configuration. The Setup Wizard will load all settings from the existing configuration and allow you to choose simple or manual setup. Answer no to start over with an empty configuration.

Simple setup

Using simple setup, the Setup Wizard uses the default values for all configuration parameters:

The server will run with security enabled.
The server will not use secure communication between the XL Release GUI and the XL Release server.
The server will listen on XL Release's standard HTTP port (5516).
The server will use / as the context root.
The server will use a minimum of 3 and a maximum of 24 threads.

First, the Setup Wizard will ask you to provide a password for the built-in admin user.

Please enter the admin password you wish to use for XL Release
New password:
Re-type password:

The admin user has all permissions (like root on a Unix operating system). The admin user is also used to connect to the JCR repository. If you connect to an existing repository, ensure that enter the password that has been used before to connect to the repository; otherwise, the XL Release server will not be able to connect.

If you provide an empty password by pressing ENTER twice, the default password admin is used.

Then, the Setup Wizard will ask:

Do you want XL Release to initialize the JCR repository?
Options are yes or no.
[yes]:

Answer yes or press ENTER if you want the XL Release repository to be recreated. The Setup Wizard must have write access to the repository directory. Answer no to leave the repository intact. This option is useful if you have an existing repository that you want to reuse.

Warning: If you choose to recreate the XL Release repository and you have installed XL Release in the same location before, any information stored in the repository will be lost.

If you answer yes, the Setup Wizard will ask the following questions to help you configure your repository:

The password encryption key protects the passwords stored in the repository.
Do you want to generate a new password encryption key?
Options are yes or no.
[yes]:

XL Release includes a default encryption key. By answering no, you agree to use either the XL Release-provided key or any key you previously generated. Answer yes to generate a new key. When you do this, you have the option of locking the keystore with a password as well:

The password encryption key is optionally secured by a password.
Please enter the password you wish to use. (Use an empty password to avoid a password prompt when starting XL Release.)
New password:
Re-type password:

If you want to secure the keystore with a password, enter the password here. You must provide this password to XL Release when it starts, either interactively via a prompt or via a command line parameter. If you do not want to use a password for the keystore, press ENTER.

See Finishing the setup process to complete the setup process.

Manual setup

The manual setup procedure contains the following steps.

Setting the admin password

First, the Setup Wizard asks you to provide a password for the built-in admin user.

Please enter the admin password you wish to use for XL Release Server
New password:
Re-type password:

Secure communication configuration**

The Setup Wizard shows the following message:

Would you like to enable SSL?
Options are yes or no.
[yes]:

Answer no to use regular unsecured communication between the GUI and the server. Continue with the HTTP configuration section.

Answer yes or press ENTER to use a secure connection between the GUI and the server. If you answer yes, the Setup Wizard asks the following question to help you configure secure communication:

Would you like XL Release to generate a keystore with a self-signed
certificate for you?
N.B.: Self-signed certificates do not work correctly with some versions
of the Flash Player and some browsers!
Options are yes or no.
[yes]:

Answer yes or press ENTER if you want the Setup Wizard to generate a digital certificate automatically. The digital certificate is required to secure communication and is normally signed by a Certificate Authority (CA).

The Setup Wizard can generate a self-signed certificate if there is no official certificate available. Note that using a self-signed certificate may trigger security warnings in some Flash players and browsers. Continue with the HTTP configuration section.

Answer no if you want to use your own keystore. XL Release uses the built-in Jetty web server to communicate with the GUI. Jetty requires a certificate with the name jetty to be present in the keystore.

The Setup Wizard prompts you for the following keystore information:

What is the path to the keystore?
[]:

What is the password to the keystore?
[]:

What is the password to the key in the keystore?
[]:

Enter the filesystem location of the keystore (for example, mykeystore.jks), the password to unlock the keystore, and the password for the Jetty certificate in the keystore.

The Setup Wizard shows the following message:

Would you like to enable mutual SSL?
Options are yes or no.
[yes]:

Answer yes or press ENTER if you want the Setup Wizard to configure mutual SSL.

Answer no if you do not want mutual SSL. Continue with the HTTP configuration section.

The Setup Wizard prompts you for the following mutual SSL information:

What is the path to the truststore?
[]:

What is the password to the truststore?
[]:

Enter the filesystem location of the truststore (for example, cacerts.jks) and the password to unlock the truststore.

HTTP configuration

The Setup Wizard shows the following questions:

What http bind address would you like the server to listen on?
[localhost]:

What http port number would you like the server to listen on?
[5516]:

Enter the web context root where XL Release will run
[/]:

Enter the host name, port number, and context root that the XL Release server listens on for connections.

XL Release derives its URL from this information. This URL is used in the emails that the XL Release server sends. In the next question, you can override this value. For example, if XL Release runs behind a proxy server and must be accessed using a different URL:

Enter the public URL to access XL Release
[http://xlrelease-server:5516/]:

Thread configuration

The Setup Wizard shows the following questions:

Enter the minimum number of threads the HTTP server should use (recommended:
    3 per client, so 3 for single user usage)
[3]:

Enter the minimum number of threads that the XL Release server uses to handle incoming connections. The recommended minimum number of threads is 3 per XL Release application client.

Enter the maximum number of threads the HTTP server should use (recommended :
    3 per client, so 24 for 8 concurrent users)
[24]:

Enter the maximum number of threads that the XL Release server uses to handle incoming connections. The recommended maximum number of threads is 3 per XL Release application client.

Note: After setup is complete0, you can see the thread configuration in the threads.min and threads.max settings in the conf/xl-release-server.conf file.

Repository configuration

The Setup Wizard shows the following questions:

Where would you like XL Release to store the JCR repository?
[repository]:

Enter the filesystem path to a directory where XL Release will create the repository. If the directory does not exist, the Setup Wizard will create it.

Do you want XL Release to initialize the JCR repository?
Options are yes or no.
[yes]:

Answer no to leave the repository intact.

Answer yes or press ENTER if you want the XL Release repository to be recreated. The Setup Wizard must have write access to the repository directory. The Setup Wizard will ask the following questions to help you configure your repository:

The password encryption key protects the passwords stored in the repository.
Do you want to generate a new password encryption key?
Options are yes or no.
[yes]:

Warning: If you choose to recreate the XL Release repository and you have installed XL Release in the same location before, any information stored in the repository will be lost.

XL Release ships with a default encryption key that matches the encryption key used in earlier versions of XL Release. By answering no, you agree to use either the XL Release-provided key or any key you previously generated. Answer yes to generate a new key. When you do this, you have the option of locking the keystore with a password as well:

The password encryption key is optionally secured by a password.
Please enter the password you wish to use. (Use an empty password to avoid a password prompt when starting XL Release.)
New password:
Re-type password:

If you want to secure the keystore with a password, enter the password here. You must to provide this password to XL Release when it starts, either interactively via a prompt or via a command line parameter. If you do not want to use a password for the keystore, press enter.

Finishing the setup process

Afer you have completed configuration of the setup process, the Setup Wizard displays an overview of all selected options. For example:

Do you agree with the following settings for XL Release and would you like
    to save them?
Changes will be saved in xl-release-server.conf
    SSL will be disabled
    HTTP bind address is localhost
    HTTP port is 5516
    HTTP server will use a minimum of 3 and a maximum of 24 threads
    JCR repository home is at repository
    JCR repository will be initialized.
    Task recovery file will deleted
[yes]:

Answer yes or press ENTER to store the configuration settings and end the Setup Wizard. If you selected the option to initialize the repository, this will be done now.

Answer no to abort the Setup Wizard.

If the Setup Wizard completes successfully, it shows the following message:

You can now start your XL Release server by executing the command server.cmd
    on Windows or server.sh on Unix.
Note: If your XL Release server is running please restart it.
Finished setup.

Changing the encryption key password

The passwords in the repository are encrypted with a secret key. This password encryption key is stored in a keystore file called conf/repository-keystore.jceks, which is optionally protected with a password. If a password is set, you must enter it when the XL Release Server starts.

To change the keystore password, use the keytool utility that is part of the Java JDK distribution:

keytool -storepasswd -keystore conf/repository-keystore.jceks -storetype jceks

However, there is one restriction: keytool will not to read or set passwords that are shorter than 6 characters. If you want to change a keystore with an empty or short password, download the third-party application KeyStore Explorer.

Note: repository-keystore.jceks is one of the two keystore concepts in XL Release. This keystore only contains the key used for encryption of passwords in the repository. If you use HTTPS, XL Release will use a second keystore file to store the (self-signed) certificate.

High availability setup

XL Release can be configured to ensure maximum uptime of the application. In such a high availability setup, two instances of XL Release run in an active/passive configuration. At any one time, only one XL Release instance is active; but as soon as a failure is detected, the passive XL Release instance is activated and the failed instance is taken down for repair.

To configure XL Release for high availability, the XL Release repository must be used in clustering mode. This means that each XL Release node writes changes to a shared journal in addition to applying the change to its own repository. See Configure the repository for information about setting up clustering.

Configuring XL Release

This section contains information about the configuration of the XL Release server.

Configuring custom passwords

XL Release provides a mechanism to automatically encrypt passwords and allow you to refer to them, so you do not need to store third-party passwords in plain text in configuration files

Declare a new custom password

To declare a new custom password, add it in the conf/xl-release-server.conf file:

third.party.password=value

Note: The key must end with ".password".

The next time that you start XL Release, your password will automatically be encrypted in the xl-release-server.conf file:

third.party.password={b64}nbbZ2zHXozfxiz1+ooe8hg\=\=

Refer to a custom password

After you declare a custom password, you can use it in Spring and Jackrabbit configuration files.

For example, if you have declared mysql.xlrelease.password in the xl-release-server.conf file, then you can use it in the conf/jackrabbit-repository.xml file:

<PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.MySqlPersistenceManager">
    <param name="url" value="jdbc:mysql://localhost:3306/xlrelease" />
    <param name="user" value="xlrelease" />
    <param name="password" value="${mysql.xlrelease.password}" />
</PersistenceManager>

Client security configuration

client.session.timeout.minutes: The number of minutes it takes before the user is disconnected when he is not using the XL Release GUI. The default value of '0' means that no time-out is configured. This configuration is only applicable during one browser session. If user closes the browser then the user will have to login again.

Configuring LDAP Security

XL Release cookies store security information that is provided by the Spring Security framework. XL Release does not store any additional information in cookies.

XL Release can be configured to use an LDAP repository to authenticate users and to retrieve role (group) membership. The LDAP users and groups are used as principals in XL Release and can be mapped to XL Release roles. Role membership and rights assigned to roles are always stored in the JCR repository.

XL Release treats the LDAP repository as read-only. This means that XL Release will use the information from the LDAP repository, but it cannot make changes to that information.

To configure XL Release to use an LDAP repository, modify the xl-release-security.xml security configuration file. For a step-by-step procedure, refer to How to connect to your LDAP or Active Directory.

Note: You must restart the XL Release server after you configure LDAP access.

Sample XL Release security file

This is an example of a working xl-release-security.xml file that uses LDAP:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:security="http://www.springframework.org/schema/security"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security.xsd
    ">

    <bean id="ldapServer" class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">
        <constructor-arg value="LDAP_SERVER_URL" />
        <property name="userDn" value="MANAGER_DN" />
        <property name="password" value="MANAGER_PASSWORD" />
        <property name="baseEnvironmentProperties">
            <map>
                <entry key="java.naming.referral">
                    <value>ignore</value>
                </entry>
            </map>
        </property>
    </bean>

    <bean id="ldapProvider" class="com.xebialabs.xlrelease.security.authentication.LdapAuthenticationProvider">
        <constructor-arg>
            <bean class="org.springframework.security.ldap.authentication.BindAuthenticator">
                <constructor-arg ref="ldapServer" />
                <property name="userSearch">
                    <bean id="userSearch" class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
                        <constructor-arg index="0" value="USER_SEARCH_BASE" />
                        <constructor-arg index="1" value="USER_SEARCH_FILTER" />
                        <constructor-arg index="2" ref="ldapServer" />
                    </bean>
                </property>
            </bean>
        </constructor-arg>
        <constructor-arg>
            <bean class="org.springframework.security.ldap.userdetails.DefaultLdapAuthoritiesPopulator">
                <constructor-arg ref="ldapServer" />
                <constructor-arg value="GROUP_SEARCH_BASE" />
                <property name="groupSearchFilter" value="GROUP_SEARCH_FILTER" />
                <property name="rolePrefix" value="" />
                <property name="searchSubtree" value="true" />
                <property name="convertToUpperCase" value="false" />
            </bean>
        </constructor-arg>
    </bean>

    <bean id="rememberMeAuthenticationProvider" class="com.xebialabs.deployit.security.authentication.RememberMeAuthenticationProvider"/>

    <bean id="jcrAuthenticationProvider" class="com.xebialabs.deployit.security.authentication.JcrAuthenticationProvider"/>

    <security:authentication-manager alias="authenticationManager">
        <security:authentication-provider ref="rememberMeAuthenticationProvider" />
        <security:authentication-provider ref="ldapProvider" />
        <security:authentication-provider ref="jcrAuthenticationProvider"/>
    </security:authentication-manager>

</beans>

The XML fragment above contains placeholders for the following values:

LDAP_SERVER_URL: The LDAP URL to connect to (example: ldap://localhost:1389/).
MANAGER_DN: The principal to perform the initial bind to the LDAP server (example: "cn=admin,dc=example,dc=com").
MANAGER_PASSWORD: The credentials to perform the initial bind to the LDAP server (example: "secret"). See Configuring custom passwords for information about encrypting this password.
USER_SEARCH_FILTER: The LDAP filter to determine the LDAP DN for the user who is logging in. {0} will be replaced with the user name (example: "(&(uid={0})(objectClass=inetOrgPerson))").
USER_SEARCH_BASE: The LDAP filter that is the base for searching for users (example: "dc=example,dc=com").
GROUP_SEARCH_FILTER: The LDAP filter to determine the group memberships for the user. {0} will be replaced with the DN of the user (example: "(memberUid={0})").
GROUP_SEARCH_BASE: The LDAP filter that is the base for searching for groups (example: "ou=groups,dc=example,dc=com").

Assign a default role to all authenticated users

In the xl-release-security.xml file, you can configure:

An LDAP setup in which there is not a group that contains all XL Release users
You want to use such a group in the default JcrAuthenticationProvider

The code below sets up an group called everyone that is assigned to each user who is authenticated (the group name can be anything you want). You can then link this group to a XL Release role and assign 'login' privileges to it.

<beans>
    ...

    <bean id="ldapProvider" class="com.xebialabs.xlrelease.security.authentication.LdapAuthenticationProvider">
        <constructor-arg>
            ...
        </constructor-arg>

        <property name="authoritiesMapper" ref="additionalAuthoritiesMapper" />
    </bean>

    <bean id="jcrAuthenticationProvider" class="com.xebialabs.deployit.security.authentication.JcrAuthenticationProvider">
        <property name="authoritiesMapper" ref="additionalAuthoritiesMapper" />
    </bean>

    <bean id="additionalAuthoritiesMapper" class="com.xebialabs.deployit.security.AdditionalAuthoritiesMapper">
        <property name="additionalAuthorities">
            <list>
                <value>everyone</value>
            </list>
        </property>
    </bean>

</beans>

Configure the repository

XL Release uses a repository to store all of its data. XL Release can use the filesystem or a database to maintain the repository. By default, XL Release uses the filesystem to store all data in the repository.

Using a database

XL Release can use a database to store its repository. The built-in Jackrabbit JCR implementation must be configured to make this possible.

There are several configuration options when setting up a database repository:

Store only binary artifacts in a database. This requires you to configure the DataStore property.
Store only CIs and CI history in a database. This requires you to configure the PersistenceManager and FileSystem properties.
Store all data (binary artifacts and CIs and CI history) in a database. This requires you to configure the DataStore, PersistenceManager, and FileSystem properties.

Here are some examples of configuring XL Release to use a database for various database vendors. The XML snippets below must be placed in the conf/jackrabbit-repository.xml file.

Note: XL Release must initialize the repository before it can be used. Run XL Release's Setup Wizard and initialize the repository after making any changes to the repository configuration.

Note: See Configuring custom passwords for information about encrypting the database password.

For more information about using a database with Jackrabbit, see its PersistenceManager FAQ and DataStore FAQ.

Using XL Release with MySQL

<DataStore class="org.apache.jackrabbit.core.data.db.DbDataStore">
    <param name="driver" value="com.mysql.jdbc.Driver"/>
    <param name="url" value="jdbc:mysql://localhost:3306/xlrelease"/>
    <param name="databaseType" value="mysql"/>
    <param name="user" value="xlrelease" />
    <param name="password" value="XL Release" />
</DataStore>

<Workspace name="${wsp.name}">
    <FileSystem class="org.apache.jackrabbit.core.fs.db.DbFileSystem">
        <param name="driver" value="com.mysql.jdbc.Driver"/>
        <param name="url" value="jdbc:mysql://localhost:3306/xlrelease"/>
        <param name="schemaObjectPrefix" value="${wsp.name}_" />
        <param name="schema" value="mysql" />
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
    </FileSystem>

    <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.MySqlPersistenceManager">
        <param name="driver" value="com.mysql.jdbc.Driver"/>
        <param name="url" value="jdbc:mysql://localhost:3306/xlrelease" />
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
        <param name="schemaObjectPrefix" value="${wsp.name}_" />
    </PersistenceManager>

    <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
        <param name="path" value="${wsp.home}/index" />
        <param name="supportHighlighting" value="true" />
    </SearchIndex>

</Workspace>

<Versioning rootPath="${rep.home}/version">
    <FileSystem class="org.apache.jackrabbit.core.fs.db.DbFileSystem">
        <param name="driver" value="com.mysql.jdbc.Driver"/>
        <param name="url" value="jdbc:mysql://localhost:3306/xlrelease"/>
        <param name="schemaObjectPrefix" value="version_" />
        <param name="schema" value="mysql" />
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
    </FileSystem>

    <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.MySqlPersistenceManager">
        <param name="url" value="jdbc:mysql://localhost:3306/xlrelease" />
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
        <param name="schemaObjectPrefix" value="version_" />
    </PersistenceManager>
</Versioning>

Note: The MySQL database is not suited for storage of large binary objects; see the MySQL bug tracker.

Using XL Release with DB2

<DataStore class="org.apache.jackrabbit.core.data.db.DbDataStore">
        <param name="driver" value="com.ibm.db2.jcc.DB2Driver"/>
        <param name="url" value="jdbc:db2://localhost:50002/xlrelease"/>
        <param name="databaseType" value="db2"/>
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
</DataStore>

<Workspace name="${wsp.name}">
    <FileSystem class="org.apache.jackrabbit.core.fs.db.DbFileSystem">
            <param name="driver" value="com.ibm.db2.jcc.DB2Driver"/>
            <param name="url" value="jdbc:db2://localhost:50002/xlrelease"/>
            <param name="schemaObjectPrefix" value="${wsp.name}_" />
            <param name="schema" value="db2" />
            <param name="user" value="xlrelease" />
            <param name="password" value="XL Release" />
    </FileSystem>

     <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.BundleDbPersistenceManager">
            <param name="driver" value="com.ibm.db2.jcc.DB2Driver"/>
            <param name="url" value="jdbc:db2://localhost:50002/xlrelease" />
            <param name="user" value="xlrelease" />
            <param name="password" value="XL Release" />
            <param name="databaseType" value="db2" />
            <param name="schemaObjectPrefix" value="${wsp.name}_" />
         </PersistenceManager>

    <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
        <param name="path" value="${wsp.home}/index" />
        <param name="supportHighlighting" value="true" />
    </SearchIndex>
</Workspace>

<Versioning rootPath="${rep.home}/version">
    <FileSystem class="org.apache.jackrabbit.core.fs.db.DbFileSystem">
        <param name="driver" value="com.ibm.db2.jcc.DB2Driver"/>
        <param name="url" value="jdbc:db2://localhost:50002/xlrelease"/>
        <param name="schemaObjectPrefix" value="version_" />
        <param name="schema" value="db2" />
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
    </FileSystem>
    <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.BundleDbPersistenceManager">
        <param name="driver" value="com.ibm.db2.jcc.DB2Driver"/>
        <param name="url" value="jdbc:db2://localhost:50002/xlrelease" />
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
        <param name="databaseType" value="db2" />
        <param name="schemaObjectPrefix" value="version_" />
    </PersistenceManager>
</Versioning>

Using XL Release with Oracle

<DataStore class="org.apache.jackrabbit.core.data.db.DbDataStore">
    <param name="driver" value="oracle.jdbc.OracleDriver"/>
    <param name="url" value="jdbc:oracle:thin:@localhost:1521:orcl"/>
    <param name="databaseType" value="oracle"/>
    <param name="user" value="xlrelease" />
    <param name="password" value="XL Release" />
</DataStore>

<Workspace name="${wsp.name}">
    <FileSystem class="org.apache.jackrabbit.core.fs.db.OracleFileSystem">
        <param name="driver" value="oracle.jdbc.OracleDriver"/>
        <param name="url" value="jdbc:oracle:thin:@localhost:1521:orcl"/>
        <param name="schemaObjectPrefix" value="${wsp.name}_"/>
        <param name="schema" value="oracle" />
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
    </FileSystem>

    <PersistenceManager
        class="org.apache.jackrabbit.core.persistence.bundle.OraclePersistenceManager">
        <param name="driver" value="oracle.jdbc.OracleDriver"/>
        <param name="url" value="jdbc:oracle:thin:@localhost:1521:orcl"/>
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
        <param name="databaseType" value="oracle" />
        <param name="schemaObjectPrefix" value="${wsp.name}_" />
    </PersistenceManager>

    <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
        <param name="path" value="${wsp.home}/index" />
        <param name="supportHighlighting" value="true" />
    </SearchIndex>
</Workspace>

<Versioning rootPath="${rep.home}/version">
    <FileSystem class="org.apache.jackrabbit.core.fs.db.OracleFileSystem">
        <param name="driver" value="oracle.jdbc.OracleDriver"/>
        <param name="url" value="jdbc:oracle:thin:@localhost:1521:orcl"/>
        <param name="schemaObjectPrefix" value="version_"/>
        <param name="schema" value="oracle" />
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
    </FileSystem>

    <PersistenceManager
        class="org.apache.jackrabbit.core.persistence.bundle.OraclePersistenceManager">
        <param name="driver" value="oracle.jdbc.OracleDriver"/>
        <param name="url" value="jdbc:oracle:thin:@localhost:1521:orcl"/>
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
        <param name="databaseType" value="oracle" />
        <param name="schemaObjectPrefix" value="version_" />
    </PersistenceManager>
</Versioning>

If you use the TNSNames Alias syntax to connect to Oracle, you may need to inform the driver where to find the TNSNAMES file. See the Oracle documentation for more information.

Clustering

It is also possible to run XL Release server with its repository shared with other XL Release server instances. In this case, you must configure the Jackrabbit JCR to run in clustered mode. This needs a cluster configuration to be present in the jackrabbit-repository.xml file.

File-based repository

Add the following snippet to jackrabbit-repository.xml to enable clustering:

<Cluster id="node1">
  <Journal class="org.apache.jackrabbit.core.journal.FileJournal">
    <param name="revision" value="${rep.home}/revision.log" />
    <param name="directory" value="/nfs/myserver/myjournal" />
  </Journal>
</Cluster>

In this example, the property directory refers to the shared journal. Both XL Release instances must be able to write to the same journal.

Database repository

The following XML snippet shows a sample clustering configuration for a JCR using Oracle as its repository:

<Cluster id="101" syncDelay="2000">
    <Journal class="org.apache.jackrabbit.core.journal.OracleDatabaseJournal">
        <param name="revision" value="${rep.home}/revision" />
        <param name="driver" value="oracle.jdbc.OracleDriver" />
        <param name="url" value="jdbc:oracle:thin:@localhost:1521:orcl" />
        <param name="user" value="xlrelease" />
        <param name="password" value="XL Release" />
        <param name="schemaObjectPrefix" value="JOURNAL_" />
    </Journal>
</Cluster>

Note that each Jackrabbit cluster node should have a unique value for id. For more information about JCR clustering or ways to configure clustering using other databases, refer to the Jackrabbit clustering documentation.

Logging

Configuring logging

By default, XL Release server writes informational, warning, and error log messages to standard output and log/xl-release.log when running. In addition, XL Release writes an audit trail to the file log/audit.log. It is possible to change XL Releases logging behavior (for instance, to write log output to a file or to log output from a specific source).

XL Release uses the Logback logging framework for its logging. To change the behavior, edit the file logback.xml in the conf directory of the XL Release server installation directory.

The following is an example logback.xml file:

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <!-- encoders are assigned the type
             ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
        <encoder>
              <pattern>
                %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
            </pattern>
        </encoder>
    </appender>

    <!-- Create a file appender that writes log messages to a file -->
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <layout class="ch.qos.logback.classic.PatternLayout">
            <pattern>%-4relative [%thread] %-5level %class - %msg%n</pattern>
        </layout>
           <File>log/my.log</File>
    </appender>

    <!-- Set logging of classes in com.xebialabs to INFO level -->
    <logger name="com.xebialabs" level="info"/>

    <!-- Set logging of class HttpClient to DEBUG level -->
    <logger name="HttpClient" level="debug"/>

    <!-- Set the logging of all other classes to INFO -->
    <root level="info">
        <!-- Write logging to STDOUT and FILE appenders -->
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>

</configuration>

For more information, see the Logback website.

Audit log

XL Release can write an audit log for each human-initiated event on the server. For each event, the following information is recorded:

The user making the request
The event timestamp
The component producing the event
An informational message describing the event

For events involving CIs, the CI data submitted as part of the event is logged in XML format.

Some of the events that are logged in the audit trail are:

The system is started or stopped
A user logs into or out of the system
An application is imported
A CI is created, updated, moved, or deleted
A security role is created, updated, or deleted
A task (deployment, undeployment, control task, or discovery) is started, cancelled, or aborted

By default, the audit log is stored in log/audit.log. The audit log is rolled over daily.

Starting and stopping XL Release

Starting the server

Open a terminal window and change to the XL_RELEASE_SERVER_HOME directory. To start the XL Release server on a Unix system, enter:

bin/server.sh

To start the XL Release server on a Window system, enter:

bin/server.cmd

Start the server with the -h flag to see the options that are available:

    Supported options:
     -help                  : Prints this usage message
     -repository-keystore-password VAL : The password to open the repository keystore file, if not given,
                              the server will prompt you.
     -reinitialize          : Reinitialize the repository, only useful with -setup
     -setup                 : (Re-)run the setup 
     -setup-defaults VAL    : Use the given file for defaults during setup server.sh arguments...

The command line options are:

-repository-keystore-password VAL: Identifies the password to use to access the repository keystore. If not specified and the repository keystore does require a password, XL Release will prompt you for it.
-reinitialize: Reinitialize the repository. Used only in conjunction with -setup. Note: This flag only works if XL Release is running on the filesystem repository. It does not work when you have configured XL Release to run against a database.
-setup: Runs the XL Release Setup Wizard.
-setup-defaults VAL: Specifies a file that contains default values for configuration properties set in the Setup Wizard.

Server options

Any options you want to give the XL Release server when it starts can be specified in the XL_RELEASE\_SERVER\_OPTS environment variable.

Starting XL Release in the background

When you execute the server.sh or server.cmd command, the XL Release server is started in the foreground. To run the server as a background process on a Unix system, use:

nohup bin/server.sh &

On a Windows system, you must configure XL Release to run as a service.

Stopping the server

You can stop the XL Release server using a REST API call. The following is an example of a command to generate such a call (replace admin:admin with your own credentials):

curl -X POST --basic -u admin:admin
    http://admin:admin@localhost:5516/server/shutdown

This requires the external curl command, which is available for both Unix and Windows.

You can also shut down the server using the command-line interface.

Maintaining XL Release

This section describes how to maintain the XL Release server in your environment.

Creating backups

To create a backup of XL Release, several components may need to be backed up depending on your configuration:

Repository:
- Built-in repository: Create a backup of the built-in JCR repository by backing up the files in the repository directory.
- Database repository: Create a backup of the files in the repository directory, and the database (using the tools provided by your database vendor).
Configuration: Create a backup of the XL Release configuration by backing up the files in the conf directory in the installation directory.

Important: XL Release must not be running when you are making a backup. Schedule backups outside planned deployment hours to ensure the server is not being used.

Restoring backups

To restore a backup of XL Release, restore one of the following components:

JCR repository:
- Built-in repository: Remove the repository directory and replace it with the backup.
- Database repository: Remove the repository directory and replace it with the backup. Then, restore a backup of the database using the tools provided by your vendor.
Configuration: Remove the conf directory in the XL_RELEASE_SERVER_HOME directory and replace it with the backup.

Important: XL Release must not be running when you are restoring a backup.