BitMaster/Proxmox-VE-for-WHMCS
1
0
Fork 0
mirror of https://github.com/The-Network-Crew/Proxmox-VE-for-WHMCS.git synced 2026-04-02 02:28:18 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Overhaul layout & info

Browse Source
This commit is contained in:
Luke S Thompson
2025-04-26 17:08:38 +10:00
committed by GitHub
parent 456161dff5
commit ea94ea50a1
1 changed files with 129 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
README.md
View File

@@ -1,5 +1,7 @@
# Proxmox VE for WHMCS (Module) Provision & Manage
<img alt="Logo for the Proxmox VE for WHMCS module" src="zLOGO.png">
**Salvation, a free and open-source solution for beloved PVE!** If you love it, REVIEW & SHARE IT! ❤️
TNC Dev are looking for a co-developer to assist with finishing the project overhaul.
@@ -8,8 +10,6 @@
Please note: We are only looking for high-quality applicants with spare time.
As it stands, we won't have much spare dev time for PVEWHMCS in early 2025.
<img alt="Logo for the Proxmox VE for WHMCS module" src="zLOGO.png">
- Configure VM/CT plans with custom CPU/RAM/VLAN/On-boot/Bandwidth/etc
- Automatically Provision VMs & CTs in **Proxmox VE** from **WHMCS** easily
- Allow clients to view/manage VMs using the WHMCS Client Area
@@ -19,7 +19,7 @@
Repo: https://github.com/The-Network-Crew/Proxmox-VE-for-WHMCS/
## ❤️ RTFM: Read the Manual & Review the Module!
# ❤️ RTFM: Read the Manual & Review the Module!
**Please read the entire README.md file before getting started with Proxmox VE for WHMCS.** Thanks!
@@ -29,9 +29,9 @@ We're pretty much done overhauling the Module to suit our needs at The Network C
>
> _If you want it to remain free and fabulous, it could use a moment of your time in reviewing it._ **Thanks!**
## 🎯 MODULE: System Requirements (PVE/WHMCS)
# 🎯 MODULE: System Requirements (PVE/WHMCS)
### WHMCS must have >100 services!
## WHMCS must have >100 services!
New Biz: Fresh Installations/Businesses using WHMCS need to take note of the Service ID <100 case.
@@ -43,21 +43,43 @@ _If you don't have enough services (of any status) in WHMCS (DB: tblhosting.id),
To check, browse to your **latest** service in WHMCS, then check the URL - it will reveal the Service ID. If it is less than 100, subtract it from 100 to deduce how many "dummy services" you need to add in a dummy order.
Once over 100, it fits the requirement & you're good!
**Once over 100, it fits the requirement & you're good!**
### General Requirements
## General Requirements
- (WHMCS) v8.x.x stable (HTTPS)
- (WHMCS) **Service ID above 100**
- (PHP) v8.x.x (latest stable version)
- (PHP) max_execution_time = 300
- (Proxmox) VE v8.x (current)
- (Proxmox) 2 users (API/VNC)
- **(WHMCS)** v8.x.x stable (HTTPS)
- **(WHMCS)** **Service ID above 100**
- **(NET)** WAN Access: WHMCS to PVE
- **(VNC)** Special Requirements: PTR, etc.
- **(PHP)** v8.x.x (latest stable version)
- **(PHP)** max_execution_time = 300
- **(Proxmox)** 2 users (API & VNC)
- **(Proxmox)** VE v8.x.x (current)
## ✅ MODULE: Installation & Configuration
# ✅ MODULE: Installation & Configuration
**DON'T SKIP ANY PART OF THIS README.md - please don't raise pointless Issues - thank you!**
## 📋 1. PREP: Upload & Configure the Module
Check the System Requirements above, and resolve any blockers to using Proxmox VE for WHMCS.
### 👥 PVE: User x2 Requirement (API & VNC users)
#### Credentials: root account for each PVE host
**You must have a root account to use the Module at all.** Configured via WHMCS > Servers.
This is configured in the pam realm. We plan to allow selection in v1.2.9.
#### Credentials: VNC user for Console Access only
Additionally, to improve security, for VNC you must also have a Restricted User.
Configured in the _Module_ as detailed below, once you've added/restricted it in PVE.
### Installing: Getting ready to use the Module
Firstly, you need to upload, activate and make the WHMCS Module available to Administrators.
Once you've done all of that, in order to get the module working properly, you need to:
@@ -66,15 +88,15 @@ Once you've done all of that, in order to get the module working properly, you n
1. WHMCS Admin > Config > Servers > Add your PVE host/s (user: root; IP: PVE's)
2. WHMCS Admin > Addons > Proxmox VE for WHMCS > Module Config > VNC Secret (see below)
3. WHMCS Admin > Addons > Proxmox VE for WHMCS > Add KVM/LXC Plan/s
4. WHMCS Admin > Addons > Proxmox VE for WHMCS > Add an IP Pool
4. WHMCS Admin > Addons > Proxmox VE for WHMCS > Add an IPv4 Pool
5. WHMCS Admin > Config > Products/Services > New Service (create offering)
6. " " > Newly-added Service > Tab 3 > **SAVE** (links Module Plan to WHMCS Service type)
## 🥽 noVNC: Console Tunnel (Client Area)
## 🥽 2. noVNC: Console Tunnel (Client Area)
After forking the module, we considered how to improve security of Console Tunneling via WHMCS. We decided to implement a routing method which uses a secondary user in Proxmox VE with very restrictive permissions. This is due to be re-built again to further enhance security.
### To offer VNC via WHMCS Client Area
### How to offer VNC via WHMCS Client Area
1. Install & configure the module properly
2. Follow the PVE User Requirement info below
@@ -82,18 +104,11 @@ After forking the module, we considered how to improve security of Console Tunne
4. PVE and WHMCS on the same Domain Name*
5. Have valid PTR/rDNS for the PVE Address
noVNC has been overhauled. It isn't guaranteed, nor the project at all. :-)
If proxying, that is your responsibility to diagnose.
- Note #1 = You must use different Subdomains on the same Domain Name, for the cookie (anti-CSRF).
- Note #2 = If your Domain Name has a 2-part TLD (ie. co.uk) then you will need to fork & amend `novnc_router.php` - ideally we/someone will optimise this to better cater to all formats.
Else, PVE must be WAN-accessible and all other configs/reqs satisfied.
## 👥 PVE: User Requirements (API & VNC)
**You must have a root account to use the Module at all.** Configured via WHMCS > Servers.
Additionally, to improve security, for VNC you must also have a Restricted User. Configured in the _Module_.
### Creating the VNC user within PVE
### Creating the VNC User within Proxmox VE
1. Create User Group "VNC" via PVE > ` Datacenter / Permissions / Group`
2. Create new User "vnc" > `Datacenter / Permissions / Users` - Group: "VNC", Realm: pve
@@ -103,16 +118,43 @@ Additionally, to improve security, for VNC you must also have a Restricted User.
> Do NOT set less restrictive permissions. The above is designed for hypervisor security.
>
> However, if you wish for proper security, wait for VNC to be further improved.
> **However, if you wish for proper security, wait for VNC to be further improved.**
## ⚙️ VM/CT PLANS: Setting everything up
### Important info about Console Access
noVNC has been overhauled. It isn't guaranteed, nor the project at all. :-)
- Note #1 = You must use different Subdomains on the same Domain Name, for the cookie (anti-CSRF).
- Note #2 = If your Domain Name has a 2-part TLD (ie. co.uk) then you will need to fork & amend `novnc_router.php` - ideally we/someone will optimise this to better cater to all formats.
## 🌐 3. Networking: IPv4 Pools, IPv6, vmbr/SDN
### IPv4: Pool required for assignment
Please make sure you create an IP Pool with sufficient scope/size to be able to deploy addresses within it to your guest VMs and CTs. Else it won't be able to create a Service for you.
**Private IPs for PVE Hosts:** Note that VNC may be problematic without work due to the strict requirements introduced in Proxmox v8.0 (strict same-site attribute).
#### IPv6: SLAAC default, 2nd vNIC
Per The-Network-Crew/Proxmox-VE-for-WHMCS#33 there's SLAAC/DHCP/off available (2x vNICs) (May 2024).
You can of course add different config via PVE/`pvesh` manually, if you need to specify a prefix.
### vmbr / SDN: Config type
This depends on your configuration on the PVE Host/s - bridge (vmbr0 etc) or software-defined (SDN).
**If normal (bridged)** - use `vmbr` as the Network, then use `0` as the Interface ID - this makes up `vmbr0`.
**If SDN (Software Defined Network)** - use SDN Name for Network, leave Interface ID blank (= no suffix).
## ⚙️ 4. VM/CT PLANS: Setting everything up
These steps explain the unique requirements per-option.
Custom Fields: Values need to go in Name & Select Options.
> **Unsure?** Consult the zMANUAL-PVE4.pdf _legacy_ manual file.
### VM Option 1: KVM, using PVE Template VM
Firstly, create the Template in PVE. You need its unique PVE ID.
@@ -138,67 +180,15 @@ ie. If using ZFS for Templates, substitute local with volume name.
Then make a 2nd Custom Field `Password` for the CT's root user.
## 🌐 IPv4/v6: Networking (IP Pools)
## 🔄 5. PATCH: Updating the Module
Please make sure you create an IP Pool with sufficient scope/size to be able to deploy addresses within it to your guest VMs and CTs. Else it won't be able to create a Service for you.
WHMCS Admin > Addon Modules > Proxmox VE for WHMCS > Support/Health shows updates.
**Private IPs for PVE Hosts:** Note that VNC may be problematic without work due to the strict requirements introduced in Proxmox v8.0 (strict same-site attribute).
You can download the new version and upload it over the top, then run any needed SQL queries.
### IPv6: SLAAC default, 2nd vNIC
Please consult the **UPDATE-SQL.md** file, open your WHMCS DB & run the statements. Then you're done!
Per The-Network-Crew/Proxmox-VE-for-WHMCS#33 there's SLAAC/DHCP/off available (2x vNICs) (May 2024).
You can of course add different config via PVE/`pvesh` manually, if you need to specify a prefix.
## 💅 FEATURES: PVE v8.x bling
There are new features deployed into Proxmox VE upstream in the v8 branch which are exciting and should be added to this module.
### Proxmox v8.0
1. Create, manage and assign resource mappings for PCI and USB devices for use in virtual machines (VMs) via API and web UI.
2. (DONE) Add virtual machine CPU models based on the x86-64 psABI Micro-Architecture Levels and use the widely supported x86-64-v2-AES as default for new VMs created via the web UI.
### Proxmox v8.1
1. Secure Boot support.
2. Software Defined Networking (SDN).
3. New flexible notification system (SMTP & Gotify).
4. MAC Organizationally Unique Identifier (OUI) BC:24:11: prefix!
### Proxmox v8.2
1. Import Wizard for Guests.
2. Unattended PVE Install (answer file).
3. Backup Fleecing (local disk as data block buffer).
4. Firewall Preview (based on nftables).
### Proxmox v8.3
1. Software-defined Networking/Firewall.
2. Better guest importing from OVA/OVF.
3. Webhook target for system alerting.
4. Better change detection for PBS.
### Proxmox v8.4
1. Live migrate with mediated devices.
2. Support for external backup providers.
3. Host dir's, share with guests (virtiofs).
PVE Roadmap: https://pve.proxmox.com/wiki/Roadmap
## 🤬 ABUSE: Zero Tolerance (ZT)
This module has been overhauled and remains functionally-OK but not thoroughly tested nor reviewed.
Your support and assistance is always welcomed per the spirit of FOSS (Free Open-source Software)!
If you cannot accept this, do not download nor use the code. Complaints, nasty reviews, and similar behaviour is against the spirit of FOSS and will not be tolerated.
**Be grateful & considerate - thank you!**
## 🆘 HELP: Best-effort Support
## 🆘 6. HELP: Best-effort Support
**Before raising a GitHub Issue, please check:**
@@ -238,23 +228,53 @@ The more info/context you provide up-front, the quicker & easier it will be!
**If you don't read, listen or actively try, no help is given.**
## 🔄 UPDATING: Patching the Module
# 💅 FEATURES: PVE v8.x bling
WHMCS Admin > Addon Modules > Proxmox VE for WHMCS > Support/Health shows updates.
There are new features deployed into PVE upstream which are exciting and may be integrated.
You can download the new version and upload it over the top, then run any needed SQL ops.
**PVE Roadmap:** https://pve.proxmox.com/wiki/Roadmap
Please consult the **UPDATE-SQL.md** file, open your WHMCS DB & run the statements. Then you're done.
## Proxmox v8.4
## 🖥️ INC: Libraries & Dependencies
1. Live migrate with mediated devices.
2. Support for external backup providers.
3. Host dir's, share with guests (virtiofs).
## Proxmox v8.3
1. Software-defined Networking/Firewall.
2. Better guest importing from OVA/OVF.
3. Webhook target for system alerting.
4. Better change detection for PBS.
## Proxmox v8.2
1. Import Wizard for Guests.
2. Unattended PVE Install (answer file).
3. Backup Fleecing (local disk as data block buffer).
4. Firewall Preview (based on nftables).
## Proxmox v8.1
1. Secure Boot support.
2. Software Defined Networking (SDN).
3. New flexible notification system (SMTP & Gotify).
4. MAC Organizationally Unique Identifier (OUI) BC:24:11: prefix!
## Proxmox v8.0
1. Create, manage and assign resource mappings for PCI and USB devices for use in virtual machines (VMs) via API and web UI.
2. (DONE) Add virtual machine CPU models based on the x86-64 psABI Micro-Architecture Levels and use the widely supported x86-64-v2-AES as default for new VMs created via the web UI.
# 🖥️ INC: Libraries & Dependencies
- (MIT) PHP Client for PVE2 API (Dec 5th, 2022) https://github.com/CpuID/pve2-api-php-client
- (GPLv2) TigerVNC VncViewer.jar (v1.14.0 in repo) https://sourceforge.net/projects/tigervnc/files/stable/
- (MPLv2) noVNC HTML5 Viewer (v1.5.0 in repo) https://github.com/novnc/noVNC
- (GPLv2) TigerVNC VncViewer.jar (v1.15.0 in repo) https://sourceforge.net/projects/tigervnc/files/stable/
- (MPLv2) noVNC HTML5 Viewer (v1.6.0 in repo) https://github.com/novnc/noVNC
- (GPLv3) SPICE HTML5 Viewer (v0.3 in repo) https://gitlab.freedesktop.org/spice/spice-html5
- (MIT) IPv4/SN Validation (August 2012) https://github.com/tapmodo/php-ipv4/
## 📄 DIY: Documentation & Resources
# 📄 DIY: Documentation & Resources
- Proxmox API: https://pve.proxmox.com/pve-docs/api-viewer/
- TigerVNC: https://github.com/TigerVNC/tigervnc/wiki
@@ -262,7 +282,17 @@ Please consult the **UPDATE-SQL.md** file, open your WHMCS DB & run the statemen
- WHMCS: https://developers.whmcs.com/
- x86-64-ABI: https://gitlab.com/x86-psABIs/x86-64-ABI/-/jobs/artifacts/master/raw/x86-64-ABI/abi.pdf?job=build
## 🎉 FOSS: Contributions & Open-source
# 🤬 ABUSE: Zero Tolerance (ZT)
This module has been overhauled and remains functionally-OK but not thoroughly tested nor reviewed.
Your support and assistance is always welcomed per the spirit of FOSS (Free Open-source Software)!
If you cannot accept this, do not download nor use the code. Complaints, nasty reviews, and similar behaviour is against the spirit of FOSS and will not be tolerated.
**Be grateful & considerate - thank you!**
# 🎉 FOSS: Contributions & Open-source
If you'd like to contribute to the Module, please open a Pull on GitHub >> The-Network-Crew/Proxmox-VE-for-WHMCS
@@ -274,13 +304,13 @@ Thank you to psyborg® for the module's logo design! We love it.
FOSS is only possible thanks to dedicated individuals!
## Usage License (GPLv3) & Links to TNC & Co.
# Usage License (GPLv3) & Links to TNC & Co.
_**This module is licensed under the GNU General Public License (GPL) v3.0.**_
GPLv3: https://www.gnu.org/licenses/gpl-3.0.txt (by the Free Software Foundation)
### Corporate Sites: TNC & Merlot Digital
## Corporate Sites: TNC & Merlot Digital
**The Network Crew Pty Ltd** :: https://tnc.works