DOCSEARCHbyAlgolia
Submit Docs

Podman

repository·main·Indexed 12 days ago

https://github.com/containers/podman

A daemonless tool for managing OCI containers, images, volumes, and pods. It supports rootful and rootless modes and is compatible with the Docker CLI and REST API. This documentation includes guides for extending the Podman CLI in Go (v6), managing dependencies with goda, installing shell completions, and configuring systemd socket activation for root and rootless services.

Tokens
255.9K
Snippets
984
Records
1.2K
Agent score
98%

What's inside Podman

  1. What is Podman?

    main

    Podman (the POD MANager) is a tool for managing OCI containers and images, volumes, and pods (groups of containers).

    Key characteristics:

    • Daemonless: Unlike Docker, Podman does not require a central manager daemon, which improves security and reduces idle resource usage.
    • Multi-platform: Runs natively on Linux and uses a managed virtual machine (podman machine) on macOS and Windows.
    • Rootless: Supports running containers without root or elevated privileges using user namespaces.
    • OCI Compliant: Supports multiple container image formats, including OCI and Docker images.
    • API Support: Provides a REST API that includes a Docker-compatible interface and an advanced interface for Podman-specific features.
    • Pod Support: Allows managing groups of containers as a single unit (pods) that share resources.

  3. Manage OCI artifacts with podman artifact

    main

    The podman artifact command provides a suite of subcommands for managing OCI (Open Container Initiative) artifacts. These artifacts are files associated with OCI images and containers. Podman manages them through a local "artifact store," allowing you to pull, inspect, push, and extract them.

    Available subcommands include:

    • add: Add an OCI artifact to the local artifact store.
    • extract: Extract an OCI artifact to a specified local path.
    • inspect: Inspect the metadata or contents of an OCI artifact.
    • ls (alias for list): List all OCI artifacts currently in the local store.
    • pull: Download an artifact from a remote registry and store it locally.
    • push: Upload an OCI artifact from local storage to a remote image registry.
    • rm: Remove one or more OCI artifacts from local storage.
    podman artifact <subcommand>

  4. Use podman-manifest to manage manifest lists and image indexes

    main

    The podman manifest command is used to create and manipulate Docker manifest lists or OCI image indexes. This allows you to group multiple images (often for different architectures) under a single tag.

    Available Subcommands

    CommandDescription
    addAdd an image or artifact to a manifest list or image index.
    annotateAdd and update information about an image or artifact in a manifest list or image index.
    createCreate a manifest list or image index.
    existsCheck if the given manifest list exists in local storage.
    inspectDisplay a manifest list or image index.
    pushPush a manifest list or image index to a registry.
    removeRemove an item from a manifest list or image index.
    rmRemove the manifest list or image index from local storage.

  6. Understand the Podman codebase structure

    main

    The Podman repository is organized into several key directories that separate the CLI, the core engine, and the API layers:

    • bin/: Contains the compiled binaries (e.g., podman, podman-remote, quadlet).
    • cmd/: Contains the source code for individual binaries. cmd/podman/ handles the CLI commands and flags using the Cobra library, while cmd/quadlet/ handles Quadlet-specific logic.
    • libpod/: The core engine (Linux and FreeBSD only). It manages containers, pods, and volumes. It uses SQLite or Botldb for disk storage and integrates with containers/storage, containers/buildah, and containers/common/libnetwork.
    • pkg/: Contains reusable logic and interfaces:
      • pkg/api/: The HTTP REST API server implementation.
      • pkg/bindings/: The HTTP REST API client code. This is a stable interface intended for external consumers.
      • pkg/domain/: The "glue" layer between the CLI and core operations. It uses ContainerEngine and ImageEngine interfaces to map CLI commands to either local operations (pkg/domain/infra/abi/) or remote operations via the API (pkg/domain/infra/tunnel/).
      • pkg/libartifact/: Logic for Podman artifact commands.
      • pkg/machine/: Logic for podman machine commands.
    • test/: Test suites (Linux only).
    • vendor/: Go dependencies managed via go mod vendor. Do not edit this directory directly.

  7. Manage container images with podman image

    main

    The podman image command is the entry point for managing container images in Podman. It provides a suite of subcommands to perform lifecycle operations such as building, pulling, pushing, inspecting, and removing images.

    Common workflows include:

    • Building: Create images from a Dockerfile using build.
    • Registry Operations: Use pull to download images, push to upload them, and search to find them in a registry.
    • Local Management: Use list (or the alias ls) to view local images, rm to delete them, and prune to clean up unused images.
    • Inspection: Use inspect to view configuration or history to see the image's layer history.
    # Example: List all local images
podman image list

# Example: Pull an image from a registry
podman image pull <image_name>

  8. Access Podman online documentation and API reference

    main

    Podman's official documentation, including man pages and command references, is hosted on Read The Docs. The API reference is automatically generated using Redoc from a Swagger/OpenAPI specification.

    • Online Documentation: Read The Docs
    • Command Reference: Available under the Commands link on the Read The Docs site.
    • API Reference: Latest Online API Documentation
    • Swagger/OpenAPI Spec: You can download the swagger.yaml file directly to inspect the API definition.

    To download a specific version of the Swagger file, replace latest in the URL with the desired version (e.g., v6.0.0): https://docs.podman.io/en/v6.0.0/_static/swagger.yaml

    https://docs.podman.io/en/latest/_static/swagger.yaml

  9. Manage Podman's virtual machine with podman machine

    main

    The podman machine command is used to manage the virtual machine (VM) required to run Linux containers on non-Linux operating systems. While Podman on Linux can run containers directly, MacOS and Windows require a VM because container core functionality is tied to the Linux kernel.

    Key details:

    • All podman machine commands are rootless only.
    • Configuration files are managed under $XDG_CONFIG_HOME/containers/podman/machine/.
    • Warning: Do not change the $XDG_CONFIG_HOME environment variable while machines are running, as this can cause unexpected behavior.
    • Behavior can be modified via the [machine] section in the containers.conf(5) file.

  10. What is podmansh and how does it work?

    main

    podmansh is a tool that executes a user's login shell inside a Podman container when they log into the system. This allows administrators to provide users with a confined environment that is isolated from the host OS using container security mechanisms like SELinux.

    Key Concepts

    • Automatic Lifecycle: Systemd automatically starts the container when the user session begins and shuts it down when all connections to the user session are removed. Multiple login sessions for the same user will connect to the same container.
    • Isolation: Users are confined to the container environment. The only host information available to them is what is explicitly exposed via volumes.
    • Configuration via Quadlets: The container behavior (image, volumes, capabilities, etc.) is defined using Podman Quadlet files.
    • Scope of Quadlets:
      • Global: Placing Quadlet files in /etc/containers/systemd/users/ makes the container available for all users.
      • User-Specific: Placing Quadlet files in /etc/containers/systemd/users/${UID}/ ensures only that specific user triggers the container upon login.
    • Timeout: The session timeout can be configured using the podmansh_timeout option in containers.conf.

  11. Overview of Podman security architecture

    main

    Podman is a daemonless container engine designed for managing OCI containers and pods with a primary focus on security. Unlike traditional container engines, Podman operates without a background daemon process, which reduces the attack surface.

    Key security pillars include:

    • Rootless operation: Allows running containers without root privileges, preventing privilege escalation if a container is compromised.
    • Daemonless architecture: Eliminates the central daemon process, removing a high-value target for attacks.
    • Pod support: Native support for Kubernetes-style pods with proper security isolation.
    • OCI Compliance: Maintains compatibility with Open Container Initiative specifications for interoperability and standard security enforcement.

  12. What is Podman Quadlet and how does it work?

    main

    Podman Quadlet is a tool that simplifies container lifecycle management by using declarative unit files (e.g., .container, .volume). Quadlet translates these files into standard systemd services, allowing you to manage containers using systemctl.

    Key concepts:

    • Declarative Files: You define the desired state (image, ports, volumes) in a configuration file.
    • Systemd Integration: Quadlet generates systemd units from these files, making containers behave like native system services.
    • Lifecycle: You manage the containers via systemctl start, systemctl stop, etc., rather than calling podman run directly.