From d26341332cec996af0c98ecde6ba27d78d393251 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Fri, 2 Aug 2024 09:41:24 -0400 Subject: [PATCH] docs/podman-systemd: Try to clarify `Exec=` more In podman-systemd we are intersecting the worlds of containers and systemd, and I had to stop and think to understand what `Exec=` does. I tried to clarify things more here. I found it especially confusing because the example at the very top of the file does: ``` Image=quay.io/fedora/fedora Exec=sleep 10 ``` But that only makes sense because the fedora base image (being generic) doesn't define an `ENTRYPOINT`, just a `CMD`. But IMO by far the most common usage for podman-systemd is "app images" which conventionally should use `ENTRYPOINT` in general. Maybe we should change the default example, but I'm leaving that for a later followup. (It perhaps would have been less confusing if this field had been called `Args=` to make clear it's quite different in practice from systemd `ExecStart=`) Signed-off-by: Colin Walters --- docs/source/markdown/podman-systemd.unit.5.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/source/markdown/podman-systemd.unit.5.md b/docs/source/markdown/podman-systemd.unit.5.md index 6490554acd..c16d46361c 100644 --- a/docs/source/markdown/podman-systemd.unit.5.md +++ b/docs/source/markdown/podman-systemd.unit.5.md @@ -435,9 +435,19 @@ Use the host environment inside of the container. ### `Exec=` -If this is set then it defines what command line to run in the container. If it is not set the -default entry point of the container image is used. The format is the same as for -[systemd command lines](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines). +Additional arguments for the container; this has exactly the same effect as passing +more arguments after a `podman run ` invocation. + +The format is the same as for [systemd command lines](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines), +However, unlike the usage scenario for similarly-named systemd `ExecStart=` verb +which operates on the ambient root filesystem, it is very common for container +images to have their own `ENTRYPOINT` or `CMD` metadata which this +which this interacts with. + +The default expectation for many images is that the image will include an `ENTRYPOINT` +with a default binary, and this field will add arguments to that entrypoint. + +Another way to describe this is that it works the same way as the [args field in a Kubernetes pod](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell). ### `ExposeHostPort=`