Chapter 2: Command line

Introduction

The chapter introduces a web-application workflow for learning Podman’s command line, from running and modifying a container to creating and distributing an image.

• Containerized application workflow: Trace the chapter’s example workflow: launch a container, modify its contents, create an image, and ship the image to a registry. Explain that the chapter then introduces an automated way to do this to help maintain image security.
  Why it matters: This workflow connects the chapter’s container, image, and build commands into one practical task.
• Podman example prerequisites: State that the examples assume Podman 4.1 or later and use the registry.access.redhat.com/ubi8/httpd-24 base image. Describe updating Podman if an example fails on an older packaged version.
  Why it matters: The assumed version and base image help explain why a reader’s results might differ from the examples.
• Podman features for Docker users: Describe why experienced Docker users might still find the chapter useful: it points to Podman features such as mounting container images and using different transports.
  Why it matters: These examples show where the chapter goes beyond command-line tasks a Docker user may already recognize.

Key terms: container, image, registry, automated, Podman 4.1, registry.access.redhat.com/ubi8/httpd-24, Universal Base Images (UBI), mount container images, different transports

2.1 Working with containers

Introduces working with containers by using podman run to pull and explore a base image before building a containerized application.

• Base image starting point: Explain that working on a containerized application starts with a base image from a registry, and that podman run can pull and run it for testing or exploration.
  Why it matters: This connects finding an image to the first hands-on step of working with a container.
• Example image and storage: Describe the section's example: pulling and running registry.access.redhat.com/ubi8/httpd-24, storing the image in container storage in the user's home directory, and exploring inside the container.
  Why it matters: The example makes the introductory workflow concrete.

Key terms: container registries, podman run, base image, registry.access.redhat.com/ubi8/httpd-24, container storage

2.1.1 Exploring containers

This section walks through an interactive Podman run command and uses the resulting shell to compare a container’s environment with its host.

• Interactive container lifecycle: Explain how `podman run -ti --rm` provides an interactive shell, runs in the foreground, and stops and removes the container when the shell exits.
  Why it matters: These options determine how you interact with the container and what remains afterward.
• Image retrieval and command selection: Trace how Podman obtains the specified image from its registry, stores its layers locally, and uses `bash` instead of the image’s default Apache web server command.
  Why it matters: It explains both the initial download and why this example opens a shell instead of starting the web server.
• Container and host comparison: Describe what the shell exploration reveals by comparing `/etc/os-release`, available commands, and `ps` output inside the container with those on the host.
  Why it matters: The comparison makes the container’s distinct environment visible from the command line.

Key terms: podman run, -ti, --rm, foreground, registry.access.redhat.com/ubi8/httpd-24, layers, blobs, local container storage, default command, /etc/os-release

2.1.2 Running the containerized application

This section shows how to run a web-service container in the background, make it reachable from the host, and prepare or run additional containers.

• Detached application execution: Explain how running the image’s intended web application differs from opening an interactive shell in it. Describe how `-d` lets `podman run` exit while the container keeps running, and why this example omits `-ti` and `--rm`.
  Why it matters: These options determine whether you get a continuing service or an interactive session.
• Published container ports: Explain why the web server is not reachable through the host by default and how `-p` connects a host port to a container port. Describe the `HOST:CONTAINER` order, the single-port form, and how to discover the chosen mapping.
  Why it matters: Publishing a port is what lets a host-side browser reach the containerized web service.
• Rootless host port restriction: Explain why a rootless user generally cannot publish host port 80 and how mapping host port 8080 to container port 80 avoids that problem.
  Why it matters: The restriction applies to the host-side port even when the application can listen on a low port inside its container.
• Container names and port conflicts: Describe how `--name` gives a container a reusable identity and why launching the example’s second container requires both a new name and an unused host port.
  Why it matters: Names identify containers for later commands, while each running service needs an available host port.
• Container creation without execution: Distinguish `podman create` from `podman run`: describe how create obtains the image if needed and prepares a container without executing it, leaving it to be started later.
  Why it matters: Preparing a container separately lets another mechanism, such as a systemd unit, start it when needed.

Key terms: podman run, -d, --detach, -ti, --rm, --tty, -p, --publish, network namespace, host port

2.1.3 Stopping containers

This section shows how to stop running containers, what Podman does when stopping them, and how to change the signal, timeout, or containers selected.

• Graceful stop sequence: Explain that podman stop sends a stop signal, usually SIGTERM, to the container’s primary process (PID 1), waits 10 seconds by default for a graceful exit, and then sends SIGKILL if the container is still running.
  Why it matters: The default wait gives a container time to clean up before Podman forces it to stop.
• Stop targets and timeout: Describe how to stop a container by name or ID, use --latest (-l) for the last created container on Linux, use --all for all running containers, or set --timeout (-t), with -t 0 forcing an immediate kill.
  Why it matters: These options let you choose which containers to stop and whether to allow cleanup time.
• Custom signals and kill command: Distinguish changing a container’s stop signal with podman run --stop-signal from using podman kill to send a specified signal, which can be useful without stopping the container. Explain that a different stop signal matters when the primary process ignores SIGTERM, as systemd does.
  Why it matters: A container whose main process ignores SIGTERM may need another signal instead of waiting for a forced stop.

Key terms: podman stop, stop signal, SIGTERM, PID 1, SIGKILL, --timeout, -t 0, --latest, --all, --stop-signal

2.1.4 Starting containers

This section shows how to restart stopped containers with podman start and introduces options for starting multiple containers or connecting a terminal.

• Starting stopped containers: Explain that podman start starts one or more stopped containers, prints a container ID when a container starts, and lets you reconnect to the running application, such as through a web browser. Describe starting containers again after a reboot as a common use case.
  Why it matters: Starting a stopped container lets you resume using it without creating a new one.
• Start command terminal options: Distinguish the --all option, which starts all stopped containers in container storage, from --attach, which connects the terminal to container output, and --interactive (-i), which connects terminal input.
  Why it matters: These options let you choose how many containers to start and whether to interact with one through your terminal.

Key terms: podman start, container ID, stopped containers, --all, --attach, --interactive, -i

2.1.5 Listing containers

This section shows how to list running or previously created containers with `podman ps` and choose what its output includes.

• Running and all containers: Explain that `podman ps` lists running containers by default, while `podman ps --all` lists all containers, including ones created previously that are not running.
  Why it matters: Choosing the right listing helps you find a container before inspecting or managing it.
• Container listing output options: Describe how `podman ps --quiet` prints only container IDs and `podman ps --size` reports disk space used by each container apart from its base image; state that `man podman-ps` documents the other options.
  Why it matters: These options let you get IDs or container disk-use figures without confusing that use with the image’s size.

Key terms: podman ps, --all, running containers, --quiet, --size, container IDs, man podman-ps

2.1.6 Inspecting containers

This section shows how to examine a container’s detailed configuration with podman inspect and find specific information in its output.

• Container inspection purpose and scope: Explain when to use podman inspect instead of podman ps: inspect provides detailed information such as the source image, default environment variables, and security settings. Distinguish the general inspect command, which also works with other Podman objects, from podman container inspect, which is specific to containers.
  Why it matters: Choosing the right command helps you find details that a container listing does not show.
• Finding fields in inspect output: Describe how podman inspect produces a large JSON output and how to locate a particular field by piping it to less or grep or by using --format. Give the executed command or stop signal as an example of a field to examine.
  Why it matters: Filtering the output makes a specific container setting easier to find.
• Latest container and size options: State that --latest (-l) inspects the last created container without supplying its name or ID, while --size adds disk-space usage and is omitted by default because gathering it is slow.
  Why it matters: These options save typing or provide storage information when you need it.

Key terms: podman inspect, podman container inspect, podman ps, JSON, less, grep, --format, stop signal, --latest, -l

2.1.7 Removing containers

