@startuml

'Actors
actor Customer
actor Agent as "Agent (public)"
actor Ticketing as "Ticketing (public)"
actor Accounting as "Accounting (private)"
actor NETSetup as "NETSetup (private)"
actor Supplier as "Supplier (Alltron)"
actor Provider as "Provider (Dropbox)"
actor Computer
actor SWVendor as "Software Vendor (Microsoft)"
actor HWVendor as "Hardware Vendor (HP)"

'Contact
Customer -> Agent: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/050%20Kontaktaufnahme/Kontaktaufnahme%20V1.1.adoc callAgent() -> new order]]
Agent -> Ticketing: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/050%20Kontaktaufnahme/Ticketverwaltung%20in%20Freshdesk.adoc createNETSetupTicket(order) -> new ticket]]
Ticketing -> Customer: notifyCustomer(ticket)

'Delta
Agent -> Customer: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/100%20Offerte/Offertprozess.adoc#ist-soll-analyse requestCurrentMode(ticket)]] -> ensureConfig(ticket.customer.currentMode)[[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/Templates/TemplateCompany.adoc Template Company]] [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup.Tests/TestInfrastructure/OfflineCompany.cs Example Code]]
Customer -> Agent: responseCurrentMode(ticket) -> updateConfig(updatedCurrentMode)
Agent -> Customer: requestFutureMode(updatedCurrentMode.config)
Customer -> Agent: responseFutureMode(updatedCurrentMode.config) -> futureMode.config

'Quote
Agent -> Accounting: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/100%20Offerte/Offertprozess.adoc#offerterstellung createQuote(updatedCurrentMode.config, futureMode.config) -> new quote]]
Accounting -> Agent: returnQuote(quote)
Agent -> Customer: sendQuote(quote)
Customer -> Agent: responseQuote(quote)

'Config
Agent -> Supplier: [[https://github.com/osisa/NETSetup/blob/feature/proxmoxvms/docs/NETSetup/230%20Beschaffung/Beschaffung.adoc createOrder(quote) -> new order]]
Supplier -> Agent: return order.Success
Agent -> NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup.Tests/Customers/TranslateCompanyToConfig.cs createConfigs(ticket, futureMode.config)]] -> new config[]
note over Agent, NETSetup: someConfig[] = { {HASTAG}ticket.json, ... }
NETSetup -> Provider: [[https://www.dropbox.com/home/NETSetup/BOOT/Config save config() ]]
Provider -> NETSetup: return save.Success
NETSetup -> Agent: return save.Success

newpage Old Prerequisite Steps
Supplier -> Agent: return order.HardwareHashes
Agent -> NETSetup: TODO: updateConfigs(ticket, hardwareHashes)
NETSetup -> Provider: TODO: updateConfigs(ticket, hardwareHashes)
Provider -> NETSetup: return update.Success
NETSetup -> Agent: return update.Success
Supplier -> Customer: [[https://github.com/osisa/NETSetup/blob/develop/docs/NETSetup/300%20Auslieferung/Auslieferung.adoc deliverOrder(setup)]]
Agent -> NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/input/NETSetupInstallUSB.adoc#NS-INSTALL-USB-CREATE-STICK Create NETSetup USB Stick]]
NETSetup -> Agent: NETSetup ready USB Stick

'Installation
loop For every computer
    Agent -> Computer: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/input/NETSetupInstall.adoc#NS-INSTALL-USB-USE-STICK plugIn(Power, USB Stick, Display, Keyboard)]]
    Agent -> Computer: turnOn()
    Agent -> Computer: hold(F9 or other key to get into Boot Menu)
    Agent -> Computer: select(USB Stick)

newpage NETSetup Setup Process - Boot Phase 1: USB Boot into WinPE

    == PHASE 1: UEFI Firmware + WinPE (runs from USB stick) ==
    note over Computer: UEFI firmware is running.\n**Proxmox installs require TWO USB sticks PRE-FLASHED WITH RUFUS (each >= 16 GB):**\n  USB #1 (NETSetup/WinPE, Rufus: Partitionsschema GPT, Zielsystem UEFI, NTFS):\n    Partition 1: FAT32 ESP — Windows Boot Manager + WinPE boot files\n    Partition 2: NTFS (label=DATA) — WinPE boot.wim, NETSetup\n  USB #2 (Proxmox installer, Rufus: DD image mode from proxmox.iso):\n    Unmodified Proxmox hybrid ISO layout (ESP + iso9660).\n    NETSetup does NOT touch USB #2 — it is booted as-is by the agent\n    after WinPE finishes writing the answer.toml to USB #1.\n**Agent boots USB #1 first; after WinPE prep + reboot, agent boots USB #2.**
    Computer -> Computer: UEFI firmware loads Windows Boot Manager from USB ESP (Secure Boot OK)
    alt Can boot NTFS Partition
        Computer -> Computer: Boots WinPE from NTFS Partition on USB
    else Lacks NTFS Driver
        Computer -> Computer: Boots FAT32 NTFS Driver from USB
        Computer -> Computer: Boots WinPE from NTFS Partition on USB
    end
    note over Computer: WinPE is now running from USB RAM disk.\nProcess: startnet.cmd -> autoexecute.ps1 -> NETSetup.exe
    Computer -> Computer: WinPE runs startnet.cmd
    Computer -> Computer: startnet.cmd searches every drive for autoexecute.ps1
    Computer -> Computer: cd to drive and run autoexecute.ps1
    Computer -> NETSetup: autoexecute.ps1 runs [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/CLI/Commands/InstallCommand.cs NETSetup.exe install]]
    note over NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/CLI/Commands/InstallCommand.cs InstallCommand.cs]]\nhost = NETSetup.GetSystemHost()\nhost.OperatingSystem, host.ExitIfNotElevated()\nconfig = ConfigMethods.GetConfig(host, services, ticket, hostname)\nBranches on host.IsOnWinPE() -> [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/2-WinPE/MainWinPE.cs MainWinPE.InstallOperatingSystem(cli, config, host)]]
    NETSetup -> Computer: host = GetSystemHost() — ISystemHost with Hardware, Logger, OperatingSystem
    NETSetup -> Computer: logs NETSetup Version, host.OperatingSystem
    NETSetup -> Computer: host.ExitIfNotElevated()
    NETSetup -> Computer: config = ConfigMethods.GetConfig(host, services, ticket, hostname)
    opt ConfigMethods.GetConfig()
        NETSetup -> Computer: host.Hardware.SerialNumber
        NETSetup -> Computer: online = CheckOnline(timeout 10s)
        alt online
            NETSetup -> Computer: check for online map file
            note over Agent, NETSetup: foreach machine in config a map file. Nomenclature: SerialNumber#Ticket.json
            NETSetup -> Computer: download map file
            NETSetup -> Computer: check for single matching map file
        end
        NETSetup -> Computer: if no map file found online -> check local map files as fallback (covers USB stick with embedded map file)
        NETSetup -> Computer: if no disks or not online -> try to install drivers
        NETSetup -> Computer: if nothing is found, but there are configs locally -> UI select which
    end

    NETSetup -> Computer: computer = config.IdentifyHost(host).CastTo<Computer>()

    alt operatingSystem is Windows (target)

newpage NETSetup Setup Process - Windows Install Path

        == PHASE 1 continued: WinPE prepares Windows installation (DISM /Apply-Image) ==
        note over NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/2-WinPE/MainWinPE.cs MainWinPE]] Windows branch\nsetup.exe replaced with DISM /Apply-Image (setup.exe fails on Win11 25H2).
        NETSetup -> Computer: unattended = [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/2-WinPE/S4WindowsUnattended.cs GetDismUnattendedFileSubPath(host, config, computer)]]
        note over NETSetup: **Image resolution BEFORE wiping install disk:**\nbootRoot = Path.GetFullPath("/") — boot medium root (startnet.cmd cd'd here).\nif <bootRoot>\\NETSetup\\Images\\<OS>\\ exists → prebuilt offline ISO path, no download.\nelse if !isOnline → ExitFailure.\nelse → mark imagesNetsetup = W:\\NETSetup (download after partitioning).\nThe broken pre-clear copy to Z:\\ was removed — Z: lives on the install disk and\ngets wiped by Clear() a few lines below, so anything staged there would be lost.
        NETSetup -> Computer: installationDisk.Clear(GPT) + AddPartitions(S: ESP 1000 MB, W: remaining)
        opt image was NOT prebuilt on boot medium
            NETSetup -> Computer: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/2-WinPE/S2Images.cs S2Images.EnsureImageElseExit(services, host, computer, isOnline, W:\\NETSetup)]]\nDownloads <OS>.7z from Dropbox + sha256 sidecar, extracts to W:\\NETSetup\\Images\\<OS>\\.
        end
        NETSetup -> Computer: wimPath = imagesNetsetup\\Images\\<OS>\\sources\\install.wim (verified with FileExists)
        NETSetup -> Computer: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/2-WinPE/DismCommand.cs DismCommand.ApplyImage(wimPath, imageName, W:)]] — 60 min timeout
        NETSetup -> Computer: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/2-WinPE/BcdbootCommand.cs bcdboot W:\\Windows /s S: /f UEFI]] — bcdboot from applied image, not WinPE's
        NETSetup -> Computer: Copy unattend.xml → W:\\Windows\\Panther\\unattend.xml
        NETSetup -> Computer: Copy NETSetup folder → W:\\NETSetup (excludes Images, Logs)
        NETSetup -> Computer: Reboot()

        == PHASE 2: Windows Setup (runs from target disk) ==
        note over Computer: Windows installer is running from target disk.\nNo USB needed anymore. WinPE is gone.
        Computer -> Computer: UEFI boots Windows Setup from installationDisk
        Computer -> Computer: Windows auto setup via unattend.xml
        Computer -> Computer: Unattend adds scheduled task: run NETSetup on first login
        Computer -> Computer: Reboot()

        == PHASE 3: Windows + NETSetup (runs from target disk) ==
        note over Computer: Full Windows is running.\nScheduled task launches NETSetup.exe install.\nInstallCommand detects host.IsOnWindows() && host.HasNETSetup()\n-> [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/3-NETSetupWindows/Stage3Windows.cs Stage3Windows.InstallNETSetupWindows()]]
        Computer -> Computer: Boots Windows from installationDisk
        Computer -> NETSetup: Scheduled Task runs NETSetup.exe install
        NETSetup -> Computer: computer = config.IdentifyHost(host).CastTo<Computer>()
        NETSetup -> Computer: CheckOnline(), EnsureOnlineIfNeededAskForWifi()
        NETSetup -> Computer: PowerSettings: Disable screen timeout and sleep (powercfg)
        NETSetup -> Computer: InstallChocolatey() (needed for HP updates)
        NETSetup -> Computer: TryGetDrivers() from remote source + TryInstallDrivers()
        opt computer is on Proxmox
            NETSetup -> Computer: Install VirtIO drivers via pnputil + disable WU driver search
            NETSetup -> Computer: Install QEMU Guest Agent
        end
        opt computer is HP (host.IsOnHP())
            NETSetup -> Computer: HPUpdateHelper.UpdateHPMachine() — install HP Support Assistant via choco, run silent driver/firmware/BIOS update -> Reboot
        end
        alt computer is WindowsServer
            NETSetup -> Computer: SetIPv4Configuration(staticIP)
            NETSetup -> Computer: InstallADForest() -> Reboot
            NETSetup -> Computer: ConfigureDNSServer()
            NETSetup -> Computer: InstallDHCPServer() -> Reboot
            NETSetup -> Computer: DisableDHCPServer()
            NETSetup -> Computer: Enable Remote Desktop
            NETSetup -> Computer: WinFirewall configuration
            NETSetup -> Computer: Enable Wake-on-LAN
            NETSetup -> Computer: Set Wallpaper
            NETSetup -> Computer: net start netlogon
            NETSetup -> Computer: dcdiag /test:dns + dcdiag
            NETSetup -> Computer: Create AD Users + Groups
            NETSetup -> Computer: Deactivate Default Administrator
            NETSetup -> Computer: Finished DC Setup -> Reboot
            NETSetup -> Computer: RunUpdate (choco upgrade, software install, Windows Update) -> Reboot
        else computer is WindowsComputer (Client)
            NETSetup -> Computer: Enable FullDomainDNSRegistration
            NETSetup -> Computer: Set all networks to Private
            NETSetup -> Computer: Enable Remote Desktop
            NETSetup -> Computer: WinFirewall configuration
            NETSetup -> Computer: Enable Wake-on-LAN
            NETSetup -> Computer: DomainJoin(config.Domain) -> Reboot
            NETSetup -> Computer: Set Wallpaper
            NETSetup -> Computer: gpupdate /force
            NETSetup -> Computer: RunUpdate (choco upgrade, software install, Windows Update) -> Reboot
        end

    else operatingSystem is Linux (target)

newpage NETSetup Setup Process - Linux/Proxmox: WinPE prepares USB

        == PHASE 1 continued: WinPE prepares USB stick for Linux boot ==
        note over NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/2-WinPE/MainWinPE.cs MainWinPE]] Linux branch.\nStill running in WinPE from USB RAM disk.\n**Target disk is NOT touched. Everything stays on USB #1.**

        alt operatingSystem is Proxmox

            note over NETSetup: **New architecture (single-USB prep):**\nNETSetup does NOT touch USB #2 at all.\nUSB #2 is a plain Rufus-flashed Proxmox installer stick that the agent\nbrought with them. NETSetup only modifies USB #1 by adding a small FAT32\nSYSTEM partition that holds the generated answer.toml.\nproxmox-fetch-answer will scan *all* attached partitions (including USB #1)\nby label, so answer.toml living on USB #1 still reaches the installer running\nfrom USB #2.

            NETSetup -> Computer: FindBootDiskNumber(host) — resolve USB #1 disk number from AppContext.BaseDirectory drive letter
            NETSetup -> Computer: UsbLinuxPartitionManager.EnsureUsbDataPartition(usbDiskNumber, 100 MB, label=SYSTEM, fs=fat32, assignDriveLetter=true)
            note over Computer: **On USB #1 (the booted NETSetup stick):**\n  1. Find largest partition (NTFS DATA partition 2)\n  2. Shrink it via diskpart (current - 100 MB)\n  3. Create new primary partition in freed space\n  4. Format FAT32 with label SYSTEM\n  5. Add-PartitionAccessPath -AssignDriveLetter -> first free letter\nIdempotent: if SYSTEM already exists, re-uses it and just re-assigns a letter.
            NETSetup -> Computer: netSetupConfig.ToProxmoxAutoInstall(host, liberator, setStaticNetworkConfiguration: true).WriteTomlFile({letter}:\answer.toml)
            note over Computer: answer.toml lives at {assignedLetter}:\answer.toml on USB #1 SYSTEM (FAT32).\nPath + full TOML content are logged via LogDebugToFile("WinPE_Proxmox_AnswerToml").
            NETSetup -> Agent: UserInteraction.AskRebootNow("You will need to boot from Proxmox USB Stick now...")
            note over Agent: **Agent must now reboot and pick USB #2 (Proxmox) from the boot menu**\n(NETSetup cannot force this — USB #1 is still the default boot device).\nUSB #1 stays plugged in so proxmox-fetch-answer can find SYSTEM:/answer.toml.

        else other Linux (NixOS, etc.)
            note over Computer: VoidPE stays on USB NTFS (not overwritten).\nWinPE writes linux config to SYSTEM partition.
            NETSetup -> Computer: Write linux config file to SYSTEM:\config
        end

        NETSetup -> Computer: ExitReboot()
        note over Computer: **USB #1 layout after WinPE prep (Proxmox case):**\n  Partition 1: FAT32 ESP (unchanged)\n  Partition 2: NTFS DATA (shrunk by 100 MB)\n  Partition 3: FAT32 SYSTEM — answer.toml\n**USB #2 is completely unchanged** (still a plain Rufus-flashed Proxmox ISO).\nTarget disk is completely untouched.

newpage NETSetup Setup Process - Boot Phase 2: Agent boots Proxmox USB

        == PHASE 2: Agent reboots and selects USB #2 (Proxmox) from boot menu ==
        Agent -> Computer: Power-cycle; hold F9 (or equivalent) to open UEFI boot menu
        Agent -> Computer: Select USB #2 "Proxmox" entry (NOT USB #1)
        note over Computer: **USB #1 stays plugged in** — proxmox-fetch-answer will scan all attached\npartitions (by label) and find SYSTEM:answer.toml on USB #1.\nSecure Boot must be OFF (Proxmox GRUBX64.EFI is not signed for SB).\nThe agent already disabled SB in BIOS before deployment.
        Computer -> Computer: UEFI loads Proxmox shim BOOTX64.EFI from USB #2 ESP (unmodified Rufus flash)
        Computer -> Computer: Proxmox shim loads GRUBX64.EFI, which loads the stock Proxmox GRUB.CFG from USB #2

        alt operatingSystem is Proxmox

            Computer -> Computer: Stock Proxmox GRUB menu appears — agent selects "Install Proxmox VE (Automated)"
            note over Computer: **No custom GRUB.CFG** — USB #2 is a plain Rufus-flashed Proxmox ISO.\nAgent picks the stock "Automated" entry manually, which passes\nproxmox-start-auto-installer to the kernel.
            Computer -> Computer: GRUB loads Proxmox kernel+initrd from USB #2 iso9660 partition

newpage NETSetup Setup Process - Phase 2 continued: Proxmox auto-installer

            == PHASE 2 continued: Proxmox auto-installer ==
            Computer -> Computer: Kernel boots, normal Proxmox /init runs
            Computer -> Computer: /init mounts squashfs (pve-base.squashfs, pve-installer.squashfs)
            Computer -> Computer: Creates overlayfs, switch_root -> /sbin/unconfigured.sh
            Computer -> Computer: proxmox-start-auto-installer triggers proxmox-auto-installer
            Computer -> Computer: proxmox-fetch-answer scans all attached partitions for answer.toml
            note over Computer: proxmox-fetch-answer uses blkid to scan every attached partition and reads\nthe first one containing answer.toml.\nFinds **USB #1 partition 3 (SYSTEM, FAT32, written by WinPE)**.\nUSB #1 must still be plugged in at boot time — agent keeps both sticks attached\nuntil the installer has read the answer.
            Computer -> Computer: Auto-installer partitions TARGET DISK, installs Proxmox
            note over Computer: Target disk touched for the FIRST TIME here.\nAuto-installer: sgdisk, mkfs, LVM, debootstrap.\nConfigures network, hostname, root password from answer.toml.\nBoth USB sticks stay completely intact.
            Computer -> Computer: Reboot into installed Proxmox

        else other Linux (VoidPE path)

            Computer -> Computer: GRUB selects "NETSetup VoidPE" entry
            Computer -> Computer: GRUB loads VoidPE kernel+initrd from LINUX partition
            note over Computer: VoidPE boots from USB LINUX partition.\ndracut live module finds squashfs on LABEL=LINUX.\nOverlayfs rootfs. /etc/rc.local runs NETSetup.
            Computer -> NETSetup: NETSetup.exe install (Stage4LinuxPE)
            NETSetup -> Computer: Partition target drive, format, unpack image
            NETSetup -> Computer: Update boot entry (GRUB/EFI), reboot into installed Linux

        end

newpage NETSetup Setup Process - Phase 3: Proxmox Host Creates VMs

        == PHASE 3: Proxmox Host + NETSetup (runs ON installed Proxmox) ==
        note over Computer: Proxmox VE is now installed and running.\n[[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Resources/netsetup-first-boot.sh netsetup-first-boot.sh]] (USB-only install, no network fallback):\n  0. **Log-exists gate** — if /NETSetup/first-boot.log exists → exit (idempotent)\n  1. Restore Windows Boot Manager on USB ESP (bootmgfw.efi.bak → BOOTX64.EFI)\n  2. Mount SYSTEM partition (label=SYSTEM, FAT32 on USB #1)\n  3. cp -p NETSetup binary from /mnt/system/NETSetup/NETSetup → /NETSetup/NETSetup (preserves mtime)\n  4. cp -r config files from /mnt/system/NETSetup/Config → /NETSetup/Config\n  5. Install systemd service + timer (OnBootSec=2min, OnUnitActiveSec=6h, Persistent=true)\n  6. systemctl enable netsetup.timer (**NOT --now** — fires only after reboot)\n  7. **systemctl reboot** (scheduled +5s so first-boot unit exits cleanly)\n**No inline `netsetup update`** — network flaky during first-boot (DNS/403 on GitHub).\nBinary handles self-update via GitHub Releases API on every update cycle (see 3a).
        Computer -> Computer: First-boot service runs (from Proxmox ISO, ordering=fully-up)
        Computer -> Computer: Restore USB ESP boot manager (so USB is reusable)
        Computer -> Computer: Mount SYSTEM partition → cp NETSetup binary + Config locally
        Computer -> Computer: systemctl enable netsetup.timer (timer armed, NOT fired)
        Computer -> Computer: **Reboot** — clean boot, full network, then timer fires
        note over Computer: **After reboot**, systemd timer fires 2 min in (Persistent=true catches missed runs).\nOn **every subsequent boot** the timer also re-fires `netsetup update`.
        Computer -> NETSetup: systemd timer → ExecStart=/NETSetup/NETSetup update

        note over NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/CLI/Commands/UpdateCommands.cs UpdateCommands.cs]] → [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Helpers/UpdateMethods.cs UpdateMethods.RunUpdate]]\nDetermineUpdateStage(host) → host.IsProxmoxHost() → RunProxmoxUpdate.\nEvery step is a discrete NETCommand call so individual failures stay scoped\nand surface in the C# log (no monolithic shell scripts).

        == PHASE 3a: Self-Update via GitHub Releases ==
        note over NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Helpers/UpdateMethods.cs EnsureLatestBinaryOrReexec]] — runs FIRST, before anything else:\n  1. Decrypt embedded GitHub PAT via osisa.Security.Contracts.EncryptionHelper\n     (AES-256-CBC, PBKDF2-SHA1, baked-in ciphertext invisible to strings(1))\n  2. curl GET /repos/osisa/netsetup/releases/latest with Bearer token\n  3. ParseReleaseInfo → (version, assetId)\n  4. CompareSemVer(local, remote) — same major.minor.patch ⇒ trailing build counter wins\n  5. Remote newer → curl /releases/assets/{id} (Accept: application/octet-stream),\n     mv -f → /NETSetup/NETSetup, chmod 755, spawn child `NETSetup update`,\n     Environment.Exit(child.IsSuccess ? 0 : 1) — re-execs into the new binary
        NETSetup -> Computer: Decrypt embedded PAT (Contents:Read on osisa/netsetup only)
        NETSetup -> Computer: curl /releases/latest → ParseReleaseInfo
        alt remoteSemVer > localSemVer
            NETSetup -> Computer: Download asset by id → mv -f → chmod 755
            NETSetup -> NETSetup: Spawn `/NETSetup/NETSetup update`, wait, Environment.Exit
            note over NETSetup: Re-execed into the new binary; rest of this cycle runs there.
        else equal or older
            NETSetup -> Computer: Continue with current binary
        end

        == PHASE 3b: EnsureProxmoxPostInstall (once-only, LogFileExists-gated) ==
        note over NETSetup: **Log-file gate** mirrors Windows Stage3 pattern:\n  `if (!host.Logger.LogFileExists("ProxmoxPostInstall"))` → run + LogInformationToFile → **reboot + Environment.Exit(0)**\n  → next boot the log exists → skip → continue with 3c.\nEach helper = one discrete NETCommand or IFileOperator call:\n  - DisableEnterpriseListRepos (PVE 8 .list — sed in-place)\n  - DisableEnterpriseDeb822Repos (PVE 9 .sources — fileop read+write)\n  - EnsureNoSubscriptionRepo (pveversion → write .list or .sources)\n  - InstallNagRemovalHook (write hook + apt post-invoke + chmod + run once)\n  - ConfigureBanners (clear /etc/motd + systemctl disable pvebanner + write /etc/issue with detected IP)
        alt /NETSetup/Logs/ProxmoxPostInstall.log missing (FIRST run)
            NETSetup -> Computer: EnsureProxmoxPostInstall (repos, nag, banners)
            NETSetup -> Computer: LogInformationToFile("ProxmoxPostInstall", ...) — writes gate marker
            NETSetup -> Computer: systemctl reboot + Environment.Exit(0) — rest of cycle skipped
            note over Computer: **Next boot** the timer re-fires `netsetup update`.\nlog exists → post-install skipped → continues with 3c-3e below.
        else log exists (subsequent runs)
            NETSetup -> Computer: log "skipping post-install, continuing update" — falls through to 3c
        end

        == PHASE 3c: apt update + full-upgrade ==
        NETSetup -> Computer: apt update (only succeeds AFTER enterprise repos disabled in 3b)
        NETSetup -> Computer: env DEBIAN_FRONTEND=noninteractive apt full-upgrade -y

        == PHASE 3d: EnsureCustomerVms + EnsureCustomerLxcs ==
        note over NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Helpers/EnsureCustomerVms.cs EnsureCustomerVms.Run]] orchestrates per-host VM/LXC provisioning:\n  1. orderedVms = [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/5-NETSetupLinux/CreateVirtualMachines.cs GetOrderedVmsForHost]](config, host.SerialNumber)\n     IsForHost matches serial `<VMID>@<HostSerial>`; tests rewire suffix to real BIOS serial.\n  2. Classify: Nix (OS.NixNextcloud / OS.NixMail / OS.NixDns / OS.NixIPFS / OS.NixDocker / OS.NixGeneric) | Windows | PMG-LXC | Skip\n  3. If any Nix VM exists → [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Helpers/EnsureNixosIsoOnProxmoxHost.cs EnsureNixosIsoOnProxmoxHost]] (sha256-driven 7z sync from Dropbox NETSetup/BOOT/Images/NixOS.7z to /var/lib/vz/template/iso/nixos.iso)\n  4. Per-VM dispatch with fault isolation (Mail failure does NOT skip Dns/Pmg)
        NETSetup -> Computer: EnsureCustomerVms.Run(host, config, services)

        == PHASE 3d.1: NixOS VM provisioning ==
        note over NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/5-NETSetupLinux/ProvisionNixosVm.cs ProvisionNixosVm.Run]] — applies to Nextcloud, Mail, Dns (any Nix* VM):\n  Per-template CPU/RAM/disk via [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Config/Nix/Templates/NixHostTemplate.cs NixHostTemplate]] virtuals:\n    - Nextcloud: 4c / 8 GB / 256 GB disk\n    - Mail/Dns/Generic: 2c / 2 GB / 32 GB disk\n  Steady-state swapfile (8 GB on /var/swapfile) keeps services from OOM under load.
        loop For each Nix VM in orderedVms (DC-first ordering)
            NETSetup -> Computer: qm create <vmid> with per-template cpu/mem/disk + 16G install-time swap on scsi1 + ide0 ISO (nixos.iso) + autoStart=false
            NETSetup -> Computer: qm set scsi1 (16G scratch) + qm start <vmid>
            NETSetup -> Computer: DiscoverVmIpViaQmAgent — poll qm guest-agent network-get-interfaces (5min timeout, filters lo/link-local)
            NETSetup -> Computer: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/5-NETSetupLinux/ProvisionNixosVm.cs EmitConfigBundle]] — writes config.nix + hardware.nix + sops secrets.yaml + .default.key + bakes netsetup-master.pub into root + admin authorizedKeys
            NETSetup -> Computer: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/NETCommand/NixRemoteInstallCommand.cs NixRemoteInstallCommand]] phases 1-3 over SSH (master key root):
            note over NETSetup: 1. ssh-keyscan target ip\n2. tar c <configDir> | ssh ... 'rm -rf /nixos-config && cp -r /iso/nixos-config /nixos-config && tar x -C /nixos-config --strip-components=1'\n3. SSHEnvironment + LsBlkCommand: detect largest non-removable disk = INSTALL, smallest = SWAP (virtio-scsi-single PCI ordering unstable, fixed sda/sdb broke run #23)\n4. SSHEnvironment + MkswapCommand + SwaponCommand + MountCommand: prep install-time swap on SWAP, remount /nix/.rw-store to 20G tmpfs\n5. SSHEnvironment + BashCommand: /iso/nixos-config/scripts/install.sh -h default -d <INSTALL>
            note over Computer: Inside the VM, install.sh runs disko-install which partitions INSTALL, writes bootloader (systemd-boot + /EFI/Boot/BOOTX64.EFI fallback), generates SOPS host age key, decrypts secrets.yaml -> luks_password.\nNon-interactive mode auto-reboots via `systemctl reboot --no-block` so VM exits live ISO and boots installed system.
            NETSetup -> Computer: qm set <vmid> -delete ide0 -delete scsi1 (detach installer ISO + scratch swap), qm stop <vmid>, qm start <vmid>
            note over Computer: VM boots from disk into installed NixOS.\nMail-only: mail-tls-bootstrap systemd unit generates snake-oil cert at /var/lib/acme/mail.<domain>/{fullchain.pem,key.pem} BEFORE postfix/dovecot/nginx start, so services come up even before Let's Encrypt issues real cert.
        end

        == PHASE 3d.2: PMG LXC provisioning ==
        note over NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/5-NETSetupLinux/ProvisionPmgLxc.cs ProvisionPmgLxc.Run]] — Proxmox Mail Gateway as LXC container (not full VM, smaller footprint).\nUses [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/NETCommand/LxcCommand.cs LxcCommand]] (pct binary wrapper).
        loop For each PMG LXC in customer config
            NETSetup -> Computer: pct create <ctid> debian-12-standard.tar.zst — 8G rootfs, 2 cores, 2 GB RAM, dhcp on vmbr0, unprivileged + nesting=1, --password default4244$
            NETSetup -> Computer: pct start <ctid>; poll status until running (60s timeout)
            NETSetup -> Computer: pct exec <ctid> -- /bin/sh -c '<install_script>' — apt update + apt install proxmox-mailgateway, configure smarthost relay to mail.<domain>:26
        end

        == PHASE 3d.3: OPNsense router VM provisioning (gated, Option Y 5-NIC) ==
        note over NETSetup: **Gate**: only runs if `host.Description == "Liberator"` AND OPNsense VM in config for `host.SerialNumber`.\nPower Station / vanilla Proxmox / other -> entire OPNsense + Mikrotik + VLAN flow skipped.\nSee [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/docs/Liberator.adoc Liberator.adoc]] for role matrix.\n\n[[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/5-NETSetupLinux/ProvisionOpnsenseVm.cs ProvisionOpnsenseVm.Run]] - OPNsense router as Proxmox-hosted VM (FreeBSD, prebuilt raw disk image).\nClassify gate: OS == OS.OPNSense -> VmProvisionKind.Opnsense.\nImage source: /var/lib/vz/template/iso/opnsense.img (synced via [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Helpers/EnsureOpnsenseImageOnProxmoxHost.cs EnsureOpnsenseImage.EnsureOpnsenseImageOnProxmoxHost]] from Dropbox NETSetup/BOOT/Images/Opnsense.7z).\nOrdering: OPNsense first in [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/5-NETSetupLinux/CreateVirtualMachines.cs GetOrderedVmsForHost]].\n**5 tagged vNICs (Option Y)**: hypervisor enforces VLAN, defence in depth.
        alt host.Description == "Liberator" && hasOpnsenseVm
        loop For each OPNsense VM in orderedVms (host-first ordering)
            NETSetup -> Computer: qm create <vmid> --bios seabios --memory 2048 --cores 2 --agent enabled=1 --scsihw virtio-scsi-single\n  --net0 virtio,bridge=vmbr0\n  --net1 virtio,bridge=vmbr0,tag=10\n  --net2 virtio,bridge=vmbr0,tag=20\n  --net3 virtio,bridge=vmbr0,tag=250\n  --net4 virtio,bridge=vmbr0,tag=254
            NETSetup -> Computer: qm importdisk <vmid> /var/lib/vz/template/iso/opnsense.img <storage>
            NETSetup -> Computer: qm set <vmid> --scsi0 <storage>:vm-<vmid>-disk-0 --boot order=scsi0
            NETSetup -> Computer: qm start <vmid>
            NETSetup -> Computer: OpnsenseInstall.Install(host, machine, config) - first-boot only, gated by /conf/.netsetup-installed:\n  build config.xml with 5 if assignments (vtnet0..4), DHCP per VLAN,\n  static maps from config.Computers[].MAC, DNS forwarder -> NixDns,\n  FW deny-default inter-VLAN, admin user + api_key/api_secret\n  ssh root@<wanIp> + scp /conf/config.xml + configctl service reload all\n  persist api_key to /etc/netsetup/opnsense-api.env
        end
        else !runFullNetworkFlow (Power Station / Proxmox / other)
            note over NETSetup: OPNsense provisioning skipped entirely.\nFlat vmbr0 only. VMs still get provisioned (next sections).
        end

        == PHASE 3d.4: Windows VM provisioning ==
        note over NETSetup: [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/src/NETSetup/Stages/5-NETSetupLinux/ProvisionWindowsVmOnProxmox.cs ProvisionWindowsVmOnProxmox.Run]] — generates per-VM offline NETSetup ISO via MainISO.CreateOfflineProductionISO, scps to /var/lib/vz/template/iso/, qm create with VirtIO + answer.toml.
        loop For each Windows VM in orderedVms
            NETSetup -> Computer: MainISO.CreateOfflineProductionISO(vm.Os, vm.AnswerToml) -> /tmp/<vmname>.iso
            NETSetup -> Computer: scp -> /var/lib/vz/template/iso/<vmname>.iso
            NETSetup -> Computer: qm create <vmid> + scsi0 (32+G), ide2 cdrom (vm-iso), virtio net, autoStart=true
        end

        == PHASE 3e: Liberator network converge (gated, every cycle, idempotent) ==
        note over NETSetup: **Gate**: `runFullNetworkFlow = host.Description == "Liberator" && hasOpnsenseVm`.\nSkipped on Power Station / vanilla Proxmox / other.\nFour helpers run in this order, each idempotent + drift-correcting.\nSee [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/docs/Liberator.adoc Liberator.adoc]] + [[https://github.com/osisa/NETSetup/tree/feature/proxmoxvms/docs/Liberator-Network-Push.puml Liberator-Network-Push.puml]] for full diagram.
        alt runFullNetworkFlow
            NETSetup -> Computer: ConfigureOpnsenseVlans (REST API push)\n  probe /api/core/system/status\n  PUT /api/dhcpv4/static_map (per Computer in machine map)\n  PUT /api/dnsforwarder/settings (forward to NixDns .53)\n  PUT /api/firewall/alias/... (per-VLAN subnets, public services)\n  PUT /api/firewall/filter/... (deny default, allow VLAN20->VLAN10 AD/DNS/SMB/print/HTTPS)\n  POST /api/firewall/apply
            NETSetup -> Computer: ConfigureMikrotikVlans (REST API push)\n  bridge VLAN-aware on, VLANs 10/20/250/254\n  bonding1 LACP 802.3ad slaves=ether2,ether3\n  trunk tagged on bond, ether4/ether5 access VLAN20 untagged\n  WiFi SSIDs: Liberator(20), Liberator-Guest(254 open), admin-oob-lib(250 hidden WPA3)\n  Mikrotik mgmt IP VLAN250 .1\n  remove flat NAT, disable Mikrotik DHCP server
            NETSetup -> Computer: ConfigureProxmoxBridges (/etc/network/interfaces rewrite)\n  bond0 LACP enp1s0+enp2s0, bond-mode 802.3ad\n  vmbr0 bridge-vlan-aware yes, bridge-vids 10 20 250 254\n  vmbr0v250 host mgmt = .2\n  ifupdown2 reload safe-mode (commit/rollback if mgmt lost)
            NETSetup -> Computer: RewireVmNicsToVlans (drift correction)\n  for each existing VM, qm set <vmid> -netN ...,tag=<vlan> only if missing/wrong\n  NixDns/DC/NC/Mail/PMG -> tag=10\n  Win11 clients -> tag=20
        else !runFullNetworkFlow
            note over NETSetup: All 4 network converge helpers skipped.
        end

        == PHASE 3f: btrfs scrub ==
        NETSetup -> Computer: For each mounted btrfs filesystem -> btrfs scrub start -B
        note over Computer: systemd timer re-fires netsetup.service every 6h **and on every boot** (OnBootSec=2min).\nPhases 3c/3d/3e/3f run every cycle (apt, VMs, network converge, scrub all idempotent).\nPhase 3b runs ONCE (log-gated) and reboots on first run.\nPhase 3a swaps binary only when remote SemVer is strictly greater, logs outcome either way.\nPhase 3e gated on host.Description == "Liberator" && hasOpnsenseVm. Bare hosts skip it entirely.

    end
end

newpage Approval and Billing
Agent -> Customer: [[https://github.com/osisa/NETSetup/tree/develop/docs/NETSetup/400%20Abnahme config.CreateApprovalForm())]]
Customer -> Agent: fillOut(config.approvalForm)
Agent -> Accounting: [[https://github.com/osisa/NETSetup/blob/develop/docs/Infobl%C3%A4tter/Software/Sage/Sage%20Start/Softwareinfoblatt%20Sage%20Start.adoc commissionBill(config)]]
Accounting -> Agent: returnBill(config.bill)
Agent -> Customer: sendBill(config.bill)
Customer -> Accounting: payBill(config.bill)
Accounting -> Agent: notify(config.bill.paid)
Agent -> Ticketing: closeTicket()

@enduml

@startuml NETSetupProvisionVms

title Proxmox VM Provisioning During `netsetup update`

actor Admin
participant "netsetup update\n(on Proxmox host)" as NS
participant "UpdateMethods\nRunProxmoxUpdate" as UM
participant "EnsureCustomerVms" as ECV
participant "EnsureNixosIso" as EI
participant "Dropbox\nNETSetup/ISOs" as DB
participant "Proxmox Host\n(corsinvest API)" as PH
participant "NixOS VM\n(generic nixos.iso)" as NIX
participant "Windows VM" as WIN

Admin -> NS: netsetup update
NS -> UM: RunProxmoxUpdate(host, config)
UM -> UM: apt update + full-upgrade
UM -> UM: btrfs scrub
UM -> ECV: EnsureCustomerVms(host, config)

group Nix path (any nix VM in config)
    ECV -> EI: EnsureNixosIsoOnProxmoxHost
    EI -> DB: GET nixos.iso.sha256
    EI -> EI: compare to local iso sha256
    alt mismatch or missing
        EI -> DB: GET nixos.iso.7z
        EI -> EI: verify sha256, 7z extract
        EI -> PH: place nixos.iso at\n/var/lib/vz/template/iso/
    end
end

loop for each VM (DC first)
    alt IsNixBacked(os)
        ECV -> PH: CreateVirtualMachine(nixos.iso)
        PH -> NIX: boot from nixos.iso\n(qemu-guest-agent enabled)
        ECV -> PH: qm guest network-get-interfaces\n(poll 2s, deadline 5m)
        PH --> ECV: ipv4
        ECV -> ECV: NixTemplateFactory.ForMachine\nemit flake.nix + default.nix + hardware.nix\nto /NETSetup/generated-nix/<vm>
        ECV -> NIX: scp -i netsetup-master.key\n-r <genDir> root@ip:/nixos-config/
        ECV -> NIX: ssh root@ip\ninstall.sh -h <name> -d <disk>
        NIX --> ECV: install OK, reboot
    else Windows
        ECV -> ECV: per-VM offline create-iso\nNETSetup-<ticket>-<host>.iso
        ECV -> PH: upload ISO to\n/var/lib/vz/template/iso/
        ECV -> PH: CreateVirtualMachine(NETSetup-ISO,\nstealth hw iff Win11)
        PH -> WIN: boot from NETSetup ISO\n(unattended install)
    else other
        ECV -> ECV: log + skip
    end
    ECV -> ECV: collect per-VM outcome
end

alt any failure
    ECV --> UM: throw NETSetupException\n(aggregate failed VM names)
else all success
    ECV --> UM: OK
end

UM --> NS: update complete
NS --> Admin: exit 0

@enduml

@startuml Liberator-Network

title Liberator network topology - hAP ax2 + Proxmox + OPNsense + VLANs

' Role discriminator = host.Description (DeviceTranslator.cs:297 pattern):
'   "Liberator"     -> full flow: Mikrotik upstream + OPNsense on host + VLANs
'   "Power Station" -> bare Proxmox, future cluster compute, no router/VLAN
'   "Proxmox" / other -> bare Proxmox, no router/VLAN
' Defensive double-gate: isLiberator && hasOpnsenseVm in config for host.SerialNumber.
'
' VLAN map: 10 = server tier, 20 = LAN clients, 250 = OOB/MGMT, 254 = Guest.
' WAN untagged on Mikrotik ether1.
' DHCP source of truth: OPNsense per VLAN. Static reservations from config.Computers[].MAC.
' DNS resolver: NixDns VM running Unbound. OPNsense forwards all clients to NixDns IP.

skinparam rectangle {
  BackgroundColor<<infra>> #E8F0FE
  BackgroundColor<<svc>>   #E6F4EA
  BackgroundColor<<fw>>    #FCE8E6
  BackgroundColor<<dns>>   #FEF7E0
  BackgroundColor<<net>>   #F3E8FD
}

cloud "ISP / GPON CPE\nuntagged DHCP" as NET

node "Mikrotik hAP ax2 (L2 only post phase 2)\nmgmt IP VLAN250 .1\nNO NAT, NO DHCP server" as MT <<net>> {
  rectangle "ether1 (2.5G) WAN\nuntagged DHCP" as MT_E1
  rectangle "bonding1 = ether2 + ether3\nLACP 802.3ad\ntrunk: 10,20,250,254" as MT_BOND
  rectangle "ether4 access\nVLAN20 untagged" as MT_E4
  rectangle "ether5 access (spare LAN port)\nVLAN20 untagged" as MT_E5
  rectangle "wlan 2.4 + 5 GHz\nSSID Liberator\nWPA2/3 -> VLAN20" as MT_W_LAN
  rectangle "wlan 2.4 GHz\nSSID Liberator-Guest\nopen, no portal -> VLAN254" as MT_W_GUEST
  rectangle "wlan 5 GHz hidden\nSSID admin-oob-lib\nWPA3 -> VLAN250" as MT_W_ADMIN
}

NET <--> MT_E1 : public IP

node "Proxmox host (Liberator)\nbond0 = enp1s0 + enp2s0 LACP\nvmbr0 VLAN-aware trunk\nhost mgmt = vmbr0v250 = .2" as PVE <<infra>> {

  rectangle "OPNsense VM (Option Y, 5 vNIC)\nserial 104@lib\n  net0 untagged   = WAN\n  net1 tag=10     = .1 server tier gw\n  net2 tag=20     = .1 LAN gw + DHCP\n  net3 tag=250    = .3 MGMT\n  net4 tag=254    = .1 Guest gw\nFW deny-default inter-VLAN\nNAT outbound\nDNS forwarder -> NixDns .53\nREST API key first-boot installed" as OPN <<fw>>

  rectangle "NixDns VM (Unbound)\nserial 103@lib\nvNIC tag=10 = .53\nVLAN10\nresolver + blocking +\nreverse + DDNS" as DNS <<dns>>
  rectangle "Win Server DC\nserial dc@lib\nvNIC tag=10 = .10\nVLAN10\nDNS = 127.0.0.1, .53" as DC <<svc>>
  rectangle "Nextcloud VM\nserial 100@lib\nvNIC tag=10 = .50\nVLAN10" as NC <<svc>>
  rectangle "Mail VM\nserial 102@lib\nvNIC tag=10 = .51\nVLAN10" as MAIL <<svc>>
  rectangle "PMG LXC\nctid 200@lib\nvNIC tag=10 = .52\nVLAN10" as PMG <<svc>>
  rectangle "Win11 client VM\nserial 201@lib\nvNIC tag=20\nDHCP from OPNsense VLAN20" as W11 <<svc>>
}

MT_BOND <==> PVE : LACP 802.3ad trunk\n10 / 20 / 250 / 254

OPN -[hidden]- DNS
OPN -[hidden]- DC

DNS --> OPN  : VLAN10
DC --> OPN   : VLAN10
NC --> OPN   : VLAN10
MAIL --> OPN : VLAN10
PMG --> OPN  : VLAN10
W11 --> OPN  : VLAN20

MT_E4 ..> OPN : VLAN20 access (LAN clients reach OPNsense via Mikrotik bridge)
MT_W_LAN ..> W11 : VLAN20 (WiFi clients)
MT_W_ADMIN ..> PVE : VLAN250 OOB (admin laptop -> Proxmox host independent of OPNsense)

note bottom of OPN
  **Option Y: 5 tagged vNICs**
  Hypervisor enforces VLAN, defence in depth.
  qm create:
    -net0 virtio,bridge=vmbr0
    -net1 virtio,bridge=vmbr0,tag=10
    -net2 virtio,bridge=vmbr0,tag=20
    -net3 virtio,bridge=vmbr0,tag=250
    -net4 virtio,bridge=vmbr0,tag=254
  Other VMs: single tagged vNIC each.
end note

note right of PVE
  Out-of-band mgmt path:
    laptop -> admin-oob-lib WiFi (hidden, VLAN250)
    -> Mikrotik bridges VLAN250 over LACP trunk
    -> Proxmox host .2 reachable
    even if OPNsense down.
end note

note left of MT
  **Phase 1 bootstrap** (today's flash-mikrotik):
    flat NAT, Mikrotik DHCP, single vmbr0 on host.
  **Phase 2 cutover** (additive then strip):
    add VLAN bridge alongside flat
    -> swing Proxmox + VMs
    -> enable OPNsense WAN VLAN
    -> strip Mikrotik NAT + DHCP.
  Re-pushed every netsetup update cycle (idempotent).
end note

note top of NET
  **Role gate**: host.Description == "Liberator"
  AND OPNsense VM in config for host.SerialNumber.
  Otherwise (Power Station / Proxmox / other):
  skip entire Mikrotik + OPNsense + VLAN flow.
  VMs still provisioned on flat vmbr0 untagged.
end note

@enduml

@startuml Liberator-Network-Push

title netsetup update push - Liberator network converge (every cycle, idempotent)

actor Admin
participant "netsetup update\n(on Proxmox host)" as NS
participant "UpdateMethods\nRunProxmoxUpdate" as UM
participant "EnsureCustomerVms" as ECV
participant "ProvisionOpnsenseVm" as POPN
participant "OpnsenseInstall\n(SSH first-boot)" as INST
participant "ConfigureOpnsenseVlans\n(REST API push)" as COV
participant "ConfigureMikrotikVlans\n(REST API push)" as CMV
participant "ConfigureProxmoxBridges\n(/etc/network/interfaces +\nsafe ifreload)" as CPB
participant "RewireVmNicsToVlans\n(qm set tag=...)" as RWN
participant "OPNsense VM" as OPN
participant "Mikrotik hAP ax2" as MT
participant "Other VMs (Nix / Win / PMG)" as VMS

Admin -> NS: netsetup update
NS -> UM: RunProxmoxUpdate(host, config)
UM -> UM: post-install gate (log file)\napt update + full-upgrade\nEnsureProxmoxResolvConfSecondaryDns

== Role gate ==
UM -> UM: isLiberator = host.Description == "Liberator"
UM -> UM: hasOpnsenseVm = GetOrderedVmsForHost(config, host.SerialNumber)\n  .Any(v => v.OS == OS.OPNSense)
UM -> UM: runFullNetworkFlow = isLiberator && hasOpnsenseVm

alt runFullNetworkFlow

  UM -> ECV: Run(host, config, services)

  == Phase 3d.3: OPNsense provision (Option Y, 5 vNIC) ==
  ECV -> POPN: provision (default raw image, first only)
  POPN -> OPN: qm create <vmid>\n  --net0 virtio,bridge=vmbr0\n  --net1 virtio,bridge=vmbr0,tag=10\n  --net2 virtio,bridge=vmbr0,tag=20\n  --net3 virtio,bridge=vmbr0,tag=250\n  --net4 virtio,bridge=vmbr0,tag=254\nqm importdisk + qm set --scsi0 + qm start

  alt /conf/.netsetup-installed missing
    ECV -> INST: OpnsenseInstall.Install(host, machine, config)
    INST -> INST: build config.xml:\n  vtnet0..4 assigned\n  DHCP per VLAN (10/20/254)\n  static maps from config.Computers[].MAC\n  DNS forwarder -> NixDns .53\n  FW deny-default inter-VLAN\n  allow VLAN20 -> VLAN10 (AD/DNS/SMB/print/HTTPS)\n  admin user + api_key/api_secret
    INST -> OPN: ssh root@<wanIp> (master key)\nscp config.xml -> /conf/\nconfigctl service reload all
    INST -> INST: persist api_key/secret to\n/etc/netsetup/opnsense-api.env
  end

  == Phase 3d.x: other VMs (single tagged vNIC each) ==
  ECV -> VMS: NixDns/DC/NC/Mail/PMG -> tag=10\nWin11 client -> tag=20\n(serial host matching unchanged)

  == Phase 3e: VLAN converge (every cycle, drift-correcting) ==

  UM -> COV: push OPNsense REST API
  COV -> OPN: probe /api/core/system/status (basic auth)
  COV -> OPN: PUT /api/dhcpv4/static_map\nPUT /api/dnsforwarder/settings\nPUT /api/firewall/alias/...\nPUT /api/firewall/filter/...\nPOST /api/firewall/apply

  UM -> CMV: push Mikrotik REST API
  CMV -> MT: bridge VLAN-aware on\nadd VLANs 10,20,250,254\nbonding1 LACP 802.3ad\n  slaves = ether2, ether3\ntrunk ports tagged\nether4, ether5 access VLAN20\nwifi SSIDs: Liberator(20)\n             Liberator-Guest(254)\n             admin-oob-lib(250 hidden)\nMikrotik IP VLAN250 .1\nremove flat NAT\ndisable Mikrotik DHCP server

  UM -> CPB: rewrite /etc/network/interfaces:\n  bond0 LACP enp1s0+enp2s0\n  vmbr0 bridge-vlan-aware\n  vmbr0v250 host mgmt = .2\nifupdown2 reload safe-mode\n(rollback if mgmt lost)

  UM -> RWN: for each existing VM, drift-check tag:\n  qm set <vmid> -netN ...,tag=<vlan>\nonly when tag missing or wrong\n(idempotent)

  == Phase 3f: btrfs scrub ==
  UM -> UM: btrfs scrub each mounted fs

else !runFullNetworkFlow (Power Station / vanilla Proxmox / other)
  UM -> ECV: Run(host, config, services)
  ECV -> VMS: VMs provisioned on flat vmbr0 untagged\n(serial host matching unchanged)
  note right
    Skipped:
      ProvisionOpnsenseVm
      OpnsenseInstall
      ConfigureOpnsenseVlans
      ConfigureMikrotikVlans
      ConfigureProxmoxBridges
      RewireVmNicsToVlans
    Bare Proxmox path. Power Station
    cluster wiring = future TODO.
  end note
  UM -> UM: btrfs scrub each mounted fs
end

UM --> NS: update complete
NS --> Admin: exit 0

note over UM
  Cutover sequence (additive then strip) handled by the
  ordering above: OPNsense API stages all interfaces first
  (VLAN children created), Mikrotik adds VLAN bridge alongside
  flat, Proxmox swings VM NICs to tags, OPNsense WAN VLAN if
  enabled, finally Mikrotik strips flat NAT + DHCP.
  Every step idempotent so re-running netsetup update
  is always safe and converges drift.
end note

@enduml

@startuml

title Public Mail Stack Flow (per customer, on Proxmox host)

' Companion to netsetup.puml. Covers public mail stack added 2026-05-05:
' PBS on host, PMG LXC, mail VM (NixOS), dns VM (NixOS).
' All resources auto-prov via EnsureCustomerVms + EnsureCustomerLxcs +
' EnsureProxmoxPostInstall on the customer Proxmox host.

' Actors (external)
actor InternetSender as "Internet Sender\n(MX -> public IP)"
actor MUA as "MUA / Webmail User"
actor Registrar as "DNS Registrar API\n(provider per Customer)"
actor LECA as "Lets Encrypt CA"
actor Smarthost as "Optional Smarthost\n(Mailgun / Brevo / SES / M365 / ...)"

' Customer site
node "Customer Edge Router" as Edge {
  [NAT 25 -> Liberator]
  [NAT 80 -> Liberator]
  [NAT 443 -> Liberator]
  [NAT 587 -> Liberator]
}

' Proxmox host (Liberator)
node "Proxmox Host (Liberator)" as Host {
  component "PBS (apt pkg)" as PBS
  note bottom of PBS
    /var/lib/proxmox-backup/datastore
    Installed by EnsurePbsInstalled
    (EnsureProxmoxPostInstall step)
  end note

  node "LXC: pmg@<hostSerial>" as PMG {
    [proxmox-mailgateway]
    [postfix in 25]
    [postfix out 26 -> mail VM]
  }
  note bottom of PMG
    Provisioned by ProvisionPmgLxc
    pct create --features nesting=1 --unprivileged 1
    Routed by EnsureCustomerLxcs (OS = PmgLxc)
  end note

  node "VM: mail@<hostSerial>\n(NixOS, OS = NixMail)" as Mail {
    [postfix smtpd 25]
    [postfix submission 587]
    [postfix LMTP-from-PMG 26]
    [dovecot imap 143/993]
    [dovecot lmtp unix sock]
    [nginx + roundcube 443]
    [opendkim (keys only)]
  }
  note bottom of Mail
    Provisioned by ProvisionNixosVm
    via NixMailTemplate (NixHostTemplateFactory)
  end note

  node "VM: dns@<hostSerial>\n(NixOS, OS = NixDns)" as Dns {
    [coredns auth zone]
    [step-ca internal CA]
    [lego LE DNS-01]
    [ddns-updater]
  }
  note bottom of Dns
    Provisioned by ProvisionNixosVm
    via NixDnsTemplate
    Provider knob: NETSetupConfig.DnsProvider
  end note
}

' Inbound mail path
InternetSender --> Edge : "MX lookup ->\nmx.<domain> ->\npublic IP"
Edge --> PMG : "TCP 25\n(NAT forward)"
PMG --> Mail : "TCP 26\n(filtered, LMTP/SMTP)"
Mail --> Mail : "dovecot lmtp ->\nmaildir"

' Outbound mail path (two branches)
MUA --> Edge : "TCP 587 (submission)\nSTARTTLS + SASL"
Edge --> Mail : "NAT 587 -> mail VM"
Mail --> Smarthost : "if MailRelay set:\nSTARTTLS + SASL"
Smarthost --> InternetSender : "smarthost delivers"
Mail --> InternetSender : "if MailRelay null:\ndirect MX lookup"

' Webmail
MUA --> Edge : "HTTPS 443\nmail.<domain>"
Edge --> Mail : "NAT 443 -> nginx"
Mail --> Mail : "php-fpm + roundcube ->\nIMAP local 143 STARTTLS"

' DNS + ACME flow (provider-pluggable)
Dns --> Registrar : "ddns-updater PATCH\nA records (mail/pmg/mx)\nevery 60 s if IP changed"
Dns --> LECA : "lego DNS-01\n(challenge via Registrar)"
LECA --> Dns : "cert for\nmail.<domain>, pmg.<domain>"
Dns --> Mail : "SSH-push cert\non systemd path unit"
Dns --> PMG : "SSH-push cert\non systemd path unit"

' Internal DNS (LAN clients)
node "LAN Clients" as Lan
Lan --> Dns : "internal A records\n(coredns split-horizon)"

' Backup pull
Mail ..> PBS : "proxmox-backup-client\npush backups"
PMG ..> PBS : "proxmox-backup-client\npush backups"

@enduml