.. /* * This file is part of the SavaPage project . * Copyright (c) 2026 Datraverse B.V. * Author: Rijk Ravestein. * * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. * SPDX-License-Identifier: CC-BY-SA-4.0 * * For more information, please contact Datraverse B.V. at this * address: info@datraverse.com */ .. _ch-install-on-linux: .. figure:: ../images/manual/savapage-logo-no-text-100px.png :width: 75px |PRODUCT_NAME| on GNU/Linux =========================== .. admonition:: |ADMONITION_TABLE_OF_CONTENTS| - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` This section is a supplement to the :ref:`Server Installation ` guide. It provides an in-depth explanation of the GNU/Linux installation process, the directory layout and tools involved. Information in this chapter is technical in nature. It is expected that readers have prior experience with: - The Unix command line environment - Unix file permissions .. _ch-install-on-linux-process: Installation Process -------------------- .. contents:: :depth: 2 :local: |PRODUCT_NAME| is supplied as a pre-compiled self-installing application. The installation process is designed to work with all major GNU/Linux distributions. To be sure if your GNU/Linux distro is supported out of the box, please check :ref:`System Requirements `. Due to the varied nature of some installations and administrator preferences, often some manual configuration is required. This section describes the installation process in detail as well as some additional options available to system administrators. Manual extraction ~~~~~~~~~~~~~~~~~ |PRODUCT_NAME| is supplied in a self-extracting, self-installing archive. The archive is simply a ``tar`` archive compressed with ``gzip``, and headed with a shell script to facilitate self-extracting. After extraction is complete, the installation script named ``install`` is executed to begin the install process in the directory where the archive resides (usually ``/opt/savapage``). Some system administrators may like to inspect the contents of the archive, and possibly the installation process itself prior to the actual install. The self-extracting installer takes a number of command line arguments. The ``-e`` option will extract the archive into the current working directory ready for inspection. With the ``-n`` switch the ``-i`` install will be non-interactive. With this mode you implicitly agree with the AGPL license, and root tasks are collected in a ``MUST-RUN-AS-ROOT`` script located in the install directory. This script must be run manually as ``root`` after the installation. Further usage information is available via the ``-h`` switch. .. code-block:: text _____________________________________________________________________________ SavaPage Install (c) 2010-2018, Datraverse B.V. License: GNU AGPL version 3 or later . This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Usage: savapage-setup-1.0.0-linux-x64.bin [-h|-i|-e|-l] [-n] [-v] [FILE]... -h This help text. -i Install after extracting the files (default). -n Non-interactive install: execute MUST-RUN-AS-ROOT afterwards. -e Extract all files or a FILE list and exit without installing. -l List the contents of the archive and exit without extracting. -v Verbose. Print the names of the files as they are extracted. .. _ch-install-on-linux-process-install: The install process ~~~~~~~~~~~~~~~~~~~ Even though the majority of the installation process is completed under the identity of the system user account called ``savapage``, most administrators would like to know what the install process does. The main steps are outlined in the next paragraphs. Extraction ^^^^^^^^^^ The first stage in the install process extracts the archive to ``/tmp`` or a location as defined by an environment variable TMPDIR. The command-line programs ``tar`` and ``gunzip`` are used during this phase. Installation ^^^^^^^^^^^^ After extraction is complete the ``install`` script is called. The current directory is passed as ``-d`` option argument, to be used as install location. Also, the ``-n`` switch, used at the setup binary, is propagated to this script. The extracted files are copied to the install location. *Care is taken not to overwrite any existing data or configuration files if this is an install-over-the-top upgrade.* .. code-block:: text _____________________________________________________________________________ SavaPage Install (c) 2010-2018, Datraverse B.V. License: GNU AGPL version 3 or later . This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Usage: install [OPTION]... -d The target location, usually the /opt/savapage directory. -h This help text. -n Non-interactive install: execute MUST-RUN-AS-ROOT afterwards. Permissions ^^^^^^^^^^^ To ensure the default installation is secure by default, permissions are applied to key files. The following ``/opt/savapage/server`` areas of the application are restricted to the ``savapage`` user only: .. list-table:: Secured Application Areas :width: 100% :widths: 25 75 :header-rows: 1 * - Area - Description * - ``data/`` - This directory contains application data including database files. Some of these data may contain sensitive information. * - ``data/server.properties`` - Contains server configuration properties. See :ref:`server.properties ` in :ref:`Advanced Configuration `. * - ``data/admin.properties`` - Contains the hashed password of the reserved internal ``admin`` user. * - ``data/jmxremote.password`` - Contains the plain text password of the reserved JMX ``admin`` user. See :ref:`JMX Agent `. * - ``data/jmxremote.ks`` - The private keystore used by the :ref:`JMX Agent `. * - ``bin/linux-x64/`` - This directory contains the ``savapage-pam`` setuid-root binary. Even though the binary is no use to an end-user or hacker, good security practice stipulates that we should only allow the ``savapage`` user access to this directory. Permissions can be checked and re-applied any time after the installation by running this script: |br| ``/opt/savapage/server/bin/linux-x64/setperms`` Firewall ^^^^^^^^ The |PRODUCT_NAME| Application Server runs in a Java Virtual Machine (JVM) process and listens on ports |PROD_IP_PORT|, and |PROD_IP_PORT_SSL| and |PROD_IP_PORT_SSL_LOCAL| (SSL). These ports are used for Web App access, printing and other services. Ensure that any firewall or local IP filtering software such as ``iptables`` is set to allow local network traffic access to this ports. .. _ch-install-on-linux-process-install-root-tasks: Root Level Tasks ^^^^^^^^^^^^^^^^ A small part of the install process needs to run as the ``root`` account. The tasks conducted as root include: - Setting the ``/opt/savapage/server/bin/linux-x64/savapage-pam`` binary as setuid-root. This binary is used for password verification. - Installing the ``/opt/savapage/providers/cups/linux-x64/savapage-notifier`` binary as CUPS event notifier. This binary is used to send CUPS printer and print job status events to the central |PRODUCT_NAME| server. See :ref:`CUPS Notifier `. - Setting up a **systemd** unit for GNU/Linux systems that use the systemd service manager. This is done by creating a ``savapage.service`` file in the systemd unit library. Depending on the distribution the unit will either be created in the ``/lib/systemd/system/`` or ``/usr/lib/systemd/system/`` directory. The unit is started and enabled. - Setting up a *custom* **systemd** unit for the CUPS scheduler ``cupsd``. - If the scheduler is run from systemd some systems pass the ``-l`` parameter so ``cupsd`` is run on demand by socket and path activation. The advantage of this setup is that CUPS is activated when needed, saving precious boot time and resources, and deactivated again after being idle for a while. This lazy activation scenario is efficient for desktop systems that print occasionally and for which printing is not time critical. - However, dedicated print systems like |PRODUCT_NAME|, that intensively use IPP to communicate with CUPS, need CUPS to be full-time activated. Therefore a custom systemd ``cups.service`` unit is installed in ``/etc/systemd/system/`` to override the default ``/lib/systemd/system/cups.service`` shipped with the CUPS package. This custom unit starts ``cupsd`` with the ``-f`` parameter so it runs steadily in the foreground (without dependencies for ``cups.socket`` and ``cups.path``). - Setting up **SysV** style start scripts for Debian based systems that use the SysV service manager. This is done by placing symlinks in the: .. code-block:: text /etc/init.d/ /etc/rc3.d/ /etc/rc5.d/ and so on... If the administrator decides not to run the root-level tasks during the install process, the tasks can be run again post-install by executing the shell scripts: |br| ``/opt/savapage/server/bin/linux-x64/roottasks`` and ... |br| ``/opt/savapage/providers/cups/linux-x64/roottasks`` Alternatively the administrator can view the script and make the required changes by hand.