Files
podman/docs/source/markdown/options/pidfile.md
T
Marek Nogacki d5ff562f83 Add --pidfile flag to podman start
create and run already take --pidfile, but the path is fixed at create
time and reused on every start. Toolbx wants a fresh path per start so it
can learn the PID of the container's entry point, which names the stamp
file the entry point creates once it is initialized, before running
podman exec.

Add the same flag to start. libpod's Container.Start now returns the PID
of the container's main process, read while the container lock is still
held right after the OCI runtime started it, so the value always belongs
to the process this start launched. For a container that is already
running it returns the PID of that process together with
ErrCtrStateRunning, read under the same lock that saw the running state.
start --pidfile writes this PID to the requested path.

The flag only works for a single container and is rejected together with
--attach. As documented for create and run --pidfile, it is not
available on the remote client; start returns an error there rather than
silently ignoring the flag.

Fixes: #25849
Signed-off-by: Marek Nogacki <no.marek@gmail.com>
2026-09-15 16:05:19 +02:00

1.0 KiB

####> This option file is used in: ####> podman create, run, start ####> If file is edited, make sure the changes ####> are applicable to all of those.

--pidfile=path

When the pidfile location is specified, the container process' PID is written to the pidfile. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) If the pidfile option is not specified, the container process' PID is written to /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile.

After the container is started, the location for the pidfile can be discovered with the following podman inspect command:

$ podman inspect --format '{{ .PidFile }}' $CID
/run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile

With podman start, the pidfile is written for that start only: the path is not saved to the container configuration, so podman inspect keeps reporting the path from podman create or podman run (or the default location) rather than the one given here.