While Proxmox has a very intuitive WebGUI, it can prove to be tedious when making many different system level changes in short order. It would be helpful if there was a utility that could be leverage to allow scripting within the platform. Luckily there is and this article intends to introduce the Proxmox command line utility (pvesh) to help improve administrative efficiency when it comes to administrating this platform.
Why pvesh?
Although I have used Proxmox for many years now, I recently discovered some capabilities of the platform that have allowed me to dramatically increase my efficiency in deploying virtual environments. Through the use of the pvesh utility, users can perform the same actions available in the WebGUI via the command line directly on the Proxmox server. With these capabilities, the following benefits can be recognized:
- Reduce the amount of time to create a virtual demo environment for customers
- Rapidly deploy and disassemble virtual environments to make the most efficient use of resources
- Share common topologies/settings among colleagues instead of re-inventing the wheel
- Perform hypervisor modifications when only CLI access to the server is available
Proxmox API
All of the functionality within pvesh is driven by the Proxmox Application Programming Interface (API). It is a “Rest-like” and uses Javascript Object Notation (JSON) as its primary data format. Standard HTTP methods (GET, PUT, POST, DELETE) are supported for consumption and it uses the same standard port as the normal Proxmox web interface (8006). As an example, for a default deployment of proxmox, the base URL to access the API is:
https://<your.server>:8006/api2/json/
For more information about the Proxmox API, consult the official documentation at the following link.
PVESH Command Line Utility
PVESH is a command-line utility to expose the Proxmox API. It can be used directly from the proxmox shell as shown in the example below:
# pvesh get /version
It generally follows the usage convention:
pvesh <command> <api path> <options>
This command also supports “tab-completion”, similar to many other linux utilities, so if you do not know the commands to use, you can leverage this method to discover applicable commands.
Proxmox PVESH Methods
To map the common API methods to the corresponding commands in PVESH, see the following table below:
| HTTP METHOD | PVESH CLI | Description |
| GET | get | Read a value that is currently set |
| PUT | set | Update a value that is currently set |
| POST | create | Assign a value that is not set |
| DELETE | delete | Remove a value that is set |
Not listed on the table listed above is the “usage” command which is very valuable for usage with the API. It can return information that is helpful:
pvesh usage /cluster/firewall/aliases
For even more detailed information on the usage of this command, you can use the following command:
pvesh usage /cluster/firewall/aliases -v
PVESH Examples
Proxmox Firewall Alias Modification
As part of upgrading my Internet connection by switching to a different provider, I was assigned a new IP address. Unfortunately, I forgot to update the firewall on my colocated Proxmox server to provide management access to the device. Fortunately for me, I still had access to a VM in the cloud that could SSH into the Proxmox.
Using this VM, I was able to change the firewall via the pvesh command and restore my connectivity to the Proxmox. Below is a summary of the commands I used to restore this access:
1. Check the existing firewall settings
pvesh get /cluster/firewall/rules
2. Append the rule ID to the previous command to find the details of the rule:
pvesh get /cluster/firewall/rules/4
3. Check the alias for the object that needed to be updated to my new IP address
pvesh get /cluster/firewall/aliases/home
You can use the general alias command without specifying the alias name for a listing of all defined aliases.
pvesh get /cluster/firewall/aliases
4. Update the alias to the new IP address
pvesh set /cluster/firewall/aliases/home --cidr 1.1.1.1
Although the warning is listed below the command, it seems to be able to be ignored as it does update the value
5. To confirm that the alias was updated, use the command from earlier to get the contents of the alias
pvesh get /cluster/firewall/aliases/home
Once I completed these steps, I was able to successfully access my Proxmox server from my home computer again.
Creation of Virtual Machine
Creating virtual machines via the WebGUI wizard is very straight forward but there are quite a few steps. If there is a need to provision a lot of different VMs, one can see that the workload can increase exponentially if they need to be provisioned by the wizard.
Luckily, via the pvesh utility, those multiple steps can be reduced to allow for faster creation of these VMs with less effort. Below is are a few examples of provisioning a VM in Proxmox using the pvesh utility.
Bare Minimum Virtual Machine Creation
According to the output, the bare minimum of what needs to be defined when creating a VM is the “VMID”. Specifying this as part of the command used to create a VM results in the following:
pvesh create /nodes/<nameofproxmoxnode>/qemu -vmid <unusedVMID>
This results in the following output when listing the contents of the virtual machines on this Proxmox node:
pvesh get /nodes/pve1/qemu/
While this created the VM, there are a lot of items missing such as a hard drive and network interfaces. In addition to that, without defining some items, the pvesh commands substitutes some default values which are present once displaying the hardware of this VM from the WebGUI.
Creation of Usable Virtual Machine
In order to get a more usable VM from the pvesh utility, it is recommended to specify the following parameters:
- Name
- Sockets (CPU)
- Cores (CPU)
- Memory (RAM)
- Hard Disk
- Hard Disk Controller
- Operating System
- Network Interfaces
Below is a template of the pvesh command to specify all of these items:
pvesh create /nodes/<name of proxmox node>/qemu -vmid <unusedVMID> -name <name of VM> -sockets <num of sockets> -cores <num of cores> -memory <amount in MB> -ostype <operating system type> -scsi0 <storage:size in GB> -net<#> <type of virtual nic>,bridge=<proxmox bridge>
Based on this template, the following example below creates a usable VM:
pvesh create /nodes/pve1/qemu -vmid 7777 -name historianTechVM -sockets 1 -cores 2 -memory 2048 -ostype l26 -scsi0 local-zfs:16 -net0 virtio,bridge=vmbr1
Reviewing the same output from the command used earlier above to list the virtual machines, we see much more information defined for the virtual machine with VMID 7777:
Lastly, after looking in the WebGUI, we see more information populated for this virtual machine under the “hardware” tab:
These examples above are just an introduction of the power that the pvesh provides, however in a later post, I will cover how to leverage this tool for rapid topology deployment.
As always, I hope this content is useful. Please comment below and let me know how you use pvesh to increase your operational efficiency in Proxmox.