Bots

Per cluster

Remote Proxmox VE cluster management through a Telegram chatbot: execute commands and check status from any device.

Features

Remote Control

Execute commands and manage nodes through a Telegram bot.

Messages

Receive the replies to your commands. Receive also the messages sent manually from the Telegram page to one or all connected chats.

Access Control

Restrict the bot to a list of allowed Telegram chat IDs. The token is stored encrypted at rest.

Mobile Access

Manage the cluster from any device with the Telegram app.

Command Response

Receive feedback on commands and system status.

Chat Interface

Execute operations through chat-based commands.

Why

Why a chatbot when the web UI is already there?

Cluster status from your phone

Check node uptime, VM state and last backup without a browser or a VPN connection. You reach the cluster wherever Telegram works.

Push, not pull

Telegram delivers the replies to your commands and the messages sent from the Telegram page. There is no polling, no mail filter that hides a message and no email password to keep up to date.

Authorised chats only

Only the chat IDs you allow can talk to the bot. The token is stored encrypted at rest.

Quick fire-and-forget

Send /vmstart to start VM 200 from your phone while you walk to the data centre. You need no laptop, no SSH and no web UI.

Sections

• Overview: introduction to the module
• Telegram: live bot log and a button that opens Telegram Web. Once at least one chat has written to the bot, the page also shows a Users picker and a Message box. Use them to send a message to all or one of the connected chats (press Enter to send)

Set Up Your Telegram Bot

To connect the Bots module to Telegram, create a bot with BotFather and copy the generated token into the module settings.

1. Open the Telegram app on your phone or computer.

2. Search for the BotFather bot: it is the official Telegram bot for creating and managing bots.

3. Type /newbot to create a new bot. Follow the instructions:

   • Choose a display name (e.g. My PVE Bot)
   • Choose a username: must be unique and end in bot (e.g. my_pve_bot)

4. BotFather generates an API token (e.g. 707587383:AAHD9D***************).

5. Copy the token and paste it into the Token field in the Bots module settings.

The bot starts when Enabled and Telegram → Enabled are both on. Restrict who can use it with Chats Id. Both are described in Settings.

Unique test usernames: If you create a bot only for testing, prefix the username with your name to make it unique (e.g. john_pve_bot).

Bot commands

Commands are sent to the bot as Telegram commands (/name). The bot answers a message that is not a command with the help, unless a previous command is waiting for an answer.

The VM commands take no argument: the bot answers with the list of guests to choose from.

Command	Action
/help	Show help
/vmstart	Start VM/CT
/vmstop	Stop VM/CT
/vmshutdown	Shutdown VM/CT
/vmreset	Reset VM/CT
/nodereboot	Reboot node
/nodeshutdown	Shutdown node
/get · /set · /create · /delete	Call the Proxmox VE API on a resource path; the result is sent back as a file
/usage	Show the usage of an API resource
/alias	Create alias commands

The bot also has built-in aliases for common API calls, for example /top, /topn, /tops and /topv (cluster resources, all or by node, storage, VM/CT) and /nsts (node status).

The bot acts with the cluster credentials

The bot talks to Proxmox VE through the connection configured for the cluster in cv4pve-admin, not with the permissions of a cv4pve-admin user. Anyone who can write to the bot from an allowed chat can run every command above, node shutdown and raw API calls included. Always restrict Chats Id.

Access control and log

• Every message received is written to the log of the Telegram page with its chat ID, user name and text. To find the chat ID to allow, write to the bot and read it from the log.
• A message from a chat that is not allowed is answered with a refusal and logged as a security line.
• The log and the list of connected chats are kept in memory: they start empty when the application or the bot restarts.
• Saving the settings restarts the bot.

Settings

Enabled

Turns the module on for the cluster. While it is off the bot does not run, whatever Telegram → Enabled

• Default: off

Telegram → Enabled

Starts the Telegram bot for the cluster. The bot runs while this switch and the module setting Enabled are both on

• Default: off

Telegram → Token

Token generated by BotFather, stored encrypted at rest

• Default: empty (required)

Telegram → Chats Id

Numeric IDs of the chats allowed to use the bot, one per line. When the field is empty there is no access control: every chat is accepted

• Default: empty

Application permissions

Permission	Key	Grants
Bots	Bots.Link	Access to the module and to its Overview page
Telegram	Bots.Link.telegram	Telegram page
Send message	Bots.Chat.SendMessage	The Message box of the Telegram page
Edit Settings	Bots.EditOptions	The settings button of the module

The built-in role Admin for module Bots includes all of them. Roles and permissions are assigned in Admin Area → Security EE.

These permissions apply to the web pages only. Who can use the bot from Telegram is decided by Chats Id.

Proxmox VE privileges: the base (PVEAuditor) plus the following.

Privilege	Used for
VM.PowerMgmt	/vmstart, /vmstop, /vmshutdown, /vmreset
Sys.PowerMgmt	/nodereboot, /nodeshutdown

/get, /set, /create, /delete and the aliases need the privilege of the API path they call.

The base and the rules common to all modules are in Proxmox VE Permissions.