This is an automated email from the ASF dual-hosted git repository.
kparisa pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iggy-website.git
The following commit(s) were added to refs/heads/main by this push:
new d066afc8e docs: state the minimum Linux kernel version (#105)
d066afc8e is described below
commit d066afc8e90a5566efbc4b5429101e851cfe5d58
Author: Justin Mclean <[email protected]>
AuthorDate: Wed Sep 16 14:19:56 2026 +1000
docs: state the minimum Linux kernel version (#105)
The server creates its io_uring rings with setup flags that need Linux
5.19, and refuses to start on anything older, but no page said so.
Ubuntu 22.04 ships 5.15, which is how people hit this.
Co-authored-by: Justin Mclean <[email protected]>
Co-authored-by: Kranti Parisa <[email protected]>
---
content/docs/introduction/getting-started.mdx | 2 +-
content/docs/server/docker.mdx | 1 +
content/docs/server/introduction.mdx | 12 ++++++++++++
3 files changed, 14 insertions(+), 1 deletion(-)
diff --git a/content/docs/introduction/getting-started.mdx
b/content/docs/introduction/getting-started.mdx
index 09d0d7334..3532f739f 100644
--- a/content/docs/introduction/getting-started.mdx
+++ b/content/docs/introduction/getting-started.mdx
@@ -33,7 +33,7 @@ docker run --rm \
apache/iggy:0.9.0
```
-The capabilities, seccomp setting, and memlock limit form a permissive
development setup. Production deployments can use narrower syscall permissions
and a finite memory budget; see [Docker &
Helm](/docs/server/docker#why-these-capabilities) for the details.
`IGGY_TCP_ADDRESS` is needed because the server binds to `127.0.0.1` inside the
container by default, which a published port cannot reach.
`IGGY_NODE_ADVERTISED_ADDRESS` is needed because that wildcard leaves the
server with no addre [...]
+The container needs a host kernel of 5.19 or newer, because the server uses
`io_uring`; see [System
requirements](/docs/server/introduction#system-requirements) if it fails to
start. The capabilities, seccomp setting, and memlock limit form a permissive
development setup. Production deployments can use narrower syscall permissions
and a finite memory budget; see [Docker &
Helm](/docs/server/docker#why-these-capabilities) for the details.
`IGGY_TCP_ADDRESS` is needed because the server bi [...]
Alternatively, build from source by cloning the
[repository](https://github.com/apache/iggy) and running:
diff --git a/content/docs/server/docker.mdx b/content/docs/server/docker.mdx
index f39ce4957..f8e7e9414 100644
--- a/content/docs/server/docker.mdx
+++ b/content/docs/server/docker.mdx
@@ -67,6 +67,7 @@ docker run -d --name iggy \
- **`SYS_NICE`** broadens scheduling and NUMA permissions. Pinning a thread
owned by the process with `sched_setaffinity` does not by itself require this
capability; container policies can impose additional restrictions. See [Linux
affinity
permissions](https://man7.org/linux/man-pages/man2/sched_setaffinity.2.html).
- **`seccomp:unconfined`** permits `io_uring` calls blocked by Docker's
default seccomp profile. A custom profile allowing the required syscalls is an
alternative to disabling filtering. See [Docker seccomp
profiles](https://docs.docker.com/engine/security/seccomp/).
- **`memlock: -1`** removes the process's locked-memory limit. A finite limit
is valid if it covers the runtime's requirements; neither setting overrides the
container's memory limit.
+- **Host kernel 5.19 or newer** is required. Containers use the host's kernel,
so these settings alone are not enough. See [System
requirements](/docs/server/introduction#system-requirements).
### Available images
diff --git a/content/docs/server/introduction.mdx
b/content/docs/server/introduction.mdx
index adbfbfed7..e8b87fe4d 100644
--- a/content/docs/server/introduction.mdx
+++ b/content/docs/server/introduction.mdx
@@ -11,6 +11,18 @@ The releases are published to GitHub and can be found
[here](https://github.com/
If you compile the source code in release mode, linking takes longer because
[LTO](https://doc.rust-lang.org/cargo/reference/profiles.html#lto) is enabled
in the `[profile.release]` section of the workspace
[Cargo.toml](https://github.com/apache/iggy/blob/master/Cargo.toml).
+## System requirements
+
+The server uses `io_uring` on Linux, which sets a minimum kernel version.
+
+- **Linux kernel 5.19 or newer is required.** The shard executors create their
rings with `IORING_SETUP_COOP_TASKRUN` and `IORING_SETUP_TASKRUN_FLAG`, which
older kernels reject, and the server refuses to start rather than run without
them. Check yours with `uname -r`.
+- **Kernel 6.1 or newer is worth having.** It is the first version with the
`kernel.io_uring_disabled` sysctl, so the startup diagnostics can tell you
io_uring was disabled by policy instead of failing obscurely. See [Linux
tuning](/docs/server/linux-tuning#runtime-access-and-process-limits).
+- **Ubuntu 22.04 LTS ships 5.15 and will not run the server.** Its hardware
enablement kernel is new enough, and so are Ubuntu 24.04 LTS and Debian 12 as
they ship.
+- **WSL2 often ships incomplete `io_uring`**, missing setup flags or
operations even on a kernel that reports 5.19 or newer. Run `wsl --update`
first.
+- **macOS uses a polling backend** rather than `io_uring`, so this requirement
does not apply there.
+
+Containers use the host's kernel, so it is the host that has to meet this
requirement. See [Docker & Helm](/docs/server/docker#why-these-capabilities).
+
## Running the server
One `iggy-server` binary serves both the single-node and the clustered
deployment. The loaded configuration decides which one you get. The server
accepts these startup flags, plus `--help` and `--version`:
