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

Figure. – Screenshot of the pvesh command line utility

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

Figure. – pvesh command showing demonstration of usage

For even more detailed information on the usage of this command, you can use the following command:

pvesh usage /cluster/firewall/aliases -v

Figure. – pvesh command showing verbose output

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

Figure. – Screenshot of pvesh command to list firewall rules

2. Append the rule ID to the previous command to find the details of the rule:

pvesh get /cluster/firewall/rules/4

Figure. – Screenshot of pvesh command listing firewall rule requiring modification

3. Check the alias for the object that needed to be updated to my new IP address

pvesh get /cluster/firewall/aliases/home

Figure. – Screenshot of pvesh command listing the alias

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>

Figure. – Screenshot of pvesh command to create a virtual machine

This results in the following output when listing the contents of the virtual machines on this Proxmox node:

pvesh get /nodes/pve1/qemu/

Figure. – Screenshot of pvesh command to list virtual machines on Proxmox node

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.

Figure. – Screenshot of the Proxmox WebGUI of the VM created with pvesh utility

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

Figure. – Screenshot of pvesh command to create a usable VM

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:

Figure. – Screenshot of output from pvesh command to list virtual machines

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.