1 of 6

Installation

Installation Procedure

This section provides instructions for installing on-premise or cloud hosted deployments of Clarity LIMS v6.2. For assistance with installation steps, contact the Clarity LIMS Support team.

This document provides the steps required to install a new Clarity LIMS v6.2 instance to Oracle Linux/RedHat Enterprise Linux v8.8 and v8.9.

The installation procedure includes adding the Clarity LIMS repository, installing the Clarity LIMS RPM through yum commands, and configuring the installation through a series of configuration scripts.

Prerequisites

Your system meets the requirements listed in Technical Requirements.
You have installed and configured the required components. For more information, see Pre-Installation Requirements.
You have a database user and two empty schemas on your database server. The schemas are populated during configuration.
You have received the appropriate repository files from the Clarity LIMS Support team.
All standard OS security updates have been applied.
All instances of Clarity LIMS must have a purchased SSL/TLS certificate installed. Purchase the certificate before installation or upgrade. For instructions on installing purchased SSL/TLS certificates, see Install a Purchased SSL/TLS Certificate.

With the Oracle Linux/RedHat Enterprise Linux server, the following error messages can display when you perform the yum commands used to install Clarity LIMS:

Failed loading plugin "product-id": No module named 'urllib3'

Failed loading plugin "subscription-manager": No module named 'urllib3'

Failed loading plugin "upload-profile": No module named 'urllib3'

These messages do not affect the installation of Clarity LIMS. You can resolve these error messages by running the following command:

pip3 install urllib3==1.24.2

Step 1: Add the Clarity LIMS Repository

Using scp/sftp, WinSCP, FileZilla, PSCP, or similar, copy the repository to the following location: /etc/yum.repos.d.

Test the repo file with this command:

yum --enablerepo=GLS_Clarity62 search ClarityLIMS-App

Step 2: Install Clarity LIMS

Run the install command:

yum --enablerepo=GLS_Clarity62 install ClarityLIMS-App

Type y to download and install the Clarity LIMS RPM core components.
NOTE: The installation of Clarity LIMS creates 3 operating system users:
- glsai - User created to run the Automation Worker node
- glsftp - User to access the SFTP file store
- glsjboss - Runs the application server
These users are created by the RPM installation process, and should not be created before starting the installation steps. The user home directories are created in the directory /opt/gls/clarity/users
The operating system passwords for each of the above users should be set by the root user.

Step 3: Run Configuration Scripts

As the glsjboss user, change directory to /opt/gls/clarity/config/pending with the following command:
```
cd /opt/gls/clarity/config/pending
```
Run the first script listed sequentially in the directory listing with the following bash command:
```
bash /opt/gls/clarity/config/pending/05_configure_claritylims_secretutil.sh
```
This script configures the Secret Utility password management tool so that secrets and passwords are accessible. It is recommended that you store application secrets in vault. If that is not possible, the configuration script supports file-based storage. For more information about the prompts, see Guide to Secret Management.

Run the following script:

bash /opt/gls/clarity/config/pending/20_configure_claritylims_platform.sh

Run the next script to initialize the database and overwrite any existing data:
```
bash /opt/gls/clarity/config/pending/26_initialize_claritylims_tenant.sh
```
NOTE: This script requires that you enter the password for the glsftp user. Entering the password does not set the password for this user.
If your database server is standalone or remote, update the /opt/gls/clarity/tomcat/current/lib/activity-management-ui-config.groovy file with the following code snippet.
```
hibernate {
    isis {
        template {
            url="jdbc:postgresql://<Replace me: Remote DB IP>:<Replace me: Remote DB Port>/{0}"
        }
    }
}
```
NOTE: Substitute the Remote DB IP and Remote DB Port placeholders with the information for your server.
If you do not update the script, log and database connection errors can occur.
Change to the root user, and then run the following script in the sequence to configure RabbitMQ:
```
bash /opt/gls/clarity/config/pending/32_root_configure_rabbitmq.sh
```
As the root user, install the Apache proxy with the following script:
```
bash /opt/gls/clarity/config/pending/40_root_install_proxy.sh
```

