Proxmox / Operations

Retire a Proxmox Guest So It Stays Retired

You are done with a container. You stop it. A week later it is running again, or your phone goes off at 3am about a host being down that you turned off yourself. Stopping a guest is one command. Retiring one is three switches, and the order matters.

This assumes you are keeping the guest, not destroying it

Stopped and kept is the right default for something you might want back. The disk stays, the backups stay, and you can read the logs later.

If you are certain you want it gone, destroy it and skip most of this. A guest that does not exist cannot restart itself and cannot page you.

Do these in order

Silence monitoring first. Then stop it. Do not do it the other way around or you page yourself during your own maintenance.

1. Silence monitoring, before you touch the guest

Schedule a downtime for the host. In Checkmk that is one API call, and it takes effect immediately with no activate-changes cycle:

curl -s -X POST \
  -H "Authorization: Bearer $USER $SECRET" \
  -H "Content-Type: application/json" \
  "http://$SERVER/$SITE/check_mk/api/1.0/domain-types/downtime/collections/host" \
  -d '{"downtime_type":"host",
       "host_name":"oldbox",
       "start_time":"2026-01-01T00:00:00Z",
       "end_time":"2027-01-01T00:00:00Z",
       "comment":"Retired on purpose. Expected DOWN, not an incident."}'

A host downtime covers that host's services too, so you do not need one per check.

Write the reason in the comment. Future you will find this host in a downtime list with no idea why.

BE WARNED: a scheduled downtime expires. Pick an end date and then actually put it somewhere you will see it. When it lapses you get an unexplained DOWN alert for a machine nobody remembers turning off. If the retirement is permanent, remove the host from monitoring instead of scheduling a very long downtime.

2. Turn off onboot

Set it with command pct set <VMID> --onboot 0 for a container, or qm set <VMID> --onboot 0 for a VM.

Miss this and the guest is back the next time the host reboots. Which will not be today, so you will have completely forgotten by then.

Check what it was first with command pct config <VMID> | grep onboot. Plenty of guests were built with onboot: 1 and nobody remembers setting it.

3. Deal with your watchdog

If you run something that restarts guests that should be running, it will undo everything above.

A well built watchdog uses onboot: 1 as its opt-in test. If yours does, step 2 already excluded this guest and you are finished. Prove it rather than assume it:

grep -qE '^onboot: *1' <(pct config <VMID>) \
  && echo "WOULD BE RESTARTED" \
  || echo "excluded"

BE WARNED: do not reach for the global hold file. Most watchdogs have a maintenance switch that pauses the whole thing. That is for a maintenance window, not for retiring one guest. Leave it on and you have silently disabled automatic recovery for every other guest you own, and nothing will tell you.

If your watchdog uses its own allow list instead, edit that list. The rule is the same either way. Exclude the one guest, never disable the watchdog.

4. Now stop it

pct shutdown <VMID> --timeout 60 || pct stop <VMID>
pct status <VMID>

Try the graceful shutdown first and fall back to the hard stop. A container with nothing left running shuts down in a second or two.

Leave the backup job alone

A stopped guest still backs up. vzdump handles it, and the backup is arguably more useful now than it was before, because it is the only copy of a thing nobody is maintaining.

Removing it from the backup job is how a retired guest becomes an unrecoverable one the day you decide you wanted it after all.

Write down why

Put one line somewhere permanent. What it was, when you retired it, and why.

A stopped guest with no explanation gets restarted by whoever finds it next, including you.

The five minute check

pct status <VMID>                          # stopped
pct config <VMID> | grep onboot            # onboot: 0
ls /etc/<watchdog>/hold                     # should NOT exist

Then look at your monitoring and confirm the host shows in downtime rather than critical.

When this isn't your problem

You are destroying the guest. Remove it from monitoring and from the backup job, then destroy it. No downtime needed for something that will not exist.
You have no watchdog. Skip step 3. Steps 1, 2 and 4 still apply.
The guest is in an HA group. Take it out of HA first. HA will restart it on another node and none of the above stops that.

The general lesson

Every layer you add to keep things running is a layer that fights you when you want something stopped. Autostart, watchdogs, HA and alerting are all doing their job when they drag a retired guest back up or page you about it. Turning a service off is not one action. It is one action per layer that has an opinion about whether it should be on.