Linux upgrade

This topic describes how to upgrade an existing installation on Linux.

Note: Connect for Linux is distributed as a tgz/tar.gz bundle, but not in a Linux package manager format such as RPM or DEB. Therefore, installation, uninstallation, and upgrades require manual intervention. Only attempt these actions if you have extensive knowledge in Linux.

Important note before upgrading to 25.2

Starting with version 25.2, Connect exclusively supports only PostgreSQL as the database. Derby is officially deprecated.

Database installation, upgrade, and management are the responsibility of the administrator.

For details, see PostgreSQL database.

Back to top

If you are currently using a version earlier than 25.1

You can only upgrade to version 25.2 from 25.1.

If you are running a version older than 25.1, download and install Connect 25.1, and then start it at least once to enable the necessary database upgrades.

After the above steps are done, run the following command to verify that the current Derby database is ready for upgrade:

  1. Go to the Connect installation path (.../MicroFocusConnect).

  2. Execute the following command:

    sudo ./jre/bin/java -jar ./Utilities/mfcMaintenance.jar -basePath . -dbValidate -dbValidateVersion

Back to top

Upgrade overview

This section guides you through the steps for upgrading to a later version of the product. We recommend using the latest version of Connect and its connectors, to benefit from the added capabilities and enhanced stability.

It is important to understand that upgrading to version 25.2 requires migrating from Derby to PostgreSQL. Follow the steps below carefully to ensure proper migration and upgrade.

Note: If you are upgrading from a prior version that uses a separate database deployment, contact support for upgrade guidance. The separate database deployment option has been deprecated until further notice.

Back to top

