From nobody Fri Oct 02 07:47:13 2026 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4hx18R1Ktsz6tpsG for ; Fri, 02 Oct 2026 07:47:19 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "YR2" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4hx18Q6XbWz4hPT for ; Fri, 02 Oct 2026 07:47:18 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1790927238; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=6+bq3OoEXSYoVO3DbPDu1axOPBrmcdVwn1vCn85MGN8=; b=h39yfcT+ZqaOEbpaVmrSJt0b+bWDx5geT8IFt7NgQwn1EMlvFoKQELQiOb3Nd/S+/OQbKr fc4ReAcQLCy6MGSxakuHkG4669+tpV2jT9C+89VCfCv02VBsrccebKMHzAJzWEl+do+UyP JKavm5vOpDkPnOkBOC0biYI9sTLVrzTgFzImkRQ4JhCawc2SgKo7g6F4cNp+PGcyKu/Iuw e4KBXyWXQRclv8NUdpjCDt6Y24QDoKJTRgB0tMrXAW1w45vg+SMPq4I2Et9QFlrqUC5kTk eSu53hSfBcfD3IeBXkfKTOg7dlCflqMxZUbJIswWROJD+h1/bJWnpwwzjMK6Fw== ARC-Seal: i=1; a=rsa-sha256; d=freebsd.org; s=dkim; cv=none; t=1790927238; b=UCEGvuvhV4I1nMycyMp+/v9WaK0DlrrUkabnqznSXwE1mp051TOgYuHsL2tZohSeYlm3v3 Na39FeRofC73YtZNYVIj2XmzF1irvbCzA0Ny0To97PTxySKOIGCDYZpHe0TiomaGq/SuW9 wwgK9px2RzpXMlBNUyuEkajzWlp6e0CSDEj9eRx3Or181M5iewp9y042M0gU/SFDOthXrp qdlLRpEN3HJk+/aSdgIs9Lfkm7UeBJ4oRDeza6Wm3bhfFbrObEoskYXTCbmPaOZecf8Wym NYWPDB41qogSj8C4z1qu2gRg/VstP6ryz9O3+ANtvUPyxlrfj1ji1rE8WP3YCA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1790927238; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=6+bq3OoEXSYoVO3DbPDu1axOPBrmcdVwn1vCn85MGN8=; b=T/OvSs4neavQcucWH/bTzW222D/g4EW5zMO9RKc8qTGqw2yXkA8BZOnommgS26Oip8Tqq0 jWGstMBZ9g6DRF7F4TkQlqCntwYcrL7ne+7PcaeEONg/RZioa1/g7lvPCOxhSI+X5Sw2a+ zaIGAiTX4EQngG13OcsRhUQbZHlYdDRH/HiOyT8O4aIhbTcUkgfPySLkRotCrz6LCSEaca 0cDel2bnTAgqhx1tSUB5Fh4p+uv+6lzU042KNCgdVWF/6ewCgjS5uaXCu4D1dMbOGYn28E 9he7J5j0tioKQw4bF3rieDqsXmgliPFamRZVz1gZqet0xvKUevIKnmp+wl387A== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4hx18Q5Gp3z17cc for ; Fri, 02 Oct 2026 07:47:18 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 32d60 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Fri, 02 Oct 2026 07:47:13 +0000 To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Dave Cottlehuber Subject: git: df4e42b61d - main - containers: Extend and improve the firewall section List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-all@FreeBSD.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: dch X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: df4e42b61dbb2606b9442cefd8fa4072bf48791a Auto-Submitted: auto-generated Date: Fri, 02 Oct 2026 07:47:13 +0000 Message-Id: <6abf6181.32d60.5dc19592@gitrepo.freebsd.org> The branch main has been updated by dch: URL: https://cgit.FreeBSD.org/doc/commit/?id=df4e42b61dbb2606b9442cefd8fa4072bf48791a commit df4e42b61dbb2606b9442cefd8fa4072bf48791a Author: Dave Cottlehuber AuthorDate: 2026-10-02 07:46:57 +0000 Commit: Dave Cottlehuber CommitDate: 2026-10-02 07:46:57 +0000 containers: Extend and improve the firewall section --- .../en/books/handbook/containers/_index.adoc | 85 ++++++++++++++++++---- 1 file changed, 71 insertions(+), 14 deletions(-) diff --git a/documentation/content/en/books/handbook/containers/_index.adoc b/documentation/content/en/books/handbook/containers/_index.adoc index b00fd470f2..7b8476abb4 100644 --- a/documentation/content/en/books/handbook/containers/_index.adoc +++ b/documentation/content/en/books/handbook/containers/_index.adoc @@ -234,16 +234,13 @@ The File Descriptor filesystem is required: # mount -t fdescfs fdesc /dev/fd ---- -Podman uses FreeBSD's packet filter to forward container ports to the host network: +This should be added to `+/etc/fstab+` to persist across reboots: [source,shell] ---- -# test -c /dev/pf || kldload pf -# sysctl net.pf.filter_local=1 +fdescfs /dev/fd fdescfs rw 0 0 ---- -Amend `+/etc/sysctl.conf+` and `+/etc/fstab+` as appropriate, to make these changes permanent. - [[containers-installing]] == Installing Podman @@ -254,22 +251,59 @@ Only the `+sysutils/podman-suite+` meta-package is required, but if the addition # pkg install -r FreeBSD -y podman-suite emulators/qemu-user-static ---- -Integrate changes from `+/usr/local/etc/containers/pf.conf.sample+` into `+/etc/pf.conf+`, setting egress macros appropriately, then restart the firewall: +[[containers-networking]] +== Configuring Networking + +Container networking uses Network Address Translation (NAT) to enable VNET jails to access the host's network. This is done via man:pf[4], so the packet filter kernel module must be loaded. + +Integrate changes from `+/usr/local/etc/containers/pf.conf.sample+` into `+/etc/pf.conf+`, setting the egress interface macros to match your default network interface. + +[source] +---- +# Change these to your interface(s) with the default route +v4egress_if = "vtnet0" +v6egress_if = "vtnet0" + +nat on $v4egress_if inet from to any -> ($v4egress_if) +nat on $v6egress_if inet6 from to !ff00::/8 -> ($v6egress_if) + +rdr-anchor "cni-rdr/*" +nat-anchor "cni-rdr/*" +table +---- + +The `+rdr-anchor+` and `+nat-anchor "cni-rdr/*"+` lines implement port redirections as anchors nested under `+cni-rdr+`. The `+nat-anchor "cni-rdr/*"+` line in particular is required to redirect connections from the container host to services running inside a container, including when the destination is `+localhost+` (`+127.0.0.1+` or `+::1+`). + +Enable and start the firewall: + +[source,shell] +---- +# service pf enable +# service pf start +---- + +Redirecting connections from the container host itself to services running inside a container also requires enabling support for local redirections: [source,shell] ---- -# service pf restart +# sysctl net.pf.filter_local=1 +---- + +Amend `+/etc/sysctl.conf+` to make this change permanent: + +[source] +---- +net.pf.filter_local=1 ---- -The packages install a number of template configuration files, none of which need to be edited immediately. -Review and amend these as needed: +[[containers-config-files]] +== Additional Configuration Files + +The packages install a number of template configuration files, none of which need to be edited immediately. Review and amend these as needed: [source,shell] ---- -# pkg list buildah podman conmon \ - ocijail containers-common \ - containernetworking-plugins \ - | grep /etc/ +# pkg list | grep /etc/containers/ /usr/local/etc/containers/containers.conf.sample /usr/local/etc/containers/policy.json.sample /usr/local/etc/containers/registries.conf.sample @@ -277,6 +311,29 @@ Review and amend these as needed: /usr/local/etc/containers/pf.conf.sample ---- +[[containers-first]] +== Running Your First Container + +The various flags are described in man:podman-run[1]. This invocation creates a new container, attaching an interactive terminal, and will remove the container on exit: + +[source,shell]] +---- +# podman run -it --rm ghcr.io/freebsd/freebsd-notoolchain:{rel-latest} +# top -b +last pid: 24414; load averages: 0.47, 0.51, 0.53; battery: 23% up 0+18:48:46 23:30:12 +2 processes: 1 running, 1 sleeping +CPU: 6.9% user, 0.0% nice, 2.2% system, 0.7% interrupt, 90.2% idle +Mem: 2619M Active, 6587M Inact, 1813M Laundry, 4552M Wired, 56K Buf, 334M Free +ARC: 2526M Total, 802M MFU, 1219M MRU, 3586K Anon, 29M Header, 467M Other + 1625M Compressed, 4234M Uncompressed, 2.61:1 Ratio +Swap: 10G Total, 219M Used, 10G Free, 2% Inuse + + PID USERNAME THR PRI NICE SIZE RES STATE C TIME WCPU COMMAND +17963 root 1 1 0 14M 3120K wait 1 0:00 0.44% sh +24414 root 1 3 0 15M 2992K CPU0 0 0:00 0.00% top +# exit +---- + [[containers-terminal-tour]] == Importing and Running Containers @@ -290,7 +347,7 @@ With the necessary tools and firewall rules in place, the officially published i [[containers-importing]] === Importing FreeBSD OCI Images -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. +As above, while it is most convenient to pull images directly from a public container registry, 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. [source,shell,subs="attributes"] ----