From aaf2e49ecb03f73d66749b53168198e8b787b64d Mon Sep 17 00:00:00 2001 From: Yury Kirsanov Date: Sun, 11 Oct 2026 19:29:32 +1100 Subject: [PATCH 1/4] docs: memory sizes with suffixes and HG_MALLOC elastic arenas (4.1) - troubleshooting/outofmem: -m/-M accept k/m/g from 4.1; new "Let the pool grow" subsection for HG_MALLOC's elastic INIT:CAP arenas, LimitMEMLOCK, hg_advise and the grow-blocked statistics. - troubleshooting/increasemem: short pointer to elastic arenas. - migration 4.0 -> 4.1: -m/-M forms and the opt-in HG_MALLOC parameters (no action needed for existing setups). Documents OpenSIPS/opensips#4327. --- docs/migration/4-0-0-to-4-1-0.md | 7 +++++++ docs/troubleshooting/increasemem.md | 18 ++++++++++++++++++ docs/troubleshooting/outofmem.md | 19 ++++++++++++++++++- 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/docs/migration/4-0-0-to-4-1-0.md b/docs/migration/4-0-0-to-4-1-0.md index d4ae1a7..50ae092 100644 --- a/docs/migration/4-0-0-to-4-1-0.md +++ b/docs/migration/4-0-0-to-4-1-0.md @@ -48,6 +48,13 @@ The following is the full list of backwards-incompatible syntax or functional ch the framework and `pi_reload` to reload it. The old `pi_reload_tbls_and_cmds` / `pi_http:reload_tbls_and_cmds` commands should no longer be used. +* Memory: `-m` and `-M` now also accept a `k`/`m`/`g` suffix and the + `INIT:CAP` form; existing values keep working unchanged. `INIT:CAP` is used + by the new, opt-in HG_MALLOC allocator (`-a HG_MALLOC`), which also adds + optional global parameters (`shm_auto_scaling_profile`, + `pkg_auto_scaling_profile`, `shm_grow_granule`, `pkg_grow_granule` and the + `hg_*` parameters). Nothing changes unless it is selected. + ### Core Variables * example diff --git a/docs/troubleshooting/increasemem.md b/docs/troubleshooting/increasemem.md index dc0e8b7..014f3c6 100644 --- a/docs/troubleshooting/increasemem.md +++ b/docs/troubleshooting/increasemem.md @@ -55,3 +55,21 @@ opensips -m 256 # this will run OpenSIPS with 256MB of share memory ``` + +--- + +## Let the memory grow (OpenSIPS 4.1 and later) + +With the HG_MALLOC allocator both sizes can be given as `INIT:CAP`: OpenSIPS +starts with INIT and grows on demand up to CAP, so a pool no longer has to be +sized for the worst case up front: + +```bash + +opensips -a HG_MALLOC -m 256:2g -M 8:32 + +# 256 MB of shared memory growing up to 2 GB, 8 MB of private memory per process growing up to 32 MB + +``` + +See [Out Of Memory](/troubleshooting/outofmem#let-the-pool-grow-opensips-41-and-later) for monitoring and host requirements. diff --git a/docs/troubleshooting/outofmem.md b/docs/troubleshooting/outofmem.md index ab23d8c..4e79e23 100644 --- a/docs/troubleshooting/outofmem.md +++ b/docs/troubleshooting/outofmem.md @@ -35,7 +35,7 @@ If the result is inconclusive, continue with the memory-debugging procedure. Use the `-m` option to increase the shared-memory pool and the `-M` option to increase the private-memory pool allocated to each OpenSIPS process. Both values -are specified in MB. +are specified in MB (from OpenSIPS 4.1 they also take a `k`/`m`/`g` suffix). For example: @@ -50,6 +50,23 @@ installation before restarting OpenSIPS by editing: * `/etc/sysconfig/opensips` on Red Hat-based systems +### Let the pool grow (OpenSIPS 4.1 and later) + +With the HG_MALLOC allocator the pools can be elastic: `-m INIT:CAP` starts at +INIT, grows on demand up to CAP and gives memory back when it is no longer +used, so the size does not have to be guessed for the busiest hour: + +```bash +opensips -a HG_MALLOC -m 128:1024 -M 8:32 +``` + +HG_MALLOC pins its memory, so run OpenSIPS with `LimitMEMLOCK=infinity` (or +`ulimit -l unlimited`). `opensips-mi hg_advise` reports what `-m` and `-M` +should be from the peaks actually reached, and the `hgmem:hg_shm_grow_blocked` +and `hgmem:hg_pkg_grow_blocked` statistics show when an arena cannot grow any +further. See the HG_MALLOC documentation (`mem/README.hg_malloc.md` in the +source tree) for details. + ## Debug memory usage on OpenSIPS 3.x and later ### 1. Enable memory debugging From f1b7d166f1f75318e75e437e22e68cf6acdd5da1 Mon Sep 17 00:00:00 2001 From: Yury Kirsanov Date: Sun, 11 Oct 2026 23:05:17 +1100 Subject: [PATCH 2/4] outofmem: MI command is core:hg_advise --- docs/troubleshooting/outofmem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting/outofmem.md b/docs/troubleshooting/outofmem.md index 4e79e23..5437720 100644 --- a/docs/troubleshooting/outofmem.md +++ b/docs/troubleshooting/outofmem.md @@ -61,7 +61,7 @@ opensips -a HG_MALLOC -m 128:1024 -M 8:32 ``` HG_MALLOC pins its memory, so run OpenSIPS with `LimitMEMLOCK=infinity` (or -`ulimit -l unlimited`). `opensips-mi hg_advise` reports what `-m` and `-M` +`ulimit -l unlimited`). `opensips-mi core:hg_advise` reports what `-m` and `-M` should be from the peaks actually reached, and the `hgmem:hg_shm_grow_blocked` and `hgmem:hg_pkg_grow_blocked` statistics show when an arena cannot grow any further. See the HG_MALLOC documentation (`mem/README.hg_malloc.md` in the From 9b9e8f891005484bd7f8dc9d41db956f3a196428 Mon Sep 17 00:00:00 2001 From: Yury Kirsanov Date: Sun, 11 Oct 2026 23:24:09 +1100 Subject: [PATCH 3/4] outofmem: MI call via opensips-cli -x mi --- docs/troubleshooting/outofmem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting/outofmem.md b/docs/troubleshooting/outofmem.md index 5437720..8393e64 100644 --- a/docs/troubleshooting/outofmem.md +++ b/docs/troubleshooting/outofmem.md @@ -61,7 +61,7 @@ opensips -a HG_MALLOC -m 128:1024 -M 8:32 ``` HG_MALLOC pins its memory, so run OpenSIPS with `LimitMEMLOCK=infinity` (or -`ulimit -l unlimited`). `opensips-mi core:hg_advise` reports what `-m` and `-M` +`ulimit -l unlimited`). `opensips-cli -x mi core:hg_advise` reports what `-m` and `-M` should be from the peaks actually reached, and the `hgmem:hg_shm_grow_blocked` and `hgmem:hg_pkg_grow_blocked` statistics show when an arena cannot grow any further. See the HG_MALLOC documentation (`mem/README.hg_malloc.md` in the From b619ee99bed66ad78bf395b3c7cc2229e45e109a Mon Sep 17 00:00:00 2001 From: Yury Kirsanov Date: Sun, 11 Oct 2026 23:33:39 +1100 Subject: [PATCH 4/4] outofmem: LimitMEMLOCK required for elastic arenas on hugetlb pages, keeps the arena unswapped elsewhere --- docs/troubleshooting/outofmem.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/troubleshooting/outofmem.md b/docs/troubleshooting/outofmem.md index 8393e64..68271cf 100644 --- a/docs/troubleshooting/outofmem.md +++ b/docs/troubleshooting/outofmem.md @@ -60,8 +60,9 @@ used, so the size does not have to be guessed for the busiest hour: opensips -a HG_MALLOC -m 128:1024 -M 8:32 ``` -HG_MALLOC pins its memory, so run OpenSIPS with `LimitMEMLOCK=infinity` (or -`ulimit -l unlimited`). `opensips-cli -x mi core:hg_advise` reports what `-m` and `-M` +HG_MALLOC pins its memory: run OpenSIPS with `LimitMEMLOCK=infinity` (or +`ulimit -l unlimited`) - required for an elastic arena on hugetlb pages, and +it keeps the arena from being swapped on the others. `opensips-cli -x mi core:hg_advise` reports what `-m` and `-M` should be from the peaks actually reached, and the `hgmem:hg_shm_grow_blocked` and `hgmem:hg_pkg_grow_blocked` statistics show when an arena cannot grow any further. See the HG_MALLOC documentation (`mem/README.hg_malloc.md` in the