Upgrade

This section describes how to upgrade an existing installation of an on-premises ALM Octane server on Linux.

Before you upgrade

  1. Verify that your server machine, and if relevant, all cluster nodes, meet all prerequisites.

    This includes checking the supported versions for all third party tools, such as Elasticsearch, and upgrading accordingly.

    For details, see Prerequisites.

    Note: If the following are both true, add the CREATE SEQUENCE privilege to the site and shared space schemas: 

    • You are upgrading from an ALM Octane version earlier than 12.55.3. 

    • You are upgrading an installation without a DB admin, for example, your original ALM Octane was installed using the FILL_EXISTING site action.

  2. Create backups of:

    • The repository

    • Existing ALM Octane configuration files, including setup.xml and octane.yml

    • Your database

    • Elasticsearch

    • If you are using ALM Octane Synchronizer, back up : 

      • /opt/octane/wrapper.conf

      • Service.locator.properties (/opt/octane/webapps)

    For recommendations on making these backups, see Best practices: Backing up ALM Octane data.

  3. Take note of any special aspects of your configuration, such as: 

    Special configuration Recommendation
    Did you use a different user, other than the octane user, to install? If you did, the user is set in the OCTANE_USER environment variable. Use this user to upgrade.
    Did you install ALM Octane to a location other than /opt/octane? Refer to the location you used while upgrading.
    What sudoer user did you use to install?  Use the same sudoer user that was used for installation to upgrade.
    Did you modifiy the /opt/octane/webapps/root/WEB-INF/classes/hpssoconfig.xml file to control session timeouts? 

    If you modified the /opt/octane/webapps/root/WEB-INF/classes/hpssoconfig.xml file to control session timeouts, your updates will be overwritten by the upgrade.

    After upgrading, control session timeouts by setting the MINUTES_UNTIL_GLOBAL_SESSION_TIMEOUT and MINUTES_UNTIL_IDLE_SESSION_TIMEOUT configuration parameters instead. For details, see Configuration parameters in the ALM Octane Help Center.

    Do you want to switch from native user management to LDAP user management with this upgrade? 

    If you are upgrading from an ALM Octane version using native user management, and want to start using LDAP user management with this new ALM Octane version:

    1. Realize that once you configure for LDAP user management, you cannot return back to native, internal user management.

    2. When configuring initial settings in the setup.xml file, set the DefaultSpaceMode to isolated. For details, see DefaultSpaceMode.

    3. Upgrade ALM Octane without configuring for LDAP. This means, when modifying the octane.yml file, do not enter any values in the LDAP Settings section.

    4. After the upgrade is complete, configure for LDAP.

    5. Deactivate any native, internal users after LDAP configuration. These users can no longer log into ALM Octane (except for the adminDN user).
    Did your organization's DBA made changes to database schemas, such as the addition of tables or columns?

    Define an exception file. The exception file instructs ALM Octane to ignore manual changes to the database schemas during installation. For details, see Using exception files for manual database changes.

  4. Stop the octane service on the server, and if relevant, all cluster nodes.

Back to top

Deploy

Download and deploy the rpm package for the new version of ALM Octane using:

rpm -U <name of the RPM file>

For details, see Deploy ALM Octane.

Back to top

Configure initial settings

Here we describe how to modify settings in the setup.xml file.

  1. Manually add newly-introduced settings to setup.xml

    With each version of ALM Octane, settings are added to support new features. To upgrade to the new version, add the newly-introduced settings as listed in the table below to the setup.xml file.

    Give these new settings values.

    Here is a list of introduced settings for setup.xml, by version:

    Version New Setting Example
    12.53.20

    AppURL

    <entry key="AppURL">http://my_octane_server.my_domain.net:8080/</entry>

    Introduced in 12.55.4, but mandatory as of 12.55.17

    DefaultSpaceMode

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

    12.60.4 A new section, oracle_database, was added. It contains the new useDefaultSort setting. See Oracle settings below.
    1. If not already open, open /opt/octane/conf/setup.xml using an editor.

    2. Add any missing settings using this format:

      <entry key="<setting>"><setting value></entry>

      Do not modify any text in the <entry> and </entry> tags themselves. Only modify text between these tags.

    3. Save the file.

For a full list of settings for the current ALM Octane installation and their syntax, see Configure initial site settings .

Back to top

Configure other settings

Here we describe how to modify settings in the octane.yml file.

  1. Learn the format for yml files

    <setting><setting value>

    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.

  2. Determine settings to add to, and remove from, octane.yml

    With each version of ALM Octane, settings are added to support new features. To upgrade to the new version, add the newly-introduced settings as listed in the table below to the octane.yml file.

    Here is a list of introduced settings, by version:

    Version Added / Removed Example
    12.53.22

    In the LDAP settings section, added all LDAP settings.

    See LDAP below.
    12.55.4

    In the LDAP settings section, added the following LDAP settings:

    dn

    uid

    baseDirectories

    baseFilters

    dn and uid example:

        mapping:
          dn: entryDN
          uid: entryUUID

    method example:

    authentication:
      method: anonymous

    baseDirectories example:

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

    baseFilters example

    baseFilters:
       - (objectClass=*)
       - (&(objectClass=user)(objectCategory=person))

    In the License settings section, added all licenses settings.

    See licenses below.
    In the General server settings section removed the serverDomain setting.  
    12.55.17 In the License settings section, added the trialEdition setting. See licenses below.
    12.60.16

    For support for SSO in federated environments, added the service provider section.

    Also added a new authentication type setting for SSO.

    See SP Settings below.

    authenticationType: sso

  3. Modify settings

    1. Edit the /opt/octane/conf/octane.yml file using an editor.

    2. Remove the line with the serverDomain setting.

    3. Locate the section for each setting you need to add.

    4. Add any missing settings as listed above using this format:

      <setting><setting value>

      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.

      LDAP settings

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

      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.

      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.

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

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

      License settings

      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.

      Oracle settings

      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

      ALM Octane service provider (SP) settings

      The following service provider (SP) section and its settings are also available. Use these settings to set up SSO authentication for connecting to ALM Octane.

      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.

      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.metadata 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 Octane wrapper.log file.

      Optional.

      Default: false

      sso.logging.file.dir

      The directory in which to create the SSO log files.

      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.

      Example: .*company-infra.net.*

      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.

      sso.oauth.client.redirect-uri.schema

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

      Optional.

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

      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.

      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

    7. Save the file.

Back to top

Upgrade

  1. Start the ALM Octane server.

    service octane start
  2. Check the /opt/octane/log/wrapper.log file. If you do not see the "Server is ready!" message, correct the errors shown in the log.

    Instructions for troubleshooting upgrade errors and warnings:

Caution: Do not use ALM Octane until you have completed Upgrade spaces in ALM Octane.

Back to top

Upgrade cluster nodes

Caution: Do not use ALM Octane until you have completed Upgrade spaces in ALM Octane.

After the upgrade on the first node has completed successfully, you can then upgrade the remaining nodes in a cluster.

  1. Copy setup.xml and octane.yml files to each node.

  2. Start the ALM Octane server on each node.

    service octane start

For details, see Cluster installation (optional).

Back to top

Upgrade spaces in ALM Octane

After upgrading, log into ALM Octane as the site admin to upgrade each space.

  1. In a browser, navigate to <ServerURL>:<port>/ui?site.

  2. Log in as the space admin, with the user name and password you provided in the setup.xml file.

  3. Click Site and then click the Spaces tab.

  4. Select the space and click Upgrade.

    Upgrade is available only if the space needs to be upgraded.

    Click Refresh to see the updated status for the space.

    Note: Upgraded spaces are, by default, isolated. To work with shared spaces, create new spaces.

  5. Individual workspaces are upgraded in the background. In Settings > Spaces, click Background Jobs to track the progress of the workspace upgrades.

    Note: Until all of the background jobs have completed, some data may be unavailable in trend graphs.

For details on upgrading the space, see Upgrade spaces in the ALM Octane Help Center.

Back to top

Restart all Jetty servers

After upgrading the spaces in Settings, clear caches: 

  1. Stop all Jetty servers.

  2. Restart each Jetty server.

Note: Make sure all Jetty servers are stopped at the same time before restarting even one of them.

Back to top

After the upgrade

After the upgrade has completed successfully:

  • The space status becomes Active.

  • The space version is updated to the current version.

Back to top

Bulk update data access control

Note: This section is relevant only if you want to apply data access control for the first time to an upgraded system.

For data access control to work properly, both roles and entities must be assigned with data access control categories. After an upgrade, entities do not yet have a data access control category assigned to them. This means that roles that already have data access restrictions, will not be able to access these entities.

We recommend using the bulk update functionality to update entities efficiently.

Follow the instructions in Set up data access.When you reach the Assign data access categories to items section, use the Bulk Update option to assign data access categories to items, so that all the items are accessible only to the relevant roles.

Back to top

Next steps:

  • Update mandatory configuration parameters, such as SMTP_NOTIFICATION_SENDER_EMAIL. See
    Configuration parameters in the ALM Octane Help Center.
  • Download the newest IDE plugins for this ALM Octane version. See IDE integrations in the ALM Octane Help Center.
  • If you work with the REST API, you might want to check if any API resources have been deprecated. While the deprecated resources are supported for a while, we recommend that you start updating your code so that you use the resource aliases instead. To see deprecated resources for a particular version, see the corresponding REST API example and how to use the interactive API client in the ALM Octane Developer Help, What's changed in the REST API.
  • Rollback