ALM 

Octane
Software Version: 16.0.100

Installation Guide for Linux

Go to HELP CENTER ONLINE

http://admhelp.microfocus.com

Document Release Date: October 12, 2021 | Software Release Date: September 2021
Legal Notices
Disclaimer
Certain versions of software and/or documents (“Material”) accessible here may contain branding from Hewlett-Packard Company (now
HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately
owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP
and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.

Warranty
The only warranties for products and services of Micro Focus and its affiliates and licensors (“Micro Focus”) are set forth in the express
warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional
warranty. Micro Focus shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein
is subject to change without notice.

Restricted Rights Legend

Contains Confidential Information. Except as specifically indicated otherwise, a valid license is required for possession, use or copying.
Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for
Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Copyright Notice
© Copyright 2016-2021 Micro Focus or one of its affiliates.

ALM Octane (16.0.100) Page 2 of 80

Installation Guide for Linux
ALM Octane

Contents
ALM Octane 1

Architecture 6
Basic configuration 6
Enterprise configuration 7
Components 8

Installation types 11

Licensing flow 12
Overview 12
Request a trial 12
Using Pro Edition 12
Installing a license 13

Installation flow 14
Prerequisites 14
Deploy 14
Configure 15
Start the server 15
Log in 15
Configure cluster (optional) 15

Cluster installation flow 16

Prerequisites 19
Checklist 19
File system permissions 23
Oracle database permissions 23
SQL database permissions 24
Configure Elasticsearch 27

Installation 30
Deploy ALM Octane 31
Overview 31
Prerequisites 31
Deploy 31
Deploy in cluster environment 33
Configure site settings 34

ALM Octane (16.0.100) Page 3 of 80

Installation Guide for Linux
ALM Octane

Workflow 35
Database server settings 36
Oracle server settings 39
SQL server settings 40
Site actions 40
Space settings 41
Elasticsearch settings 41
Site admin credentials 42
Cluster settings 43
Heap size 43
Proxy settings (optional) 43
Public URL and Server Ports 44
License settings 46
Authentication Type 46
LDAP authentication settings (optional) 46
SSO authentication settings (optional) 50
Configuration tips 54
Start the ALM Octane server 54

Log in to ALM Octane 56

Management 57
Start the ALM Octane server manually 58
Handle database-related issues 58
Change site schema settings and reinitialize 58
Update database password in ALM Octane site schema and configuration files 59
Configure trust on the ALM Octane server 61
Configure trust 61
Advanced ALM Octane server configuration 62
Redirect http to https 62
Configure number of allowed open files (Linux) 63
Configure secure database access 64
Configure SSL offloading 65
Dedicate a cluster node for background jobs – 12.60 CP8 and later 67
Using exception files for manual database changes 68
Overview 68
Define exception files 68
Set up use of the exception file 70

Troubleshooting 72
Checking logs 76
Log files 76

ALM Octane (16.0.100) Page 4 of 80

Installation Guide for Linux
ALM Octane

Monitor the deployment procedure 76

Uninstall 77

Send Us Feedback 79

ALM Octane (16.0.100) Page 5 of 80

Installation Guide for Linux
Architecture

Architecture
You can set up ALM Octane as a single node, or in a cluster configuration. The following diagrams
illustrate the system architecture for both options.
These are followed by descriptions of each of the components.
l "Basic configuration" below
l "Enterprise configuration" on the next page
l "Components" on page 8

Basic configuration
The following diagram illustrates the system architecture of a single-node configuration. Components
in grey are Micro Focus products.

Note: The ALM Octane, database, and Elasticsearch servers should each reside on separate
machines.

ALM Octane (16.0.100) Page 6 of 80

Installation Guide for Linux
Architecture

Enterprise configuration
The following diagram illustrates the system architecture of an enterprise, cluster configuration.
Components in grey are Micro Focus products.

ALM Octane (16.0.100) Page 7 of 80

Installation Guide for Linux
Architecture

Components
Components Description

ALM Octane clients The clients communicate with the ALM Octane server over HTTP/S.

ALM Octane Server application Client requests from ALM Octane are dispatched to the deployed application.
nodes
Note: The ALM Octane, database, and Elasticsearch servers should each
reside on separate machines.

ALM Octane application Cluster configuration: A cluster is a group of application servers that run as a single
additional cluster (sync) nodes system. Each application server in a cluster is referred to as a "node."

l All nodes must have access to the database server on which the site database
schema resides.
l All nodes must have access to the repository.
Generally, the repository will be located on an NFS or SAN server.
If the repository is not located on a remote, dedicated machine, the repository
location cannot be /opt/octane.
l All nodes must have access to each other.

Synchronizer service nodes The service nodes handle synchronization between ALM Octane and ALM or Jira.

Repository / File system Stores all files to be used by all the projects in the system, such as templates and
attachments.

Cluster configuration: When working in a clustered configuration, the repository

must be accessible by all nodes. Also, the repository must be configured to use the same
mount point (path) on all nodes.

Database server A relational database management system, either Oracle RAC or Microsoft SQL Server.

The database server stores the following schemas:

l Site schema. Stores all site-related information, such as database servers, cluster
nodes, the SMTP servers, and configuration.
l Space schema. All space information, such as workspaces, users, and roles.
This server can be shared with other applications with the following constraints:

l The database must be able to sustain the load of all the applications.
l Future versions of ALM Octane might require a database upgrade. This may
necessitate migration of data if other applications sharing the same database will not
support the database version that ALM Octane requires.

Note: The ALM Octane, database, and Elasticsearch servers should each
reside on separate machines.

ALM Octane (16.0.100) Page 8 of 80

Installation Guide for Linux
Architecture

Components Description

Elasticsearch server (or cluster) A Java-based, open-source search engine. This component is used for various aspects of
the application, such as global search and trends.

This server can be shared with other applications with the following constraints:

l The Elasticsearch engine must be able to sustain the load of all the applications.
l Future versions of ALM Octane might require an Elasticsearch upgrade. This may
necessitate migration of data if other applications sharing the same Elasticsearch will
not support the Elasticsearch version that ALM Octane requires.

Note: The ALM Octane, database, and Elasticsearch servers should each
reside on separate machines.

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 Database and Elasticsearch in the ALM Octane Help
Center.

Load balancer Cluster configuration: When working with a load balancer, client requests are
transmitted to the load balancer and distributed according to server availability within
the cluster.

If you are using a load balancer, we recommend you utilize SSL offloading.

High availability load balancers Cluster configuration: These can be "VIPs" (virtual IP addresses) of one physical
load balancer.

DMZ An optional, demilitarized zone.

High availability reverse proxies Cluster configuration: Optional configuration for load balancing using a software
and SSL offloading solution (for example, NGINX).

SMTP A mail server.

Jenkins (with ALM Octane Enterprise configuration: You can integrate ALM Octane with a Jenkins CI server
plugin) using the Application Automation Tools Plugin on your CI server.

TFS, TeamCity, or Bamboo Enterprise configuration: You can integrate ALM Octane with a TFS, TeamCity, or
server (with ALM Octane plugin) Bamboo CI server using the ALM Octane CI Plugin on your CI server.

Slack Integration with Slack, which enables all stakeholders of a backlog item to collaborate
and communicate. You can integrate with Slack by adding it as a collaboration tool
associating it with a workspace.

Micro Focus testing tools: UFT You can integrate ALM Octane with Micro Focus testing tools. For details, see ALM
Developer, UFT One, Octane DevOps integrations in the ALM Octane Help Center.
LoadRunner Professional,
LoadRunner Cloud, LoadRunner
Enterprise

ALM Octane (16.0.100) Page 9 of 80

Installation Guide for Linux
Architecture

See also:
l "Installation types" on the next page
l "Installation flow" on page 14
l "Prerequisites" on page 19
l "Installation" on page 30
l "Deploy ALM Octane" on page 31

ALM Octane (16.0.100) Page 10 of 80

Installation Guide for Linux
Installation types

Installation types
This topic describes the necessary requirements and procedures for the installation of ALM Octane
server, and initial setup steps.

Type Description

Installation Instructions for installing on:

l A single node. For details, see "Installation flow" on page 14.

l A cluster configuration. For details, see "Cluster installation flow" on page 16.

Upgrade For details, see ALM Octane Upgrade Guide for Linux.

See also:
l "Prerequisites" on page 19
l "Deploy ALM Octane" on page 31
l "Configure site settings" on page 34

ALM Octane (16.0.100) Page 11 of 80

Installation Guide for Linux
Licensing flow

Licensing flow
This topic provides a high-level flow for setting up your trial license.
In this topic: 
l "Overview" below
l "Request a trial" below
l "Using Pro Edition" below
l "Installing a license" on the next page

Overview
To get started with ALM Octane, you begin with a 90-day on-premises free trial for 100 users. You
can then install an ALM Octane license file, or allocate licenses from ALM or Quality Center.
Before you begin a trial, you should be familiar with the different editions of ALM Octane. ALM
Octane is available in Enterprise and Pro Editions. For details, see ALM Octane editions in the ALM
Octane Help Center.

Request a trial
Submit a request for a free trial here: https://software.microfocus.com/en-us/products/alm-
octane/free-trial.
When you first start using ALM Octane, you automatically receive a Trial license which gives you a
90-day trial for 100 users. 
By default, your trial is Enterprise Edition, which allows one shared space. If you create a shared space
in an Enterprise Edition trial and then install a license for Pro Edition, the sharing capabilities are no
longer supported.

Using Pro Edition

There is no Pro Edition trial.

To work with Pro Edition:

1. Install ALM Octane Enterprise Edition as your trial type, but do not create shared spaces. If you
create a shared space during an Enterprise Edition trial and then install a Pro Edition license, the
shared space is deactivated.
2. Get an evaluation Pro Edition license from your Sales account manager, or create a support ticket
for a one-time evaluation license.
3. In the ALM Octane Settings area, apply your Pro Edition license. For details about applying
licenses, see "Installing a license" on the next page.

ALM Octane (16.0.100) Page 12 of 80

Installation Guide for Linux
Licensing flow

Installing a license
After you install and configure your trial instance of ALM Octane, you can purchase licenses for
Enterprise or Pro Edition. You then install your license key (.dat file) in ALM Octane.
Alternatively, you can allocate your current licenses from ALM or Quality Center and share them with
ALM Octane. Licenses can be allocated from ALM (ALM.Net) Edition to ALM Octane Enterprise
Edition, or from Quality Center (QC) Enterprise Edition to ALM Octane Pro Edition.

Note: You can share up to 15% of your licenses from ALM or Quality Center, or up to 150
licenses, the lower of the two.

To learn more, see Manage licenses (on-premises) in the ALM Octane Help Center.

Next steps:
l "Installation flow" on the next page

ALM Octane (16.0.100) Page 13 of 80

Installation Guide for Linux
Installation flow

Installation flow
This document describes the overall flow for installing the ALM Octane server on Linux.

In this topic: 
l "Prerequisites " below
l "Deploy " below
l "Configure " on the next page
l "Start the server" on the next page
l "Log in " on the next page
l "Configure cluster (optional) " on the next page

Prerequisites
Verify your system meets hardware and software requirements.
This includes setting up permissions, opening ports, database configuration, and more.
You need three separate server machines. 
l ALM Octane server
l Database server

l Elasticsearch server

For details see "Prerequisites" on page 19, and Best practices in the ALM Octane Help Center.

Note: We recommend you review security considerations in ALM Octane 15.x Secure
Deployment and Configuration Guidelines. This contains instructions on how to set up a
secure configuration for ALM Octane.

Deploy
Deploy ALM Octane on a machine dedicated for the ALM Octane server on Linux.
ALM Octane is deployed using the RPM Package Manager (as an .rpm file).
The deployment path is /opt/octane.

The command to deploy is: rpm -Uvh <name of the RPM file>

ALM Octane (16.0.100) Page 14 of 80

Installation Guide for Linux
Installation flow

For details see "Deploy ALM Octane" on page 31, and Best practices for deploying ALM Octane in the
ALM Octane Help Center.

Configure
This section describes how to configure.

To configure:
1. Edit the octane.conf file with your site's settings for initial configuration.
2. (Optional) Depending on your needs, configure optional configuration files:
l elasticsearch-security.conf to configure secure Elasticsearch.

l proxy.conf to use a proxy server.

l ldap.conf to use LDAP  authentication.

l sso.conf to use SSO authentication.

The path to these files is <Repository folder>/conf.

For details, see "Configure site settings" on page 34.

Start the server

Start the ALM Octane server: 

systemctl start octane

For details, see "Start the ALM Octane server" on page 54.

Log in
Verify that ALM Octane was properly installed. For details, see "Checking logs" on page 76.
Log into ALM Octane. For details, see "Log in to ALM Octane" on page 56.

Configure cluster (optional)

After starting the server on the first machine, configure and initialize each additional cluster node. For
details, see "Cluster installation flow" on the next page.

Next steps:
l "Prerequisites" on page 19
l "Deploy ALM Octane" on page 31
l "Configure site settings" on page 34

ALM Octane (16.0.100) Page 15 of 80

Installation Guide for Linux
Cluster installation flow

Cluster installation flow

This section provides end-to-end instructions for installing an on-premises ALM Octane server in a
cluster configuration on Linux. A cluster is a group of application servers that run as a single system.
Each application server in a cluster is referred to as a "node."

To install ALM Octane in a cluster configuration:

1. For each node in the cluster, check requirements and access:

Check Verify that the all cluster nodes, including the first, meet all requirements
requirements and prerequisites. For details, see "Prerequisites" on page 19.

Check All cluster nodes, including the first, must have access to the database
database server on which the site database schema resides.
server access

Check Create an environment variable OCTANE_REPOSITORY_DIR.

repository The repository directory has to be a shared directory visible to all cluster
access nodes. All nodes must have read and write access to the repository.
Generally, the repository is located on an NFS or SAN server.
The repository must be configured to use the same mount point (path) on
all nodes.
It is important that you enter the repository path using the same path name
on all nodes.

Check access All nodes must have access to each other. Verify ports are open in your
between nodes firewall.
ALM Octane needs to communicate between the nodes in the cluster on
port 5701. Therefore, make sure that your firewall enables communication
between the nodes of the cluster on the specified port..
By default, outbound ports are open. Check inbound ports.
2. Install ALM Octane on the first cluster node, as described in "Installation" on page 30.
a. Verify that you have created an environment variable OCTANE_REPOSITORY_DIR, as
described above. If this variable is missing, the installation will fail.
b. Deploy the ALM Octane installation files on to the first node.
c. Configure initial site settings in octane.conf and optional configuration files.
o Make sure to set the database server name to a value that all cluster nodes can access.

o Enter values described in "Cluster settings" on page 43.

ALM Octane validates these settings when starting. If they are not valid, the ALM Octane
server does not start.

ALM Octane (16.0.100) Page 16 of 80

Installation Guide for Linux
Cluster installation flow

d. On the first node only, start the ALM Octane server by running systemctl start octane. See
"Start the ALM Octane server" on page 54.
3. (Optional) If you want to set up a secure configuration for ALM Octane, follow the instructions in
ALM Octane Secure Deployment and Configuration Guidelines.
4. Log in to the first node in the cluster. For details, see "Log in to ALM Octane" on page 56.
5. Download and deploy the ALM Octane package on each cluster node. For details, see "Deploy
ALM Octane" on page 31 and "Deploy in cluster environment" on page 33.

Caution:
l Do not configure octane.conf or other configuration files on the nodes.
l Do not run connectnode.sh scripts.

6. On each other node, start ALM Octane by running systemctl start octane.
Each node is automatically configured using the configuration files located in the repository, as
defined when you configured the first node.
7. (Optional) If you want to set up a secure configuration for ALM Octane in a cluster configuration,
follow these instructions on each other node: ALM Octane Secure Deployment and Configuration
Guidelines.
8. Log in to make sure ALM Octane is running on each other node. For details, see "Log in to ALM
Octane" on page 56. Use the load balancer URL when you log in.

Tip: For best performance, configure your load balancer with round-robin (stateless)
configuration.

9. If you need to make changes in configuration settings later, edit the <Repository
folder>/conf\octane.conf file, and not octane.conf.new, which is a temporary file that is for internal
use only. After modifying these settings, restart the ALM Octane server on each node to pull the
configuration changes from the repository.

Troubleshooting:
If the cluster was not properly defined, you may receive an error message when you start the
ALM Octane server:
Cluster is unhealthy...
During installation, values in the hazelcast.xml file change according to the octane.conf configuration.
The configuration of the hazelcast.xml file is the one that controls the cluster behavior.
Therefore, make sure that the octane.conf file is configured exactly the same in all nodes, and the
hazelcast.xml file is identical on all nodes. In addition, make sure that the member element of the
hazelcast.xml file contains the same values that were defined in the nodes section of the octane.conf
file.

ALM Octane (16.0.100) Page 17 of 80

Installation Guide for Linux
Cluster installation flow

Next steps:
l "Prerequisites" on the next page
l "Deploy ALM Octane" on page 31
l "Configure site settings" on page 34

ALM Octane (16.0.100) Page 18 of 80

Installation Guide for Linux
Prerequisites

Prerequisites
Verify that your system meets the requirements listed below, and the detailed Support matrix in the
ALM Octane Help Center.
For security requirements, see the ALM Octane Secure Deployment and Configuration Guidelines.
In this topic: 
l "Checklist" below
l "File system permissions" on page 23
l "Oracle database permissions" on page 23
l "SQL database permissions" on page 24
l "Configure Elasticsearch" on page 27

Checklist
Use the following questions to make sure you are ready to install.

Category Tell us... Your answer...

On which machine will you be installing ALM Octane?

Does the machine have a Quad Core AMD64 processor or

equivalent x86-compatible processor? 
How much memory does the machine have? 
You need a minimum of 8 GB.

What Linux operating system is on the machine?

What is the user name and password you will use for the
installation user? 

Does the installation user have sudo permissions?

Are your browsers and screen resolutions compatible with

ALM Octane?

On-premises installation of ALM Octane supports only

English characters for the names of schemas, operating
systems, users, and so on. Did you check?

ALM Octane (16.0.100) Page 19 of 80

Installation Guide for Linux
Prerequisites

Category Tell us... Your answer...

Does your Elasticsearch version match ALM Octane

requirements? See Database and Elasticsearch in the ALM
Octane Help Center.

Do you need to download Elasticsearch? 

If you haven’t installed Elasticsearch, you can download
from here:
https://www.elastic.co/downloads/past-
releases/elasticsearch-7-9-1

On which machine is Elasticsearch installed?

Did you make sure that the port for outbound
communication to Elasticsearch is open? 
By default, outbound ports are open.

Did you make sure that the Elasticsearch ports (such as

9300 and 9200) are accessible directly from the ALM
Octane server, not just by checking the HTTP connection? 

What is the name of the Elasticsearch cluster you have

configured? 

Is the Elasticsearch accessible from the ALM Octane

server? 
Was Elasticsearch configured according to ALM Octane
requirements?
These are described in detail in "Configure Elasticsearch"
on page 27.

ALM Octane (16.0.100) Page 20 of 80

Installation Guide for Linux
Prerequisites

Category Tell us... Your answer...

Does your Oracle version match ALM Octane

requirements? See Support matrix in the ALM Octane
Help Center.
On which machine is the database installed? 

What is the Oracle database port? Default: 1521

You can modify the port in the connection-string field in
octane.conf.

Did you make sure that the port for outbound

communication to Oracle is open? 
By default, outbound ports are open.

What is the URL for Java Database Connectivity (JDBC)

for your database?

What is the database admin's user name and password?

Does the database admin power user have the necessary

permissions? See "Oracle database permissions" on
page 23.

What table space and temporary table space can be used?

Did the DBA add any objects to the schemas? If so, create
an exception file before installing. For details, see "Using
exception files for manual database changes" on page 68.

ALM Octane (16.0.100) Page 21 of 80

Installation Guide for Linux
Prerequisites

Category Tell us... Your answer...

Does your SQL Server version match ALM Octane

requirements? See Support matrix in the ALM Octane
Help Center.

On which machine is the database installed? 

Will you be using the SQL Server database port or
instance name to connect to the database? 
l What is the SQL Server database port? Default: 1433
l What is the SQL Server instance name?

What is the database admin's user name and password?

Does the database administrator (power user) have the

necessary permissions? See "SQL database permissions"
on page 24.

What MSSQL database login user, and password, can be

used for ALM Octane? 

Did the DBA add any objects to the

databases/schemas? If so, create an exception file before
installing. For details, see "Using exception files for manual
database changes" on page 68.

Do you need to install the JDK on the ALM Octane server

and other servers, such as the ElasticSearch server? 

Does your Java version match ALM Octane requirements?

See Support matrix in the ALM Octane Help Center.

Did you make sure that the port for inbound

communication with Jetty is open? 
By default, the port is 8080. For SSL, 8443.
You can define the port during initial installation, in
octane.conf.

Did you make sure that ALM Octane can communicate

between the nodes in the cluster, using inbound and
outbound communication for clusters? 
By default, the port is 5701.
You can define the port during initial installation, in
hazelcast.xml.

ALM Octane (16.0.100) Page 22 of 80

Installation Guide for Linux
Prerequisites

File system permissions

Root or sudo user.
During deployment, ALM Octane creates a user and group named octane for running the octane
service that starts the ALM Octane server. However, if your organization prefers to manage users in a
centralized way, without enabling ad hoc creation of local users, create a user and group for this
purpose, and define the following environment variables: OCTANE_USER and OCTANE_GROUP.
Make sure the user has write permissions to the /opt/octane/log directory.

Oracle database permissions

Permissions depend on how you want to install ALM Octane. Do you want ALM Octane to create
schemas, objects, and tables during installation, or do you want your DBA to prepare them? 
Refer to the relevant section for your installation scenario:
l "Allow ALM Octane to create Oracle schemas automatically" below
l "Create your own Oracle schemas for ALM Octane" on the next page

Allow ALM Octane to create Oracle schemas automatically

To enable ALM Octane to create schemas, tables, and objects automatically during the installation,
provide ALM Octane with an Oracle power user with the following admin privileges:
l CREATE USER
l CREATE SESSION WITH ADMIN OPTION
l CREATE TABLE WITH ADMIN OPTION
l CREATE SEQUENCE WITH ADMIN OPTION
l DROP USER (optional). If not provided, the DBA must take responsibility for cleaning up
unnecessary schemas.

Note: These permissions are for the user you will specify in the admin-user > name setting in
the octane.conf file.

When defining your site action in the octane.conf file, you will specify CREATE_NEW. For
details, see "CREATE_NEW" on page 40.

This power user can also be created temporarily, for installation purposes only. You can remove this
user if: 
l The installation is complete, and login to ALM Octane is successful.
l The ALM Octane site admin intends to create spaces using an existing schema, which can be
selected when creating a space in the ALM Octane Settings area for the site. For details, see
Manage the site (on-premises) in the ALM Octane Help Center.

ALM Octane (16.0.100) Page 23 of 80

Installation Guide for Linux
Prerequisites

Create your own Oracle schemas for ALM Octane

If you do not want ALM Octane to create schemas, tables, and objects automatically, perform the
following:
1. Before installation, create two schemas with the same password.
2. Provide ALM Octane with a regular Oracle user with the following permissions, for both the site
and space schemas:
l CREATE  TABLE
l CREATE SESSION
l CREATE SEQUENCE
l The QUOTA clause on the user's default tablespace should be unlimited.

Note: During installation when you define the octane.conf file, you will enter the name of the
site schema in schemas > site, the space schema in schemas > initial-shared-space, and the
password in schema-password.

When defining your site action in the octane.conf file, you will specify FILL_EXISTING. For
details, see "FILL_EXISTING" on page 41.

SQL database permissions

Permissions depend on how you want to install ALM Octane. Do you want ALM Octane to create
databases during the installation, or do you want your DBA to prepare them? 
Refer to the relevant section for your installation scenario:
l "Allow ALM Octane to create SQL databases automatically" below
l "Create your own SQL databases for ALM Octane" on the next page

Allow ALM Octane to create SQL databases automatically

To enable ALM Octane to create databases automatically during the installation, use the sa user, or
an ALM Octane database admin power user.
Install ALM Octane with a database admin power user if you cannot use the SQL sa user for security
reasons. This user can be a temporary user, for installation purposes only.
Request that the SQL Server database admin create a temporary power user with the following
privileges (roles), which are required to install ALM Octane:
l Database Creators dbcreator role
l Security Administrator securityadmin role

ALM Octane (16.0.100) Page 24 of 80

Installation Guide for Linux
Prerequisites

Note: These permissions are for the user you will specify in the admin-user > name setting in
the octane.conf file.

When defining your site action in the octane.conf file, you will specify CREATE_NEW. For
details, see "CREATE_NEW" on page 40.

It is important that the ALM Octane database administrative user is not the same as the ALM Octane
admin user. The SQL Server database admin could name this power user octane_install_power_user,
for example. For details on removing this temporary power user, see "Handle database-related issues"
on page 58.

Create your own SQL databases for ALM Octane

Before installation, create two databases: one for the site and one for the space.
Associate the login user to ‘octane’ user in both databases.
The default collation is SQL_Latin1_General_CP1_CI_AS (must be case-insensitive).

Example: Create a database and grant user access

CREATE DATABASE <database_name>

CREATE LOGIN <login_name> WITH PASSWORD = 'thepassword', CHECK_
POLICY = OFF
USE <database_name>
CREATE SCHEMA [octane]
GO
CREATE USER [octane] FOR LOGIN <login name> WITH DEFAULT_SCHEMA=
[octane]
GO
ALTER AUTHORIZATION ON Schema::octane TO [octane]
GO
ALTER ROLE [db_ddladmin] ADD MEMBER [octane]
GO

Run the previous commands separately for each database (site schema and space schema).

Note: During installation when you define the octane.conf file, you will enter the name of the
site schema in schemas > site, the space schema in schemas > initial-shared-space, and the
password in schema-password.

ALM Octane (16.0.100) Page 25 of 80

Installation Guide for Linux
Prerequisites

When defining your site action in the octane.conf file, you will specify FILL_EXISTING. For
details, see "FILL_EXISTING" on page 41.

ALM Octane (16.0.100) Page 26 of 80

Installation Guide for Linux
Prerequisites

Configure Elasticsearch
Before installing ALM Octane, there are a number of settings you must configure in Elasticsearch.

Supported Elasticsearch versions

ALM Octane version Supported Elasticsearch versions

15.1.90 7.9.1

15.1.60 6.8.1, 7.6.2, 7.9.1

15.1.40 6.8.1, 7.6.2

15.1.20 6.8.1, 7.6.2

Note: Elasticsearch supports indexes that were created in the current Elasticsearch main
version, or one earlier version. Each time ALM Octane extends support for a new Elasticsearch
main version, the ALM Octane upgrade includes a reindex process for the older indexes.

Elasticsearch configuration
Before installing ALM Octane, configure Elasticsearch settings:
1. In the elasticsearch.yml file, configure the following:
l cluster.name. Assign a unique name which will be used when you configure ALM Octane to

connect to the cluster. Note that even a single-server installation is considered a cluster.
l node.name. If you do not assign the node a name, Elasticsearch generates a random name on

every reboot.
l network.host. The node binds to this hostname or IP address and publishes this host to other

nodes in the cluster. You can enter an IP address, hostname, a special value, or an array of any
combination of these. Defaults to _local_.
l action.auto_create_index. In each of your Elasticsearch cluster nodes, you must have the

following line in the elasticsearch.yml files:

action.auto_create_index: "-mqm_*,*"

Note: If you already have an action.auto_create_index line in the yml file, add the -mqm_
* phrase to the beginning of its specified value. For example, if you have the following
line: 

action.auto_create_index: "-index*,*"

ALM Octane (16.0.100) Page 27 of 80

Installation Guide for Linux
Prerequisites

You would change that to:

action.auto_create_index: "-mqm_*,-index*,*"

2. You can configure Elasticsearch securely using TLS. For details, see
https://softwaresupport.softwaregrp.com/doc/KM03712315.
3. In the jvm.options file, set the following parameters: -Xms<value>g and -Xmx<value>g.
Define value as half of memory available on the machine – 1, but no more than 31GB.

Configuring an Elasticsearch cluster

Elasticsearch can run on a single node but it is designed to run as a cluster. We do not recommend
running a production environment on a single host Elasticsearch instance.
Elasticsearch clusters should have at least 3 nodes, or a larger odd number. For details see
https://www.elastic.co/guide/en/elasticsearch/reference/master/high-availability.html.
To configure an Elasticsearch cluster, modify the following parameters in the elasticsearch.yml:
l cluster.name. This name should be identical on all nodes of the cluster to make sure they join the
same cluster.
l discovery.seed_hosts. To form a cluster with nodes on other hosts, use the static discovery.seed_
hosts setting to provide a list of other nodes in the cluster that are master-eligible, and likely to be
live in order to seed the discovery process.

Note: The cluster nodes should be able to communicate with each other, meaning, the ports
should be open in the firewall.

Restart Elasticsearch
After changing Elasticsearch setting files (for example elasticsearch.yml or jvm.options), you must
restart the Elasticsearch service.
For details on restarting an Elasticsearch cluster, see
https://www.elastic.co/guide/en/elasticsearch/guide/master/_rolling_restarts.html.

Backing up Elasticsearch
For details on backing up Elasticsearch, see
https://www.elastic.co/guide/en/elasticsearch/reference/master/snapshot-restore.html.
We recommend performing ELS snapshot at the same time as database backup and file repository
backup.
ALM Octane does not need to be stopped for this operation.

ALM Octane (16.0.100) Page 28 of 80

Installation Guide for Linux
Prerequisites

You can use curl to issue relevant snapshot commands. Also, consider creating a shell script to back
up Elasticsearch data on a regular basis.

Next steps:
l "Deploy ALM Octane" on page 31

ALM Octane (16.0.100) Page 29 of 80

Installation Guide for Linux
Installation

Installation
This section describes how to install an on-premises ALM Octane server using Linux.
Before installing:
l Verify that your server fulfills all prerequisites. See Support matrix in the ALM Octane Help Center.
l Review the ALM Octane Secure Deployment and Configuration Guidelines.

Cluster configuration: If you intend to install ALM Octane in a cluster configuration, review the end-to-
end process under "Cluster installation flow" on page 16 before starting.

Language support: On-premises installation of ALM Octane supports only English. This means
only English characters can be specified for the names of schemas, operating systems, users,
and so on.

This section includes:

• Deploy ALM Octane 31
• Overview 31
• Prerequisites 31
• Deploy 31
• Deploy in cluster environment 33
• Configure site settings 34
• Workflow 35
• Database server settings 36
• Oracle server settings 39
• SQL server settings 40
• Site actions 40
• Space settings 41
• Elasticsearch settings 41
• Site admin credentials 42
• Cluster settings 43
• Heap size 43
• Proxy settings (optional) 43
• Public URL and Server Ports 44
• License settings 46
• Authentication Type 46
• LDAP authentication settings (optional) 46
• SSO authentication settings (optional) 50
• Configuration tips 54
• Start the ALM Octane server 54

ALM Octane (16.0.100) Page 30 of 80

Installation Guide for Linux
Installation

Deploy ALM Octane

This section describes how to deploy an RPM file for installing an ALM Octane server.
In this topic:
l "Overview" below
l "Prerequisites" below
l "Deploy" below
l "Deploy in cluster environment" on page 33

Overview
Installing the ALM Octane RPM package does the following:
l Creates the correct directory structure.
l Copies all the files to the right locations.
l Creates a user and group for running the ALM Octane service that starts the ALM Octane server.
By default, both the user and group are named octane. However, you can use a pre-defined user
instead by defining the following environment variables: OCTANE_USER and OCTANE_GROUP.
l Installs the octane service so that the operating system recognizes it.

Prerequisites
Before installing:
l Verify that your server fulfills all prerequisites. See Support matrix in the ALM Octane Help Center.
l Review the ALM Octane Secure Deployment and Configuration Guidelines.

Deploy
This section describes how to deploy.

To deploy:
1. Download the ALM Octane RPM package:
https://sld.microfocus.com/mysoftware/download/downloadCenter

Tip: To verify the digital signature of the RPM package, see "Installation Security" in the
ALM Octane Secure Deployment and Configuration Guidelines.

ALM Octane (16.0.100) Page 31 of 80

Installation Guide for Linux
Installation

2. Set up repository access.

If the repository is located on a remote, dedicated machine, the ALM Octane server user account
must have network access to the remote repository.
The repository directory has to be shared, so the user performing installation (generally, the
octane user) can write to the repository.
l Single-node configuration
Create an environment variable OCTANE_REPOSITORY_DIR on the ALM Octane server with
the repository location.
For example: export OCTANE_REPOSITORY_DIR=/opt/octane/repo
l Cluster configuration
o The repository directory has to be a shared directory visible to all cluster nodes.
o On each cluster node create a mount directory that points to the repository directory, for
example: /mnt/octane/repo. It is important that you enter the repository path using the
same path name on all nodes.
o On each cluster node create an environment variable OCTANE_REPOSITORY_DIR with the
repository location.
For example: export OCTANE_REPOSITORY_DIR=/mnt/octane/repo
o The repository location cannot be /opt/octane on an ALM Octane node.
3. Install the ALM Octane RPM package.
l To install the ALM Octane RPM package in the default installation directory /opt/octane, run:

rpm -ivh <name of the RPM file>

l Alternatively, install the ALM Octane RPM package to a different directory:

rpm -ivh --prefix <base path> <name of the RPM file>

Note: If you install RPM to a different directory, make sure to replace "/opt/octane" with
the relevant path when following these instructions.

4. Verify the required file permissions.

Default directory Description Permissions

/opt/octane ALM Octane installation directory and all its sub-directories and files. Full read, write,
These files are used for configuring the server. and execute

/opt/octane/log Log file directory. Full read, write,

and execute

5. If planning to install ALM Octane on additional cluster nodes, perform the steps described under
"Deploy in cluster environment" on the next page.

ALM Octane (16.0.100) Page 32 of 80

Installation Guide for Linux
Installation

Deploy in cluster environment

This section describes how to deploy in cluster environment.

To deploy in cluster environment:

1. Configure the IP addresses (or fully qualified domain names) of the cluster nodes. Configure the
node IP addresses or fully qualified domain names in the octane.conf file. For details, see
"Configure site settings" on the next page.
2. Verify ports are open in your firewall. When deploying ALM Octane over a cluster, ALM Octane
needs to communicate between the nodes in the cluster located on port 5701. Therefore, make
sure that your firewall enables communication between the nodes of the cluster on the specified
port.

ALM Octane (16.0.100) Page 33 of 80

Installation Guide for Linux
Installation

Configure site settings

Configure site settings using the ALM Octane configuration files:
l The octane.conf settings are mandatory for all environments.
l In addition, there are other settings that are required in complex ALM Octane environments. These
include secure Elasticsearch, proxy settings, and LDAP or SSO authentication, as described below.
These settings are configured during installation, and can also be changed any time, whenever
necessary.
In this topic: 
l "Workflow" on the next page
l "Database server settings" on page 36
l "Oracle server settings" on page 39
l "SQL server settings" on page 40
l "Site actions " on page 40
l "Space settings" on page 41
l "Elasticsearch settings" on page 41
l "Site admin credentials" on page 42
l "Cluster settings" on page 43
l "Heap size" on page 43
l "Proxy settings (optional)" on page 43
l "Public URL and Server Ports" on page 44
l "License settings" on page 46
l "Authentication Type" on page 46

ALM Octane (16.0.100) Page 34 of 80

Installation Guide for Linux
Installation

Workflow
1. Configure basic settings by editing the octane.conf file. In addition, depending on your
environment, configure the optional files described in the following sections.
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>

Example: chown octane:octane octane.conf

2. If you are installing ALM Octane, after editing your configuration files proceed with "Start the
ALM Octane server" on page 54.
3. If you need to make changes in configuration files later, make sure you edit the <Repository
folder>\conf\octane.conf file, and not octane.conf.new, which is a temporary file that is for internal
use only.
After modifying these settings, restart the ALM Octane server on each node to pull the
configuration changes from the repository. For details, see Restart the server in the ALM Octane
Help Center.
For example, you might initially install ALM Octane to use native user management, and at a later
time, decide to implement LDAP authentication for user management instead.

Tip: We recommend that you save a local copy of the octane.conf file before making changes
to it. Also, for security purposes, octane.conf should be stored in a secure, off-site location.

ALM Octane (16.0.100) Page 35 of 80

Installation Guide for Linux
Installation

Database server settings

Setting Description

db-type Enter ORACLE or MSSQL.

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

Oracle connection-string
The instructions below demonstrate how to set up the string with non-secured database
access. To configure secure access to the database, see "Using SSL/SSO in Oracle
(optional)" on the next page.

Syntax using service names:

jdbc:oracle:thin:@//DB_SERVER_NAME:DB_SERVER_PORT/DB_SERVICE_
NAME
Examples:

l jdbc:oracle:thin:@//dbserver1.net:1521/orcl
l jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=
(PROTOCOL=TCP)(HOST=dbserver1.net)(PORT=1521)))(CONNECT_
DATA=(SERVICE_NAME=orcl)))