Step 4: Install Lablink

LabLink v2.4 is compatible with Clarity LIMS v6.2.

Before installing LabLink v2.4, make sure that a database named LabLink is created with the same database user as the Clarity LIMS database.

Turn off all Clarity LIMS services using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh stop
```
Install the LabLink RPM with the following yum command. Make sure that you have the correct repo enabled:
```
yum --enablerepo=GLS_Clarity6 install ClarityLIMS-LabLink
```
As the glsjboss user, run the pending initialization script using the following command:
```
bash /opt/gls/clarity/config/pending/60_initialize_lablink.sh
```
Restart all Clarity LIMS services using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh start
```
Make sure that LabLink is accessible at https://<your-Clarity-FQDN>/lablink

Step 5: Start the System

Clarity LIMS includes the run_clarity.sh script. This script starts (or stops) all Clarity LIMS services (Elasticsearch, RabbitMQ, Search Indexing, Tomcat, httpd/Apache proxy, Automation Worker) in the required order, with one command.

Run the following script as the root user:

/opt/gls/clarity/bin/run_clarity.sh (start|stop|restart)

If an error occurs starting any service, subsequent services will not be started. Stop all services before trying to start them again.

Start the system as follows.

Switch to the root user.
Make sure that no Clarity LIMS services are running.
Run the script with the following start command:
```
/opt/gls/clarity/bin/run_clarity.sh start
```
After the script has completed, all Clarity LIMS services should be ready for use.

If any services are running, the script exits and provides a list of services to stop. In this scenario, complete the following steps:

Use the script with stop command to stop services.
Open a supported browser window and make sure that you can access the Clarity LIMS client at the following URL: https://<your-Clarity-FQDN>/

Guide to Secret Management

Secret Utility (secretutil) is a password management tool used to store, manage, and retrieve passwords. Secret Utility returns the passwords in plain text.

The following sections describe the configuration of Secret Utility, which is installed as part of the Clarity LIMS-SecretUtil RPM.

Installing Integration Packages on Clarity LIMS

Integration Package

Clarity LIMS Version

Secret Util Mode

Installation Steps

Configuration Script

If Secret Utility has not been configured, the 05_configure_claritylims_secretutil.sh script is created in the /opt/gls/clarity/config/pending folder.

To reconfigure Secret Utility:

Remove the hidden file /opt/gls/clarity/tools/secretutil/.configured
Run the Secret Utility configuration script as follows: /opt/gls/clarity/config/configure_claritylims_secretutil.sh

The following table describes the entries prompted by the configure_claritylims_secretutil.sh script.

Configuration Script Entries

Prompts

Default

Description

Managing the passwords (Vault Mode)

If Secret Utility is configured as Vault Mode, the passwords are stored and retrieved from Vault Enterprise.

To use Secret Utility and perform the following steps, you must first remote into the instance before performing any of the following steps.
To use the Vault user interface (UI) and perform the following steps, you must have the appropriate role and access control list (ACL) policies.

Vault ACL Paths

The Vault ACLs control three main paths: Clarity, Integration, and Ops. If there is an attempt to write into a read-only path, secretutil.jar returns an error.

Clarity (read only)

Stores all passwords related to Clarity LIMS. The secrets/passwords are encrypted with CLARITYSECRET_ENCRYPTION_KEY env variable. See #claritylimsv6.2guidetosecretmanagement-configurationscript.

Integration (read write)

Stores all integration-related passwords and allows read and write access.
apiusers
- Stores passwords that are used by packages and applications for API authentication (eg, the apiuser password).
- Username is case sensitive.
- For example, retrieve apiuser password from integration/apiusers/apiuser.
external.file.stores
- Stores password of external file stores used by Clarity LIMS.
- External file store is optional to the Clarity LIMS system.
- For example, retrieve file store password from integration/external.file.stores/.password.

