From 49554b8fd31dc38ab35afc79e9f1b36a104b4ad4 Mon Sep 17 00:00:00 2001 From: Ralf Schmid Date: Mon, 31 Aug 2026 14:20:59 +0200 Subject: [PATCH] Docs: document jemalloc memory allocator for package installations Package installations now preload libjemalloc.so.2 via the postinstall script (zammad/zammad 791c607006, .pkgr.yml + contrib/packager.io/functions). Docker images have shipped jemalloc since 0f15700ec4. - install/package.rst: new Memory Allocator section (availability per distro, opt-out/opt-in, verification command) - appendix/environment-variables.rst: LD_PRELOAD and ZAMMAD_USE_JEMALLOC entries, jemalloc pointer in Performance Tuning intro --- appendix/environment-variables.rst | 23 ++++++++++++ appendix/memory-allocator.rst | 58 ++++++++++++++++++++++++++++++ index.rst | 1 + install/package.rst | 4 +++ prerequisites/software.rst | 5 +++ 5 files changed, 91 insertions(+) create mode 100644 appendix/memory-allocator.rst diff --git a/appendix/environment-variables.rst b/appendix/environment-variables.rst index b6d5bf6b..8355dcf4 100644 --- a/appendix/environment-variables.rst +++ b/appendix/environment-variables.rst @@ -56,6 +56,25 @@ S3_URL |package| Example for value: ``https://key:secret@s3.eu-central-1.amazonaws.com/zammad-storage-bucket?region=eu-central-1&force_path_style=true`` +LD_PRELOAD |package| + Default: unset (package installations set it to ``libjemalloc.so.2`` + automatically if the jemalloc library is present on your system) + + Preloads a shared library for all Zammad processes. Package installations + use it to enable jemalloc as memory allocator (see + :doc:`Memory Allocator `). This variable is + managed by the package install script and may be overwritten during + updates. + +ZAMMAD_USE_JEMALLOC |package| + Default: unset + + Set to ``no`` to opt out of jemalloc as memory allocator. Takes + effect on the next package installation or upgrade (see + :doc:`Memory Allocator `). Unset it to opt + back in; any value other than ``no`` re-enables jemalloc on the next + package installation or upgrade. + Zammad ------ @@ -362,6 +381,10 @@ will begin to emerge. Below settings may consume all available database connections. Please consider the :doc:`configure-database-server` for more information. +jemalloc as memory allocator is active by default on package +installations and reduces memory usage. See :doc:`Memory Allocator +` for details. + ZAMMAD_WEB_CONCURRENCY Default: unset diff --git a/appendix/memory-allocator.rst b/appendix/memory-allocator.rst new file mode 100644 index 00000000..b841abe5 --- /dev/null +++ b/appendix/memory-allocator.rst @@ -0,0 +1,58 @@ +Memory Allocator +================ + +Package installations use `jemalloc `_ as memory +allocator for all Zammad Ruby processes, as recommended by Rails. This +reduces memory usage and fragmentation. The package postinstall script +preloads the jemalloc library automatically if it's present on your system. +This happens on every package installation and upgrade. + +Docker installations have jemalloc always active (baked into the image). +To opt out, override the environment variable with an empty value (e.g. +``LD_PRELOAD=""`` in your compose or env file). + +Availability +------------ + +- Debian / Ubuntu: libjemalloc2 is installed automatically as package + dependency. +- CentOS / RHEL: jemalloc is installed automatically from the EPEL + repository (already a Zammad dependency). +- SLES: jemalloc is **not** installed automatically (only available via + SUSE Package Hub). If you install it manually with + ``zypper install jemalloc``, Zammad activates it automatically on the + next package installation or upgrade. + +Opt-Out and Opt-In +------------------ + +To opt out of using jemalloc: + +.. code-block:: console + + $ zammad config:set ZAMMAD_USE_JEMALLOC=no + +This takes effect on the next package installation or upgrade. The +postinstall script then removes the ``LD_PRELOAD`` variable entirely, so a +pre-existing system value is respected. For immediate effect: + +.. code-block:: console + + $ zammad config:unset LD_PRELOAD + +.. code-block:: console + + $ sudo systemctl restart zammad + +To opt back in, unset the variable again (any value other than ``no`` +re-enables jemalloc on the next package installation or upgrade): + +.. code-block:: console + + $ zammad config:unset ZAMMAD_USE_JEMALLOC + +To verify whether jemalloc is active, run: + +.. code-block:: console + + $ zammad run ruby -e 'puts File.read("/proc/self/maps").match?(/jemalloc/) ? "jemalloc active" : "jemalloc NOT active"' diff --git a/index.rst b/index.rst index 399a9f8a..641e0777 100644 --- a/index.rst +++ b/index.rst @@ -103,5 +103,6 @@ Zammad System Documentation /appendix/single-sign-on /appendix/reporting-tools-thirdparty /appendix/redis + /appendix/memory-allocator /appendix/custom-kb-url /appendix/custom-kb-css diff --git a/install/package.rst b/install/package.rst index 73644014..427a11e6 100644 --- a/install/package.rst +++ b/install/package.rst @@ -50,6 +50,10 @@ some operating systems may require additional packages if not already installed. $ sudo dnf install curl epel-release +Zammad uses `jemalloc `_ as memory allocator out of +the box on Debian, Ubuntu, CentOS and RHEL. For SLES, opt-out and +verification details, see :doc:`Memory Allocator `. + 2. Install Elasticsearch ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/prerequisites/software.rst b/prerequisites/software.rst index 1872ce0e..78fc9a89 100644 --- a/prerequisites/software.rst +++ b/prerequisites/software.rst @@ -145,6 +145,11 @@ automatically be installed with the Zammad-Package. | *However:* If you have to use ``bundle install`` for e.g. custom gems or development, you'll need to install it! +On Debian/Ubuntu and CentOS/RHEL, the jemalloc memory allocator is +installed automatically as dependency and preloaded by all Zammad Ruby +processes. On SLES it's not installed automatically; see +:doc:`Memory Allocator ` for details. + 2.3 Database Server ^^^^^^^^^^^^^^^^^^^