PUQ Mautic

Admin Area

Product Home Screen

 Order now | Dowload | FAQ
The main screen of the product contains the following items.

image-1689070174880.png

Module Command buttons

 Order now | Dowload | FAQ

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:


 

Standard Module Command buttons

image-1689692732371.png

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:

  1. An available IP address is selected from the list in the server settings. 
  2. The available virtual machine ID is selected in such a way that it is unique in the WHMCS system and Proxmox server
  3. 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.
  4. 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:

  1. Deletes all backups and snapshots of the virtual machine.
  2. Makes the machine virtual stop if the virtual machine is powered on.
  3. Then it deletes the virtual machine.
  4. Adds information with the date and IP address to the admin notes on the client service.
  5. Returns the machine's used IP address back to the pool of free useable IP addresses.
  6. 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:

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

 

Additional Module Command buttons

image-1689692773619.png

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

 Order now | Dowload | FAQ

Add new product to WHMCS

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

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

image-1663073259616.png

 

License key

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

image-1663073397433.png


 

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

image-1663073575590.png


 

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.

image-1663073887426.png


 

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.

image-1663074053214.png


 

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.

image-1663074126727.png


 

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.

image-1663074169365.png


 

VM configuration

Basic configuration settings for the virtual machine

image-1663074365027.png

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.

image-1663075790309.png


 

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.

image-1663076436021.png


 

Network configuration

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

image-1689071484773.png

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.

image-1663136275519.png

 

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.

image-1663137423113.png

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.

image-1663137992356.png

Configurable Option (Operating system selection)

 Order now | Dowload | 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

image-1663138303613.png

 

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

Group Name: Operating system

image-1663138481534.png

 

Add Configurable Option

After saving, create a new Configurable Option

image-1663138662765.png

 

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.

image-1663138753301.png

 

 

 

 

 

 

 

 

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

 Order now | Dowload | 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

image-1689071160905.png

 

Option Name: B|Backup -> Options: <count>|Nameimage-1689071191624.png

 

Option Name: S|Snapshot -> Options: <count>|Nameimage-1689071194449.png

 

Option Name: CPU|Processor -> Options: <count>|Nameimage-1689071172482.png

 

Option Name: RAM|Memory -> Options: <count>|Nameimage-1689071183758.png

 

Option Name: ipv4|IPv4 -> Options: <count>|Nameimage-1689071185927.png

 

Option Name: ipv6|IPv6 -> Options: <count>|Nameimage-1689071188713.png

 

Option Name: OS|Operating system -> Options: <template_id>|Nameimage-1689071196609.png

 

 


 

Option Group

Add new Configurable Option to WHMCS
System Settings->Configurable Option->Create a New Group

Proxmox KVM module for WHMCS - adding configurable options

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

Group Name: Backups/Snapshots

 

After saving, create a new Configurable Option

image-1663139696592.png

 

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.

 

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

 

image-1663139775820.png

 

 

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

 

image-1663141212475.png

 

 

 

 

 

 

 

IPv4/IPv6 Pools

 Order now | Dowload | 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/

image-1689071770666.png

image-1689071770698.png

image-1689071770713.png

image-1689071770729.png

image-1689071770765.png

DNS Zones Synchronization

 Order now | Dowload | 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/


image-1689686238773.png

image-1689686243802.png

image-1689686250657.png