Ops

Stores secrets related to operations.
- For Illumina cloud hosted deployments, Illumina manages this path.
- This path is optional for on-premise customers.

Create a New Password

Using Secret Utility

The following command creates a new password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-h] [-n="namespace"] [-u="newValue"] "key"

When creating a new password for integration, specify the -n= integration option.
Make sure that the key uses a forward slash for nested secrets. For example, apiusers/apiuser
The same command is used for updating an existing password and creating a new password. Read the key you are planning to create to check whether it is an existing password.

Using Vault UI

Log in to the Vault UI.
Select the Key Value (KV) secret engine with the path instances.
Look for the FQDN instance that you want to create the password for.
Select the path where you want to create the new password, ie, clarity/integration/ops.
Select Create Secret +.
Under Path for this secret, enter the path for the new password, eg, app.ldap.managerPass.
Under Version data:
1. Enter 'value' into the key field.
2. Enter the new password into the value field.
Select Save.

Read an Existing Password

Using Secret Utility

Run the following command to create a new password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar "key"

Using Vault UI

Log in to the Vault UI.
Select the KV secret engine with the path instances.
Look for the FQDN instance that you want to create the password for.
Select the path where the existing password is located, ie, clarity/integration/ops.
Click into the secret and view the password by selecting the peek icon.

Update an Existing Password

Using Secret Utility

Run the following command to update an existing password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-h] [-n="namespace"] [-u="newValue"] "key"

Using Vault UI

Log in to the Vault UI.
Select the KV secret engine with the path instances.
Look for the FQDN instance that you want to create the password for.
Select the path where the existing password is located, ie, clarity/integration/ops.
Select into the secret.
Select Create new version +.
Under Version Data, enter the new password.
Select Save.

Delete an Existing Password

NOTE: Confirm with the Illumina Support team before deleting passwords and secrets.

Using Secret Utility

Secret Utility does not support permanent deletion of a key by design.

Using Vault UI

Log in to the Vault UI.
Select the KV secret engine with the path instances.
Look for the FQDN instance that you want to create the password for.
Select the path, ie, clarity/integration/ops, to the location of the existing password.
Select into the secret.
Select Delete secret.

Managing the Passwords (File Mode)

If Secret Utility is configured as File mode, the passwords are encrypted and stored in /opt/gls/clarity/tools/secretutil/conf/secrets.properties. Encryption is based on the CLARITYSECRET_ENCRYPTION_KEY environment variable.

To manage the passwords and perform the following steps, you must first remote into the instance.

Create a New Password

Run the following command to create a new password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-h] [-n="namespace"] [-u="newValue"] "key"

If you are creating a new password for integration, specify the -n=integration option.
The same command is used for updating an existing password and creating a new password. Read the key you are planning to create to check whether it is an existing password.

Read an Existing Password

Run the following command to read an existing password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar "key"

Update an Existing Password

Run the following command to update an existing password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-h] [-n="namespace"] [-u="newValue"] "key"

Delete an Existing Password

NOTE: Confirm with the Illumina Support team before deleting passwords and secrets.

By design, Secret Utility does not support permanent deletion of a key. As an alternative, you can run the following steps.

Open the secrets.properties file with an editor, eg, vim.
Remove the key from the file and save the file.

Install/Upgrade Secret Management for Integration Modules

This section describes the installation steps required for installing Secret Utility and integration packages.

As of Clarity LIMS v5.4, the method used for managing passwords (secrets) for Clarity LIMS integration modules has changed.

The following diagram shows the installation steps required for installing Secret Utility and integration packages with Clarity LIMS v5.4 and later.

For details on Compatibility of Releases with Integration Modules, see Compatibility

