This section describes the configuration of RCE. Configuration is done within one single configuration file. It is located in the profile directory. From the graphical user interface, you can easily access it from the tool bar or the Help menu. Note: To apply changes you need to restart RCE. The format of the configuration file is JSON. See http://www.json.org/ for the format definition. Also refer to the example configuration files in the installation data directory.
Starting with RCE 6.0.0, all user data is strictly separated from the RCE installation itself. Each set of user data is contained in a so-called "profile". Each profile defines what is called an RCE "instance". Each profile (and therefore, each instance) belongs to exactly one user, and each user can have multiple profiles. The default profile is located within the user's "home" directory ("C:\users\<user id>\" on Windows), in the ".rce/default" sub-folder.
Note
Note that ".rce" is a hidden directory; you may need to set operating-specific options to see hidden files and directories.
All manual configuration takes place in the profile's central configuration file, "configuration.json". As of RCE 9.0.0, most configuration settings only take effect on startup, so you need to restart RCE after editing it. (This will be changed in a future release.) This applies to all types of installations.
Configuration parameters are grouped within the configuration file. Below are lists of the configuration parameters. There is one list per JSON configuration group. You can find example configurations in "configuration_reference_sample" in the installation data directory or by opening the configuration information in RCE.
Table 2.1. "general"
| Configuration key | Comment | Default value |
|---|---|---|
| instanceName | The name of the instance that will be shown to all users in the RCE
network. The following placeholders can be used within the instance name:
Example: "Default instance started by \"${systemUser}\" on ${hostName}". | "<unnamed instance>" |
| isWorkflowHost | If set to true, the local instance can be used as a workflow host by other RCE instances. I.e., the workflow controller can be set to this instance and the workflow data is stored there as well. | false |
| isRelay |
If set to true, the local node will merge all connected nodes into a single network, and forward messages between them. This behaviour is transitive; if a relay node connects to another relay node, both networks will effectively merge into one. If set to false (the default value), the local node can connect to multiple networks at once without causing them to merge. | false |
| tempDirectory | Can be used to override the default path where RCE stores temporary files. Useful if there is little space in the default temp file location. Must be an absolute path to an existing directory, and the path must not contain spaces (to prevent problems with tools accessing such directories). The placeholder ${systemUser} can be used for path construction, e.g. "/tmp/custom-temp-directory/${systemUser}" | An "rce-temp" subdirectory within the user or system temp directory. |
| enableDeprecatedInputTab | If set to true the tab 'Inputs' is enabled again in the properties view of running workflows. It is disabled by default due to robustness and memory issues. It is recommended to use the 'Workflow Data Browser' to see inputs received and outputs sent. | false |
Table 2.2. "backgroundMonitoring"
| Configuration key | Comment | Default value |
|---|---|---|
| enabledIds | Comma-separated list of identifiers referring to certain kind of monitoring data that should be logged continuously in the background. Currently, only 'basic_system_data' is supported. | |
| intervalSeconds | Logging interval | 10 |
Note
IMPORTANT: When setting up a network of RCE instances, keep in mind that the RCE network traffic is currently not encrypted. This means that it is not secure to expose RCE server ports to untrusted networks like the internet. When setting up RCE connections between different locations, make sure that they either connect across a secure network (e.g. your institution's internal network), or that the connection is secured by other means, like SSH tunneling or a VPN. Alternatively, you can set up SSH connections in RCE instead of the standard RCE connections.
Table 2.3. "network"
| Configuration key | Comment | Default value |
|---|---|---|
| requestTimeoutMsec | The timeout (in milliseconds) for network requests that are made by the local node. If this time expires before a response is received, the request fails. | 40000 |
| forwardingTimeout Msec | The timeout (in milliseconds) for network requests that are forwarded by the local node on behalf of another node. If this time expires before a response is received, an error response is sent back to the node that made the request. | 35000 |
| connections | A map of all connections that the local instance tries to establish on startup. This allows the local instance to act as a client. For each connection a unique identifier (id) must be given. | {} (an empty map in JSON format) |
| connections/[id]/host | IP address of the host to connect to. Host names and IPv4 addresses are permitted. | - |
| connections/[id]/port | Port number of the remote RCE instance. | - |
| connections/[id]/connectOnStartup | If set to true, the connection is immediately established on startup. | true |
| connections/[id]/autoRetryInitialDelay | The initial delay, in seconds, to wait after a failed or broken connection before a reconnect attempt is made. This configuration must be present to enable the auto-reconnect feature. | - |
| connections/[id]/autoRetryDelayMultiplier | A decimal-point value >= 1 that the delay time is multiplied with after each consecutive connection failure. This provides an "exponential backoff" feature that reduces the frequency of connection attempts over time. This configuration must be present to enable the auto-reconnect feature. | - |
| connections/[id]/autoRetryMaximumDelay | Defines an upper limit for the delay time, even when applying the multiplier would create a higher value. This can be used to maintain a minimum frequency for retrying the connection. This configuration must be present to enable the auto-reconnect feature. | - |
| serverPorts | A map of all server ports that the local instance registers for other instances to connect to. This allows the local instance to act as a server. For each server port a unique identifier (id) must be given. | {} (an empty map in JSON format) |
| serverPorts/[id]/ip | IP address to which the local instance should be bound. | - |
| serverPorts/[id]/port | Port number to which other instances connect to. | - |
| ipFilter | Allows to limit the incoming connections to a set of IP addresses. | - |
| ipFilter/enabled | If set to true, the ip filter active. | false |
| ipFilter/allowedIPs | List of IP addresses, which are allowed to connect to the instance. | [] (an empty list in JSON format) |
Table 2.4. "componentSettings"
| Configuration key | Comment | Default value |
|---|---|---|
| de.rcenvironment. cluster | Configuration of the cluster workflow component. | - |
| de.rcenvironment. cluster/maxChannels | Maximum number of channels, which are allowed to be opened in parallel to the cluster server. | 8 |
Table 2.5. "thirdPartyIntegration"
| Configuration key | Comment | Default value |
|---|---|---|
| tiglViewer | Configuration of the external TiGL Viewer application integration. This needs to be configured to enable RCE´s TiGL Viewer view and thus, the TiGL Viewer workflow component. Note:TiGL Viewer must be downloaded and installed separately. | - |
| tiglViewer/binaryPath | The path to the TiGL Viewer executable file. Must be an absolute path. | - |
| tiglViewer/startupTimeoutSeconds | The timeout in seconds, to wait for the external TiGL viewer application to start and determine its process id. | 10 |
| tiglViewer/embedWindow | If set to false, the external TiGL Viewer application Window will not be embeded into RCE´s TiGL Viewer view. | true |
Table 2.6. "sshServer"
| Configuration key | Comment | Default value |
|---|---|---|
| enabled | If set to true the local instance acts as an SSH server. | false |
| ip (deprecated alias: "host") | The host's ip address to bind to. If you want to make the SSH server accessible from remote, you should set this to the IP of the machine's external network interface. Alternatively, you can set this to "0.0.0.0" to listen on all available IPv4 addresses, if this is appropriate in your network setup. | 127.0.0.1 |
| port | The port number to which SSH clients can connect to. | - |
| idleTimeoutSeconds | The time to keep an idle SSH connection alive, in seconds. For typical SSH usage, the default value is usually sufficient. Higher values are, for example, needed when invoking long-running tools using the SSH Remote Access feature. | 10 |
| accounts | A map of accounts. For each account a unique identifier (account name) must be given. | {} (an empty map in JSON format) |
| [account name]/passwordHash | The hashed password for the account, if password authentication is used. If the SSH account is configured using the configuration UI, the hash is automatically computed and stored here. | - |
| [account name]/password (deprecated) | The password for the account. SSH passwords can also be configured as plain text, which is however not recommended. To prevent misuse of the configured login data, any configuration file with SSH accounts must be secured against unauthorized reading (e.g. by setting restrictive filesystem permissions). A more secure alternative is to just store the password hash. | - |
| [account name]/publicKey | The public key for the account, if keyfile authentication is used. Only RSA keys in the OpenSSH format are supported. The public key has to be entered here in the OpenSSH format (a string starting with "ssh-rsa", like it is used for example in authorized_keys files). Only applicable on RCE version 7.1 or newer. | - |
| [account name]/role | The role of the account. See next table for a list of the possible roles. | - |
| [account name]/enabled | If set to true, the account is enabled. | true |
Table 2.7. Possible roles for SSH accounts
| Role name | Allowed commands |
|---|---|
| remote_access_user (Standard role for using SSH remote access tools and workflows) | ra|sysmon |
| remote access (backwards compatibility alias for remote_access_user) | ra|sysmon |
| remote_access_admin | ra|ra-admin|sysmon|components |
| workflow_observer | components|net info|sysmon|wf list|wf details |
| workflow_admin | components|net info|sysmon|wf |
| local_admin | cn|components|mail|net|restart|shutdown|stop|stats|tasks|auth |
| instance_management_admin | im|net info|auth |
| instance_management_delegate_user | cn|components|net|restart|shutdown|stop|stats|tasks|wf|ra-admin|auth |
| developer | <all> |
Note
The command wf open is only accessible to the role developer, as it influences the GUI of the server-instance.
Table 2.8. "sshRemoteAccess"
| Configuration key | Comment | Default value |
|---|---|---|
| sshConnections | A map of SSH connections.This allows the local instance to act as a SSH remote access client. For each connection a unique identifier (id) must be given. | {} (an empty map in JSON format) |
| sshConnections/[id]/displayName | The name for the connection that will be shown in the network view. | - |
| sshConnections/[id]/host | The remote RCE instance to connect to. Host names and IPv4 addresses are permitted. | - |
| sshConnections/[id]/port | Port number of the remote RCE instance. | - |
| sshConnections/[id]/loginName | The login name for authentication. | - |
| sshConnections/[id]/keyfileLocation | Path to the private key file, if keyfile authentication is used. Only RSA keys in the OpenSSH format are supported. | - |
| sshConnections/[id]/noPassphrase | This option should only be set if a private key that requires no passphrase is used for authentication. If set to true, RCE does not ask for a passphrase before connecting. | false |
| sshConnections/[id]/connectOnStartup | If set to true, the connection is immediately established on startup. (Only possible when the password is stored in the secure store, which currently only works on Windows machines.) | false |
| sshConnections/[id]/autoRetry | If set to true, RCE will try to automatically reconnect the connection (every 10 seconds) if it can not be established or is lost of a network error. (Only possible when the password is stored in the secure store, which currently only works on Windows machines.) | false |
Table 2.9. "smtpServer"
| Configuration key | Comment | Default value |
|---|---|---|
| host | The IP address or hostname of the SMTP server, which should be used for mail delivery. | - |
| port | Port number of the SMTP server. | - |
| encryption | Can either be "explicit" or "implicit". Select "implicit" if you want to connect to the SMTP server using SSL/TLS. Select "explicit" if you want to connect to the SMTP server using STARTTLS. Unencrypted connections are not permitted. | - |
| username | The login name for authentication. | - |
| password | The obfuscated password for authentication. Plaintext password cannot be used here. To create the obfuscated password from the plaintext password, you need to use the Configuration UI described in Section 2.2.3, “Configuration UI” | - |
| sender | Email address, which should be displayed as the sender in the sent email. | - |
Note
The used SMTP server needs to be configured using the Configuration UI described in Section 2.2.3.2, “Mail: SMTP server configuration”, since the password needs to be obfuscated.
If you want to configure SSH accounts with passphrases or you want to configure e-mail support for the instance, you need to use the Configuration UI. You can access the interactive tool by executing RCE from the command line with the option "rce --configure" or by using the "Launch Configuration UI" script in the "extras" folder of your RCE installation directory.
If the RCE instance shall act as a SSH server, you can configure SSH accounts using the Configuration UI, which encrypts the SSH passwords before storing them in the configuration file.
Note
All SSH accounts configured with this tool initially have the role "remote_access_user", which allows to execute commands needed for remote access on tools and workflows. If you want to change the role of an SSH account, you can do this by editing the configuration file manually (see Table 2.7, “Possible roles for SSH accounts” ).
If you use the tool output verification (cf. Section 3.2.8, “Manual Tool Result Verification”) and want RCE to send the verification key via email, you need to configure an SMTP server. RCE does not send e-mails directly to the recipient, but instead sends the e-mails to an SMTP server, which delivers them to the recipient. You need to use the Configuration UI to configure such an SMTP server, since the password used for authentication needs to be obfuscated before it is stored in the configuration file. The SMTP server parameters that need to be configured are described in more detail in Table 2.9, “"smtpServer"”
Note
Due to a known bug on Windows system with a German keyboard layout, the Configuration UI inserts the characters "q@" into a text field if you want to insert the @ sign. You can manually remove the additional character "q".