Configure other settings

You can configure additional site settings using the octane.yml file. These settings are configured during installation, and can also be changed any time, whenever necessary.

Overview

If you update any of these settings at a later time, make sure you restart the ALM Octane server. 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.

Configure these settings by editing the octane.yml using any editor:   C:\octane\conf\octane.yml.

Back to top

Rules for editing the octane.yml file

Caution: Correct indentation and formatting is essential when editing yml files to avoid unpredictable results during installation.

There are resources available online that describe the exact rules and conventions for formatting yml files. We strongly recommend that you familiarize yourself with these rules before editing octane.yml.

Here are some important rules when editing settings in octane.yml:

  • Put a single space after the colon between the parameter name and the value.

  • Do not add bullets or any other extra formatting.

  • Do not add extra spaces.

  • Use double quotes to enclose any values that include special characters, especially the #.

    A # that is not enclosed in quotes marks the beginning of a comment. Any text after it, until the end of the line, is ignored. The octane.yml file is then interpreted incorrectly during installation and causes errors.

If these conventions are not followed, ALM Octane initialization or upgrade can fail.

For an example, see the sample octaneExample.yml file.

Back to top

General server settings

cluster

Cluster configuration: Enter a comma-separated list of node host names or IPs in the cluster.

Example: 10.0.0.24,10.0.0.99,10.0.0.23

This is a mandatory setting.

By default, the cluster is not configured, and the default value is blank. This indicates a standalone ALM Octane server.

heapSize

Before starting the ALM Octane server the first time, change the heap memory values on all active cluster 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.

heapSize should be set 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

server

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

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.

proxy

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.

An example of accessing an external server is when using a Trigger webhook rule.

host: <proxy_host>

port: <proxy_port>

user: <user>

password: <password>

authenticationType

Whether the ALM Octane installation should use native user management or LDAP authentication for user management.

Values are: 

sso. Use SSO authentication.

ldap. Use LDAP authentication.

internal. Use internal, native ALM Octane user management. Default.

Back to top

LDAP settings

If you are planning on authenticating users using LDAP, set the authenticationType setting is set to ldap, and define the following settings.

Later, after ALM Octane installation, import users from LDAP into ALM Octane. See Plan how to set up LDAP user authentication in the ALM OctaneHelp Center.

Note: After updating the octane.yml file, 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.

Make sure your LDAP system has the corresponding attributes for each mandatory LDAP setting.

General LDAP settings

connectionTimeout

Connection timeout in seconds. Optional.

Default: 30 seconds

adminDn

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 octane.yml, 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 setup.xml 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 setup.xml file is overwritten.

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

LDAP server settings

Make sure your LDAP system has the corresponding attributes for each mandatory LDAP setting.

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

Enter the following settings for each LDAP server separately.

Each LDAP server is defined by a group of settings. The settings for each LDAP server start with a hyphen (-) followed by the host setting.

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.

Prefix each host item with a - sign: - host. This instructs ALM Octane where each host begins, especially if there are multiple LDAP servers.

port LDAP server connection port. Mandatory.
isSsl

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 ALM Octane server.

description

Description of the LDAP server. Optional.

baseDirectories

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.

If specified,

Make sure to put a space after hyphen ( - ) before specifying the filter.

Example:

baseDirectories:
   - ou=Groups,o=organization.com
   - dc=maxcrc,dc=com
baseFilters

Filters to use to refine the search for users when including new LDAP users in ALM Octane spaces. This is generally a list of LDAP objectClasses.

Optional. Default:  (objectClass=*)

Make sure to put a space after hyphen ( - ) before specifying the filter.

Example

baseFilters:
   - (objectClass=*)
   - (&(objectClass=user)(objectCategory=person))
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: 

  • anonymous. In this case, skip the next two parameters, user and password.

  • simple, user, and password are mandatory.

user

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

Make sure your LDAP system has the corresponding attributes for each mandatory LDAP setting.

Enter the following mapping settings for each LDAP server separately.

Values used in the mapping section are case-sensitive.

ALM Octane attribute in octane.yml Sample LDAP attribute that 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

(for Active Directory)

The LDAP distinguished name attribute. Unique. Mandatory.

This attribute is typically in a format that contains the common name and 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.

Example

  1. If in LDAP, the entryDN attribute value is: cn=<common_name>,ou=<organizational_unit>,dc=<part_of_domain>

  2. In the octane.yml, 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

entryDN

(for other LDAP systems)

 

uid

objectGUID

(for Active Directory)

The LDAP attribute that should be used as the immutable, globally-unique identifier. Mandatory.

In this documentation, we also refer to this as the UUID (universally unique ID).

To work with ALM Octane with Active Directory, we use objectGUID.

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.

entryUUID

(for other LDAP systems)

The LDAP attribute that should be used as the immutable, globally-unique identifier. Mandatory.

In this documentation, we also refer to this as the UUID (universally unique ID).

To work with ALM Octane, we generally use entryUUID for OpenLDAP. However, depending on your LDAP, this attribute might be different, such as GUID or orclguid.

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.
firstName givenName LDAP attribute for first name, such as givenName. Mandatory.
lastName sn LDAP attribute for last name, such as sn. Mandatory.
fullName cn LDAP attribute for full name, such as cn. Optional.
logonName mail

