> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-34-virtualization-and-container-management/di-34.3-jie-podman-rong-qi-guan-li.md).

# 34.3 Podman Container Management

Podman is an open-source container runtime led by Red Hat, serving as an alternative to Docker with a highly compatible command-line interface. Podman uses a daemonless architecture where each container runs as an independent process, eliminating the need for a constantly running background daemon, which improves system security and reduces the risk of single points of failure.

On the FreeBSD platform, Podman relies on the Linux compatibility layer (Linuxulator) when running Linux containers, and uses the Jail mechanism for isolation when running FreeBSD native containers. For containers running through the Linux compatibility layer, you can use the `jls` command to view their underlying Jail structure. Through `sysctl -d security.jail.param`, you can list all queryable Jail kernel parameters, which reflect the underlying Jail attributes corresponding to each container.

## Installing Podman

When installing the sysutils/podman-suite meta-package, it will also install sysutils/buildah (for building container images), sysutils/podman (container runtime), sysutils/skopeo (for manipulating container images), and sysutils/catatonit (container init process).

* **Install using pkg**:

```sh
# pkg install podman-suite
```

* **Install using Ports**:

```sh
# cd /usr/ports/sysutils/podman-suite/
# make install clean
```

* **View post-installation configuration information**:

```sh
# pkg info -D podman
```

## Configuring the fstab File

To use Podman on FreeBSD, you need to configure filesystem mount points. fdescfs is a file descriptor filesystem provided by FreeBSD that maps process file descriptors to filesystem nodes; Podman depends on this filesystem to pass file descriptors inside containers.

Add the following line to the **/etc/fstab** file:

```ini
fdesc   /dev/fd         fdescfs         rw      0       0
```

Then execute the following command to make it take effect immediately:

```sh
# mount -t fdescfs fdesc /dev/fd
```

## Configuring the Network

Podman uses the PF (Packet Filter) firewall for address translation and traffic control of container networks, allowing containers to access external networks through the host's network interface.

If PF has not been previously configured on the system, you can directly copy the configuration example provided by Podman:

```sh
# cp /usr/local/etc/containers/pf.conf.sample /etc/pf.conf
```

Edit the **/etc/pf.conf** file, replacing `ix0` with the currently used network card; you can check it with the `ifconfig` command:

```ini
# Set the IPv4 egress network interface
v4egress_if = "ix0"

# Set the IPv6 egress network interface
v6egress_if = "ix0"
```

If the system already has PF running with a custom rule set, directly copying the example file will overwrite the existing configuration. In this case, you should only extract the rules related to container networking and append them to the existing **/etc/pf.conf**. The core content to add is as follows:

```ini
# Podman container network NAT anchors and rules
nat-anchor "cni-rdr/*"
rdr-anchor "cni-rdr/*"
nat on $ext_if inet from 10.88.0.0/16 to any -> ($ext_if)
```

Where `$ext_if` needs to be replaced with the actual network card name, and the subnet `10.88.0.0/16` is the Podman default bridge subnet. After adding the rules, execute `pfctl -f /etc/pf.conf` to reload the configuration for it to take effect.

Next, start the PF firewall. The `net.pf.filter_local=1` parameter enables PF filtering for packets destined to the local machine's address; once enabled, PF can apply NAT/rdr rules to such packets, thereby enabling network communication between containers and the host.

```sh
# kldload pf # Load kernel module; only needs to be done once, will auto-load thereafter
# echo 'net.pf.filter_local=1' >> /etc/sysctl.conf # Redirect container host connections to inside the container
# sysctl net.pf.filter_local=1 # Take effect immediately
# service pf enable # Enable the pf firewall service
# service pf start # Start the pf firewall
```

## Creating a ZFS Storage Pool

To manage container storage resources, it is recommended to create a dedicated ZFS filesystem. The specific steps are as follows:

Create a ZFS filesystem `zroot/containers` and set the mount point to **/var/db/containers**:

```sh
# zfs create -o mountpoint=/var/db/containers zroot/containers
```

## Starting Services

Start the related services:

```sh
# service linux enable # Set Linux compatibility service to start at boot
# service linux start # Start Linux compatibility service
# service podman enable # Set Podman service to start at boot
# service podman start # Start Podman service
```

Project structure:

```sh
/
├── etc/
│   ├── fstab # Filesystem mount configuration
│   ├── pf.conf # PF firewall configuration
│   └── sysctl.conf # sysctl configuration
├── run/
│   └── containers/
│       └── 0/
│           └── auth.json # Runtime authentication credentials location (default read/write location, may be lost after reboot)
├── root/
│   └── .config/
│       └── containers/
│           └── auth.json # Persistent authentication credentials location (fallback read location, preserved after reboot)
├── var/
│   └── db/
│       └── containers/ # Container database directory
└── usr/
    └── local/
         └── etc/
           └── containers/
                └── pf.conf.sample # PF firewall configuration example

```

## Testing the Ubuntu Image

After the services are started, you can test pulling the Ubuntu image to verify that Podman is working properly:

* **Test pulling the Ubuntu image**:

```sh
# podman pull --os=linux docker.io/library/ubuntu:latest
Trying to pull docker.io/library/ubuntu:latest...
Getting image source signatures
Copying blob 0622fac788ed done   |
Copying config a0e45e2ce6 done   |
Writing manifest to image destination
a0e45e2ce6e6e22e73185397d162a64fcf2f80a41c597015cab05d9a7b5913ce
```

* **View currently pulled images**:

```sh
# podman images
REPOSITORYTAG IMAGE ID  CREATED  SIZE
docker.io/library/ubuntu  latest  a0e45e2ce6e6  3 weeks ago  80.6 MB
```

* **Print system version (only the first 5 lines)**:

```sh
# podman run --os=linux ubuntu /usr/bin/cat "/etc/os-release" | head -5
PRETTY_NAME="Ubuntu 24.04.2 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"
VERSION="24.04.2 LTS (Noble Numbat)"
VERSION_CODENAME=noble
```

* **Enter the container**:

```sh
# podman run -it --os=linux ubuntu /bin/bash # Enter the container
root@3b6d47dea81e:/# apt update # Now inside the container
Get:1 http://archive.ubuntu.com/ubuntu noble InRelease [256 kB]
Get:2 http://security.ubuntu.com/ubuntu noble-security InRelease [126 kB]

...omitted below...

root@3b6d47dea81e:/# exit # Exit the container
exit
# # Returned to the host
```

## Testing the Nginx Container Packaged by FreeBSD Maintainers

In addition to Linux images, Podman can also run FreeBSD native containers. This section tests the Nginx container packaged by FreeBSD maintainers:

```sh
# Pull the nginx image from quay.io
# podman pull quay.io/dougrabson/nginx

# Create and run the container mynginx in the background using this image, mapping host port 8080 to container port 80
# podman run -d --name mynginx -p 8080:80 quay.io/dougrabson/nginx
```

Open `http://ip:8080` in a browser to access the Nginx test page.

## More Usage

* **View logs**:

```sh
# podman logs container_name
```

* **View container running status**:

```sh
# podman ps # View currently running containers
CONTAINER ID  IMAGECOMMAND   CREATED STATUSPORTS NAMES
ca088c9c56fc  quay.io/dougrabson/nginx:latest  /usr/local/sbin/n...  3 minutes agoUp 3 minutes  0.0.0.0:8080->80/tcp  mynginx
# podman ps -a # View all statuses, including containers that failed to run
CONTAINER ID  IMAGECOMMAND   CREATED STATUS PORTS  NAMES
e8ea65b7e6c9  docker.io/library/nginx:latest   nginx -g daemon o...  17 minutes ago Exited (0) 292 years ago   0.0.0.0:8080->80/tcp   nginx-test
ca088c9c56fc  quay.io/dougrabson/nginx:latest  /usr/local/sbin/n...  3 minutes ago Up 3 minutes   0.0.0.0:8080->80/tcp   mynginx
```

* **Stop and remove a container**:

```sh
# podman stop container_name # Stop the container
# podman rm container_name  # Remove the container
```

* **Remove an image (must remove containers referencing the image first)**:

```sh
# podman rmi image_name
```

## Using FreeBSD Containers

In addition to containers provided by third-party maintainers, you can also directly pull the official FreeBSD image from Docker Hub:

```sh
# podman pull docker://freebsd/freebsd-runtime:15.0
```

## References

* daemonless. "Networking FreeBSD Podman containers support several networking modes."\[EB/OL]. \[2026-03-25]. <https://daemonless.io/guides/networking/>. Firewall examples
* freebsd/freebsd-runtime\[EB/OL]. \[2026-03-26]. <https://hub.docker.com/r/freebsd/freebsd-runtime/tags>. Tag list for the official FreeBSD runtime base image on Docker Hub.
* Podman Project. Podman Installation Instructions\[EB/OL]. \[2026-03-25]. <https://podman.io/docs/installation>. Official installation tutorial detailing Podman deployment steps.
* Josphat Mutai. Install Podman and run Containers in FreeBSD 14\[EB/OL]. cloudspinx.com, \[2026-03-25]. <https://cloudspinx.com/install-podman-and-run-containers-in-freebsd/>. Provides a practical Podman configuration guide on FreeBSD 14.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://book.bsdcn.org/ask/flat/chapter-34-virtualization-and-container-management/di-34.3-jie-podman-rong-qi-guan-li.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.