To run RCE on a system, the only prerequisite is an installed Java Runtime Environment (JRE), version 8u161 or above. If you don't 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.
There are two installation options on Linux: installing RCE from .deb/.rpm packages, or extracting it from a zip file (which was traditionally used by earlier versions of RCE). Whenever possible, using the packages is recommended, as RCE is automatically installed into the proper system locations, and can be cleanly managed using your distribution's package manager. If you are using a Debian-based distribution, a package repository is provided as well, which makes it even easier to install and upgrade RCE. The following table compares these options:
Table 2.1. Linux installation options
| Installation type | Multi-user operation supported | Daemon operation (system service) supported | Installing more than one version at the same time | File system location | Updating to a new version | Verifying digital signatures | Registers start menu entry and icon |
|---|---|---|---|---|---|---|---|
| Using the package repository (Debian/Ubuntu/Mint 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 | Manually download and install a newer package | manual (gpg/shasum) | 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 (gpg/shasum) | no |
To register the RCE .deb package repository in your system, you have to add the repository location, and add the RCE signing key. Then, you can install RCE like any other software package. There are two different ways to do this, both leading to the the same result.
(Option 1) If you prefer to use graphical tools, start the program "Synaptic"; if it is not available, install if from your Software Center - or similar - first. Please note that this option might not be available on all systems. If this is the case for you, you can still install the package using the manual process listed as Option 3.
Open "Settings > Repositories".
Click on "Authentication keys", and then on "Download a key...". Copy the text
258BC129EDA2389D3ECD2DE6BA880CB39DC1CE34
into the dialog that appears and click "Ok". The list of keys should now contain an entry "RCE Automatic Signing Key <rce@dlr.de>".
Click on a section named "Additional Repositories", "Other Sources" or similar. Select the "Add..." or "Add new..." option. Copy the text
deb https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/deb/ /
into the dialog that appears and click "Ok".
Close the settings dialog and click "Reload" to update the list of available software. After this, you should find an entry "rce" in this list (for example, using the Search button), which you can install like any other software. You will also receive automatic notifications when a newer version of RCE 10.x is available.
(Option 2) If you prefer to execute all steps manually using the command line, enter the following commands as "root" (or with the "sudo" prefix). Obviously, this is the most complicated way.
apt-key adv --recv-key 258BC129EDA2389D3ECD2DE6BA880CB39DC1CE34
If you see a message containing the text "RCE
Automatic Signing Key <rce@dlr.de>", the key
import was successful. Sometimes, this step fails with the
message "key [...] not found on keyserver; gpg: no
valid OpenPGP data found." If this happens, just
repeat the command a few times until it works. This issue
may also be caused by an outdated gpg version (gpg version
2.0.9 on SUSE Linux Enterprise Desktop 11 is known to be
problematic, while gpg version 2.0.22 works).
The RCE signing key is published on the keyserver
pool.sks-keyservers.net, which is the
default keyserver for most distributions of gpg. If your
installation does not default to that keyserver, you may try
to explicitly specify the keyserver at
hkps://hkps.pool.sks-keyservers.net or at
hkp://pool.sks-keyservers.net. Please
consult the documentation of your installation of gpg to
determine how to specify the keyserver.
If you cannot access keyservers at all for some reason, you can also download the key manually from
https://github.com/rcenvironment/rce-signing/blob/master/rce_signing_key.asc
After the download has completed, you can import the key by executing
apt-key adv --import rce_signing_key.asc
from the command line.
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 it may be split across lines here, this command must be executed as a single line.
apt-get update
apt-get install rce
For previous versions of RCE there existed a script that imported the signing key from github and added the software repository to the system repositories automatically. Due to recent changes to our workflow for producing RCE releases, we are currently improving and adapting these scripts. Once they are available, you can find them at
https://github.com/rcenvironment/rce-signing
Executing the script
register_rce_10.x_deb_repository.sh
will import the signing key onto your system and subsequently register the repository with your package manager.
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 file manually, download the latest version from
https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/deb/You
can either install it using the graphical package management tools of your
distribution (double-clicking the .deb should start them), or by running sudo
dpkg -i <filename> from a terminal. To upgrade an existing
installation, simply install the newer package. The package manager will detect the
upgrade and handle it properly.
To install the .rpm file, download the latest version from
https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/rpm/You
can either install it with the graphical package management tools of your
distribution (double-clicking the .rpm should start them), or by running the
appropriate installation command as the "root" user. On CentOS or Red Hat, the
command is yum install <filename>; on SUSE, use zypper install
<filename>. 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.
Starting with RCE 6.x, we provide digital signatures for our releases. These can be used to verify the integrity of the downloaded files, as any unsigned software can be tampered with while downloading it over an unsecured (HTTP) connection. This is especially important when installing RCE from a user account with root privileges, for example as a system daemon
For each type of release files (.zip, .deb, and .rpm files), a
SHA256SUM.asc file is provided next to the actual files. This file
contains checksums for each release file, and these checksums are signed with our
release key. It is named "RCE Automatic Signing Key", has the id 9DC1CE34, and is valid
until Nov 22, 2020. Its full fingerprint is 258B C129 EDA2 389D 3ECD 2DE6 BA88
0CB3 9DC1 CE34.
On Linux, the required command-line tools to verify these signatures (gpg and shasum/sha1sum/sha256sum) are usually already installed as part of your distribution. If they are not, use your system's package manager to install them. To perform the actual verification:
Execute
gpg --recv-key 258BC129EDA2389D3ECD2DE6BA880CB39DC1CE34
to import the signing key. This only needs to be done once per key.
If you see a message containing the text "RCE Automatic
Signing Key <rce@dlr.de>", the key import was
successful. Sometimes, this step fails with the message "key
[...] not found on keyserver; gpg: no valid OpenPGP data
found." If this happens, just repeat the command a few
times until it works. This issue may also be caused by an outdated
gpg version (gpg version 2.0.9 on SUSE Linux Enterprise Desktop 11
is known to be problematic, while gpg version 2.0.22 works).
The RCE signing key is published on the keyserver
pool.sks-keyservers.net, which is the default
keyserver for most distributions of gpg. If your installation does
not default to that keyserver, you may try to explicitly specify the
keyserver at hkps://hkps.pool.sks-keyservers.net or at
hkp://pool.sks-keyservers.net. Please consult the
documentation of your installation of gpg to determine how to
specify the keyserver.
If you cannot access keyservers at all for some reason, you can also download the key manually from
https://github.com/rcenvironment/rce-signing/blob/master/rce_signing_key.asc
After the download has completed, you can import the key by executing
apt-key adv --import rce_signing_key.asc
from the command line.
Download the SHA256SUMS.asc file from the same location as
the installation package and place it in the same folder as the downloaded
.zip-file. Run
gpg --verify --yes SHA256SUMS.asc
in the
location where you saved it to; this verifies the digital signature. Inspect
the output to see if it is correct; you should find the text "Good signature
from "RCE Automatic Signing Key <rce@dlr.de>" (or a similar translation).
Once the command has terminated, you should find a file
SHA256SUMS in the current folder.
When following these steps, it is normal to receive a warning about the fact that the owner of this key cannot be verified. If you have received this user guide from a trustworthy source (e.g. an official RCE project site secured with HTTPS), you can assume that the key is correct, as the command used to import the key has already verified the key's integrity. Alternatively, you can fetch the key's fingerprint from a trustworthy source (e.g. from a secure intranet page, or the official @rcenvironment Twitter feed accessed via HTTPS) and compare it with the one shown in the command's output. If they match, you can trust that you are using the authentic key.
Run
shasum -c SHA256SUMS
in the same folder. This verifies that the actual download matches what has been digitally signed for the release. You should see the installation package's name, followed by "OK".
On some distributions, you need to use sha1sum or
sha256sum instead of shasum.
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.