Proxmox Manager (TimInTech) – co to jest, jak działa, instalacja i obsługa

1. Czym jest Proxmox Manager?

Proxmox Manager to lekkie, jednoplikowe narzędzie napisane w języku Bash, które służy do zarządzania maszynami wirtualnymi (VM) i kontenerami LXC działającymi na platformie Proxmox VE. Projekt powstał z myślą o administratorach serwerów, którzy chcą szybko i wygodnie obsługiwać swoją infrastrukturę wirtualizacyjną bezpośrednio z wiersza poleceń — bez potrzeby otwierania przeglądarki i logowania do panelu webowego.

 

 

Narzędzie działa jako interaktywny interfejs TUI (Text User Interface) — czyli tekstowy interfejs użytkownika — wyświetlający tabelę ze wszystkimi maszynami wirtualnymi i kontenerami na hoście Proxmox. Dzięki prostocie architektury (jeden plik .sh) instalacja jest błyskawiczna, a obsługa nie wymaga znajomości skomplikowanych komend.

Proxmox Manager jest dostępny na licencji MIT i jest w pełni darmowy. Projekt ma 24 gwiazdki na GitHub i aktywnie jest rozwijany — najnowsza wersja to v2.7.2 z września 2025 roku.

2. Co robi Proxmox Manager?

Proxmox Manager opakowuje natywne narzędzia CLI platformy Proxmox (qm dla maszyn wirtualnych i pct dla kontenerów) w przejrzysty, interaktywny interfejs. Poniżej opisano wszystkie główne funkcje narzędzia.

2.1 Wyświetlanie listy maszyn i kontenerów

Po uruchomieniu narzędzie automatycznie pobiera listę wszystkich maszyn wirtualnych i kontenerów LXC na lokalnym węźle Proxmox. Każda pozycja jest wyświetlana z następującymi informacjami: identyfikatorem VMID, typą (VM lub CT), nazwą oraz aktualnym statusem. Status jest wizualnie oznaczony symbolami:

• [+] — maszyna/kontener działa (running)
• [-] — maszyna/kontener zatrzymana (stopped)
• [~] — maszyna/kontener wstrzymana (paused)
• [?] — status nieznany

2.2 Zarządzanie stanem maszyn

Po wybraniu maszyny z listy (wpisując jej VMID) otwiera się menu akcji. Dostępne opcje to uruchomienie (start), zatrzymanie (stop) oraz restart. Dla destruktywnych akcji takich jak stop i restart narzędzie wymaga potwierdzenia przed wykonaniem operacji, co zabezpiecza przed przypadkowym wyłączeniem produkcyjnej maszyny. W razie błędu wyświetlane są szczegóły komunikatu błędu z Proxmox, co ułatwia diagnostykę.

2.3 Dostęp do konsoli

Proxmox Manager umożliwia bezpośrednie wejście do konsoli wybranej maszyny lub kontenera. W przypadku kontenerów LXC jest to powłoka systemowa (shell), natomiast dla maszyn wirtualnych QEMU — terminal tekstowy. Przed wejściem do konsoli kontenera narzędzie automatycznie sprawdza, czy kontener jest uruchomiony.

2.4 Zarządzanie snapshotami

Jedną z najważniejszych funkcji Proxmox Managera jest kompleksowe zarządzanie snapshotami. Dostępne operacje to listowanie istniejących snapshotów, tworzenie nowego snapshota, przywracanie do wybranego snapshota (rollback) oraz usuwanie snapshota. Przed wykonaniem rollbacku i usunięcia narzędzie wyświetla listę istniejących snapshotów, a format nazwy snapshota jest walidowany przed wywołaniem komendy Proxmox.

2.5 Integracja SPICE

Dla maszyn wirtualnych dostępna jest integracja z protokołem SPICE, umożliwiającym zdalny dostęp do graficznego interfejsu VM. Narzędzie pozwala włączyć SPICE oraz pobrać dane do połączenia. Domyślny adres bind to 127.0.0.1, który można nadpisać zmienną środowiskową PROXMOX_MANAGER_SPICE_ADDR.

