<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section>
	<title>Setting up Cross-Organization Networks using RCE Uplink</title>
	<para>"RCE Uplink" is an experimental feature introduced in RCE 10.x that addresses the growing
		need for the exchange of computation services between different organizations. Conceptually,
		this is realized using RCE's standard approach of providing access to local tools as
		distributed services, while keeping the tool's files and execution on the local
		machine.</para>
	<para>To allow the efficient and low-overhead exchange of tool computation services between
		organizations, some sort of network connection must be established between them. For IT
		security reasons, however, many organizations are understandably reluctant to open ports
		into their networks. The Uplink approach addresses this by providing a shared coordination
		and forwarding server called a "relay". This relay server is typically placed outside of any
		organization's protected network, e.g. on a rented server or in the DMZ of one of the
		involved organizations. </para>
	<para>
		Due to the exposed nature of this relay server, it is designed
		to be
		secure by default. There is only
		one way of connecting to it,
		which is the encrypted and authenticated
		SSH protocol. The protocol
		transmitted over SSH is designed to be concise and easily audited.
	</para>
	<para> Development is focused on placing as little trust as possible into the relay server.
		Technical steps are being taken to limit what data can be monitored at the relay server.
		Some of these features, however, are <emphasis>not</emphasis> implemented in the
		experimental Uplink feature in RCE 10 yet. In all RCE 10.x versions, data transmitted to and
		from tools is safely encrypted against unauthorized access from <emphasis>outside</emphasis>
		users, through the standard security features provided by the SSH protocol. However, all
		data could theoretically still be observed by administrators of the relay server.
			<emphasis>If this is unacceptable in your setup, please wait for RCE 11 (or later)
			releases, in which the Uplink feature is planned for non-experimental release. Please
			note that the feature scope of each release depends on the prioritization of Uplink in
			relation to project and user needs.</emphasis></para>
	<para>A typical Uplink setup between two or more organizations involves an Uplink relay server (a
		specially configured RCE instance) in a location that is accessible from all organization's
		networks. </para>
	<para>This relay server opens an Uplink/SSH port, with one or more sets of credentials for each
		organization. The recommended approach is to issue one account per person, and potentially
		additional accounts for technical systems (i.e., servers). This allows tracing activities
		within the network to individual users or servers. (<emphasis role="italic">Please note that
			tracing capabilities are rudimentary in the current experimental
			implementation.</emphasis>)</para>
	<para>Another possible approach is to issue accounts to so-called "gateway" nodes. These are
		specially configured RCE nodes that make this account usable to other users within the local
		network without sharing the account's login data itself. End users can then use their
		individual RCE instances to connect to the gateway node using RCE's local network features.
		This way, the connection to the relay server can be centrally administered at the gateway
		while keeping the user's machines simpler.</para>
	<para>Please note that in setups based on gateway notes, both the relay server and other
		organizations can not easily distinguish nodes behind the gateway, and can therefore not
		easily associate actions with individuals or servers. This may either be an advantage or a
		disadvantage, depending on your organization's and your partners' IT security policies.
		Please make sure that the chosen setup is in accordance with the respective IT
		departments.</para>
	<para>In both approaches, any RCE node that connects directly or indirectly (via gateway) to the
		relay server can use the tools published by the other organizations as compute services, or
		publish tools themselves to the other organizations. Future versions of the Uplink feature
		may provide additional features to centrally restrict this ability. If this is a project
		need for you, please contact us via <email>rce@dlr.de</email>.</para>
	<section>
		<title>Security considerations of external tool publishing</title>
		<para>As usual in RCE's distribution approach, the binary or script code of "published" tools
			never leaves the node it is running on. Instead, "publishing" a tool means offering it
			as a standardized compute service that can be invoked with external input data. The
			security of tools with regards to potentially unknown input data lies with the tool
			developer and/or its publisher.</para>
	<para>Therefore, it is recommended to avoid publishing tools to external organizations directly
			from user's machines. Instead, the recommended approach is to only <emphasis
				role="italic">develop</emphasis> them on user's machines, and use RCE's <emphasis
				role="italic">local</emphasis> publishing options for initial testing with
			colleagues. Once the tool is sufficiently stabilized, it should then be installed on
			dedicated server machines, and published to external partners (via Uplink) from there.
			This allows central administration and security monitoring of these servers.</para>
	</section>
	<section>
		<title>Example of a Cross-Organization Network</title>
		<para>The following figure gives an example of how such a cross-organization network
			could be structured: </para>
		<figure>
			<title>Example RCE network</title>
			<mediaobject>
				<imageobject>
					<imagedata fileref="../images/RCE-uplink-network.png" contentwidth="400"/>
				</imageobject>
			</mediaobject>
		</figure>
		<note>
			<para>Please note that this diagram makes heavy use of "gateway" nodes, which are not recommended
				for typical setups at this time. A future version of this guide will contain an
				updated diagram.</para>
		</note>
		<para>The four project partners in the example all have an internal network of RCE
			instances which are connected by standard RCE connections. Uplink connections to a
			relay server are used to connect between the different partners. The relay server is
			located outside of the organizations networks, and only the relay server has to be
			reachable via SSH over the internet. Within each organization, users can either
			connect directly to the relay server (as in the diagram's "Partner D" network, which
			is typically the preferred approach), or they can use a so-called "gateway" node.
			Such a gateway node provides a shared SSH/Uplink connection for multiple users. When
			such a gateway is used, RCE instances in the institution’s internal network can be
			connected to it by standard (local) RCE connections and still publish tools to the
			other partners and access tools published by other partners. </para>
		<para> Each institution in the example has a different internal setup, all of which are
			possible: <itemizedlist>
				<listitem>
					<para> Partner A has a dedicated RCE server where the published tools are
						located, which is connected to the SSH gateway by an RCE connection. All
						other RCE users in the internal network are connected to this server
					</para>
				</listitem>
				<listitem>
					<para> Partner B has put all the tools directly on the SSH gateway instance.
					</para>
				</listitem>
				<listitem>
					<para> In Partner C's network, some tools are located on the SSH gateway,
						but some tools are also published by users directly on their own
						machines. As long as they are connected to the SSH gateway also those
						tools can be published to the other partners. </para>
				</listitem>
				<listitem>
					<para> Partner D has no tool server, instead the users’ computers connect
						directly to the relay server. </para>
				</listitem>
			</itemizedlist></para>
	</section>
</section>
