Linux installation

This topic describes how to install Connect on a Linux machine.

You can install Connect to run as a background service, which is the standard installation, or as a standalone application, commonly used when trying out the product.

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.

Installation types

Beginning with version 4.5, for on-premises deployments, you can install Connect as a standalone installation or a multi-node installation.

  • Standalone (single-node) installation. This option performs a full standalone installation of the Connect service and the database service on same machine. This type of installation does not allow other machines to access the database.

  • Multi-node installation. This option allows you to install Connect on multiple machines, all accessing the same database.

Note: We strongly recommend deploying the product in a single node configuration. The use of multi-server nodes may significantly affect efficiency and performance in certain synchronization scenarios.

Back to top

Before you install Connect

For all installation types, perform the following before you install the product on a Linux machine:

  1. Check the Support Matrix to make sure that your environment is supported.
  2. Install the haveged and rngd services which are needed for installation:

    sudo yum install haveged

    sudo systemctl start haveged

    sudo systemctl enable haveged

    sudo yum install rng-tools

    sudo systemctl start rngd

    sudo systemctl enable rngd

    Note: In the context of cryptography, entropy is related to random number generation. On Linux systems in virtual environments, calls to /dev/random are limited by the availability of entropy in the system. Without the proper level of entropy, the initial Connect start may be blocked because Connect generates OSP keyfiles on start, and requires random key data for these purposes. The haveged and rngd services increase the system's entropy.

  3. Create a unique user and group for Connect services.

  4. Provide sudo permissions to the Connect user for the following commands:

    <install-dir>/MicroFocusConnect/install_database_service.sh

    <install-dir>/MicroFocusConnect/install_service.sh

    systemctl enable connect-database

    systemctl disable connect-database

    systemctl start connect-database

    systemctl stop connect-database

    systemctl enable connect

    systemctl disable connect

    systemctl start connect

    systemctl stop connect

  5. Ensure that you use this user to install, upgrade, and uninstall Connect.

    Caution: To maintain security, do not use the root account as the account to install, upgrade and uninstall Connect.

  6. Ensure that all files in the Connect installation directory have this user and group.

  7. Download Connect Core for Linux from the AppDelivery Marketplace.
  8. Create a folder for the Connect installation, and unpack the files from the downloaded archive:

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

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

  9. If you are upgrading an existing installation, stop any connections that are running in the existing installation, to prevent data loss.

Tip: For an overview of system resource utilization and other installation considerations, see Windows installation. Instead of the Windows Task Scheduler, use cron jobs to schedule your tasks.

Back to top

Perform a full Linux installation

This section describes how to perform a full standalone installation of Connect on a Linux machine.

To perform a full installation:

  1. For multi-server node installations only: Set the database to an open connection:

    1. Change the directory to the <MFConnect_installdir>/Database/bin folder.

    2. Open the setenv file and change the value of the derby.drda.host system variable from 127.0.0.1 to the relevant private network. For details, see the Derby documentation.

  2. Change the directory to the deployment folder:

    cd MicroFocusConnect

  3. Run the database configuration:

    ./configure_database_server.sh

  4. Install the Derby database service:

    sudo ./install_database_service.sh

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

    sudo systemctl start connect-database

    sudo systemctl enable connect-database

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

    ./prepare_database.sh

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

    sudo ./install_service.sh

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

    sudo systemctl start connect

    sudo systemctl enable connect

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

    sudo systemctl status connect

    Wait for the system to return an Active status.

  10. Secure the database. For details, see Install SSL certificates.

  11. Using the URL, for example, http://my_server:8081/ConnectWeb/index.html and the credentials provided to you, log into Connect.

Back to top

Perform a server node installation - Linux

For multi-node installations, you install Connect server nodes on multiple Linux machines, accessing an existing database. Before installing a server node, make sure that you have a database installed through a standalone database installation. For details, see Perform a full Linux installation.

To install a server node:

  1. Go to the deployment directory:

    cd MicroFocusConnect

  2. Prepare the database:

    1. Edit the connect_database.env file and change the default host value to the name of the database machine. Do not keep the default value, localhost.

    2. Run the prepare_database.sh script.

      ./prepare_database.sh

  3. Remove extraneous example folders. The content of these folders may interfere with Connect.

    1. Stop the tomcat server.

      sudo systemctl stop connect

    2. Delete the webserver\webapps\examples folder and if present, the webserver\work\Catalina\localhost\examples folder.

    3. Restart the tomcat server.

      sudo systemctl start connect

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

    sudo ./install_service.sh

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

    sudo systemctl start connect

    sudo systemctl enable connect

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

    sudo systemctl status connect

    Wait for the system to return an Active status.

  7. Using the URL, for example, http://my_server:8081/ConnectWeb/index.html and the credentials provided to you, log into Connect.

  8. Open the Servers tab to view a list of the server nodes.

Back to top

Install as a standalone application

You can install Connect as an application only, and not as a service that runs continuously in the background.

This option is useful if you are trying out Connect.

Run the following commands:

cd MicroFocusConnect/WebServer/bin/

./startup.sh

Back to top

Upgrade

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.

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.

To upgrade to the latest version:

  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 database connection parameters:

    cp ./previous-connect/MicroFocusConnect/connect_database.env ./MicroFocusConnect/

  18. Copy database files and node properties:

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

  19. Copy logging and sso configuration files:

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

  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 database configuration:

    ./configure_database_server.sh

  25. Install the Derby database service:

    sudo ./install_database_service.sh

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

    sudo systemctl start connect-database

    sudo systemctl enable connect-database

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

    ./prepare_database.sh

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

    sudo ./install_service.sh

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

    sudo systemctl start connect

    sudo systemctl enable connect

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

    sudo systemctl status connect

    Wait for the system to return an Active status.

  31. Secure the database. For details, see Install SSL certificates.

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

Back to top

Stop and uninstall Connect

Use the following commands to stop or uninstall Connect:

Action Command
Stop the Connect service sudo systemctl stop connect
Stop the Derby database service sudo systemctl stop connect-database
Disable the Connect service auto-start sudo systemctl disable connect
Disable the Derby database service auto-start sudo systemctl disable connect-database
Uninstall the Connect service sudo ./uninstall_service.sh
Uninstall the Derby database service sudo ./uninstall_database_service.sh
Remove the Connect files rm -rf MicroFocusConnect/

Back to top

Increase maximum allocated memory in Linux

The following procedure describes how to increase maximum allocated memory for Tomcat on Linux deployments.

To increase the maximum allocated memory:

  1. Locate the file setenv.sh in the /MicroFocusConnect/WebServer/bin directory.
  2. Open the file and modify the value for -Xmx in JAVA_OPTS parameters.
  3. Restart the Connect service.

Back to top

Next steps: