Proxmox VMID Renumber Script (1xx ➜ 4xx)

This repository contains a Bash script to renumber Proxmox VE QEMU VMs (classic qm virtual machines) from an old VMID scheme (e.g. 100–199) to a new one (e.g. 400–499).

Depending on your storage backend, this is more than just renaming a config file: the script also renames the underlying disks/volumes so that Proxmox remains consistent after the VMID change.

⚠️ Warning / Risk Notice
Changing VMIDs is an invasive operation touching configuration files and storage objects.
If config and volumes get out of sync, VMs may end up in a “missing disk” / “undefined” state.
Use at your own risk and create backups before applying changes.

---

Table of Contents

• Features
• Prerequisites
• Quickstart
• Options
• How It Works
• Supported Storage Backends
• What Is NOT Covered Automatically
• Post-Migration Checks
• Troubleshooting
• Recovery / Manual Fix
• Repository Layout
• Contributing
• License
• Disclaimer

---

Features

• ✅ Dry-run by default (prints what would happen)
• ✅ Collision avoidance: picks the next free VMID in the target range instead of blindly using +300
• ✅ Renumbers QEMU VMs (qm) including:
  • Proxmox VM config (/etc/pve/qemu-server/<VMID>.conf)
  • Optional firewall config (/etc/pve/firewall/<VMID>.fw)
  • Referenced disks/volumes (vm-<id>-disk-*, etc.), depending on storage backend
• ✅ Creates a backup directory with a mapping.txt
• ✅ Supports common storage types:
  • ZFS (zvol) via zfs rename
  • LVM/LVM-thin via lvrename
  • Directory storages (qcow2/raw files) via mv / directory rename

---

Prerequisites

• Run on a Proxmox VE node with:
  • qm, pvesm
• Root privileges (root@host or sudo -i)
• Depending on storage:
  • ZFS: zfs CLI available, datasets local
  • LVM: lvs, lvrename (package lvm2)

Recommended: run directly on the PVE node holding the VM configs and storage.

---

Quickstart

1. Copy the script to your PVE node, e.g.:

   cp pve-renumber.sh /root/pve-renumber.sh
   chmod +x /root/pve-renumber.sh

2. Dry-run first (recommended):

   /root/pve-renumber.sh

   This will:

   • create a backup directory under /root/pve-vmid-renumber-backup-YYYYMMDD-HHMMSS
   • write the computed mapping to mapping.txt
   • print the planned renumbering (e.g. 100 -> 400)
   • print all operations it would execute

3. If the plan looks correct, run with --apply:

   /root/pve-renumber.sh --apply

4. If some VMs might be running, you can add:

   /root/pve-renumber.sh --apply --shutdown --force-stop

---

Options

• --apply Actually perform changes. Without this flag, the script runs in dry-run mode.

• --shutdown If a VM is running, try a graceful shutdown and wait up to 300 seconds.

• --force-stop If --shutdown was used and the VM is still running after waiting, force-stop it.

• --help / -h Print usage information.

---

How It Works

At a high level, Proxmox VMIDs are tied to:

1. Configuration files:

   • QEMU VMs: /etc/pve/qemu-server/<VMID>.conf
   • Optional firewall rules: /etc/pve/firewall/<VMID>.fw

2. Storage objects referenced by the config:

   • ZFS zvols like rpool/data/vm-100-disk-0
   • LVM logical volumes like /dev/pve/vm-100-disk-0
   • Directory-based images like /var/lib/vz/images/100/vm-100-disk-0.qcow2

The script performs these steps:

1. Detect all QEMU VMIDs in the source range (default: 100–199).

2. Build a target mapping into the target range (default: 400–499), skipping already-used VMIDs.

3. Create a backup directory and write mapping.txt.

4. For each VM:

   • Ensure it is stopped (or shut it down / force-stop based on options)

   • Parse qm config <VMID> for referenced disks/volids

   • Resolve each volid to an actual path via pvesm path

   • Rename volumes depending on storage type:

     • ZFS: zfs rename
     • LVM: lvrename
     • Directory: mv folder/file and vm-<old>- ➜ vm-<new>-

   • Backup the config file

   • Rewrite references inside the config (vm-<old>- ➜ vm-<new>-, plus common /images/<id>/ paths)

   • Move /etc/pve/qemu-server/<old>.conf ➜ <new>.conf

   • Optionally move firewall config

