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.md71
-rw-r--r--docs/source/markdown/podman-machine-init.1.md6
-rw-r--r--docs/source/markdown/podman-network-connect.1.md16
-rw-r--r--docs/source/markdown/podman-play-kube.1.md18
-rw-r--r--docs/source/markdown/podman-pod-create.1.md91
-rw-r--r--docs/source/markdown/podman-ps.1.md2
-rw-r--r--docs/source/markdown/podman-run.1.md75
-rw-r--r--docs/source/markdown/podman-search.1.md2
-rw-r--r--docs/source/markdown/podman-secret-ls.1.md13
-rw-r--r--docs/tutorials/mac_experimental.md2
-rw-r--r--docs/tutorials/mac_win_client.md6
14 files changed, 275 insertions, 57 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 b58fd1e18..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,16 +474,24 @@ Path to the container-init binary.
Keep STDIN open even if not attached. The default is *false*.
-#### **--ip6**=*ip*
+#### **--ip**=*ipv4*
-Not implemented
+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.
-#### **--ip**=*ip*
+#### **--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.
-Specify a static IP 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 CNI network's IP address pool (default **10.88.0.0/16**).
#### **--ipc**=*ipc*
@@ -531,12 +544,16 @@ This option is currently supported only by the **journald** log driver.
#### **--mac-address**=*address*
-Container MAC address (e.g. 92:d0:c6:0a:29:33)
+Container network interface MAC address (e.g. 92:d0:c6:0a:29:33)
+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_**.
Remember that the MAC address in an Ethernet network must be unique.
The IPv6 link-local address will be based on the device's MAC address
according to RFC4862.
+To specify multiple static MAC addresses per container, set multiple networks using the **--network** option with a static MAC address specified for each using the `mac` mode for that option.
+
#### **--memory**, **-m**=*limit*
Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
@@ -668,15 +685,22 @@ This works for both background and foreground containers.
#### **--network**=*mode*, **--net**
-Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_. If used together with **--pod**, the container will not join the pod's network namespace.
+Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** set to **none** or **container:**_id_. If used together with **--pod**, the container will not join the pod's network namespace.
Valid _mode_ values are:
-- **bridge**: Create a network stack on the default bridge. This is the default for rootfull containers.
+- **bridge[:OPTIONS,...]**: Create a network stack on the default bridge. This is the default for rootfull containers. It is possible to specify these additional options:
+ - **alias=name**: Add network-scoped alias for the container.
+ - **ip=IPv4**: Specify a static ipv4 address for this container.
+ - **ip=IPv6**: Specify a static ipv6 address for this container.
+ - **mac=MAC**: Specify a static mac address address for this container.
+ - **interface_name**: Specify a name for the created network interface inside the container.
+
+ For example to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`.
+- \<network name or ID\>[:OPTIONS,...]: Connect to a user-defined network; this is the network name or ID from a network created by **[podman network create](podman-network-create.1.md)**. Using the network name implies the bridge network mode. It is possible to specify the same options described under the bridge mode above. You can use the **--network** option multiple times to specify additional networks.
- **none**: Create a network namespace for the container but do not configure network interfaces for it, thus the container has no network connectivity.
- **container:**_id_: Reuse another container's network stack.
- **host**: Do not create a network namespace, the container will use the host's network. Note: The host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
-- **network**: Connect to a user-defined network, multiple networks should be comma-separated.
- **ns:**_path_: Path to a network namespace to join.
- **private**: Create a new namespace for the container. This will use the **bridge** mode for rootfull containers and **slirp4netns** for rootless ones.
- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options:
@@ -694,7 +718,9 @@ Valid _mode_ values are:
#### **--network-alias**=*alias*
-Add network-scoped alias for the container. NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release.
+Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a name only for a specific network, use the alias option as described under the **--network** option.
+Network aliases work only with the bridge networking mode. This option can be specified multiple times.
+NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release.
#### **--no-healthcheck**
@@ -933,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**.
@@ -1126,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
@@ -1492,6 +1529,12 @@ $ podman create --name container1 --personaity=LINUX32 fedora bash
$ podman create --name container1 --rootfs /path/to/rootfs:O bash
```
+### Create a container connected to two networks (called net1 and net2) with a static ip
+
+```
+$ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
+```
+
### Rootless Containers
Podman runs as a non root user on most systems. This feature requires that a new enough version of shadow-utils
diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md
index 3abc7c9ea..aead6c695 100644
--- a/docs/source/markdown/podman-machine-init.1.md
+++ b/docs/source/markdown/podman-machine-init.1.md
@@ -55,6 +55,12 @@ Memory (in MB).
Start the virtual machine immediately after it has been initialized.
+#### **--timezone**
+
+Set the timezone for the machine and containers. Valid values are `local` or
+a `timezone` such as `America/Chicago`. A value of `local`, which is the default,
+means to use the timezone of the machine host.
+
#### **--help**
Print usage statement.
diff --git a/docs/source/markdown/podman-network-connect.1.md b/docs/source/markdown/podman-network-connect.1.md
index b998d4b7e..c3eef4038 100644
--- a/docs/source/markdown/podman-network-connect.1.md
+++ b/docs/source/markdown/podman-network-connect.1.md
@@ -11,12 +11,21 @@ Connects a container to a network. A container can be connected to a network by
Once connected, the container can communicate with other containers in the same network.
## OPTIONS
-#### **--alias**
+#### **--alias**=*name*
Add network-scoped alias for the container. If the network is using the `dnsname` CNI plugin, these aliases
can be used for name resolution on the given network. Multiple *--alias* options may be specified as input.
NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation
that will be removed in a later release.
+#### **--ip**=*address*
+Set a static ipv4 address for this container on this network.
+
+#### **--ip6**=*address*
+Set a static ipv6 address for this container on this network.
+
+#### **--mac-address**=*address*
+Set a static mac address for this container on this network.
+
## EXAMPLE
Connect a container named *web* to a network named *test*
@@ -29,6 +38,11 @@ Connect a container name *web* to a network named *test* with two aliases: web1
podman network connect --alias web1 --alias web2 test web
```
+Connect a container name *web* to a network named *test* with a static ip.
+```
+podman network connect --ip 10.89.1.13 test web
+```
+
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-network(1)](podman-network.1.md)**, **[podman-network-disconnect(1)](podman-network-disconnect.1.md)**
diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md
index 075fbbe81..81ab65176 100644
--- a/docs/source/markdown/podman-play-kube.1.md
+++ b/docs/source/markdown/podman-play-kube.1.md
@@ -142,6 +142,7 @@ removed. Any volumes created are left intact.
#### **--ip**=*IP address*
Assign a static ip address to the pod. This option can be specified several times when play kube creates more than one pod.
+Note: When joining multiple networks you should use the **--network name:ip=\<ip\>** syntax.
#### **--log-driver**=driver
@@ -167,15 +168,24 @@ This option is currently supported only by the **journald** log driver.
#### **--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.
+Note: When joining multiple networks you should use the **--network name:mac=\<mac\>** syntax.
#### **--network**=*mode*, **--net**
-Change the network mode of the pod. The host and bridge network mode should be configured in the yaml file.
+Change the network mode of the pod. The host network mode should be configured in the YAML file.
Valid _mode_ values are:
+- **bridge[:OPTIONS,...]**: Create a network stack on the default bridge. This is the default for rootfull containers. It is possible to specify these additional options:
+ - **alias=name**: Add network-scoped alias for the container.
+ - **ip=IPv4**: Specify a static ipv4 address for this container.
+ - **ip=IPv6**: Specify a static ipv6 address for this container.
+ - **mac=MAC**: Specify a static mac address address for this container.
+ - **interface_name**: Specify a name for the created network interface inside the container.
+
+ For example to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`.
+- \<network name or ID\>[:OPTIONS,...]: Connect to a user-defined network; this is the network name or ID from a network created by **[podman network create](podman-network-create.1.md)**. Using the network name implies the bridge network mode. It is possible to specify the same options described under the bridge mode above. You can use the **--network** option multiple times to specify additional networks.
- **none**: Create a network namespace for the container but do not configure network interfaces for it, thus the container has no network connectivity.
- **container:**_id_: Reuse another container's network stack.
-- **network**: Connect to a user-defined network, multiple networks should be comma-separated.
- **ns:**_path_: Path to a network namespace to join.
- **private**: Create a new namespace for the container. This will use the **bridge** mode for rootfull containers and **slirp4netns** for rootless ones.
- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options:
@@ -253,9 +263,9 @@ $ podman play kube demo.yml --configmap configmap-foo.yml --configmap configmap-
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
```
-CNI network(s) can be specified as comma-separated list using ``--network``
+Create a pod connected to two networks (called net1 and net2) with a static ip
```
-$ podman play kube demo.yml --network cni1,cni2
+$ podman play kube demo.yml --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10
52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6
```
diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md
index cca90c942..b2e16e051 100644
--- a/docs/source/markdown/podman-pod-create.1.md
+++ b/docs/source/markdown/podman-pod-create.1.md
@@ -118,9 +118,23 @@ The custom image that will be used for the infra container. Unless specified, P
The name that will be used for the pod's infra container.
-#### **--ip**=*ipaddr*
+#### **--ip**=*ip*
-Set a static IP for the pod's shared network.
+Specify a static IP address for the pod, for example **10.88.64.128**.
+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 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**
@@ -132,7 +146,16 @@ Read in a line delimited file of labels.
#### **--mac-address**=*address*
-Set a static MAC address for the pod's shared network.
+Pod network interface MAC address (e.g. 92:d0:c6:0a:29:33)
+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_**.
+
+Remember that the MAC address in an Ethernet network must be unique.
+The IPv6 link-local address will be based on the device's MAC address
+according to RFC4862.
+
+To specify multiple static MAC addresses per pod, set multiple networks using the **--network** option with a static MAC address specified for each using the `mac` mode for that option.
+
#### **--name**=*name*, **-n**
@@ -140,11 +163,23 @@ Assign a name to the pod.
#### **--network**=*mode*, **--net**
-Set network mode for the pod. Supported values are:
-- **bridge**: Create a network stack on the default bridge. This is the default for rootfull containers.
+Set the network mode for the pod. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_.
+
+Valid _mode_ values are:
+
+- **bridge[:OPTIONS,...]**: Create a network stack on the default bridge. This is the default for rootfull containers. It is possible to specify these additional options:
+ - **alias=name**: Add network-scoped alias for the container.
+ - **ip=IPv4**: Specify a static ipv4 address for this container.
+ - **ip=IPv6**: Specify a static ipv6 address for this container.
+ - **mac=MAC**: Specify a static mac address address for this container.
+ - **interface_name**: Specify a name for the created network interface inside the container.
+
+ For example to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`.
+- \<network name or ID\>[:OPTIONS,...]: Connect to a user-defined network; this is the network name or ID from a network created by **[podman network create](podman-network-create.1.md)**. Using the network name implies the bridge network mode. It is possible to specify the same options described under the bridge mode above. You can use the **--network** option multiple times to specify additional networks.
- **none**: Create a network namespace for the container but do not configure network interfaces for it, thus the container has no network connectivity.
-- **host**: Do not create a network namespace, all containers in the pod will use the host's network. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
-- **network**: Connect to a user-defined network, multiple networks should be comma-separated.
+- **container:**_id_: Reuse another container's network stack.
+- **host**: Do not create a network namespace, the container will use the host's network. Note: The host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
+- **ns:**_path_: Path to a network namespace to join.
- **private**: Create a new namespace for the container. This will use the **bridge** mode for rootfull containers and **slirp4netns** for rootless ones.
- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options:
- **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`, which is added to `/etc/hosts` as `host.containers.internal` for your convenience). Default is false.
@@ -159,9 +194,11 @@ Set network mode for the pod. Supported values are:
Note: Rootlesskit changes the source IP address of incoming packets to a IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks.
- **port_handler=slirp4netns**: Use the slirp4netns port forwarding, it is slower than rootlesskit but preserves the correct source IP address. This port handler cannot be used for user-defined networks.
-#### **--network-alias**=strings
+#### **--network-alias**=*alias*
-Add a DNS alias for the pod. When the pod is joined to a CNI network with support for the dnsname plugin, the containers inside the pod will be accessible through this name from other containers in the network.
+Add a network-scoped alias for the pod, setting the alias for all networks that the pod joins. To set a name only for a specific network, use the alias option as described under the **--network** option.
+Network aliases work only with the bridge networking mode. This option can be specified multiple times.
+NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release.
#### **--no-hosts**
@@ -194,6 +231,38 @@ NOTE: This cannot be modified once the pod is created.
If another pod with the same name already exists, replace and remove it. The default is **false**.
+#### **--security-opt**=*option*
+
+Security Options
+
+- `apparmor=unconfined` : Turn off apparmor confinement for the pod
+- `apparmor=your-profile` : Set the apparmor confinement profile for the pod
+
+- `label=user:USER` : Set the label user for the pod processes
+- `label=role:ROLE` : Set the label role for the pod processes
+- `label=type:TYPE` : Set the label process type for the pod processes
+- `label=level:LEVEL` : Set the label level for the pod processes
+- `label=filetype:TYPE` : Set the label file type for the pod files
+- `label=disable` : Turn off label separation for the pod
+
+Note: Labeling can be disabled for all pods/containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file.
+
+- `mask=/path/1:/path/2` : The paths to mask separated by a colon. A masked path
+ cannot be accessed inside the containers within the pod.
+
+- `no-new-privileges` : Disable container processes from gaining additional privileges
+
+- `seccomp=unconfined` : Turn off seccomp confinement for the pod
+- `seccomp=profile.json` : Whitelisted syscalls seccomp Json file to be used as a seccomp filter
+
+- `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**.
+
+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.
+
#### **--share**=*namespace*
A comma-separated list of kernel namespaces to share. If none or "" is specified, no namespaces will be shared. The namespaces to choose from are ipc, net, pid, uts.
@@ -429,10 +498,12 @@ $ podman pod create --publish 8443:443
$ podman pod create --network slirp4netns:outbound_addr=127.0.0.1,allow_host_loopback=true
$ podman pod create --network slirp4netns:cidr=192.168.0.0/24
+
+$ podman pod create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10
```
## SEE ALSO
-**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**
+**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **containers.conf(1)**
## HISTORY
diff --git a/docs/source/markdown/podman-ps.1.md b/docs/source/markdown/podman-ps.1.md
index 4bae3e6bd..827fb2b2f 100644
--- a/docs/source/markdown/podman-ps.1.md
+++ b/docs/source/markdown/podman-ps.1.md
@@ -34,7 +34,7 @@ Note: Podman shares containers storage with other tools such as Buildah and CRI-
#### **--external**
-Display external containers that are not controlled by Podman but are stored in containers storage. These external containers are generally created via other container technology such as Buildah or CRI-O and may depend on the same container images that Podman is also using. External containers are denoted with either a 'buildah' or 'storage' in the COMMAND and STATUS column of the ps output. Only used with the --all option.
+Display external containers that are not controlled by Podman but are stored in containers storage. These external containers are generally created via other container technology such as Buildah or CRI-O and may depend on the same container images that Podman is also using. External containers are denoted with either a 'buildah' or 'storage' in the COMMAND and STATUS column of the ps output.
#### **--filter**, **-f**
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 0d9e6dbcd..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,16 +497,23 @@ Path to the container-init binary.
When set to **true**, keep stdin open even if not attached. The default is **false**.
-#### **--ip6**=*ip*
+#### **--ip**=*ipv4*
-Not implemented.
+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.
-#### **--ip**=*ip*
+#### **--ip6**=*ipv6*
-Specify a static IP 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 CNI network's IP address pool (default **10.88.0.0/16**).
+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*
@@ -557,12 +569,16 @@ This option is currently supported only by the **journald** log driver.
#### **--mac-address**=*address*
-Container MAC address (e.g. **92:d0:c6:0a:29:33**).
+Container network interface MAC address (e.g. 92:d0:c6:0a:29:33)
+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_**.
Remember that the MAC address in an Ethernet network must be unique.
The IPv6 link-local address will be based on the device's MAC address
according to RFC4862.
+To specify multiple static MAC addresses per container, set multiple networks using the **--network** option with a static MAC address specified for each using the `mac` mode for that option.
+
#### **--memory**, **-m**=_number_[_unit_]
Memory limit. A _unit_ can be **b** (bytes), **k** (kilobytes), **m** (megabytes), or **g** (gigabytes).
@@ -696,15 +712,22 @@ This works for both background and foreground containers.
#### **--network**=*mode*, **--net**
-Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_. If used together with **--pod**, the container will not join the pods network namespace.
+Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** set to **none** or **container:**_id_. If used together with **--pod**, the container will not join the pod's network namespace.
Valid _mode_ values are:
-- **bridge**: Create a network stack on the default bridge. This is the default for rootfull containers.
+- **bridge[:OPTIONS,...]**: Create a network stack on the default bridge. This is the default for rootfull containers. It is possible to specify these additional options:
+ - **alias=name**: Add network-scoped alias for the container.
+ - **ip=IPv4**: Specify a static ipv4 address for this container.
+ - **ip=IPv6**: Specify a static ipv6 address for this container.
+ - **mac=MAC**: Specify a static mac address address for this container.
+ - **interface_name**: Specify a name for the created network interface inside the container.
+
+ For example to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`.
+- \<network name or ID\>[:OPTIONS,...]: Connect to a user-defined network; this is the network name or ID from a network created by **[podman network create](podman-network-create.1.md)**. Using the network name implies the bridge network mode. It is possible to specify the same options described under the bridge mode above. You can use the **--network** option multiple times to specify additional networks.
- **none**: Create a network namespace for the container but do not configure network interfaces for it, thus the container has no network connectivity.
- **container:**_id_: Reuse another container's network stack.
- **host**: Do not create a network namespace, the container will use the host's network. Note: The host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
-- **network**: Connect to a user-defined network, multiple networks should be comma-separated.
- **ns:**_path_: Path to a network namespace to join.
- **private**: Create a new namespace for the container. This will use the **bridge** mode for rootfull containers and **slirp4netns** for rootless ones.
- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options:
@@ -722,7 +745,9 @@ Valid _mode_ values are:
#### **--network-alias**=*alias*
-Add network-scoped alias for the container. NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release.
+Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a name only for a specific network, use the alias option as described under the **--network** option.
+Network aliases work only with the bridge networking mode. This option can be specified multiple times.
+NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release.
#### **--no-healthcheck**
@@ -747,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).
@@ -977,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.
@@ -1196,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 ...`.
@@ -1867,6 +1908,12 @@ Forcing UTC:
Fri Nov 19 23:10:55 UTC 2021
```
+### Run a container connected to two networks (called net1 and net2) with a static ip
+
+```
+$ podman run --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
+```
+
### Rootless Containers
Podman runs as a non root user on most systems. This feature requires that a new enough version of **shadow-utils**
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/source/markdown/podman-secret-ls.1.md b/docs/source/markdown/podman-secret-ls.1.md
index 27576f026..f33ccf41b 100644
--- a/docs/source/markdown/podman-secret-ls.1.md
+++ b/docs/source/markdown/podman-secret-ls.1.md
@@ -20,11 +20,24 @@ Format secret output using Go template.
Omit the table headings from the listing of secrets. .
+#### **--filter**, **-f**=*filter=value*
+
+Filter output based on conditions given.
+Multiple filters can be given with multiple uses of the --filter option.
+
+Valid filters are listed below:
+
+| **Filter** | **Description** |
+| ---------- | ----------------------------------------------------------------- |
+| name | [Name] Secret name (accepts regex) |
+| id | [ID] Full or partial secret ID |
+
## EXAMPLES
```
$ podman secret ls
$ podman secret ls --format "{{.Name}}"
+$ podman secret ls --filter name=confidential
```
## SEE ALSO
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
diff --git a/docs/tutorials/mac_win_client.md b/docs/tutorials/mac_win_client.md
index 6295eb6b2..159296d5e 100644
--- a/docs/tutorials/mac_win_client.md
+++ b/docs/tutorials/mac_win_client.md
@@ -12,11 +12,11 @@ The remote client uses a client-server model. You need Podman installed on a Lin
### Windows
-Installing the Windows Podman client begins by downloading the Podman windows installer. The windows installer is built with each Podman release and is downloadable from its [release description page](https://github.com/containers/podman/releases/latest). You can also build the installer from source using the `podman.msi` Makefile endpoint.
+Installing the Windows Podman client begins by downloading the Podman Windows installer. The Windows installer is built with each Podman release and is downloadable from its [release description page](https://github.com/containers/podman/releases/latest). The Windows installer file is named `podman-v.#.#.#.msi`, where the `#` symbols represent the version number of Podman. At the time of this writing, the file name is `podman-v3.4.4.msi`. You can also build the installer from source using the `podman.msi` Makefile endpoint.
-Once you have downloaded the installer, simply double click the installer and Podman will be installed. The path is also set to put `podman` in the default user path.
+Once you have downloaded the installer to your Windows host, simply double click the installer and Podman will be installed. The path is also set to put `podman` in the default user path.
-Podman must be run at a command prompt using the Windows ‘cmd” or powershell applications.
+Podman must be run at a command prompt using the Windows Command Prompt (`cmd.exe`) or PowerShell (`pwsh.exe`) applications.
### macOS
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-12-29 15:34:08 +0000