2.6 Wyjście w formacie JSON i tekstowym

Proxmox Manager obsługuje tryb maszynowy, co czyni go użytecznym w skryptach i automatyzacji. Flaga –json zwraca dane o wszystkich maszynach i kontenerach w formie tablicy JSON, gotowej do parsowania narzędziami takimi jak jq. Tryb –list wyświetla sformatowaną tabelę tekstową przydatną do logowania lub szybkiego podglądu.

3. Jak działa Proxmox Manager?

Proxmox Manager jest napisany jako pojedynczy skrypt Bash (proxmox-manager.sh), który bezpośrednio wywołuje natywne narzędzia CLI platformy Proxmox: qm do zarządzania maszynami wirtualnymi oraz pct do zarządzania kontenerami LXC. Nie wymaga żadnych zewnętrznych zależności poza tym, co jest dostarczane razem z Proxmox VE.

Architektura narzędzia jest celowo prosta — skrypt nie działa jako demon w tle, nie wymaga agentów ani dodatkowych serwerów. Uruchamiany jest na żądanie, wykonuje żądaną operację i kończy działanie. Dzięki temu nie obciąża systemu i nie wprowadza dodatkowych wektorów ataku.

Komponent	Opis
proxmox-manager.sh	Główny skrypt — cała logika narzędzia w jednym pliku
install_dependencies.sh	Opcjonalny skrypt instalujący zależności i rejestrujący alias pman
qm	Narzędzie CLI Proxmox do zarządzania maszynami wirtualnymi (VM)
pct	Narzędzie CLI Proxmox do zarządzania kontenerami LXC (CT)
tests/run.sh	Zestaw 8 testów działających na zaślepkach (mock-bin) — bez prawdziwego Proxmox

4. Wymagania systemowe

Proxmox Manager jest narzędziem przeznaczonym wyłącznie dla platformy Proxmox VE. Musi być uruchamiany bezpośrednio na hoście Proxmox — nie działa zdalnie przez SSH w standardowej konfiguracji.

4.1 System operacyjny

• Proxmox VE w wersji 7.x, 8.x lub 9.x
• Bash w wersji 4.0 lub nowszej (dostarczany z Proxmox)
• Uprawnienia root (lub ustawiona zmienna PROXMOX_MANAGER_ALLOW_NONROOT=1 dla celów CI)

4.2 Narzędzia CLI (dostarczone z Proxmox)

• qm — zarządzanie maszynami wirtualnymi
• pct — zarządzanie kontenerami LXC
• Standardowe narzędzia POSIX: awk, sed, grep

Ważne: Proxmox Manager nie wymaga Pythona, Dockera ani żadnych zewnętrznych API. Wszystkie operacje są wykonywane lokalnie na węźle Proxmox.

5. Instalacja krok po kroku

5.1 Klonowanie repozytorium

Zaloguj się na host Proxmox przez SSH lub konsolę i wykonaj poniższe polecenia:

git clone https://github.com/TimInTech/proxmox-manager.git

cd proxmox-manager

chmod +x proxmox-manager.sh

Na tym etapie narzędzie jest już gotowe do użycia. Nie jest wymagany żaden krok kompilacji ani budowania.

5.2 Instalacja opcjonalna (polecana)

Aby zainstalować opcjonalne zależności i zarejestrować komendę pman jako globalną komendę systemową (dostępną z dowolnego miejsca), uruchom skrypt instalacyjny. Wymaga on uprawnień root i musi być uruchomiony z katalogu repozytorium:

./install_dependencies.sh

Skrypt automatycznie tworzy dowiązanie symboliczne w katalogu /usr/local/bin/, dzięki czemu komenda pman jest dostępna globalnie w systemie.

5.3 Weryfikacja instalacji

Po instalacji sprawdź czy narzędzie działa poprawnie:

pman –version

Powinna zostać wyświetlona wersja narzędzia. Jeśli polecenie nie jest znane, sprawdź czy /usr/local/bin/ jest w zmiennej PATH.

