<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section id="configuration">
	<title>Configuration and Profiles</title>
	<para>Each instance of RCE reads its configurations from the <emphasis>profile
		directory</emphasis>, or <emphasis>profile</emphasis> for short. In this document, if the
		distinction is irrelevant or clear from context, we use these terms interchangeably. On
			<phrase os="windows">Windows</phrase><phrase os="linux">Linux</phrase> systems, the
		profile is, by default, located in the <emphasis>main RCE directory</emphasis>
		<phrase os="windows"><code>C:\Users\&lt;username>\.rce\default</code></phrase><phrase
			os="linux"><code>~/.rce/default</code>, where <code>~</code> denotes the path to your
			home directory. Normally, this is <code>/home/&lt;username>/</code></phrase>.</para>
	<para>If this directory or any of its parent directories do not exist, RCE creates them at first
		startup and populates them with a default configuration. RCE creates the directory
			<code>.rce</code> as a hidden directory. Thus, you will have to enable the display of
		hidden directories in order to see that directory.</para>
	<section id="profile_directory">
		<title>Choosing the Profile Directory</title>
		<para>Since RCE uses the profile directory to load its configuration at startup, it is not
			possible to change the profile directory at runtime. Instead, when running RCE via the
			commandline, you can use the commandline switch <code>-p</code> to change the profile at
			startup. Currently, there is no way to select the profile via the graphical interface of
			RCE.</para>
		<para>You can temporarily (i.e., for a single execution of RCE) change the profile directory
			by supplying its path as a parameter for the commandline switch <code>-p</code>. If you
			supply a relative path (i.e., one not starting with <phrase os="windows"
					><code>C:\</code> or some other drive name</phrase><phrase os="linux"
					><code>/</code></phrase>), RCE resolves that path relative to its main
			directory, i.e., to <phrase os="windows"
				><code>C:\Users\&lt;username>\.rce</code></phrase><phrase os="linux"
					><code>~/.rce</code></phrase>. If you supply an absolute path, RCE treats that
			path as the path to its profile directory.<note>
				<para>You can change the path to which RCE resolves relative profile directories by
					editing the file rce.ini in the main folder of your RCE installation. Add the
					line <code>-Drce.profiles.parentDir="&lt;directory>"</code> and replace
						<code>&lt;directory></code> with the absolute path to a directory which
					contains your profiles.</para>
			</note></para>
		<para>In either case, RCE creates the profile directory and its parents if they do not
			exist. The range of valid profile names is mainly restricted by your OS's range of valid
			directory names. We strongly recommend to restrict your profile names to the range of
			printable ASCII characters. Furthermore, the profile name <code>common</code> is
			reserved for internal use of RCE.</para>
		<para>If you want to change the profile location permanently, you can do so by supplying the
			commandline switch <code>-p</code> without a parameter. In this case, RCE starts with a
			text-based profile selection UI which allows you to set a new location of the default
			profile. We show this profile selection UI in the following figure.</para>
		<figure>
			<title>Profile Selection UI</title>
			<mediaobject>
				<imageobject>
					<imagedata fileref="images/profileSelectionUI.png" contentwidth="420"/>
				</imageobject>
			</mediaobject>
		</figure>
		<para>Choosing the second option ("Select the default profile for future runs") will present
			a list of available profiles. On selection of one of these profiles, RCE will not be
			started using this profile, but instead the selected profile will be marked as the
			default profile for future runs. This selection is only stored for the current user and
			for the current installation location of RCE. Different users on the same machine can
			therefore configure different default profiles. Furthermore, different installations of
			RCE can have different default profiles configured.</para>
		<note>
			<para>The Profile Selection UI will only display profiles if they have been started once
				with RCE 7.0 or newer.</para>
		</note>
		<para>No two instances of RCE may use the same profile simultaneously. Upon startup, RCE
			checks whether some other instance of RCE is already running which uses the given
			profile. In this case, RCE displays an error message stating that it "failed to lock
			profile directory" and shuts down. If you want to start multiple instances of RCE
			simultaneously on the same machine, you have to specify a different profile for each
			instance.</para>
		<example>
			<title>Choosing the Profile Directory</title>
			<para>Install RCE on some system that has not had RCE installed previously. For the sake
				of this example, we assume the current user to be called <code>rceuser</code><phrase
					os="linux"> and to have its home directory set to
					<code>/home/rceuser</code></phrase>.</para>
			<para>Start RCE without any parameters (i.e., via <phrase os="windows"
						><code>rce.exe</code></phrase><phrase os="linux"
				><code>./rce</code></phrase>). RCE will use the profile <phrase os="windows"
						><code>C:\Users\rceuser\.rce</code></phrase><phrase os="linux"
						><code>/home/rceuser/.rce</code></phrase>. Execute that command a second
				time in a second <phrase os="windows">cmd</phrase><phrase os="linux"
					>terminal</phrase> while the first instance is still running. Startup of RCE
				will fail, since the profile is already used by the first instance of RCE.</para>
			<para>Now execute the command <phrase os="windows"><code>rce.exe -p
						secondinstance</code></phrase><phrase os="linux"><code>./rce -p
						secondinstance</code></phrase> in a second <phrase os="windows"
					>cmd</phrase><phrase os="linux">terminal</phrase>. You will have two instances
				of RCE running, one using the profile <phrase os="windows"
						><code>C:\Users\rceuser\.rce\default</code></phrase><phrase os="linux"
						><code>/home/rceuser/.rce/default</code></phrase>, the other using the
				profile <phrase os="windows"
					><code>C:\Users\rceuser\.rce\secondinstance</code></phrase><phrase os="linux"
						><code>/home/rceuser/.rce/secondinstance</code></phrase>.</para>
			<para>Finally, execute the command <phrase os="windows"><code>rce.exe -p</code></phrase><phrase
					os="linux"><code>./rce -p</code></phrase>. RCE will offer you a list of profiles
				that you have most recently used. Pick the profile <code>secondinstance</code> as
				the default profile. If you now close all running instances of RCE and restart RCE
				without any parameters (i.e., via <phrase os="windows"
					><code>rce.exe</code></phrase><phrase os="linux"><code>./rce</code></phrase>),
				RCE will start using the profile <code>secondinstance</code>.</para>
		</example>
	</section>
	<section>
		<title>Contents of the Profile Directory</title>
		<para>As stated above, each profile contains the static configuration of RCE as well as its
			integrated tools. The former is defined via the JSON-file
				<code>configuration.json</code>. For an in-depth introduction to the JSON file
			format, please refer to <ulink url="http://www.json.org/">https://www.json.org/</ulink>. 
			The file <code>configuration.json</code> is located in the root of the profile directory,
			while the integrated tools are defined in the directory <code>integration</code> and its
			subdirectories.</para>
		<para>To change the static configuration of RCE, change the contents of the file
			configuration.json and restart RCE. You can either change the contents of this file
			manually using your favorite text editor, or from the GUI of RCE via the toolbar or the
			menu entry <emphasis>Configuration</emphasis>. <note>
				<para>Recall that RCE only parses its configuration during startup. Thus, if you
					change the contents of the file <code>configuration.json</code>, you have to
					restart RCE to apply these changes.</para>
			</note></para>
	</section>
	<section>
		<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>
	</section>
	<section 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>

		<section>
			<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>
		</section>
		<section 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>
		</section>

	</section>
	<section>
		<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>
		<section>
			<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>
		</section>
		<section>
			<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>When the profile is launched, the password or keyfile passphrase is
						imported into RCE's secure storage and the import files are deleted to
						mitigate potential security risks.</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>
		</section>
		<section>
			<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>When the profile is launched, the password or keyfile passphrase is
						imported into RCE's secure storage and the import files are deleted to
						mitigate potential security risks.</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>
		</section>
	</section>
</section>
