Windows installation

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

In this topic:

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.

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 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 server node installation - Windows

For a multi-server node configuration, you install 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.

To install a Connect server node:

1. Run the installation .exe file and choose the second option, a 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 Connect was installed.

4. Open the Services console, select the Connect Web Server service, and click the Start button.

   Note: Make sure that the database server is running before you start the 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 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 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 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 Connect server with JVM options that specify a keystore with the 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 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 Connect and its connectors, to benefit from the added capabilities and enhanced stability.

To upgrade to the latest version:

1. Download the latest version of 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 Connect Web Server again.
5. Zip and backup the entire Connect folder as a safety measure.
6. Launch and run the 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 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 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 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 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. Go 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 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 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. Go 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 Connect Web Server service.
12. Log in and start the connections.

Back to top

Next steps:

• Install connectors
• Servers tab
• Create a data source
• User maps and user matching
• Create and manage connections
• Log in to Connect