Note:
For the syntax using TNS, see "Using TNS alias names in Oracle" on page 38.

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

SQL connection-string
l Syntax using port:

jdbc:sqlserver://DB_SERVER_NAME:DB_SERVER_PORT
Example:

jdbc:sqlserver://dbserver1:1433
l Syntax using instance:

jdbc:sqlserver://DB_SERVER_NAME;instanceName=INSTANCE_NAME
Example:

jdbc:sqlserver://dbserver1;instanceName=my_instance

ALM Octane (16.0.100) Page 36 of 80

Installation Guide for Linux
Installation

Setting Description

admin-user > name ALM Octane uses the admin-user both to create objects during installation and also to
check that the database server is accessible.

l For Oracle, enter the name of the database admin user.

l For SQL Server, enter the sa user, or an SQL Server power user with the correct
permissions.
For details about admin-user permissions, see "Prerequisites" on page 19.

admin-user > password The password of the database admin user.

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

schemas >  The name of the site schema that will be created by the admin-user during the
site installation, or supplied by the organization's DBA. Enter the supplied name.

schemas >  This parameter is relevant only for the FILL_EXISTING site action.
initial-shared-space
If you are using FILL_EXISTING, set the initial-shared-space to the name of the
schema that is designated for the space.

Using SSL/SSO in Oracle (optional)