This section explains when and how to remove containers with `podman rm`, including options for removing all containers or forcing removal.

• Container removal sequence: Explain that removing an unneeded container frees disk space or makes its name available again, and describe stopping it before removing it with `podman rm`.
  Why it matters: Stopping a container first gives you the basic sequence for removing one you no longer need.
• Removal command options: Distinguish `podman rm --all`, which removes all containers, from `--force`, which tells Podman to stop running containers when removing them.
  Why it matters: These options change whether removal applies to every container or handles containers that are still running.

Key terms: podman rm, container name, --all, --force, man podman-rm

2.1.8 exec-ing into a container

This section shows how to run a command inside an existing container, change its web page, and observe that the change survives a restart.

• Executing inside a running container: Explain that podman exec starts an additional process in an existing, running container, whereas podman run creates a new container from an image. Describe using podman exec --interactive with the container name and a shell to work inside it.
  Why it matters: This lets you inspect or change a running container without creating a new one.
• Persistence of container edits: Describe how an exec-ed shell can create /var/www/html/index.html to change the website to display Hello World, and explain that the change remains in that container after it is stopped and restarted.
  Why it matters: The edited page provides a visible example of a change that stays with the container, setting up the next step of committing it to an image.

Key terms: podman exec, --interactive, -i, --tty, podman run, /var/www/html/index.html, Hello World, commit

2.1.9 Creating an image from a container

Shows how to save a configured container as a reusable OCI image with podman commit, while noting that scripted builds are the usual approach.

• Container-to-image commit workflow: Describe how to stop or pause a container so it cannot change during a commit, use podman commit to create an OCI image from it, and then either restart the original container or create a new one from the image.
  Why it matters: This lets you explain how a working container environment becomes an image others can run.
• Commit option purposes: Explain that podman commit --pause can pause a running container during the commit, while --change adds image-use instructions such as CMD or ENV that correspond to Containerfile or Dockerfile directives.
  Why it matters: These options explain how a commit can protect the captured state and supply instructions for the resulting image.
• Scripted image-building preference: Explain that creating images with podman commit is uncommon because the image-building process can instead be scripted and automated with podman build.
  Why it matters: It distinguishes an available way to capture a container from the usual reproducible building workflow.

Key terms: podman commit, OCI image, podman start, --pause, --change, CMD, ENV, Containerfile, Dockerfile, podman build

2.2 Working with container images

This introduction moves from basic container operations to working with images, distinguishing them from containers, and sharing them through registries.

• Container image learning roadmap: Describe how the section follows inspecting containers and committing one to an image, then turns to working with images, distinguishing images from containers, and sharing images through container registries.
  Why it matters: This connects the container operations you just tried to the image tasks that follow.

Key terms: container images, containers, container registries

2.2.1 Differences between a container and an image

Distinguishes containers from images, explains how committing a container creates a shareable layered image, and introduces commands for examining image layers and changes.

• Containers versus committed images: Distinguish a container as a running process or a non-running, uncommitted storage object from an image as committed content that can be shared and used to create new containers.
  Why it matters: The distinction makes Podman’s container and image commands easier to interpret.
• Layered image creation: Explain that committing a container copies its container storage into image storage and creates a new layer above the existing image layers. Describe image layers as TAR diffs applied over lower layers, while container content is an uncommitted layer.
  Why it matters: Layers explain how a modified container becomes a new image without replacing its underlying image.
• Image storage and transports: Describe the storage container as uncommitted files and descriptive data managed by containers/storage, and distinguish local image storage from the other places or transports through which container images can be stored or shared.
  Why it matters: These terms clarify whether the section is talking about unfinished local container data or a stored image.
• Image layer inspection commands: Describe how podman image tree shows an image’s layers and podman image diff shows files or directories changed, added, or deleted relative to another image or a lower layer.
  Why it matters: These commands let you check the layered contents and concrete filesystem changes discussed in the section.

Key terms: container, image, committed container, storage container, commit, image storage, layers, TAR diffs, uncommitted layer, myimage

