Configure initial site settings

You can configure initial site settings using the setup.xml file. You must configure the settings in the setup.xml file during the ALM Octane installation.

Caution: These settings cannot be changed later.


Configure these settings by editing the setup.xml file, for example, with an editor such as nano:   nano /opt/octane/conf/setup.xml

Configuration files must be readable and editable by the user installing ALM Octane, which is generally the octane user. If you copy or edit a configuration file as the root or sudoer user that does not have the necessary installation permissions, the install fails.

Tip: To change the owner: chown <owner>:<group> <file>

Examplechown octane:octane setup.xml

It is recommended that you save a local copy of the setup.xml file before making changes to it.

Also, for security purposes, setup.xml should be stored in a secure, off-site location.

Back to top

Database server settings

The Oracle settings can be used for both Oracle and SQL server.

Oracle settings Description

The supported database types are:




The name of the site schema that is created by the DBAdminUser during the installation, or supplied by the organization's DBA. Enter the supplied name.


For Oracle

  • The password of the site schema. Enter the supplied password.

  • When using Oracle, and installing using existing site schemas (with the FILL_EXISTING site action), make sure that the passwords that the DBA defines for the site schema and the space schema both match this SchemaPassword.

For SQL Server

The password for the DBLoginUser user.


ALM Octane uses the DBAdminUser both to create objects during installation and also to check that the database server is accessible.

For Oracle: 

  • The name of the database admin user (DBAdminUser). 

  • When using Oracle, and installing using existing site schemas (with the FILL_EXISTING site action), enter the SchemaName.

For SQL Server: 

Login object for logging into the database instance. ALM Octane uses this login for setup, tables, and indexes.

  • This is either the sa user or an SQL Server power user with the correct permissions.

  • When using SQL Server, and installing using the FILL_EXISTING site action, enter the DBAdminUser value.

For details about DBAdminUser permissions, see Permissions.

For the FILL_EXISTING site action, make sure to also specify SharedSpaceSchemaName.


