<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<sect1 id="configuration">
	<title>Configuration</title>
	<para>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  <emphasis role="italic"
			>Configuration</emphasis> menu. </para>
		<note>To apply changes you need to restart RCE.</note>
	<para>The format of the configuration file is JSON. See <ulink url="http://www.json.org/"><emphasis role="underline"
	>http://www.json.org/</emphasis></ulink> for the format definition. Also refer to
	the example configuration files in the installation data directory.
	</para>
	<sect2>
		<title>Configuration Locations and Files</title>
		<para>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 (<phrase os="windows"
				>"C:\users\&lt;user id>\" on Windows</phrase><phrase os="linux">"/home/&lt;user
				id>/" on Linux</phrase>), in the ".rce/default" sub-folder.<note>
				<para>Note that ".rce" is a hidden directory; you may need to set operating-specific
					options to see hidden files and directories.</para>
			</note></para>
		<para>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.</para>
	</sect2>
	<sect2>
		<title>Configuration Parameters</title>
		<para>Configuration parameters are grouped within the configuration file. The configuration
			parameters are listed below. There is one list per JSON configuration group. Some
			example snippets are given as well. The complete example configurations can be found in
			the installation data directory in the sub-directory <emphasis role="italic"
				>examples/configuration</emphasis> or by opening the configuration information in
			RCE.</para>
		<table width="100%">
			<title>"general"</title>
			<tgroup cols="3">
				<colspec colnum="1" colwidth="1*"/>
				<colspec colnum="2" colwidth="2*"/>
				<colspec colnum="3" colwidth=".5*" align="left"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Configuration key </emphasis></entry>
						<entry>
							<emphasis role="italic">Comment </emphasis></entry>
						<entry>
							<emphasis role="italic">Default value </emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>instanceName</entry>
						<entry>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:<itemizedlist>
								<listitem>
									<para>${hostName} is resolved to the local system's host
										name.</para>
								</listitem>
								<listitem>
									<para>${systemUser} is resolved to the user account name.</para>
								</listitem>
								<listitem>
									<para>${profileName} is resolved to the last part of the current
										profile's file system path.</para>
								</listitem>
								<listitem>
									<para>${version} is resolved to the build id.</para>
								</listitem>
								<listitem>
									<para>${javaVersion} is resolved to the JRE version
										number.</para>
								</listitem>
							</itemizedlist><para>Example: "Default instance started by
								\"${systemUser}\" on ${hostName}".</para></entry>
						<entry>"&lt;unnamed instance>"</entry>
					</row>
					<row>
						<entry>isWorkflowHost </entry>
						<entry>If set to <emphasis role="italic">true</emphasis>, the local instance
							can be used as a <emphasis role="italic">workflow host</emphasis> by
							other RCE instances. I.e., the workflow controller can be set to this
							instance and the workflow data is stored there as well.</entry>
						<entry>false</entry>
					</row>
					<row>
						<entry>isRelay</entry>
						<entry>
							<para>If set to <emphasis>true</emphasis>, 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.</para>
							<para>If set to <emphasis>false</emphasis> (the default value), the
								local node can connect to multiple networks at once without causing
								them to merge.</para>
						</entry>
						<entry>false</entry>
					</row>
					<row>
						<entry>tempDirectory </entry>
						<entry>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 <emphasis role="italic"
								>${systemUser}</emphasis> can be used for path construction, e.g.
							"/tmp/custom-temp-directory/${systemUser}"</entry>
						<entry>An "rce-temp" subdirectory within the user or system temp
							directory.</entry>
					</row>
					<row>
						<entry>enableDeprecatedInputTab </entry>
						<entry>If set to <emphasis>true</emphasis> 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.</entry>
						<entry>false</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<table width="100%">
			<title>"backgroundMonitoring"</title>
			<tgroup cols="3">
				<colspec colnum="1" colwidth="1*"/>
				<colspec colnum="2" colwidth="2*"/>
				<colspec colnum="3" colwidth="0.5*" align="left"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Configuration key </emphasis></entry>
						<entry>
							<emphasis role="italic">Comment </emphasis></entry>
						<entry>
							<emphasis role="italic">Default value </emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>enabledIds</entry>
						<entry>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.</entry>
						<entry/>
					</row>
					<row>
						<entry>intervalSeconds</entry>
						<entry>Logging interval</entry>
						<entry>10</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<table frame="all" width="100%">
			<title>"network"</title>
			<tgroup cols="3">
				<colspec colnum="1" colwidth="1*"/>
				<colspec colnum="2" colwidth="2*"/>
				<colspec colnum="3" colwidth="0.5*" align="left"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Configuration key </emphasis></entry>
						<entry>
							<emphasis role="italic">Comment </emphasis></entry>
						<entry>
							<emphasis role="italic">Default value </emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>requestTimeoutMsec</entry>
						<entry>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.</entry>
						<entry>40000</entry>
					</row>
					<row>
						<entry>forwardingTimeout Msec</entry>
						<entry>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.</entry>
						<entry>35000</entry>
					</row>
					<row>
						<entry>connections</entry>
						<entry>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.</entry>
						<entry>{} (an empty map in JSON format)</entry>
					</row>
					<row>
						<entry>connections/[id]/host</entry>
						<entry>IP address of the host to connect to. Host names and IPv4 addresses
							are permitted.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>connections/[id]/port</entry>
						<entry>Port number of the remote RCE instance.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>connections/[id]/connectOnStartup</entry>
						<entry>If set to <emphasis role="italic">true</emphasis>, the connection is
							immediately established on startup.</entry>
						<entry>true</entry>
					</row>
					<row>
						<entry>connections/[id]/autoRetryInitialDelay</entry>
						<entry>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.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>connections/[id]/autoRetryDelayMultiplier</entry>
						<entry>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.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>connections/[id]/autoRetryMaximumDelay</entry>
						<entry>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.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>serverPorts </entry>
						<entry>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.</entry>
						<entry>{} (an empty map in JSON format)</entry>
					</row>
					<row>
						<entry>serverPorts/[id]/ip</entry>
						<entry>IP address to which the local instance should be bound.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>serverPorts/[id]/port</entry>
						<entry>Port number to which other instances connect to.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>ipFilter </entry>
						<entry>Allows to limit the incoming connections to a set of IP
							addresses.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>ipFilter/enabled </entry>
						<entry>If set to <emphasis role="italic">true</emphasis>, the ip filter
							active.</entry>
						<entry>false</entry>
					</row>
					<row>
						<entry>ipFilter/allowedIPs</entry>
						<entry>List of IP addresses, which are allowed to connect to the
							instance.</entry>
						<entry>[] (an empty list in JSON format)</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<note>
			<para>IMPORTANT: When setting up a network of RCE instances, keep in mind that the RCE
				network traffic is currently <emphasis>not encrypted</emphasis>. This means that it
				is <emphasis>not secure</emphasis> 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 an uplink connection in RCE
				instead of the standard RCE connections.</para>
		</note>
		<para>Network Server Sample:
			<programlisting>"network" : {
		"serverPorts" : {
			"relayPort1" : {
				"ip" : "127.0.0.1",
				"port" : 21000
			}
		}, 
		"ipFilter" : {
			"enabled" : false,
			"allowedIPs" : [
				"127.0.0.1",
				"127.0.0.2"
			]
		}
	}
	</programlisting></para>
		<para>Network Client
			Sample:<programlisting>"network" : {
		"connections" : {
			"exampleConnection1" : {
				"host" : "127.0.0.1",
				"port" : 21000,
				"connectOnStartup": false,
				"autoRetryInitialDelay" : 5,
				"autoRetryMaximumDelay" : 300,
				"autoRetryDelayMultiplier" : 1.5
			}
		}
	}</programlisting></para>
		<table width="100%">
			<title>"componentSettings"</title>
			<tgroup cols="3">
				<colspec colnum="1" colwidth="1*"/>
				<colspec colnum="2" colwidth="2*"/>
				<colspec colnum="3" colwidth="0.5*" align="left"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Configuration key </emphasis></entry>
						<entry>
							<emphasis role="italic">Comment </emphasis></entry>
						<entry>
							<emphasis role="italic">Default value </emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry><![CDATA[de.rcenvironment.                cluster]]></entry>
						<entry>Configuration of the cluster workflow component.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry><![CDATA[de.rcenvironment.               cluster/maxChannels]]></entry>
						<entry>Maximum number of channels, which are allowed to be opened in
							parallel to the cluster server.</entry>
						<entry>8</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<table width="100%">
			<title>"thirdPartyIntegration"</title>
			<tgroup cols="3">
				<colspec colnum="1" colwidth="1*"/>
				<colspec colnum="2" colwidth="2*"/>
				<colspec colnum="3" colwidth="0.5*" align="left"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Configuration key </emphasis></entry>
						<entry>
							<emphasis role="italic">Comment </emphasis></entry>
						<entry>
							<emphasis role="italic">Default value </emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>tiglViewer</entry>
						<entry>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.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>tiglViewer/binaryPath</entry>
						<entry>The path to the TiGL Viewer executable file. Must be an absolute
							path.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>tiglViewer/startupTimeoutSeconds</entry>
						<entry>The timeout in seconds, to wait for the external TiGL viewer
							application to start and determine its process id.</entry>
						<entry>10</entry>
					</row>
					<row>
						<entry>tiglViewer/embedWindow</entry>
						<entry>If set to <emphasis role="italic">false</emphasis>, the external TiGL
							Viewer application Window will not be embeded into RCE´s TiGL Viewer
							view.</entry>
						<entry>true</entry>
					</row>
					<row>
						<entry>python</entry>
						<entry>Configuration of a external Python installation. This needs to be configured to enable
							Python script language for the Script Component. Note: Python must be
							downloaded and installed separately.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>python/binaryPath</entry>
						<entry>The path to a local python installation. This needs to be configured to enable Python
							script language for the Script Component</entry>
						<entry>-</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<para> </para>
		<para>Third Party integration Python path example:
			<programlisting>"thirdPartyIntegration": {
			"python":{
			"binaryPath": "/path/to/python/executable"
					}
			}
		</programlisting></para>
		<table width="100%">
			<title>"sshServer"</title>
			<tgroup cols="3">
				<colspec colnum="1" colwidth="1.02*"/>
				<colspec colnum="2" colwidth="2.06*"/>
				<colspec colnum="3" colwidth="0.5*" align="left"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Configuration key </emphasis></entry>
						<entry>
							<emphasis role="italic">Comment </emphasis></entry>
						<entry>
							<emphasis role="italic">Default value </emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>enabled</entry>
						<entry>If set to <emphasis role="italic">true</emphasis> the local instance
							acts as an SSH server.</entry>
						<entry>false</entry>
					</row>
					<row>
						<entry>ip <emphasis>(deprecated alias: "host")</emphasis></entry>
						<entry>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.</entry>
						<entry>127.0.0.1</entry>
					</row>
					<row>
						<entry>port</entry>
						<entry>The port number to which SSH clients can connect to.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>idleTimeoutSeconds</entry>
						<entry>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.</entry>
						<entry>10</entry>
					</row>
					<row>
						<entry>accounts</entry>
						<entry>A map of accounts. For each account a unique identifier (account
							name) must be given.</entry>
						<entry>{} (an empty map in JSON format)</entry>
					</row>
					<row>
						<entry>[account name]/passwordHash</entry>
						<entry>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.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>[account name]/password <emphasis role="italic"
								>(deprecated)</emphasis></entry>
						<entry>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
								<emphasis>must</emphasis> be secured against unauthorized reading
							(e.g. by setting restrictive filesystem permissions). A more secure
							alternative is to just store the password hash.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>[account name]/publicKey</entry>
						<entry>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.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>[account name]/role</entry>
						<entry>The role of the account. See next table for a list of the possible
							roles.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>[account name]/enabled</entry>
						<entry>If set to <emphasis role="italic">true</emphasis>, the account is
							enabled.</entry>
						<entry>true</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<para> SSH Server
			Sample:<programlisting>"sshServer" : {
		"enabled" : true,
		"ip" : "127.0.0.1",
		"port" : 31005,
		"accounts" : {
			"ra_demo" : {
				// hashed form of the "ra_demo" test password; DO NOT reuse this for live accounts!
				"passwordHash" : "$2a$10$qxCBuEvq0xWoOlox2dVbCu8zCYsyxQMBe5SAnS2HId0uaEp59aAu2",
				"role" : "remote_access_user",
				"enabled" : true
			}
		}
	}</programlisting></para>
		<table width="100%" id="table_ssh_roles">
			<title>Possible roles for SSH accounts</title>
			<tgroup cols="2">
				<colspec colnum="1" colwidth="1.3*"/>
				<colspec colnum="2" colwidth="2*"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Role name</emphasis></entry>
						<entry>
							<emphasis role="italic">Allowed commands</emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>uplink_client (Standard role for using Uplink connections)</entry>
						<entry>Cannot open a command shell or run any commands</entry>
					</row>
					<row>
						<entry>remote_access_user (Standard role for using SSH remote access tools
							and workflows)</entry>
						<entry>ra|sysmon (can use Uplink connections)</entry>
					</row>
					<row>
						<entry>remote access (backwards compatibility alias for
							remote_access_user)</entry>
						<entry>ra|sysmon (can use Uplink connections)</entry>
					</row>
					<row>
						<entry>remote_access_admin</entry>
						<entry>ra|ra-admin|sysmon|components</entry>
					</row>
					<row>
						<entry>workflow_observer</entry>
						<entry>components|net info|sysmon|wf list|wf details</entry>
					</row>
					<row>
						<entry>workflow_admin</entry>
						<entry>components|net info|sysmon|wf</entry>
					</row>
					<row>
						<entry>local_admin</entry>
						<entry>cn|components|mail|net|restart|shutdown|stop|stats|tasks|auth</entry>
					</row>
					<row>
						<entry>instance_management_admin</entry>
						<entry>im|net info|auth</entry>
					</row>
					<row>
						<entry>instance_management_delegate_user</entry>
						<entry>cn|components|net|restart|shutdown|stop|stats|tasks|wf|ra-admin|auth</entry>
					</row>
					<row>
						<entry>developer</entry>
						<entry>&lt;all></entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<table width="100%">
			<title>"uplink"</title>
			<tgroup cols="3">
				<colspec colnum="1" colwidth="1*"/>
				<colspec colnum="2" colwidth="2*"/>
				<colspec colnum="3" colwidth="0.5*" align="left"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Configuration key </emphasis></entry>
						<entry>
							<emphasis role="italic">Comment </emphasis></entry>
						<entry>
							<emphasis role="italic">Default value </emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>uplinkConnections</entry>
						<entry>A map of Uplink connections.This allows the local instance to act as
							an Uplink client. For each connection a unique identifier (id) must be
							given. </entry>
						<entry>{} (an empty map in JSON format)</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/displayName </entry>
						<entry>The name for the connection that will be shown in the network
							view.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/host </entry>
						<entry>The remote RCE instance (Uplink relay) to connect to. Host names and
							IPv4 addresses are permitted.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/port</entry>
						<entry>Port number of the remote RCE instance.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/loginName</entry>
						<entry>The login name for authentication.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/keyfileLocation</entry>
						<entry>Path to the private key file, if keyfile authentication is used. Only
							RSA keys in the OpenSSH format are supported.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/noPassphrase</entry>
						<entry>This option should only be set if a private key that requires no
							passphrase is used for authentication. If set to <emphasis role="italic"
								>true</emphasis>, RCE does not ask for a passphrase before
							connecting.</entry>
						<entry>false</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/clientID</entry>
						<entry>If other RCE instances use the same account to connect to the relay,
							you have to set a unique client ID here (max. 8 characters)</entry>
						<entry>default</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/isGateway</entry>
						<entry>If set to <emphasis role="italic">true</emphasis>, this instance will
							act as an Uplink gateway (see chapter <xref linkend="uplink-connections"
							/> for further information)</entry>
						<entry>false</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/connectOnStartup</entry>
						<entry>If set to <emphasis role="italic">true</emphasis>, the connection is
							immediately established on startup. (Only possible when the password is
							stored.)</entry>
						<entry>false</entry>
					</row>
					<row>
						<entry>uplinkConnections/[id]/autoRetry</entry>
						<entry>If set to <emphasis role="italic">true</emphasis>, RCE will try to
							automatically reconnect the connection (every 5 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.) </entry>
						<entry>false</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<para> Uplink Connection
			Sample:<programlisting>"uplink" : {
		"uplinkConnections" : {
			"exampleUplinkConnectionID" : {
				"displayName" : "example",
				"clientID": "client1",
				"host" : "127.0.0.1",
				"port" : 31005,
				"connectOnStartup": false,
				"autoRetry" : false,
				"isGateway" : false,
				"loginName" : "ra_demo"
				//The passphrase is not stored here, it has to be entered when connecting.
			}
		}
	}</programlisting></para>
		<table width="100%">
			<title>"sshRemoteAccess"</title>
			<tgroup cols="3">
				<colspec colnum="1" colwidth="1*"/>
				<colspec colnum="2" colwidth="2*"/>
				<colspec colnum="3" colwidth="0.5*" align="left"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Configuration key </emphasis></entry>
						<entry>
							<emphasis role="italic">Comment </emphasis></entry>
						<entry>
							<emphasis role="italic">Default value </emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>sshConnections</entry>
						<entry>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. </entry>
						<entry>{} (an empty map in JSON format)</entry>
					</row>
					<row>
						<entry>sshConnections/[id]/displayName </entry>
						<entry>The name for the connection that will be shown in the network
							view.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>sshConnections/[id]/host </entry>
						<entry>The remote RCE instance to connect to. Host names and IPv4 addresses
							are permitted.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>sshConnections/[id]/port</entry>
						<entry>Port number of the remote RCE instance.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>sshConnections/[id]/loginName</entry>
						<entry>The login name for authentication.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>sshConnections/[id]/keyfileLocation</entry>
						<entry>Path to the private key file, if keyfile authentication is used. Only
							RSA keys in the OpenSSH format are supported.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>sshConnections/[id]/noPassphrase</entry>
						<entry>This option should only be set if a private key that requires no
							passphrase is used for authentication. If set to <emphasis role="italic"
								>true</emphasis>, RCE does not ask for a passphrase before
							connecting.</entry>
						<entry>false</entry>
					</row>
					<row>
						<entry>sshConnections/[id]/connectOnStartup</entry>
						<entry>If set to <emphasis role="italic">true</emphasis>, the connection is
							immediately established on startup. (Only possible when the password is
							stored in the secure store.)</entry>
						<entry>false</entry>
					</row>
					<row>
						<entry>sshConnections/[id]/autoRetry</entry>
						<entry>If set to <emphasis role="italic">true</emphasis>, 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.) </entry>
						<entry>false</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<para> Remote Access Connection Sample
			<programlisting>"sshRemoteAccess" : {
				"sshConnections" : {
					"exampleSSHConnection" : {
						"displayName" : "example",
						"host" : "127.0.0.1",
						"port" : 31005,
						"connectOnStartup": false,
						"autoRetry" : false,
						"loginName" : "ra_demo"
						//The passphrase is not stored here, it has to be entered when connecting.
					}
				}
			}</programlisting>
		</para>
		<table width="100%" id="smtpServerParameterTable">
			<title>"smtpServer"</title>
			<tgroup cols="3">
				<colspec colnum="1" colwidth="1*"/>
				<colspec colnum="2" colwidth="2*"/>
				<colspec colnum="3" colwidth="0.5*"/>
				<thead>
					<row>
						<entry><emphasis role="italic">Configuration key </emphasis></entry>
						<entry>
							<emphasis role="italic">Comment </emphasis></entry>
						<entry>
							<emphasis role="italic">Default value </emphasis></entry>
					</row>
				</thead>
				<tbody>
					<row>
						<entry>host</entry>
						<entry>The IP address or hostname of the SMTP server, which should be used
							for mail delivery. </entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>port</entry>
						<entry>Port number of the SMTP server.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>encryption</entry>
						<entry>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.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>username</entry>
						<entry>The login name for authentication.</entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>password</entry>
						<entry>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 <xref
								linkend="configuration_ui"/></entry>
						<entry>-</entry>
					</row>
					<row>
						<entry>sender</entry>
						<entry>Email address, which should be displayed as the sender in the sent
							email.</entry>
						<entry>-</entry>
					</row>
				</tbody>
			</tgroup>
		</table>
		<note>
			<para>The used SMTP server needs to be configured using the Configuration UI described
				in <xref linkend="configuration_ui_smtp"/>, since the password needs to be
				obfuscated.</para>
		</note>
	</sect2>
	<sect2 id="configuration_ui">
		<title>Configuration UI</title>		
		<para>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. </para>
		
		
		<figure>
			<title>Configuration tool for SSH account and SMTP server configuration</title>
			<mediaobject>
				<imageobject>
					<imagedata fileref="images/configUI.PNG" contentwidth="420"/>
				</imageobject>
			</mediaobject>
		</figure>

		<sect3>
			<title>Remote Access: SSH account configuration</title>		
		
			<para>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.</para>
		
			<note>
				<para>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 <xref linkend="table_ssh_roles"/>
					). </para>
			</note>
		</sect3>
		<sect3 id="configuration_ui_smtp">
			<title>Mail: SMTP server configuration</title>		
			
			<para>If you use the tool output verification (cf. <xref linkend="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 <xref linkend="smtpServerParameterTable"/>
			</para>
			<note>
				<para>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". </para>
			</note>
		</sect3>

	</sect2>
	<sect2>
		<title><anchor id="authdata-import"/>Importing authorization data without GUI access</title>
		<para>There are currently two categories of authorization data that should not be simply written
			into configuration files for security reasons: SSH login passwords and keyfile
			passphrases, and RCE authorization group keys (the "export/import" strings). To support
			scenarios where interactive entry is not possible, for example daemon/service
			installations, a file-based import mechanism is provided as well.</para>
		<para>The general usage is the same for all kinds of import data:<itemizedlist>
				<listitem>
					<para>Locate the folder of the profile that you want to import into.</para>
				</listitem>
				<listitem>
					<para>If it does not exist yet, create a folder "<code>import</code>" within
						that profile directory.</para>
				</listitem>
				<listitem>
					<para>Within this "<code>import</code>" folder, create the sub-folder mentioned in the specific
						description below; for example, "<code>auth-group-keys</code>".</para>
				</listitem>
				<listitem>
					<para>To perform an import, create a file inside this specific sub-folder and
						edit it, or copy a file that you already prepared into that folder. These
						files are referred to as "import files". The filenames and contents to use
						for them are described in the specific sections below.</para>
				</listitem>
				<listitem>
					<para>Once you have created or copied all import files that you want to
						processs, (re)start RCE. Currently, all import file processing is done on
						startup. (Note: Future versions of RCE may be expanded to also detect and
						process new import files without a restart.)</para>
				</listitem>
				<listitem>
					<para>If a file has been successfully imported, it is
							<emphasis>deleted</emphasis> to minimize the time that it is present in
						the filesystem (for security), and to prevent it from being processed again
						on every RCE start. Make sure that this file is not the only reference to
						the authorization data that you have!</para>
				</listitem>
			</itemizedlist></para>
		<sect3>
			<title>Importing or deleting RCE authorization group keys</title>
			<para>This section focusses on importing or deleting <emphasis role="italic">already
					defined</emphasis> authorization groups via their group keys. Creating groups is
				explained in <xref linkend="publishing_authorization"/>. </para>
			<para>	
				<itemizedlist>
					<listitem>
						<para>Group key import files must be placed in
								<code>&lt;profile>/import/auth-group-keys/</code> .</para>
					</listitem>
					<listitem>
						<para>For group keys, the import files can have any name. For each key you wish to import a
							single file is required.</para>
					</listitem>
					<listitem>
						<para>The import file's content must be the group import string; it should
							look similar to
								"<code>MyGroupName:23b0ad9043a39496:1:1K6D5C9BKYu[...]sSMLlj0Tg</code>".</para>
					</listitem>
					<listitem>
						<para>Deleting groups is also supported. To delete a group, write "<code>delete</code>" into
							the file, followed by the full id (name + random part) of the group you
							want to delete. For convenience, you can also use the full import string
							as used above. For example, if you wanted to delete the group mentioned
							above, either of these contents would work:<itemizedlist>
								<listitem>
									<para>"<code>delete MyGroupName:23b0ad9043a39496</code>"</para>
								</listitem>
								<listitem>
									<para>"<code>delete
											MyGroupName:23b0ad9043a39496:1:1K6D5C9BKYu[...]sSMLlj0Tg</code>"</para>
								</listitem>
							</itemizedlist></para>
					</listitem>
					<listitem>
						<para>After successful import or deletion of a group key, the file is deleted from the profile folder.</para>
					</listitem>
				</itemizedlist>
			</para>
		</sect3>
		<sect3>
			<title>Importing SSH Uplink passwords or keyfile passphrases</title>
			<itemizedlist>
				<listitem>
					<para>Uplink password/passphrase import files must be placed in
							<code>&lt;profile>/import/uplink-pws/</code> .</para>
				</listitem>
				<listitem>
					<para>The names of the import files are relevant: These must be the "connection id" used in the
						Uplink connection configuration. This id is the string right in front of the
						the part outside of the connection's configuration block (e.g.
							<code>"myConnection" : { ...&lt;connection settings>... }</code>). For
						convenience on Windows, a ".txt" extension can be added to this filename;
						this will be cut away by the importer.</para>
				</listitem>
				<listitem>
					<para>The content of the files is the password or keyfile passphrase.</para>
				</listitem>
				<listitem>
					<para>As this is never actually needed, deleting passwords is not directly
						supported. If you have imported a password/passphrase you would rather
						remove from RCE's secure storage, simply import a dummy password for the
						same connection id. This will overwrite and erase the previous data.</para>
				</listitem>
			</itemizedlist>
		</sect3>
		<sect3>
			<title>Importing SSH Remote Access passwords or keyfile passphrases</title>
			<itemizedlist>
				<listitem>
					<para>Uplink password/passphrase import files must be placed in
							<code>&lt;profile>/import/ra-pws/</code> .</para>
				</listitem>
				<listitem>
					<para>The names of the import files are relevant: These must be the "connection id" used in the
						Remote Access connection configuration. This id is the string right in front
						of the the part outside of the connection's configuration block (e.g.
							<code>"myConnection" : { ...&lt;connection settings>... }</code>). For
						convenience on Windows, a ".txt" extension can be added to this filename;
						this will be cut away by the importer.</para>
				</listitem>
				<listitem>
					<para>The content of the files is the password or keyfile passphrase.</para>
				</listitem>
				<listitem>
					<para>As this is never actually needed, deleting passwords is not directly
						supported. If you have imported a password/passphrase you would rather
						remove from RCE's secure storage, simply import a dummy password for the
						same connection id. This will overwrite and erase the previous data.</para>
				</listitem>
			</itemizedlist>
		</sect3>
	</sect2>
</sect1>