This is the unique identifier between all ALM Octane users, and this attribute is 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 logonName. Mandatory.

  • You can change the logonName attribute mapping at any time, but make sure the logonName 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.

    Back to top

    License settings

    Locate the section called license, and enter values for the following settings.

    Caution: If you plan to install a license for Team Edition at a later stage, you must enter team in the trialEdition field now.

    Installing a license for Team Edition after an Enterprise Edition trial is not supported.

    trialEdition

    Enter team or enterprise, depending on your trial edition. For details, see the information about ALM Octane editions in the ALM Octane User Guide.

    Note: This setting is used the first time the ALM Octane server starts, and cannot be changed retroactively.

    mode
    • If you are using a standalone ALM Octane license, enter standalone. You can then skip the remaining fields in the License section. Default.

    • If you are allocating licenses from ALM to ALM Octane, enter almSharing. You then need to fill in the following fields as described below.

    The following fields are mandatory for almSharing mode:
    url

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

    almIntegrationUser

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

    almIntegrationPassword

    Enter the password for the almIntegrationUser.

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

    Back to top

    Oracle settings

    The following Oracle section and its settings are also available.

    Section Setting Description and usage
    oracle_database: useDefaultSort

    For Oracle databases: Defines whether the standard Oracle binary sort (NLS_SORT="BINARY_CI") should be overridden for non-Latin language support.

    Valid values: yes, no, or blank

    Default: blank (yes) 

    Usage

    oracle_database:
      useDefaultSort: no

    Back to top

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

    cluster: 

    Section header. Do not edit.

    cluster:
       isCluster: true
       nodes:

    isCluster

    Available with 12.60 CP8 and later.

    Whether your server is standalone or in a cluster configuration.

    Mandatory.

    For a cluster configuration, set this value to true. You must enter node host names in the nodes setting.

    For a standalone server, set this value to false and do not enter any host names using the nodes setting.

    Default: true

    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.

    Examples

    • server1.domain.com,server2.domain.com,server3.domain.com
    • 120.150.12.12,120.150.80.13,120.150.32.14

    Make sure isCluster is set to true.

    Back to top

    ALM Octane service provider (SP) settings

    The following service provider (SP) section and its settings are also available.

    For these settings to take affect, make sure to set the authentication type to sso in this octane.yml file using the authenticationType setting.

    For an example of setting these parameters, see the octaneExample.yml file.

    Main settings

    Setting Description and usage
    sso.key-pair.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

    sso.key-pair.pwd

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

    When ALM Octane starts, it encrypts this password.

    Mandatory.

    Example: my-secret

    sso.keystore.file

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

    The default format for this file is PKCS12. You can change the format to Java KeyStore (JKS) by specifying this type when adding the sso.oauth-keystore.type setting to octane.yml.

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

    Mandatory.

    Example: /opt/octane/conf/keystore.p12

    sso.keystore.pwd

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

    When ALM Octane starts, it encrypts this password.

    Mandatory.

    Example: my-password

    sso.login.saml2.idp.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 sso.login.saml2.idp.metadata setting.

    Mandatory, if sso.login.saml2.idp.metadatal is not defined.

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

    sso.login.saml2.idp.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 sso.saml2.idp.metadata-url is ignored.

    Mandatory, if sso.login.saml2.idp.metadata-url is not defined.

    You can define the SAML metadata descriptor resource with either this setting or the sso.login.saml2.idp.metadata-url setting.

    sso.oauth.authentication.timeout.seconds

    The SSO authentication timeout in seconds.

    Optional.

    Default: 10800 seconds (3 hours).

    sso.oauth.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

    sso.oauth.client.secret

    The OAuth client secret for the integration's client ID defined with sso.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

    sso.saml.mapping.username

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

    Valid values are: 

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

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

    Additional settings

    Setting Description and usage
    sso.logging.console.enabled

    Whether to log to the console. Log messages are issued to the ALM Octanewrapper.log file.

    Optional.

    Default: false

    sso.logging.file.dir

    The directory to create the SSO log files in, if .

    Optional.

    Default: <log folder>/sso

    sso.logging.file.enabled

    Whether to log to the ALM Octane file in the directory defined by the sso.logging.file.dir attribute.

    Optional.

    Default: true

    sso.logging.level

    Logging level. Possible values are: 

    • SEVERE

    • INFO

    • WARNING

    • ALL

    Optional.

    Default: WARNING

    sso.login.saml2.subject.format

    The format of the NameIDPolicy attribute in the SAML request.

    Default: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

    sso.oauth.client.redirect-uri.host

    The domain name used to redirect back to ALM Octane. Regular expressions are supported, for example, .*mydomain.*

    Optional.

    in the domain from the AppURL setting as defined in the setup.xml file, surrounded by wildcards.

    Caution: The redirect URI is a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server redirects the user back to the application with the authorization code in the URL. Because the redirect URL contains sensitive information, it is critical that the service does not redirect the user to arbitrary locations.

    Example: .*company-infra.net.*

    sso.oauth.client.redirect-uri.schema

    The schema (http or https) used to access ALM Octane.

    Caution: The redirect URI is a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server redirects the user back to the application with the authorization code in the URL. Because the redirect URL contains sensitive information, it is critical that the service does not redirect the user to arbitrary locations.

    Optional.

    Default: The schema in the AppURL setting defined in the setup.xml file.

    sso.saml.mapping.firstName

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

    Optional.

    Default: firstName

    sso.saml.mapping.fullName

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

    Optional.

    Default: fullName

    sso.saml.mapping.lastName

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

    Optional.

    Default: lastName

    sso.saml.mapping.mail

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

    Optional.

    Default: mail

    sso.saml.mapping.uuid

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

    Optional.

    Default: uuid

    Back to top

    Next steps: