diff --git a/README.md b/README.md index 295ded2..424a213 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Proxmox VE for WHMCS (Module) Provision & Manage +Logo for the Proxmox VE for WHMCS module + **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. -Logo for the Proxmox VE for WHMCS module - - 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