5.4 Uruchomienie bez instalacji

Jeśli nie chcesz instalować narzędzia globalnie, możesz uruchamiać je bezpośrednio ze sklonowanego katalogu:

./proxmox-manager.sh

./proxmox-manager.sh –list

./proxmox-manager.sh –json

6. Obsługa programu

6.1 Tryb interaktywny (domyślny)

Uruchomienie narzędzia bez żadnych flag otwiera interaktywny interfejs TUI. W górnej części ekranu wyświetlane są informacje o węźle: nazwa hosta, wersja PVE oraz czas działania systemu (uptime).

pman

W trybie interaktywnym dostępne są następujące skróty klawiszowe:

• r — odśwież listę maszyn i kontenerów
• q — wyjdź z programu
• [VMID] + Enter — otwórz menu akcji dla wybranej maszyny

6.2 Wybór maszyny i menu akcji

Po wpisaniu identyfikatora VMID i wciśnięciu Enter otwiera się menu akcji dla wybranej maszyny lub kontenera. Dostępne opcje to start (uruchomienie), stop (zatrzymanie), restart (ponowne uruchomienie), console (dostęp do konsoli), snapshots (zarządzanie snapshotami) oraz spice (integracja SPICE, tylko dla VM).

Akcje destruktywne (stop, restart, rollback snapshota) wymagają dodatkowego potwierdzenia przez wpisanie 'y’ lub 'yes’.

6.3 Tryb listy (plain text)

Tryb –list wyświetla sformatowaną tabelę wszystkich maszyn i kontenerów bez uruchamiania interaktywnego interfejsu. Jest przydatny do szybkiego podglądu stanu infrastruktury lub do logowania:

pman –list

6.4 Pozostałe opcje wiersza poleceń

Flaga	Opis
–list	Wyświetl tabelę tekstową bez TUI
–json	Wyświetl dane w formacie JSON
–version	Wyświetl wersję narzędzia i zakończ
–no-clear	Nie czyść ekranu w trybie interaktywnym
–once	Wykonaj jedno odświeżenie (przydatne do nagrywania)
-h, –help	Wyświetl pomoc

6.7 Zmienne środowiskowe

Zachowanie narzędzia można dostosować za pomocą zmiennych środowiskowych ustawianych przed uruchomieniem skryptu:

• LOG_FILE — ścieżka do pliku logów; gdy ustawiona, narzędzie zapisuje ustrukturyzowane logi
• PROXMOX_MANAGER_SPICE_ADDR — adres bind dla SPICE (domyślnie 127.0.0.1)
• PROXMOX_MANAGER_ALLOW_NONROOT=1 — pozwala uruchomić narzędzie bez uprawnień root (do celów CI)

Przykład ustawienia zmiennej środowiskowej:

LOG_FILE=/var/log/pman.log pman

7. Bezpieczeństwo

Proxmox Manager został zaprojektowany z myślą o bezpieczeństwie. Oto kluczowe aspekty:

• Wymagane uprawnienia root: Skrypt wywołuje qm, pct i inne narzędzia Proxmox wymagające podniesionych uprawnień.
• Brak przechowywanych poświadczeń: Narzędzie polega wyłącznie na uwierzytelnianiu hosta Proxmox — nie przechowuje żadnych haseł ani tokenów.
• Brak ruchu wychodzącego: Wszystkie operacje są wykonywane lokalnie. Narzędzie nie komunikuje się z zewnętrznymi serwerami.
• ShellCheck: Każdy plik .sh jest sprawdzany przez ShellCheck przy każdym pushu i pull requeście.
• Gitleaks: Skaner zapobiega przypadkowemu dodaniu sekretów (haseł, kluczy API) do repozytorium.

Uwaga bezpieczeństwa: Ponieważ narzędzie wymaga uprawnień root, należy uruchamiać je wyłącznie na zaufanych hostach Proxmox. Nie należy udostępniać dostępu do narzędzia nieuprawnionym użytkownikom.

8. Testowanie i CI

Projekt posiada automatyczne testy i potok CI (Continuous Integration) oparty na GitHub Actions.