2.2.2 Listing images

This section shows how to list locally stored images with Podman, reveal dangling images, and watch image storage use.

• Local image listings: Explain that `podman images` lists images in local storage and that its default output provides information about each image, including its size. Describe how `--all` changes which images appear.
  Why it matters: The image listing helps you find images and decide which ones need closer inspection.
• Dangling images and storage: Describe how replacing an image with a newer one using the same tag leaves the previous image tagged `<none><none>`, called a dangling image. Explain why image and container sizes should be monitored and unused items removed.
  Why it matters: Recognizing old images and watching storage use can help prevent the disk from filling up.

Key terms: podman images, local storage, --all, dangling images, <none><none>, man podman-system-prune

2.2.3 Inspecting images

This section shows how to inspect an image’s configuration, extract specific fields, and interpret an unspecified stop signal.

• Image inspection command and output: Explain that `podman image inspect` examines an image’s configuration and returns a large JSON array containing OCI Image Format data used when creating a container. Distinguish it from `podman image diff`, which shows file changes, and `podman image tree`, which shows image layers.
  Why it matters: Choosing the right command helps you find configuration details rather than file changes or image layers.
• Focused fields and stop signal: Describe how to find a particular value in the large inspect output using `less`, `grep`, or `--format`, including the image’s default command or stop signal. Explain that an empty stop-signal result means the developer did not specify `STOPSIGNAL`, so the default is 15 unless overridden on the command line.
  Why it matters: Extracting a field makes inspect output practical, while an empty field still has a meaningful default.

Key terms: podman image inspect, podman inspect, podman image diff, podman image tree, OCI Image Format, --format, STOPSIGNAL, stop signal, default command

2.2.4 Pushing images

This section explains how Podman pushes an image from local storage to another image store, especially a registry, and how to specify and authorize the destination.

• Image push and transports: Explain that `podman push` copies an image and all its layers out of local container storage to another form of image storage, such as a registry. Describe a transport as the type of storage used for that copy.
  Why it matters: This explains what a push copies and where Podman can send it.
• Push destination specification: Describe the `transport:ImageName` destination format and state that omitting the transport defaults to the docker, or container-registry, transport. Distinguish a locally created `localhost/myimage` from an image already associated with a remote registry when deciding whether a push needs an explicit destination.
  Why it matters: The destination determines where the image goes, and a locally created image does not already name a remote registry.
• Registry authorization and availability: Explain that a registry may reject a push until `podman login` supplies authorization, and that a successfully pushed image becomes available for authorized users to pull from that registry.
  Why it matters: A correctly named destination is not enough if the registry has not authorized the push.

Key terms: podman push, image layers, containers/storage, transport, containers/image, destination, transport:ImageName, docker transport, docker://, localhost/myimage

2.2.5 podman login: Logging into a container registry

This section shows how to authenticate to container registries with Podman and manage the credentials it stores.

• Registry login requirements: Explain when registry authentication is needed and how podman login obtains credentials: it prompts for a username and password unless they are supplied through options.
  Why it matters: A push, or a pull from a private registry, may fail until you log in.
• Authentication file storage and protection: Describe how podman login stores registry credentials in auth.json, why that file must be protected, and how its default location can be changed.
  Why it matters: The saved password is encoded, not encrypted, so the authentication file needs protection.
• Multiple logins and logout: Describe how repeated logins can store credentials for different registries in one auth.json file, and how podman logout removes cached credentials.
  Why it matters: You can manage access to several registries without treating each login as a separate authentication file.

Key terms: podman login, container registry, credentials, auth.json, /run/user/$UID/containers/auth.json, Base64, --auth-file, REGISTRY_AUTH_FILE, podman logout, --all

2.2.6 Tagging images

This section shows how to give a local image registry-ready and versioned names, push those names, and avoid treating the latest tag as a guarantee of recency.