You can configure a secure connection from the ALM Octane server to the database server using
SSL or SSO.
1. Define the Oracle native JDBC as the default Java driver:
a. Open the file <Java Home>\jre\lib\security\java.security.
b. Search for jdk.tls.disabledAlgorithms and comment out the line.
c. Search for security.provider, and locate the line com.sun.net.ssl.internal.ssl.Provider.
d. Add the line oracle.security.pki.OraclePKIProvider above the previous line, and change the
numbering of the providers.

Example:
# jdk.tls.disabledAlgorithms=SSLv3, RC4, DES, MD5withRSA, DH
keySize < 1024, \
EC keySize < 224, 3DES_EDE_CBC, anon, NULL

security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=sun.security.ec.SunEC
security.provider.4=oracle.security.pki.OraclePKIProvider
security.provider.5=com.sun.net.ssl.internal.ssl.Provider

ALM Octane (16.0.100) Page 37 of 80

Installation Guide for Linux
Installation

security.provider.6=com.sun.crypto.provider.SunJCE

2. Place the Oracle client wallet file in a location on the server into a directory accessible to all, such
as /opt/octane/conf/ewallet.p12. ALM Octane will need Read permissions to this file.
3. Copy the following to octane.conf, after the connection-string parameter:

connection-properties : [
{
"key" : "javax.net.ssl.trustStore",
"value" : "/opt/octane/conf/ewallet.p12"
}
,
{
"key" : "javax.net.ssl.trustStoreType",
"value" : "PKCS12"
}
,
{
"key" : "javax.net.ssl.trustStorePassword",
"value" : "********"
}
]

