Admin Area

Product Home Screen
Module Command buttons
Product Configuration
Configurable Option (Operating system selection)
Configurable Option (Backups/Snapshots/CPU/RAM/IPv4/IPv6)
IPv4/IPv6 Pools
DNS Zones Synchronization

Product Home Screen

ProxmoxKVM module WHMCS

The main screen of the product contains the following items.

Module Command buttons of the module for managing the service and the virtual machine
Section with the id of the virtual machine and a button for setting a new ID
Connection API status to PROXMOX server
Button to connect to the noVNC server console
The section in which in real time with an update of 1 time for 5 seconds the parameters and stars of the virtual machine are shown
Section with graphs with virtual machine statistics

Module Command buttons

ProxmoxKVM module WHMCS

Status concepts.

Remote status

The status of the virtual machine as returned by the PROXMOX server.
May be: running/stopped

VM remote lock

May be: clone/backup

Local status

The status is internal, to control and select automation actions using the module.

The local state can take the following values:

creation - the first status issued at the time of service creation. Indicates that the virtual machine creation process should start
reinstall -status if the reinstallation process is running and the virtual machine is in the reinstallation queue
clone - the process of cloning a virtual machine from a template
set_cpu_ram - the process of configuring the number of processor cores and RAM memory was successful
set_system_disk_size - the process of creating the size of the system disk has completed successfully
set_system_disk_bandwidth - the process of configuring system disk bandwidth limits was successful
set_created_additional_disk - the process of creating an additional disk is successful. Also if the additional disk is not present in the package configuration
set_additional_disk_size - the process of creating the size of theadditional disk has completed successfully. Also if the additional disk is not present in the package configuration
set_additional_disk_bandwidth - the process of configuringadditional disk bandwidth limits was successful. Also if the additional disk is not present in the package configuration
set_network - network card configuration (vlan, bridge) completed successfully
set_firewall - firewall rules added successfully
set_cloudinit - cloud init configuration successful
ready - the status characterizes that the virtual machine was created correctly and is ready to work
set_dns_records - means that the next time the crontab is executed, DNS records will be synchronized
change_package - means that the next time you run crontab, the settings of the virtual machine will be changed, such as (disk, ram, processor, IP)

Standard Module Command buttons

Create

This function runs when a new product is provisioned. This can be initiated by WHMCS upon checkout or Client making payment for a new order. Also, it can be initiated by an admin user from the Products/Services tab in a client's profile of the admin area.

General algorithm of action:

An available IP address is selected from the list in the server settings.
The available virtual machine ID is selected in such a way that it is unique in the WHMCS system and Proxmox server
The fields with the domain name and the name of the virtual machine are generated and filled. The procedure uses the data supplied in the virtual machine package.
Start the process of cloning a virtual machine from the desired virtual machine template.

All other functions for creating a virtual machine will be implemented by a cron task

Terminated service IP addresses are also taken into account and can be assigned to a new service.

Suspend

This function runs when a suspension is requested. It can be requested automatically by the WHMCS Cron when a product becomes overdue, or by admin user in the Client Profile.

Makes the virtual machine stop if the virtual machine is powered on.

Unsuspend

This function runs when an unsuspension is requested. It can be requested upon payment of an overdue invoice for a product.

Makes the virtual machine start if the virtual machine is powered off.

Terminate

This function runs when a termination is requested. It can be automatically requested by the WHMCS Cron for long overdue products when enabled (Automation Settings). It can be also requested by an admin user in the Client Profile.

General algorithm of action:

Deletes all backups and snapshots of the virtual machine.
Makes the machine virtual stop if the virtual machine is powered on.
Then it deletes the virtual machine.
Adds information with the date and IP address to the admin notes on the client service.
Returns the machine's used IP address back to the pool of free useable IP addresses.
Cleans up data.

Change Package

This function runs during procedure of upgrading or downgrading products. This function runs when an upgrade or downgrade order, placed by the client, becomes paid. Admins can also invoke this from the product management pages. The same function runs for upgrades and downgrades of both products and configurable options.

General algorithm of action:

Makes the virtual machine stop if the virtual machine is powered on.
Changes the parameters of the virtual machine to the parameters specified in the package.
Makes the start of the virtual machine.

Additional Module Command buttons

All possible actions available to be performed in the admin panel have short symbols that will help you understand the consequences of the action.
* - It is possible to run a function with which will do actions on the virtual machine in the running state.
** - It is possible to run only if the virtual machine is in the stopped state
-> - means that this function participates in the automatic creation of the virtual machine and points to the next function that must be run to correctly complete the creation of the virtual machine.

