To run RCE on a system, the only prerequisite is an installed Java Runtime Environment (JRE), version 8u161 or above. If you do not already have one on your machine, use your system's package manager to install it; the most common choice is the OpenJDK JRE.
Some pre-installed components of RCE have additional dependencies. Please refer to Section 2.3 (Workflow Components) for more details.
Any software can be tampered with by a malicious attacker. For RCE, the consequences of such tampering may be worse than with other software, since its intended behavior already includes executing arbitrary processes, opening outgoing network connections, and listening for incoming ones. One common safeguard against such tampering is software signing. If the developers sign a software artifact, e.g., a zip-archive or an executable file, the user can verify the signature. This verification confirms that the artifact downloaded onto their machine is identical to the artifact prepared by the software developers and has not been tampered with.
In order to sign a software artifact, the developers combine the artifact and a so-called signing key to form a signature file. The user can then verify the signature using the artifact, the signature file, and a part of the signing key that can only be used for verification, but not for signing. A technical introduction to the minutiae of software signing is out of the scope of this user guide and we refer to the literature for more information on this topic.
If you would like to install RCE by using a package repository (see below), you need to obtain the signing key before doing so. For other methods of installation, namely manual installation of a package or unpacking a .zip-file, verifying the signature of the downloaded artifact is optional. Despite this, we strongly recommend doing so.
In order to verify the signature of a software, you require
the artifact that you want to verify (in this case a .zip-, .deb-, or .rpm-file)
a signature file provided by the signer (in this case provided by us)
the verification part of the signing key.
How to obtain the former two items depends on your chosen method of installation (see Section 2.1.3 for more details). The latter item, i.e., the signing key, is not available via https://rcenvironment.de or linked to in this user guide on purpose: Recall that the purpose of software signing is to protect against compromised communication channels between developers and users. Thus, if the artifact, the signatures, and the signing key were available at the same location, an attacker that takes control over that location could easily forge all three components.
One common way to distribute such keyfiles is via so-called public keyservers. We have
thus published the signing key for RCE at the SKS-keyservers (https://sks-keyservers.net/). In case you
are unable to access those keyservers, we have furthermore published the keyfile via
https://github.com in the repository called
rce-signing owned by the organization rcenvironment.
Please verify the integrity of the obtained keyfile by checking its fingerprint against
the one published by us via a trusted channel (e.g., the RCE Twitter account). We omit
giving direct links as well as the key's fingerprint here on purpose. This slightly
decreases the chance of attackers directing you toward a forged key.
The precise steps required for signature verification differ from system to system. Commonly, key retrieval and verification is handled by either your package manager or by gpg, which should be pre-installed on your system or available via the package manager of your choice. Please refer to its documentation in order to verify your downloaded software artifact.
On Linux, there are up to three installation options, depending on your distribution:
Installing RCE from a .deb package via a package manager (only on .deb-based systems such as Debian, Ubuntu, or Mint),
installing RCE from a .deb- or .rpm-package (on .deb- and .rpm-based systems, respectively), or
extracting RCE from a zip file (traditionally used by earlier versions of RCE).
If you are using a .deb-based distribution, we strongly recommend installing RCE via your package manager of choice. On .rpm-based systems, we instead recommend using the provided .rpm-package, as this automatically installs RCE into the proper system locations. It furthermore allows you to cleanly manage your installation via the package manager.
The following table compares these options:
Table 2.1. Linux installation options
| Installation type | Multi-user operation supported | Daemon operation (system service) supported | Installing multiple versions simultaneously | File system location | Updating to a new version | Verifying digital signatures | Registers start menu entry and icon |
|---|---|---|---|---|---|---|---|
| Using the package repository (.deb-based systems only) | yes | yes | no | /usr/share/rce | Using the distribution's update manager (automatic or manual) | automatic | yes |
| Manual installation of the .deb/.rpm package | yes | yes | no | /usr/share/rce | Manual download and install a newer package | manual | yes |
| Unpacking the .zip file | no | no | yes | (anywhere) | Use "Help -> Check for Updates" in RCE -or- delete the old installation directory and manually download and unpack a newer zip file | manual | no |
To register the RCE .deb package repository in your system, you first have to add the RCE signing key to your package manager. Popular choices for such a package manager are Synaptic and apt, which feature a graphical user interface and a command-line interface, respectively. Please refer to Section 2.2 for details on how to obtain this key. The steps required to import the signing key into your package manager differ greatly based on the used package manager. Please refer to its documentation for more information on this.
Once you have imported the signing key into your package manager, please add the following repository to its list of repositories:
deb https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/deb/ /
When using Synaptic, you can add this repository by opening
Settings -> Repositories -> Additional Repositories / Other Sources (or similar) -> Add New...
When using apt as your package manager, you can add the repository by executing the following command in a terminal:
sudo echo "deb https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/deb/ /" >/etc/apt/sources.list.d/dlr_rce_10_releases.list
Although this command is split across multiple lines in this guide, it must be executed as a single line. Further, this command requires superuser-rights and will ask you for your sudo-password. Please contact your system administrator if you do not have such a password.
After adding the repository to your package manager, refresh the list of available
software (e.g., via clicking a Refresh- or Reload-button or via the console command
sudo apt-get update) and install RCE like any other software (e.g.,
via selecting it in the list of available software in Synaptic or via the console
command sudo apt-get install rce).
Once you have installed RCE using either of these approaches, any RCE 10.x upgrade will automatically show up via the update mechanism of your operating system. Depending on the upgrade settings of your system, they may be installed automatically, or be presented to you for selection. Although technically possible, RCE 10.x will not auto-upgrade to 11.x (or higher) to maintain compatibility within networks of RCE 10.x instances. You will need to manually install the 11.x repository location in order to upgrade.
To install the .deb/.rpm file manually, download the latest version from either
https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/deb/or from
https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/rpm/Use the former package on .deb-based systems such as Debian, Ubuntu, or Mint and use the latter package on .rpm-based systems such as Red Hat or CentOS.
You can install the package using the graphical package management tools of your
distribution (double-clicking the .deb/.rpm-file should start them), or by running
yum install <filename> (Red Hat, CentOS, ...), zypper
install <filename> (openSUSE), or sudo dpkg -i
<filename> (Debian, Ubuntu, Mint, ...) from a terminal.
To upgrade an existing installation, simply install the newer package. The package manager will detect the upgrade and handle it properly.
If none of the previous installation options fits your needs, you can also extract RCE from a zip file downloaded from
https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/zip/If you prefer graphical tools, double-click the .zip file to open it with your distribution's archive manager. Extract it to a location of your choice and open that location in your file-system explorer. Typically, double-clicking the "rce" executable will work out of the box and start RCE. If this does not happen, right-click the executable, open its "properties" section (or similar), and look for an option to mark it as executable. Confirm the dialog, then double-click it again.
If you prefer using the command line, use the unzip command
to extract the zip file to a location of your choice. In the location where
you unpacked the files to, you can usually simply
enter
./rce
to start RCE. In some cases, you may first need to make it executable using the command
chmod +x rce
The path to your installation location must not contain any colons to avoid Java Virtual Machine errors when starting RCE.
Once your RCE instance has started, you can open the configuration file with the menu option "Configuration > Open Configuration File". Edit the file, save it, and then restart RCE using the "File > Restart" menu option to apply the changes. There are configuration templates and other information available via the "Configuration > Open Configuration Information" option. The available configuration settings are described in the configuration chapter.
On Ubuntu, the Ubuntu overlay scrollbars can sometimes lead to problems with
the RCE GUI. To avoid these problems, you can start RCE from a terminal with
env LIBOVERLAY_SCROLLBAR=0 ./rce to disable the overlay
scrollbars for RCE. Alternatively, if you want to disable the overlay scrollbars
permanently for all programs, execute echo "export LIBOVERLAY_SCROLLBAR=0"
> /etc/X11/Xsession.d/80overlayscrollbars as a superuser and then
restart your computer.
RCE can also be run from the command line without a graphical user interface (which is called "headless" mode), which uses less system resources and is therefore recommended when the GUI is not needed.
To run a headless RCE instance, open a terminal and run the command
rce --headless -console
While RCE is running, you can
enter various console commands described in Section 3.3, “Commands”; note that
you need to prefix all RCE commands with "rce" here. To perform a clean shutdown, for
example, type rce stop and press enter.
For ad-hoc or temporary RCE network setups, running a headless RCE from the command line is perfectly fine. For more permanent installations, however, we recommend installing RCE as a system daemon instead. This has the advantage that RCE automatically shuts down when the server is shut down, and automatically restarts when the server does.
Executing the following steps will install RCE as daemon. An RCE daemon will start automatically on system boot and stop before system shutdown.
The recommended (and supported) way to install a Linux daemon is to
install RCE from a .deb or .rpm package, or (equivalently) installing it from the
APT repository. While installing a daemon from the .zip file distribution can be
made to work, it creates unnecessary complications regarding installation paths and
file permissions. As registering a daemon requires root privileges anyway, there
should be no reason to use the .zip file; if you have a compelling use case for
this, please contact the RCE team at rce@dlr.de.
Once RCE is properly installed, registering it as a daemon is very
simple. A command named rce-daemon is provided to control the whole
daemon life cycle. The only manual step you need to perform before using that
command is creating a user account that the daemon will run under. For now, this
account has to be named rce-daemon; use your distribution's console
commands or GUI tools to add it. (Please note that this account needs to have a home
directory to hold the daemon's profile directory.) Future RCE versions will make
this account name customizable.
As of RCE 10, the daemon wrapper still uses the System V approach. Migration to systemd is planned for RCE 11.
Once this user account is created, you can use the following commands to manage the daemon installation:
rce-daemon install - installs and starts the daemon
instance
rce-daemon uninstall - stops and uninstalls the daemon
instance; the profile directory remains unchanged
rce-daemon start / rce-daemon stop /
rce-daemon restart - standard daemon controls
rce-daemon locate - prints the location of the daemon's
RCE instance's profile directory and relevant files
rce-daemon status - displays if the RCE daemon is
currently running or not
After installation, the daemon instance will be started automatically. This will create a default configuration file if it does not exist yet.
To configure the daemon instance, use rce-daemon locate to
find its configuration file, edit and save it, and then use rce-daemon
restart to apply the new configuration.
For importing SSH credentials and authorization group keys into a daemon, please refer to section Section 2.2.4, “Importing authorization data without GUI access”. As of RCE 10, file-based imports are only processed on startup, so a restart is required for this, too.
The need to restart the daemon is temporary; future versions of RCE will apply configuration changes as soon as configuration files are changed or new import files are placed in the respective folders.