Windows installation

This topic describes how to perform an installation of Micro Focus Connect on Windows and how to upgrade an existing installation. Make sure to review the planning documents described in Basics.

Installation types

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

  • Standalone (single-node) installation. This option performs a full standalone installation of the Micro Focus 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 Micro Focus 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

For all installation types, perform the following steps before you install the product:

  1. Check the Support Matrix.
  2. Download Micro Focus Connect Core for Windows from the AppDelivery Marketplace.
  3. Extract the installer file from the downloaded archive, mfconnect-<version-OS_Info>.exe. Double click the installer .exe file.

Back to top

Perform a full Windows installation

This section describes how to perform an on-premises installation.

To install the product:

  1. On the Installation's opening page, choose Full installation. Click Next to move through the installation wizard.
  2. In the wizard's Database Connection Options page, keep the default database's Host Name value, localhost.

  3. Wait for the Install Complete screen indicating that the Micro Focus Connect and database services were installed.
  4. For multi-server node installations only: Set the database to an open connection:

    1. Stop the database service: Open the Services console, select the Micro Focus Connect DB Server service, and click Stop.

    2. Open the <Connect_Installation>/Database/bin folder, and run the database setup, ConnectDBServer.exe. The Server Properties dialog box opens.

    3. In the Java tab's Java Options section, locate the -Derby.drda.host=127.0.0.1 entry and enter the relevant private network IP in place of the local host. For details, see the Derby documentation. Click Apply and OK to save the changes.

    4. Start the DB service: Open the Services console, select the Micro Focus Connect DB Server service, and click Start.
    5. Secure the database. For details, see Install SSL certificates.

  5. Open the Windows Services app, select the Micro Focus Connect Web Server service, and click the Start button.

  6. Go to the URL provided to you, and log in with your credentials.

  7. For multi-server node installations only: Open the Servers tab to view a list of the servers that are installed, using the same database.

Note: If you performed a full installation of Micro Focus Connect, and you want to move the database to another server, first back up the entire data folder and modify the database properties file accordingly. Alternatively, use Derby's import/export utility. For details, see Migrate to a new machine. After you have a backup, uninstall Micro Focus Connect. Reinstall the product in multi-server mode, and then perform a separate database installation, as described below.

Back to top

Perform a server node installation - Windows

For a multi-server node configuration, you install Micro Focus Connect server nodes that access an existing database. Before installing a server node, make sure that you have a database installed, either through a full installation with the multi-server capability enabled, or through a standalone database installation. For details, see Perform a full Windows installation and Windows installation.

Note: When performing a multi-server installation, make sure that all server node machines and the database machine are set to the same time zone.

To install a Micro Focus Connect server node:

  1. Run the installation .exe file and choose the second option, a Micro Focus Connect server node only installation. Click Next to move through the installation wizard.
  2. In the wizard's Database Connection Options page, change the database's Host Name to the name of the database machine—do not keep the default value, localhost.

    Note: If you receive a warning indicating that the database connection properties are not valid, ignore it. You will fix those properties in a post-installation step.

  3. Wait for the Install Complete screen that indicates that Micro Focus Connect was installed.
  4. Open the Services console, select the Micro Focus Connect Web Server service, and click the Start button.

    Note: Make sure that the database server is running before you start the Micro Focus Connect server.

  5. Go to the URL provided to you, and log in with your credentials.

  6. Open the Servers tab to see a list of the servers that are installed, using the same database.

Back to top

Secure the connection to the database server

For a multi-server node configurations, you can secure the connection from the Micro Focus Connect server to the Derby database server with encryption and two-way authentication.

The Derby server and client can operate in two SSL modes: basic or peerAuthentication. Basic mode only provides communication encryption. The peerAuthentication mode also verifies that the other side is trustworthy.

If the server operates in peerAuthentication mode, the client must have a keystore containing keys that the server trusts.

To secure your connection with the Apache Derby database:

  1. Obtain a Derby Server SSL/TLS key and certificate.
  2. Configure the SSL/TLS for the Derby database and run it in basic mode. For details, refer to the Configuring SSL/TLS and Starting the server with SSL/TLS sections in the Derby security guide.

  3. Configure the security properties for the connection from the Micro Focus Connect server to Derby server in the AppData/data/database.properties config file.

    • For basic mode, set the ssl.mode property to basic.

    • For peerAuthentication mode, set the ssl.mode property to peerAuthentication (strongly recommended).

  4. If the Micro Focus Connect server is set to peerAuthentication mode, it must be configured with a trust relationship with the Derby server SSL certificate. For details, see the Install SSL certificates.

  5. If the Derby server is set to start in peerAuthentication mode, perform the following steps:

    1. Obtain a server key for the connection to the Derby server.

    2. Run the Micro Focus Connect server with JVM options that specify a keystore with the Micro Focus Connect server key, for connection with the Derby server:

      -Djavax.net.ssl.keyStore=/path/to/KeyStore and -Djavax.net.ssl.keyStorePassword=KeyStorePassword

    3. Add a trust relationship between the Derby server and the Micro Focus Connect server in one of the following ways:

      • Add a certificate for the key, to connect to the Derby server on the system level.

      • Run the Derby server with the JVM options that specify a trust store with a certificate for the key, to connect to the Derby server:
        -Djavax.net.ssl.trustStore=/path/to/TrustStore and
        -Djavax.net.ssl.trustStorePassword=TrustStorePassword

    For more information, refer to the Starting the server with SSL/TLS section in the Derby security guide.