4. Replace the values above as follows:

l trustStore. Enter the location of the ewallet.p12 or cwallet.sso certificate.

l trustStoreType. PKCS12 or SSO.

l trustStorePassword. (For SSL  only) Enter the password to use to open the keystore file.

Using TNS alias names in Oracle

If you want to use TNS, perform the following:
1. Create a tnsnames.ora file with your Oracle connection description. ALM Octane will need Read
permissions to the file.
Example:

ALM Octane (16.0.100) Page 38 of 80

Installation Guide for Linux
Installation

orcl =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = myhost.net)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = orcl)
)
)

2. Define the connection-string parameter as follows:

jdbc:oracle:thin:@<tns_server_name>
For example:
jdbc:oracle:thin:@orcl
3. Copy the following to octane.conf, after the connection-string parameter:

connection-properties : [
{
"key" : "oracle.net.tns_admin",
"value" : "/opt/octane/conf/tnsnames.ora"
}
]

4. In connection-properties, define the value with the location of your tnsnames.ora file.

Oracle server settings

Oracle
settings Description

schema- The password of the site schema.

password
When 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 schema-
password.
table-space The tablespace in the Oracle database where the site schema segment will be created. Case-sensitive.

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

table-space

ALM Octane (16.0.100) Page 39 of 80

Installation Guide for Linux
Installation

Oracle
settings Description

user- Defines whether the standard Oracle binary sort (NLS_SORT="BINARY_CI") should be overridden for
default- non-Latin language support.
sort
Valid values: yes, no, or blank

Default: blank (yes) 

SQL server settings

SQL Server
settings Description

app-user > name 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.

Note: This should be different from the admin-user > name. However if you are using
FILL_EXISTING, this must be the same as the admin-user name.

app-user The password for the app-user.

> password
If you are using FILL_EXISTING, this must be the same as the admin-user password.

authentication- Enter the authentication method used: Windows or DB (SQL Server Authentication).
method

Site actions
The site-action setting determines how the installation should handle databases.

CREATE_ Use this site action for new installations.

NEW
l Creates a new site schema, creates a new space schema, and configures the current node.
l Only an admin-user with create schema permissions can create a new schema.
l The CREATE_NEW site action fails when the schema already exists.

ALM Octane (16.0.100) Page 40 of 80

Installation Guide for Linux
Installation

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

In this case, the organization's DBA must create a new site and space schema/database and users before
installation. 

See the following for details:

l "Create your own Oracle schemas for ALM Octane" on page 24

l "Create your own SQL databases for ALM Octane" on page 25
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" on page 68.

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

l isolated. Workspaces associated with the initial space will not share entities or customization
settings.
l shared. Workspaces associated with the initial space can share entities or customization settings.

Elasticsearch settings
A working Elasticsearch server is a requirement for working with ALM Octane. For details on
Elasticsearch prerequisites, see "Configure Elasticsearch" on page 27.

hosts The name of the host running Elasticsearch.

If running an Elasticsearch cluster, all node host names should be separated by commas, as follows:

["host1","host2","host3"]
http-port Port configured in Elasticsearch for incoming HTTP requests. Default in Elasticsearch is 9200.

cluster-name The name of the Elasticsearch cluster.

Elasticsearch security (optional)

You can connect ALM Octane with Elasticsearch securely using TLS. For details, see Setting up TLS
for ALM Octane and Elasticsearch.

ALM Octane (16.0.100) Page 41 of 80

Installation Guide for Linux
Installation

1. Make sure you have the following line in your octane.conf file: 

include "elasticsearch-security.conf"
2. Set up the elasticsearch-security.conf file as follows:
user l name: The username to use when authenticating against Elasticsearch.
l password: The password of the Elasticsearch user.
key-store l file: The name of the PKCS12 keystore file. The file should be placed in the configuration folder.
l password (optional, encrypted): The password to use to open the keystore file if the store is
password protected.
l keystore type: Certificate files should be in the PKCS12 format and should be put in the
configuration folder.

trust-store l file: The name of the PKCS12 truststore file. The file should be placed in the configuration folder.
l password (optional, encrypted): The password to use to open the truststore file if the store is
password protected.
l keystore type: Certificate files should be in the PKCS12 format and should be put in the
configuration folder.

