---
title: Chapter 18. OCI Containers
part: Part III. System Administration
prev: books/handbook/security
next: books/handbook/mac
description: OCI Containers provide an industry-standard way to describe, distribute, and run container-based workloads
tags: ["containers", "oci"]
showBookMenu: true
weight: 21
params:
  path: "/books/handbook/containers/"
---

[[containers]]
= OCI Containers
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumoffset: 18
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/handbook/containers/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

[[containers-synopsis]]
== Synopsis

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.

For FreeBSD users familiar with jails, there is a loose analogy:

* FreeBSD's `+base.txz+` tarball is an example of a container image.
* the `+jail.conf+` file describes the desired container properties, or `+Containerfile+`.
* use the `+jail ..+` command to run a container, given a filesystem path, with the `+podman+` suite of tools.

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.

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.

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.

[source,display,subs="verbatim,attributes"]
----
CHECKSUM.SHA256
CHECKSUM.SHA512
FreeBSD-{rel-latest}-RELEASE-amd64-container-image-static.txz
FreeBSD-{rel-latest}-RELEASE-amd64-container-image-dynamic.txz
FreeBSD-{rel-latest}-RELEASE-amd64-container-image-runtime.txz
FreeBSD-{rel-latest}-RELEASE-amd64-container-image-notoolchain.txz
FreeBSD-{rel-latest}-RELEASE-amd64-container-image-toolchain.txz
----

[[containers-naming-tagging]]
== Container Image Naming and Tagging

=== Introduction

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.

[[containers-image-types]]
=== Available Image Types

Five types of FreeBSD container images are available, for `+amd64+` and `+aarch64+` architectures.

[[containers-freebsd-static]]
==== `+freebsd-static+`

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.

* public TLS certificates
* minimal password file
* minimal termcap
* timezone database

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.

[[containers-freebsd-dynamic]]
==== `+freebsd-dynamic+`

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.

[[containers-freebsd-runtime]]
==== `+freebsd-runtime+`

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.

[[containers-freebsd-notoolchain]]
==== `+freebsd-notoolchain+`

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.

[[containers-freebsd-toolchain]]
==== `+freebsd-toolchain+`

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.

[[containers-tag-structure]]
=== Image Tag Structure

[[containers-immutable-tags]]
==== Immutable Tags

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.

* `+major.minor+` (e.g., `+14.4+`): Points to a specific FreeBSD RELEASE version
* `+major.minor.pX+` (e.g., `+14.4p1+`): Points to a specific patch level of a RELEASE
* `+major.snapYYYYMMDDHHMMSS+` (e.g., `+16.snap20260325035941+`): a snapshot build with timestamp

[[containers-mutable-tags]]
==== Mutable Tags

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.

* `+major+` (e.g., `+15+`) will always be the latest support RELEASE version along the 15.x stable ABI
* `+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.

=== When to Use Each Tag Type

==== For Production

Use immutable tags to ensure your environment stays consistent:

* `+freebsd-runtime:15.0+` - pinned to FreeBSD 15.0-RELEASE

When security patches are released, you must explicitly rebuild or update with a new image tag.

==== For Continuous Integration and Development

Use mutable tags to automatically get the latest updates:

* `+freebsd-runtime:15+` - always the latest official RELEASE in the 15.x series

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.

* `+freebsd-runtime:14.snap+` - always the latest build from 14-STABLE branch
* `+freebsd-runtime:15.snap+` - always the latest build from 15-STABLE branch
* `+freebsd-runtime:16.snap+` - always the latest build from 16-CURRENT branch
