summaryrefslogtreecommitdiff
path: root/docs/source/markdown
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/markdown')
-rw-r--r--docs/source/markdown/podman-auto-update.1.md55
-rw-r--r--docs/source/markdown/podman-build.1.md18
-rw-r--r--docs/source/markdown/podman-container-cleanup.1.md2
-rw-r--r--docs/source/markdown/podman-create.1.md25
-rw-r--r--docs/source/markdown/podman-generate-systemd.1.md2
-rw-r--r--docs/source/markdown/podman-machine-start.1.md3
-rw-r--r--docs/source/markdown/podman-play-kube.1.md4
-rw-r--r--docs/source/markdown/podman-run.1.md32
-rw-r--r--docs/source/markdown/podman-save.1.md3
-rw-r--r--docs/source/markdown/podman-start.1.md29
-rw-r--r--docs/source/markdown/podman.1.md2
11 files changed, 152 insertions, 23 deletions
diff --git a/docs/source/markdown/podman-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md
index f82a1375c..f298d6bf6 100644
--- a/docs/source/markdown/podman-auto-update.1.md
+++ b/docs/source/markdown/podman-auto-update.1.md
@@ -9,21 +9,25 @@ podman-auto-update - Auto update containers according to their auto-update polic
## DESCRIPTION
`podman auto-update` looks up containers with a specified "io.containers.autoupdate" label (i.e., the auto-update policy).
-If the label is present and set to "image", Podman reaches out to the corresponding registry to check if the image has been updated.
+If the label is present and set to "registry", Podman reaches out to the corresponding registry to check if the image has been updated.
+The label "image" is an alternative to "registry" maintained for backwards compatibility.
An image is considered updated if the digest in the local storage is different than the one of the remote image.
If an image must be updated, Podman pulls it down and restarts the systemd unit executing the container.
+The registry policy requires a requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container.
+This enforcement is necessary to know which image to actually check and pull.
+If an image ID was used, Podman would not know which image to check/pull anymore.
+
+Alternatively, if the autoupdate label is set to "local", Podman will compare the image a container is using to the image with it's raw name in local storage.
+If an image is updated locally, Podman simply restarts the systemd unit executing the container.
+
If "io.containers.autoupdate.authfile" label is present, Podman reaches out to corresponding authfile when pulling images.
At container-creation time, Podman looks up the "PODMAN_SYSTEMD_UNIT" environment variables and stores it verbatim in the container's label.
This variable is now set by all systemd units generated by `podman-generate-systemd` and is set to `%n` (i.e., the name of systemd unit starting the container).
This data is then being used in the auto-update sequence to instruct systemd (via DBUS) to restart the unit and hence to restart the container.
-Note that `podman auto-update` relies on systemd and requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container.
-This enforcement is necessary to know which image to actually check and pull.
-If an image ID was used, Podman would not know which image to check/pull anymore.
-
-Moreover, the systemd units are expected to be generated with `podman-generate-systemd --new`, or similar units that create new containers in order to run the updated images.
+Note that`podman auto-update` relies on systemd. The systemd units are expected to be generated with `podman-generate-systemd --new`, or similar units that create new containers in order to run the updated images.
Systemd units that start and stop a container cannot run a new image.
@@ -44,9 +48,11 @@ environment variable. `export REGISTRY_AUTH_FILE=path`
## EXAMPLES
+Autoupdate with registry policy
+
```
# Start a container
-$ podman run --label "io.containers.autoupdate=image" \
+$ podman run --label "io.containers.autoupdate=registry" \
--label "io.containers.autoupdate.authfile=/some/authfile.json" \
-d busybox:latest top
bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
@@ -70,5 +76,40 @@ $ podman auto-update
container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service
```
+Autoupdate with local policy
+
+```
+# Start a container
+$ podman run --label "io.containers.autoupdate=local" \
+ -d busybox:latest top
+be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
+
+# Generate a systemd unit for this container
+$ podman generate systemd --new --files be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
+/home/user/containers/libpod/container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service
+
+# Load the new systemd unit and start it
+$ mv ./container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service ~/.config/systemd/user
+$ systemctl --user daemon-reload
+
+# If the previously created containers or pods are using shared resources, such as ports, make sure to remove them before starting the generated systemd units.
+$ podman stop be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
+$ podman rm be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338
+
+$ systemctl --user start container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service
+
+# Get the name of the container
+$ podman ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+01f5c8113e84 docker.io/library/busybox:latest top 2 seconds ago Up 3 seconds ago inspiring_galileo
+
+# Modify the image
+$ podman commit --change CMD=/bin/bash inspiring_galileo busybox:latest
+
+# Auto-update the container
+$ podman auto-update
+container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service
+```
+
## SEE ALSO
podman(1), podman-generate-systemd(1), podman-run(1), systemd.unit(5)
diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index 791e2d907..9fc4ffb5b 100644
--- a/docs/source/markdown/podman-build.1.md
+++ b/docs/source/markdown/podman-build.1.md
@@ -381,12 +381,6 @@ BUILDAH\_LAYERS environment variable. `export BUILDAH_LAYERS=true`
Log output which would be sent to standard output and standard error to the
specified file instead of to standard output and standard error.
-#### **\-\-loglevel**=*number*
-
-Adjust the logging level up or down. Valid option values range from -2 to 3,
-with 3 being roughly equivalent to using the global *--debug* option, and
-values below 0 omitting even error messages which accompany fatal errors.
-
#### **\-\-manifest** "manifest"
Name of the manifest list to which the image will be added. Creates the manifest list
@@ -490,6 +484,18 @@ commands specified by the **RUN** instruction.
Note: You can also override the default runtime by setting the BUILDAH\_RUNTIME
environment variable. `export BUILDAH_RUNTIME=/usr/local/bin/runc`
+
+#### **\-\-secret**=**id=id,src=path**
+
+Pass secret information to be used in the Containerfile for building images
+in a safe way that will not end up stored in the final image, or be seen in other stages.
+The secret will be mounted in the container at the default location of `/run/secrets/id`.
+
+To later use the secret, use the --mount flag in a `RUN` instruction within a `Containerfile`:
+
+`RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret`
+
+
#### **\-\-security-opt**=*option*
Security Options
diff --git a/docs/source/markdown/podman-container-cleanup.1.md b/docs/source/markdown/podman-container-cleanup.1.md
index bd650c6af..9f9b90fc2 100644
--- a/docs/source/markdown/podman-container-cleanup.1.md
+++ b/docs/source/markdown/podman-container-cleanup.1.md
@@ -48,7 +48,7 @@ After cleanup, remove the image entirely.
`podman container cleanup --latest`
## SEE ALSO
-podman(1), podman-container(1)
+**podman**(1), **podman-container**(1), **conmon**(8).
## HISTORY
Jun 2018, Originally compiled by Dan Walsh <dwalsh@redhat.com>
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index 7e1d0be4a..d59793f28 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -887,8 +887,7 @@ Note: Labeling can be disabled for all containers by setting label=false in the
- `proc-opts=OPTIONS` : Comma-separated list of options to use for the /proc mount. More details for the
possible mount options are specified in the **proc(5)** man page.
-- `unmask=ALL or /path/1:/path/2` : Paths to unmask separated by a colon. If set to **ALL**, it will
- unmask all the paths that are masked or made read only by default.
+- **unmask**=_ALL_ or _/path/1:/path/2_, or shell expanded paths (/proc/*): Paths to unmask separated by a colon. If set to **ALL**, it will unmask all the paths that are masked or made read only by default.
The default masked paths are **/proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux.** The default paths that are read only are **/proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup**.
Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file.
@@ -956,6 +955,12 @@ The `container_manage_cgroup` boolean must be enabled for this to be allowed on
`setsebool -P container_manage_cgroup true`
+#### **\-\-timeout**=*seconds*
+
+Maximum time a container is allowed to run before conmon sends it the kill
+signal. By default containers will run until they exit or are stopped by
+`podman stop`.
+
#### **\-\-tmpfs**=*fs*
Create a tmpfs mount
@@ -1417,6 +1422,20 @@ $ podman start --attach ctr
b
```
+## CONMON
+
+When Podman starts a container it actually executes the conmon program, which
+then executes the OCI Runtime. Conmon is the container monitor. It is a small
+program whose job is to watch the primary process of the container, and if the
+container dies, save the exit code. It also holds open the tty of the
+container, so that it can be attached to later. This is what allows Podman to
+run in detached mode (backgrounded), so Podman can exit but conmon continues to
+run. Each container has their own instance of conmon. Conmon waits for the
+container to exit, gathers and saves the exit code, and then launches a Podman
+process to complete the container cleanup, by shutting down the network and
+storage. For more information on conmon, please reference the conmon(8) man
+page.
+
## FILES
**/etc/subuid**
@@ -1426,7 +1445,7 @@ NOTE: Use the environment variable `TMPDIR` to change the temporary storage loca
## SEE ALSO
**podman**(1), **podman-secret**(1), **podman-save**(1), **podman-ps**(1), **podman-attach**(1), **podman-pod-create**(1), **podman-port**(1), **podman-start*(1), **podman-kill**(1), **podman-stop**(1),
-**podman-generate-systemd**(1) **podman-rm**(1), **subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5)**.
+**podman-generate-systemd**(1) **podman-rm**(1), **subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5), **conmon**(8).
## HISTORY
October 2017, converted from Docker documentation to Podman by Dan Walsh for Podman `<dwalsh@redhat.com>`
diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md
index 431163d56..1d427d35b 100644
--- a/docs/source/markdown/podman-generate-systemd.1.md
+++ b/docs/source/markdown/podman-generate-systemd.1.md
@@ -233,7 +233,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS
bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
```
## SEE ALSO
-[podman(1)](podman.1.md), [podman-container(1)](podman-container.1.md), systemctl(1), systemd.unit(5), systemd.service(5)
+[**podman**(1)](podman.1.md), [**podman-container**(1)](podman-container.1.md), **systemctl**(1), **systemd.unit**(5), **systemd.service**(5), **conmon**(8).
## HISTORY
April 2020, Updated details and added usecase to use generated .service files as root and non-root, by Sujil Shah (sushah at redhat dot com)
diff --git a/docs/source/markdown/podman-machine-start.1.md b/docs/source/markdown/podman-machine-start.1.md
index 22942767a..b430f51eb 100644
--- a/docs/source/markdown/podman-machine-start.1.md
+++ b/docs/source/markdown/podman-machine-start.1.md
@@ -14,6 +14,9 @@ Podman on MacOS requires a virtual machine. This is because containers are Linux
containers do not run on any other OS because containers' core functionality are
tied to the Linux kernel.
+Only one Podman managed VM can be active at a time. If a VM is already running,
+`podman machine start` will return an error.
+
**podman machine start** starts a Linux virtual machine where containers are run.
## OPTIONS
diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md
index 1074c27f8..ab2019139 100644
--- a/docs/source/markdown/podman-play-kube.1.md
+++ b/docs/source/markdown/podman-play-kube.1.md
@@ -70,6 +70,10 @@ Assign a static ip address to the pod. This option can be specified several time
Set logging driver for all created containers.
+#### **\-\-mac-address**=*MAC address*
+
+Assign a static mac address to the pod. This option can be specified several times when play kube creates more than one pod.
+
#### **\-\-network**=*networks*, **\-\-net**
A comma-separated list of the names of CNI networks the pod should join.
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 56ca8fde0..0ab8f04db 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -939,8 +939,7 @@ Note: Labeling can be disabled for all containers by setting label=false in the
- **proc-opts**=_OPTIONS_ : Comma-separated list of options to use for the /proc mount. More details
for the possible mount options are specified in the **proc(5)** man page.
-- **unmask**=_ALL_ or _/path/1:/path/2_: Paths to unmask separated by a colon. If set to **ALL**, it will
- unmask all the paths that are masked or made read only by default.
+- **unmask**=_ALL_ or _/path/1:/path/2_, or shell expanded paths (/proc/*): Paths to unmask separated by a colon. If set to **ALL**, it will unmask all the paths that are masked or made read only by default.
The default masked paths are **/proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux.**. The default paths that are read only are **/proc/asound**, **/proc/bus**, **/proc/fs**, **/proc/irq**, **/proc/sys**, **/proc/sysrq-trigger**, **/sys/fs/cgroup**.
Note: Labeling can be disabled for all containers by setting **label=false** in the **containers.conf**(5) file.
@@ -1029,6 +1028,12 @@ The **container_manage_cgroup** boolean must be enabled for this to be allowed o
setsebool -P container_manage_cgroup true
```
+#### **\-\-timeout**=*seconds*
+
+Maximum time a container is allowed to run before conmon sends it the kill
+signal. By default containers will run until they exit or are stopped by
+`podman stop`.
+
#### **\-\-tmpfs**=*fs*
Create a tmpfs mount.
@@ -1643,6 +1648,13 @@ the **mask** option.
$ podman run --security-opt unmask=ALL fedora bash
```
+To unmask all the paths that start with /proc, set the **unmask** option to
+**/proc/***.
+
+```
+$ podman run --security-opt unmask=/proc/* fedora bash
+```
+
```
$ podman run --security-opt unmask=/foo/bar:/sys/firmware fedora bash
```
@@ -1768,6 +1780,20 @@ $ podman run --env ENV*****=b alpine printenv ENV*****
b
```
+## CONMON
+
+When Podman starts a container it actually executes the conmon program, which
+then executes the OCI Runtime. Conmon is the container monitor. It is a small
+program whose job is to watch the primary process of the container, and if the
+container dies, save the exit code. It also holds open the tty of the
+container, so that it can be attached to later. This is what allows Podman to
+run in detached mode (backgrounded), so Podman can exit but conmon continues to
+run. Each container has their own instance of conmon. Conmon waits for the
+container to exit, gathers and saves the exit code, and then launches a Podman
+process to complete the container cleanup, by shutting down the network and
+storage. For more information on conmon, please reference the conmon(8) man
+page.
+
## FILES
**/etc/subuid**
@@ -1778,7 +1804,7 @@ NOTE: Use the environment variable `TMPDIR` to change the temporary storage loca
## SEE ALSO
**podman**(1), **podman-save**(1), **podman-ps**(1), **podman-attach**(1), **podman-pod-create**(1), **podman-port**(1), **podman-start**(1), **podman-kill**(1), **podman-stop**(1),
-**podman-generate-systemd**(1) **podman-rm**(1), **subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5)**.
+**podman-generate-systemd**(1) **podman-rm**(1), **subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5), **conmon**(8).
## HISTORY
September 2018, updated by Kunal Kushwaha `<kushwaha_kunal_v7@lab.ntt.co.jp>`
diff --git a/docs/source/markdown/podman-save.1.md b/docs/source/markdown/podman-save.1.md
index 0036a9379..cae0c4b05 100644
--- a/docs/source/markdown/podman-save.1.md
+++ b/docs/source/markdown/podman-save.1.md
@@ -45,6 +45,7 @@ Save image to **oci-archive, oci-dir** (directory with oci manifest type), or **
#### **\-\-multi-image-archive**, **-m**
Allow for creating archives with more than one image. Additional names will be interpreted as images instead of tags. Only supported for **docker-archive**.
+The default for this option can be modified via the `multi_image_archive="true"|"false"` flag in containers.conf.
#### **\-\-quiet**, **-q**
@@ -99,7 +100,7 @@ Storing signatures
```
## SEE ALSO
-podman(1), podman-load(1)
+podman(1), podman-load(1), containers.conf(5)
## HISTORY
July 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com>
diff --git a/docs/source/markdown/podman-start.1.md b/docs/source/markdown/podman-start.1.md
index 1822eab34..7085f3f47 100644
--- a/docs/source/markdown/podman-start.1.md
+++ b/docs/source/markdown/podman-start.1.md
@@ -38,6 +38,35 @@ to run containers such as CRI-O, the last started container could be from either
Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true* when attaching, *false* otherwise.
+#### **\-\-all**
+
+Start all the containers created by Podman, default is only running containers.
+
+#### **\-\-filter**, **-f**
+
+Filter what containers are going to be started from the given arguments.
+Multiple filters can be given with multiple uses of the --filter flag.
+Filters with the same key work inclusive with the only exception being
+`label` which is exclusive. Filters with different keys always work exclusive.
+
+Valid filters are listed below:
+
+| **Filter** | **Description** |
+| --------------- | -------------------------------------------------------------------------------- |
+| id | [ID] Container's ID (accepts regex) |
+| name | [Name] Container's name (accepts regex) |
+| label | [Key] or [Key=Value] Label assigned to a container |
+| exited | [Int] Container's exit code |
+| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' |
+| ancestor | [ImageName] Image or descendant used to create container |
+| before | [ID] or [Name] Containers created before this container |
+| since | [ID] or [Name] Containers created since this container |
+| volume | [VolumeName] or [MountpointDestination] Volume mounted in container |
+| health | [Status] healthy or unhealthy |
+| pod | [Pod] name or full or partial ID of pod |
+| network | [Network] name or full ID of network |
+
+
## EXAMPLE
podman start mywebserver
diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md
index 87bcd8802..3b90a0922 100644
--- a/docs/source/markdown/podman.1.md
+++ b/docs/source/markdown/podman.1.md
@@ -343,7 +343,7 @@ The Network File System (NFS) and other distributed file systems (for example: L
For more information, please refer to the [Podman Troubleshooting Page](https://github.com/containers/podman/blob/master/troubleshooting.md).
## SEE ALSO
-`containers-mounts.conf(5)`, `containers-registries.conf(5)`, `containers-storage.conf(5)`, `buildah(1)`, `containers.conf(5)`, `oci-hooks(5)`, `containers-policy.json(5)`, `crun(8)`, `runc(8)`, `subuid(5)`, `subgid(5)`, `slirp4netns(1)`
+**containers-mounts.conf**(5), **containers-registries.conf**(5), **containers-storage.conf**(5), **buildah**(1), **containers.conf**(5), **oci-hooks**(5), **containers-policy.json**(5), **crun**(8), **runc**(8), **subuid**(5), **subgid**(5), **slirp4netns**(1), **conmon**(8).
## HISTORY
Dec 2016, Originally compiled by Dan Walsh <dwalsh@redhat.com>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-10-01 04:44:38 +0000