summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/source/_static/api.html2
-rw-r--r--docs/source/markdown/podman-container-checkpoint.1.md18
-rw-r--r--docs/source/markdown/podman-container-restore.1.md10
-rw-r--r--docs/source/markdown/podman-create.1.md37
-rw-r--r--docs/source/markdown/podman-pod-create.1.md9
-rw-r--r--docs/source/markdown/podman-run.1.md42
-rw-r--r--docs/source/markdown/podman-search.1.md2
-rw-r--r--docs/tutorials/mac_experimental.md2
8 files changed, 96 insertions, 26 deletions
diff --git a/docs/source/_static/api.html b/docs/source/_static/api.html
index fbc945d87..6d467d099 100644
--- a/docs/source/_static/api.html
+++ b/docs/source/_static/api.html
@@ -18,7 +18,7 @@
</style>
</head>
<body>
- <redoc spec-url='https://storage.googleapis.com/libpod-master-releases/swagger-latest.yaml' sort-props-alphabetically></redoc>
+ <redoc spec-url='https://storage.googleapis.com/libpod-master-releases/swagger-latest.yaml' sort-props-alphabetically sort-operations-alphabetically></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
diff --git a/docs/source/markdown/podman-container-checkpoint.1.md b/docs/source/markdown/podman-container-checkpoint.1.md
index 200920ca9..00d8f7095 100644
--- a/docs/source/markdown/podman-container-checkpoint.1.md
+++ b/docs/source/markdown/podman-container-checkpoint.1.md
@@ -9,6 +9,8 @@ podman\-container\-checkpoint - Checkpoints one or more running containers
## DESCRIPTION
**podman container checkpoint** checkpoints all the processes in one or more *containers*. A *container* can be restored from a checkpoint with **[podman-container-restore](podman-container-restore.1.md)**. The *container IDs* or *names* are used as input.
+*IMPORTANT: If the container is using __systemd__ as __entrypoint__ checkpointing the container might not be possible.*
+
## OPTIONS
#### **--all**, **-a**
@@ -37,7 +39,7 @@ root file-system, if not explicitly disabled using **--ignore-rootfs**.
If a checkpoint is exported to a tar.gz file it is possible with the help of **--ignore-rootfs** to explicitly disable including changes to the root file-system into the checkpoint archive file.\
The default is **false**.\
-*IMPORTANT: This OPTION only works in combination with **--export, -e**.*
+*IMPORTANT: This OPTION only works in combination with __--export, -e__.*
#### **--ignore-volumes**
@@ -68,6 +70,13 @@ Dump the *container's* memory information only, leaving the *container* running.
operations will supersede prior dumps. It only works on `runc 1.0-rc3` or `higher`.\
The default is **false**.
+The functionality to only checkpoint the memory of the container and in a second
+checkpoint only write out the memory pages which have changed since the first
+checkpoint relies on the Linux kernel's soft-dirty bit, which is not available
+on all systems as it depends on the system architecture and the configuration
+of the Linux kernel. Podman will verify if the current system supports this
+functionality and return an error if the current system does not support it.
+
#### **--print-stats**
Print out statistics about checkpointing the container(s). The output is
@@ -122,8 +131,13 @@ The default is **false**.
Check out the *container* with previous criu image files in pre-dump. It only works on `runc 1.0-rc3` or `higher`.\
The default is **false**.\
-*IMPORTANT: This OPTION is not available with **--pre-checkpoint***.
+*IMPORTANT: This OPTION is not available with __--pre-checkpoint__*.
+
+This option requires that the option __--pre-checkpoint__ has been used before on the
+same container. Without an existing pre-checkpoint, this option will fail.
+Also see __--pre-checkpoint__ for additional information about __--pre-checkpoint__
+availability on different systems.
## EXAMPLES
Make a checkpoint for the container "mywebserver".
diff --git a/docs/source/markdown/podman-container-restore.1.md b/docs/source/markdown/podman-container-restore.1.md
index a4630dedf..3dfa063b8 100644
--- a/docs/source/markdown/podman-container-restore.1.md
+++ b/docs/source/markdown/podman-container-restore.1.md
@@ -39,7 +39,7 @@ The default is **false**.\
If a *container* is restored from a checkpoint tar.gz file it is possible that it also contains all root file-system changes. With **--ignore-rootfs** it is possible to explicitly disable applying these root file-system changes to the restored *container*.\
The default is **false**.\
-*IMPORTANT: This OPTION is only available in combination with **--import, -i**.*
+*IMPORTANT: This OPTION is only available in combination with __--import, -i__.*
#### **--ignore-static-ip**
@@ -98,14 +98,14 @@ If the **--name, -n** option is used, Podman will not attempt to assign the same
address to the *container* it was using before checkpointing as each IP address can only
be used once and the restored *container* will have another IP address. This also means
that **--name, -n** cannot be used in combination with **--tcp-established**.\
-*IMPORTANT: This OPTION is only available in combination with **--import, -i**.*
+*IMPORTANT: This OPTION is only available in combination with __--import, -i__.*
#### **--pod**=*name*
Restore a container into the pod *name*. The destination pod for this restore
has to have the same namespaces shared as the pod this container was checkpointed
-from (see **[podman pod create --share](podman-pod-create.1.md#--share)**).
-*IMPORTANT: This OPTION is only available in combination with **--import, -i**.*
+from (see **[podman pod create --share](podman-pod-create.1.md#--share)**).\
+*IMPORTANT: This OPTION is only available in combination with __--import, -i__.*
This option requires at least CRIU 3.16.
@@ -168,7 +168,7 @@ Import a checkpoint file and a pre-checkpoint file.
# podman container restore --import-previous pre-checkpoint.tar.gz --import checkpoint.tar.gz
```
-Remove the container "mywebserver". Make a checkpoint of the container and export it. Restore the container with other port ranges from the exported file.
+Start the container "mywebserver". Make a checkpoint of the container and export it. Restore the container with other port ranges from the exported file.
```
$ podman run --rm -p 2345:80 -d webserver
# podman container checkpoint -l --export=dump.tar
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index c8f1ec3a5..e3647b194 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -410,6 +410,11 @@ Container host name
Sets the container host name that is available inside the container. Can only be used with a private UTS namespace `--uts=private` (default). If `--pod` is specified and the pod shares the UTS namespace (default) the pod's hostname will be used.
+#### **--hostuser**=*name*
+
+Add a user account to /etc/passwd from the host to the container. The Username
+or UID must exist on the host system.
+
#### **--help**
Print usage statement
@@ -469,19 +474,24 @@ Path to the container-init binary.
Keep STDIN open even if not attached. The default is *false*.
-#### **--ip6**=*ip*
-
-Not implemented
+#### **--ip**=*ipv4*
-#### **--ip**=*ip*
-
-Specify a static IP address for the container, for example **10.88.64.128**.
+Specify a static IPv4 address for the container, for example **10.88.64.128**.
This option can only be used if the container is joined to only a single network - i.e., **--network=network-name** is used at most once -
and if the container is not joining another container's network namespace via **--network=container:_id_**.
The address must be within the network's IP address pool (default **10.88.0.0/16**).
To specify multiple static IP addresses per container, set multiple networks using the **--network** option with a static IP address specified for each using the `ip` mode for that option.
+#### **--ip6**=*ipv6*
+
+Specify a static IPv6 address for the container, for example **fd46:db93:aa76:ac37::10**.
+This option can only be used if the container is joined to only a single network - i.e., **--network=network-name** is used at most once -
+and if the container is not joining another container's network namespace via **--network=container:_id_**.
+The address must be within the network's IPv6 address pool.
+
+To specify multiple static IPv6 addresses per container, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option.
+
#### **--ipc**=*ipc*
@@ -949,12 +959,13 @@ Note: Labeling can be disabled for all containers by setting label=false in the
- `no-new-privileges` : Disable container processes from gaining additional privileges
-- `seccomp=unconfined` : Turn off seccomp confinement for the container
-- `seccomp=profile.json` : White listed syscalls seccomp Json file to be used as a seccomp filter
+- `seccomp=unconfined` : Turn off seccomp confinement for the container.
+- `seccomp=profile.json` : JSON file to be used as a seccomp filter. Note that the `io.podman.annotations.seccomp` annotation is set with the specified value as shown in `podman inspect`.
- `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_, 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**.
@@ -1142,10 +1153,20 @@ If for example _amount_ is **5** the second mapping step would look like:
| _from_uid_ + 3 | _container_uid_ + 3 |
| _from_uid_ + 4 | _container_uid_ + 4 |
+The current user ID is mapped to UID=0 in the rootless user namespace.
+Every additional range is added sequentially afterward:
+
+| host |rootless user namespace | length |
+| - | - | - |
+| $UID | 0 | 1 |
+| 1 | $FIRST_RANGE_ID | $FIRST_RANGE_LENGTH |
+| 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID | $SECOND_RANGE_LENGTH|
+
Even if a user does not have any subordinate UIDs in _/etc/subuid_,
**--uidmap** could still be used to map the normal UID of the user to a
container UID by running `podman create --uidmap $container_uid:0:1 --user $container_uid ...`.
+
#### **--ulimit**=*option*
Ulimit options
diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md
index b1b029429..56c3e7d34 100644
--- a/docs/source/markdown/podman-pod-create.1.md
+++ b/docs/source/markdown/podman-pod-create.1.md
@@ -127,6 +127,15 @@ The address must be within the network's IP address pool (default **10.88.0.0/16
To specify multiple static IP addresses per pod, set multiple networks using the **--network** option with a static IP address specified for each using the `ip` mode for that option.
+#### **--ip6**=*ipv6*
+
+Specify a static IPv6 address for the pod, for example **fd46:db93:aa76:ac37::10**.
+This option can only be used if the pod is joined to only a single network - i.e., **--network=network-name** is used at most once -
+and if the pod is not joining another container's network namespace via **--network=container:_id_**.
+The address must be within the network's IPv6 address pool.
+
+To specify multiple static IPv6 addresses per pod, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option.
+
#### **--label**=*label*, **-l**
Add metadata to a pod (e.g., --label com.example.key=value).
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index a6687e656..b98e563ef 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -446,6 +446,11 @@ The initialization time needed for a container to bootstrap. The value can be ex
The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the
value can be expressed in a time format such as **1m22s**. The default value is **30s**.
+#### **--hostuser**=*name*
+
+Add a user account to /etc/passwd from the host to the container. The Username
+or UID must exist on the host system.
+
#### **--help**
Print usage statement
@@ -492,19 +497,24 @@ Path to the container-init binary.
When set to **true**, keep stdin open even if not attached. The default is **false**.
-#### **--ip6**=*ip*
-
-Not implemented.
-
-#### **--ip**=*ip*
+#### **--ip**=*ipv4*
-Specify a static IP address for the container, for example **10.88.64.128**.
+Specify a static IPv4 address for the container, for example **10.88.64.128**.
This option can only be used if the container is joined to only a single network - i.e., **--network=network-name** is used at most once -
and if the container is not joining another container's network namespace via **--network=container:_id_**.
The address must be within the network's IP address pool (default **10.88.0.0/16**).
To specify multiple static IP addresses per container, set multiple networks using the **--network** option with a static IP address specified for each using the `ip` mode for that option.
+#### **--ip6**=*ipv6*
+
+Specify a static IPv6 address for the container, for example **fd46:db93:aa76:ac37::10**.
+This option can only be used if the container is joined to only a single network - i.e., **--network=network-name** is used at most once -
+and if the container is not joining another container's network namespace via **--network=container:_id_**.
+The address must be within the network's IPv6 address pool.
+
+To specify multiple static IPv6 addresses per container, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option.
+
#### **--ipc**=*mode*
Set the IPC namespace mode for a container. The default is to create
@@ -762,6 +772,11 @@ Tune the host's OOM preferences for containers (accepts values from **-1000** to
#### **--os**=*OS*
Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`.
+#### **--passwd**
+
+Allow Podman to add entries to /etc/passwd and /etc/group when used in conjunction with the --user option.
+This is used to override the Podman provided user setup in favor of entrypoint configurations such as libnss-extrausers.
+
#### **--personality**=*persona*
Personality sets the execution domain via Linux personality(2).
@@ -992,8 +1007,8 @@ Note: Labeling can be disabled for all containers by setting label=false in the
- **no-new-privileges**: Disable container processes from gaining additional privileges
-- **seccomp=unconfined**: Turn off seccomp confinement for the container
-- **seccomp**=_profile.json_: Allowed syscall list seccomp JSON file to be used as a seccomp filter
+- **seccomp=unconfined**: Turn off seccomp confinement for the container.
+- **seccomp=profile.json**: JSON file to be used as a seccomp filter. Note that the `io.podman.annotations.seccomp` annotation is set with the specified value as shown in `podman inspect`.
- **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.
@@ -1211,6 +1226,17 @@ If for example _amount_ is **5** the second mapping step would look like:
| _from_uid_ + 3 | _container_uid_ + 3 |
| _from_uid_ + 4 | _container_uid_ + 4 |
+When running as rootless, Podman will use all the ranges configured in the _/etc/subuid_ file.
+
+The current user ID is mapped to UID=0 in the rootless user namespace.
+Every additional range is added sequentially afterward:
+
+| host |rootless user namespace | length |
+| - | - | - |
+| $UID | 0 | 1 |
+| 1 | $FIRST_RANGE_ID | $FIRST_RANGE_LENGTH |
+| 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID | $SECOND_RANGE_LENGTH|
+
Even if a user does not have any subordinate UIDs in _/etc/subuid_,
**--uidmap** could still be used to map the normal UID of the user to a
container UID by running `podman run --uidmap $container_uid:0:1 --user $container_uid ...`.
diff --git a/docs/source/markdown/podman-search.1.md b/docs/source/markdown/podman-search.1.md
index 9e166fcc2..9c075a1e0 100644
--- a/docs/source/markdown/podman-search.1.md
+++ b/docs/source/markdown/podman-search.1.md
@@ -62,7 +62,7 @@ Valid placeholders for the Go template are listed below:
| --------------- | ---------------------------- |
| .Index | Registry |
| .Name | Image name |
-| .Descriptions | Image description |
+| .Description | Image description |
| .Stars | Star count of image |
| .Official | "[OK]" if image is official |
| .Automated | "[OK]" if image is automated |
diff --git a/docs/tutorials/mac_experimental.md b/docs/tutorials/mac_experimental.md
index 8df64dc99..b5b815fe5 100644
--- a/docs/tutorials/mac_experimental.md
+++ b/docs/tutorials/mac_experimental.md
@@ -90,7 +90,7 @@ that you were given. It will be used in two of the steps below.
## Test podman
-1. podman machine init --image-path /path/to/image
+1. podman machine init --image-path /path/to/image --cpus 2
2. podman machine start
3. podman images
4. git clone http://github.com/baude/alpine_nginx && cd alpine_nginx
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-01-20 12:04:45 +0000