• Multiple names for one image: Explain that podman tag adds another name to an existing image, such as naming localhost/myimage quay.io/rhatdan/myimage, without creating a different image. Describe how matching image IDs in podman images show that the names refer to the same image.
  Why it matters: Recognizing tags as names helps you identify which image you are publishing.
• Tagged image publishing workflow: Describe how assigning an image a quay.io name lets you log in and push it using that name without supplying a separate destination, and how adding a :1.0 tag lets you push that version too.
  Why it matters: Registry-ready names make it simpler to publish and retrieve the intended image version.
• Version tags versus latest: Explain that tags such as 1.0 let users select a particular application version, whereas latest is only an ordinary, often default, tag and does not guarantee the newest image. Justify choosing a specific version rather than relying on latest.
  Why it matters: An explicit version helps you run the image you intended, even when other versions are available.

Key terms: podman tag, localhost registry, image ID, podman images, quay.io/rhatdan/myimage, podman login, podman push, 1.0, latest, version

2.2.7 Removing images

This section shows how to reclaim local image storage with podman rmi and podman image prune, and explains when removing a tag does or does not remove image content.

• Tags and image storage: Explain why removing an image name with podman rmi may remove only a tag, and describe when the image's disk space is reclaimed. Describe how Podman handles a short name and a tag other than latest.
  Why it matters: A successful removal command does not necessarily mean the image content or its disk usage is gone.
• Image ID removal with force: Describe why removal by image ID fails when the image has multiple tags, and how podman rmi with --force changes the result.
  Why it matters: It provides a way to remove an image and all its tags without removing each tag separately.
• Pruning unused local images: Distinguish the images removed by podman image prune from those removed with its --all option, and state how to check Podman's storage usage.
  Why it matters: Pruning helps reclaim space when there are too many images and containers to inspect one by one.

Key terms: podman rmi, tag, image ID, short name, latest, --force, podman image prune, dangling images, --all, podman system df

2.2.8 Pulling images

This section explains how Podman pulls images into local storage, resolves short image names across registries, and helps avoid pulling from the wrong source.

• Pulling images into local storage: Explain that `podman pull` retrieves an image from a container registry into local container storage. Describe how commands such as `podman run` may pull a required image implicitly when it is not already local.
  Why it matters: This explains why an image can appear locally even when you did not run `podman pull` yourself.
• Full and short image names: Distinguish a fully specified image name from a short name: an image reference can identify a registry, repository, image name, and tag, with `latest` implicit when no tag is given. Explain that Docker resolves short names through its built-in `docker.io` registry, whereas Podman supports configurable registries rather than hardcoding just one.
  Why it matters: A short name is convenient, but it does not state every part of the image’s source.
• Short-name selection and safety: Justify using a full image name when the source matters: it specifies the registry and avoids selecting a same-named image elsewhere. Describe how Podman can prompt for an exact image on the first short-name pull, record the successful choice as a mapping, and subsequently reuse it; registry lists and shipped or company-provided short-name aliases also affect resolution.
  Why it matters: Choosing the wrong registry can mean pulling an image other than the one you intended.
• Pull architecture and output options: State that `podman pull --arch` requests an image for a different architecture instead of the native one, while `--quiet` or `-q` suppresses progress output and prints the image ID on completion.
  Why it matters: These options let you change which architecture you pull or reduce command output.

Key terms: podman pull, container registry, local container storage, podman images, short names, fully specified image name, registry, repository, tag, latest

2.2.9 Searching for images

This section shows how to find container images in a registry with podman search and how to adjust the displayed results.

• Registry image name search: Explain that podman search finds images in container registries by matching names when you do not know the exact image you want to run or use as a base image. Describe the example as searching registry.access.redhat.com for image names containing httpd.
  Why it matters: Searching helps you find a suitable image without knowing its exact name first.
• Search result display options: Describe how --no-trunc shows an image’s full description and --format customizes which fields podman search displays.
  Why it matters: These options help you see the information you need in search results.

Key terms: podman search, container registries, httpd, registry.access.redhat.com, --no-trunc, --format

2.2.10 Mounting images

This section shows how to inspect an image’s files without running a container, including the extra namespace step required in rootless mode.

• Container-free image inspection: Explain why mounting an image can be preferable to launching a shell in a container, and describe what podman image mount makes available.
  Why it matters: You can inspect image contents without relying on tools inside the container or running a potentially malicious application.
• Rootless image mount workflow: Describe why a direct image mount fails in rootless mode and trace the section’s workflow for inspecting and cleaning up the mount.
  Why it matters: The namespace step makes image inspection possible in rootless mode, while unmounting and exiting clean up the session.

Key terms: podman image mount, root filesystem, read-only mode, rootless mode, podman unshare, user namespace, mount namespace

2.3 Building images

This section introduces image building, explains why developers must maintain image contents, and identifies how Podman builds images from a Containerfile or Dockerfile.

• Image content maintenance responsibility: Explain that a built container image includes the application and a subset of the OS, so developers must keep all its contents current and secure; otherwise vulnerabilities accumulate as the image ages.
  Why it matters: Building an image also means taking responsibility for the software and security updates inside it.
• Podman image building workflow: Describe image building as creating a container image, and explain that podman build uses Buildah as a library and reads commands from a Containerfile or Dockerfile to automate the build.
  Why it matters: This connects the build command to the file that specifies how an image is made.
• Containerfile and Dockerfile compatibility: Distinguish Podman's default Containerfile name from the older Dockerfile name, while stating that they use the same syntax and Podman supports both; Docker can use a Containerfile when given the -f option.
  Why it matters: Knowing the naming difference helps you reuse build instructions across the two tools.

Key terms: container image, building, security updates, podman build, Buildah, Containerfile, Dockerfile, -f

2.3.1 Format of a Containerfile or Dockerfile

This section explains how Containerfile directives build an image’s filesystem, specify how to run it, and produce a stored image with podman build.

• Base image and rootfs: Explain how FROM establishes the rootfs for a new image, either from an existing base image or from an empty scratch image.
  Why it matters: The starting rootfs determines what content later build steps can add to.
• Rootfs content directives: Describe how COPY adds local files to the rootfs and RUN executes commands in a build container to change it, such as installing packages.
  Why it matters: These directives turn a starting image into one containing the application’s required files and software.
• Image runtime directives: Explain that Containerfile directives also record information about how to run the image: CMD and ENTRYPOINT set default command behavior, ENV sets default environment variables, and EXPOSE records ports used by podman run --publish-all.
  Why it matters: An image needs running instructions as well as filesystem content.
• Build commit and image tag: Trace how podman build finishes by committing the rootfs changes relative to the base image along with the image’s JSON configuration, and state that --tag names the resulting image in container storage.
  Why it matters: The commit makes the filesystem changes and running instructions into an image that can be reused.

Key terms: FROM, base image, scratch, rootfs, copy-on-write filesystem, COPY, RUN, podman build, OCI Runtime Specification, CMD

2.3.2 Automating the building of our application

This section builds an application image from a context directory, then explains how to rebuild it safely and manage the old image.

• Application image build sequence: Describe how to create the myapp context directory with index.html and a Containerfile, then run podman build with a tag and that context directory.
  Why it matters: These steps turn the application file and build instructions into a named image.
• Automated rebuild and verification: Explain that the build can be run regularly by CI/CD or cron, with tests checking the application before the previous version is replaced; the resulting image can then be pushed to a registry.
  Why it matters: Regular builds are useful only if a faulty replacement is caught before it takes over.
• Old image name and cleanup: Explain why rebuilding with the same tag leaves the previous image as a dangling <none> <none> image, and describe how to recover or remove it.
  Why it matters: Recognizing the old image lets you roll back a bad build or reclaim storage after a good one.

Key terms: context directory, Containerfile, FROM, COPY, podman build, --tag, CI/CD, cron job, test scripts, podman push

2.4 Summary

This summary recaps Podman’s container, image, and build commands and its compatibility with the Docker CLI.