--- title: Install Java RCS description: The Java RCS is supported on the following Java versions: component: openicf page_id: openicf:connector-reference:java-server canonical_url: https://docs.pingidentity.com/openicf/connector-reference/java-server.html section_ids: java-connector-server-unix: Install a Java RCS on Unix/Linux java-connector-server-windows: Install a Java RCS on Windows rcs-service: Run Java RCS as a service configure-rcs-service: Configure RCS as a service manage-rcs-service: Use systemctl commands to manage the RCS service --- # 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](rcs-docker.html). | ## Install a Java RCS on Unix/Linux 1. Download and extract the Java RCS from the [Backstage download site](https://backstage.forgerock.com/downloads). 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](configure-server.html#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)](configure-server.html). 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](https://backstage.forgerock.com/downloads). 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](configure-server.html#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)](configure-server.html). 4. You can either run the Java RCS as a Windows service or start and stop it from the command line. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you previously started the RCS using `/run`, the user account that entered the command owns the log files in `openicf\logs\`. When you install and start the RCS as a Windows service, the Windows service account doesn't have write access to those log files. The service starts without error but produces no log output.To avoid this issue, use one of the following workarounds before running `/install`:- Delete the `openicf\logs\` directory. The RCS recreates it with the correct permissions when the service starts. - In the Windows Services management console, open the RCS service properties, click the Log On tab, and select Local System Account. The Local System Account has broad local system privileges. For production deployments, grant the existing service account write access to openicf\logs\ instead. | 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: ```none sudo vim /etc/systemd/system/rcs.service ``` 2. Add the following content to this file, update the paths as needed, and save: ```ini [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: ```none sudo systemctl enable rcs.service ``` 4. Check the service is enabled: ```none 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: ```none sudo systemctl start rcs.service ``` * Stop the service: ```none sudo systemctl stop rcs.service ``` * Restart the service: ```none sudo systemctl restart rcs.service ``` * Check the service status: ```none 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.