<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<sect1 id="installation">
    <title>Installation on <phrase os="linux">Linux</phrase><phrase os="windows"
        >Windows</phrase></title>
    <sect2>
        <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>http://www.java.com/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>
    </sect2>
    <sect2>
        <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 have
            thus published the signing key for RCE at the SKS-keyservers (<ulink
                url="https://sks-keyservers.net/">https://sks-keyservers.net/</ulink>). In case you
            are unable to access those keyservers, we have furthermore 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>.
            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>
    </sect2>
    <sect2>
        <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>
        <sect3 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>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</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>
        </sect3>
        <sect3 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>
        </sect3>
        <sect3 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>
        </sect3>
    </sect2>
    <sect2>
        <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>
    </sect2>
    <sect2>
        <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>
    </sect2>
    <sect2>
        <title>Installation as a <phrase os="linux">Daemon on a Linux Server</phrase><phrase
                os="windows">Service on a Windows Server</phrase></title>
        <para>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 <phrase os="windows">Windows service</phrase><phrase
                os="linux">system daemon</phrase> instead. This has the advantage that
            RCE automatically shuts down when the server is shut down, and automatically restarts
            when the server does.</para>
        <sect3>
            <title>Installation and <phrase os="linux">Daemon</phrase><phrase os="windows"
                    >Service</phrase> Management</title>
            <para>Executing the following steps will install RCE as <phrase os="linux"
                    >daemon</phrase><phrase os="windows">service</phrase>. An RCE <phrase os="linux"
                    >daemon</phrase><phrase os="windows">service</phrase> will start automatically
                on system boot and stop before system shutdown.</para>
            <para os="linux">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 <code>rce@dlr.de</code>.</para>
            <para os="linux">Once RCE is properly installed, registering it as a daemon is very
                simple. A command named <code>rce-daemon</code> 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 <code>rce-daemon</code>; 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.</para>
            <note os="linux"><para>As of RCE 10, the daemon wrapper still uses the System V approach. Migration to systemd is
                    planned for RCE 11.</para></note>
            <para os="linux">Once this user account is created, you can use the following commands
                to manage the daemon installation:<itemizedlist>
                    <listitem>
                        <para><code>rce-daemon install</code> - installs and starts the daemon
                            instance</para>
                    </listitem>
                    <listitem>
                        <para><code>rce-daemon uninstall</code> - stops and uninstalls the daemon
                            instance; the profile directory remains unchanged</para>
                    </listitem>
                    <listitem>
                        <para><code>rce-daemon start</code> / <code>rce-daemon stop</code> /
                                <code>rce-daemon restart</code> - standard daemon controls</para>
                    </listitem>
                    <listitem>
                        <para><code>rce-daemon locate</code> - prints the location of the daemon's
                            RCE instance's profile directory and relevant files</para>
                    </listitem>
                    <listitem>
                        <para><code>rce-daemon status</code> - displays if the RCE daemon is
                            currently running or not</para>
                    </listitem>
                </itemizedlist></para>
            <para os="windows">
                <orderedlist>
                    <listitem>
                        <para>Navigate to the <code>extras\windows_service</code> folder inside your
                            installation folder of RCE named <code>rce</code></para>
                    </listitem>
                    <listitem>
                        <para>Open the file <code>install_as_service.bat</code> and adjust these
                            settings:</para>
                        <para>
                            <itemizedlist>
                                <listitem>
                                    <para>Set RCE_ROOT_PATH to the location of your RCE installation
                                        (typically, the location which you are editing these files
                                        in). RCE must already be present (and unpacked) in this
                                        location; the daemon installer does not copy any files
                                        there.</para>
                                </listitem>
                                <listitem>
                                    <para>Set RCE_SERVICE_USER to the name of the existing user
                                        account that the RCE service should run as.<note>
                                            <para>This user account will be used to run RCE and all
                                                local tools that are invoked by it. Make sure that
                                                this user has appropriate system permissions to run
                                                these tools' executables, and read/write all related
                                                files.</para>
                                        </note></para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                    <listitem>
                        <para>Execute with administrator rights
                            <programlisting>install_as_service.bat</programlisting> by
                            double-clicking or on the command line</para>
                    </listitem>
                    <listitem>
                        <para>Open the Windows Service Managment Console (e.g. execute
                            "services.msc" on the command line)</para>
                    </listitem>
                    <listitem>
                        <para>Look for entry "RCE Service", do a right-click and click
                            "Properties"</para>
                    </listitem>
                    <listitem>
                        <para>Click on the "Log On" tab and fill in the correspondig password for
                            the user account set to the RCE_SERVICE_USER variable. By clicking the
                            "Apply" button a message should inform you that the privilege to "Log on
                            as service" was added to the account.<note>
                                <para>To add the "Log on as a service" right to an account on your
                                    local computer manually:</para>
                                <orderedlist>
                                    <listitem>
                                        <para>Open Local Security Policy.</para>
                                    </listitem>
                                    <listitem>
                                        <para>In the console tree, double-click <emphasis
                                                role="bold">Local Policies</emphasis>, and then
                                            click <emphasis role="bold">User Rights
                                                Assignments</emphasis>.</para>
                                    </listitem>
                                    <listitem>
                                        <para>In the details pane, double-click <emphasis
                                                role="bold">Log on as a service</emphasis>.</para>
                                    </listitem>
                                    <listitem>
                                        <para>Click <emphasis role="bold">Add User or
                                                Group</emphasis> and add the appropriate account to
                                            the list of accounts that possess the <emphasis
                                                role="bold">Log on as a service</emphasis>
                                            right.</para>
                                    </listitem>
                                </orderedlist>
                            </note></para>
                    </listitem>
                    <listitem>
                        <para>Close the properties dialog by clicking "Ok"</para>
                    </listitem>
                </orderedlist>
            </para>
            <para os="windows">To manually start the RCE service:</para>
            <para os="windows">
                <orderedlist>
                    <listitem>
                        <para>Open the Windows Service Managment Console (e.g. execute
                                <code>services.msc</code> on the command line)</para>
                    </listitem>
                    <listitem>
                        <para>Right-click on the entry "RCE Service" and select "Start"</para>
                    </listitem>
                </orderedlist>
            </para>
            <para os="windows">To stop the RCE service:</para>
            <para os="windows">
                <orderedlist>
                    <listitem>
                        <para>Open the Windows Service Managment Console (e.g. execute
                                <code>services.msc</code> on the command line)</para>
                    </listitem>
                    <listitem>
                        <para>Right-click on the entry "RCE Service" and select "Stop"</para>
                    </listitem>
                </orderedlist>
            </para>
            <para os="windows">To uninstall the RCE service:</para>
            <para os="windows">
                <orderedlist>
                    <listitem>
                        <para>Navigate to the <code>extras\windows_service</code> folder inside your
                            installation folder of RCE named <code>rce</code>
                        </para>
                    </listitem>
                    <listitem>
                        <para>Open the file <code>uninstall_service.bat</code> and set the absolute
                            path of the variable RCE_ROOT_PATH to the location of your RCE
                            installation</para>
                    </listitem>
                    <listitem>
                        <para>Execute with administrator rights
                            <programlisting>uninstall_service.bat</programlisting> by
                            double-clicking or on the command line</para>
                    </listitem>
                </orderedlist>
            </para>
        </sect3>
        <sect3>
            <title><phrase os="linux">Daemon</phrase><phrase os="windows">Service</phrase>
                Configuration</title>
            <para>After installation, the <phrase os="linux">daemon</phrase><phrase os="windows"
                    >service</phrase> instance will be started automatically. This will create a
                default configuration file if it does not exist yet.</para>
            <para os="linux">To configure the daemon instance, use <code>rce-daemon locate</code> to
                find its configuration file, edit and save it, and then use <code>rce-daemon
                    restart</code> to apply the new configuration.</para>
            <para os="windows">To configure the service instance, locate the RCE configuration file
                in the service user's home directory - by default, it is located at
                    <code>C:\users\&lt;user id>\.rce\default\configuration.json</code>. Edit this
                file and restart the service to apply the changes.</para>
            <para>For importing SSH credentials and authorization group keys into a <phrase
                    os="linux">daemon</phrase><phrase os="windows">service</phrase>, please refer to
                section <xref linkend="authdata-import"/>. As of RCE 10, file-based imports are only
                processed on startup, so a restart is required for this, too.</para>
            <note>
                <para>The need to restart the <phrase os="linux">daemon</phrase><phrase os="windows"
                        >service</phrase> 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.</para>
            </note>
        </sect3>
    </sect2>
</sect1>
