v4.0.0-RC4

This is the fourth release candidate for Podman v4.0.

Preliminary release notes are below:

Features

• Podman has seen an extensive rewrite of its network stack to add support for Netavark, a new tool for configuring container networks, in addition to the existing CNI stack. Netavark will be default on new installations when it is available.
• The podman network connect command now supports three new options, --ip, --ip6, and --mac-address, to specify configuration for the new network that will be attached.
• The podman network create command now allows the --subnet, --gateway, and --ip-range options to be specified multiple times, to allow for the creation of dual-stack IPv4 and IPv6 networks with user-specified subnets.
• The --network option to podman create, podman pod create, podman run, and podman play kube can now, when specifying a network name, also specify advanced network options such as alias, ip, mac, and interface_name, allowing advanced configuration of networks when creating containers connected to more than one network.
• The podman play kube command can now specify the --net option multiple times, to connect created containers and pods to multiple networks.
• The podman create, podman pod create, and podman run commands now support a new option, --ip6, to specify a static IPv6 address for the created container or pod to use.
• Macvlan networks can now configure the mode of the network via the -o mode= option.
• When using the CNI network stack, a new network driver, ipvlan, is now available.
• The podman info command will now print the network backend in use (Netavark or CNI).
• The network backend to use can be now be specified in containers.conf via the network_backend field. Please note that it is not recommended to switch backends while containers exist, and a system reboot is recommended after doing so.
• All Podman commands now support a new option, --noout, that suppresses all output to STDOUT.
• All commands that can remove containers (podman rm --force, podman pod rm --force, podman volume rm --force, podman network rm --force) now accept a --time option to specify the timeout on stopping the container before resorting to SIGKILL (identical to the --time flag to podman stop).
• The podman run and podman create commands now support a new option, --passwd, that uses the /etc/passwd and /etc/groups files from the image in the created container without changes by Podman (#11805).
• The podman run and podman create commands now support a new option, --hostuser, that creates one or more users in the container based on users from the host (e.g. with matching username, UID, and GID).
• The podman create and podman run commands now support two new options, --unsetenv and --unsetenv-all, to clear default environment variables set by Podman and by the container image (#11836).
• The podman rm command now supports a new option, --depend, which recursively removes a given container and all containers that depend on it (#10360).
• All commands that support filtering their output based on labels (e.g. podman volume ls, podman ps) now support labels specified using regular expressions (e.g. --filter label=some.prefix.com/key/*).
• The podman pod create command now supports the --volume option, allowing volumes to be specified that will be mounted automatically to all containers in the pod (#10379).
• The podman pod create command now supports the --device option, allowing devices to be specified that will be mounted automatically to all containers in the pod.
• The podman pod create command now supports the --volumes-from option, allowing volumes from an existing Podman container to be mounted automatically to all containers in the pod.
• The podman pod create command now supports the --security-opt option, allowing security settings (e.g. disabling SELinux or Seccomp) to be configured automatically for all containers in the pod (#12173).
• The podman pod create command now supports the --sysctl option, allowing sysctls to be configured automatically for all containers in the pod.
• The podman events command now supports the --no-trunc option, which will allow short container IDs to be displayed instead of the default full IDs. The flag defaults to true, so full IDs remain the default (#8941).
• The podman machine init command now supports a new VM type, wsl, available only on Windows; this uses WSL as a backend for podman machine, instead of creating a separate VM and managing it via QEMU (#12503).
• The podman machine init command now supports a new option, --now, to start the VM immediately after creating it.
• The podman machine init command now supports a new option, --volume, to mount contents from the host into the created virtual machine.
• Virtual machines created by podman machine now automatically mount certificates from the host's keychain into the virtual machine (#11507).
• Virtual machines created by podman machine now automatically propagate standard proxy environment variables from the host into the virtual machine, including copying any required certificates from SSL_FILE_CERT into the VM.
• The podman machine ssh command now supports a new option, --username, to specify the username to connect to the VM with.
• Port forwarding from VMs created using podman machine now supports ports specified using custom host IPs (e.g. -p 127.0.0.1:8080:80), the UDP protocol, and containers created using the slirp4netns network mode (#11528 and #11728).
• The podman system connection rm command supports a new option, --all, to remove all available connections (#12018).
• The podman system service command's default timeout is now configured via containers.conf (using the service_timeout field) instead of hardcoded to 5 seconds.
• The --mount type=devpts option to podman create and podman run now supports new options: uid, gid, mode, and max.
• The --volume option to podman create and podman run now supports a new option, :idmap, which using an ID mapping filesystem to allow multiple containers with disjoint UID and GID ranges mapped into them access the same volume (#12154).
• The U option for volumes, which changes the ownership of the mounted volume to ensure the user running in the container can access it, can now be used with the --mount option to podman create and podman run, as well as the --volume option where it was already available.
• The :O option for volumes, which specifies that an overlay filesystem will be mounted over the volume and ensures changes do not persist, is now supported with named volumes as well as bind mounts.
• The :O option for volumes now supports two additional options, upperdir and workdir, which allow for specifying custom upper directories and work directories for the created overlay filesystem.
• Podman containers created from a user-specified root filesystem (via --rootfs) can now create an overlay filesystem atop the user-specified rootfs which ensures changes will not persist by suffixing the user-specified root filesystem with :O.
• The podman save command has a new option, --uncompressed, which saves the layers of the image without compression (#11613).
• Podman supports a new log driver for containers, passthrough, which logs all output directly to the STDOUT and STDERR of the podman command; it is intended for use in systemd-managed containers.
• The podman build command now supports two new options, --unsetenv and --all-platforms.
• The podman image prune command now supports a new option, --external, which allows containers not created by Podman (e.g. temporary containers from Buildah builds) to be pruned (#11472).
• Two new aliases for podman image prune have been added for Docker compatibility: podman builder prune and podman buildx prune.
• The podman play kube command now supports a new option, --no-hosts, which uses the /etc/hosts file from the image in all generated containers, preventing any modifications to the hosts file from Podman (#9500).
• The podman play kube command now supports a new option, --replace, which will replace any existing containers and pods with the same names as the containers and pods that will be created by the command (#11481).
• The podman play kube command now supports a new option, --log-opt, which allows the logging configuration of generated containers and pods to be adjusted (#11727).
• The podman play kube command now supports Kubernetes YAML that specifies volumes from a configmap.
• The podman generate systemd command now supports a new option, --template, to generate template unit files.
• The podman generate systemd command now supports a new option, --start-timeout, to override the default start timeout for generated unit files (#11618).
• The podman generate systemd command now supports a new option, --restart-sec, to override the default time before a failed unit is restarted by systemd for generated unit files.
• The podman generate systemd command now supports three new options, --wants, --after, and --requires, which allow detailed control of systemd dependencies in generated unit files.
• The podman container checkpoint and podman container restore commands can now print statistics about the checkpoint operation via a new option, --print-stats.
• The podman container checkpoint and podman container restore commands can now checkpoint and restore containers which make use of file locks via a new option, --file-locks.
• The podman container restore command can now be used with containers created using the host IPC namespace (--ipc=host).
• The podman container checkpoint and podman container restore commands now handle checkpointing and restoring the contents of /dev/shm.
• The podman container checkpoint and podman container restore commands are now supported with the remote Podman client (#12007).
• The podman inspect command on containers now includes additional output fields for checkpointed and restored containers, including information about when the container was checkpointed or restored, and the path to the checkpoint/restore log.
• The podman secret list command now supports a new option, --filter, to filter what secrets are returned.
• The podman image scp command can now be used to transfer images between users (both root and rootless) on the same system, without requiring sshd.
• The podman image sign command now supports a new option, --authfile, to specify an alternative path to authentication credentials (#10866).
• The podman load command now supports downloading files via HTTP and HTTPS if a URL is given (#11970).
• The podman push command now supports a new option, --compression-format, to choose the compression algorithm used to compress image layers.
• The podman volume create command now allows volumes using the local driver that require mounting to be used by non-root users. This allows tmpfs and bind volumes to be created by non-root users (#12013).
• A new command, podman dial-stdio, has been added; this command should not be invoked directly, but is used by some clients of the Docker Remote API, and is provided for Docker compatibility (#11668).

Breaking Changes

• Podman v4.0 will perform several schema migrations in the Podman database when it is first run. These schema migrations will cause Podman v3.x and earlier to be unable to read certain network configuration information from the database, so downgrading from Podman v4.0 to an earlier version will cause containers to lose their static IP, MAC address, and port bindings.
• All endpoints of the Docker-compatible API now enforce that all image shortnames will be resolved to the Docker Hub for improved Docker compatibility. This behavior can be turned off via the compat_api_enforce_docker_hub option in containers.conf (#12320).
• The Podman APIs for Manifest List and Network operations have been completely rewritten to address issues and inconsistencies in the previous APIs.
• The make install makefile target no longer implicitly builds Podman, and will fail if make was not run prior to it.
• The podman rm --depends, podman rmi --force, and podman network rm --force commands can now remove pods if a they need to remove an infra container (e.g. podman rmi --force on the infra image will remove all pods and infra containers). Previously, any command that tried to remove an infra container would error.
• The podman system reset command now removes all networks on the system, in addition to all volumes, pods, containers, and images.
• If the CONTAINER_HOST environment variable is set, Podman will default to connecting to the remote Podman service specified by the environment variable, instead of running containers locally (#11196).
• Healthcheck information from podman inspect on a container has had its JSON tag renamed from Healthcheck to Health for improved Docker compatibility. An alias has been added so that using the old name with the --format option will still work (#11645).
• Secondary IP and IPv6 addresses from podman inspect on a container (SecondaryIPAddresses and SecondaryIPv6Addresses) have been changed from arrays of strings to arrays of structs for improved Docker compatibility (the struct now includes IP address and prefix length).
• The podman volume rm --force command will now remove containers that depend on the volume that are running (previously, it would only remove stopped containers).
• The output of the podman search command has been altered to remove the Index, Stars, and Automated columns, as these were not used by registries that are not Dockerhub.
• The host.containers.internal entry in /etc/hosts for rootless containers now points to a public IP address of the host machine, to ensure the container can reach the host (the previous value, a slirp4netns address, did not actually point to the host) (#12000).
• Containers created in pods that have an infra container can no longer independently configure a user namespace via --uidmap and --gidmap (#12669).
• Several container states have been renamed internally - for example, the previous Configured state is now named Created, and the previous Created state is now Initialized. The podman ps command already normalized these names for Docker compatibility, so this will only be visible when inspecting containers with podman inspect.

Changes

• Podman containers will now automatically add the container's short ID as a network alias when connected to a supporting network (#11748).
• The podman machine stop command will now log when machines are successfully stopped (#11542).
• The podman machine stop command now waits until the VM has stopped to return; previously, it returned immediately after the shutdown command was sent, without waiting for the VM to shut down.
• VMs created by podman machine now delegate more cgroup controllers to the rootless user used to run containers, allowing for additional resource limits to be used (#13054).
• The podman stop command will now log a warning to the console if the stop timeout expires and SIGKILL must be used to stop the container (#11854).
• Several performance optimizations have been implemented that should speed up container and pod creation, and running containers and pods that forward large ranges of ports.
• The --no-trunc argument to the podman search command now defaults to true.
• Rootless port forwarding using the rootlessport port forwarder is now handled by a separate binary, not Podman itself, which results in significantly reduced memory usage (#10790).
• The podman system connection ls command now has a separate output column to show which connection is currently the default (instead appending * to the default connection's name) (#12019).
• The --kernel-memory option to podman run and podman create has been deprecated in the upstream OCI runtime specification, and is now also deprecated in Podman and will be removed in a future release. Use of the flag will result in a warning.
• Podman will now ship build the pause image used by pods locally, instead of pulling it from the network (using the existing catatoinit binary used for podman run --init). This allows pods to be easily used on systems without an internet connection.
• The --rootless-cni option to podman unshare has been renamed to --rootless-netns. The old name has been aliased to the new one and will still function, but may be removed in a future release.
• The --cni-config-dir option to all Podman commands has been renamed to --network-config-dir as it will not be used with Netavark as well as CNI. The old name has been aliased to the new one and will still function, but may be removed in a future release.
• The --format option to all Podman commands has been changed to improved functionality and Docker compatibility (#10974).
• The podman ps --external flag previously required --all to also be specified; this is no longer true
• The port-forwarding logic previously contined in the podman-machine-cni CNI plugin has been integrated directly into Podman. The podman-machine-cni plugin is no longer necessary and should be removed.
• The --device flag to podman create, podman run, and podman pod create would previously refuse to mount devices when Podman was run as a non-root user and no permission to access the device was available; it will now mount these devices without checking permissions (#12704).

Bugfixes

• Fixed a bug where networks could be created with the same name as a container network mode (e.g. host) (#11448).
• Fixed a bug where the podman save command was not automatically removing signatures from saved images.
• Fixed a bug where a rare race condition could cause podman run --rm to return an error that a given container did not exist when trying to remove it, despite it having been safely removed (#11775).
• Fixed a bug where a rare race condition could cause podman ps to return an error if a container was removed while the command was running (#11810).
• Fixed a bug where running Kube YAML with a CPU limit would using podman play kube would result in errors (#11803).
• Fixed a bug where creating a pod without an infra container would not generate an Pod Create event.
• Fixed a bug where volumes created with the :z and :Z options would be relabelled every time a container was started, not just the first time.
• Fixed a bug where the podman tag command on a manifest list could tag an image in the manifest, and not the manifest list itself.
• Fixed a bug where creating a volume using an invalid volume option that contained a format string would print a nonsensical error.
• Fixed a bug where Podman would not create a healthcheck for containers created from images that specified a healthcheck in their configuration (#12226).
• Fixed a bug where rootless containers that used a custom user namespace (e.g. --userns=keep-id) could not have any ports forwarded to them.
• Fixed a bug where the podman system connection ls command would not print any output (including headers) if no connections were present.
• Fixed a bug where the --memory-swappiness option to podman create and podman run did not accept 0 as a valid value.
• Fixed a bug where environment variables specified in containers.conf for Podman would sometimes not be applied (#12296).
• Fixed a bug where running multiple rootless Podman instances with different configurations on the same system could cause networking issues due to the use of a single, shared rootless network namespace (#12306).
• Fixed a bug where rootless containers using bridge networking would fail if /etc/resolv.conf was a symlink to a directory (#12461).
• Fixed a bug where podman container restore could sometimes restore containers with a different OCI runtime than they had been using before they were checkpointed.
• Fixed a bug where some commands of the remote Podman client allowed the --signature-policy option to be used (with no effect); --signature-policy is not supported by the remote client (#12357).
• Fixed a bug where images which specified a port range in EXPOSE could not be run (#12293).
• Fixed a bug where Podman would resolve image names without a tag to any tag of that image available on the local system, instead of the :latest tag (#11964).
• Fixed a bug where the --blkio-weight-device option to podman create and podman run was nonfunctional.
• Fixed a bug where the podman generate systemd command did not support container entrypoints that were specified as JSON arrays (#12477).
• Fixed a bug where rootless Podman could, under some circumstances, exhaust all available inotify watches (#11825).
• Fixed a bug where, when a container was created with both the --hostname and --pod new: options, the hostname would be discarded; it is now set as the hostname of the created pod, which will be used by the container.
• Fixed a bug where the order in which podman network ls printed networks was not deterministic.
• Fixed a bug where the podman kill command would sometimes not print the ID of containers that were killed.
• Fixed a bug where VMs created by podman machine did not match their timezone to the host system (#11895).
• Fixed a bug where container healthchecks were not properly cleaning up generated systemd services, leading to healthcheck failures after containers were restarted.
• Fixed a bug where the podman build command did not properly propagate non-0 exit codes from Buildah when builds failed.
• Fixed a bug where the remote Podman client's podman build command could fail to build images when the remote client was run on Windows and the Containerfile contained COPY instructions (#13119).
• Fixed a bug where the remote Podman client's --secret option to the podman build command was nonfunctional.
• Fixed a bug where the remote Podman client's podman build command would error if given a relative path to a Containerfile (#12841).
• Fixed a bug where the podman generate kube command would sometimes omit environment variables set in containers from generated YAML.
• Fixed a bug where setting userns=auto in containers.conf was not respected (#12615).
• Fixed a bug where the podman run command would fail if the host machine did not have a /etc/hosts file (#12667).
• Fixed a bug where certain annotations used internally by Podman could be set by images, resulting in podman inspect reporting incorrect information (#12671).
• Fixed a bug where named volumes would not copy-up after being mounted over an empty directory, then subsequently mounted over a non-empty directory in another container (#12714).
• Fixed a bug where the podman inspect command on containers was URL-encoding special characters in strings (e.g. healthcheck commands).
• Fixed a bug where the podman generate kube command would generate YAML including optional environment variables from secrets and configmaps that are not included (#12553).
• Fixed a bug where the podman pod create command would ignore the default infra image specified in containers.conf (#12771).
• Fixed a bug where the host.containers.internal entry in /etc/hosts was set incorrectly to an inaccessible host IP for macvlan networks (#11351).
• Fixed a bug where secrets could not be mounted into containers that joined a user namespace (e.g. --userns=auto) (#12779).
• Fixed a bug where rootless Podman could produce an error about cgroups when containers were created inside existing pods (#10800).
• Fixed a bug where Podman could error that a systemd session was not available despite having the cgroup manager set to cgroupfs (#12802).
• Fixed a bug where the remote Podman client on Windows would ignore environment variables from the --env option to podman create and podman run (#12056).
• Fixed a bug where Podman could segfault when an error occurred trying to set up rootless mode.
• Fixed a bug where Podman could segfault when reading an image layer that did not have a creation timestamp set.
• Fixed a bug where, when Podman's storage directories were on an NFS filesystem, Podman would leave some unneeded file descriptors open, causing errors when containers were removed.
• Fixed a bug where, when Podman's storage directories were on an NFS filesystem, cleaning up a container's exec sessions could fail.
• Fixed a bug where Podman commands that operate on a container could give an incorrect error message if given a partial ID that could refer to 2 or more containers (#12963).
• Fixed a bug where the podman stats command would not show network usage statistics on containers using slirp4netns for networking (#11695).
• Fixed a bug where the /dev/shm mount in the container was not mounted with nosuid, noexec, and nodev mount options.
• Fixed a bug where the --shm-size option to podman create and podman run interpeted human-readable sizes as KB instead of KiB, and GB instead of GiB (such that a kilobyte was interpreted as 1000 bytes, instead of 1024 bytes) (#13096).

API

• The Podman remote API version has been bumped to v4.0.0.
• The Compat and Libpod Search endpoints for Images now will never truncate the returned image description. The noTrunc query parameter is now ignored as such (#11894).
• The Libpod Top endpoints for Containers and Pods now support streaming output using the stream=true query parameter (#12115).
• The Libpod Create endpoint for Volumes now supports specifying labels for the volume both as Label and Labels in the provided JSON configuration (#12102).
• The Compat Create endpoint for Containers now respects cgroup configuration from containers.conf (#12550).
• The Compat Create endpoint for Containers now respects user namespace configuration from the PODMAN_USERNS environment variable (#11350).
• Fixed a bug where the Compat Create endpoint for Containers was ignoring the HostConfig.StorageOpt field (#11016).
• Fixed a bug where the Compat List endpoint for Containers did not populate the Mounts field (#12734).
• Fixed a bug where a race condition could cause a crash in the server when the Compat or Libpod Attach endpoints for Containers were invoked (#12904).
• Fixed a bug where the Libpod Prune endpoint for Images would return nothing, instead of an empty array, when nothing was pruned.
• Fixed a bug where the Compat List endpoint for Images did not prefix image IDs with sha256:.
• Fixed a bug where the Compat Push endpoint for Images would return JSON which did not include the size field (#12468).
• Fixed a bug where the Compat Load endpoint for Images would refuse to accept input archives that contained more than one image.
• Fixed a bug where the Compat Build endpoint for Images ignored the quiet query parameter (#12566).
• Fixed a bug where the Compat Build endpoint for Images did not include aux JSON (which included the ID of built images) in returned output (#12063).
• Fixed a bug where the Compat and Libpod List endpoints for Networks would sometimes not return networks created on the server by the Podman CLI after the API server had been started (#11828).
• Fixed a bug where the Compat Inspect endpoint for Networks did not include the subnet CIDR in the returned IPv4 and IPv6 addresses.
• Fixed a bug where the Compat Events endpoint did not properly set the Action field of Died events for containers to die (previously, died was used; this was incompatible with Docker's output).
• Fixed a bug where the Compat Info endpoint did not properly populate information on configured registries.
• Fixed a bug where the Compat Events endpoint did not properly set the exit code of the container in the exitCode field in Died events for containers.
• Fixed a bug where the Compat Events endpoint did not properly populate the TimeNano field.
• Numerous small changes have been made to ensure that the API matches its Swagger documentation

Misc

• The Windows installer MSI distributed through Github releases no longer supports 32-bit systems, as Podman is built only for 64-bit machines.
• Updated Buildah to v1.24.0
• Updated the containers/image library to v5.19.0
• Updated the containers/storage library to v1.38.1
• Updated the containers/common library to v0.47.1
• Updated the containers/psgo library to v1.7.2