ICF 1.5.20.32

Install Java RCS

The Java RCS is supported on the following Java versions:

Java version support
Java RCS version Supported Java version

1.5.20.22 and earlier

Java 11 or 17

1.5.20.23 through 1.5.20.31

Java 17

1.5.20.32 and later

Java 17 or 21

Disk space, memory, and CPU requirements depend on the number of connectors you’re using and the volume of traffic through the RCS.

You can also deploy Java RCS in a Docker container.

Install a Java RCS on Unix/Linux

  1. Download and extract the Java RCS from the BackStage download site.

  2. Change to the openicf directory:

    cd /path/to/openicf

  3. Review the ConnectorServer.properties file in the /path/to/openicf/conf directory, and adjust it to suit your deployment. For a complete list of properties in that file, refer to RCS Properties.

    • In server mode, the RCS uses a connectorserver.key property to authenticate the connection. The default value of the key is a hashed value of the string changeit. You cannot set this property directly in the configuration file. To change its value, use the command ConnectorServer.sh /setKey. This example sets the key value to Passw0rd:

      /path/to/openicf/bin/ConnectorServer.sh /setKey Passw0rd
Key has been successfully updated.

      In client mode, this isn’t necessary and can be skipped. Learn more about the differences between client mode and server mode in Configure a remote connector server (RCS).

  4. Start the Java RCS:

    /path/to/openicf/bin/ConnectorServer.sh /run

    By default, the RCS is now running and listening on port 8759.

    Log files are available in the /path/to/openicf/logs directory.

    ls logs/
Connector.log  ConnectorServer.log  ConnectorServerTrace.log

  5. To stop the Java RCS, press CTRL+C or q in the terminal where you started the server.

Install a Java RCS on Windows

  1. Download and extract the Java RCS from the BackStage download site.

  2. In a Command Prompt window, change to the openicf directory:

    C:\> cd C:\path\to\openicf

  3. Review the ConnectorServer.properties file in the \path\to\openicf\conf directory, and adjust it to suit your deployment. For a complete list of properties in that file, refer to RCS Properties.

    • In server mode, the RCS uses a connectorserver.key property to authenticate the connection. The default value of the key is a hashed value of the string changeit. You cannot set this property directly in the configuration file. To change its value, use the ConnectorServer.bat /setKey command. This example sets the key value to Passw0rd:

      c:\path\to\openicf> bin\ConnectorServer.bat /setKey Passw0rd
Key has been successfully updated.

      If you use an exclamation mark (!) with the ConnectorServer.bat /setKey command, you must escape the character according to your Windows Server version:

      • For Windows Server 2012 R2, escape the character with double quotes:

        ConnectorServer.bat /setKey "changeit"!""

      • For Windows Server 2016 and later, escape the character with a caret (^):

        ConnectorServer.bat /setKey changeit^!

      In client mode, this isn’t necessary and can be skipped. Learn more about the differences between client mode and server mode in Configure a remote connector server (RCS).

  4. You can either run the Java RCS as a Windows service or start and stop it from the command line.

    1. To install the Java RCS as a Windows service, run the following command:

      c:\path\to\openicf> bin\ConnectorServer.bat /install

      If you install the RCS as a Windows service, you can use the Microsoft Services console to start, stop, and restart the service. The Java Connector Service is named OpenICFConnectorServerJava.

      To uninstall the Java RCS as a Windows service, run the following command:

      c:\path\to\openicf> bin\ConnectorServer.bat /uninstall

    2. To start the Java RCS from the command line, enter the following command:

      c:\path\to\openicf> bin\ConnectorServer.bat /run

  5. The RCS is now running, and listening on port 8759, by default.

    Log files are available in the \path\to\openicf\logs directory.

  6. To stop the Java RCS, press CTRL+C.

Run Java RCS as a service

The Java RCS can run as a service on a standard systemd-based Linux distribution. Once you have configured the RCS as a service, you can stop and start the RCS using systemd.

Configure RCS as a service

  1. Create a service file using your preferred text editor:

    sudo vim /etc/systemd/system/rcs.service

  2. Add the following content to this file, update the paths as needed, and save:

    [Unit]
SourcePath=/path/to/openicf/bin
Description=Remote Connector Server (systemd init)
After=network.target
Conflicts=shutdown.target

[Service]
Type=simple
Restart=always
RestartSec=5sec
IgnoreSIGPIPE=no
KillMode=process
Environment="OPENICF_OPTS=-Xmx1024m"
ExecStart=/path/to/openicf/bin/ConnectorServer.sh /start

[Install]
WantedBy=multi-user.target

  3. Make the new service launch on startup:

    sudo systemctl enable rcs.service

  4. Check the service is enabled:

    systemctl is-enabled rcs.service

    This command returns enabled or disabled as appropriate.

Use systemctl commands to manage the RCS service

Once you’ve configured RCS as a service and checked it’s enabled, use systemctl commands to manage the RCS service:

  • Start the service:

    sudo systemctl start rcs.service

  • Stop the service:

    sudo systemctl stop rcs.service

  • Restart the service:

    sudo systemctl restart rcs.service

  • Check the service status:

    sudo systemctl status rcs.service

    This command returns the service state (whether the service has started or stopped as expected) and the first few entries of the RCS log file.