Install Clarity LIMS v6.2.
- Install Clarity LIMS-App 6.2 and complete pending script.
- Secret Utility (secretutil) is installed as part of Clarity LIMS-App 6.2 dependency, and the Secret Utility configuration is part of Clarity LIMS pending scripts.
Install Secret Utility.
- In the automated installation tooling for Clarity LIMS v6.2, the installation and configuration of Secret Utility is included. No further action is necessary.
- For manual installation:
  1. Install Clarity LIMS-SecretUtil.
  2. Configure Secret Utility by running the following script: /opt/gls/clarity/config/pending/05_configure_claritylims_secretutil.sh.
    Refer to Guide to Secret Management for details on configuring Secret Utility.
Check usage of custom API username.
- Check for any needs for custom API username, if any (eg novaseq_user). The documentation for the integration package provides the requirements for API username.
  NOTE: In a typical installation, a default API username (apiuser) is used. It is not necessary to add the default apiuser username, because it is configured as part of Clarity LIMS v6.2 installation. If no custom API username is required, skip step 4 and proceed to step 5.
Configure custom API username.
- If a custom API username is not required, proceed to step 5.
- If a custom API username is required, configure the user/password with Secret Utility as follows. Substitute the values enclosed in double quotes with your own values, keeping the double quotes.
  java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar -n=INTEGRATION -u="password" "key"
  Example:
  java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar -n=INTEGRATION -u="mypassword" "apiusers/novaseq_user"
- For a custom api username, set the key to apiusers/{custom api username}
Install integration package.
There is no change to the installation of the integration package. Follow existing installation instructions.
NOTE:
The new configuration script in the new integration package retrieves passwords directly from Secret Utility.
For IAP access token and BSSH access token, follow the existing setup guide. There is no change in the configuration step.

Change the Clarity LIMS Hostname

The core Clarity LIMS product includes the rename_claritylims_hostname.sh script, which allows you to change the hostname to which Clarity LIMS responds.

Prerequisites & considerations

Prerequisites

Clarity LIMS must be fully installed and configured. If it is not, the script instructs you to complete the installation.
The script stops all Clarity LIMS services. Make sure that all automation jobs are complete.
If you are not using a wild card SSL Certificate, purchase a certificate for the new hostname.
Update the hostname returned by the operating system to match the new name. Refer to for more information.
Running the renaming script requires root access.

Considerations

The script does not update the Automation Worker installation. After you have completed the renaming steps, you must reconfigure all local and remote Automation Workers.
You might need to reconfigure additional services, such as the Reporting and Sequencing services.

We recommend that you back up the database before performing the following renaming steps.

Settings changed

The following table lists the settings changed by the rename_claritylims_hostname.sh script.

Property

Global

Description

Location

*The ftp.host is only updated if it matches the previous IP address/hostname. This intended behavior accounts for the scenario in which the ftp host is on a different server.

Changing the LIMS hostname

Pre-script steps

Change the internal hostname
Before running the rename_claritylims_hostname.sh script, change the internal hostname for the instance - that is, /etc/hosts and related areas. There is no need to change any other LIMS-related components.
The new internal hostname will be used in the renaming process.
- To verify the internal hostname, use the following command:
  NOTE: If the hostname command does not return the correct new name, consult with your IT department to correct the name.
Verify SSL Certificate path:
The script may prompt you for the SSL Certificate path. Be sure to have that ready.

Running the script

Use the following command to change to the root user:
Navigate to the /opt/gls/clarity/config directory.
Run the rename_claritylims_hostname.sh script:bash rename_claritylims_hostname.sh
If prompted for your SSL Certificate path, enter this information.
The script prompts you to confirm that you have changed the internal hostname.
- If you enter no, you will be prompted to manually change the hostname (output shown below).
- If you enter yes, the script proceeds to modify Clarity LIMS-related components to use the new hostname.
When the renaming is complete, the script prompts you to restart Clarity LIMS by running the run_clarity.sh script:
When all Clarity LIMS services have restarted, make sure that the hostname has been changed successfully. Complete the following steps:
- Connect to all system components.
- Log in and test the LIMS user interface in your web browser.