8.1 Testy lokalne

Zestaw 8 testów można uruchomić lokalnie bez dostępu do prawdziwego hosta Proxmox — testy używają zaślepek (mock-bin) symulujących odpowiedzi narzędzi qm i pct:

tests/run.sh

8.2 Sprawdzenie kodu

Statyczna analiza kodu Bash za pomocą ShellCheck.

ShellCheck działa na zasadzie: brak komunikatów = wszystko OK. Gdyby były problemy, wyświetliłby linie z błędami i sugestiami poprawek:

shellcheck proxmox-manager.sh

8.3 CI na GitHub Actions

Przy każdym pushu i pull requeście automatycznie uruchamiane są ShellCheck na wszystkich plikach .sh oraz Gitleaks do wykrywania sekretów w kodzie.

9. Ograniczenia narzędzia

Proxmox Manager jest świadomie zaprojektowany jako proste narzędzie. Nie zastępuje pełnego panelu webowego Proxmox i nie jest przeznaczony do:

• Zastąpienia webowego UI Proxmox dla złożonych zadań — panel webowy oferuje znacznie bogatsze możliwości konfiguracji.
• Zarządzania konfiguracją — brak integracji z Terraform czy Ansible (choć jest planowana).
• Pracy jako demon — narzędzie uruchamia się na żądanie i kończy działanie, nie działa w tle.
• Zarządzania wieloma węzłami (multi-host) — obsługuje tylko lokalny węzeł Proxmox.

10. Przykładowe scenariusze użycia

Scenariusz 1: Szybki podgląd stanu infrastruktury

Administrator chce sprawdzić które maszyny są uruchomione. Zamiast logować się do panelu webowego, wpisuje:

pman –list

Otrzymuje natychmiastowy przegląd wszystkich VM i kontenerów z ich statusami.

Scenariusz 2: Tworzenie snapshota przed aktualizacją

Przed aktualizacją systemu na maszynie wirtualnej administrator chce utworzyć snapshot:

pman

Następnie wpisuje VMID maszyny, wybiera opcję 'snapshots’, a potem 'create’. Podaje nazwę snapshota np. 'przed-aktualizacja-2026-04′ i potwierdza.

Scenariusz 3: Automatyczny monitoring w skrypcie

W skrypcie automatyzacyjnym pobierane są wszystkie uruchomione maszyny:

pman –json | jq ’.[] | select(.status == „running”) | .name’

Przykładowe use-case

Homelab

• szybkie zarządzanie VM bez GUI
• automatyczne laby testowe

DevOps

• provisioning VM pod testy
• integracja z pipeline

MSP / małe firmy

• uproszczone zarządzanie wieloma hostami

11. Zalety i wady

Zalety

• lekki i szybki
• łatwa automatyzacja
• open-source
• pełna kontrola

Wady

• brak pełnego GUI
• zależny od API Proxmoxa
• mniej funkcji niż oficjalne narzędzia
• czasem brak dokumentacji

---

12. Bezpieczeństwo (bardzo ważne)

Przy korzystaniu:

• używaj API tokenów zamiast hasła
• ogranicz uprawnienia
• korzystaj z HTTPS
• nie wystawiaj API do internetu

Podsumowanie

Proxmox Manager to wartościowe narzędzie dla każdego administratora Proxmox, który ceni efektywność pracy z wiersza poleceń. Jego największe zalety to prostota instalacji (jeden plik bash, brak zależności), czytelny interfejs TUI z symbolami statusu, obsługa zarówno maszyn wirtualnych jak i kontenerów LXC, bezpieczeństwo (brak przechowywanych poświadczeń, brak ruchu wychodzącego) oraz możliwość integracji z automatyzacją przez wyjście JSON.

Narzędzie nie jest przeznaczone do zastąpienia pełnego panelu webowego Proxmox, ale doskonale sprawdza się jako szybki, lekki interfejs do codziennych operacji administracyjnych — szczególnie gdy dostęp do przeglądarki jest utrudniony lub niepożądany.