From 425d87fdae1970ebb5bc8de2823e94f9c7408d98 Mon Sep 17 00:00:00 2001
From: Nir Soffer <nirsof@gmail.com>
Date: Mon, 31 Aug 2026 19:01:07 +0300
Subject: [PATCH 1/2] Use mDNS hostname as launchd label and CLI connection
 name

Starting and using a VM required two different names:

    launchctl start local.docker
    ssh root@docker.local

The launchd Label was reverse-DNS (`local.$VM_NAME`) while the VM's
mDNS name is `$VM_NAME.local`. launchd.plist(5) only recommends naming
the plist file `<Label>.plist`; the Label itself is an independent
identifier. Keep the plist at `~/Library/LaunchAgents/local.$VM_NAME.plist`
and set the Label to the mDNS hostname.

Use the same name for the Docker context and podman system connection,
so start, SSH, and the container CLI all share one identifier:

    launchctl start docker.local
    ssh root@docker.local
    docker context use docker.local

In the podman benchmarks, iterate the full names instead of stitching
prefixes and suffixes in the loop body. Prefix CONTAINERS_MACHINE_PROVIDER
on the commands that need it instead of exporting it into the shell.
---
 docs/docker.md  |  26 ++++++-------
 docs/launchd.md |  12 +++---
 docs/podman.md  | 101 ++++++++++++++++++++++++------------------------
 3 files changed, 69 insertions(+), 70 deletions(-)

diff --git a/docs/docker.md b/docs/docker.md
index 47715f3..6520dcc 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -127,7 +127,7 @@ cat > ~/Library/LaunchAgents/local.$VM_NAME.plist << EOF
 <plist version="1.0">
 <dict>
     <key>Label</key>
-    <string>local.$VM_NAME</string>
+    <string>$VM_NAME.local</string>
     <key>ProgramArguments</key>
     <array>
         <string>$(brew --prefix vmnet-helper)/libexec/vmnet-run</string>
@@ -166,7 +166,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.$VM_NAME.plist
 ## Start the Docker VM
 
 ```console
-launchctl start local.docker
+launchctl start docker.local
 ```
 
 Wait for the VM to boot:
@@ -195,29 +195,29 @@ EOF
 Restart the VM:
 
 ```console
-launchctl stop local.docker
-until launchctl print gui/$(id -u)/local.docker | grep -q 'state = not running'; do sleep 1; done
-launchctl start local.docker
+launchctl stop docker.local
+until launchctl print gui/$(id -u)/docker.local | grep -q 'state = not running'; do sleep 1; done
+launchctl start docker.local
 until nc -z docker.local 22; do true; done
 ```
 
 ## Add a Docker context
 
 ```console
-docker context create vmnet \
+docker context create docker.local \
     --docker "host=ssh://root@docker.local"
 ```
 
 Verify the connection:
 
 ```console
-docker --context vmnet version
+docker --context docker.local version
 ```
 
 ## Make it your default
 
 ```console
-docker context use vmnet
+docker context use docker.local
 ```
 
 > [!TIP]
@@ -300,14 +300,14 @@ docker rm -f speedtest
 Start the VM:
 
 ```console
-launchctl start local.docker
+launchctl start docker.local
 until nc -z docker.local 22; do true; done
 ```
 
 Stop the VM:
 
 ```console
-launchctl stop local.docker
+launchctl stop docker.local
 ```
 
 ## Cleanup
@@ -315,9 +315,9 @@ launchctl stop local.docker
 To remove the VM:
 
 ```console
-docker context rm vmnet
-launchctl stop local.docker
-launchctl bootout gui/$(id -u)/local.docker
+docker context rm docker.local
+launchctl stop docker.local
+launchctl bootout gui/$(id -u)/docker.local
 rm ~/Library/LaunchAgents/local.docker.plist
 rm -r ~/vms/docker
 ssh-keygen -R docker.local
diff --git a/docs/launchd.md b/docs/launchd.md
index b35ae82..ca11444 100644
--- a/docs/launchd.md
+++ b/docs/launchd.md
@@ -160,7 +160,7 @@ cat > ~/Library/LaunchAgents/local.$VM_NAME.plist << EOF
 <plist version="1.0">
 <dict>
     <key>Label</key>
-    <string>local.$VM_NAME</string>
+    <string>$VM_NAME.local</string>
     <key>ProgramArguments</key>
     <array>
         <string>$(brew --prefix vmnet-helper)/libexec/vmnet-run</string>
@@ -215,19 +215,19 @@ available options.
 Start the VM:
 
 ```console
-launchctl start local.$VM_NAME
+launchctl start $VM_NAME.local
 ```
 
 Stop the VM (cleanly terminates vmnet-helper and vfkit):
 
 ```console
-launchctl stop local.$VM_NAME
+launchctl stop $VM_NAME.local
 ```
 
 ### Checking status
 
 ```console
-launchctl print gui/$(id -u)/local.$VM_NAME | grep "^\tstate"
+launchctl print gui/$(id -u)/$VM_NAME.local | grep "^\tstate"
 ```
 
 When the VM is running:
@@ -285,8 +285,8 @@ ssh my-vm.local
 > This deletes all VM data including the disk image.
 
 ```console
-launchctl stop local.$VM_NAME
-launchctl bootout gui/$(id -u)/local.$VM_NAME
+launchctl stop $VM_NAME.local
+launchctl bootout gui/$(id -u)/$VM_NAME.local
 rm ~/Library/LaunchAgents/local.$VM_NAME.plist
 rm -r ~/vms/$VM_NAME
 ```
diff --git a/docs/podman.md b/docs/podman.md
index a9c8c3d..3091424 100644
--- a/docs/podman.md
+++ b/docs/podman.md
@@ -133,7 +133,7 @@ cat > ~/Library/LaunchAgents/local.$VM_NAME.plist << EOF
 <plist version="1.0">
 <dict>
     <key>Label</key>
-    <string>local.$VM_NAME</string>
+    <string>$VM_NAME.local</string>
     <key>ProgramArguments</key>
     <array>
         <!-- On macOS 15, use /opt/vmnet-helper/bin/vmnet-run -->
@@ -171,7 +171,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.$VM_NAME.plist
 ### Start the podman VM
 
 ```console
-launchctl start local.podman-vfkit
+launchctl start podman-vfkit.local
 ```
 
 Wait for the VM to boot:
@@ -188,16 +188,16 @@ Update the VM and restart:
 
 ```console
 ssh root@podman-vfkit.local dnf update -y
-launchctl stop local.podman-vfkit
-until launchctl print gui/$(id -u)/local.podman-vfkit | grep -q 'state = not running'; do sleep 1; done
-launchctl start local.podman-vfkit
+launchctl stop podman-vfkit.local
+until launchctl print gui/$(id -u)/podman-vfkit.local | grep -q 'state = not running'; do sleep 1; done
+launchctl start podman-vfkit.local
 until nc -z podman-vfkit.local 22; do true; done
 ```
 
 ### Add a system connection
 
 ```console
-podman system connection add vmnet-vfkit \
+podman system connection add podman-vfkit.local \
     --identity ~/.ssh/id_ed25519 \
     ssh://root@podman-vfkit.local/run/podman/podman.sock
 ```
@@ -205,7 +205,7 @@ podman system connection add vmnet-vfkit \
 Verify the connection:
 
 ```console
-podman -c vmnet-vfkit version
+podman -c podman-vfkit.local version
 ```
 
 ### Cleanup
@@ -213,9 +213,9 @@ podman -c vmnet-vfkit version
 To remove the VM after you are done testing:
 
 ```console
-podman system connection remove vmnet-vfkit
-launchctl stop local.podman-vfkit
-launchctl bootout gui/$(id -u)/local.podman-vfkit
+podman system connection remove podman-vfkit.local
+launchctl stop podman-vfkit.local
+launchctl bootout gui/$(id -u)/podman-vfkit.local
 rm ~/Library/LaunchAgents/local.podman-vfkit.plist
 rm -r ~/vms/podman-vfkit
 ssh-keygen -R podman-vfkit.local
@@ -306,7 +306,7 @@ cat > ~/Library/LaunchAgents/local.$VM_NAME.plist << EOF
 <plist version="1.0">
 <dict>
     <key>Label</key>
-    <string>local.$VM_NAME</string>
+    <string>$VM_NAME.local</string>
     <key>ProgramArguments</key>
     <array>
         <string>$(brew --prefix vmnet-helper)/libexec/vmnet-run</string>
@@ -345,7 +345,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.$VM_NAME.plist
 ### Start the podman VM
 
 ```console
-launchctl start local.podman-krunkit
+launchctl start podman-krunkit.local
 ```
 
 Wait for the VM to boot:
@@ -362,16 +362,16 @@ Update the VM and restart:
 
 ```console
 ssh root@podman-krunkit.local dnf update -y
-launchctl stop local.podman-krunkit
-until launchctl print gui/$(id -u)/local.podman-krunkit | grep -q 'state = not running'; do sleep 1; done
-launchctl start local.podman-krunkit
+launchctl stop podman-krunkit.local
+until launchctl print gui/$(id -u)/podman-krunkit.local | grep -q 'state = not running'; do sleep 1; done
+launchctl start podman-krunkit.local
 until nc -z podman-krunkit.local 22; do true; done
 ```
 
 ### Add a system connection
 
 ```console
-podman system connection add vmnet-krunkit \
+podman system connection add podman-krunkit.local \
     --identity ~/.ssh/id_ed25519 \
     ssh://root@podman-krunkit.local/run/podman/podman.sock
 ```
@@ -379,7 +379,7 @@ podman system connection add vmnet-krunkit \
 Verify the connection:
 
 ```console
-podman -c vmnet-krunkit version
+podman -c podman-krunkit.local version
 ```
 
 ### Cleanup
@@ -387,9 +387,9 @@ podman -c vmnet-krunkit version
 To remove the VM after you are done testing:
 
 ```console
-podman system connection remove vmnet-krunkit
-launchctl stop local.podman-krunkit
-launchctl bootout gui/$(id -u)/local.podman-krunkit
+podman system connection remove podman-krunkit.local
+launchctl stop podman-krunkit.local
+launchctl bootout gui/$(id -u)/podman-krunkit.local
 rm ~/Library/LaunchAgents/local.podman-krunkit.plist
 rm -r ~/vms/podman-krunkit
 ssh-keygen -R podman-krunkit.local
@@ -408,8 +408,8 @@ mkdir -p out
 Create a machine for each provider:
 
 ```console
-for provider in applehv libkrun; do
-    CONTAINERS_MACHINE_PROVIDER=$provider podman machine init --rootful podman-$provider
+for machine in podman-applehv podman-libkrun; do
+    CONTAINERS_MACHINE_PROVIDER=${machine#podman-} podman machine init --rootful $machine
 done
 ```
 
@@ -417,16 +417,15 @@ We test rootful podman with port forwarding. Traffic goes through the
 gvproxy userspace network stack.
 
 ```console
-for provider in applehv libkrun; do
-    export CONTAINERS_MACHINE_PROVIDER=$provider
-    podman machine start podman-$provider
+for machine in podman-applehv podman-libkrun; do
+    CONTAINERS_MACHINE_PROVIDER=${machine#podman-} podman machine start $machine
 
-    podman -c podman-$provider-root run -d --name iperf3 -p 5201:5201 docker.io/networkstatic/iperf3 -s
-    iperf3 -c localhost --json --time 30 > out/podman-$provider-tx.json
-    iperf3 -c localhost --json --time 30 --reverse > out/podman-$provider-rx.json
-    podman -c podman-$provider-root rm -f iperf3
+    podman -c $machine-root run -d --name iperf3 -p 5201:5201 docker.io/networkstatic/iperf3 -s
+    iperf3 -c localhost --json --time 30 > out/$machine-root-tx.json
+    iperf3 -c localhost --json --time 30 --reverse > out/$machine-root-rx.json
+    podman -c $machine-root rm -f iperf3
 
-    podman machine stop podman-$provider
+    CONTAINERS_MACHINE_PROVIDER=${machine#podman-} podman machine stop $machine
 done
 ```
 
@@ -436,17 +435,17 @@ We use rootful podman with port forwarding, implemented by the kernel using
 nftables.
 
 ```console
-for vm in vfkit krunkit; do
-    launchctl start local.podman-$vm
-    until nc -z podman-$vm.local 22; do true; done
+for vm in podman-vfkit.local podman-krunkit.local; do
+    launchctl start $vm
+    until nc -z $vm 22; do true; done
 
-    podman -c vmnet-$vm run -d --name iperf3 -p 5201:5201 docker.io/networkstatic/iperf3 -s
-    iperf3 -c podman-$vm.local --json --time 30 > out/vmnet-$vm-port-forwarding-tx.json
-    iperf3 -c podman-$vm.local --json --time 30 --reverse > out/vmnet-$vm-port-forwarding-rx.json
-    podman -c vmnet-$vm rm -f iperf3
+    podman -c $vm run -d --name iperf3 -p 5201:5201 docker.io/networkstatic/iperf3 -s
+    iperf3 -c $vm --json --time 30 > out/$vm-port-forwarding-tx.json
+    iperf3 -c $vm --json --time 30 --reverse > out/$vm-port-forwarding-rx.json
+    podman -c $vm rm -f iperf3
 
-    launchctl stop local.podman-$vm
-    until launchctl print gui/$(id -u)/local.podman-$vm | grep -q 'state = not running'; do sleep 1; done
+    launchctl stop $vm
+    until launchctl print gui/$(id -u)/$vm | grep -q 'state = not running'; do sleep 1; done
 done
 ```
 
@@ -456,17 +455,17 @@ The container uses the host network directly, avoiding the port forwarding cost.
 If your service can bind to any port, this is the fastest option.
 
 ```console
-for vm in vfkit krunkit; do
-    launchctl start local.podman-$vm
-    until nc -z podman-$vm.local 22; do true; done
+for vm in podman-vfkit.local podman-krunkit.local; do
+    launchctl start $vm
+    until nc -z $vm 22; do true; done
 
-    podman -c vmnet-$vm run -d --name iperf3 --network host docker.io/networkstatic/iperf3 -s
-    iperf3 -c podman-$vm.local --json --time 30 > out/vmnet-$vm-host-network-tx.json
-    iperf3 -c podman-$vm.local --json --time 30 --reverse > out/vmnet-$vm-host-network-rx.json
-    podman -c vmnet-$vm rm -f iperf3
+    podman -c $vm run -d --name iperf3 --network host docker.io/networkstatic/iperf3 -s
+    iperf3 -c $vm --json --time 30 > out/$vm-host-network-tx.json
+    iperf3 -c $vm --json --time 30 --reverse > out/$vm-host-network-rx.json
+    podman -c $vm rm -f iperf3
 
-    launchctl stop local.podman-$vm
-    until launchctl print gui/$(id -u)/local.podman-$vm | grep -q 'state = not running'; do sleep 1; done
+    launchctl stop $vm
+    until launchctl print gui/$(id -u)/$vm | grep -q 'state = not running'; do sleep 1; done
 done
 ```
 
@@ -489,7 +488,7 @@ but almost none on RX, since nftables only rewrites incoming packets.
 > vmnet VM for everyday container use.
 
 ```console
-podman system connection default vmnet-krunkit
+podman system connection default podman-krunkit.local
 ```
 
 ## Managing the VM
@@ -497,13 +496,13 @@ podman system connection default vmnet-krunkit
 Start the VM:
 
 ```console
-launchctl start local.podman-krunkit
+launchctl start podman-krunkit.local
 ```
 
 Stop the VM:
 
 ```console
-launchctl stop local.podman-krunkit
+launchctl stop podman-krunkit.local
 ```
 
 [xkcd]: https://xkcd.com/353/

From fa0a8fa158c2b15a2a8168769c98df8323a05931 Mon Sep 17 00:00:00 2001
From: Nir Soffer <nirsof@gmail.com>
Date: Mon, 31 Aug 2026 20:06:51 +0300
Subject: [PATCH 2/2] docs: Allow SSH to the podman socket on Fedora 44

After `dnf update`, `podman -c` fails with:

    Error: unable to connect to Podman socket: Get "http://d/v6.1.0/libpod/_ping":
    ssh: rejected: connect failed (open failed)

Fedora selinux-policy 44.6 dropped the permissive type for
`sshd_session_t`, so SSH stream-local forwarding cannot write
`/run/podman/podman.sock`. Show the failure and install a local
module over SSH that allows only this access. The module is stored
in the guest policy store, so it survives reboot. It is not in
cloud-init, so it can be inspected and retried while debugging.
---
 docs/podman.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 102 insertions(+), 2 deletions(-)

diff --git a/docs/podman.md b/docs/podman.md
index 3091424..df75de4 100644
--- a/docs/podman.md
+++ b/docs/podman.md
@@ -202,7 +202,57 @@ podman system connection add podman-vfkit.local \
     ssh://root@podman-vfkit.local/run/podman/podman.sock
 ```
 
-Verify the connection:
+### Fixing SELinux
+
+Check the connection:
+
+```console
+podman -c podman-vfkit.local version
+```
+
+Example output:
+
+```
+Client:        Podman Engine
+Version:       6.1.0
+API Version:   6.1.0
+Go Version:    go1.26.5
+Built:         Wed Aug 12 20:04:26 2026
+Build Origin:  brew
+OS/Arch:       darwin/arm64
+Cannot connect to Podman. Please verify your connection to the Linux system
+using `podman system connection list`, or try `podman machine init` and
+`podman machine start` to manage a new Linux VM
+Error: unable to connect to Podman socket: Get "http://d/v6.1.0/libpod/_ping":
+ssh: rejected: connect failed (open failed)
+```
+
+SELinux is blocking SSH from the podman socket. Confirm:
+
+```console
+ssh root@podman-vfkit.local bash -ls << 'EOF'
+ausearch -if /var/log/audit/audit.log -m avc -c sshd-session
+EOF
+```
+
+Example output:
+
+```
+----
+time->Mon Aug 31 16:39:39 2026
+type=AVC msg=audit(1788194379.948:128): avc:  denied  { write } for  pid=873 comm="sshd-session" name="podman.sock" dev="tmpfs" ino=1473 scontext=system_u:system_r:sshd_session_t:s0-s0:c0.c1023 tcontext=system_u:object_r:var_run_t:s0 tclass=sock_file permissive=0
+```
+
+Allow the access:
+
+```console
+ssh root@podman-vfkit.local 'cat > /root/sshd-podman-sock.cil && semodule -i /root/sshd-podman-sock.cil' << 'EOF'
+(allow sshd_session_t var_run_t (sock_file (write)))
+(allow sshd_session_t container_runtime_t (unix_stream_socket (connectto)))
+EOF
+```
+
+Check the connection again:
 
 ```console
 podman -c podman-vfkit.local version
@@ -376,7 +426,57 @@ podman system connection add podman-krunkit.local \
     ssh://root@podman-krunkit.local/run/podman/podman.sock
 ```
 
-Verify the connection:
+### Fixing SELinux
+
+Check the connection:
+
+```console
+podman -c podman-krunkit.local version
+```
+
+Example output:
+
+```
+Client:        Podman Engine
+Version:       6.1.0
+API Version:   6.1.0
+Go Version:    go1.26.5
+Built:         Wed Aug 12 20:04:26 2026
+Build Origin:  brew
+OS/Arch:       darwin/arm64
+Cannot connect to Podman. Please verify your connection to the Linux system
+using `podman system connection list`, or try `podman machine init` and
+`podman machine start` to manage a new Linux VM
+Error: unable to connect to Podman socket: Get "http://d/v6.1.0/libpod/_ping":
+ssh: rejected: connect failed (open failed)
+```
+
+SELinux is blocking SSH from the podman socket. Confirm:
+
+```console
+ssh root@podman-krunkit.local bash -ls << 'EOF'
+ausearch -if /var/log/audit/audit.log -m avc -c sshd-session
+EOF
+```
+
+Example output:
+
+```
+----
+time->Mon Aug 31 16:39:39 2026
+type=AVC msg=audit(1788194379.948:128): avc:  denied  { write } for  pid=873 comm="sshd-session" name="podman.sock" dev="tmpfs" ino=1473 scontext=system_u:system_r:sshd_session_t:s0-s0:c0.c1023 tcontext=system_u:object_r:var_run_t:s0 tclass=sock_file permissive=0
+```
+
+Allow the access:
+
+```console
+ssh root@podman-krunkit.local 'cat > /root/sshd-podman-sock.cil && semodule -i /root/sshd-podman-sock.cil' << 'EOF'
+(allow sshd_session_t var_run_t (sock_file (write)))
+(allow sshd_session_t container_runtime_t (unix_stream_socket (connectto)))
+EOF
+```
+
+Check the connection again:
 
 ```console
 podman -c podman-krunkit.local version