# vmaudit
Analyzes Virtual Memory Area (VMA) utilization to provide data-driven
recommendations for system administrators and developers.
[](https://pypi.org/project/vmaudit/)
## Understanding Linux Virtual Memory Areas (VMAs)
### Key Concepts
- **What are VMAs?**
- A Virtual Memory Area (VMA) is a contiguous region of virtual memory within
a process's address space.
- VMAs are used for the application's code, data/text segments, stack, heap,
and any memory-mapped files (including anonymous regions) or shared libraries.
- You can view the VMAs for a specific process by inspecting its `/proc/<pid>/maps`
file. Each line represents a `struct vm_area_struct` (VMA) in the kernel.
- **File descriptors are not VMAs.** File descriptors (`struct file` in the
kernel) don't create VMAs on their own. Instead, they count against the
file descriptor limit (`ulimit -n`), **not** the `vm.max_map_count` limit.
This is a common point of confusion since memory-mapped files do create
VMAs. You can view the file descriptors for a process by listing its `fd`
allocations via `ls -l /proc/<pid>/fd`.
- **Synchronization primitives are not VMAs.** Things like futexes, mutexes,
semaphores, pipes and sockets don't create VMAs unless they're backed by
shared memory mappings.
- **The `vm.max_map_count` Kernel Limit**
- That kernel setting defines the **maximum number of VMAs a single process**
**can have**.
- It is a **per-process limit**, not a system-wide total.
- The VMA count of a child process (including `fork()`) is separate and does
**not** count towards its parent's limit.
- If a process reaches the limit, it will not be allowed to allocate any
further memory. Allocation attempts will then be rejected with "out of
memory" (`ENOMEM`) as the reason, even if the system still has plenty
of available memory.
### Typical VMA Usage
The number of VMAs a process uses can vary significantly depending on the application.
- **Typical Linux Processes:**
- Most command-line tools and normal applications use **fewer than 1,000** VMAs.
- Heavier desktop applications (such as Electron-/Chromium-based applications)
or development tools might in very rare cases use up to **10,000** VMAs,
but they're typically below **4,000** VMAs.
- **Gaming (via Wine/Proton):**
- Most games use between **5,000 and 35,000** VMAs.
- A few exceptionally demanding games are known to push this limit much higher:
- **Counter-Strike 2**, **Hogwarts Legacy**, and **Star Citizen** can use
between **30,000 and 80,000** VMAs.
- **Specialized Software:**
- **Elasticsearch** requires a VMA limit of **262,144** (their arbitrarily
selected number; simply 64x 4096). Their official packages [automatically](https://www.elastic.co/docs/deploy-manage/deploy/self-managed/vm-max-map-count)
configure this VMA limit for your system upon installation. This number
was determined to be safe by Elasticsearch, and is verified by a bootstrap
check on every startup, to ensure that your system is suitable for
production use.
- **Docker Desktop** on Mac/Windows internally sets every container's limit
to **262,144**, to accommodate running Elasticsearch inside a container.
However, all native containers (whether Docker or Podman or something else)
share the Linux kernel with the host machine. Therefore, if you're running on
a Linux host, the container always inherits the exact same value as the host.
### Recommended VMA Limit
- If you want a custom-tailored recommendation for your own system, you can use
`vmaudit` to analyze your system. Otherwise, use the recommendations below.
- For **general Linux desktop** use, the kernel's default `vm.max_map_count` value
of **65,530** is incredibly generous and will always work.
- For **Wine/Proton gaming** use, setting `vm.max_map_count` to **120,000** is
a safe and very generous value that will prevent issues with even the most
VMA-intensive games and applications.
- For **Elasticsearch** use, set `vm.max_map_count` to **262,144** (or **300,000**
if you want a nice, round number), since it's the officially required value
and provides plenty of headroom for very demanding search engine servers.
- The value **does not need to be a power of two**. Any sufficiently large integer
is correct.
### Why Not Go Higher?
- Setting `vm.max_map_count` to a very high number is dangerous. Each VMA is
a non-swappable kernel data structure that consumes a small amount of memory.
While negligible for a single VMA, this overhead can accumulate rapidly. This
can exhaust the kernel's slab memory, leading to **kernel crashes**. High
limits also degrade system performance, as managing and traversing millions
of VMAs can **severely slow down** essential kernel operations such as regular
housekeeping and common syscalls like `mmap()` and `munmap()`.
- To make matters worse, the kernel's OOM (out-of-memory) handler doesn't take
the kernel's internal VMA structs into account when deciding which processes
to terminate, and will instead start terminating various high-memory desktop
processes (or important background services) when the system is running out of
memory. The malicious or misbehaving process that's responsible for allocating
all the VMAs usually won't be terminated until it's too late.
- This attack has been demonstrated with a proof-of-concept DoS (denial-of-service)
application, which runs entirely in user-mode and is capable of crashing Linux
by simply allocating lots of VMAs. It is especially dangerous for shared
multi-user machines, such as servers, where a hostile user could then run
a malicious binary to crash the entire server. The proof-of-concept attack
code is available on [Fedora's mailing list](https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/YGTDBA2XENG7GSMHFYZQNIIGCGS3LQCD/).
- In summary, setting the limit to an extreme value creates a **Denial-of-Service (DoS)**
vulnerability, where a single **misbehaving or malicious user-space process**
can consume vast amounts of kernel memory and very high CPU usage, thus bringing
the entire system to a **crash or severe slowdown**.
- While a moderate increase from the kernel's default 65,530 to something like
120,000 or 300,000 is reasonable for a few specific, very heavy workloads;
raising the limit blindly to millions or billions of VMAs is mostly **cargo-cult**
**paranoia**, and is both absolutely **pointless** and **poses a stability risk**.
Always remember that typical Linux processes use less than 2,000 VMAs!
### Changing Your System's VMA Limit
- To view your current VMA limit, execute any of the following commands (or
run `vmaudit`, which also analyzes your current limit).
```sh
sysctl vm.max_map_count
cat /proc/sys/vm/max_map_count
```
- You can change the active limit for the current, running system by executing
the following command (with your own value). This change will take effect
immediately, but will be lost after a reboot.
```sh
sudo sysctl -w vm.max_map_count=120000
```
- You can make the change permanent by executing the following command, and then
rebooting your system.
```sh
echo "vm.max_map_count=120000" | sudo tee /etc/sysctl.d/90-vm_max_map_count.conf
```
## How to Install `vmaudit`
- **Recommended:** Installing the package via pip.
```sh
# Only for the current user (will only be able to scan the current user's processes):
pip install vmaudit
# Alternative: Global install to be able to scan all system processes (recommended).
sudo pip install vmaudit
```
- **Alternative:** Installing the package directly from source.
```sh
git clone https://github.com/Arcitec/vmaudit.git
cd vmaudit
# User installation.
pip install .
# Alternative: Global installation (recommended).
sudo pip install .
```
- Note: In all of these examples, it's recommended to replace the `pip` command
with [pipx](https://pipx.pypa.io/stable/installation/) instead, which installs
CLI tools into isolated environments for improved reliability. However, you
should never run "sudo pipx", since the per-user pipx installation is runnable
as root without needing to be installed globally.
- If you ever want to remove the package again, run the `uninstall` command.
```sh
# User installation.
pip uninstall vmaudit
# Alternative: If you've installed it globally.
sudo pip uninstall vmaudit
```
- You can also run the package directly from source code without installing it.
See the next section.
## How to Use `vmaudit`
- Running the virtual memory analyzer when it has been **installed as a package**.
```sh
# Scanning the current user's processes:
vmaudit
# Scanning all processes on the system:
# NOTE: Only works if you've installed vmaudit via "sudo pip".
sudo vmaudit
# Alternative: Scanning all processes on the system (only for "pipx" installs):
sudo "$(which vmaudit)"
```
- Alternative: Running **directly from source code**. Supports both user and
system scans.
```sh
# Scanning the current user's processes:
python src/vmaudit
# Scanning all processes on the system:
sudo python src/vmaudit
```
- If you know the **maximum number of VMAs** observed or expected for a process,
then you can provide it directly to receive a custom recommendation.
```sh
vmaudit --vma 80000
```
- There are several other options to tweak the algorithm. However, the defaults
are already correct, so most people will have no reason to change the parameters.
```sh
vmaudit -h
```
- Note: By default, the recommendation algorithm uses a very generous, overkill
"50% additional headroom" recommendation to allow for huge, unpredictable
memory usage fluctuations. If your workload is predictable, a headroom
of "25%" is more reasonable, if you want to further optimize the limit for
your particular usage.
---
This project is licensed under the GPLv2 License.
See the [LICENSE](LICENSE) file for details.
Find out how to [contribute](CONTRIBUTING.md) to this project.
Raw data
{
"_id": null,
"home_page": null,
"name": "vmaudit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "analysis, audit, kernel, linux, linux tools, memory, memory usage, monitoring, performance, sysadmin, system administration, virtual memory, vm.max_map_count, vma, vmstat",
"author": "Arcitec",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6e/7c/de1301284af58218756cdd2880291df335f9a1b64e89822872ecd2fe8d67/vmaudit-1.0.1.tar.gz",
"platform": null,
"description": "# vmaudit\n\nAnalyzes Virtual Memory Area (VMA) utilization to provide data-driven\nrecommendations for system administrators and developers.\n\n[](https://pypi.org/project/vmaudit/)\n\n\n## Understanding Linux Virtual Memory Areas (VMAs)\n\n### Key Concepts\n\n- **What are VMAs?**\n - A Virtual Memory Area (VMA) is a contiguous region of virtual memory within\n a process's address space.\n - VMAs are used for the application's code, data/text segments, stack, heap,\n and any memory-mapped files (including anonymous regions) or shared libraries.\n - You can view the VMAs for a specific process by inspecting its `/proc/<pid>/maps`\n file. Each line represents a `struct vm_area_struct` (VMA) in the kernel.\n - **File descriptors are not VMAs.** File descriptors (`struct file` in the\n kernel) don't create VMAs on their own. Instead, they count against the\n file descriptor limit (`ulimit -n`), **not** the `vm.max_map_count` limit.\n This is a common point of confusion since memory-mapped files do create\n VMAs. You can view the file descriptors for a process by listing its `fd`\n allocations via `ls -l /proc/<pid>/fd`.\n - **Synchronization primitives are not VMAs.** Things like futexes, mutexes,\n semaphores, pipes and sockets don't create VMAs unless they're backed by\n shared memory mappings.\n\n\n- **The `vm.max_map_count` Kernel Limit**\n - That kernel setting defines the **maximum number of VMAs a single process**\n **can have**.\n - It is a **per-process limit**, not a system-wide total.\n - The VMA count of a child process (including `fork()`) is separate and does\n **not** count towards its parent's limit.\n - If a process reaches the limit, it will not be allowed to allocate any\n further memory. Allocation attempts will then be rejected with \"out of\n memory\" (`ENOMEM`) as the reason, even if the system still has plenty\n of available memory.\n\n\n### Typical VMA Usage\n\nThe number of VMAs a process uses can vary significantly depending on the application.\n\n- **Typical Linux Processes:**\n - Most command-line tools and normal applications use **fewer than 1,000** VMAs.\n - Heavier desktop applications (such as Electron-/Chromium-based applications)\n or development tools might in very rare cases use up to **10,000** VMAs,\n but they're typically below **4,000** VMAs.\n\n- **Gaming (via Wine/Proton):**\n - Most games use between **5,000 and 35,000** VMAs.\n - A few exceptionally demanding games are known to push this limit much higher:\n - **Counter-Strike 2**, **Hogwarts Legacy**, and **Star Citizen** can use\n between **30,000 and 80,000** VMAs.\n\n- **Specialized Software:**\n - **Elasticsearch** requires a VMA limit of **262,144** (their arbitrarily\n selected number; simply 64x 4096). Their official packages [automatically](https://www.elastic.co/docs/deploy-manage/deploy/self-managed/vm-max-map-count)\n configure this VMA limit for your system upon installation. This number\n was determined to be safe by Elasticsearch, and is verified by a bootstrap\n check on every startup, to ensure that your system is suitable for\n production use.\n - **Docker Desktop** on Mac/Windows internally sets every container's limit\n to **262,144**, to accommodate running Elasticsearch inside a container.\n However, all native containers (whether Docker or Podman or something else)\n share the Linux kernel with the host machine. Therefore, if you're running on\n a Linux host, the container always inherits the exact same value as the host.\n\n\n### Recommended VMA Limit\n\n- If you want a custom-tailored recommendation for your own system, you can use\n `vmaudit` to analyze your system. Otherwise, use the recommendations below.\n- For **general Linux desktop** use, the kernel's default `vm.max_map_count` value\n of **65,530** is incredibly generous and will always work.\n- For **Wine/Proton gaming** use, setting `vm.max_map_count` to **120,000** is\n a safe and very generous value that will prevent issues with even the most\n VMA-intensive games and applications.\n- For **Elasticsearch** use, set `vm.max_map_count` to **262,144** (or **300,000**\n if you want a nice, round number), since it's the officially required value\n and provides plenty of headroom for very demanding search engine servers.\n- The value **does not need to be a power of two**. Any sufficiently large integer\n is correct.\n\n\n### Why Not Go Higher?\n\n- Setting `vm.max_map_count` to a very high number is dangerous. Each VMA is\n a non-swappable kernel data structure that consumes a small amount of memory.\n While negligible for a single VMA, this overhead can accumulate rapidly. This\n can exhaust the kernel's slab memory, leading to **kernel crashes**. High\n limits also degrade system performance, as managing and traversing millions\n of VMAs can **severely slow down** essential kernel operations such as regular\n housekeeping and common syscalls like `mmap()` and `munmap()`.\n- To make matters worse, the kernel's OOM (out-of-memory) handler doesn't take\n the kernel's internal VMA structs into account when deciding which processes\n to terminate, and will instead start terminating various high-memory desktop\n processes (or important background services) when the system is running out of\n memory. The malicious or misbehaving process that's responsible for allocating\n all the VMAs usually won't be terminated until it's too late.\n- This attack has been demonstrated with a proof-of-concept DoS (denial-of-service)\n application, which runs entirely in user-mode and is capable of crashing Linux\n by simply allocating lots of VMAs. It is especially dangerous for shared\n multi-user machines, such as servers, where a hostile user could then run\n a malicious binary to crash the entire server. The proof-of-concept attack\n code is available on [Fedora's mailing list](https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/YGTDBA2XENG7GSMHFYZQNIIGCGS3LQCD/).\n- In summary, setting the limit to an extreme value creates a **Denial-of-Service (DoS)**\n vulnerability, where a single **misbehaving or malicious user-space process**\n can consume vast amounts of kernel memory and very high CPU usage, thus bringing\n the entire system to a **crash or severe slowdown**.\n- While a moderate increase from the kernel's default 65,530 to something like\n 120,000 or 300,000 is reasonable for a few specific, very heavy workloads;\n raising the limit blindly to millions or billions of VMAs is mostly **cargo-cult**\n **paranoia**, and is both absolutely **pointless** and **poses a stability risk**.\n Always remember that typical Linux processes use less than 2,000 VMAs!\n\n\n### Changing Your System's VMA Limit\n\n- To view your current VMA limit, execute any of the following commands (or\n run `vmaudit`, which also analyzes your current limit).\n\n```sh\nsysctl vm.max_map_count\n\ncat /proc/sys/vm/max_map_count\n```\n\n- You can change the active limit for the current, running system by executing\n the following command (with your own value). This change will take effect\n immediately, but will be lost after a reboot.\n\n```sh\nsudo sysctl -w vm.max_map_count=120000\n```\n\n- You can make the change permanent by executing the following command, and then\n rebooting your system.\n\n```sh\necho \"vm.max_map_count=120000\" | sudo tee /etc/sysctl.d/90-vm_max_map_count.conf\n```\n\n\n## How to Install `vmaudit`\n\n- **Recommended:** Installing the package via pip.\n\n```sh\n# Only for the current user (will only be able to scan the current user's processes):\npip install vmaudit\n\n# Alternative: Global install to be able to scan all system processes (recommended).\nsudo pip install vmaudit\n```\n\n- **Alternative:** Installing the package directly from source.\n\n```sh\ngit clone https://github.com/Arcitec/vmaudit.git\ncd vmaudit\n\n# User installation.\npip install .\n\n# Alternative: Global installation (recommended).\nsudo pip install .\n```\n\n- Note: In all of these examples, it's recommended to replace the `pip` command\n with [pipx](https://pipx.pypa.io/stable/installation/) instead, which installs\n CLI tools into isolated environments for improved reliability. However, you\n should never run \"sudo pipx\", since the per-user pipx installation is runnable\n as root without needing to be installed globally.\n\n- If you ever want to remove the package again, run the `uninstall` command.\n\n```sh\n# User installation.\npip uninstall vmaudit\n\n# Alternative: If you've installed it globally.\nsudo pip uninstall vmaudit\n```\n\n- You can also run the package directly from source code without installing it.\n See the next section.\n\n\n## How to Use `vmaudit`\n\n- Running the virtual memory analyzer when it has been **installed as a package**.\n\n```sh\n# Scanning the current user's processes:\nvmaudit\n\n# Scanning all processes on the system:\n# NOTE: Only works if you've installed vmaudit via \"sudo pip\".\nsudo vmaudit\n\n# Alternative: Scanning all processes on the system (only for \"pipx\" installs):\nsudo \"$(which vmaudit)\"\n```\n\n- Alternative: Running **directly from source code**. Supports both user and\n system scans.\n\n```sh\n# Scanning the current user's processes:\npython src/vmaudit\n\n# Scanning all processes on the system:\nsudo python src/vmaudit\n```\n\n- If you know the **maximum number of VMAs** observed or expected for a process,\n then you can provide it directly to receive a custom recommendation.\n\n```sh\nvmaudit --vma 80000\n```\n\n- There are several other options to tweak the algorithm. However, the defaults\n are already correct, so most people will have no reason to change the parameters.\n\n```sh\nvmaudit -h\n```\n\n- Note: By default, the recommendation algorithm uses a very generous, overkill\n \"50% additional headroom\" recommendation to allow for huge, unpredictable\n memory usage fluctuations. If your workload is predictable, a headroom\n of \"25%\" is more reasonable, if you want to further optimize the limit for\n your particular usage.\n\n\n---\n\nThis project is licensed under the GPLv2 License.\nSee the [LICENSE](LICENSE) file for details.\n\nFind out how to [contribute](CONTRIBUTING.md) to this project.\n",
"bugtrack_url": null,
"license": null,
"summary": "Analyzes Virtual Memory Area (VMA) utilization to provide data-driven recommendations for system administrators and developers.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/Arcitec/vmaudit",
"Repository": "https://github.com/Arcitec/vmaudit.git"
},
"split_keywords": [
"analysis",
" audit",
" kernel",
" linux",
" linux tools",
" memory",
" memory usage",
" monitoring",
" performance",
" sysadmin",
" system administration",
" virtual memory",
" vm.max_map_count",
" vma",
" vmstat"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6d7e32795981d6836fdf24f29058d40861d78358ff666888f506598cafd3a003",
"md5": "26c8189c5e0e971f3f1603b82fc4979f",
"sha256": "fdef4438c124048032614fff24112d8247fe2524d465b366257c5ed870b9bd9b"
},
"downloads": -1,
"filename": "vmaudit-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "26c8189c5e0e971f3f1603b82fc4979f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 23648,
"upload_time": "2025-09-01T00:58:38",
"upload_time_iso_8601": "2025-09-01T00:58:38.192798Z",
"url": "https://files.pythonhosted.org/packages/6d/7e/32795981d6836fdf24f29058d40861d78358ff666888f506598cafd3a003/vmaudit-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6e7cde1301284af58218756cdd2880291df335f9a1b64e89822872ecd2fe8d67",
"md5": "3cce840bd97f6ca9d327eba3af912d29",
"sha256": "cb0e63b852c82ee2493aedf24f3fb5b40db342ffa0ceda5bb284458e35e2e725"
},
"downloads": -1,
"filename": "vmaudit-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "3cce840bd97f6ca9d327eba3af912d29",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22784,
"upload_time": "2025-09-01T00:58:39",
"upload_time_iso_8601": "2025-09-01T00:58:39.494975Z",
"url": "https://files.pythonhosted.org/packages/6e/7c/de1301284af58218756cdd2880291df335f9a1b64e89822872ecd2fe8d67/vmaudit-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 00:58:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Arcitec",
"github_project": "vmaudit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "vmaudit"
}
JSON