Upgrade step 1: Before database migration

  1. Download Connect Core for Linux from the AppDelivery Marketplace.
  2. Download the latest version of the relevant connectors from AppDelivery Marketplace.
  3. Download all connector dependencies as specified in the connector Readme files. The Readme files are included in the download packages.

  4. Stop any connections that are running in the existing installation to prevent data loss.

  5. Stop the Connect web server:

    sudo systemctl stop connect

  6. Stop the Derby database service:

    sudo systemctl stop connect-database

  7. Go to the directory where Connect is installed. Zip and back up the entire Connect folder:

    tar -czvf mfconnect-backup.tar.gz MicroFocusConnect/

  8. Go to the Connect directory:

    cd MicroFocusConnect

  9. Uninstall the Connect web server:

    sudo ./uninstall_service.sh

  10. Uninstall the Derby database service:

    sudo ./uninstall_database_service.sh

  11. Go to the parent directory:

    cd ..

  12. Remove the Connect files:

    rm -rf MicroFocusConnect/

  13. Create a folder for the Connect installation, and unpack the files from the downloaded archive:

    tar -xvf mfconnect-linux-<build>.tar.gz

  14. Copy the downloaded relevant connectors with dependencies to the AppData/connectors directory.

  15. Restore required configuration files from the backup copy:

    rm -rf ./previous-connect

    mkdir previous-connect

    tar -xf mfconnect-backup.tar.gz -C ./previous-connect

  16. If you have modified the Connect environment in the file ./previous-connect/MicroFocusConnect/WebServer/bin/setenv.sh, merge the modifications into the newly installed setenv.sh file.

  17. Copy Derby database files and node properties:

    cp -r ./previous-connect/MicroFocusConnect/AppData/data/* ./MicroFocusConnect/AppData/data

  18. Copy the sso configuration files:

    cp -r ./previous-connect/MicroFocusConnect/AppData/osp-server-configuration/* ./MicroFocusConnect/AppData/osp-server-configuration/

    cp ./previous-connect/MicroFocusConnect/AppData/osp-filter-configuration.properties ./MicroFocusConnect/AppData/

  19. If you have modified logging configuration files (for example log4j2.xml), merge the modifications into the newly installed configuration file. The files are installed together with Connect.

    Caution: Do not copy older configuration files and replace new configuration files with them, as this overwrites new version configurations.

  20. If you have modified utility scripts (for example the .bat or .sh files), merge the modifications into the newly installed utilities. The utilities are installed together with Connect.

    Caution: Do not copy over or merge older .jar files back into the new (upgraded) installation files.

  21. If you have installed security certificates, copy the certificates from the backup and replace cacerts in <install path>/Connect/jre/lib:

    cp ./previous-connect/MicroFocusConnect/jre/lib/security/cacerts ./MicroFocusConnect/jre/lib/security/

  22. If you changed the running port or are using https/ssl, copy the server.xml file from the backup, and use it to replace server.xml in <install path>/Connect/WebServer/conf:

    cp ./previous-connect/MicroFocusConnect/WebServer/conf/server.xml ./MicroFocusConnect/WebServer/conf/

  23. Change the directory to the deployment folder:

    cd MicroFocusConnect

  24. Run the Derby database configuration:

    ./configure_database_server.sh

  25. Install the Derby database service:

    sudo ./install_database_service.sh

  26. Edit the connect_database.env file located in the MicroFocusConnect/ directory. Choose one of the following two options:

    (Option 1) Connect to an existing database:

    1. Manually create the database in advance. For more information, refer to Create database manually.

    2. Update the connection parameters in the file to match the manually created database.

    3. Ignore the DEFAULT_ADMIN_USER, DEFAULT_ADMIN_PASSWORD, DEFAULT_ADMIN_DATABASE parameters.

    (Option 2) Create a new database using an admin user:

    1. Provide the DEFAULT_ADMIN_USER, DEFAULT_ADMIN_PASSWORD, DEFAULT_ADMIN_DATABASE parameters to establish the required admin session.

    2. Update the desired target connection settings in the file accordingly. We will then proceed to create the database using these settings.

  27. Run one of the following commands to start the Derby service:

    sudo systemctl start connect-database

    sudo systemctl enable connect-database

  28. Prepare the database. Run the prepare_database.sh script:

    ./prepare_database.sh

  29. Using the sudo user, deploy the Connect service:

    sudo ./install_service.sh

Back to top

Upgrade step 2: Database migration

  1. Prepare for migration:

    1. During database migration, we recommend having available 24 GB of RAM, and 5 times the Derby database size as storage.

      To check the Derby database size, verify the size of the AppData/data folder where the Derby database is located.

    2. If a previous migration attempt failed, or you need to re-run the process, execute the mfcMigrateDataToPostgres script with the -force argument.

  2. Perform the migration:

    1. To perform the database migration, run the utility script mfcMigrateDataToPostgres. See Batch utility scripts for more information.

    2. To troubleshoot a migration failure, check the DerbyToPostgresMigration.log file in AppData/logs folder.

  3. Clean up migration files:

    Once you see that Connect runs successfully after migration, you can clean up the migration-related log and metadata files. These are located in the derby_to_postgres_migration directory in the <Connect Installation location>\AppData directory. This can be permanently deleted.

  4. If migration fails, check the following:

    • Disk space. If you don't have the required disk space available (5 times the Derby database size), migration will fail. To resolve this issue, make sure you have enough disk space available, as described in the migration logs.

    • Insufficient RAM. In rare situations, 24 GB of RAM is not enough to migrate. Make sure that you have more available RAM space on the system.

      To start the migration with more than 24 GB RAM, modify the mfcMigrateDataToPostgres utility script. For example, to set it to 32 GB RAM, search for -Xmx24G and replace it with -Xmx32G.

Back to top

Upgrade step 3: After database migration

  1. Start the Connect service with one of the following commands:

    sudo systemctl start connect

    sudo systemctl enable connect

  2. To verify the installation, check the service's status:

    sudo systemctl status connect

    Wait for the system to return an Active status.

  3. To secure the database, refer to PostgreSQL database.

  4. Log into Connect using the URL and the credentials provided to you. For example, log in using the URL http://my_server:8081/ConnectWeb/index.html.

  5. Delete the Derby service:

    sudo systemctl stop connect-database

  6. Uninstall the Derby database service:

    sudo ./uninstall_database_service.sh

See also: