<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section id="installation">
    <title>Installation on <phrase os="linux">Linux</phrase><phrase os="windows"
        >Windows</phrase></title>
    <section>
        <title>Prerequisites</title>
        <para>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, <phrase
                os="linux">use your system's package manager to install it; the most common choice
                is the OpenJDK JRE.</phrase><phrase os="windows">you can download it from
                <programlisting><uri>https://www.java.com/de/download/</uri></programlisting>and
                install it. Starting with RCE 8.x we only publish 64 bit packages of RCE. Therefore,
                please make sure to install the 64 bit version of the JRE.</phrase><note>
                <para>Some pre-installed components of RCE have additional dependencies. Please
                    refer to <link linkend="workflow_components">Section 2.3 (Workflow
                        Components)</link> for more details.</para>
            </note></para>
    </section>
    <section>
        <title id="signing_key">Obtaining the Signing Key</title>
        <para>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.</para>
        <para>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.</para>
        <para><phrase os="windows">While verifying the downloaded artifact is optional, we strongly
                recommend doing so.</phrase><phrase os="linux">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.</phrase></para>
        <para>In order to verify the signature of a software, you require<itemizedlist>
                <listitem>
                    <para>the artifact that you want to verify (in this case a <phrase os="windows"
                            >.zip-file</phrase><phrase os="linux">.zip-, .deb-, or
                            .rpm-file</phrase>)</para>
                </listitem>
                <listitem>
                    <para>a signature file provided by the signer (in this case provided by
                        us)</para>
                </listitem>
                <listitem>
                    <para>the verification part of the signing key.</para>
                </listitem>
            </itemizedlist></para>
        <para><phrase os="windows">You can find the former two items at <ulink
                    url="https://rcenvironment.de">https://rcenvironment.de</ulink> under the menu
                item <code>Download</code>. The signature file is called <code>SHA256SUM.asc</code>
                and is available in the same directory as the artifacts.</phrase><phrase os="linux"
                >How to obtain the former two items depends on your chosen method of installation
                (see <link linkend="installation_details">Section 2.1.3</link> for more details).</phrase>
            The latter item, i.e., the signing key, is not available via <ulink
                url="https://rcenvironment.de">https://rcenvironment.de</ulink> 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.</para>
        <para>One common way to distribute such keyfiles is via so-called public keyservers. We had
            previously published the signing key for RCE at the SKS-keyservers, which are no longer
            available. Nevertheless, we have published the keyfile via
                <ulink url="https://github.com">https://github.com</ulink> in the repository called
                <code>rce-signing</code> owned by the organization <code>rcenvironment</code>.
            For now, this is the key supplier to use until we determine a new public key server.
            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.</para>
        <para>The precise steps required for signature verification differ from system to system.
            Commonly, key retrieval and verification is handled by <phrase os="windows">gpg4win
                (available at <ulink url="https://www.gpg4win.org"
                >https://www.gpg4win.org</ulink>).</phrase>
            <phrase os="linux">either your package manager or by gpg, which should be pre-installed
                on your system or available via the package manager of your choice.</phrase> Please
            refer to its documentation in order to verify your downloaded software artifact.</para>
    </section>
    <section>
        <title id="installation_details"> Installation</title>
        <para os="windows">On Windows, we provide a single .zip-file to set up both client and
            server installations. This file is available
            at<programlisting><uri>https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/zip/</uri></programlisting>Installing
            RCE amounts to simply extracting the zip file to a location on your file system.<note>
                <para>Due to restrictions of the standard Windows file system (NTFS), you should
                    choose a destination path that is as short as possible. Long paths are known to
                    cause problems, as some RCE files may not be properly extracted from the zip
                    file.</para>
            </note></para>
        <para os="linux">On Linux, there are up to three installation options, depending on your
            distribution: <orderedlist>
                <listitem>
                    <para>Installing RCE from a .deb package via a package manager (only on
                        .deb-based systems such as Debian, Ubuntu, or Mint),</para>
                </listitem>
                <listitem>
                    <para>installing RCE from a .deb- or .rpm-package (on .deb- and .rpm-based
                        systems, respectively), or</para>
                </listitem>
                <listitem>
                    <para>extracting RCE from a zip file (traditionally used by earlier versions of
                        RCE).</para>
                </listitem>
            </orderedlist></para>
        <para os="linux">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.</para>
        <para os="linux">The following table compares these options:<table frame="all">
                <title>Linux installation options</title>
                <tgroup cols="8">
                    <colspec colname="c1" colnum="1" colwidth="1.2*"/>
                    <colspec colname="newCol4" colnum="2" colwidth="1*"/>
                    <colspec colname="newCol6" colnum="3" colwidth="1*"/>
                    <colspec colname="newCol7" colnum="4" colwidth="1*"/>
                    <colspec colname="c2" colnum="5" colwidth="1*"/>
                    <colspec colname="newCol5" colnum="6" colwidth="1.5*"/>
                    <colspec colname="newCol8" colnum="7" colwidth="1*"/>
                    <colspec colname="newCol3" colnum="8" colwidth="1*"/>
                    <thead>
                        <row>
                            <entry>Installation type</entry>
                            <entry>Multi-user operation supported</entry>
                            <entry>Daemon operation (system service) supported</entry>
                            <entry>Installing multiple versions simultaneously</entry>
                            <entry>File system location</entry>
                            <entry>Updating to a new version </entry>
                            <entry>Verifying digital signatures</entry>
                            <entry>Registers start menu entry and icon</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>Using the package repository <emphasis>(.deb-based systems
                                    only)</emphasis></entry>
                            <entry><emphasis role="bold">yes</emphasis></entry>
                            <entry><emphasis role="bold">yes</emphasis></entry>
                            <entry>no</entry>
                            <entry><code>/usr/share/rce</code></entry>
                            <entry>Using the distribution's update manager (automatic or
                                manual)</entry>
                            <entry><emphasis role="bold">automatic</emphasis></entry>
                            <entry><emphasis role="bold">yes</emphasis></entry>
                        </row>
                        <row>
                            <entry>Manual installation of the .deb/.rpm package</entry>
                            <entry><emphasis role="bold">yes</emphasis></entry>
                            <entry><emphasis role="bold">yes</emphasis></entry>
                            <entry>no</entry>
                            <entry><code>/usr/share/rce</code></entry>
                            <entry>Manual download and install a newer package</entry>
                            <entry>manual</entry>
                            <entry><emphasis role="bold">yes</emphasis></entry>
                        </row>
                        <row>
                            <entry>Unpacking the .zip file</entry>
                            <entry>no</entry>
                            <entry>no</entry>
                            <entry><emphasis role="bold">yes</emphasis></entry>
                            <entry>(anywhere)</entry>
                            <entry>Use "Help -> Check for Updates" in RCE <emphasis role="bold"
                                    >-or-</emphasis> delete the old installation directory and
                                manually download and unpack a newer zip file</entry>
                            <entry>manual</entry>
                            <entry>no</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table></para>
        <section os="linux">
            <title>Installing from the Package Repository (recommended for
                Debian/Ubuntu/Mint)</title>
            <para>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 <link linkend="signing_key"
                    >Section 2.2</link> 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.</para>
            <para>Once you have imported the signing key into your package manager, please add the
                following repository to its list of repositories:</para>
            <programlisting>deb https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/deb/ /</programlisting>
            <para>When using Synaptic, you can add this repository by
                opening<programlisting>Settings -> Repositories -> Additional Repositories / Other Sources (or similar) -> Add New...</programlisting></para>
            <para>When using apt as your package manager, you can add the repository by executing
                the following command in a
                terminal:<programlisting>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</programlisting></para>
            <para>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.</para>
            <para>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
                    <code>sudo apt-get update</code>) 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 <code>sudo apt-get install rce</code>).</para>
            <para>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.</para>
        </section>
        <section os="linux">
            <title>Installation of the .deb/.rpm Package (recommended for CentOS/Red Hat/SUSE,
                alternative for Debian/Ubuntu/Mint)</title>
            <para>To install the .deb/.rpm file manually, download the latest version from either
                <programlisting><uri>https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/deb/</uri></programlisting></para>
            <para>or
                from<programlisting><uri>https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/rpm/</uri></programlisting></para>
            <para>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.</para>
            <para>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
                    <code>yum install &lt;filename></code> (Red Hat, CentOS, ...), <code>zypper
                    install &lt;filename></code> (openSUSE), or <code>sudo dpkg -i
                    &lt;filename></code> (Debian, Ubuntu, Mint, ...) from a terminal.</para>
            <para>To upgrade an existing installation, simply install the newer package. The package
                manager will detect the upgrade and handle it properly.</para>
        </section>
        <section os="linux">
            <title>Installation from the .zip File (alternative for all distributions)</title>
            <para>If none of the previous installation options fits your needs, you can also extract
                RCE from a zip file downloaded
                from<programlisting><uri>https://software.dlr.de/updates/rce/10.x/products/standard/releases/latest/zip/</uri></programlisting></para>
            <itemizedlist>
                <listitem>
                    <para>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.</para>
                </listitem>
            </itemizedlist>
            <itemizedlist>
                <listitem>
                    <para>If you prefer using the command line, use the <code>unzip</code> 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<programlisting>./rce</programlisting> to start RCE. In some cases, you
                        may first need to make it executable using the
                        command<programlisting>chmod +x rce</programlisting></para>
                </listitem>
            </itemizedlist>
                <note>
                    <para>The path to your installation location must not contain any colons to
                    avoid Java Virtual Machine errors when starting RCE.</para>
                </note>
        </section>
    </section>
    <section>
        <title>Starting RCE as a GUI Client</title>
        <para><phrase os="windows">To use RCE with a graphical user interface (GUI), simply start
                the "rce" executable from Windows Explorer. Optionally, create a desktop icon from
                the right-click menu using the "send to > desktop" option. </phrase></para>
        <para>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.</para>
        <para>
            <note os="linux">
                <para> 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
                        <code>env LIBOVERLAY_SCROLLBAR=0 ./rce</code> to disable the overlay
                    scrollbars for RCE. Alternatively, if you want to disable the overlay scrollbars
                    permanently for all programs, execute <code>echo "export LIBOVERLAY_SCROLLBAR=0"
                        > /etc/X11/Xsession.d/80overlayscrollbars</code> as a superuser and then
                    restart your computer.</para>
            </note>
        </para>
    </section>
    <section>
        <title>Starting a Non-GUI ("Headless") Instance</title>
        <para>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. </para>
        <para>To run a headless RCE instance, open a <phrase os="windows">command
                prompt</phrase><phrase os="linux">terminal</phrase> and run the command
            <programlisting>rce --headless -console</programlisting>While RCE is running, you can
            enter various console commands described in <xref linkend="command_line"/>; note that
            you need to prefix all RCE commands with "rce" here. To perform a clean shutdown, for
            example, type <code>rce stop</code> and press enter.</para>
    </section>
    <section>
        <title>Installation as a Service on a <phrase os="linux">Linux Server</phrase><phrase
                os="windows">Windows Server</phrase></title>
        <para>Please refer to the section "<phrase os="linux">RCE as a Linux systemd Service</phrase><phrase os="windows">RCE as a Windows Service</phrase>" in the "RCE Administration
			and Security Guide" to install RCE as a service.</para>
    </section>
</section>
