No description
  • Rust 69.9%
  • Shell 15.6%
  • Python 14.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
jochen 77b8aa2300
All checks were successful
/ gitleaks (push) Successful in 10s
ci / rust (push) Successful in 8m3s
ci / deb (push) Successful in 5m14s
ci / e2e (push) Successful in 22s
Merge pull request 'Version nur in Cargo.toml; CI prüft Lock, Binary, Paket und Release-Tag' (#23) from version-check into master
Reviewed-on: #23
Reviewed-by: jochen <jochen@bocc.de>
2026-11-19 11:55:17 +00:00
.forgejo/workflows ci: Versionsprüfung in rust- und deb-Job; README: Release 2026-11-19 11:15:52 +00:00
packaging Version nur in Cargo.toml; CI prüft Lock, Binary, Paket und Release-Tag 2026-11-19 11:15:26 +00:00
src Plugin meldet CARGO_PKG_VERSION statt fest verdrahtetem "0.1.0"; README: Release 2026-11-19 11:17:32 +00:00
tests e2e: Netns per nsenter statt ip -n (sysfs-Mount im Podman-Runner verboten) 2026-11-19 09:05:53 +00:00
tools Migrationsskript: TLS für ssl:-Ziele wie im Plugin (#4) 2026-11-19 07:56:42 +00:00
.gitignore CI: Debian-Paket für Ubuntu 26.04 (resolute) 2026-11-14 07:12:32 +00:00
Cargo.lock Add Cargo.lock (#13) 2026-11-12 09:04:18 +01:00
Cargo.toml Port-Ownership absichern (#1, #2) 2026-11-11 19:12:20 +00:00
README.md README: Release (Version nur in Cargo.toml, check-version.sh) 2026-11-19 11:18:25 +00:00

netavark-ovs

Netzwerk-Plugin für netavark (den Netzwerk-Stack von Podman), das Container über Open vSwitch an OVN Logical Switches anbindet. Damit hängen Podman-Container im selben SDN wie VMs oder andere Workloads, hostübergreifend über die OVN-Overlay-Tunnel.

Pro Container und Netz legt das Plugin

  • auf dem Host ein veth-Paar an, hängt das Host-Ende an die OVN-Integrationsbridge (br-int) und schiebt das andere Ende in den Container,
  • in der OVN-Northbound-DB einen Logical Switch Port (LSP) mit Adressen und Port-Security an,
  • und verknüpft beides über external_ids:iface-id, sodass ovn-controller den Port bindet.

Voraussetzungen

  • Rootful Podman mit netavark-Backend (podman info --format '{{.Host.NetworkBackend}}' → netavark).

  • Auf dem Host laufen Open vSwitch und ovn-controller, d. h. der Host ist als OVN-Chassis eingerichtet.

  • Im Open_vSwitch-Table des Hosts gesetzt:

    Key Bedeutung
    external_ids:ovn-nb Verbindung zur Northbound-DB, z. B. ssl:10.0.0.1:6641 oder unix:/run/ovn/ovnnb_db.sock (Pflicht); mehrere Ziele kommagetrennt (Cluster)
    external_ids:ovn-nb-private-key, ovn-nb-certificate, ovn-nb-ca-cert TLS-Dateien für ssl: (optional, siehe TLS)
    external_ids:ovn-bridge Integrationsbridge, Standard br-int
    external_ids:system-id Chassis-Name; wird als Eigentümer an den Ports vermerkt
    ovs-vsctl set open_vswitch . external_ids:ovn-nb=ssl:10.0.0.1:6641
    
  • Werkzeuge: ip (iproute2), nsenter (util-linux), ovs-vsctl (openvswitch-switch), ovsdb-client (openvswitch-common), ovn-nbctl (ovn-common).

TLS zur Northbound-DB

Bei ssl:-Zielen meldet sich das Plugin mit einem Client-Zertifikat an. Die drei Dateien (Schlüssel, Zertifikat, CA-Zertifikat der NB-DB) kommen jeweils aus

  1. external_ids:ovn-nb-private-key / ovn-nb-certificate / ovn-nb-ca-cert im Open_vSwitch-Table, sonst
  2. der SSL-Konfiguration des lokalen OVS (ovs-vsctl set-ssl), die auch ovn-controller für die Southbound-Verbindung nutzt.
# eigenes Zertifikat nur für die NB-Verbindung
ovs-vsctl set open_vswitch . \
  external_ids:ovn-nb=ssl:10.0.0.1:6641 \
  external_ids:ovn-nb-private-key=/etc/ovn/podman-nb-privkey.pem \
  external_ids:ovn-nb-certificate=/etc/ovn/podman-nb-cert.pem \
  external_ids:ovn-nb-ca-cert=/etc/ovn/nb-cacert.pem

Fehlt eine Datei oder ist sie nicht lesbar, bricht das Plugin mit einer Meldung ab, die die fehlende Einstellung nennt. Bei tcp: gibt podman network create eine Warnung aus. Das Migrationsskript löst die Dateien genauso auf (zusätzlich --private-key/--certificate/--ca-cert).

Auf der NB-Seite z. B. ovn-nbctl set-connection pssl:6641 und ovn-nbctl set-ssl <key> <cert> <ca-cert>, wobei das CA-Zertifikat nur die Clients (Hosts) signiert, die schreiben dürfen.

Installation

Paket (Ubuntu 26.04 „resolute“)

Die CI baut bei jedem Commit auf master ein Paket und lädt es in die Forgejo-Debian-Registry:

echo "deb https://git.bocc.de/api/packages/jochen/debian resolute main" \
  > /etc/apt/sources.list.d/forgejo-jochen.list
# Signing-Key der Registry einrichten, falls noch nicht geschehen
apt update && apt install netavark-ovs

Das Paket installiert das Plugin nach /usr/libexec/netavark/ovs. Das Verzeichnis steht in der Standardliste netavark_plugin_dirs (containers.conf), es ist also keine weitere Konfiguration nötig.

Manuell

apt install protobuf-compiler            # vom build.rs des netavark-Crates benötigt
cargo build --release --locked
install -m 0755 target/release/ovs /usr/libexec/netavark/ovs

Kontrolle: podman info --format '{{.Plugins.Network}}' listet ovs.

Benutzung

# Netz anlegen -- legt den Logical Switch an, falls es ihn noch nicht gibt
podman network create --driver ovs --subnet 10.10.0.0/24 --gateway 10.10.0.1 net1

# Container starten
podman run -d --name web --network net1 --ip 10.10.0.5 nginx

Optionen am Netz (podman network create --opt key=value)

Option Bedeutung
ovn_switch=NAME Name des Logical Switch; Standard ist der Netzname. Mehrere Hosts mit gleichem ovn_switch landen im selben L2-Segment.
ovn_keep_ports=true Ports beim Stoppen des Containers nicht löschen (Adressen bleiben über Neustarts erhalten).
ovn_external_ports=allow Container dürfen Ports nutzen, die nicht von Podman angelegt wurden (siehe unten).
port_security=strict|mac-only|off Port-Security für Ports, die Podman gehören (siehe unten). Standard strict.

Statische Routen (--route) werden im Container gesetzt.

Optionen pro Container-Anbindung

Das Plugin wertet zusätzlich zwei Optionen aus netavarks network_options.options (pro Container und Netz) aus:

Option Bedeutung
lsp_name=NAME Fester Name des Logical Switch Ports statt des Standardnamens. Nützlich für eine stabile Identität (MAC/IP) über Neuanlagen des Containers hinweg.
lsp_cleanup=keep|delete Überschreibt für diesen Container die Lösch-Policy des Netzes.

Ab Podman 5.4 reicht --network unbekannte Schlüssel ungeprüft an netavark-Plugins durch:

podman run -d --network net1:lsp_name=web-01 nginx

Adressen

  1. Trägt der Logical Switch Port schon Adressen (vorprovisioniert, oder von einem früheren Start behalten), sind diese maßgeblich und werden nicht überschrieben. Steht dort nur dynamic, werden die von ovn-northd vergebenen Adressen übernommen (Einschränkungen bei <mac> dynamic siehe #7).
  2. Sonst kommen MAC und IPs von Podman (--mac-address, --ip); ohne MAC wird eine lokal administrierte erzeugt. Das Plugin schreibt sie dann als addresses und port_security in den LSP.
  3. Die Präfixlänge (und das Gateway) stammt aus dem netavark-Subnetz; fehlt das, aus other_config:subnet (und optional other_config:gateway) des Logical Switch; sonst wird die Adresse als /32 bzw. /128 ohne Gateway gesetzt (mit Warnung).

Port-Security

Port Verhalten
Von Podman angelegt oder übernommen port_security wird bei jedem Start gesetzt, je nach Netzoption port_security: strict (Standard) = MAC und alle IPs; ohne bekannte IP startet der Container nicht, weil sonst jede Quell-IP durchginge. mac-only = nur die MAC. off = keine Port-Security (z. B. Router, VRRP/keepalived-VIPs). Das gilt auch, wenn die Adressen schon am Port stehen (behaltene Ports, dynamic).
Außerhalb von Podman provisioniert (z. B. Netbox, freigegeben über podman-allowed=true bzw. ovn_external_ports=allow) port_security wird nie verändert, der Provisionierer ist maßgeblich – auch für zusätzliche Adressen wie VIPs. Ist das Feld leer, gibt das Plugin nur eine Warnung aus.

Beispiel für einen in Netbox bzw. per Hand vorbereiteten Port mit VIP:

ovn-nbctl lsp-add net1 web-01 \
  -- lsp-set-addresses web-01 "02:00:00:00:00:77 10.10.0.77" \
  -- lsp-set-port-security web-01 "02:00:00:00:00:77 10.10.0.77 10.10.0.100" \
  -- set logical_switch_port web-01 external_ids:podman-allowed=true
podman run -d --network net1:lsp_name=web-01 nginx

Ports und Eigentum

  • Name: <logical switch>-<erste 12 Zeichen der Container-ID>, z. B. net1-3f2a9c1b7d4e – eindeutig im ganzen OVN-Cluster, auch wenn auf mehreren Hosts gleichnamige Container laufen. Mit lsp_name frei wählbar.
  • Eigentum steht in den external_ids des Ports: podman-owned=true, podman-container-id, podman-chassis. Anlegen und Markieren passiert in einer NB-Transaktion.
  • Vorhandene Ports werden nur verwendet, wenn sie auf dem richtigen Switch liegen, ein normaler VIF-Port sind (keine router-/localnet-/…-Ports) und nicht von einem anderen laufenden Container belegt sind. Bei explizitem lsp_name wird ein Port übernommen, dessen bisheriger Container nicht mehr läuft.
  • Fremde Ports (nicht von Podman angelegt) nur mit Freigabe: ovn-nbctl set logical_switch_port P external_ids:podman-allowed=true oder --opt ovn_external_ports=allow am Netz. Solche Ports löscht das Plugin nie.
  • Beim Stoppen wird der Port gelöscht, wenn er diesem Container gehört und weder ovn_keep_ports=true noch lsp_cleanup=keep gesetzt ist.
  • Übernehmen und Löschen eines Ports passieren als Compare-and-Swap (ovsdb-client transact mit wait): Hat sich der Port seit dem Lesen geändert – etwa weil ein anderer Container ihn gerade übernommen hat –, schlägt die Übernahme mit Fehlermeldung fehl bzw. das Löschen unterbleibt.
  • Auf dem Host trägt das OVS-Interface external_ids:podman-attachment=<container-id>/<netz-id>. Der Host-Interface-Name veo<hash> ist ein 32-Bit-Hash; eine (sehr unwahrscheinliche) Namenskollision mit einer anderen laufenden Anbindung wird erkannt, der fremde Port bleibt unangetastet und der Start schlägt mit Fehlermeldung fehl.

Umstieg vom alten Namensschema

Ältere Versionen nannten Ports <switch>-<containername>. Behaltene Ports lassen sich auf jedem Host umbenennen (Probelauf ohne --apply):

python3 /usr/share/netavark-ovs/migrate-lsp-names.py           # zeigt, was passieren würde
python3 /usr/share/netavark-ovs/migrate-lsp-names.py --apply

Fehlerverhalten

  • Schlägt ein Containerstart fehl (z. B. ungültige Route), wird alles zurückgebaut, was dieser Start angelegt hat: OVS-Port, veth und – nur wenn neu angelegt – der Logical Switch Port.
  • Reste früherer Fehlstarts derselben Anbindung werden beim nächsten Start entfernt.
  • Teardown ist „best effort“: erst lokal (OVS-Port, veth), dann OVN; Fehler werden gesammelt gemeldet. Ist die NB-DB beim Stoppen nicht erreichbar, bleibt der LSP stehen, der OVS-Port wird trotzdem entfernt.
  • Alle ovs-vsctl/ovn-nbctl-Aufrufe haben ein Timeout von 30 s.
  • Das Plugin ruft seine Werkzeuge mit festem PATH auf (/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/sbin:/usr/local/bin).

Sicherheit

  • Das Plugin läuft als root und braucht Schreibzugriff auf die Northbound-DB – damit lässt sich die gesamte logische Topologie ändern. Die DB-Verbindung daher auf vertrauenswürdige Hosts beschränken.
  • Verbindung zur NB-DB über ssl: mit Client-Zertifikaten (siehe TLS). tcp: ist unverschlüsselt und unauthentifiziert: Wer den Port erreicht, kann die komplette logische Topologie lesen und ändern. Die Northbound-DB kennt kein RBAC wie die Southbound-DB; der Schutz liegt allein darin, wer ein von der NB-CA signiertes Zertifikat hat und wer den Port erreicht (Firewall).
  • Port-Security: siehe oben. Für Ports, die das Plugin anlegt, ist sie standardmäßig streng (MAC und IPs).

Bekannte Einschränkungen

Siehe offene Issues, u. a.: MTU-Option wird ignoriert (#8, bei Geneve wichtig), route_type blackhole/unreachable/prohibit (#6), <mac> dynamic-Adressen (#7), Default-Route nur für die erste Adresse (#9), MAC-Erzeugung (#5).

Entwicklung

cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked

Integrationstests gegen eine echte, frische Northbound-DB (ovn-central installiert):

mkdir -p /tmp/nb && ovsdb-tool create /tmp/nb/nb.db /usr/share/ovn/ovn-nb.ovsschema
ovsdb-server --detach --pidfile=/tmp/nb/pid --unixctl=/tmp/nb/ctl --remote=punix:/tmp/nb/nb.sock /tmp/nb/nb.db
OVN_NB_TEST_DB=unix:/tmp/nb/nb.sock cargo test --locked
OVN_NB_TEST_DB=unix:/tmp/nb/nb.sock python3 -m unittest tools/test_migrate_lsp_names.py

End-to-End-Test (root, braucht Network-Namespaces): startet in einem Temp-Verzeichnis ovsdb-server/ovs-vswitchd mit Userspace-Datapath (kein Kernelmodul) und eine NB-DB und ruft das Plugin-Binary wie netavark auf – Rollback bei Fehlstart, Reste alter Fehlstarts, behaltene Ports, Teardown bei nicht erreichbarer DB, Namenskollision, Port-Security eigener und extern provisionierter Ports, NB-Verbindung über ssl: mit eigener Test-CA:

cargo build --locked && sudo bash tests/e2e.sh target/debug/ovs

CI (.forgejo/workflows/): rust (fmt, clippy, Tests, Integrationstests, cargo audit, Release-Build) → deb (Paket in ubuntu:26.04, Installationstest, Upload bei master) → e2e (Paket im privilegierten ubuntu:26.04-Container auf dem podman-Runner); dazu gitleaks über die komplette Historie.

Release: Die Version steht nur in Cargo.toml (das Plugin meldet sie über CARGO_PKG_VERSION an netavark, das Paket heißt <Version>+git<N>.<sha>-1). packaging/check-version.sh prüft in der CI, dass Cargo.lock, das gebaute Binary (ovs info) und das Paket dazu passen, und bei einem Tag-Push, dass der Tag v<Version> ist:

bash packaging/check-version.sh --tag v0.2.0 --bin target/release/ovs