skills(wordpress-plugin-conventions): merge security/lifecycle checks from wordpress/agent-skills
Per the 2026-08-15 skills.sh and autoskills.sh scans, both flagged wordpress/agent-skills' wp-plugin-development module (Automattic-origin, now WordPress-org-hosted) as high-value source material for iWP's plugin skill: nonce+capability dual-check discipline, late escaping, prepared SQL, cron idempotency, and uninstall-vs-deactivation guardrails. Adapted (not copied) against real iWP plugin code in wp-plugins/: - nonce+capability must-both framing, cited against class-iwp-cache-db-cleanup.php's actual AJAX handler - late-escaping and wp_unslash()/explicit-key superglobal reading - %i identifier-placeholder version gate (WP 6.2+, most iWP plugins floor at 6.0 or lower) - new "Admin settings" section documenting the real Settings-API vs. AJAX-dashboard split across the suite, since the source's generic Settings-API-first prescription doesn't match roughly half of iWP's plugins - new cron idempotency section citing the existing wp_next_scheduled() guard already used consistently in iwp-cache/iwp-woosales/iwp-booking - new uninstall-vs-deactivation section flagging that only 3 of ~15 plugins ship uninstall.php despite most creating options/tables - new release-packaging checklist tied to iWP's actual IWP_Updater version-wiring convention (header/constant/updater param must agree) Provenance noted inline with source URL. Left out the source's generic architecture/Settings-API prescription and its detect_plugins.mjs script (skill's house style is prose-only, no bundled scripts). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,213 @@
|
||||
---
|
||||
name: proxmox-admin
|
||||
description: Use when administering a Proxmox VE host or cluster via CLI (qm, pct, pvesm, pvecm, pveam, pvesh) — inspecting, creating, or mutating VMs, containers, storage, networking, or cluster state. Safety-first: read-only discovery and explicit target validation before any mutating command, a destructive-command tier list, and real gotchas from hands-on fleet use (reset-vs-reboot tradeoff, Tailscale hostname collisions, storage free-space checks).
|
||||
license: MIT
|
||||
source: adapted from https://github.com/bastos/skills/tree/main/proxmox-admin (MIT) — command taxonomy and CLI coverage — plus this fleet's own direct hands-on Proxmox operations across two hosts, which supplied the safety framing, the real gotchas below, and a correction to the source's quick-reference style (see "Why this skill differs from the source" at the bottom)
|
||||
---
|
||||
|
||||
# Proxmox VE Administration
|
||||
|
||||
Proxmox VE is a server virtualization platform built on Debian, managing
|
||||
KVM virtual machines (`qm`) and LXC containers (`pct`) plus storage
|
||||
(`pvesm`), clustering (`pvecm`), templates (`pveam`), and the API shell
|
||||
(`pvesh`). This skill covers CLI-based administration.
|
||||
|
||||
**Not for:** Web UI-only workflows (use the CLI equivalents below and in
|
||||
`references/command-reference.md`).
|
||||
|
||||
**Fleet-specific values (actual VMIDs, storage pool names, bridge/VLAN
|
||||
IDs, node names) live in this fleet's own `docs/server-*.md` files, not
|
||||
here.** Every command below uses a placeholder (`<vmid>`, `<node>`,
|
||||
`<storage>`, `<bridge>`) — resolve the real value from live discovery
|
||||
commands or fleet docs before running anything, never by guessing or
|
||||
reusing an example number from this file or from upstream documentation.
|
||||
|
||||
## SAFETY FIRST — the order every task follows
|
||||
|
||||
1. **Read-only discovery first, always.** Before touching a single VM or
|
||||
container, know what actually exists and what state it's in.
|
||||
2. **Validate the target explicitly.** Never assume a VMID, node name, or
|
||||
storage name is correct — confirm it via `qm config`/`pct config`/
|
||||
`qm list` immediately before acting on it, every time, even if you
|
||||
"already know" the ID from earlier in the conversation.
|
||||
3. **Know which tier a command is in before running it.** Destructive-tier
|
||||
commands (see below) should never run unattended — expect to be
|
||||
blocked by this environment's own permission classifier, and treat
|
||||
that as correct behavior to work *with*, not around.
|
||||
|
||||
## Read-only discovery commands (run these before anything else)
|
||||
|
||||
```bash
|
||||
qm list # all VMs on this node: ID, name, status
|
||||
qm config <vmid> # full config of one VM — confirm identity before acting
|
||||
qm status <vmid> # current run state
|
||||
|
||||
pct list # all containers on this node
|
||||
pct config <ctid> # full config of one container
|
||||
pct status <ctid>
|
||||
|
||||
pvesm status # storage pools: type, active, TOTAL/USED/AVAIL
|
||||
pvecm status # cluster quorum/membership (no-op, harmless, on single-node too)
|
||||
pvecm nodes # cluster node list
|
||||
|
||||
pvesh get /cluster/resources # everything, via the API shell — useful for cross-node views
|
||||
```
|
||||
|
||||
Run the relevant subset of these before every task in this skill, not
|
||||
just once at the start of a session — state changes, and a VMID that was
|
||||
stopped five minutes ago may be running now.
|
||||
|
||||
## Never trust a VMID or hostname without confirming it first
|
||||
|
||||
`qm list` gives you IDs and names; `qm config <vmid>` gives you the full
|
||||
picture (disks, storage backing, network, memory). **Always run `qm
|
||||
config <vmid>` (or `pct config <ctid>`) immediately before any mutating
|
||||
command against that ID**, even if the ID was already established earlier
|
||||
in the same task — configs can change between when you last checked and
|
||||
when you act, and a copy-pasted or misremembered ID silently targeting
|
||||
the wrong guest is a much worse failure mode than a few extra seconds of
|
||||
discovery.
|
||||
|
||||
## The Tailscale hostname-collision gotcha
|
||||
|
||||
**Confirmed real risk, hit twice in this session** across the `vulture`
|
||||
and `ginger` hosts: a bare Tailscale MagicDNS hostname (e.g. `ssh
|
||||
<hostname>`) can resolve to the **wrong physical host** if there's a
|
||||
stale or duplicate device name registered in the tailnet. This is
|
||||
dangerous specifically because it fails silently — the SSH connection
|
||||
succeeds, a shell prompt comes back, and everything looks normal; you
|
||||
just end up running Proxmox commands against a different host's guests
|
||||
than the one you meant.
|
||||
|
||||
**Before running any command against what you believe is a specific
|
||||
host** (and especially before anything in the destructive tier below),
|
||||
verify the connection actually went where you think:
|
||||
|
||||
```bash
|
||||
ssh -v <host> 2>&1 | grep "Connecting to"
|
||||
```
|
||||
|
||||
If a hostname's identity is ever in doubt, skip MagicDNS entirely and
|
||||
connect by the host's direct Tailscale IP instead — an IP can't collide
|
||||
the way a device name can.
|
||||
|
||||
## Snapshot vs. backup — know which one you need
|
||||
|
||||
These are not interchangeable, and confusing them is a common source of
|
||||
false confidence before a destructive operation:
|
||||
|
||||
- **Snapshot** (`qm snapshot`, `qm rollback`, `qm listsnapshot`,
|
||||
`qm delsnapshot`) — fast, live, stored *on the same storage backend* as
|
||||
the disk it snapshots. Good for "undo the last five minutes of change"
|
||||
during an upgrade or config edit. **Does not protect you if the
|
||||
underlying storage itself fails, fills up, or gets deleted** — the
|
||||
snapshot dies with it.
|
||||
- **Backup** (`vzdump`, restored via `qmrestore`/`pct restore`) — a full
|
||||
archive, ideally written to storage genuinely separate from the guest's
|
||||
own disk. Slower, but survives storage-level failure and is what you
|
||||
actually want before anything in the destructive tier below.
|
||||
|
||||
Rule of thumb: before any destructive-tier command, you want a **real
|
||||
backup on separate storage**, not just a same-storage snapshot. A
|
||||
snapshot is a convenience for reversible experiments, not a safety net
|
||||
for irreversible ones.
|
||||
|
||||
## Reset vs. reboot — the real tradeoff learned this session
|
||||
|
||||
- `qm reboot <vmid>` sends a graceful ACPI shutdown-then-restart request
|
||||
*into the guest*. If the guest is hung, has no ACPI daemon running, or
|
||||
is otherwise unresponsive, **this can hang or time out waiting
|
||||
indefinitely** — it depends entirely on the guest cooperating.
|
||||
- `qm reset <vmid>` is a hard reset — functionally identical to yanking
|
||||
power. It was used exactly once this session, deliberately, as the real
|
||||
fallback when `reboot` wasn't a safe option — but **only after first
|
||||
confirming the filesystems inside the guest were already cleanly
|
||||
unmounted**. A hard reset against a guest with dirty/mounted
|
||||
filesystems risks the same corruption a real power loss would.
|
||||
|
||||
**Do not reach for `reset` just because `reboot` seems slow.** Check what
|
||||
the guest is actually doing first — console (`qm monitor <vmid>`), guest
|
||||
agent (`qm agent <vmid> ping`), or a direct login — and only escalate to
|
||||
a hard reset once you've confirmed a clean-unmount state (or have
|
||||
independently decided the guest's disk state doesn't matter, e.g. it's
|
||||
about to be destroyed anyway).
|
||||
|
||||
## Storage checks before any disk-affecting operation
|
||||
|
||||
`pvesm status` reports both which storage pools exist **and** their
|
||||
free space (`TOTAL`/`USED`/`AVAIL` columns) — check both, not just
|
||||
"does the storage exist." This matters concretely for restores: this
|
||||
fleet's real VM disks run 200GB+, and a large `qmrestore` can fail
|
||||
partway through — or silently fill the target storage and start
|
||||
affecting other guests sharing it — if free space wasn't checked first.
|
||||
Confirm `pvesm status` shows enough headroom on the *target* storage
|
||||
before starting any restore, clone, or disk-resize operation, not just
|
||||
before the operation you're focused on.
|
||||
|
||||
## Destructive-command tier list — expect to be blocked, and that's correct
|
||||
|
||||
**This environment's own permission classifier already blocks
|
||||
`qmrestore` and other VM-creating/mutating commands, requiring explicit
|
||||
human confirmation before they run.** This is real, enforced behavior in
|
||||
this session's environment, not a hypothetical policy. Treat it as a
|
||||
guardrail to design around, not a friction to route past — if a
|
||||
destructive-tier command gets blocked, **stop, explain to the human
|
||||
exactly what the command would do and why it's in this tier, and let
|
||||
them decide.** Do not look for an equivalent path that avoids the
|
||||
prompt (a raw `pvesh` API call doing the same mutation, hand-editing
|
||||
`/etc/pve/qemu-server/<vmid>.conf` directly, chaining lower-privilege
|
||||
commands to reach the same end state) — that defeats the guardrail's
|
||||
purpose rather than satisfying it.
|
||||
|
||||
**Never run these without explicit human confirmation first:**
|
||||
|
||||
- Any `*destroy*`: `qm destroy`, `pct destroy` (with or without
|
||||
`--purge`) — deletes the guest and its disks, generally unrecoverable
|
||||
without a separate backup
|
||||
- Any restore that creates or overwrites a guest: `qmrestore`,
|
||||
`pct restore`
|
||||
- Any storage mutation: `pvesm add`, `pvesm remove`
|
||||
- Any cluster mutation: `pvecm create`, `pvecm add`, `pvecm delnode`,
|
||||
`pvecm expected` (force-quorum — a single-node recovery action with
|
||||
real risk of split-brain if used carelessly on a healthy cluster)
|
||||
- Any migration: `qm migrate`, `pct migrate` — moves a guest between
|
||||
nodes, can fail mid-flight, and affects a second node's state
|
||||
- `qm template <vmid>` — converting a VM to a template is irreversible
|
||||
- `qm reset <vmid>` — lower severity than destroy, but still surface it
|
||||
given the hang-vs-corruption tradeoff above; confirm clean-unmount
|
||||
status even where the environment doesn't hard-block it
|
||||
- Any bulk/loop pattern (batch-create N containers, batch-destroy,
|
||||
scripted mass reconfiguration) — higher risk than the single-target
|
||||
equivalent because the blast radius multiplies silently and a mid-loop
|
||||
failure can leave a mix of applied and unapplied state
|
||||
|
||||
**Generally fine to run directly** (read-only or narrowly-scoped,
|
||||
reversible): `qm list`/`config`/`status`, `pct list`/`config`/`status`,
|
||||
`pvesm status`, `pvecm status`/`nodes`, `pvesh get ...`, `qm agent <vmid>
|
||||
ping`/`get-osinfo`, `qm start`/`shutdown`/`stop` on a guest whose
|
||||
identity you've just confirmed, and snapshot creation (still confirm the
|
||||
target first — a snapshot against the wrong VMID is a wasted, confusing
|
||||
action even if not a destructive one).
|
||||
|
||||
## Full command reference
|
||||
|
||||
See `references/command-reference.md` for the complete `qm`/`pct`/
|
||||
`pvesm`/`pvecm`/`pveam`/backup/troubleshooting command tables, adapted
|
||||
from the upstream source with all example VMIDs, storage names, and
|
||||
bridge names replaced by placeholders.
|
||||
|
||||
## Why this skill differs from the source
|
||||
|
||||
The upstream `bastos/skills@proxmox-admin` skill this was adapted from is
|
||||
a solid 427-line command taxonomy, but it presents everything —
|
||||
including `qm destroy`, `pct destroy`, storage mutation, and cluster
|
||||
operations — in flat quick-reference style with no confirmation, target-
|
||||
validation, or backup guardrails, and its examples hardcode specific
|
||||
VMIDs/storage/bridge names as if they were universal defaults to copy.
|
||||
This version keeps the command coverage but restructures around what
|
||||
this session's actual hands-on Proxmox work across two hosts (`vulture`,
|
||||
`ginger`) surfaced as the real operating discipline: discovery before
|
||||
mutation, explicit target confirmation, a real destructive-tier list that
|
||||
matches this environment's own enforced permission classifier, and three
|
||||
gotchas (Tailscale hostname collisions, reset-vs-reboot, storage
|
||||
free-space checks) that cost real time or carried real risk this session.
|
||||
@@ -0,0 +1,356 @@
|
||||
# Proxmox CLI command reference
|
||||
|
||||
Full command coverage for `qm`, `pct`, `pvesm`, `pvecm`, `pveam`, backup/
|
||||
restore, networking, firewall, and troubleshooting. Adapted from
|
||||
`bastos/skills@proxmox-admin` (upstream source: see `SKILL.md`
|
||||
provenance note) with all example VMIDs, storage pool names, bridge
|
||||
names, and networks replaced by placeholders — **none of the values
|
||||
below are this fleet's real values.** Resolve real values from
|
||||
`docs/server-*.md` or from live discovery (`qm list`, `pvesm status`,
|
||||
etc.) before running anything.
|
||||
|
||||
Read `SKILL.md` first — it has the safety workflow and the destructive-
|
||||
command tier list this reference assumes you already know. Everything
|
||||
in a "never run without confirmation" tier there is repeated here only
|
||||
as reference syntax, not as something to execute unattended.
|
||||
|
||||
## Tool overview
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `qm` | Manage KVM virtual machines |
|
||||
| `pct` | Manage LXC containers |
|
||||
| `pvesm` | Manage storage |
|
||||
| `pvecm` | Manage cluster |
|
||||
| `pveam` | Manage appliance/template downloads |
|
||||
| `pvesh` | Access the Proxmox API from the shell |
|
||||
| `pveperf` | Benchmark host performance |
|
||||
|
||||
## VM management with `qm`
|
||||
|
||||
### Creating a VM (destructive tier: creates persistent state — confirm first)
|
||||
|
||||
```bash
|
||||
qm create <vmid> --name <vm-name> --memory 2048 --cores 2 --sockets 1 \
|
||||
--net0 virtio,bridge=<bridge> --ostype l26
|
||||
|
||||
# SCSI disk on a given storage pool
|
||||
qm create <vmid> --name <vm-name> --memory 4096 --cores 4 \
|
||||
--scsi0 <storage>:32 --scsihw virtio-scsi-pci \
|
||||
--net0 virtio,bridge=<bridge> --ostype l26
|
||||
|
||||
# Attach an ISO for installation
|
||||
qm set <vmid> --cdrom <storage>:iso/<image>.iso --boot order=ide2
|
||||
```
|
||||
|
||||
### VM lifecycle
|
||||
|
||||
| Command | Purpose | Tier |
|
||||
|---------|---------|------|
|
||||
| `qm start <vmid>` | Start a VM | generally fine once target confirmed |
|
||||
| `qm shutdown <vmid>` | Graceful ACPI shutdown | generally fine |
|
||||
| `qm stop <vmid>` | Force stop (like pulling power) | confirm first — no ACPI grace |
|
||||
| `qm reboot <vmid>` | Reboot (ACPI-graceful) | can hang if guest unresponsive — see SKILL.md |
|
||||
| `qm reset <vmid>` | Hard reset | confirm clean unmount first — see SKILL.md |
|
||||
| `qm suspend <vmid>` | Suspend to RAM | confirm first |
|
||||
| `qm resume <vmid>` | Resume from suspend | generally fine |
|
||||
| `qm destroy <vmid>` | Delete VM and its disks | **never without human confirmation** |
|
||||
| `qm destroy <vmid> --purge` | Delete VM, disks, and all related jobs | **never without human confirmation** |
|
||||
|
||||
### VM configuration
|
||||
|
||||
```bash
|
||||
qm config <vmid> # show current config — always run before qm set
|
||||
|
||||
qm set <vmid> --memory 8192
|
||||
qm set <vmid> --cores 4
|
||||
qm set <vmid> --balloon 2048 # dynamic memory (min)
|
||||
qm set <vmid> --cpu cputype=host # pass through host CPU features
|
||||
qm set <vmid> --machine q35 # Q35 chipset (needed for PCIe passthrough)
|
||||
|
||||
# Add/resize disks — check pvesm status for free space first
|
||||
qm set <vmid> --scsi1 <storage>:50 # add a 50GB disk
|
||||
qm disk resize <vmid> scsi0 +20G # grow an existing disk
|
||||
|
||||
# Networking — <bridge> and any VLAN tag are fleet-specific, resolve first
|
||||
qm set <vmid> --net0 virtio,bridge=<bridge>,tag=<vlan>
|
||||
qm set <vmid> --net1 virtio,bridge=<bridge2>
|
||||
|
||||
# Cloud-init
|
||||
qm set <vmid> --ide2 <storage>:cloudinit
|
||||
qm set <vmid> --ciuser <user> --cipassword '<generated-secret>'
|
||||
qm set <vmid> --ipconfig0 ip=<ip>/<cidr>,gw=<gateway>
|
||||
qm set <vmid> --sshkeys ~/.ssh/authorized_keys
|
||||
qm set <vmid> --boot order=scsi0
|
||||
|
||||
# EFI / UEFI boot
|
||||
qm set <vmid> --bios ovmf --efidisk0 <storage>:1,efitype=4m,pre-enrolled-keys=1
|
||||
|
||||
# Serial console (headless)
|
||||
qm set <vmid> --serial0 socket --vga serial0
|
||||
|
||||
# PCI passthrough
|
||||
qm set <vmid> --hostpci0 <pci-address>,pcie=1
|
||||
```
|
||||
|
||||
### Snapshots and cloning
|
||||
|
||||
See SKILL.md's "Snapshot vs. backup" section before relying on any of
|
||||
these as your only safety net.
|
||||
|
||||
```bash
|
||||
qm snapshot <vmid> <snapshot-name> --description "<why>"
|
||||
qm listsnapshot <vmid>
|
||||
qm rollback <vmid> <snapshot-name>
|
||||
qm delsnapshot <vmid> <snapshot-name>
|
||||
|
||||
qm clone <vmid> <new-vmid> --name <new-name> --full # full copy
|
||||
qm clone <vmid> <new-vmid> --name <new-name> # linked clone (shares base disk)
|
||||
```
|
||||
|
||||
### Templates
|
||||
|
||||
```bash
|
||||
qm template <vmid> # convert VM to template — IRREVERSIBLE, confirm first
|
||||
|
||||
qm clone <template-vmid> <new-vmid> --name <new-name> # linked clone from template
|
||||
qm clone <template-vmid> <new-vmid> --name <new-name> --full # full clone from template
|
||||
```
|
||||
|
||||
### Migration (confirm first — affects a second node)
|
||||
|
||||
```bash
|
||||
qm migrate <vmid> <target-node> --online # online (live) migration
|
||||
qm migrate <vmid> <target-node> # offline migration
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
```bash
|
||||
qm status <vmid>
|
||||
qm list
|
||||
|
||||
qm agent <vmid> ping
|
||||
qm agent <vmid> get-osinfo
|
||||
|
||||
qm monitor <vmid> # QEMU monitor console
|
||||
```
|
||||
|
||||
## Container management with `pct`
|
||||
|
||||
### Creating a container (destructive tier — confirm first)
|
||||
|
||||
```bash
|
||||
# Download a template first
|
||||
pveam update
|
||||
pveam available --section system
|
||||
pveam download <storage> <template-filename>
|
||||
|
||||
pct create <ctid> <storage>:vztmpl/<template-filename> \
|
||||
--hostname <ct-name> --memory 1024 --cores 2 \
|
||||
--rootfs <storage>:8 \
|
||||
--net0 name=eth0,bridge=<bridge>,ip=dhcp \
|
||||
--password '<generated-secret>' --unprivileged 1
|
||||
|
||||
# Static IP variant
|
||||
pct create <ctid> <storage>:vztmpl/<template-filename> \
|
||||
--hostname <ct-name> --memory 2048 --cores 2 \
|
||||
--rootfs <storage>:16 \
|
||||
--net0 name=eth0,bridge=<bridge>,ip=<ip>/<cidr>,gw=<gateway> \
|
||||
--nameserver <dns-ip> --unprivileged 1
|
||||
```
|
||||
|
||||
### Container lifecycle
|
||||
|
||||
| Command | Purpose | Tier |
|
||||
|---------|---------|------|
|
||||
| `pct start <ctid>` | Start container | generally fine once target confirmed |
|
||||
| `pct shutdown <ctid>` | Graceful shutdown | generally fine |
|
||||
| `pct stop <ctid>` | Force stop | confirm first |
|
||||
| `pct reboot <ctid>` | Reboot container | same ACPI-hang caveat as `qm reboot` |
|
||||
| `pct destroy <ctid>` | Delete container and its volumes | **never without human confirmation** |
|
||||
| `pct enter <ctid>` | Open a shell inside the container | generally fine |
|
||||
| `pct exec <ctid> -- <cmd>` | Run a command inside the container | depends what `<cmd>` does |
|
||||
| `pct console <ctid>` | Attach to container console | generally fine |
|
||||
|
||||
### Container configuration
|
||||
|
||||
```bash
|
||||
pct config <ctid> # always run before pct set
|
||||
|
||||
pct set <ctid> --memory 4096
|
||||
pct set <ctid> --cores 4
|
||||
pct set <ctid> --swap 1024
|
||||
|
||||
pct set <ctid> --mp0 /mnt/data,mp=/data # bind mount from host
|
||||
pct set <ctid> --mp1 <storage>:50,mp=/var/lib/data # additional storage volume
|
||||
|
||||
pct set <ctid> --net0 name=eth0,bridge=<bridge>,ip=<ip>/<cidr>,gw=<gateway>
|
||||
pct set <ctid> --net1 name=eth1,bridge=<bridge2>,ip=dhcp
|
||||
|
||||
pct set <ctid> --features nesting=1
|
||||
pct set <ctid> --features nesting=1,fuse=1,mount=nfs
|
||||
|
||||
pct set <ctid> --nameserver "<dns-ip-1> <dns-ip-2>" --searchdomain <domain>
|
||||
|
||||
pct set <ctid> --onboot 1 --startup order=1,up=30
|
||||
```
|
||||
|
||||
### Container snapshots and cloning
|
||||
|
||||
```bash
|
||||
pct snapshot <ctid> <snapshot-name>
|
||||
pct rollback <ctid> <snapshot-name>
|
||||
pct clone <ctid> <new-ctid> --hostname <new-name> --full
|
||||
```
|
||||
|
||||
## Storage management
|
||||
|
||||
```bash
|
||||
pvesm status # list pools + free space — check before any restore/resize
|
||||
|
||||
pvesm list <storage> # content of a specific storage pool
|
||||
|
||||
# Adding storage is a cluster-wide config mutation — confirm first
|
||||
pvesm add dir <name> --path <path> --content backup
|
||||
pvesm add nfs <name> --server <nfs-server-ip> --export <export-path> --content images,vztmpl
|
||||
pvesm add lvm <name> --vgname <vg-name> --content rootdir,images
|
||||
pvesm add zfspool <name> --pool <zfs-pool>/<dataset> --content rootdir,images
|
||||
|
||||
pvesm remove <name> # never without human confirmation
|
||||
|
||||
wget -P /var/lib/vz/template/iso/ <iso-url>
|
||||
```
|
||||
|
||||
## Networking
|
||||
|
||||
```bash
|
||||
cat /etc/network/interfaces # current bridge/interface config — read first
|
||||
|
||||
# Bridge stanza shape (values are placeholders, not this fleet's real config)
|
||||
# auto <bridge>
|
||||
# iface <bridge> inet static
|
||||
# address <host-ip>/<cidr>
|
||||
# bridge-ports <physical-nic>
|
||||
# bridge-stp off
|
||||
# bridge-fd 0
|
||||
|
||||
ifreload -a # apply network changes — can drop connectivity if misconfigured, confirm first
|
||||
```
|
||||
|
||||
## Cluster management (all tiers below: confirm first — affects multiple nodes)
|
||||
|
||||
```bash
|
||||
pvecm create <cluster-name>
|
||||
pvecm add <existing-cluster-node-ip>
|
||||
pvecm status
|
||||
pvecm nodes
|
||||
pvecm delnode <node-name>
|
||||
pvecm expected 1 # force quorum — single-node recovery only, real split-brain risk otherwise
|
||||
```
|
||||
|
||||
## Firewall
|
||||
|
||||
```bash
|
||||
pve-firewall start
|
||||
pve-firewall stop
|
||||
pve-firewall status
|
||||
|
||||
# Datacenter: /etc/pve/firewall/cluster.fw ([OPTIONS] enable: 1)
|
||||
# Node: /etc/pve/nodes/<node>/host.fw
|
||||
# VM/CT: /etc/pve/firewall/<vmid>.fw
|
||||
#
|
||||
# Add remote-management allow rules BEFORE enabling a restrictive default
|
||||
# policy — locking yourself out of remote access to the node is a real,
|
||||
# hard-to-recover-from failure mode.
|
||||
```
|
||||
|
||||
## Backup and restore
|
||||
|
||||
```bash
|
||||
vzdump <vmid> --storage <backup-storage> --mode snapshot --compress zstd
|
||||
vzdump <ctid> --storage <backup-storage> --mode stop --compress zstd
|
||||
vzdump --all --storage <backup-storage> --mode snapshot --compress zstd --mailto <admin-email>
|
||||
|
||||
# Restore — never without human confirmation (creates/overwrites a guest).
|
||||
# Check pvesm status for target free space FIRST, especially for large disks.
|
||||
qmrestore <path-to-vzdump-file> <vmid> --storage <storage>
|
||||
pct restore <ctid> <path-to-vzdump-file>
|
||||
```
|
||||
|
||||
## Common provisioning patterns (reference only — each step still follows the tier rules above)
|
||||
|
||||
### Cloud-init VM from a template
|
||||
|
||||
```bash
|
||||
qm template <base-vmid> # irreversible — confirm first
|
||||
|
||||
qm clone <base-vmid> <new-vmid> --name <new-name> --full
|
||||
qm set <new-vmid> --ciuser <user> --sshkeys ~/.ssh/authorized_keys
|
||||
qm set <new-vmid> --ipconfig0 ip=<ip>/<cidr>,gw=<gateway>
|
||||
qm set <new-vmid> --nameserver <dns-ip>
|
||||
qm start <new-vmid>
|
||||
```
|
||||
|
||||
Note: some Proxmox documentation and community examples use VMIDs like
|
||||
`9000` as a convention for template base images. That's a naming
|
||||
convention some operators adopt, not a Proxmox default or a value to
|
||||
copy into this fleet — check `docs/server-*.md` for whatever convention
|
||||
(if any) applies to a given host before picking an ID.
|
||||
|
||||
### Batch-create containers
|
||||
|
||||
Bulk/loop patterns are explicitly a higher tier than the single-target
|
||||
equivalent (see SKILL.md) — pilot one iteration manually, confirm it's
|
||||
correct, before running the loop.
|
||||
|
||||
```bash
|
||||
for i in $(seq 1 <count>); do
|
||||
CTID=$((<base-ctid> + i))
|
||||
pct create "$CTID" <storage>:vztmpl/<template-filename> \
|
||||
--hostname "<name-prefix>-${i}" --memory 1024 --cores 2 \
|
||||
--rootfs <storage>:8 \
|
||||
--net0 name=eth0,bridge=<bridge>,ip=<ip-prefix>.$((<ip-offset> + i))/<cidr>,gw=<gateway> \
|
||||
--unprivileged 1 --start 1
|
||||
done
|
||||
```
|
||||
|
||||
### Import a disk image (e.g. a cloud image)
|
||||
|
||||
```bash
|
||||
wget <cloud-image-url>
|
||||
|
||||
qm disk import <vmid> <downloaded-image-file> <storage>
|
||||
qm set <vmid> --scsi0 <storage>:vm-<vmid>-disk-0
|
||||
qm set <vmid> --boot order=scsi0
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| VM won't start | `qm config <vmid>`, verify storage exists with `pvesm status` |
|
||||
| "TASK ERROR: can't lock file" | Check for a genuinely running task first; if the task is gone, `qm unlock <vmid>` / `pct unlock <ctid>` |
|
||||
| Container has no network | Check bridge exists: `brctl show`; verify firewall rules |
|
||||
| Disk full on storage | `pvesm status` for usage; `lvs` for LVM thin pools |
|
||||
| Cluster quorum lost | `pvecm expected 1` on a surviving node — single-node recovery only, confirm first |
|
||||
| Migration fails | Check CPU type compatibility; confirm network reachability between nodes |
|
||||
| Backup fails with lock error | `qm unlock <vmid>` / `pct unlock <ctid>` |
|
||||
| Slow disk I/O in VM | `--scsihw virtio-scsi-single` plus disk options like `,iothread=1,discard=on` |
|
||||
| Guest agent not responding | Install `qemu-guest-agent` in the guest, then `qm set <vmid> --agent 1` |
|
||||
| SSH/command seems to hit the wrong host | See SKILL.md's Tailscale hostname-collision gotcha — verify with `ssh -v <host> 2>&1 \| grep "Connecting to"` |
|
||||
|
||||
## Useful paths
|
||||
|
||||
| Path | Contents |
|
||||
|------|----------|
|
||||
| `/etc/pve/` | Cluster-wide config (pmxcfs) |
|
||||
| `/etc/pve/qemu-server/<vmid>.conf` | VM configuration files |
|
||||
| `/etc/pve/lxc/<ctid>.conf` | Container configuration files |
|
||||
| `/etc/pve/storage.cfg` | Storage definitions |
|
||||
| `/etc/pve/nodes/` | Per-node configuration |
|
||||
| `/var/lib/vz/` | Default local storage root |
|
||||
| `/var/lib/vz/template/iso/` | ISO images |
|
||||
| `/var/lib/vz/template/cache/` | Container templates |
|
||||
| `/var/lib/vz/dump/` | Backup files |
|
||||
| `/var/log/pve/tasks/` | Task logs |
|
||||
Reference in New Issue
Block a user