Start

Starts the virtual machine if the virtual machine is in the stopped state and the local state is ready

Stop

Stops the virtual machine if it is in the running state

Reinstall

Starts the process of reinstalling the virtual machine

VMSetDedicatedIp

An available IP address is selected from the list in the server settings. Terminated service IP addresses are also taken into account and can be assigned to a new service.

VMClone

Starts the process of cloning a virtual machine from the desired virtual machine template.

**Set CPU RAM

Forces configuration of the processor and memory settings of the virtual machine relative to the package configuration.

*Set System Disk Size

Forces the size of the system disk according to the parameters in the package

*Set System Disk Bandwidth

Forces system disk bandwidth settings according to packet settings.

*Set Created Additional Disk

Creates an additional virtual machine disk if configured accordingly in the package

*Set Additional Disk Size

Forces the size of the additional disk relative to the parameters in the package, if needed

*Set Additional Disk Bandwidth

Forces additional disk bandwidth settings relative to packet settings, if needed

*Set Network

Forces configuration of network card parameters such as bridge VLAN and bandwidth relative to the parameters in the packet

*Set Firewall

Adds rules to the firewall. DOES NOT REMOVE OLD.

**SetCloudinit

Forces cloud-init device settings to be configured relative to the settings in the package.

**VMRemove

Delete the virtual machine. Leaves backups and does not delete unused disks.

Set DNS records

DNS records will be synchronized immediately and before completion. May be busy for a long time.

Product Configuration

ProxmoxKVM module WHMCS

Order now | Download | FAQ

Add new product to WHMCS

System Settings->Products/Services->Create a New Product

In the Module settings section, select the "PUQ ProxmoxKVM" module

License key

A pre-purchased license key for the "PUQ ProxmoxKVM" module. For the module to work correctly, the key must be active

Type of virtual machine creation

How will the virtual machine will be cloned from the template
Full Clone - much more times for deployment.
Linked clone VM - faster deployment, requires less disk space but cannot run without access to the base VM Template

Target node

The node in the cluster on which the virtual machine should be created. If you select the automatic option or the node was unavailable at the time the virtual machine was created, the module will actually select the node with the most real free RAM (not a percentage, but the most free RAM numerically).
If a specific node is selected manually, the module does not check the available RAM in any way.

Default OS template

Sets the default operating system template. In cases where the template chosen by the client is not available, or if the options with the choice of the operating system are not configured, this template will be used.

Backups storage

Data store for backups of virtual machines

If you are using a cluster, then you need to have this data store on a network protocol, such as NFS.

ISO's storage

Data store for ISO images

If you are using a cluster, then you need to have this data store on a network protocol, such as NFS.

VM configuration

Basic configuration settings for the virtual machine

CPU - number of CPU cores for a new machine

RAM - amount of RAM for a new machine

OS username - The user that will be configured in the virtual machine settings will be transferred to the client and will appear in the password change

Depending on cloud-init settings in the template. If there is a root user in the template and you also enter root in the service configuration in WHMCS, a password for the root user will be generated when creating the VM. If you enter another user name in this window (but the template does not contain one), it will be created when the machine is created and the password will be sent to the client.

VM name prefix: The VM name prefix will be added to the virtual machine name.
VM name: <prefix>-<client_id>-<service_id>

First vm id: ID from which to start searching for a free id for a new virtual machine

Snapshot lifetime: After how many days will snapshots be removed automatically

System disk

The system disk is determined by the one that is assigned to the first boot in the virtual machine or template.

System disk options. The system drive is the drive on which the system is installed. Limitations are possible both in terms of bandwidth in megabytes per second, as well as restrictions on the number of I/O operations.

Please note that the size of the system disk must be greater than or equal to the size of the system disk in the template.

Additional disk

The additional drive is the second drive in the virtual machine or template that is not assigned to the first boot option.

If an additional disk is not created in the virtual machine template, it will be created automatically on the same storage as the system disk. If you need an additional disk on a different storage than the system disk, it must be then created in the virtual machine template on the required storage.

Additional disk options. Limitations are possible both in terms of bandwidth in megabytes per second, as well as restrictions on the number of I/O operations.

Network configuration

The section in which you must specify the parameters of the network virtual machine map.

Network model - The network card model of the virtual machine

Automatic selection bridge/VLAN -When creating a virtual machine, the IP address will be selected automatically from the list of available IP addresses from the PROXMOX server parameter or IP Pools added in the WHMCS system. Regarding the selected IP address, the network card, bridge and vlan will be configured.

Network bridge, VLAN - If you do not use the Automatic selection, bridge/VLAN. You need to select bridge and VLAN. The IP address will be selected from the list of IP addresses available in this bridge and VLAN in the PROXMOX server address list settings in the WHMCS system.

DHCP IPv4 - Whether to use a DHCP server. The IP address will not be selected from the list in the PROXMOX server in the WHMCS system. In this case, firewall rules won't be applied as we don't know IP address.

DHCP IPv6 - Whether to use a DHCP server. The IP address will not be selected from the list in the PROXMOX server in the WHMCS system. In this case, firewall rules won't be applied as we don't know IP address.

Firewall - Enable firewall on the network card of the virtual machine. Only works when DHCP is not used.

Anti spoofing rules - This option only works if you are not using a DHCP server. It adds allowing rules for incoming and outgoing traffic with the IP address of the virtual machine.

For the correct operation of the firewall rules to avoid spoofing the IP address of the virtual machine, it is necessary to configure the firewall on the PROXMOX server, the firewall policy DENY/DENY.

In order to manage pools of IPv4 and IPv6 IP addresses, you need to install the PUQ Customization addon module (free)

https://doc.puq.info/books/puq-customization-whmcs-addon

https://download.puqcloud.com/WHMCS/addons/PUQ-Customization/

https://puqcloud.com/whmcs-addon-puq-customization.php

Integrations configuration

This section contains settings that are responsible for integrating the module with other systems.

noVNC WEB proxy server, noVNC WEB proxy key - VNCPROXY server settings.
VNCPROXY and noVNC are used to enable the client to connect to the virtual machine console (Keyboard, Video, Mouse).

How to set up a VNCPROXY server is described in https://doc.puq.info/books/proxmoxkvm-whmcs-module/page/install-vncproxy-and-novnc

For your comfort we provide our public VNCPROXY server with noVNC client. You can use it freely, but we strongly recommend creating your own VNCPROXY server with noVNC client

noVNC WEB proxy server: vncproxy.puqcloud.com
noVNC WEB proxy key: puqcloud

Main domain - The domain that you use to present the virtual machine. In the WHMCS system, the domain column on the client's product will be filled in the format <prefix>-<client_id>-<service_id>.<Main domain>. Also, this parameter will be specified as "search" in the virtual machine in the /etc/resolv.conf file.

Revdns ticket/RevDNS ticket department - In case you haven't created a reverse DNS zone record integration. The module can create a ticket when the client changes the reverse zone entry in the settings. You will have to manually process the request.

How you can integrate DNS zone records with your DNS server is described here: https://doc.puq.info/books/proxmoxkvm-whmcs-module/page/synchronization-of-dns-records

Email configuration

In this section, you need to select email templates that will be used by the module to communicate with the client.

VM is ready - This email will be sent each time a virtual machine is created. In case of creation and in case of reinstallation. In this email, the client will receive a login and password to access the virtual machine system.

Reset password - This email will be sent to the client every time the client uses the password reset function, the client will receive a login and password to access the virtual machine system.

Backup restored - This email will be sent to the client every time the client uses the restore virtual machine from backup function.

Sample templates are available here:
https://doc.puq.info/books/proxmoxkvm-whmcs-module/page/email-template-puqproxmoxkvm-vm-is-ready
https://doc.puq.info/books/proxmoxkvm-whmcs-module/page/email-template-puqproxmoxkvm-reset-password
https://doc.puq.info/books/proxmoxkvm-whmcs-module/page/email-template-puqproxmoxkvm-backup-restored

Additionally:
https://doc.puq.info/books/proxmoxkvm-whmcs-module/page/email-template-puqproxmoxvkm-welcome-email
https://doc.puq.info/books/proxmoxkvm-whmcs-module/page/email-template-puqproxmoxkvm-upgrade-email

Client configuration

In this section, you can configure the client's access rights to manage its virtual machine.

Configurable Option (Operating system selection)

ProxmoxKVM module WHMCS

Order now | Download | FAQ

In order for the client to have a choice of operating system in the configuration of the virtual machine. You need to configure the Configurable Option and connect them to the package.

Create Group

Add new Configurable Option to WHMCS

System Settings->Configurable Option->Create a New Group

Enter the group name, description, and select the products you need.

Group Name: Operating system

Add Configurable Option

After saving, create a new Configurable Option

Price definitions

In this part of the settings, we define individual price lists for selected individual options.

We use the WHMCS standard and add the sign "|" to describe the individual options. The convention presented in our guide must be followed on the left side of the sign. To the right of the sign "|" we give the name that will be displayed in the views for the user (admin, client)

It is very important to enter the names of the options precisely, because they are also used to define the settings and any mistakes or typos will prevent the correct operation of the entire ordering process and starting the virtual machine.

Option name

Option Name: OS|Operating system

You can replace the name "Operating system" with your own, ie: My offered system.

It is important that the option name be started with the prefix "OS |"

Options

The Options format is this: template_id|name of system separated by "|"

You can replace the name "name of system" with your own, ie: Debian, Nextcloud, my system x etc.

template_id is the number of a specific template machine uploaded to proxmox and recreated as template.

It is important that the options be started with the prefix "template_id |"

Please look at this example - as options we have defined: 1010|Debian-10.12.

We use that precise text string because we have deployed on Proxmox node/cluster template with VM_ID: 1010 which is based on Debian 10 release.

Configurable Option (Backups/Snapshots/CPU/RAM/IPv4/IPv6)

ProxmoxKVM module WHMCS

Order now | Download | FAQ

In order for the client to have a choice of Backups/Snapshotsin/CPU/RAM/IPv4/IPv6 the configuration of the virtual machine. You need to configure the Configurable Option and connect them to the package.

List of available options

It is important that the option name be started with the prefix "prefix|name" The prefix is required for the module to define the option. Name can be changed at will

Option Name: B|Backup -> Options: <count>|Name

Option Name: S|Snapshot -> Options: <count>|Name

Option Name: CPU|Processor -> Options: <count>|Name

Option Name: RAM|Memory -> Options: <count>|Name

Option Name: ipv4|IPv4 -> Options: <count>|Name

Option Name: ipv6|IPv6 -> Options: <count>|Name

Option Name: OS|Operating system -> Options: <template_id>|Name

Option Group

Add new Configurable Option to WHMCS

System Settings->Configurable Option->Create a New Group

Enter the group name, description, and select the products you need.

Group Name: Backups/Snapshots

After saving, create a new Configurable Option

Price definitions

In this part of the settings, we define individual price lists for selected individual options.

Backup definitions

Add an option with a choice of the number of backups

Option name

Option Name: B|Backup

You can replace the name "Backup" with your own, ie: Sicherung, My backup offer etc..

It is important that the option name be started with the prefix "B|"

Options

The Options format is this: number_of_backups|name separated by |

You can replace the name "name" with your own.

It is important that the options be started with the prefix "x |" where "x" represent number of allowed backup

Snapshot definitions

Add an option with a choice of the number of snapshots

Option name

Option Name: S|Snapshot

You can replace the name "Snapshot" with your own, ie: Fast Snapshots, personal Snapshot etc.

It is important that the option name be started with the prefix "S|"

Options

The Options format is this: number_of_snapshot|name separated by |

You can replace the name "name" with your own.

It is important that the options be started with the prefix "x |" where "x" represent number of allowed snapshots

IPv4/IPv6 Pools

ProxmoxKVM module WHMCS

Order now | Download | FAQ

Starting with version 1.3, the module started supporting IPv4/IPv6 pools.

In order to manage pools of IPv4 and IPv6 IP addresses, you need to install the PUQ Customization addon module (free)

https://doc.puq.info/books/puq-customization-whmcs-addon/page/ip-pools
https://doc.puq.info/books/puq-customization-whmcs-addon/chapter/module-puqproxmoxkvm
https://doc.puq.info/books/puq-customization-whmcs-addon

https://download.puqcloud.com/WHMCS/addons/PUQ-Customization/

DNS Zones Synchronization

ProxmoxKVM module WHMCS

Order now | Download | FAQ

Starting with version 1.4, the module started supporting DNS Synchronization
(cloudflare.com, HestiaCP)

In order to manage DNS zones to synchronization , you need to install the PUQ Customization addon module (free)

https://doc.puq.info/books/puq-customization-whmcs-addon/page/dns-zones
https://doc.puq.info/books/puq-customization-whmcs-addon/chapter/module-puqproxmoxkvm
https://doc.puq.info/books/puq-customization-whmcs-addon

https://download.puqcloud.com/WHMCS/addons/PUQ-Customization/