Update Server Passwords and Database Connection Details

This document describes the steps required to update the Clarity LIMS application configuration.

Two levels of user passwords are created in the Clarity LIMS system: one at the operating system level and one at the Clarity LIMS level.

Following are details on the user passwords, instructions for changing them, and instructions for updating Clarity LIMS with the new database connection details.

The following steps are only required if the passwords for glsftp and/or apiuser have been changed.

Update Operating System User Passwords

The user passwords created at the operating system level are for the glsai, glsjboss, and glsftp users.

glsai and glsjboss users:
- These users have no configuration associated with them.
- You may change their passwords at any time.
glsftp user:
- After installation of Clarity LIMS, you can change this password. However, you must also update it in the file/vault secret store, using the Secret Management Util tool.

To change the glsftp password after installing Clarity LIMS, using SecretUtil:

Change the glsftp user's password on the server.
Log in to the server as the root user.
Stop Clarity LIMS using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh stop
```
Go to /opt/gls/clarity/tools/secretutil.
Update the password in the secret store.
- For vault-based secret storage, use either the Vault command line interface (CLI) or Vault user interface (UI) to update the password.
- For file-based secret storage, use Secret Management Util to update the password as follows:
  $ java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar -u="new-password" app.ftp.password
Start Clarity LIMS using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh start
```

Update Clarity LIMS User Passwords

The user passwords created at the Clarity LIMS level are for the admin, facility, and apiuser users.

admin and facility users:
- These users have no configuration associated with them.
- You may change their passwords at any time.
apiuser user:
- After installation of Clarity LIMS, you can change this password. However, you must also update it in the file/vault secret store, using the Secret Management Util.

To change the apiuser password after installing Clarity LIMS:

Check for any remote Automation Workers, and take note of their locations in your network. You will need to restart these after changing the password.
Log in to the server as the root user.
Stop Clarity LIMS using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh stop
```
Go to /opt/gls/clarity/tools/secretutil.
Update the password in the secret store
- For vault-based secret storage, use either the Vault command line interface (CLI) or Vault user interface (UI) to update the password.
- For file-based secret storage, use Secret Management Util to update the password as follows:
  $ java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar -n=integration -u="new-password" "apiusers/apiuser"
Start Clarity LIMS using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh start
```

Update Database Connection Details

In some circumstances (such as security breaches/compromises), the database connection details (eg, database password) are updated, which prevents Clarity LIMS from connecting to the database. You can correct this issue by updating Clarity LIMS with the new database connection details as follows.

Check for any remote Automation Workers.
Update the existing tenant with the new details.
Restart any Automation Workers.

To update database connection details:

Check for any remote Automation Workers, and take note of their locations in your network.
Log in to the server as the root user.
Stop Clarity LIMS using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh stop
```
Go to /opt/gls/clarity/tools/secretutil.
Update existing tenant with new details.
- For vault-based secret storage, use either the Vault CLI or Vault UI to update the password.
- For file-based secret storage, use the Secret Management Util to update the database password as the root user.
```
$ java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar -u="db-password" db.<db-name>.password
```
Start Clarity LIMS using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh start
```

Installation Procedure

This section provides instructions for installing on-premise or cloud hosted deployments of Clarity LIMS v6.2. For assistance with installation steps, contact the Clarity LIMS Support team.

This document provides the steps required to install a new Clarity LIMS v6.2 instance to Oracle Linux/RedHat Enterprise Linux v8.8 and v8.9.

Prerequisites

Your system meets the requirements listed in Technical Requirements.
You have installed and configured the required components. For more information, see Pre-Installation Requirements.
You have a database user and two empty schemas on your database server. The schemas are populated during configuration.
You have received the appropriate repository files from the Clarity LIMS Support team.
All standard OS security updates have been applied.
All instances of Clarity LIMS must have a purchased SSL/TLS certificate installed. Purchase the certificate before installation or upgrade. For instructions on installing purchased SSL/TLS certificates, see Install a Purchased SSL/TLS Certificate.

