snix-podman-rootless

Manage rootless Podman pods with pasta networking and static IP addresses.

Description

Provides the podctl script to create and manage rootless Podman pods with dedicated static IPs. Each pod gets a persistent network alias on the host interface, ensuring connectivity from both the host and external networks across reboots.

The pod system user (uid/gid 392) runs Podman in rootless mode. The script runs as root and delegates to pod only for Podman operations.

Dependencies

• podman
• iproute2
• passt (provides pasta)

Usage

# Create a pod with IP and ports
podctl net add mypod 10.0.0.10 80 443

# Remove pod and IP
podctl net del mypod

# List all pods (JSON)
podctl list

# List a single pod (JSON)
podctl list mypod

# Enable a rootless container service
podctl enable mypod

# Enable a root container service
podctl enable --root mypod

# Disable a container service
podctl disable mypod
podctl disable --root mypod

# Edit a container service (copies template, opens editor)
podctl edit mypod
podctl edit --root mypod

# Migrate existing pods to /etc/podctl.conf
podctl migrate

# Any podman command as the pod user
podctl ps -a
podctl images

How it works

podctl net add <name> <ip> [ports...]

1. Appends an entry to /etc/podctl.conf
2. Creates the Podman pod with pasta networking (--address, --gateway, --netmask, --map-gw)

Ports support individual values and ranges:

podctl net add mypod 10.0.0.10 80 443 8080-8090

podctl net del <name>

1. Removes the Podman pod
2. Removes the entry from /etc/podctl.conf

podctl list

Reads /etc/podctl.conf and queries Podman for pod status. JSON output:

[
  {
    "name": "mypod",
    "ip": "10.0.0.10",
    "ports": ["80", "443"],
    "status": "running"
  }
]

podctl migrate

Interactive migration from a manually configured system. For each existing pod:

1. Shows remaining available secondary IPs on the host interface
2. Asks to assign an IP to the pod
3. Asks for ports
4. Re-adds the IP with the correct interface label
5. Writes the entry to /etc/podctl.conf

If any IPs remain unassigned after all pods are processed, offers to remove them from the interface.

Enables the podctl service at boot automatically.

IP assignment

IP aliases are managed by the podctl service, not by podctl directly. On boot the service reads /etc/podctl.conf and assigns each IP to the host interface:

ip addr add <ip>/<nm> dev <iface> label <iface>:<name>

On stop, all aliases are removed.

Both OpenRC and systemd are supported:

# OpenRC
rc-service podctl start

# systemd
systemctl start podctl

Configuration

Pod metadata is stored in /etc/podctl.conf:

# name:ip:iface:nm:ports
db:10.0.0.250:eth0:24:80 443
vw:10.0.0.41:eth0:24:
manga.it:10.0.0.81:eth0:24:80 443

Container services

Each container runs inside a pod and is managed by a dedicated service. podctl detects the init system automatically.

Without --root, uses the rootless template (runs as the pod user). With --root, uses the root template (runs as root).

# Enable rootless container service
podctl enable mypod

# Enable root container service
podctl enable --root mypod

# Disable
podctl disable mypod
podctl disable --root mypod

# Edit: copies template, opens $EDITOR
podctl edit mypod
podctl edit --root mypod

OpenRC

Two templates are installed:

Template	Path
Rootless	/etc/rc.service/init.d/rootless-pod
Root	/etc/rc.service/init.d/pod

• enable → symlinks template to /etc/init.d/mypod
• disable → removes symlink
• edit → copies template to /etc/init.d/mypod, opens $EDITOR

rc-update add mypod default

systemd

Two template units are installed:

Template	Unit
Rootless	/usr/lib/systemd/system/rootless-pod@.service
Root	/usr/lib/systemd/system/pod@.service

• enable → systemctl enable rootless-pod@mypod or systemctl enable pod@mypod
• disable → disables the unit
• edit → copies template to /etc/systemd/system/, opens $EDITOR, runs daemon-reload

systemctl start rootless-pod@mypod
systemctl start pod@mypod

Each container requires an update script in /pods/<name>/update that runs the podman run command for that container.

Installed files

File	Description
/usr/sbin/podctl	Main management script
/etc/podctl.conf	Pod metadata
/etc/init.d/podctl	OpenRC IP alias service
/etc/rc.service/init.d/rootless-pod	Rootless container service template (OpenRC)
/etc/rc.service/init.d/pod	Root container service template (OpenRC)
/usr/lib/systemd/system/podctl.service	systemd IP alias service
/usr/lib/systemd/system/rootless-pod@.service	systemd rootless container template unit
/usr/lib/systemd/system/pod@.service	systemd root container template unit

System user

The package creates the pod user if it does not exist:

pod:x:392:392::/var/pod:/usr/sbin/nologin

Path	Description
/var/pod	Home directory for the pod user
/var/lib/containers/rootless	Rootless Podman data directory