# PGS

`pve-guests-state` este utilitarul manual pentru suspendarea si restaurarea guest-urilor Proxmox inainte si dupa lucrari de mentenanta.

Modelul suportat este deliberat simplu:

- `pgs suspend` se ruleaza manual inainte de mentenanta

- `pgs resume` se ruleaza manual dupa revenirea stabila a clusterului

- `pgs cleanup` poate fi rulat manual pentru audit sau cleanup al artefactelor stale de suspend

Automatizarea prin systemd pentru shutdown si boot a fost abandonata intentionat. Contextul complet este in [docs/DECISIONS.md](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/docs/DECISIONS.md).

## Capabilitati

- suspend to disk pentru VM-uri QEMU care ruleaza

- graceful shutdown pentru containere LXC care ruleaza

- resume pentru VM-urile salvate in state

- start pentru containerele salvate in state

- cleanup pentru stale suspend images

- cleanup pentru volume orphan `vm-*-state-suspend-YYYY-MM-DD.raw`

- retry pentru anumite erori legate de quorum

- dry-run pentru verificare fara efecte

## Layout proiect

- [bin/pgs](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/bin/pgs) - comanda principala

- [scripts/install.sh](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/scripts/install.sh) - instalare locala pe host

- [scripts/uninstall.sh](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/scripts/uninstall.sh) - uninstall canonic

- [setup.sh](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/setup.sh) - wrapper local/remote

- [docs/TECHNICAL.md](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/docs/TECHNICAL.md) - detalii tehnice

- [systemd/README.md](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/systemd/README.md) - statusul unitatilor legacy

## Locatii instalate pe host

- comanda operatorului: `/usr/local/sbin/pgs`

- uninstall canonic: `/usr/local/lib/xdev/pve-guests-state/uninstall.sh`

- wrapper optional pentru uninstall: `/usr/local/sbin/xdev-pve-guests-state-uninstall`

- documentatie instalata: `/usr/local/share/doc/xdev/pve-guests-state`

- state runtime: `/var/lib/xdev/pve-guests-state/pgs-state.json`

Compatibilitate:

- la primul run, daca exista vechiul state file `/var/lib/pve-manager/pgs-state.json`, acesta este migrat automat in locatia noua

- installerul si uninstallerul curata si artefactele istorice `pve-reboot-manager.sh` si `pve-guest-state.sh`

## Flux rapid

```bash

# instalare locala

sudo ./setup.sh --local

# test

/usr/local/sbin/pgs suspend --dry-run -v

/usr/local/sbin/pgs cleanup --dry-run -v

# suspend inainte de mentenanta

/usr/local/sbin/pgs suspend -v

# resume dupa revenirea clusterului

/usr/local/sbin/pgs resume -v

# cleanup manual al artefactelor stale/orphan

/usr/local/sbin/pgs cleanup -v

```

## Instalare si uninstall

Instalare:

```bash

sudo ./setup.sh --local

sudo ./setup.sh <node>

```

Uninstall:

```bash

sudo ./setup.sh --local --uninstall

sudo ./setup.sh --uninstall <node>

```

Sau direct pe host:

```bash

sudo /usr/local/lib/xdev/pve-guests-state/uninstall.sh

```

## Observatii operationale

- proiectul nu instaleaza configuratie persistenta proprie in `/etc`

- proiectul nu instaleaza unitati systemd active; cele vechi sunt doar artefacte istorice si sunt eliminate la install/uninstall

- dupa un `resume` complet reusit, state file-ul este sters

- daca `resume` are erori, state file-ul este pastrat pentru retry

- `cleanup` si preflight-ul din `suspend` ating doar fisiere `vm-*-state-suspend-YYYY-MM-DD.raw`; fisiere `vm-*-state-cp*.raw` sau alte variante raman neatinse

- state file-ul retine si `suspend_volume`/`suspend_file_date` per VM pentru a detecta guest-uri alterate dupa salvarea state-ului

## Debug rapid

```bash

journalctl -t pgs -n 50

cat /var/lib/xdev/pve-guests-state/pgs-state.json

```