verification- Determine the level used when verifying the certificate. We recommend using the default setting.
mode
l none: No certificate verification checks are made. This means that any certificate will be accessed and
should only be sued to debug issues.
l certificate: Only checks that the certificate is signed by a trusted CA. Should be used when hosts are
dynamic.
l full: In addition to certificate, also checks that the host name reported by the certificate matches the
host the request is coming from. Should be used whenever possible and is the default.

Site admin credentials

site- The email of the site admin user that the installation will create.
administrator
The email address can be specified now and created later.
> name
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).

site- The site admin's password. The password must be at least 8 characters long, and contain at least one
administrator uppercase letter, one lowercase letter, and one number or symbol.
> password
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.

ALM Octane (16.0.100) Page 42 of 80

Installation Guide for Linux
Installation

Cluster settings
Here are some settings you must use to establish if you are installing a standalone ALM Octane
server or a cluster configuration. For details on cluster configurations, see "Cluster installation flow" on
page 16.

single- Whether your server is standalone or in a cluster configuration.

server
Mandatory.

l For a standalone server, set this value to true and do not enter any host names using the nodes
setting.
l For a cluster configuration, set this value to false. You must enter node host names in the nodes
setting.

nodes Configure the IP addresses or fully qualified domain names for each cluster node.

Enter a comma-separated list of node host names or IPs, in the cluster, for example:

["host1","host2","host3"]

Make sure single-server is set to false.

Heap size
heap- Before starting the ALM Octane server the first time, change the heap memory values on all active cluster
size nodes.

For example, you may need to increase the heap size if there is an increase in the number of active workspaces
in ALM Octane, or an increase in the number of concurrent user sessions.

Set heap-size to half of available server memory on a dedicated server, regardless of load.

Heap size should not exceed 31 GB.

Values should be specified in MB (for example, 4096 for 4 GB).

Default: 4096

Proxy settings (optional)

If ALM Octane is behind a firewall, and needs to access an outside server, you may need to configure
ALM Octane to use a proxy server.
1. Make sure you have the following line in your octane.conf file: 

include "proxy.conf"
2. Set up the proxy.conf file as follows:

ALM Octane (16.0.100) Page 43 of 80

Installation Guide for Linux
Installation

http l host: The proxy host (if using HTTP).

l port: The proxy port (if using HTTP).
https l host: The proxy host (if using HTTPS).
l port: The proxy port (if using HTTPS).
user l name: User name accessing the proxy.
l password: Password for proxy user.
non-proxy hosts

Public URL and Server Ports

Tip: We recommend that you always run ALM Octane in production with a secure connection.
See "Configuration tips" on page 54.

Enter the following in the server-binding section:

app-url 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.

Note: If you have a URL with a top-level domain (TLD) that is not listed in
https://www.iana.org/domains/root/db (for example http://a.b.corp, where corp is not listed), see
"Troubleshooting non-standard top-level-domains" on the next page.

ALM Octane (16.0.100) Page 44 of 80

Installation Guide for Linux
Installation

http-port The value of a Jetty port for HTTP, or a Jetty secure port for HTTPS.

https-port After you install ALM Octane, you may need to change the ALM Octane server port number.

Because the installation uses a non-root user, common ports (below 1024) cannot be used with ALM
Octane.

By default, the installation uses port 8080 for HTTP or port 8443 for HTTPS (SSL).

httpPort: 8080

httpsPort: 8443
Leaving any of these ports empty disables the access using the specified http schema server.

It is possible that the default application server port is used by another application that is running on the
same machine. In this case, you can either locate the application that is using the port and stop it, or you
can change the ALM Octane server port.

allow-http- By default, if you define your app-url as using HTTPS protocol, users cannot access ALM Octane via
requests-if- HTTP.
ssl-enabled
If you need to enable HTTP access (for example for internal tools inside your network), you can set this
parameter to true. This will allow HTTP access to ALM Octane even though your protocol is set to
HTTPS.

java-default- By default, the Java trust store password is changeit. If you changed this password, enter the Java trust
trust-store- store password here. When ALM Octane starts, it encrypts this password.
password
This is useful when ALM Octane server trust is configured.

The key-store fields are mandatory for HTTPS:

file Enter the absolute path to the keystore file, or the file name if the keystore is in ALM Octane's
configuration folder.

password Password used to protect the keystore file. When ALM Octane starts, it encrypts this password.

keystore Enter JKS or PKCS12.

type
Note: This field must be populated (default: JKS).

Troubleshooting non-standard top-level-domains

ALM Octane validates that the top-level domain (TLD) entered in the app-url parameter is listed in
https://www.iana.org/domains/root/db. If you enter a URL with a TLD that is not listed there (for
example http://a.b.corp, where corp is not listed), server startup will fail. In this case, perform the
following steps:
1. Enter the default app-url: https://localhost:8080.
2. Start ALM Octane.

ALM Octane (16.0.100) Page 45 of 80

Installation Guide for Linux
Installation

3. In the configuration parameters, define the parameter ADDITIONAL_ALLOWED_TLD with the

