Mirrors/criu
1
0
Fork 0
mirror of https://github.com/checkpoint-restore/criu.git synced 2026-07-17 16:47:50 +00:00
Code Issues Projects Releases Wiki Activity

docs: update Pidfd Store documentation

Browse source 
- Explain the PID reuse problem during iterative migration
- Document the use of pidfd_open() for race-free identification
- Detail the 'socket trick' for persistent FD storage via SCM_RIGHTS
- Explain the identity verification process in subsequent iterations
- List required kernel features (pidfd_open, pidfd_getfd)

Signed-off-by: Andrei Vagin <avagin@google.com>
This commit is contained in:
Andrei Vagin 2026-03-07 22:43:30 +00:00
parent 4a55bbd95d
commit 192fef5745
1 changed files with 31 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

43
Documentation/under-the-hood/pidfd-store.md
View file

@ -1,22 +1,41 @@
# Pidfd Store
# Pidfd Store: Reliable Process Identification
The `pidfd` store increases the reliability of PID reuse detection during pre-dumps and dumps by using task `pidfds` instead of task creation times.
The **Pidfd Store** is an internal CRIU mechanism used during iterative migration to reliably identify processes across multiple pre-dump iterations. It leverages the Linux kernel's `pidfd` interface to eliminate the risks associated with PID reuse.
This feature is supported only via RPC and the C library.
## The Problem: PID Reuse
## Usage
In an iterative migration workflow, CRIU performs multiple `pre-dump` operations. Each iteration captures memory pages that have changed since the previous snapshot. To do this safely, CRIU must ensure that it is still talking to the *exact same process* it was in the previous iteration.
A connectionless UNIX socket is passed to CRIU during each pre-dump or dump operation using the `pidfd_store_sk` RPC option or the `criu_set_pidfd_store_sk` library routine.
If a process dies between iterations and the kernel assigns its old PID to a new, unrelated process, a naive check based only on the PID would fail to detect this change. Performing an incremental dump on a new process using the state of an old one would lead to corrupted images and a failed restoration.
**NOTE**: This feature is intended for migration tools like P.Haul, as the provided socket must remain active throughout all pre-dump and dump iterations.
## How the Pidfd Store Works
## Feature Check
The Pidfd Store allows CRIU to maintain a persistent, race-free handle for every process in the tree.
This feature requires the `pidfd_open` and `pidfd_getfd` system calls. Support can be verified via:
### 1. Capturing Pidfds
During the first pre-dump, CRIU calls `pidfd_open()` for every task it captures. Unlike a numeric PID, a **pidfd** is a file descriptor that refers to a specific process *instance*. If that process terminates, its pidfd becomes invalid and will never refer to a subsequent process, even if the numeric PID is reused.
- **CLI**: `criu check --feature pidfd_store`
- **RPC**: Use `CRIU_REQ_TYPE__FEATURE_CHECK` and set `pidfd_store` to `true` in the `features` field of the request.
### 2. Persistent Storage via "The Socket Trick"
CRIU often operates as a service, receiving commands via RPC. To keep pidfds alive between independent RPC calls, CRIU uses a clever "socket trick":
* CRIU creates a Unix domain socket and connects it to itself.
* It "sends" the captured pidfds into this socket using the `SCM_RIGHTS` mechanism.
* The Linux kernel stores these file descriptors in the socket's internal buffer. Because the socket is connected to itself, the descriptors remain queued in the kernel until CRIU explicitly reads them back.
## How It Works
### 3. Identity Verification
In each subsequent `pre-dump` or the final `dump` command:
1. CRIU "drains" the pidfds from its internal storage socket.
2. It builds a hash table mapping PIDs to these stable pidfd handles.
3. Before capturing state for a PID, CRIU verifies the task against the stored pidfd.
4. If the pidfd is still valid, CRIU knows it is the same process and can safely perform an incremental memory dump.
5. If the pidfd is invalid or missing, CRIU detects a **PID reuse** event and treats the process as entirely new, performing a full dump to maintain consistency.
The `pidfd_store_sk` serves as a queue for task `pidfds`. CRIU sends task `pidfds` to this socket and retrieves them during the subsequent pre-dump or dump iteration. These `pidfds` are then used to verify if the task is still active. If the task is no longer alive, CRIU detects this as a PID reuse scenario and performs a full page dump.
## Kernel Requirements
The Pidfd Store requires modern kernel features (automatically detected via [Kerndat](kerndat.md)):
* `pidfd_open()` (Kernel v5.3+)
* `pidfd_getfd()` (Kernel v5.6+, used to transfer the storage socket between service components).
## See also
* [Memory Changes Tracking](memory-changes-tracking.md)
* [Iterative Migration](iterative-migration.md)
* [Kerndat](kerndat.md)