With the Oracle Linux/RedHat Enterprise Linux server, the following error messages can display when you perform the yum commands used to install Clarity LIMS:

Failed loading plugin "product-id": No module named 'urllib3'

Failed loading plugin "subscription-manager": No module named 'urllib3'

Failed loading plugin "upload-profile": No module named 'urllib3'

These messages do not affect the installation of Clarity LIMS. You can resolve these error messages by running the following command:

pip3 install urllib3==1.24.2

Step 1: Add the Clarity LIMS Repository

Using scp/sftp, WinSCP, FileZilla, PSCP, or similar, copy the repository to the following location: /etc/yum.repos.d.

Test the repo file with this command:

yum --enablerepo=GLS_Clarity62 search ClarityLIMS-App

Step 2: Install Clarity LIMS

Run the install command:

yum --enablerepo=GLS_Clarity62 install ClarityLIMS-App

Type y to download and install the Clarity LIMS RPM core components.
NOTE: The installation of Clarity LIMS creates 3 operating system users:
- glsai - User created to run the Automation Worker node
- glsftp - User to access the SFTP file store
- glsjboss - Runs the application server
These users are created by the RPM installation process, and should not be created before starting the installation steps. The user home directories are created in the directory /opt/gls/clarity/users
The operating system passwords for each of the above users should be set by the root user.

Step 3: Run Configuration Scripts

As the glsjboss user, change directory to /opt/gls/clarity/config/pending with the following command:
```
cd /opt/gls/clarity/config/pending
```
Run the first script listed sequentially in the directory listing with the following bash command:
```
bash /opt/gls/clarity/config/pending/05_configure_claritylims_secretutil.sh
```
This script configures the Secret Utility password management tool so that secrets and passwords are accessible. It is recommended that you store application secrets in vault. If that is not possible, the configuration script supports file-based storage. For more information about the prompts, see Guide to Secret Management.

Run the following script:

bash /opt/gls/clarity/config/pending/20_configure_claritylims_platform.sh

Run the next script to initialize the database and overwrite any existing data:
```
bash /opt/gls/clarity/config/pending/26_initialize_claritylims_tenant.sh
```
NOTE: This script requires that you enter the password for the glsftp user. Entering the password does not set the password for this user.
If your database server is standalone or remote, update the /opt/gls/clarity/tomcat/current/lib/activity-management-ui-config.groovy file with the following code snippet.
```
hibernate {
    isis {
        template {
            url="jdbc:postgresql://<Replace me: Remote DB IP>:<Replace me: Remote DB Port>/{0}"
        }
    }
}
```
NOTE: Substitute the Remote DB IP and Remote DB Port placeholders with the information for your server.
If you do not update the script, log and database connection errors can occur.
Change to the root user, and then run the following script in the sequence to configure RabbitMQ:
```
bash /opt/gls/clarity/config/pending/32_root_configure_rabbitmq.sh
```
As the root user, install the Apache proxy with the following script:
```
bash /opt/gls/clarity/config/pending/40_root_install_proxy.sh
```

Step 4: Install Lablink

LabLink v2.4 is compatible with Clarity LIMS v6.2.

Before installing LabLink v2.4, make sure that a database named LabLink is created with the same database user as the Clarity LIMS database.