value of your TLD (for example corp).
4. Restart ALM Octane.
5. In the configuration parameters, define the parameter SERVER_BASE_URL with the correct value
of your server URL (for example http://a.b.corp).

License settings
trial-edition The trial edition is always enterprise. For details, see the information about ALM Octane editions
in the ALM Octane Help Center.

license-mode l If you are using a standalone ALM Octane license, enter standalone. You can then skip the
remaining fields in the License section. Default.
l If you are allocating licenses from ALM to ALM Octane, enter ALM_SHARING. You then need
to fill in the following fields as described below.
For details, see Manage licenses (on-premises) in the ALM Octane Help Center.

The following fields are mandatory for ALM_SHARING mode:

url Enter the full path that you use to access ALM. Typically, this includes the suffix qcbin.

integration-user > Enter the user name for accessing ALM. This user was defined in ALM for integration purposes.
name

integration-user > Enter the password for the integration-user.

password
This password is automatically encrypted after you restart the ALM Octane server.

Authentication Type
Specify whether the ALM Octane installation should use native user management (default), LDAP, or
SSO authentication for user management.

authentication- Values are: 

type
internal. Use internal, native ALM Octane user management. Default.
ldap. Use LDAP authentication. Define LDAP settings as described in "LDAP authentication settings
(optional)" below.

sso. Use SSO authentication. Define SSO settings as described in "SSO authentication settings
(optional) " on page 50.

LDAP authentication settings (optional)

If you plan on authenticating users using LDAP, we recommend you configure LDAP settings using
the ALM Octane Settings UI after installation, rather than in the ldap.conf file. When you configure

ALM Octane (16.0.100) Page 46 of 80

Installation Guide for Linux
Installation

LDAP in the Settings UI, your settings are automatically validated and updated in the ldap.conf file.
For details, see Configure LDAP in the ALM Octane Help Center.
If you prefer to work directly in the configuration files rather than in the Settings UI:
1. Make sure you have the following line in your octane.conf file: 

include "ldap.conf"
2. In the ldap.conf file, configure the LDAP settings as described below.
3. Later, after ALM Octane installation, import users from LDAP into ALM Octane.

Tip: LDAP settings are validated when you start ALM Octane. If there are errors in your LDAP
configuration which prevent the ALM Octane server from starting, have a site admin check the
wrapper, site, and app logs.

General LDAP settings
connection- Connection timeout in seconds. Optional.
timeout
Default: 30 seconds

admin-dn The user that will log on to ALM Octane after initially setting up LDAP authentication. Its purpose is to
make sure that one workable user exists to start configuring LDAP user authentication.

When the ALM Octane server starts, it checks LDAP configuration settings, verifies that this user exists,
and validates this user against the LDAP data. If this attribute is not defined correctly, the server will not
start. Correct the user details and restart the server.

This user can be same user as the user entered in the octane.conf file, or a different user. After entering
the value for this user, and then restarting the ALM Octane server, the admin user entered in the
octane.conf file is overwritten. This becomes the ALM Octane site admin user that can be used to log
into ALM Octane the first time.

Note: If the admin-dn is changed and the server is restarted, both the original admin-dn and the new
admin-dn exist as site admins. Modifying the admin-dn does not remove the original one.

LDAP server settings
Enter the following settings for each LDAP server separately.

Caution: Back up all passwords set below because they are encrypted after the ALM Octane
server is initialized.

servers Header row to delineate that the information below is for each LDAP server. Do not enter a value.

host The LDAP server host name or IP address. Mandatory.

ALM Octane (16.0.100) Page 47 of 80

Installation Guide for Linux
Installation

port LDAP server connection port. Mandatory.

ssl Whether the LDAP server uses SSL. Mandatory.

Enter Y or N.

If Y, establish trust to the certificate authority that issued the LDAP server certificate. For details, see
"Configure trust on the server" in the ALM Octane Installation Guide.

base-directories Root of the LDAP path to use to search for users when including new LDAP users in ALM Octane
spaces. This can be a list of common names and domain components (cns and dns), a list of
organizational units (ou), and so on.

Optional. Default: Blank.

Example:

"base-directories" : [
"dc=maxcrc,dc=com",
"ou=Administrative,dc=maxcrc,dc=com"
],
base-filters Filters to use to refine the search for users when including new LDAP users in ALM Octane spaces.
This is generally a semi-colon delimited list of LDAP objectClasses.

Optional. Default: (objectClass=*)

description Description of the LDAP server. Optional.

authentication: Header row to delineate that the information below is for authentication. Do not enter a value.

method The LDAP authentication method supported by the LDAP server. Authentication method used by the
LDAP server. The following methods are supported: 

l anonymous. In this case, skip the next two parameters, name and password.
l simple. name and password are mandatory.
user name Only required if you set the authentication parameter to simple.

User name for accessing the LDAP server. This user must have at least read permissions for the LDAP
server.

password Only required if you set the authentication parameter to simple.

Password for accessing the LDAP server.

This password will be encrypted.

LDAP server mapping settings

Enter the following mapping settings for each LDAP server separately.
Values used in the mapping section are case-sensitive.

ALM Octane (16.0.100) Page 48 of 80

Installation Guide for Linux
Installation

ALM
Octane Sample
attribute in LDAP attribute that
ldap.conf can be used Values and descriptions

mapping Header row to delineate that the information below is for mapping of
LDAP attributes. Do not enter a value.

dn distinguishedName The LDAP distinguished name attribute. Unique. Mandatory.

(for Active This attribute is typically in a format that contains the common name and
Directory) organization details, such as:

cn=<common_name>,ou=<organizational_unit>,dc=<part_of_domain>

The dn is a unique string that typically contains other LDAP attributes, such as cn,
ou, and dc.

entryDN Example

(for other LDAP 1. If in LDAP, the entryDN attribute value is: cn=<common_

systems) name>,ou=<organizational_unit>,dc=<part_of_domain>
2. In the ldap.conf, the dn value would be mapped to: entryDN
3. When exporting users from LDAP, the dn string representation of each
LDAP user would be the common name, followed by the organizational unit,
followed by a part of the domain, such as: cn=Joe_Smith@nga,ou=my_
org,dc=com
uid objectGUID The LDAP attribute that should be used as the immutable, globally-unique
identifier. Mandatory.
(for Active
Directory) In this documentation, we also refer to this as the UUID (universally unique ID).

l For Active Directory: To work with ALM Octane with Active Directory, we use
objectGUID.
l For other LDAP systems: To work with ALM Octane, we generally use
entryUUID entryUUID for OpenLDAP. However, depending on your LDAP, this attribute
might be different, such as GUID or orclguid.
(for other LDAP
systems) This is an attribute by which ALM Octane identifies each user internally for
synchronization between ALM Octane and LDAP, including when importing users
into ALM Octane.

You can configure other values, such as GUID or orclguid, or any other unique value.

first-name givenName LDAP attribute for first name, such as givenName. Mandatory.

last-name sn LDAP attribute for last name, such as sn. Mandatory.

full-name cn LDAP attribute for full name, such as cn. Optional.

ALM Octane (16.0.100) Page 49 of 80

Installation Guide for Linux
Installation

ALM
Octane Sample
attribute in LDAP attribute that
ldap.conf can be used Values and descriptions

logon- mail This is the unique identifier between all ALM Octane users, and this attribute is
name used to log onto ALM Octane.

In some cases, ALM Octane may use this attribute to identify each user internally
for synchronization between ALM Octane and LDAP, including when importing
users into ALM Octane.

mail is usually unique for each user, so mail is an appropriate LDAP attribute to

use to map to logon-name. Mandatory.

You can change the logon-name attribute mapping at any time, but make sure
the logon-name is unique across all ALM Octane users.

email mail The LDAP attribute for email address, such as mail. Mandatory.

phone1 telephoneNumber The LDAP attribute for the primary phone number, such as telephoneNumber.
Optional.

SSO authentication settings (optional) 

Use these settings to set up SSO authentication for connecting to ALM Octane with an external IDP.
1. Make sure you have the following line in your octane.conf file: 

include "sso.conf"
2. Set up the sso.conf file as follows:
Setting Description and usage

Key-pair settings:

alias Unique identifier for the SSO public/private key pair used by the ALM Octane service provider for
signing and encrypting authentication information.

Mandatory.

Example: sso-osp-keypair

password Password for protecting and encrypting the key pair defined with key-pair alias.

When ALM Octane starts, it encrypts this password.

Mandatory.

Example: my-secret

Key-store settings:

ALM Octane (16.0.100) Page 50 of 80

Installation Guide for Linux
Installation

Setting Description and usage

file The absolute path to the keystore file identified with key-pair alias.

The path should be under ALM Octane's configuration folder to avoid permission issues.

Mandatory.

password Password used to protect the keystore file defined with keystore file.

When ALM Octane starts, it encrypts this password.

Mandatory.

Example: my-password

keystore-type This defines the keystore type. The default format for this file is PKCS12. You can change the format
to Java KeyStore (JKS) by specifying this type here.

OAuth settings:

client-id Client ID used for internal OAuth2 configuration and by which the integration that will be accessing
ALM Octane will identify itself.

Regular expressions are not supported (meaning, no asterisk wildcards).

Must be the same on all ALM Octane cluster nodes.

Mandatory.

Example: my-client-ID

client-secret The OAuth client secret for the integration's client ID defined with oauth client-id.

Can be any value. We recommend that the secret be complex and hard to guess.

Must be the same on all ALM Octane cluster nodes.

When ALM Octane starts, it encrypts this password.

Mandatory.

Example: secret

ALM Octane (16.0.100) Page 51 of 80

Installation Guide for Linux
Installation

Setting Description and usage

authentication- The SSO authentication timeout in seconds.

timeout
Optional.

Default: 10800 seconds (3 hours).

Other timeout settings when working with SSO

The following configuration parameters can be used to set other timeouts when working with SSO.
These parameters are defined in the Settings area in ALM Octane, not in the sso.conf file. They do
not have any effect on the SSO authentication timeout.

l MINUTES_UNTIL_IDLE_SESSION_TIMEOUT. Defines license consumption in minutes.

l MINUTES_UNTIL_GLOBAL_SESSION_TIMEOUT. Defines API key authorization timeout in
minutes.
For details on setting these configuration parameters, see Configuration parameters in the ALM
Octane Help Center.

SAML settings:

IdP section

metadata-url The IdP's URI for publishing IdP metadata. Part of the pairing process. If this is set, there is no need to
set metadata. Using this option, the URL must be available and respond with a valid XML or ALM
Octane will not start.

Any valid URL is accepted.

You can define the SAML metadata descriptor resource with either this setting, or the saml idp
metadata setting.

Mandatory, if saml idp metadata is not defined.

Example: http://my-server.company-infra.net:8080/auth/realms/Dev/protocol/saml/descriptor

metadata Base 64 encoded XML of the SAML metadata descriptor from the IdP. This should be used if the
IdP metadata URL cannot be accessed from the ALM Octane server. If metadata is provided using this
setting, the URL defined in saml idp metadata-url is ignored.

You can define the SAML metadata descriptor resource with either this setting, or the saml idp
metadata-url setting.
Mandatory, if saml idp metadata-url is not defined.

Mapping section

ALM Octane (16.0.100) Page 52 of 80

Installation Guide for Linux
Installation

Setting Description and usage

user-name The parameter in the SAML response which maps to the user name.

Valid values are: 

l '{$id}'. Mapping is to the NameID in the SAML response's subject. Default.

l userName. Mapping is to the username in the SAML attribute statement.
Changing the default to a property name, such as userName, in the SAML response, does not require
quotes.

uuid The attribute in the SAML response's attribute statement that maps to the user's UUID.

Optional.

Default: uuid

mail The attribute in the SAML response's attribute statement that maps to the user's email address.

Optional.

Default: mail

first-name The attribute in the SAML response's attribute statement that maps to the user's first name.

Optional.

Default: firstName

last-name The attribute in the SAML response's attribute statement that maps to the user's last name.

Optional.

Default: lastName

full-name The attribute in the SAML response's attribute statement that maps to the user's full name.

Optional.

Default: fullName

Logging settings

directory The directory in which to create the SSO log files.

Optional. If the value is empty then the default logging directory will be used.

Default: <log folder>/sso

ALM Octane (16.0.100) Page 53 of 80

Installation Guide for Linux
Installation

Setting Description and usage

logging-level Logging level. Possible values are: 

l SEVERE
l INFO
l WARNING
l ALL
Optional.

Default: WARNING

Configuration tips
l When you install a single node configuration for the Jetty server, you need to use the full address
to access it. Meaning, if the Jetty server was installed on a machine named
myserver.mydomain.com, then you access it via: http[s]://myserver.mydomain.com:<port> and not
via http[s]://myserver:<port> if there are client-side DNS shortcuts installed.
l When you install a cluster Jetty server environment, the load balancer and all Jetty nodes should all
be accessible from one another. The same rules for accessing the server via the load balancer from
the client side apply. Meaning, the full address of the load balancer should be used for access.

Start the ALM Octane server

When you finish defining your configuration settings as described in "Configure site settings" on
page 34, start ALM Octane.

To start the ALM Octane server:

1. Log in as either the root or sudo user.
2. Run the octane service to start the ALM Octane server. Run:

systemctl start octane

The installation is complete only when the "Server is ready!" message is shown in the
/opt/octane/log/wrapper.log file. If you do not see the "Server is ready!" message, correct the errors
shown in the log.

Tip: When you first start using ALM Octane, you automatically receive a Trial license which
gives you a 90-day trial for 100 users. For details, see Trial license in the ALM Octane Help
Center.

ALM Octane (16.0.100) Page 54 of 80

Installation Guide for Linux
Installation

Next steps:
l "Log in to ALM Octane" on the next page
l Cluster configuration: If you successfully installed and logged into ALM Octane on the first cluster
node, continue installing on additional cluster nodes.
l If connecting to a database server or an LDAP server over a secure channel (SSL/TLS), or for
license sharing with ALM, configure trust. For details, see "Configure trust on the ALM Octane
server" on page 61.

ALM Octane (16.0.100) Page 55 of 80

Installation Guide for Linux
Log in to ALM Octane

Log in to ALM Octane

This section describes how to log into ALM Octane.

Tip: When you first start using ALM Octane, you automatically receive a Trial license which
gives you a 90-day trial for 100 users. For details, see Trial license in the ALM Octane Help
Center.

To log into ALM Octane:

1. In a browser, navigate to <serverURL>:<serverport>/ui.
Make sure to specify a fully-qualified domain name for the server. The name must include at least
one period. Do not specify an IP address.
Cluster configuration: Use the load balancer URL.
2. Log in with the site admin user name and password you provided in the octane.conf file using
settings site-administrator name and password.

Note: Errors might be listed even if the ALM Octane server initializes and starts. If you
encounter problems initializing ALM Octane, check for errors in the log files. For details, see
"Troubleshooting" on page 72.

Next steps:
l Cluster configuration: If you successfully installed and logged into ALM Octane on the first cluster
node, continue installing on additional cluster nodes. See "Cluster installation flow" on page 16.
l Set configuration parameters, such as FORGET_USER_ON_DELETE and SMTP_NOTIFICATION_
SENDER_EMAIL. See Configuration parameters in the ALM Octane Help Center.
l Create spaces. See Create spaces for a site in the ALM Octane Help Center.
l Once you have logged on as the space admin, you can create other users and workspaces. See
Ways to add users and Create workspaces in the ALM Octane Help Center.

ALM Octane (16.0.100) Page 56 of 80

Installation Guide for Linux
Management

Management
Here are some management tasks you may have to perform during or after installation.

Note: In addition to these management tasks, you can also set configuration parameters to
define how your site operates. Configuration parameters for the site are set using Settings.
See Configuration parameters in the ALM Octane Help Center.

This section includes:

• Start the ALM Octane server manually 58
• Handle database-related issues 58
• Change site schema settings and reinitialize 58
• Update database password in ALM Octane site schema and configuration files 59
• Configure trust on the ALM Octane server 61
• Configure trust 61
• Advanced ALM Octane server configuration 62
• Redirect http to https 62
• Configure number of allowed open files (Linux) 63
• Configure secure database access 64
• Configure SSL offloading 65
• Dedicate a cluster node for background jobs – 12.60 CP8 and later 67
• Using exception files for manual database changes 68
• Overview 68
• Define exception files 68
• Set up use of the exception file 70

ALM Octane (16.0.100) Page 57 of 80

Installation Guide for Linux
Management

Start the ALM Octane server manually

If you need to start the ALM Octane server manually, perform the following.

To start (or restart) the ALM Octane server:

l Log in as the root user and run the octane service:

systemctl start octane

The service runs in the background.

To follow the server's boot process:

l Run: 

tail -f /opt/octane/log/wrapper.log

To start (or restart) ALM Octane in a cluster configuration:

All nodes must be restarted.

Handle database-related issues

This topic provides instructions for handling database-related management tasks.
In this topic: 
l "Change site schema settings and reinitialize" below
l "Update database password in ALM Octane site schema and configuration files" on the next page

Change site schema settings and reinitialize

If you need to make changes to the site schema settings, make the changes in the octane.conf file.

To change site schema settings and reinitialize:

1. Obtain the names of the indexes related to your instance of ALM Octane in the sharedspace_
logical_name.txt in the /opt/octane/server/conf/ directory.
2. Delete the database site schema.
3. Delete the repository.
4. Delete the mqm_<sp_logical_name> index from Elasticsearch. From the shell on the ALM Octane
server, run:

ALM Octane (16.0.100) Page 58 of 80

Installation Guide for Linux
Management

curl -XDELETE 'http://<server address>:9200/mqm_<sp_logical_

name>/'

5. Start the ALM Octane server.

systemctl start octane

Update database password in ALM Octane site schema and

configuration files
If you change your database password, you can use the database password update tool to update the
database password in ALM Octane’s site schema, and in the octane.conf configuration files. Note that
this does not update the database user’s password, but only ALM Octane's configuration.

Note: The tool operates offline. Credential outputs are disabled for security.

1. Stop the ALM Octane server.

After stopping the server, wait 30 seconds before running the tool. The cluster is considered
offline when there is no activity from any node for 30 seconds.
2. Run the following command on your ALM Octane server:

/opt/octane/install/updatedbcreds.sh
3. Enter values as described in the sections below.
4. When you are done, start the ALM Octane server.

Usage
The tool can operate in 2 modes: file, or interactive.

updatedbcreds.sh <-m mode> <-f path | -t target>

Where:
l mode = {file | interactive}
l target = {admin | user}

l path = valid absolute or relative path to file

File. If mode is set to file, use -f to specify the path to the password definition file. Credentials will be
taken from the provided file.
Interactive. If mode is set to interactive, use -t to specify the target whose password you want to
change - either admin or user. You will enter credentials interactively. Note that either the admin or

ALM Octane (16.0.100) Page 59 of 80

Installation Guide for Linux
Management

user definition can be omitted. In this case the other user's password is taken and its password will not
change.

File mode
You can use the CLI in file mode, which allows granular definitions for admin, user, or space
passwords.
Using a tool in file mode looks like this:

./updatedbcreds.sh -m file -f /path/to/definition.json

This is done using a JSON password definition file, in the following format:

```json
{
"admin" : {
"password" : "PasswordForAdminUser"
},
"appUser" : {
"password" : "PasswordForAppUser"
},
"spaces": {
"default_shared_space": {
"password": "PasswordForSpecificSpace"
}
}
}
You can delete the spaces section. In this case all spaces will get the appUser password.

Caution: Before the tool runs, your file contains passwords in clear text. It is your responsibility
as administrator to secure the file according to your organization's policies. The tool encrypts
the file when running. The tool can read the encrypted password if you want to rerun the tool.

For improved security, use interactive mode.

Interactive mode
In interactive mode you update only the admin or user password. This is useful when you do not need
extensive password definition and just want to change a password for a single user.
Using a tool in interactive mode looks like this:

$ ./updatedbcreds.sh -m interactive -t admin

Enter the following:

ALM Octane (16.0.100) Page 60 of 80

Installation Guide for Linux
Management

l New password for ADMIN: Enter a new password for admin user. Output is disabled.
l DB authentication username: Enter a user for CLI database connection. Output is disabled.
l DB authentication password: Enter a password for CLI database connection. Output is disabled.

See also:
l "Management" on page 57

Configure trust on the ALM Octane server

Configure trust on the ALM Octane server when you connect to any remote server (such as a
database server, an LDAP server, license sharing with ALM, and so on) over a secure channel.

Note: When connecting to a database server with SSL, or an LDAP server, over a secure
channel, you must configure trust before starting the ALM Octane server by running systemctl
start octane.

In this topic:
l "Configure trust" below

Configure trust
This section describes how to configure trust.

To configure trust:
1. Obtain the certificate of the root and any intermediate Certificate Authority that issued the
remote server certificate.
2. Import each certificate into the ALM Octane java truststore using a keytool command.
l Locate your <java_home>  directory. It is usually under the user/lib directory but may be
different for your environment. One way to check the location of the <java_home> directory
is to check the environment information settings in the /octane/log/wrapper.log file.
Example: /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.131-11.b12.el7.x86_64/jre
l Locate your keystore cacerts file, which is usually here: <java_
home>/jre/lib/security/cacerts
l Import each certificate.
Example:

cd <java_home>/bin

ALM Octane (16.0.100) Page 61 of 80

Installation Guide for Linux
Management

./keytool -import -trustcacerts -alias <CA> -file <path to the

CA certificate file> -keystore ../lib/security/cacerts

3. In the octane.conf file, enter the cacerts password in the java-default-trust-store-password

parameter.
4. If the ALM Octane service (octane) is running, restart it.

Advanced ALM Octane server configuration

This section describes advanced configuration tasks for the ALM Octane server.
This section includes:
l "Redirect http to https" below
l "Configure number of allowed open files (Linux)" on the next page
l "Configure SSL offloading" on page 65
l "Dedicate a cluster node for background jobs – 12.60 CP8 and later" on page 67

Redirect http to https

This procedure describes how to redirect http to https. You need to redirect to https when accessing
the ALM Octane server directly, and not through a front-end server.

To redirect http to https:

1. Edit /opt/octane/webapps/root/WEB-INF/web.xml, and add the following at the end (before
</web-app>):

<security-constraint>
<web-resource-collection>
<web-resource-name>Everything</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>

2. Restart .
3. Access ALM OctaneALM Octane via http://<ALM Octane>:8080/ui. Port 8080 is the default port.
You should be redirected to https://<ALM Octane>:8443/ui. If not, ensure that SecurePort in
jetty.xml matches your secure port.

ALM Octane (16.0.100) Page 62 of 80

Installation Guide for Linux
Management

Configure number of allowed open files (Linux)

If ALM Octane is under a very heavy load, it might try to use too many Linux resources. In this case,
Linux kills the server process. Do the following to increase the number of allowed open files to 65536:

To configure number of allowed open files:

1. Open the /etc/security/limits.conf file.
2. Add the following line:

octane hard nofile 65536

3. Restart the ALM Octane server.
For details, see https://easyengine.io/tutorials/linux/increase-open-files-limit/.

ALM Octane (16.0.100) Page 63 of 80

Installation Guide for Linux
Management

Configure secure database access

This section describes how to configure a secure connection from the ALM Octane server to the
database server. The secure connection is protected with SSL/TLS for encryption and authentication.
This section includes: 
l "Defining the connection-string for secure database access" below
l "To configure a secure database connection for a previously-unsecured database " on the next
page
l "To configure a secure database connection for a new ALM Octane installation" on the next page

Defining the connection-string for secure database access

SQL Server

SQL Server
Scenario Instructions

SSL/TLS is Add the encryption method to the end of the ConnectionString value.
required
jdbc:sqlserver://<server>:<port>;encrypt=true;trustServerCertificate=true

SSL without When using SSL, disable validation of the certificate sent by the database server.
certificate Add the encryption method to the end of the ConnectionString value, and apply the
validation certificate into the java certs file located under <JAVA_
HOME>\jre\lib\security\certs.
jdbc:sqlserver://<server>:<port>;encrypt=true;trustServerCertificate=false;trustStor
e=<Java Certs file>;trustStorePassword=<JKS password>

Oracle

Oracle
scenario Instructions

SSL/TLS To configure a secure connection from the ALM Octane server to the database server
required using SSL or SSO, refer to the section "Using SSL/SSO (optional)" in the ALM Octane
Installation Guide..

ALM Octane (16.0.100) Page 64 of 80

Installation Guide for Linux
Management

To configure a secure database connection for a previously-unsecured database

This step provides instructions for configuring the site schema connection.
Skip this section if you have a separate database server for your workspaces and you only want a
secure connection to that database.
This section is relevant if the database server that was configured for a secure connection contains
your site schema.
1. Edit the octane.conf file. The default location is /opt/octane):
a. Set the value of site-action to CONNECT_TO_EXISTING:

site-action=CONNECT_TO_EXISTING
b. Edit the line with connection-string. For details, see "Advanced ALM Octane server
configuration" on page 62.
2. If SSL/TLS is required, make sure the trust on the ALM Octane server has been established. For
details, see "Configure trust on the ALM Octane server" on page 61.
3. Run the service to start the ALM Octane server.

systemctl start octane

To configure a secure database connection for a new ALM Octane installation

1. After installing ALM Octane, start the server:

systemctl start octane

2. In the Database Server step, select the connection-string option and set the values for your
database. For details, see "Advanced ALM Octane server configuration" on page 62.
3. Make sure the trust on ALM Octane the ALM Octane server has been established. For details, see
"Configure trust on the ALM Octane server" on page 61.

Configure SSL offloading

When ALM Octane is installed with SSL offloading, make sure re-directions go to HTTPS addresses
instead of HTTP addresses.

To configure SSL offloading:

1. The X-Forwarded-Proto header must be defined in a reverse proxy.
For example (on Apache):

ALM Octane (16.0.100) Page 65 of 80

Installation Guide for Linux
Management

a. Add this line at the end of httpd.conf:

RequestHeader set X-Forwarded-Proto https

b. Restart Apache.
2. Open the <ALM Octane-installation-folder>/octane/server/conf/jetty.xml file in an editor.
In the section <New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">, make sure
that the following lines are uncommented:

<Call name="addCustomizer">

<Arg><New
class="org.eclipse.jetty.server.ForwardedRequestCustomizer"/></A
rg>

</Call>

ALM Octane (16.0.100) Page 66 of 80

Installation Guide for Linux
Management

Dedicate a cluster node for background jobs – 12.60 CP8

and later
You can dedicates nodes for certain purposes, such as for running background asynchronous jobs.
This frees up nodes for processing requests that come directly from the ALM Octane UI, as users
work.

Overview
Cluster nodes can be one of the following types:
l Worker nodes. Cluster nodes that handle background asynchronous jobs, such as synchronization.
l Web nodes. All other nodes. Web nodes generally handle direct requests from ALM Octane, but can
also handle background jobs if the worker nodes are not available. The load balancer distributes
the requests as usual among the web nodes.

To dedicate a node for background jobs

After the ALM Octane installation is complete, and you have verified that the server is up and you can
log into ALM Octane, perform the following:
1. Stop the ALM Octane server.
2. Add another node to the cluster that is not connected to the load balancer.
3. Follow the instructions for installing ALM Octane on cluster nodes. For details, see "Cluster
installation flow" on page 16.
4. The ALM Octane site admin authenticates, and then updates the ROLE for this cluster node in
the SERVER table using the REST API.

PUT https://<server>:<port>/admin/servers

{  "data": [
{

"role":"WORKER",

"id":"<serverID>"

}
]

}
For details on authenticating and working with the REST API, see Overview for developer in the
ALM Octane Help Center.
5. Start the ALM Octane server.

ALM Octane (16.0.100) Page 67 of 80

Installation Guide for Linux
Management

See also:
l "Management" on page 57

Using exception files for manual database changes

This topic provides instructions for defining exception files. Use exception files if the organization's
DBA added objects to database schemas, such as tables, indexes, stored procedures, columns, or
other objects.
In this topic: 
l "Overview" below
l "Define exception files" below
l "Set up use of the exception file" on page 70

Overview
Exception files instruct ALM Octane to ignore any errors issued because of manual additions to the
database schema. These errors would typically stop the installation or upgrade process.
You can use exception files to ignore errors for extra tables, views, columns, and sequences. For any
other problem, consult with your database administrator.

Caution: Using the exception file to ignore errors for objects that are added manually to the
schema may compromise stability and the validity of the database user schema.

You can use the exception files during a new ALM Octane installation, when upgrading, and when
creating a space. 

Define exception files

Define exception files before installation, before upgrading, or before you create the new spaces.

To define exception files:

1. Copy both of the mqm_exception.xml files from the ALM Octane installation directories. You can
rename them.
2. Locate the MQM_EXCEPTIONS part of the file.

<MQM_EXCEPTIONS>
<exceptions>
<declaration>
<!--<object pattern="TABLE_1_EXAMPLE" type="missing"

ALM Octane (16.0.100) Page 68 of 80

Installation Guide for Linux
Management

/>-->
<!--<object pattern=" TABLE_1_EXAMPLE" type="extra"
/>-->
</declaration>
</exceptions>
</MQM_EXCEPTIONS>

3. Change the <declaration> to one of the following. Add as many declarations as you need.
l TableMissing
l ViewMissing

l ColumnMissing

l ConstraintMissing

l IndexMissing

l PartitionFunctionMissing

l PartitionSchemeMissing

l ProcedureMissing

l SequenceMissing

l TriggerMissing

4. For each object pattern, you can specify one of the following types: 

missing The object is needed but is missing.

extra The object is extra because it was created after ALM Octane installation or before
upgrading.

Examples
l For an extra table:

<TableMissing>
<object pattern="MY_Table" type="extra"/>
</TableMissing>

l For an extra view:

<ViewMissing>
<object pattern="MY_VIEW" type="extra"/>
</ViewMissing>

ALM Octane (16.0.100) Page 69 of 80

Installation Guide for Linux
Management

l For an extra column:

<ColumnMissing>
<object pattern="MY_COLUMN" type="extra"/>
</ColumnMissing>

l For an extra sequence:

<SequenceMissing>
<object pattern="MY_SEQUENCE" type="extra"/>
</SequenceMissing>

Set up use of the exception file

This topic explains how to use the exception file when installing ALM Octane or when creating a new
space.

Use of the exception files during first-time installation

You can use exception files when installing ALM Octane using existing schemas/databases instead of
having ALM Octane create new schemas for you. This is the FILL_EXISTING installation option and it is
set in the octane.conf file.
1. During installation, when configuring the /opt/conf/octane.conf file in the configuration folder,
add these two settings using an editor: 

MqmExceptionsSiteAdminPath The exception file for the site.

/opt/tmp/site/mqm_exceptions.xml.

MqmExceptionsSharedSpacePath The exception file for the default space.

/opt/tmp/shared_space/mqm_exceptions.xml
2. Continue installing.
3. After the installation, check that the ALM Octane Server is up and that you have proper access to
the site and the default space.

Use of the exception files when upgrading

You can use exception files when upgrading ALM Octane.
After installation, the exception files are copied to the repository folder. So when upgrading, modify
the copies of the exception files in the repository folder instead of the files in the configuration folder.
1. During the upgrade, when configuring the octane.conf file in the repository folder, add or modify
these two settings using an editor: 

ALM Octane (16.0.100) Page 70 of 80

Installation Guide for Linux
Management

The exception /opt/octane/repo/storage/schema/maintenance/exceptions/site_

file for the site admin/mqm_exception.xml

The exception /opt/octane/repo/storage/schema/maintenance/exceptions/shared_

file for the new space/mqm_exception.xml
space
2. Continue upgrading.
3. After the upgrade, check that the ALM Octane Server is up and that you have proper access to
the site and the default space.

Use of the exception files when creating a space

ALM Octane processes the exception files also when adding new spaces.
After installation, the exception files are copied to the repository folder.
Before adding a new space, modify the copies of the exception files in the repository folder instead of
the files in the configuration folder.
1. Add exceptions as necessary to the exception files using an editor:

The exception /opt/octane/repo/storage/schema/maintenance/exceptions/site_

file for the site admin/mqm_exception.xml

The exception /opt/octane/repo/storage/schema/maintenance/exceptions/shared_

file for the new space/mqm_exception.xml
space
2. In ALM Octane Settings area, add the space using an existing schema. For details, see Create
spaces for a site in the ALM Octane Help Center.
3. Check that you have proper access to the space.

See also:
l "Configure site settings" on page 34
l Troubleshooting: ""My FILL_EXISTING installation failed, indicating that I have extra tables, view,
indexes, and so on."" on page 74

ALM Octane (16.0.100) Page 71 of 80

Installation Guide for Linux
Troubleshooting

Troubleshooting
This section contains troubleshooting suggestions for issues relating to the ALM Octane installation.
You can also check the log here: /opt/octane/log
For an up-to-date list of installation troubleshooters, see Micro Focus Software Self-solve knowledge
base article KM02703217.

"ALM Octane displays an error indicating that the ALM Octane server is not responding. I
cannot work in ALM Octane."
If ALM Octane is under a very heavy load, it might try to use too many Linux resources. In this case,
Linux kills the server process. Do the following to increase the number of allowed open files to 65536:
1. Open the /etc/security/limits.conf file.
2. Add the following line:

octane hard nofile 65536

3. Restart the ALM Octane server.
For details, see https://easyengine.io/tutorials/linux/increase-open-files-limit/.

"I rebooted the ALM Octane server machine. The octane service did not start up
automatically."
When you reboot the machine, you need to manually restart the ALM Octane server:

systemctl restart octane

The service runs in the background.

"ALM Octane does not open in Internet Explorer."

If you encounter problems opening ALM Octane in Internet Explorer, check that the domain is
configured correctly:
1. Edit the octane.conf and provide the correct the domain.
2. Restart the ALM Octane server.

"I cannot log into ALM Octane because ports are closed."
By default, the ALM Octane server uses port 8080 or port 8443 (secure). The port must be opened in
the firewall for incoming traffic.

"I am unexpectedly logged out."

Typically, a user is logged out of ALM Octane only after session timeout. If, however, you are
unexpectedly logged out while actively working in ALM Octane, you may need to clear cookies before

ALM Octane (16.0.100) Page 72 of 80

Installation Guide for Linux
Troubleshooting

you can log in again.

To prevent an unexpected logout:
l When working with a local DNS, make sure that you access ALM Octane only with a fully-qualified
machine name, together with the machine's domain.

Example: http://myserver-123545.domain.com:8080/

"JVM does not load."

If JVM fails to load after the octane service is started, check that Java is properly installed and that
JAVA_HOME is configured correctly.
The /opt/octane/log/wrapper.log file shows the following error message:

ERROR | wrapper | JVM exited while loading the application.

INFO | jvm 1 | Unrecognized VM option
'UseCompressedClassPointers'
INFO | jvm 1 | Error: Could not create the Java Virtual
Machine.
INFO | jvm 1 | Error: A fatal exception has occurred. Program
will exit.

To identify the important parameters of the system that may affect the installation, run the following
commands:

To get... Command

Java information java -XshowSettings:properties -version

All installed Java applications find / -name java
All installed Java versions find / -name java -exec {} a \;
The JAVA_HOME property echo $JAVA_HOME
The PATH property echo $PATH

"Application server address shows port 8080 even when changed."

By default, the installation uses port 8080 for HTTP or port 8443 for HTTPS (SSL). If you change the
port to a non-default value after the initial installation phase, the site Servers tab shows:
l The original application server address still displays as port 8080.
l The server state is inaccessible even though the server is accessible.

ALM Octane (16.0.100) Page 73 of 80

Installation Guide for Linux
Troubleshooting

"Failure to create SA schema due to nonexistent TableSpace or TempTableSpace."

If errors occur during site schema creation, and the site.log file contains a message indicating that a
certain tablespace or a temporary tablespace does not exist, check that the specified TableSpace or
TempTableSpace is correct.

"When initializing, the ALM Octane installation failed with a site schema problem."
If you receive a site schema error, such as "Cannot upgrade SA. SA schema version must be lower than
the current server version," do the following:
1. Open a backup copy of the site schema.
2. Fix the problem.
3. Restart the server (meaning, run systemctl restart octane again).

"The wrapper.log has Java-related warnings (Linux)"

After installing or upgrading, the following warning appears in the /opt/octane/log/wrapper.log file.

INFO | jvm 1 | 2017/06/27 17:20:56.318 | Caused by:

java.net.UnknownHostException: <…some host name…> unknown error

To eliminate this warning:

1. Add the ALM Octane server to the /etc/hosts file.

Example: For non-dynamic IPs, you can add the server in this format: 

<ip_of_machine> <name_of_machine> localhost

Such as: 192.168.0.185 machine-72 localhost

2. Restart the ALM Octane Server. For details, see "Start the ALM Octane server manually" on
page 58.

"My FILL_EXISTING installation failed, indicating that I have extra tables, view, indexes, and
so on."
Check if your DBA made manual additions to the database schema, such as adding tables, indexes,
and so on. If the installation encounters objects that it does not expect in the database schema, the
installation can fail.
To avoid this, create exception files. For details, see "Using exception files for manual database
changes" on page 68.

ALM Octane (16.0.100) Page 74 of 80

Installation Guide for Linux
Troubleshooting

If you still have problems: 

l Check that the parameters in the octane.conf file and the exception files have been entered
correctly.
l Check the /opt/octane/log/wrapper.log for errors.

"Either ALM Octane cannot fetch Jetty files or Internet Explorer 11 does not connect to
SSL"
The conscript library allows you to enable HTTP/2 in Jetty. Sometimes, however, using the conscript
library causes issues. To resolve these issues, disable the conscript library and switch back to native
Java SSL. For instructions, see Micro Focus Software Self-solve knowledge base article KM03310408.

See also:
l "Management" on page 57

ALM Octane (16.0.100) Page 75 of 80

Installation Guide for Linux
Troubleshooting

Checking logs
ALM Octane's log files are stored in the /opt/octane/log directory, or the directory that you specified
when you deployed.
In this topic: 
l "Log files" below
l "Monitor the deployment procedure" below

Log files
Log Path

Application logs /opt/octane/log/nga/app/app.log

Site logs /opt/octane/log/nga/site/site.log
octane service (server) logs /opt/octane/log/nga/wrapper.log
Overall octane log, which summarizes the contents of day-to-day log files in /opt/octane/log/nga/octane.log
one file.

Monitor the deployment procedure

Run the following command and wait until you see a server boot complete message:

tail -f /opt/octane/log/wrapper.log

See also:
l "Management" on page 57

ALM Octane (16.0.100) Page 76 of 80

Installation Guide for Linux
Uninstall

Uninstall
This section describes how to uninstall the ALM Octane server.

To uninstall the ALM Octane server:

1. Query the package name. Run:

rpm –q octane

2. Uninstall ALM Octane. Run:

rpm -e <package name>

3. The uninstall process does not delete the repository, log, and configuration directories, in case
you want to reinstall. Delete them if necessary:

rm -rf /opt/octane

See also:
l "Installation" on page 30

ALM Octane (16.0.100) Page 77 of 80

Installation Guide for Linux
Uninstall

ALM Octane (16.0.100) Page 78 of 80

Installation Guide for Linux
Send Us Feedback

Send Us Feedback
Let us know how we can improve your experience with the Installation Guide for Linux.
Send your email to: docteam@microfocus.com

ALM Octane (16.0.100) Page 79 of 80