For Oracle: The password of the database admin user (DBAdminUser).

  • Do not include a pound sign (#) or accented characters (such as, ä, ç, ñ).

  • When installing using existing site schemas (with the FILL_EXISTING site action), enter the SchemaPassword.

For SQL Server: Password for the sa user or the SQL Server power user defined with the DBAdminUser setting.


The Java Database Connectivity (JDBC) database connection string. It includes the following details: database type, database server name, database server port number, service name.

The instructions below demonstrate how to set up the string with non-secured database access. However, you can use this connection string to configure secure access to the database. For details, see Configure secure database access.


  • Syntax using TNS alias names:

    To use TNS alias names, make sure to provide a value for the DBServerName setting.

    <entry key="ConnectionString">jdbc:mercury:oracle:TNSNamesFile=/<path>/tnsnames.ora;TNSServerName=<server_name></entry>



  • Syntax using service names:

    <entry key="ConnectionString">jdbc:mercury:oracle://DB_SERVER_NAME:DB_SERVER_PORT;servicename=DB_SERVICE_NAME</entry>



To connect to Oracle RAC, use the Single Client Access Name (SCAN) instead of the database server name.


  • Syntax using port:

    <entry key="ConnectionString">jdbc:mercury:sqlserver://DB_SERVER_NAME:DB_SERVER_PORT</entry>



  • Syntax using instance:

    <entry key="ConnectionString">jdbc:mercury:sqlserver://DB_SERVER_NAME/INSTANCE_NAME</entry>



Back to top

Oracle server settings

Oracle settings Description

The tablespace in the Oracle database where the site schema segment will be created. Case-sensitive.

TempTableSpace The temporary tablespace in the Oracle database. Case-sensitive.

The TNS alias name for connecting to the Oracle database. Optional.

For use with Configure initial site settings .


DBServerPort The port for connecting to the Oracle database.

Back to top

SQL server settings

SQL Server settings Description


MSSQL database login authentication user for ALM Octane. This is the user for day-to-day ALM Octane use.

This login is associated with the ALM Octane site and space databases.

Specify the password for this user using the SchemaPassword setting. Do not include a pound sign (#) or accented characters (such as, ä, ç, ñ).

If the DBLoginUser user already exists, make sure to use the existing user's password.

Back to top

Site actions

The SiteAction setting determines how the installation should handle databases. Possible values:


Use this site action for new installations.

  • Creates a new site schema, creates a new space schema, and configures the current node.
  • Only a DBAdminUser with create schema permissions can create a new schema.
  • The CREATE_NEW site action fails when the schema already exists.


Use this site action for new installations, in cases where the database admin user does not give permissions to create a schema (for Oracle) or a database (for SQL Server)..

For SQL Server:

Two databases are created, one for the site and one for the space. Both are created by the DBA.

  • The default collation is SQL_Latin1_General_CP1_CI_AS (must be case-insensitive).

  • Make sure you specify these databases in the SchemaName and SharedSpaceSchemaName settings, because they are mandatory.

  • Make sure you define the DbLoginUser setting.

For Oracle:

Two schemas are created, one for the site and one for the space. Both are created by the DBA.

SharedSpaceSchemaName should have the same password as SchemaName.

Make sure that the passwords that the DBA defines for the site schema and the shared space schema both match the SchemaPassword setting.

Handling schema exceptions

If the organization's DBA made changes to schemas, such as the addition of tables or columns, you can define an exception file. The exception file instructs ALM Octane to ignore manual changes to the database user schema during installation and upgrade. For details, see Using exception files for manual database changes.

For SQL Server: Example of creating a database and granting user access

CREATE DATABASE <database_name>

CREATE LOGIN <login_name> WITH PASSWORD = 'thepassword', CHECK_POLICY = OFF

USE <database_name>

sp_adduser '<logName>' , 'octane'

GRANT ALL TO octane sp_addrolemember 'db_ddladmin','octane'

Back to top

Space settings

Where relevant, the Oracle settings can be used for both Oracle and SQL server. Alternatively, for SQL Server, you can specify the SQL Server settings instead.

Oracle settings SQL Server settings Description
SharedSpaceSchemaName MssqlSharedspaceDatabaseName

Relevant only for the FILL_EXISTING site action.

For Oracle

To configure the space, add a SharedSpaceSchemaName parameter and set it to the name of the schema that is designated for the space.

For SQL Server:  

To configure the space, add a MssqlSharedspaceDatabaseName parameter and set it to the name of the database that is designated for the space.

DefaultSpaceMode <NA>

The mode in which the initial space will be created when the ALM Octane server starts. Valid values are: 

  • isolated. Workspaces associated with the initial space will not share entities or customization settings.

  • shared. Workspaces associated with the initial space can share entities or customization settings.


<entry key="DefaultSpaceMode">isolated</entry>

<entry key="DefaultSpaceMode">shared</entry>

Back to top

Elasticsearch settings

A working Elasticsearch server is a requirement for working with ALM Octane. Make sure you are using a version supported by ALM Octane:

  • For the supported version, see the requirements for Database and Elasticsearch.

  • For details on installing Elasticsearch, see knowledge base article KM02494295.

  • For details on upgrading to a new Elasticsearch version, see knowledge base article KM03207448.


The name of the host running Elasticsearch.

If running an Elasticsearch cluster, all node host names should be separated by semi-colons (;).

Example: host1;host2;host3


The number of the port running the Elasticsearch binary service.

This port must be accessible from the ALM Octane server, not just by checking the HTTP connection.

Example: 9300


The name of the Elasticsearch cluster.

Back to top

Site admin credential settings


The email of the site admin user that the installation will create.

The email address can be specified now and created later.

This is the only user available after installation. Other users can be added later.

When using external user authentication, such as LDAP or SSO, this admin should be an existing user in the external system (LDAP or the IdP, respectively).


The site admin's password. The password must be at least 8 characters long, and contain at least one uppercase letter, one lowercase letter, and one number or symbol.

Do not include a pound sign (#) or accented characters (such as, ä, ç, ñ).

When using external user authentication, such as LDAP or SSO, this password should be defined as a "dummy" password. It will not be used once ALM Octane is configured for external authentication.

Back to top

Repository settings


The full path of the repository directory.


Cluster configuration:

  • The directory specified here must be accessible to all cluster nodes.

  • If the repository is not located on a remote, dedicated machine, the repository location cannot be /opt/octane.

Back to top

Additional settings


The fully-qualified domain name and port for the ALM Octane server. This is used for SSO configuration, reverse proxy configuration, SSL offloading configuration, and so on.

This URL is also inserted as a link in emails that ALM Octane sends. Email recipients can click the link to access the relevant entity directly in ALM Octane.

Use this pattern: http://<Server URL>:[Port]

Basic configuration: Usually the URL of the server on which you installed the ALM Octane server.

Cluster configuration: The Virtual IP URL.

Next steps: