# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2026-08-16 15:11-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: Yaml Front Matter Hash Value: description #: documentation/content/en/books/handbook/containers/_index.adoc:1 #, no-wrap msgid "OCI Containers provide an industry-standard way to describe, distribute, and run container-based workloads" msgstr "" #. type: Yaml Front Matter Hash Value: part #: documentation/content/en/books/handbook/containers/_index.adoc:1 #, no-wrap msgid "Part III. System Administration" msgstr "" #. type: Yaml Front Matter Hash Value: title #: documentation/content/en/books/handbook/containers/_index.adoc:1 #, no-wrap msgid "Chapter 18. OCI Containers" msgstr "" #. type: Title = #: documentation/content/en/books/handbook/containers/_index.adoc:15 #, no-wrap msgid "OCI Containers" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:52 #, no-wrap msgid "Synopsis" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:58 msgid "" "The https://opencontainers.org/[Open Container Initiative], commonly " "referred to as `+OCI+`, provides a vendor and OS-agnostic way to describe, " "distribute, and run containers. The OCI specifications provide these in a " "way that can be used on many different operating systems, including " "FreeBSD. The underlying virtualization technology is still FreeBSD jails, " "with the same feature set, but OCI tooling enables additional ways of " "working, and constructing, container-based workloads. https://" "www.freebsd.org/releases/14.3R/announce/[14.3-RELEASE] and upwards, " "including https://download.freebsd.org/snapshots/OCI-IMAGES/[snapshots], now " "include OCI-compatible images, and the https://podman.io/[Podman] toolkit on " "FreeBSD is ready to use them, on both amd64 and arm64 architectures." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:60 msgid "For FreeBSD users familiar with jails, there is a loose analogy:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:62 msgid "FreeBSD's `+base.txz+` tarball is an example of a container image." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:63 msgid "" "the `+jail.conf+` file describes the desired container properties, or " "`+Containerfile+`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:64 msgid "" "use the `+jail ..+` command to run a container, given a filesystem path, " "with the `+podman+` suite of tools." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:68 msgid "" "By importing this container stack, FreeBSD users both benefit from common " "tooling, but also enjoy wide support across public and private container " "registries, and container-specific tooling and services. In the https://" "download.freebsd.org/releases/OCI-IMAGES/{rel-latest}-RELEASE/aarch64/Latest/" "[aarch64] and https://download.freebsd.org/releases/OCI-IMAGES/{rel-latest}-" "RELEASE/amd64/Latest/[amd64] download directories, you'll see official OCI-" "format images. The naming may be a little confusing at first, but should " "make sense once you start using them." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:70 msgid "" "The same images are also available through common public container " "registries, including https://hub.docker.com/u/freebsd[Docker Hub], and " "https://github.com/orgs/freebsd/packages[Github Container Registry], but for " "the strongest chain of trust, you should fetch your image directly from " "https://download.freebsd.org/releases[Official FreeBSD Releases], and import " "them to your local system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:73 msgid "" "Each image comprises a subset of a standard FreeBSD `+base.txz+` release " "tarball, for various use cases, and the usual FreeBSD `+CHECKSUM.*+` files, " "that can be verified against the PGP-signed release announcement. This " "gives a very strong chain of provenance, directly verifiable from the " "FreeBSD release team." msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:83 #, no-wrap msgid "" "CHECKSUM.SHA256\n" "CHECKSUM.SHA512\n" "FreeBSD-{rel-latest}-RELEASE-amd64-container-image-static.txz\n" "FreeBSD-{rel-latest}-RELEASE-amd64-container-image-dynamic.txz\n" "FreeBSD-{rel-latest}-RELEASE-amd64-container-image-runtime.txz\n" "FreeBSD-{rel-latest}-RELEASE-amd64-container-image-notoolchain.txz\n" "FreeBSD-{rel-latest}-RELEASE-amd64-container-image-toolchain.txz\n" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:86 #, no-wrap msgid "Container Image Naming and Tagging" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:88 #, no-wrap msgid "Introduction" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:93 msgid "" "FreeBSD's official container images are built from base system packages, " "themselves built during the FreeBSD release process, and published to public " "registries. This guide explains how images are named and tagged, helping " "you choose the right image for your needs, and ensuring you understand the " "implications of each choice, as new images are published, and in some cases, " "mutable tags are amended. This naming convention aligns with the new base " "system package naming scheme, giving clear provenance between container " "images and the corresponding FreeBSD releases." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:95 #, no-wrap msgid "Available Image Types" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:98 msgid "" "Five types of FreeBSD container images are available, for `+amd64+` and " "`+aarch64+` architectures." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/containers/_index.adoc:100 #, no-wrap msgid "`+freebsd-static+`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:103 msgid "" "The static image is intended as a base image, for a workload which is " "entirely statically linked. It contains no libraries, nor binaries, just the " "supporting files that most applications of this nature require." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:105 msgid "public TLS certificates" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:106 msgid "minimal password file" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:107 msgid "minimal termcap" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:108 msgid "timezone database" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:112 msgid "" "Note that it has, by design, a lean footprint, to make a security compromise " "of the container less useful to the attacker. There's no UNIX shell, no " "command-line tools, no dynamic libraries, nor package manager. It is the " "smallest image provided by the FreeBSD project." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/containers/_index.adoc:114 #, no-wrap msgid "`+freebsd-dynamic+`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:120 msgid "" "The dynamic image uses the static image as a parent layer, and supports " "using shared libraries, including `+libc+`. Most FreeBSD software should " "run without issue with this image, with minor changes. It doesn't have a " "shell, rc system, nor a package manager. These limitations are additional " "security, making it awkward for attackers in a compromised container to move " "laterally, or make use of tools that were never installed." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/containers/_index.adoc:122 #, no-wrap msgid "`+freebsd-runtime+`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:128 msgid "" "Again, runtime builds on the preceding dynamic layer, and finally adds the " "minimum that a user would expect - a UNIX shell, rc system, and the package " "manager. It is the ideal base image for porting existing applications with " "a minimum of changes. Users will need to include additional FreeBSD base " "system libraries, as well as additional packages from the Ports tree. This " "is the closest to a typical FreeBSD system, including the man:pkg[8] tool, " "allowing users to install, or do, almost anything, similar to a non-" "containerised system." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/containers/_index.adoc:130 #, no-wrap msgid "`+freebsd-notoolchain+`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:133 msgid "" "This base image contains almost all tools one would expect on a typical " "FreeBSD system, excluding those that are directly hardware-related, and thus " "not generally useful within a container, and the compiler and related " "toolchain, as it is quite large." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/containers/_index.adoc:135 #, no-wrap msgid "`+freebsd-toolchain+`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:140 msgid "" "The Toolchain base image is the sum of all preceding images, including a " "full compiler and toolchain. It is generally possible to compile almost any " "software for FreeBSD in the same way as a normal non-jailed FreeBSD system. " "All images follow a consistent naming pattern, derived from the FreeBSD " "release they are based upon." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:142 #, no-wrap msgid "Image Tag Structure" msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/containers/_index.adoc:145 #, no-wrap msgid "Immutable Tags" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:151 msgid "" "Immutable tags never change and are ideal for production systems where you " "need stability and predictability. These are the most common tags used by " "the release process. They will not change, even after FreeBSD security " "patches, or errata notices. They are ideal for base images for software " "deployments where a high degree of reproducibility is expected, even as a " "trade-off against more pro-active security patching." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:153 msgid "" "`+major.minor+` (e.g., `+14.4+`): Points to a specific FreeBSD RELEASE " "version" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:154 msgid "" "`+major.minor.pX+` (e.g., `+14.4p1+`): Points to a specific patch level of a " "RELEASE" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:155 msgid "" "`+major.snapYYYYMMDDHHMMSS+` (e.g., `+16.snap20260325035941+`): a snapshot " "build with timestamp" msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/containers/_index.adoc:157 #, no-wrap msgid "Mutable Tags" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:160 msgid "" "Mutable tags are updated over time and are ideal for production, or CI/CD " "systems that always want the latest updates, but still wish to align with " "FreeBSD ABI compatibility." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:162 msgid "" "`+major+` (e.g., `+15+`) will always be the latest support RELEASE version " "along the 15.x stable ABI" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:165 msgid "" "`+major.snap+` (e.g., `+15.snap+`) follows the latest developer snapshot " "along the 15.x stable ABI train, will often be in advance of official " "releases, and carries a risk of breakage, incompatibility, or other " "unanticipated issues. This is the most mutable tag, and should be used with " "caution. They are exactly the same as using FreeBSD's STABLE or CURRENT " "snapshots, as they use those images as their source." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:166 #, no-wrap msgid "When to Use Each Tag Type" msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/containers/_index.adoc:168 #, no-wrap msgid "For Production" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:171 msgid "Use immutable tags to ensure your environment stays consistent:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:173 msgid "`+freebsd-runtime:15.0+` - pinned to FreeBSD 15.0-RELEASE" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:175 msgid "" "When security patches are released, you must explicitly rebuild or update " "with a new image tag." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/containers/_index.adoc:176 #, no-wrap msgid "For Continuous Integration and Development" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:179 msgid "Use mutable tags to automatically get the latest updates:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:181 msgid "" "`+freebsd-runtime:15+` - always the latest official RELEASE in the 15.x " "series" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:184 msgid "" "These additional mutable tags will follow the regular published snapshots of " "FreeBSD STABLE and CURRENT. Use these if you want to test against what " "subsequent future releases of FreeBSD may contain, and accept occasional " "breakage or unanticipated changes." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:186 msgid "" "`+freebsd-runtime:14.snap+` - always the latest build from 14-STABLE branch" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:187 msgid "" "`+freebsd-runtime:15.snap+` - always the latest build from 15-STABLE branch" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:188 msgid "" "`+freebsd-runtime:16.snap+` - always the latest build from 16-CURRENT branch" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:190 #, no-wrap msgid "Official Registry Locations" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:193 msgid "" "Architecture-independent images can be downloaded and directly imported into " "your own registry from the https://download.freebsd.org/releases[Official " "FreeBSD Releases] site, or alternatively, pulled from the FreeBSD project's " "https://hub.docker.com/u/freebsd[Docker Hub], or https://github.com/orgs/" "freebsd/packages[GitHub Container Registry]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:195 msgid "" "Both https://hub.docker.com/_/alpine/[Alpine Linux] and the https://" "hub.docker.com/_/debian/[Debian] project publish tagged and mutable images, " "using similar approaches." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:197 #, no-wrap msgid "Introduction to Podman" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:200 msgid "" "The Podman suite comprises three main tools and a number of supporting ones:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:202 msgid "" "https://podman.io/[podman] is a daemonless container engine using docker-" "compatible commands" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:203 msgid "https://buildah.io/[buildah] generates OCI formatted container images" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:204 msgid "" "https://github.com/containers/skopeo[skopeo] works with remote OCI image " "registries" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:206 #, no-wrap msgid "Preparing the System for Podman Containers" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/containers/_index.adoc:211 msgid "" "If running commands over SSH, or in a similar remote session, use " "man:screen[1], man:tmux[1], or similar to avoid losing the connection while " "restarting the firewall." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:214 msgid "" "If ZFS is not available, switch to UFS storage and skip the ZFS commands " "below:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:219 #, no-wrap msgid "" "# sed -I .bak -e 's/driver = \"zfs\"/driver = \"vfs\"/' \\\n" " /usr/local/etc/containers/storage.conf\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:222 msgid "Otherwise, create the container storage dataset:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:227 #, no-wrap msgid "" "# zfs create -o mountpoint=/var/db/containers zroot/containers\n" "# zfs snapshot zroot/containers@empty\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:230 msgid "The File Descriptor filesystem is required:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:234 #, no-wrap msgid "# mount -t fdescfs fdesc /dev/fd\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:237 msgid "" "Podman uses FreeBSD's packet filter to forward container ports to the host " "network:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:242 #, no-wrap msgid "" "# test -c /dev/pf || kldload pf\n" "# sysctl net.pf.filter_local=1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:245 msgid "" "Amend `+/etc/sysctl.conf+` and `+/etc/fstab+` as appropriate, to make these " "changes permanent." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:247 #, no-wrap msgid "Installing Podman" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:250 msgid "" "Only the `+sysutils/podman-suite+` meta-package is required, but if the " "additional package:emulators/qemu-user-static[] package is installed, it " "becomes possible to build or test images for other architectures such as " "`+arm64+` on an `+amd64+` host." msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:254 #, no-wrap msgid "# pkg install -r FreeBSD -y podman-suite emulators/qemu-user-static\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:257 msgid "" "Integrate changes from `+/usr/local/etc/containers/pf.conf.sample+` into `+/" "etc/pf.conf+`, setting egress macros appropriately, then restart the " "firewall:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:261 #, no-wrap msgid "# service pf restart\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:265 msgid "" "The packages install a number of template configuration files, none of which " "need to be edited immediately. Review and amend these as needed:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:277 #, no-wrap msgid "" "# pkg list buildah podman conmon \\\n" " ocijail containers-common \\\n" " containernetworking-plugins \\\n" " | grep /etc/\n" "/usr/local/etc/containers/containers.conf.sample\n" "/usr/local/etc/containers/policy.json.sample\n" "/usr/local/etc/containers/registries.conf.sample\n" "/usr/local/etc/containers/storage.conf.sample\n" "/usr/local/etc/containers/pf.conf.sample\n" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:280 #, no-wrap msgid "Importing and Running Containers" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/containers/_index.adoc:285 msgid "" "At present, all Podman containers on FreeBSD must run as root, as FreeBSD " "jails require this." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:288 msgid "" "With the necessary tools and firewall rules in place, the officially " "published images can be fetched from https://download.freebsd.org/releases/" "OCI-IMAGES/[FreeBSD Releases], for https://download.freebsd.org/releases/OCI-" "IMAGES/{rel-latest}-RELEASE/aarch64/Latest/[aarch64] or https://" "download.freebsd.org/releases/OCI-IMAGES/{rel-latest}-RELEASE/amd64/Latest/" "[amd64] as appropriate." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:290 #, no-wrap msgid "Importing FreeBSD OCI Images" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:293 msgid "" "It is simplest to pull images directly from a public container registry, but " "for the strongest chain of trust, download them from https://" "download.freebsd.org/releases[FreeBSD.org] directly, and verify the " "checksums against the PGP-signed release announcement." msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:303 #, no-wrap msgid "" "# export OCIBASE=https://download.freebsd.org/releases/OCI-IMAGES/{rel-latest}-RELEASE/amd64/Latest\n" "# podman load -i=$OCIBASE/FreeBSD-{rel-latest}-RELEASE-amd64-container-image-static.txz\n" "Getting image source signatures\n" "Copying blob 44defc6cee2e done |\n" "Copying config 5921c62e76 done |\n" "Writing manifest to image destination\n" "Loaded image: localhost/freebsd-static:{rel-latest}-RELEASE-amd64\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:310 #, no-wrap msgid "" "# podman load -i=$OCIBASE/FreeBSD-{rel-latest}-RELEASE-amd64-container-image-dynamic.txz\n" "Getting image source signatures\n" "Copying blob 6054dffc3887 done |\n" "Copying config 33427d59f9 done |\n" "Writing manifest to image destination\n" "Loaded image: localhost/freebsd-dynamic:{rel-latest}-RELEASE-amd64\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:317 #, no-wrap msgid "" "# podman load -i=$OCIBASE/FreeBSD-{rel-latest}-RELEASE-amd64-container-image-runtime.txz\n" "Getting image source signatures\n" "Copying blob dcbbfcb598fe done |\n" "Copying config 90c4936754 done |\n" "Writing manifest to image destination\n" "Loaded image: localhost/freebsd-runtime:{rel-latest}-RELEASE-amd64\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:324 #, no-wrap msgid "" "# podman load -i=$OCIBASE/FreeBSD-{rel-latest}-RELEASE-amd64-container-image-notoolchain.txz\n" "Getting image source signatures\n" "Copying blob a16c94176cc3 done |\n" "Copying config 086572f35c done |\n" "Writing manifest to image destination\n" "Loaded image: localhost/freebsd-notoolchain:{rel-latest}-RELEASE-amd64\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:331 #, no-wrap msgid "" "# podman load -i=$OCIBASE/FreeBSD-{rel-latest}-RELEASE-amd64-container-image-toolchain.txz\n" "Getting image source signatures\n" "Copying blob b04531b7d93d done |\n" "Copying config b927c11b2e done |\n" "Writing manifest to image destination\n" "Loaded image: localhost/freebsd-toolchain:{rel-latest}-RELEASE-amd64\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:334 #, no-wrap msgid "Listing Images" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:345 #, no-wrap msgid "" "# podman images\n" "REPOSITORY TAG IMAGE ID CREATED SIZE\n" "localhost/freebsd-toolchain {rel-latest}-RELEASE-amd64 b927c11b2e8d 13 days ago 660 MB\n" "localhost/freebsd-notoolchain {rel-latest}-RELEASE-amd64 086572f35cc9 13 days ago 152 MB\n" "localhost/freebsd-runtime {rel-latest}-RELEASE-amd64 90c493675429 13 days ago 34.1 MB\n" "localhost/freebsd-dynamic {rel-latest}-RELEASE-amd64 33427d59f990 13 days ago 14.5 MB\n" "localhost/freebsd-static {rel-latest}-RELEASE-amd64 5921c62e76c1 13 days ago 2.92 MB\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:348 msgid "" "Note that the image IDs are reproducible each time, and the `+IMAGE_ID+` " "column matches the hashes reported when importing the images." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:350 #, no-wrap msgid "Listing Layers" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:353 msgid "" "It is possible to show the layers that comprise an image, demonstrating how " "the `+runtime+` image has three components, each one a layer in its own " "right:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:364 #, no-wrap msgid "" "# podman image tree ghcr.io/freebsd/freebsd-runtime:14.2\n" "Image ID: c5f3e77557a9\n" "Tags: [ghcr.io/freebsd/freebsd-runtime:14.2]\n" "Size: 35.07MB\n" "Image Layers\n" "├── ID: cd53fb07fb66 Size: 5.449MB Top Layer of: [ghcr.io/freebsd/freebsd-static:14.2]\n" "├── ID: a01d37f7777b Size: 10.4MB Top Layer of: [ghcr.io/freebsd/freebsd-dynamic:14.2]\n" "└── ID: 36b0c80ca1f7 Size: 19.21MB Top Layer of: [ghcr.io/freebsd/freebsd-runtime:14.2]\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:367 #, no-wrap msgid "Using Public Registries" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:371 msgid "" "While the most secure provenance is downloading from https://" "download.freebsd.org/releases[Official FreeBSD Releases], there are two " "public container registries managed by the FreeBSD Release and Cluster Admin " "teams. The images from both registries are identical, but provide a simpler " "and more container-friendly workflow." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:373 msgid "https://hub.docker.com/u/freebsd[Docker Hub]" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:374 msgid "https://github.com/orgs/freebsd/packages[GitHub Container Registry]" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:376 #, no-wrap msgid "Fetching Containers" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:379 msgid "Images can be fetched from a public registry using `+podman pull+`:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:389 #, no-wrap msgid "" "# podman pull ghcr.io/freebsd/freebsd-notoolchain:{rel-latest}\n" "Trying to pull ghcr.io/freebsd/freebsd-notoolchain:{rel-latest}...\n" "Getting image source signatures\n" "Copying blob 711cf0d3c0ef done |\n" "Copying config 086572f35c done |\n" "Writing manifest to image destination\n" "086572f35cc90b1a1d2b7904b63e8a849071b4ba89b15492f6da47a802372aa2\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:392 #, no-wrap msgid "Running a Container" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:397 msgid "" "Use `+podman run+` to start a container. The `+-it+` flags allocate an " "interactive terminal, and `+--rm+` removes the container when it exits. If " "no command is specified, the image's default entrypoint is used:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:402 #, no-wrap msgid "" "# podman run -it --rm ghcr.io/freebsd/freebsd-notoolchain:{rel-latest}\n" "# exit\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:405 msgid "A specific command can be given as well:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:410 #, no-wrap msgid "" "# podman run -it --rm ghcr.io/freebsd/freebsd-notoolchain:{rel-latest} uname -a\n" "FreeBSD c0038de70651 {rel-latest}-RELEASE FreeBSD {rel-latest}-RELEASE releng/{rel-latest}-n283562-96841ea08dcf GENERIC amd64\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:414 msgid "" "As the container image does not include the kernel, man:freebsd-version[1] " "shows different results for the running kernel versus the installed " "userland. In this example, a {rel-latest-previous}-RELEASE container runs " "on a {rel-latest}-RELEASE host:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:422 #, no-wrap msgid "" "# podman run -it --rm ghcr.io/freebsd/freebsd-notoolchain:{rel-latest-previous} /bin/sh\n" "# freebsd-version -ru\n" "{rel-latest}-RELEASE\n" "{rel-latest-previous}-RELEASE\n" "# exit\n" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:425 #, no-wrap msgid "Useful Variations and Tips" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:429 msgid "" "Almost all of the `+podman run ...+` parameters also apply to `+podman " "build+`. Refer to the man:podman-run[1] and man:podman-build[1] manual " "pages for details." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:431 msgid "" "Use the `+--rm+` flag to have ephemeral containers clean themselves up " "afterwards." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:433 msgid "Use `+podman images -a+` to show all downloaded images:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:439 #, no-wrap msgid "" "# podman images -a\n" "REPOSITORY TAG IMAGE ID CREATED SIZE\n" "ghcr.io/freebsd/freebsd-runtime {rel-latest} 90c493675429 2 weeks ago 34.1 MB\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:442 msgid "Use `+podman ps -a+` to see running containers:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:448 #, no-wrap msgid "" "# podman ps -a\n" "CONTAINER ID IMAGE COMMAND CREATED STATUS NAMES\n" "3123623bef9b ghcr.io/freebsd/freebsd-runtime:{rel-latest} /bin/sh 4 minutes ago Up 4 minutes admiring_brattain\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:451 #, no-wrap msgid "Environment Variables" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:454 msgid "" "Podman sets a number of default environment variables in each container:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:463 #, no-wrap msgid "" "# podman run -it --rm ghcr.io/freebsd/freebsd-notoolchain:{rel-latest} /usr/bin/env\n" "container=podman\n" "TERM=xterm\n" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\n" "HOME=/root\n" "HOSTNAME=60bae3343e6b\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:467 msgid "" "The `+HOSTNAME+` is set to the container ID by default. It can be " "overridden with `+--hostname+`, which is useful when the application inside " "the container needs a stable or meaningful hostname." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:469 msgid "Arbitrary environment variables can be passed in with `+--env+`:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:475 #, no-wrap msgid "" "# podman run --env FOO=BAR -it --rm ghcr.io/freebsd/freebsd-runtime:{rel-latest}\n" "# echo $FOO\n" "BAR\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:478 #, no-wrap msgid "Mounting Files and Volumes" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:482 msgid "" "Both files and volumes can be passed into containers using `+--volume+`. " "For example, the `+runtime+` image does not contain man:which[1]:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:488 #, no-wrap msgid "" "# podman run -it --rm ghcr.io/freebsd/freebsd-runtime:{rel-latest}\n" "# which\n" "/bin/sh: which: not found\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:491 msgid "It can be mounted into the container from the host:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:498 #, no-wrap msgid "" "# podman run -it --rm --volume /usr/bin/which:/usr/bin/which \\\n" " ghcr.io/freebsd/freebsd-runtime:{rel-latest}\n" "# which which\n" "/usr/bin/which\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:503 msgid "" "For a lean image such as `+freebsd-static+`, mount the existing man:pkg-" "static[8] from the host to bootstrap man:pkg[8] inside the container. " "Sharing the host's package cache via `+--volume /var/cache/pkg+` avoids re-" "downloading packages that have already been fetched, which is particularly " "useful when building multiple containers. The `+--no-hosts+` flag prevents " "mounting `+/etc/hosts+`, which would otherwise interfere with package " "upgrades." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/containers/_index.adoc:507 msgid "" "Sharing the package cache only works when the host and container run the " "same FreeBSD major version, as packages are version-specific." msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:522 #, no-wrap msgid "" "# podman run -it --rm \\\n" " --env ASSUME_ALWAYS_YES=true \\\n" " --no-hosts \\\n" " --volume /usr/local/sbin/pkg-static:/bin/pkg-static \\\n" " --volume /var/cache/pkg \\\n" " ghcr.io/freebsd/freebsd-static:{rel-latest}\n" "# pkg-static bootstrap -r FreeBSD\n" "Bootstrapping pkg from pkg+https://pkg.FreeBSD.org/FreeBSD:14:amd64/latest, please wait...\n" "Verifying signature with trusted certificate pkg.freebsd.org.2013102301... done\n" "[fd343e182fa5] Installing pkg-2.1.2...\n" "[fd343e182fa5] Extracting pkg-2.1.2: 100%\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:525 msgid "" "Files and directories from the host can also be mounted into containers:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:533 #, no-wrap msgid "" "# podman run -it --rm \\\n" " --volume /etc/fstab:/etc/fstab \\\n" " --volume /tmp:/var/tmp \\\n" " --volume /tmp \\\n" " ghcr.io/freebsd/freebsd-runtime:{rel-latest}\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:536 #, no-wrap msgid "Inspecting Image Contents" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:539 msgid "" "To list all files in any image, including minimal images with no shell or " "tools, export the container filesystem and list its contents:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:543 #, no-wrap msgid "# podman export $(podman create --rm ghcr.io/freebsd/freebsd-static:{rel-latest} /) | tar tf -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:547 msgid "" "The container images do not include man:pkg[8] itself, but man:pkg-static[8] " "can be mounted from the host to query the installed base system packages. " "Use `+pkg info -q+` to list package names, or `+pkg info -ql+` to show all " "files owned by packages:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:575 #, no-wrap msgid "" "# podman run --rm \\\n" " -v /usr/local/sbin/pkg-static:/pkg \\\n" " ghcr.io/freebsd/freebsd-runtime:{rel-latest} /pkg info -q\n" "FreeBSD-audit-lib-{rel-latest}\n" "FreeBSD-bzip2-lib-{rel-latest}\n" "FreeBSD-certctl-{rel-latest}\n" "FreeBSD-clibs-{rel-latest}\n" "FreeBSD-fetch-{rel-latest}\n" "FreeBSD-kerberos-lib-{rel-latest}\n" "FreeBSD-libarchive-{rel-latest}\n" "FreeBSD-libcasper-{rel-latest}\n" "FreeBSD-libexecinfo-{rel-latest}\n" "FreeBSD-libucl-{rel-latest}\n" "FreeBSD-mtree-{rel-latest}\n" "FreeBSD-ncurses-lib-{rel-latest}\n" "FreeBSD-openssl-{rel-latest}\n" "FreeBSD-openssl-lib-{rel-latest}\n" "FreeBSD-pam-lib-{rel-latest}\n" "FreeBSD-pkg-bootstrap-{rel-latest}\n" "FreeBSD-rc-{rel-latest}\n" "FreeBSD-runtime-{rel-latest}\n" "FreeBSD-xz-lib-{rel-latest}\n" "FreeBSD-zlib-{rel-latest}\n" "FreeBSD-zoneinfo-{rel-latest}\n" "FreeBSD-zstd-lib-{rel-latest}\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:578 msgid "" "When the host and container run different FreeBSD major versions, man:pkg[8] " "detects the ABI by inspecting `+/bin/sh+` inside the container, and will " "warn about the mismatch:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:589 #, no-wrap msgid "" "# podman run -it --rm \\\n" " --env ASSUME_ALWAYS_YES=true \\\n" " --no-hosts \\\n" " --volume /usr/local/sbin/pkg-static:/usr/sbin/pkg \\\n" " --volume /var/cache/pkg \\\n" " ghcr.io/freebsd/freebsd-runtime:14.4 /bin/sh\n" "# pkg bootstrap\n" "pkg: Warning: Major OS version upgrade detected. Running \"pkg bootstrap -f\" recommended\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:592 msgid "" "For images without `+/bin/sh+`, such as `+freebsd-dynamic+`, man:pkg-" "static[8] cannot detect the system ABI at all." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:594 #, no-wrap msgid "Networking and Name Resolution" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:597 msgid "" "By default, the Podman suite of tools will use man:mount_nullfs[8] to mount " "`+/etc/resolv.conf+` and a modified `+/etc/hosts+` from the jail host, as " "well as a `+.containerenv+` file in `+/var/run+`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:599 msgid "" "This hosts file will conflict with base system package upgrades, so it is " "advised to skip this during `+podman build+` runs, but leave it enabled " "during production deployment:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:604 #, no-wrap msgid "" "# podman run --dns 1.2.3.4 ...\n" "# podman build --no-hosts ...\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:608 msgid "" "The `+--dns+` flag specifies a custom DNS server instead of mounting `+/etc/" "resolv.conf+` from the host. The `+--no-hosts+` flag prevents mounting `+/" "etc/hosts+` from the host." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:610 #, no-wrap msgid "Building Custom Images" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:613 msgid "" "Custom images can be built directly from tarballs (for example those from " "man:poudriere[8], or official release tarballs), from existing tagged " "images, or bootstrapped from man:pkg[8]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:615 #, no-wrap msgid "Building from Tarballs" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:620 msgid "" "A custom image can be made from any FreeBSD root filesystem tarball using " "man:podman-import[1]. The tarball can be an official release `+base.txz+`, " "one produced by man:poudriere-image[8], or your own custom tarball. The " "final tagged image can be pushed to registries, modified, and used for " "further image creation." msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:633 #, no-wrap msgid "" "# podman import --os freebsd \\\n" " --arch amd64 \\\n" " --message 'Import FreeBSD {rel-latest}-RELEASE base.txz' \\\n" " https://download.freebsd.org/releases/amd64/{rel-latest}-RELEASE/base.txz\n" "Downloading from \"https://download.freebsd.org/releases/amd64/{rel-latest}-RELEASE/base.txz\"\n" "Getting image source signatures\n" "Copying blob 3768988b151c done |\n" "Copying config 332bec83a4 done |\n" "Writing manifest to image destination\n" "sha256:332bec83a428efa6c9f7d1f8b3fbd589c5613d938dca7da5125240c89f4f3dcd\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:635 #, no-wrap msgid "# podman image tag 332bec83a428 localhost/freebsd-base:{rel-latest}\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:639 #, no-wrap msgid "" "# podman image ls\n" "REPOSITORY TAG IMAGE ID CREATED SIZE\n" "localhost/freebsd-base {rel-latest} 332bec83a428 5 minutes ago 715 MB\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:642 #, no-wrap msgid "Building from Containerfiles" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:647 msgid "" "Images can be built using a `+Containerfile+`, similar to a Dockerfile. In " "most cases, the `+freebsd-notoolchain+` image is the most convenient base, " "as it includes nearly all standard system tools. For leaner containers, " "start from `+freebsd-static+`, `+freebsd-dynamic+`, or `+freebsd-runtime+` " "as appropriate, and add only what is needed:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:657 #, no-wrap msgid "" "# Containerfile\n" "FROM ghcr.io/freebsd/freebsd-notoolchain:{rel-latest}\n" "RUN env ASSUME_ALWAYS_YES=yes IGNORE_OS_VERSION=yes pkg bootstrap -r FreeBSD\n" "RUN pkg update\n" "RUN pkg upgrade -y\n" "RUN pkg clean -y\n" "ENTRYPOINT /bin/sh\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:660 msgid "Build the image with man:podman-build[1]:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:666 #, no-wrap msgid "" "# podman build --no-hosts --squash \\\n" " -t localhost/freebsd-base:{rel-latest} \\\n" " -f ./Containerfile\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:669 msgid "Further images can be layered on top:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:677 #, no-wrap msgid "" "# Containerfile.webserver\n" "FROM localhost/freebsd-base:{rel-latest}\n" "RUN pkg install -y lang/python3\n" "RUN pkg clean -y\n" "ENTRYPOINT /usr/local/bin/python3 -m http.server\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:684 #, no-wrap msgid "" "# podman build --no-hosts \\\n" " -t localhost/python-www:{rel-latest} \\\n" " -f ./Containerfile.webserver\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:688 msgid "" "Run the web server in the background with `+--detach+`, and use `+-p+` to " "map a host port to the container port. In this example, the container " "listens on its default port 8000, which is mapped to port 8888 on the host:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:692 #, no-wrap msgid "# c=$(podman run --detach --rm -p 8888:8000 localhost/python-www:{rel-latest})\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:696 msgid "" "The port mapping uses man:pf[4] redirect rules. These rules redirect " "traffic arriving over the network, so the mapped port must be accessed from " "another host, or via the host's network-facing IP address:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:704 #, no-wrap msgid "" "$ fetch -v http://172.16.2.10:8888/\n" "resolving server address: 172.16.2.10:8888\n" "requesting http://172.16.2.10:8888/\n" "remote size / mtime: 784 / 0\n" "fetch.out 784 B 3791 kBps 00s\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:707 msgid "" "To access the container directly from the host, use the container's own IP " "on its listening port:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:717 #, no-wrap msgid "" "# podman inspect -f '{{.NetworkSettings.IPAddress}}' $c\n" "10.88.0.91\n" "# fetch -v http://10.88.0.91:8000/\n" "resolving server address: 10.88.0.91:8000\n" "requesting http://10.88.0.91:8000/\n" "remote size / mtime: 784 / 0\n" "fetch.out 784 B 25 MBps 00s\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/containers/_index.adoc:724 msgid "" "Port mappings via `+-p+` are handled by man:pf[4] redirect rules and only " "apply to traffic arriving over the network. Traffic originating from the " "jail host itself to `+localhost+` or `+127.0.0.1+` will not be redirected. " "From the host, use the container's IP address directly instead." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:727 #, no-wrap msgid "Advanced Usage" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:730 #, no-wrap msgid "Daemonising Podman" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:733 msgid "FreeBSD's Podman implementation provides two man:rc[8] services:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:735 msgid "" "The `+podman+` service runs at boot and ensures that all containers marked " "with `+restart-policy=always+` are started." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:736 msgid "" "The `+podman_service+` service runs the https://docs.podman.io/en/latest/" "_static/api.html[Podman API service], providing a REST API and listening on " "`+/var/run/podman/podman.sock+` by default." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:738 msgid "Enable them as follows:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:746 #, no-wrap msgid "" "# sysrc podman_enable=YES\n" "# sysrc podman_service_enable=YES\n" "# sysrc podman_service_flags='--time 0'\n" "# service podman start\n" "# service podman_service start\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:749 msgid "" "Containers that should restart automatically after a host reboot must be run " "with the `+--restart=always+` option:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:753 #, no-wrap msgid "# podman run --detach --restart=always my-image\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:756 #, no-wrap msgid "Running Linux Containers" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:759 msgid "" "It is possible to run many Linux container images using FreeBSD's Linux " "emulation:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:770 #, no-wrap msgid "" "# service linux onestart\n" "# podman run --rm --os=linux docker.io/alpine cat /etc/os-release | head -1\n" "Trying to pull docker.io/library/alpine:latest...\n" "Getting image source signatures\n" "Copying blob 4abcf2066143 done |\n" "Copying config 05455a0888 done |\n" "Writing manifest to image destination\n" "NAME=\"Alpine Linux\"\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/containers/_index.adoc:775 msgid "" "Linux containers that depend on systemd, expect to be PID 1, or rely on " "Linux-specific kernel interfaces may not work correctly under FreeBSD's " "Linux emulation." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:778 #, no-wrap msgid "Running a Local Registry" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:783 msgid "" "A registry is a web server for storing and sharing OCI images. The https://" "freshports.org/sysutils/docker-registry[sysutils/docker-registry] port " "provides a simple registry suitable for local development or a small " "organisation. https://zotregistry.dev/[Zot Registry] is a more " "comprehensive modern alternative." msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:798 #, no-wrap msgid "" "# pkg install -r FreeBSD sysutils/docker-registry\n" "# zfs create zroot/var/db/registry\n" "# chown -R www:www /var/db/registry\n" "# sysrc docker_registry_enable=YES\n" "# sysrc docker_registry_user=www\n" "# sed -i '' -E -e 's,rootdirectory:.+,rootdirectory: /var/db/registry,' \\\n" " /usr/local/etc/docker-registry/config.yml\n" "# touch /usr/local/etc/docker-registry/htpasswd\n" "# chown -R root:www /usr/local/etc/docker-registry/config.yml \\\n" " /usr/local/etc/docker-registry/htpasswd\n" "# chmod 0640 /usr/local/etc/docker-registry/config.yml \\\n" " /usr/local/etc/docker-registry/htpasswd\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:801 msgid "" "A sample configuration for `+/usr/local/etc/docker-registry/config.yml+`:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:827 #, no-wrap msgid "" "version: 0.1\n" "log:\n" " fields:\n" " service: registry\n" "storage:\n" " cache:\n" " blobdescriptor: inmemory\n" " filesystem:\n" " rootdirectory: /var/db/registry\n" "http:\n" " addr: :5000\n" " secret: \n" " headers:\n" " X-Content-Type-Options: [nosniff]\n" "auth:\n" " htpasswd:\n" " realm: basic-realm\n" " path: /usr/local/etc/docker-registry/htpasswd\n" "health:\n" " storagedriver:\n" " enabled: true\n" " interval: 10s\n" " threshold: 3\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:830 msgid "Start the registry and verify it is running:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:835 #, no-wrap msgid "" "# service registry start\n" "# curl -u admin:passwd http://localhost:5000/v2/\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/containers/_index.adoc:840 msgid "" "It is recommended to serve the registry over TLS, behind a reverse proxy " "such as nginx or haproxy." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:843 #, no-wrap msgid "Synchronising Registries" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:847 msgid "" "It is possible to synchronise official FreeBSD images into a local registry " "using `+skopeo+`. The following example replicates all FreeBSD-related " "images from https://hub.docker.com/u/freebsd[Docker Hub] to a local registry:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:856 #, no-wrap msgid "" "# sync.yml\n" "docker.io:\n" " images:\n" " freebsd/freebsd-static: []\n" " freebsd/freebsd-dynamic: []\n" " freebsd/freebsd-runtime: []\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:865 #, no-wrap msgid "" "$ skopeo sync --src yaml --dest docker --all sync.yml cr.example.net/freebsd\n" "INFO[0000] Processing repo repo=freebsd/freebsd-static\n" "INFO[0000] Querying registry for image tags repo=freebsd/freebsd-static\n" "...\n" "INFO[0771] Synced 42 images from 3 sources\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:868 msgid "" "So long as the credentials in `+/root/.config/containers/auth.json+` are up " "to date, root access is not required to sync images." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:870 #, no-wrap msgid "Working with Container Registries" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:874 msgid "" "Registries generally require authentication for push operations, and " "optionally for pull. Credentials are saved in `+/root/.config/containers/" "auth.json+` by default after login:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:880 #, no-wrap msgid "" "# podman login ghcr.io -u username\n" "Password:\n" "Login Succeeded!\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:883 msgid "Images can then be pushed to a registry:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:892 #, no-wrap msgid "" "# podman push localhost/freebsd-runtime:{rel-latest} \\\n" " docker://ghcr.io/example/freebsd-runtime:{rel-latest}\n" "Getting image source signatures\n" "Copying blob bbacfdfbe140 done |\n" "Copying config 786f2592a8 done |\n" "Writing manifest to image destination\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:895 msgid "Public images can be pulled without authentication:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:899 #, no-wrap msgid "# podman pull ghcr.io/freebsd/freebsd-runtime:{rel-latest}\n" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:902 #, no-wrap msgid "Building Container Images from Sources" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:906 msgid "" "The FreeBSD release tooling provides an `+oci-release+` target to build the " "necessary images for `+podman load+` to use. It requires building world, " "kernel, and base system packages first, so this can take a while." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:908 msgid "The following example builds `+arm64+` images:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:919 #, no-wrap msgid "" "# cd /usr/src \\\n" " && make TARGET_ARCH=aarch64 TARGET=arm64 -s -j32 buildworld \\\n" " && make TARGET_ARCH=aarch64 TARGET=arm64 KERNCONF=GENERIC -s -j32 buildkernel \\\n" " && make TARGET_ARCH=aarch64 TARGET=arm64 KERNCONF=GENERIC -s -j32 packages \\\n" " && cd ./release \\\n" " && make TARGET_ARCH=aarch64 TARGET=arm64 -j32 -s clean \\\n" " && make KERNCONF=GENERIC TARGET_ARCH=aarch64 TARGET=arm64 WITH_OCIIMAGES=yes \\\n" " -s oci-release\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:922 msgid "And similarly for `+amd64+`:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:933 #, no-wrap msgid "" "# cd /usr/src \\\n" " && make TARGET_ARCH=amd64 TARGET=amd64 -s -j32 buildworld \\\n" " && make TARGET_ARCH=amd64 TARGET=amd64 KERNCONF=GENERIC -s -j32 buildkernel \\\n" " && make TARGET_ARCH=amd64 TARGET=amd64 KERNCONF=GENERIC -s -j32 packages \\\n" " && cd ./release \\\n" " && make TARGET_ARCH=amd64 TARGET=amd64 -s -j32 clean \\\n" " && make KERNCONF=GENERIC TARGET_ARCH=amd64 TARGET=amd64 \\\n" " WITH_OCIIMAGES=yes -s oci-release\n" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:936 #, no-wrap msgid "Cross-Architecture Testing" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:940 msgid "" "The `+emulators/qemu-user-static+` package allows testing container images " "built for other architectures. After installing the package, enable and " "start the service to register image activators for all emulated " "architectures:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:946 #, no-wrap msgid "" "# pkg install emulators/qemu-user-static\n" "# service qemu_user_static enable\n" "# service qemu_user_static start\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:949 msgid "" "Then run an `+arm64+` image on an `+amd64+` host by mounting the appropriate " "QEMU binary:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:956 #, no-wrap msgid "" "# podman run -it --rm --arch=arm64 \\\n" " -v /usr/local/bin/qemu-aarch64-static:/usr/local/bin/qemu-aarch64-static \\\n" " ghcr.io/freebsd/freebsd-runtime:14.snap uname -a\n" "FreeBSD 73d4049d10b2 14.2-RELEASE-p1 FreeBSD 14.2-RELEASE-p1 GENERIC arm64\n" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/containers/_index.adoc:959 #, no-wrap msgid "Troubleshooting" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:962 #, no-wrap msgid "Package Upgrades and Mounted Files" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:966 msgid "" "Podman mounts `+/etc/resolv.conf+` and `+/etc/hosts+` into containers using " "man:mount_nullfs[8]. These mounts can cause errors during man:pkg[8] " "operations with messages such as `+Cross-device link+`:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:970 #, no-wrap msgid "pkg: Fail to rename /etc/.pkgtemp.hosts.VeIDrHM0sKN5 -> /etc/hosts:Cross-device link\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:973 msgid "To avoid this, use `+--no-hosts+` and `+--dns+` flags:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:978 #, no-wrap msgid "" "# podman run --no-hosts --dns 1.1.1.1 -it --rm \\\n" " ghcr.io/freebsd/freebsd-runtime:{rel-latest} /bin/sh\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:981 #, no-wrap msgid "Checking Networking" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:985 msgid "" "Start with the firewall rules from `+/usr/local/etc/containers/" "pf.conf.sample+`. Test connectivity step by step from within a container:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:993 #, no-wrap msgid "" "# podman run --no-hosts --dns 1.1.1.1 \\\n" " --env ASSUME_ALWAYS_YES=1 \\\n" " -it --rm \\\n" " ghcr.io/freebsd/freebsd-runtime:{rel-latest} \\\n" " /bin/sh\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:999 #, no-wrap msgid "" "# route show 1.1.1.1\n" " route to: 1.1.1.1\n" "destination: default\n" " gateway: 10.88.0.1\n" " interface: eth0\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:1004 #, no-wrap msgid "" "# ping -c 3 10.88.0.1\n" "PING 10.88.0.1 (10.88.0.1): 56 data bytes\n" "64 bytes from 10.88.0.1: icmp_seq=0 ttl=64 time=0.083 ms\n" "...\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:1009 #, no-wrap msgid "" "# ping -c 3 1.1.1.1\n" "PING 1.1.1.1 (1.1.1.1): 56 data bytes\n" "64 bytes from 1.1.1.1: icmp_seq=0 ttl=60 time=0.920 ms\n" "...\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:1012 #, no-wrap msgid "" "# fetch -v http://1.1.1.1/\n" "...\n" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:1014 #, no-wrap msgid "# pkg -dd bootstrap -r FreeBSD\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:1020 msgid "" "If man:ping[8] fails, check the firewall rules for blocked ICMP. If " "man:fetch[1] fails, check the firewall rules for blocked TCP on ports 80 and " "443. If man:pkg[8] fails but ICMP and TCP work, this may be a fragmentation " "or MTU problem. Add `+set reassemble yes no-df+` to `+/etc/pf.conf+` and " "restart the firewall." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:1022 msgid "" "For debugging blocked packets, enable `+log+` on all block rules in `+/etc/" "pf.conf+` and use man:tcpdump[1] on the man:pflog[4] device:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:1027 #, no-wrap msgid "" "# service pflog onerestart\n" "# tcpdump -vvveni pflog0 icmp or net 10.88.0.0/16\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/containers/_index.adoc:1030 #, no-wrap msgid "MTU Consistency" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:1034 msgid "" "Ensure MTU values are consistent across the primary network interface, the " "container bridge, and the container itself. Mismatched MTU values can cause " "packet fragmentation and connectivity failures." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:1037 msgid "" "In the following example, `+vtnet0+` has MTU 9000, but the bridge and " "containers have MTU 1500. In general, align the internal layout to match " "the external network:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:1042 #, no-wrap msgid "" "# ifconfig vtnet0 mtu 9000\n" "# ifconfig cni-podman0 mtu 9000\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:1045 msgid "Inside the container:" msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/handbook/containers/_index.adoc:1049 #, no-wrap msgid "# ifconfig eth0 mtu 9000\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/containers/_index.adoc:1052 msgid "" "The bridges and epairs used by Podman are ephemeral and will need to be " "configured for each bridge creation and each container. In some cloud " "environments, adding `+set reassemble yes no-df+` to `+/etc/pf.conf+` may " "also be required." msgstr ""