Back to top

Upgrades

This section guides you through the steps for upgrading to a later version of the product.

We recommend using the latest version of Micro Focus 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 the latest version of Micro Focus Connect Core from 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 the Micro Focus Connect Web Server again.
  5. Zip and backup the entire Connect folder as a safety measure.
  6. Launch and run the Micro Focus Connect installer of the new version.
  7. When complete, copy the relevant connectors with their dependencies into the AppData/Connectors folder.
  8. 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 Micro Focus Connect.

    Caution: Do not copy over or merge older .jar files back into the new/upgraded install.

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

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

  11. Open the Services console and start the Micro Focus Connect Web Server service.

  12. We recommend running the Purge script on a regular basis. Use Windows Task Scheduler to set up a nightly run of the utility at a convenient time. For details, see Purge files on Windows as a nightly task.
  13. Log in, click the Info button, and select About. Verify that all builds and connectors match the latest version that you installed.
  14. Start up the connections, one connection at a time. Verify that each connection is running correctly before starting the next one.

Back to top

Increase maximum allocated memory

A standard installation is configured to run with 8 GB of memory. As the number of connections and usage grow, you may require more memory.

The following procedure describes how to increase the Tomcat maximum allocated memory on Windows deployments.

To increase the allocated memory:

  1. Open a command prompt window as an administrator in the <MFConnect_installdir>\WebServer\bin folder.
  2. Run the command tomcat9w.exe //ES/ConnectWebServer. This launches the Web Server Properties dialog box.
  3. Select the Java tab.
  4. In the Maximum memory pool box, change the value to reflect a reasonable percentage of the available memory on the machine. For example, on a 16 GB machine change the value to 12288 MB (12 GB). On a 32 GB machine, change the value to 28672 MB (28 GB).
  5. Click OK.

Back to top

Set the locale to English

To run synchronizations, you must configure your operating system to the US English locale.

The following procedure describes how to set the locale to US English on a Windows machine. This applies to both new installations and upgrades.

To set the locale to English:

  1. Open a command prompt window as an administrator in the <MFConnect_installdir>\WebServer\bin folder.
  2. Run the command tomcat9w.exe //ES/ConnectWebServer. This launches the Micro Focus Connect Web Server Properties dialog box.
  3. Select the Java tab.
  4. Append the following to the bottom of the Java settings area. Add them to the upper area—not the bottom Java 9 Options area:

    -Duser.language=EN

    -Duser.country=US

  5. Select the General tab.

  6. Click Stop to stop the service.

  7. Click Start to restart the service.

  8. Click OK.

Back to top

Migrate to a new machine

This section describes how to migrate an installation to a new machine.

On the source machine:

  1. Stop all running connections.
  2. Run C:\Program Files\Micro Focus\Connect\Utilities\mfcpurge.bat as an administrator.
  3. Open services.msc and stop the Micro Focus Connect Web Server service.
  4. Right click the service and click Properties. Select Disabled and click OK. This prevents simultaneous writing to endpoints from two instances.
  5. Compress C:\Program Files\Micro Focus\Connect\AppData and all its contents into a zip file.
  6. Open a command prompt as an Administrator and run <MFConnect_installdir>\WebServer\bin\tomcat9w.exe //ES/ConnectWebServer
  7. Navigate to the Java tab. Copy all of the contents in the Java Options section and paste into a text file. Save the file.
  8. Note the value of the Maximum Memory Pool.
  9. Back up <MFConnect_installdir>\jre\bin\security\cacerts.
  10. Refer to the server.xml file to see if your connection was set up to be secure. If you had made modifications to secure Micro Focus Connect with SSL, then back up <MFConnect_installdir>\WebServer\conf\server.xml and all certificate files that were in use.
  11. Back up the contents of <MFConnect_installdir>\war.

On the target machine:

  1. Download and install the same build of Micro Focus Connect used on the source server.
  2. Copy the files you saved from the source machine to the target machine.
  3. Delete the <MFConnect_installdir>\AppData folder and replace it with the copy from the source machine.
  4. Open a command prompt as an Administrator and run <MFConnect_installdir>\WebServer\bin\tomcat9w.exe //ES/ConnectWebServer
  5. Navigate to the Java tab.
  6. Paste of the contents of the Java Options box that you saved to a text file above (step 7), into the Java Options section. Make sure to paste them into the Java Options section and not the Java 9 Options section.
  7. If the target machine has the same memory installed as the source machine, adjust the Maximum Memory Pool to match the source's value. If the machine has less memory, request that it be increased. If the machine has more memory than the source machine, it can be increased further. Check the Task Manager on the target machine to see how much memory is available on the machine.
  8. Overwrite <MFConnect_installdir>\jre\bin\security\cacerts with the source machine version, from step 9 above.
  9. If you have an SSL Secured deployment, overwrite <MFConnect_installdir>\WebServer\conf\server.xml with the copy from the source machine in step 10. If you saved any certificate files, copy them over too.
  10. Overwrite the contents of <MFConnect_installdir>\war with the files saved from the source machine in step 11 above.
  11. Open services.msc and start the Micro Focus Connect Web Server service.
  12. Log in and start the connections.

Back to top

Next steps: