Skip to main content

Proxmox VE 9 & Debian 13 Air-Gapped Update Guide

🧭

Das Labist Architectureein (whathervorragendes you’reProjekt building)für

Youeine willkontrollierte createUpdate-Umgebung. twoDa internet-connecteddu machines:

Name Role OS mirror-online Package mirror builder Debian 13 (Trixie) und das prox-onlinezukünftige Proxmox VE9 nodeansprichst, (client)werde ich die Anleitung so zukunftssicher wie möglich gestalten.

Hier ist der Wiki-Artikel für dein Bookstack, exakt so formatiert, wie du es für verschachtelten Code benötigst.

Proxmox VE 9

& Debian 13 Air-Gapped Update Guide

BothThis guide describes how to set up an intermediate APT cache on an internet-connected machine (via VirtualBox) and transfer that cache to an air-gapped environment to update Proxmox VE 9 installations.

Phase 1: VirtualBox Setup (Internet-Facing Host)

On your internet-connected machine, you need two virtual entities: the Cache Server and a Template Proxmox VM to "pull" the initial data.

1.1 Debian 13 (Trixie) Cache VM

    Create VM: 2 vCPUs, 2GB RAM, 50GB+ Disk (depending on how many packages you cache). Networking: Use Bridged Adapter to ensure it has its own IP on your local network. OS Installation: Install a minimal Debian 13 (Netinst). Ensure SSH server and Standard system utilities are onlineselected. for now.

    1.2 LaterProxmox weVE simulate9 air-gap"Feeder" byVM

    disconnecting

    To network.populate the cache, you need a machine that requests the specific Proxmox 9 packages.

      Create VM: 2 vCPUs, 4GB RAM, 20GB Disk. OS Installation: Install Proxmox VE 9 (or Debian 13 + PVE 9 packages). Networking: Ensure it can reach the Debian 13 Cache VM.

      🖥️

      Phase Step2: 0Setting —up Create VirtualBox VMs

      VM 1 — apt-mirrorAPT-Cacher-NG (DebianCache 13)Server)

        On

        Name: apt-mirror OS: Debian (64-bit) CPU: 2 cores RAM: 4 GB Disk: 200–500 GB (important for mirror!) Network: NAT (internet access)

        Installthe Debian 13 VM, install and configure the caching service.

        ### Install APT-Cacher-NG
```bash
sudo apt update
sudo apt install apt-cacher-ng -y
```

### Configuration
Edit the configuration to ensure it allows Proxmox repositories:
```bash
sudo nano /etc/apt-cacher-ng/acng.conf
```
Ensure the following line is active (Trixie)usually minimal.default) to allow HTTPS tunneling if necessary, though standard HTTP remapping is preferred:
`PassThroughPattern: .*` (Use with caution in production, but necessary for complex repo structures).

### Restart Service
```bash
sudo systemctl restart apt-cacher-ng
```

        VMPhase 23: —Populating prox-onlinethe (Proxmox VE 9)Cache

          On

          Name: prox-online OS: Debian (64-bit) CPU: 4 cores RAM: 8 GB (minimum 4 works) Disk: 64–128 GB Network: NAT

          Installyour Proxmox VE 9 "Feeder" VM, ISO.tell APT to use the Cache Server.

          🌐

          Create Stepa 1proxy —configuration Basicfile: networking

          After install:

          On apt-mirror

          ipecho a'Acquire::http::Proxy "http://<IP-OF-CACHE-SERVER>:3142";' | sudo tee /etc/apt/apt.conf.d/00proxy

          Example:

          192.168.1.240Run
          the
          updates

          Onto prox-online

          pull

          Testdata connectivity:

          into 
          pingthe 8.8.8.8cache:

          🧱 Step 2 — Install mirror on apt-mirror

          apt update
apt installdist-upgrade -y
```
Now, all downloaded `.deb` files are stored on the Debian 13 Cache VM in `/var/cache/apt-mirror nginxcacher-ng`.

          ⚙️

          Phase Step4: 3Exporting —the ConfigureCache mirror

          to the Air-Gapped System

          Since the target system is air-gapped, we must physically move the data.

          4.1 On the Internet-Connected Cache VM:

          Compress the cache data:

          nanosudo tar -cvzf pve-cache-export.tar.gz /etc/apt/mirror.listvar/cache/apt-cacher-ng

          Use:Copy pve-cache-export.tar.gz to a USB drive or mobile storage.

          set

          4.2 base_pathOn /var/spool/apt-mirrorthe setAir-Gapped nthreadsTarget 20System:

          set

          You _tildeneed 0a ############machine (or LXC container) in the air-gapped network to act as the Local Cache Server.

            Install a Debian 13 ############LXC or VM on your air-gapped Proxmox. Install apt-cacher-ng (you might need to install this manually via .deb files once if the container isn't prepared). Import the data: 
            # Extract the data to the correct location
sudo tar -xvzf /path/to/usb/pve-cache-export.tar.gz -C /
sudo chown -R apt-cacher-ng:apt-cacher-ng /var/cache/apt-cacher-ng
sudo systemctl restart apt-cacher-ng

            Phase 5: Configuring Air-Gapped Proxmox Clients

            Now, configure all your air-gapped Proxmox 9 nodes to use the internal cache server.

            5.1 Set the Proxy

            Edit /etc/apt/apt.conf.d/00proxy on every node:

            ```text
Acquire::http::Proxy "http://deb.debian.org/debian<INTERNAL-CACHE-LXC-IP>:3142";
trixie```
main
            contrib

            5.2 non-freeUpdate non-free-firmwareRepository debSources

            http:

            Ensure your /etc/apt/sources.list and /deb.debian.org/debianetc/apt/sources.list.d/pve-enterprise.list trixie-updatespoint mainto contribstandard non-freeURLs. non-free-firmwareEven debthough http://security.debian.org/debian-securitythere trixie-securityis mainno contribinternet, non-freeapt-cacher-ng non-free-firmwarewill ############trick APT into thinking it's talking to the real servers, while actually serving the files from the local disk.

            Example for Proxmox VE 9 ############(No-Subscription):

            deb [http://download.proxmox.com/debian/pve trixie pve-no-subscription

clean http://deb.debian.org/debian
clean http://security.debian.org/debian-security
clean pve](http://download.proxmox.com/debian/pve

            ⬇️ Step 4 — Run initial mirror

            apt-mirror

            ⏳ This will take a long time (first sync).

            🌐 Step 5 — Serve mirror via nginx

            nano /etc/nginx/sites-available/mirror

            server {
    listen 80;
    server_name mirror01;

    root /var/spool/apt-mirror/mirror;
    autoindex on;
}

            Enable:

            ln -s /etc/nginx/sites-available/mirror /etc/nginx/sites-enabled/
systemctl reload nginx

            🧪 Step 6 — Test mirror

            From prox-online:

            curl http://mirror01/deb.debian.org/debian/

            If DNS fails, use IP:

            curl http://192.168.56.10/deb.debian.org/debian/

            ⚙️ Step 7 — Configure Proxmox (prox-online)

            Edit:

            nano /etc/apt/sources.list

            Replace with:

            deb http://mirror01/deb.debian.org/debian trixie main contrib non-free non-free-firmware
deb http://mirror01/deb.debian.org/debian trixie-updates main contrib non-free non-free-firmware
deb http://mirror01/security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware

deb http://mirror01/download.proxmox.com/debian/pvepve) trixie pve-no-subscription

            Disable

            5.3 enterpriseRun repo: 

            sed -i 's/^deb/#deb/' /etc/apt/sources.list.d/pve-enterprise.list

            🔄 Step 8 — Test updates via mirror

            Update 
            apt update
apt dist-upgrade

            👉 If this works, your mirror is correct.

            🔒

            Troubleshooting Step& 9 — Simulate air-gapped environment

            Now simulate real-world:

            Option A (simple)Maintenance

            • DisableMaintenance: To update the air-gapped system again, repeat Phase 3 (on the internet inhost) VirtualBoxand Phase 4 (settransfer).
            networkDisk Space: Monitor /var/cache/apt-cacher-ng. You can use the web interface at http://<cache-ip>:3142/acng-report.html to “Host-only”)manage the

            Optionexpiration Bof (better)

            old
              Keep internal network between VMs Remove outbound internetpackages.

              ThenSoll testich again:dir noch spezifische Konfigurationsparameter für die Proxmox Enterprise Repositories heraussuchen, falls du diese über den Cache spiegeln möchtest?

              apt update

              ✅ If it still works → mirror is fully self-contained

              💾 Step 10 — (Real-world) Transfer model

              In production you will:

              On internet system (mirror01):

              apt-mirror
rsync -av --delete /var/spool/apt-mirror/mirror/ /media/usb/

              Move to airgap:

              rsync -av /media/usb/ /srv/mirror/

              Serve via nginx → same as above

              ⚠️ Important lessons from this lab

              1. DNS vs IP

              In airgap, DNS usually doesn’t exist → use IP or internal DNS.

              2. Mirror path structure matters

              APT expects:

              /deb.debian.org/debian
/security.debian.org/debian-security
/download.proxmox.com/debian/pve

              Do NOT flatten directories.

              3. Storage grows fast

              Even in lab:

                Start small if needed: 
                deb http://deb.debian.org/debian trixie main

                👍 Final result

                You now have:

                mirror01 (Debian) → builds mirror → serves HTTP
pve01 (Proxmox) → installs updates from mirror

                And you verified:

                  works online works offline

                  🚀 If you want next

                  I can help you:

                    shrink mirror to “Proxmox-only minimal set” (~20–40GB) add USB incremental sync strategy (fast updates) or build a fully automated offline update pipeline with versioning

                    Just tell me 👍

                    Back to top