---

Supported Storage Backends

✅ ZFS (zvol)

Typical naming:

• rpool/data/vm-100-disk-0

The script renames datasets via:

zfs rename rpool/data/vm-100-disk-0 rpool/data/vm-400-disk-0

✅ LVM / LVM-thin

Typical paths:

• /dev/pve/vm-100-disk-0

The script uses lvrename to rename the LV accordingly.

✅ Directory storages (qcow2/raw)

Typical paths:

• /var/lib/vz/images/100/vm-100-disk-0.qcow2

The script renames:

• the directory /images/<old>/ ➜ /images/<new>/ (if applicable)
• files vm-<old>-* ➜ vm-<new>-*

---

What Is NOT Covered Automatically

Depending on your environment, you may need additional manual work:

• Ceph / RBD (or other remote storages) pvesm path may not produce a local filesystem path, and renaming objects can require backend-specific commands. The script may skip these volumes with a warning.

• Replication / HA / Backup jobs Proxmox replication, HA resources, scheduled backup jobs, monitoring systems, and external automation often reference VMIDs. After renumbering, update those references accordingly.

• Snapshots / complex storage states Snapshots can introduce additional volume naming/relationships. While renaming can still work, it increases risk. Consider consolidating/handling snapshots carefully before renumbering.

---

Post-Migration Checks

After an --apply run:

1. Verify VM list:

   qm list

2. Verify a VM config resolves all disks:

   qm config 400

3. Verify storage paths (example):

   pvesm path local-zfs:vm-400-disk-0

4. Search for leftover references to old VMIDs:

   grep -R "vm-1[0-9][0-9]-" /etc/pve/qemu-server/ || true

5. Start a few VMs and confirm they boot as expected:

   qm start 400
   qm status 400

---

Troubleshooting

“dataset does not exist” (ZFS)

This often happens if:

• the dataset was already renamed during a previous run
• the config still references the old name

Check existing datasets:

zfs list -H -o name | grep 'vm-'

Then ensure the config (/etc/pve/qemu-server/<id>.conf) references the correct vm-<new>-disk-* names.

“missing disk” / VM is “undefined”

This usually means:

• volumes were renamed but the config file was not updated/moved (or vice versa)

See Recovery / Manual Fix.

“ignore invalid acl token …”

This warning is commonly related to an ACL/user token entry in Proxmox, and usually not caused by this script. It can often be fixed by cleaning up invalid tokens/ACL entries, but it is not typically blocking.

---

Recovery / Manual Fix

If a VM ends up in an inconsistent state (example: volumes renamed but config not updated), you can recover manually:

1. Find the VM’s disks (ZFS example):

   zfs list -H -o name | grep 'vm-100\|vm-400'

2. Decide the target VMID (e.g. 400) and update the config references:

   • Backup config:

     cp -a /etc/pve/qemu-server/100.conf /root/100.conf.bak

   • Replace references inside the config:

     sed -i -E \
       -e 's/(^|[^0-9])vm-100-/\1vm-400-/g' \
       -e 's#/images/100/#/images/400/#g' \
       /etc/pve/qemu-server/100.conf

   • Move config to new VMID:

     mv /etc/pve/qemu-server/100.conf /etc/pve/qemu-server/400.conf

3. Verify:

   qm config 400

---

Repository Layout

Typical layout:

.
├── pve-renumber.sh
└── README.md

---

Contributing

Contributions are welcome. Ideas:

• Improve support for additional storage backends (Ceph/RBD, iSCSI/LUN naming patterns, etc.)
• Add a “verify-only” mode that checks whether all pvesm path references resolve
• Add smarter snapshot handling (where possible)
• Extend to also handle containers (pct) if desired

Please open an issue/PR with:

• Proxmox version (pveversion -v)
• storage configuration (/etc/pve/storage.cfg with sensitive info removed)
• a sample qm config <VMID> (remove secrets/tokens)

---

Disclaimer

This script is provided “as is”, without warranty of any kind. Use at your own risk. Always ensure you have backups and a recovery plan before applying changes.

::contentReference[oaicite:0]{index=0}