-
Notifications
You must be signed in to change notification settings - Fork 46
Home
Thank you for visiting, considering, using and/or hopefully contributing to the project.
This wiki aims to explain some of the more specific requirements to get it working well.
- System Environment must be up-to-date & well set-up
- WHMCS Server needs to be root on PVE for Actions
- Module also needs a vnc user on PVE for Console
- WHMCS & Proxmox must be Subdomains of 1x Domain
- Proxmox Server IPv4 needs FCrDNS for Cookie
- WHMCS Service ID (DB primary key) > 100
- 2-level TLD Domains need code amended
Please consider factors such as public-to-private (WHMCS-to-Proxmox) integration and the inherent risks it carries, as well as Cyber Security factors such as anti-CSRF limitations (same-domain services due to same-domain cookie) and upstream limitations.
We have tried to ensure a least-privilege approach with how the module has been overhauled.
We can only look at helping where you are on the latest versions of all involved software and systems. This extends from your Web Server to PHP and its extensions, to all WHMCS modules, to the Proxmox VE installation and underlying packages, as well as this module and its dependencies.
It also applies to server and service configurations, permissions/ownership structures, and more. Issues can arise due to tiny misconfigurations, so your systems must be sanity-checked to be following best practices in all regards. If issues can't be ruled out, we can't help.
When configuring the module in WHMCS, you will need to create a Server in WHMCS Configuration. That will need to be grouped into a Proxmox group, and the Module is linked to the Servers via the Product/Service creation (where you tie it to Proxmox Plans and IP Pools).
The server in WHMCS needs to be root-level, or hold sufficient segregated privileges for its user in Proxmox that the requests present in the module codebase can be successfully carried out. Please ensure you provide sufficient ACLs if you do not provide root access.
Once everything is configured, you also need to follow the instructions below to create a restricted 'vnc' user in Proxmox VE itself. This is only used for allowing end users to proxy their console to the Client Area via noVNC.
To facilitate the web socket (WSS) connection to the VNC tunnel/proxy, the password for the resulting user must be configured in WHMCS Admin > Modules > Proxmox VE for WHMCS > Module Config > VNC Secret.
- Create User Group "VNC" via PVE > Datacenter / Permissions / Group
- Create new User "vnc" > Datacenter / Permissions / Users - select Group: "VNC", Realm: pve
- Create new Role -> Datacenter / Permissions / Roles - select Name: "VNC", Privileges: VM.Console (only)
- Add permission to access VNC -> Datacenter / Node / VM / Permissions / Add Group Permissions - select Group: "VNC", Role: "VNC"
- Configure the WHMCS > Modules > Proxmox VE for WHMCS > Module Config > VNC Secret with 'vnc' password.
Due to anti-CSRF limitations, cookies can only be issued to subdomains of a domain at the most. This means that your WHMCS and Proxmox VE must be subdomains of the same domain name. This only applies if you wish for noVNC access to be possible, as to do this we must set a Proxmox Access Ticket in a browser cookie, and also then send the VNC Ticket as a parameter to the Proxmox API.
As WHMCS originates the cookie placement request, it does not have scope to do this inter-domain.
In order to obtain the hostname of the Proxmox Server we perform a PTR/rDNS lookup on its IPv4 address. Make sure it's correctly configured so there are no problems using the VNC service via the Client Area.
If you don't wish to leverage the functionality, you should leave the VNC Secret configuration blank so it is unable to attempt any connection requests.
If you have not sold/given enough WHMCS Services for the Primary Key in your tblhosting table to be >100 then you will not have success trying to do anything with those services over the Proxmox API, as they reserve 0-100 for internal purposes to protect the system.
You'd have to create dummy/fake/cancelled services to make up the difference, and then you will be sorted.
To obtain the domain-only (no subdomains) variable to set the Cookie (PVEAuthCookie) for VNC access, we use some regex to remove the subdomain parts, however this simple logic doesn't support 2-level Domains (ie. com.au or co.uk) so you would need to amend the novnc_router.php file to cater to your needs.
There are regex syntax generators online that can assist with this, in your testing environment.