Turn off all Clarity LIMS services using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh stop
```
Install the LabLink RPM with the following yum command. Make sure that you have the correct repo enabled:
```
yum --enablerepo=GLS_Clarity6 install ClarityLIMS-LabLink
```
As the glsjboss user, run the pending initialization script using the following command:
```
bash /opt/gls/clarity/config/pending/60_initialize_lablink.sh
```
Restart all Clarity LIMS services using the following command:
```
/opt/gls/clarity/bin/run_clarity.sh start
```
Make sure that LabLink is accessible at https://<your-Clarity-FQDN>/lablink

Step 5: Start the System

Run the following script as the root user:

/opt/gls/clarity/bin/run_clarity.sh (start|stop|restart)

If an error occurs starting any service, subsequent services will not be started. Stop all services before trying to start them again.

Start the system as follows.

Switch to the root user.
Make sure that no Clarity LIMS services are running.
Run the script with the following start command:
```
/opt/gls/clarity/bin/run_clarity.sh start
```
After the script has completed, all Clarity LIMS services should be ready for use.

If any services are running, the script exits and provides a list of services to stop. In this scenario, complete the following steps:

Use the script with stop command to stop services.
Open a supported browser window and make sure that you can access the Clarity LIMS client at the following URL: https://<your-Clarity-FQDN>/

Guide to Secret Management

Secret Utility (secretutil) is a password management tool used to store, manage, and retrieve passwords. Secret Utility returns the passwords in plain text.

The following sections describe the configuration of Secret Utility, which is installed as part of the Clarity LIMS-SecretUtil RPM.

Installing Integration Packages on Clarity LIMS

Integration Package

Clarity LIMS Version

Secret Util Mode

Installation Steps

Configuration Script

If Secret Utility has not been configured, the 05_configure_claritylims_secretutil.sh script is created in the /opt/gls/clarity/config/pending folder.

To reconfigure Secret Utility:

Remove the hidden file /opt/gls/clarity/tools/secretutil/.configured
Run the Secret Utility configuration script as follows: /opt/gls/clarity/config/configure_claritylims_secretutil.sh

The following table describes the entries prompted by the configure_claritylims_secretutil.sh script.

Configuration Script Entries

Prompts

Default

Description

Managing the passwords (Vault Mode)

If Secret Utility is configured as Vault Mode, the passwords are stored and retrieved from Vault Enterprise.

To use Secret Utility and perform the following steps, you must first remote into the instance before performing any of the following steps.
To use the Vault user interface (UI) and perform the following steps, you must have the appropriate role and access control list (ACL) policies.

Vault ACL Paths

The Vault ACLs control three main paths: Clarity, Integration, and Ops. If there is an attempt to write into a read-only path, secretutil.jar returns an error.

Clarity (read only)

Stores all passwords related to Clarity LIMS. The secrets/passwords are encrypted with CLARITYSECRET_ENCRYPTION_KEY env variable. See #claritylimsv6.2guidetosecretmanagement-configurationscript.

Integration (read write)

Stores all integration-related passwords and allows read and write access.
apiusers
- Stores passwords that are used by packages and applications for API authentication (eg, the apiuser password).
- Username is case sensitive.
- For example, retrieve apiuser password from integration/apiusers/apiuser.
external.file.stores
- Stores password of external file stores used by Clarity LIMS.
- External file store is optional to the Clarity LIMS system.
- For example, retrieve file store password from integration/external.file.stores/.password.

Ops

Stores secrets related to operations.
- For Illumina cloud hosted deployments, Illumina manages this path.
- This path is optional for on-premise customers.

Create a New Password

Using Secret Utility

The following command creates a new password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-h] [-n="namespace"] [-u="newValue"] "key"

When creating a new password for integration, specify the -n= integration option.
Make sure that the key uses a forward slash for nested secrets. For example, apiusers/apiuser
The same command is used for updating an existing password and creating a new password. Read the key you are planning to create to check whether it is an existing password.

Using Vault UI

Log in to the Vault UI.
Select the Key Value (KV) secret engine with the path instances.
Look for the FQDN instance that you want to create the password for.
Select the path where you want to create the new password, ie, clarity/integration/ops.
Select Create Secret +.
Under Path for this secret, enter the path for the new password, eg, app.ldap.managerPass.
Under Version data:
1. Enter 'value' into the key field.
2. Enter the new password into the value field.
Select Save.

Read an Existing Password

Using Secret Utility

Run the following command to create a new password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar "key"

Using Vault UI

Log in to the Vault UI.
Select the KV secret engine with the path instances.
Look for the FQDN instance that you want to create the password for.
Select the path where the existing password is located, ie, clarity/integration/ops.
Click into the secret and view the password by selecting the peek icon.

Update an Existing Password

Using Secret Utility

Run the following command to update an existing password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-h] [-n="namespace"] [-u="newValue"] "key"

Using Vault UI

Log in to the Vault UI.
Select the KV secret engine with the path instances.
Look for the FQDN instance that you want to create the password for.
Select the path where the existing password is located, ie, clarity/integration/ops.
Select into the secret.
Select Create new version +.
Under Version Data, enter the new password.
Select Save.

Delete an Existing Password

NOTE: Confirm with the Illumina Support team before deleting passwords and secrets.

Using Secret Utility

Secret Utility does not support permanent deletion of a key by design.

Using Vault UI

Log in to the Vault UI.
Select the KV secret engine with the path instances.
Look for the FQDN instance that you want to create the password for.
Select the path, ie, clarity/integration/ops, to the location of the existing password.
Select into the secret.
Select Delete secret.

Managing the Passwords (File Mode)

To manage the passwords and perform the following steps, you must first remote into the instance.

Create a New Password

Run the following command to create a new password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-h] [-n="namespace"] [-u="newValue"] "key"

If you are creating a new password for integration, specify the -n=integration option.
The same command is used for updating an existing password and creating a new password. Read the key you are planning to create to check whether it is an existing password.

Read an Existing Password

Run the following command to read an existing password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar "key"

Update an Existing Password

Run the following command to update an existing password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-h] [-n="namespace"] [-u="newValue"] "key"

Delete an Existing Password

NOTE: Confirm with the Illumina Support team before deleting passwords and secrets.

By design, Secret Utility does not support permanent deletion of a key. As an alternative, you can run the following steps.

Open the secrets.properties file with an editor, eg, vim.
Remove the key from the file and save the file.

Installation

Installation Procedure

Prerequisites

Step 1: Add the Clarity LIMS Repository

Step 2: Install Clarity LIMS

Step 3: Run Configuration Scripts

Step 4: Install Lablink

Step 5: Start the System

Guide to Secret Management

Installing Integration Packages on Clarity LIMS

Configuration Script

Configuration Script Entries

Managing the passwords (Vault Mode)

Managing the Passwords (File Mode)

Install/Upgrade Secret Management for Integration Modules

Change the Clarity LIMS Hostname

Prerequisites & considerations

Prerequisites

Considerations

Settings changed

Changing the LIMS hostname

Pre-script steps

Running the script

Update Server Passwords and Database Connection Details

Update Operating System User Passwords

To change the glsftp password after installing Clarity LIMS, using SecretUtil:

Update Clarity LIMS User Passwords

To change the apiuser password after installing Clarity LIMS**:**

Update Database Connection Details

Install/Upgrade Secret Management for Integration Modules

Update Server Passwords and Database Connection Details

Update Operating System User Passwords

To change the glsftp password after installing Clarity LIMS, using SecretUtil:

Update Clarity LIMS User Passwords

To change the apiuser password after installing Clarity LIMS**:**

Update Database Connection Details

Change the Clarity LIMS Hostname

Prerequisites & considerations

Prerequisites

Considerations

Settings changed

Changing the LIMS hostname

Pre-script steps

Running the script

Installation Procedure

Prerequisites

Step 1: Add the Clarity LIMS Repository

Step 2: Install Clarity LIMS

Step 3: Run Configuration Scripts

Step 4: Install Lablink

Step 5: Start the System

Guide to Secret Management

Installing Integration Packages on Clarity LIMS

Configuration Script

Configuration Script Entries

Managing the passwords (Vault Mode)

Managing the Passwords (File Mode)

To change the apiuser password after installing Clarity LIMS:

To change the apiuser password after installing Clarity LIMS: