.. /*  
    * This file is part of the SavaPage project <https://www.savapage.org>.
    * Copyright (c) 2026 Datraverse B.V.
    * Author: Rijk Ravestein.
    *
    * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. <info@datraverse.com>
    * SPDX-License-Identifier: CC-BY-SA-4.0
    *
    * For more information, please contact Datraverse B.V. at this
    * address: info@datraverse.com
    */

.. _ch-tuning-jvm:

JVM Tuning
----------

.. contents:: |RST_TABLE_OF_CONTENTS|
   :depth: 2
   :local:

.. _ch-tuning-jvm-intro:

Introduction
~~~~~~~~~~~~

SavaPage runs in the Java Virtual Machine (JVM) using the class
libraries and other supporting files provided in the JRE.

The SavaPage JVM settings work fine, and generally there is no
customization needed. However, if needed the JVM can be tuned by adding
extra JVM arguments in the file:
``/opt/savapage/server/custom/app-server.conf``

Edit this file as ``savapage`` user and enter the extra JVM arguments as value
of the ``CUSTOM_JVM_ARGS`` key. The examples below shows the JVM
arguments as explained in the next sections.

.. code-block:: ini

   # JDK 11
   # Note: enclose the value with quotes
   CUSTOM_JVM_ARGS="-XX:MaxRAMFraction=2"

The location of temporary files can be overwritten with the
``JAVA_IO_TMPDIR`` key. See :ref:`JVM Temporary Files <ch-tuning-jvm-tmpdir>`.

.. important::

   Before doing any JVM customizing please consult SavaPage Support
   to discuss your requirements and which customization fits best.

.. _ch-tuning-jvm-memory:

JVM Memory Allocation
~~~~~~~~~~~~~~~~~~~~~

The JVM allocates a quarter of host system RAM to the |PRODUCT_NAME|
Server process by default. This ensures that SavaPage does not
consume too many resources and does not get in the way of other
applications running on the same system.

However, if the host system is dedicated to running |PRODUCT_NAME|, you
can safely allocate more memory to |PRODUCT_NAME|. With more allocated
memory SavaPage will have a better performance, particularly with
many users and large printing throughput.

Add one of the following JVM parameters to allocate relative or absolute
memory:

.. callout::

   .. code-block:: ini

       -XX:MaxRAMFraction=3    # <1>
       -XX:MaxRAMFraction=2    # <2>
       -Xmx864m                # <3>

   .. annotations::
      :1: Allocate one third of host system RAM.
      :2: Allocate one half of host system RAM.
      :3: Allocate 864MB of host system RAM.


.. _ch-tuning-jvm-gc:

JVM Garbage Collection
~~~~~~~~~~~~~~~~~~~~~~

Customizing Java Garbage Collection (GC) depends on the characteristics
of the application involved. The JVM provides proper defaults for
SavaPage most of the time. See `OpenJDK Wiki <https://wiki.openjdk.org/>`__ 
for an introduction to GC options.

.. _ch-tuning-jvm-tmpdir:

JVM Temporary Files
~~~~~~~~~~~~~~~~~~~

The Java system property ``java.io.tmpdir`` determines where the JVM
writes temporary files. The default value typically points to the world
readable ``/tmp`` directory. As a result, all Java components that are
part of the SavaPage application will write their temporary files to
that directory. You can override the default in:
``/opt/savapage/server/custom/app-server.conf``

Edit this file as ``savapage`` user and specify the alternative temp directory
at the ``JAVA_IO_TMPDIR`` variable.

.. code-block:: ini

   # Overwrite of JVM system property 'java.io.tmpdir' 
   # User 'savapage' must have mode 700 access to this directory. 
   #JAVA_IO_TMPDIR=


.. caution::

   Use the ``JAVA_IO_TMPDIR`` setting with the *utmost care*. Make sure
   the directory is *exclusively used* by the SavaPage application,
   and is accessible by the ``savapage`` system user only. If these conditions
   are not met, SavaPage will not start and might get corrupted.

Among all Java third-party components, SavaPage components take a
special position because they write their own temp files in
``/opt/savapage/server/data/.tmp`` . This directory is created when
the application starts and removed when stopped. You can override this
special location with the ``app.dir.tmp`` property in the
``server.properties`` file.
See :ref:`Alternative File Locations <ch-install-on-linux-config-alt-file-locations>`.

.. caution::

   Make sure that the special temp directory used by |PRODUCT_NAME|
   resides on the same |image1| disk partition as the other file
   locations that are used to store SavaPage data on runtime. See:
   
   - :ref:`Alternative File Locations <ch-install-on-linux-config-alt-file-locations>`.
   - :ref:`File Locations <app-file-locations>`.


.. |image1| image:: ../images/manual/famfamfam-silk_drive-16x11.png
   :width: 16px