Команды CLI в Proxmox VE: шпаргалка системного администратора

Веб-интерфейс Proxmox VE (PVE) удобен, но ровно до того момента, пока узел не потерял сеть, кластерная файловая система pmxcfs не перешла в read-only из-за потери кворума, а виртуальная машина с критичной БД не зависла намертво на этапе I/O блокировки. В таких ситуациях графический интерфейс либо не отвечает, либо выдает таймауты.

Ниже собрана подробная шпаргалка по утилитам командной строки PVE (qm, pct, pvesm, pvecm, ha-manager), реальным сценариям траблшутинга и скрытым трюкам, которые экономят часы при сбоях.

1. Архитектура CLI в Proxmox VE: базовый инструментарий

Proxmox разделяет управление разными уровнями виртуализации на отдельные специализированные бинарники:

• qm (Qemu/KVM Virtual Machine Manager) — управление полновесными виртуальными машинами.
• pct (Proxmox Container Toolkit) — управление LXC-контейнерами.
• pvesm (Proxmox VE Storage Manager) — дисковые пулы, LVM, ZFS, NFS, Ceph.
• pvecm (Proxmox VE Cluster Manager) — состояние Corosync, узлы, кворум.
• pveum (Proxmox VE User Management) — пользователи, токены API, ACL.
• ha-manager — управление подсистемой High Availability.

Конфигурационные файлы хранятся в специальной распределенной FUSE-файловой системе pmxcfs, смонтированной в /etc/pve/:

• /etc/pve/qemu-server/<VMID>.conf — конфигурации ВМ.
• /etc/pve/lxc/<CTID>.conf — конфигурации контейнеров.
• /etc/pve/storage.cfg — конфигурация хранилищ.
• /etc/pve/corosync.conf — параметры кластера.

2. Управление KVM (qm)

Повседневные операции

# Список всех ВМ на узле (включая статус, PID процесса KVM и выделенную память)
qm list
# Запуск, мягкая остановка и принудительный стоп
qm start 100
qm shutdown 100 --timeout 60
qm stop 100
# Перезагрузка и пауза (сохранение состояния в RAM)
qm reboot 100
qm suspend 100
qm resume 100
# Доступ к текстовой консоли без GUI (требуется настроенный serial console в госте)
qm terminal 100

Модификация “на лету” и работа с дисками

# Добавить RAM (если включен Memory Ballooning / Hotplug)
qm set 100 -memory 8192
# Изменить количество vCPU без перезагрузки (при активном CPU Hotplug)
qm set 100 -cores 4
# Проброс USB-устройства на лету (например, токена или флешки)
qm set 100 -usb0 host=10c4:ea60
# Изменение размера виртуального диска (например, virtio0 на +20 ГБ)
qm resize 100 virtio0 +20G
# Перемещение диска между хранилищами без остановки ВМ (онлайн-миграция диска)
qm move-disk 100 virtio0 local-zfs --delete 1

3. Управление LXC-контейнерами (pct)

Контейнеры запускаются через ядро хоста, поэтому команды выполняются быстрее и предоставляют прямой доступ внутрь окружения.

Основные команды

# Список всех контейнеров
pct list
# Запуск, штатная остановка и жесткий kill
pct start 200
pct shutdown 200 --forceStop 0
pct stop 200
# Вход в контейнер напрямую (root-shell без пароля и без запущенного sshd)
pct enter 200
# Выполнение одиночной команды внутри LXC без интерактивного входа
pct exec 200 -- df -h
pct exec 200 -- systemctl restart nginx

Монтирование и правка диска выключенного контейнера

Если контейнер сломался (например, упал systemd или испорчен /etc/fstab), его диск можно смонтировать прямо в файловую систему гипервизора:

# Монтирует диск контейнера в точку монтирования на хосте
pct mount 200
# Вывод покажет путь вида: /var/lib/lxc/200/rootfs
# Теперь можно исправить ошибки в файлах
nano /var/lib/lxc/200/rootfs/etc/fstab
# Размонтировать после завершения правок
pct unmount 200

4. Экстренный траблшутинг: когда ВМ или LXC намертво зависли

Классическая проблема: нажатие кнопки Stop в Web GUI приводит к бесконечному таймауту TASK ERROR: can’t lock file ‘/var/lock/qemu-server/lock-100.conf’ – got timeout.

Сценарий 1: Зависла KVM-машина

Шаг 1. Снять лок

Если веб-интерфейс заблокировал конфигурацию, принудительно снимаем флаг блокировки:

qm unlock 100

Шаг 2. Завершить через команду монитора QEMU

Если QEMU еще слушает сокет управления:

qm monitor 100
# Внутри монитора:
quit

Шаг 3. Жесткий расстрел процесса на уровне ядра

Если ВМ ушла в неперебиваемый сон (D-state) из-за проблем со стораджем (NFS/iSCSI) или переполнилась память:

# Находим PID процесса KVM
cat /var/run/qemu-server/100.pid
# Либо через pgrep
pgrep -f "kvm.*-id 100\b"
# Шлем SIGTERM, а затем SIGKILL
kill -9 $(cat /var/run/qemu-server/100.pid)
# Удаляем файл pid и сокет вручную, если процесс умер, но мусор остался
rm -f /var/run/qemu-server/100.pid
rm -f /var/run/qemu-server/100.qmp
qm unlock 100

Сценарий 2: Завис LXC-контейнер

Если контейнер не останавливается:

# Снять лок
pct unlock 200
# Принудительная остановка через штатный бинарник
pct stop 200 --kill 1
# Если не помогло, ищем пространство имен контейнера:
lxc-stop -n 200 -k
# Поиск процессов, застрявших внутри cgroup контейнера:
cat /sys/fs/cgroup/lxc/200/cgroup.procs | xargs -r kill -9
# Если не помогает, ищем PID основного процесса контейнера
pgrep -f "lxc-start.*200"
# Принудительное завершение найденного процесса
pkill -9 -f "lxc-start.*200"
# Финальное снятие лока
pct unlock 200

5. Кластер, кворум и Corosync: спасение Split-Brain

В кластере Proxmox вся конфигурация (/etc/pve) синхронизируется через Corosync. Если падает больше половины нод (или изолируется сеть), кластер теряет кворум. Файловая система /etc/pve монтируется в режиме Read-Only: нельзя запустить ВМ, отредактировать конфиг или выполнить миграцию.

# Проверка состояния кластера и кворума
pvecm status

Аварийное понижение кворума (Expected Votes)

Если из 3 нод жива осталась только 1, кворум потерян (Quorate: No). Чтобы вернуть узел в рабочий режим и разрешить запись в /etc/pve:

# Устанавливаем требуемое количество голосов в 1
pvecm expected 1

После этого pvecm status покажет Quorate: Yes, и нода снова сможет управлять своими ВМ.

Как корректно вывести сгоревшую ноду из кластера

Внимание: никогда не удаляйте ноду, пока она включена и видит сеть, иначе Corosync сломает конфигурацию.

# 1. Обесточьте удаляемую ноду навсегда (node-02).
# 2. На живой ноде выполните:
pvecm nodes
# 3. Удалите ноду из состава кластера:
pvecm delnode pve-node-02
# 4. Если папка ноды осталась в файловой системе кластера:
rm -rf /etc/pve/nodes/pve-node-02

Перенос конфигурации ВМ с мертвой ноды

Если узел сгорел, а его диски находились на общем хранилище (Ceph / NFS / ZFS over iSCSI), виртуальную машину можно поднять на живом узле за 5 секунд:

# Конфигурации всех узлов доступны в общем дереве /etc/pve/nodes/
mv /etc/pve/nodes/dead-node/qemu-server/100.conf /etc/pve/nodes/alive-node/qemu-server/
qm start 100

6. Диски, хранилища и LVM/ZFS (pvesm)

Утилита pvesm

# Статус всех подключенных хранилищ
pvesm status

# Список всех образов дисков в конкретном хранилище
pvesm list local-zfs

# Ручное удаление дискового тома (если GUI отказывает из-за несуществующего VMID)
pvesm free local-zfs:vm-100-disk-0

# Сканирование удаленного NFS/SMB ресурса
pvesm scan nfs 192.168.1.50

Импорт внешних образов в Proxmox (QCOW2, RAW, VMDK)

Частая задача — перенос виртуальной машины из AWS, OpenStack или VMware:

# 1. Создаем пустую ВМ без диска
qm create 300 --name imported-vm --memory 4096 --net0 virtio,bridge=vmbr0
# 2. Импортируем диск из файла (qcow2, vmdk, raw) в нужное хранилище
qm importdisk 300 /root/backup-image.qcow2 local-zfs
# 3. После импорта диск появится в статусе 'Unused'. Подключаем его:
qm set 300 --virtio0 local-zfs:vm-300-disk-0
# 4. Устанавливаем порядок загрузки
qm set 300 --boot order=virtio0

7. Бэкапы и восстановление (vzdump / qmrestore)

Создание бэкапа из CLI дает полный контроль над компрессией, нагрузкой на I/O и исключениями.

# Создание снепшота-бэкапа на лету со сжатием ZSTD
vzdump 100 --mode snapshot --compress zstd --storage pbs-storage

# Бэкап нескольких машин с ограничением скорости (bwlimit в КБ/с), чтобы не положить продакшен
vzdump 100,101,102 --mode snapshot --compress zstd --bwlimit 50000 --dumpdir /mnt/backup/

# Восстановление KVM из архива
qmrestore /mnt/backup/vzdump-qemu-100.vma.zst 100 --storage local-zfs

# Восстановление LXC из архива
pctrestore 200 /mnt/backup/vzdump-lxc-200.tar.zst --storage local-zfs

8. Секреты, трюки и полезные однострочники

Быстрый шаблон из любого Cloud-Init образа

Создание готового шаблона Ubuntu Cloud-Init занимает 4 команды:

wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
qm create 9000 --name "ubuntu-2204-template" --memory 2048 --cores 2 --net0 virtio,bridge=vmbr0
qm importdisk 9000 jammy-server-cloudimg-amd64.img local-zfs
qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-zfs:vm-9000-disk-0
qm set 9000 --ide2 local-zfs:cloudinit --boot c --bootdisk scsi0 --serial0 socket --vga serial0
qm template 9000

Отключение Nag-окна о подписке (No-Subscription Banner)

Чтобы окно «No valid subscription» не выскакивало при каждом входе в админку:

sed -Ezi.bak "s/(Ext.Msg.show\(\{\s+title: gettext\('No valid sub)/void\(\{ \/\/\1/g" /usr/share/javascript/proxmox-widget-toolkit/proxmoxlib.js
systemctl restart pveproxy.service

Сброс зависшей задачи (Task Lock)

Если задача в фоновом режиме повисла, а кнопки Stop/Abort не помогают:

# Список активных задач
ls -la /var/log/pve/tasks/active

# Чтобы остановить задачу, найдите процесс worker и завершите его:
ps aux | grep task

Сводная таблица ключевых команд

Ситуация / Задача	Команда
Снять зависший лок с ВМ	qm unlock <VMID>
Снять зависший лок с LXC	pct unlock <CTID>
Убить зависший KVM-процесс	kill -9 $(cat /var/run/qemu-server/<VMID>.pid)
Аварийный кворум при падении нод	pvecm expected 1
Войти в шелл LXC без сети и SSH	pct enter <CTID>
Монтировать диск контейнера на хост	pct mount <CTID>
Импортировать диск VMDK/QCOW2 в ВМ	qm importdisk <VMID> <FILE> <STORAGE>
Увеличить диск ВМ на 10 ГБ	qm resize <VMID> <DISK> +10G
Восстановить ВМ из бэкапа	qmrestore <BACKUP_PATH> <VMID>
Посмотреть распределение памяти	pvesm status / pveversion -v

Избранное