Installation and Configuration Guide

Step-by-step instructions for installing, configuring, and setting up the Synology WHMCS module, including Synology DSM preparation, WHMCS integration, email templates, and product configuration.

WHMCS Installation and Update
Synology part setup guide
Setup guide: WHMCS setup
Email Template (puqSynology Notification disk limit)
Add server (Synology NAS)
Product Configuration

WHMCS Installation and Update

Synology module WHMCS

Order now | Download | Community

System requirements

Requirement	Minimum
WHMCS	8.x+, 9.x+.
PHP	7.4, 8.1, 8.2, 8.3, 8.4
Synology DSM	7.x or higher
ionCube Loader	v15+

Note: The module uses ionCube encoding. Make sure ionCube Loader is installed and active on your server.

Download

Note: The module now uses ionCube 15, which provides universal out-of-the-box support for all encodings across modern PHP runtimes.

All versions can be found at this link: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Synology/

Older module versions for WHMCS 8 are available in the archive directory: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Synology/archive/

The module can be ordered and downloaded from PUQ Cloud:

Order Module: https://puqcloud.com/whmcs-module-synology.php
Documentation: https://doc.puq.info/books/synology-whmcs-module
All Versions / Download: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Synology/
Support: https://puqcloud.com/submitticket.php
Community: https://community.puqcloud.com/
Direct download link for the latest version:

wget https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Synology/PUQ_WHMCS-Synology-latest.zip

After downloading, extract the archive:

unzip PUQ_WHMCS-Synology-latest.zip

Installation

Step 1: Upload files

Extract the module archive and copy the puqSynology directory to the WHMCS servers module directory:

cp -r puqSynology /path/to/whmcs/modules/servers/

Or target path:

WHMCS_WEB_DIR/modules/servers/puqSynology

Once the files are uploaded, proceed to the WHMCS Setup Guide to configure the server and product.

Update

The update procedure is the same as installation — replace the existing files with the new version:

Download the latest version as described in the Download section.
Unzip the archive.
Replace the existing WHMCS_WEB_DIR/modules/servers/puqSynology directory with the new one.
Verify the version number in the module interface matches the new release.

Synology part setup guide

Synology module WHMCS

Order now | Download | Community

Here are the initial steps of configuring Synology devices to prepare them for use with the WHMCS module.

Note: At the beginning, you should prepare the appropriate domain with the correct DNS entries so that you can generate a correct SSL certificate for Your Synology NAS server.

1. Generate an SSL certificate for your domain.

Connect the certificate for all services that will be used in the server.(FTPS, System, Synology Drive, etc...)

04-synology-setup-1.png

2. Make sure the partition is formatted in BTRFS

07-synology-setup-4.png

3. Enable the user's home folder.

08-synology-setup-5.png

4. Enable all necessary file services (ie: FTP, FTPS, SFTP, etc.).

09-synology-setup-6.png

5. Create user groups with the necessary quotas and permissions.

05-synology-setup-2.png

06-synology-setup-3.png

Setup guide: WHMCS setup

Synology module WHMCS

Order now | Download | Community

Step 1: Add server in WHMCS

Navigate to:

System Settings -> Servers -> Add New Server

Enter the correct Name and Hostname

10-add-server-1.png

In the Server Details section, select the PUQ Synology module and enter the correct username and password of the Synology DSM account.
Click Test connection to verify.

11-add-server-2.png

Warning: The ACCESS HASH field is used to store the server access key and is updated automatically — do not edit it manually.

For more details, see Add server (Synology NAS).

Step 2: Create product in WHMCS

Navigate to:

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

In the Module Settings section, select the PUQ Synology module and the Server Group that contains your Synology server, then click Save Changes to load the configuration panel.

14-product-configuration-overview.png

Every setting in this panel (License key, Disk, Synology group, Notifications, History, Client Area and User rules) is described in detail on the Product Configuration page.

Email Template (puqSynology Notification disk limit)

Synology module WHMCS

Order now | Download | Community

Create an email template for customer notifications.

System Settings->Email Templates->Create New Email Template

Email Type: Product/service
Unique Name: puqSynology Notification disk limit

12-email-template-1.png

Subject:

Disk space usage {$disk_used_percentage} % - {$username}

Body:

Dear {$client_name},

This letter informs you that the disk space usage limit is coming to an end.

Product/Service: {$service_product_name}
Due Date: {$service_next_due_date}

Username: {$username}

Disk limit: {$disk_limit_bytes*$unit_coefficient} {$unit}
Disk used: {$disk_used_unit} {$unit} ({$disk_used_percentage} %)
Disk free: {$disk_free_unit} {$unit} ({$disk_free_percentage} %)

{$signature}

13-email-template-2.png

Add server (Synology NAS)

Synology module WHMCS

Order now | Download | Community

Add a new server to the system WHMCS.

System Settings->Servers->Add New Server

Enter the correct Name and Hostname

10-add-server-1.png

In the Server Details section, select the "PUQ Synology" module and enter the correct username and password for the Synology NAS web interface.
To check, click the "Test connection" button

11-add-server-2.png

Warning: WARNING: ACCESS HASH field Used to store the access key to the server and is updated automatically.

Product Configuration

Synology module WHMCS

Order now | Download | Community

Add a new product to WHMCS

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

In the Module Settings section, select the PUQ Synology module and the Server Group that contains your Synology server, then click Save Changes. The module then renders its modern configuration panel.

14-product-configuration-overview.png

Note: Select the Server Group and save the product first — the Synology group drop-down (in the Disk section) is populated live from the server assigned to that group.

At the top of the panel:

Module Name — the provisioning module (PUQ Synology).
Server Group — the WHMCS server group whose Synology server this product is provisioned on.
License key — your pre-purchased PUQ Synology license key. The validation status and the paid-through date are shown right below the field; the key must be active for the module to work.

Disk

20-product-config-disk.png

Note: Display only. The disk size/unit are shown to the client in the client area (and used for the usage-percentage chart and notifications). They do not enforce a limit on Synology. The real quota/permission limits must be configured on the Synology group selected here (Control Panel → User & Group → Group → Quota).

Disk size — disk space shown to the client (display only). 0 = Unlimited.
Disk unit — unit (MB / GB / TB) for the displayed disk space.
Synology group (enforces the real limits) — the pre-configured Synology group assigned to provisioned users, chosen from a live drop-down of the groups that actually exist on the server. Use the refresh button to reload the list. Configure the real disk quota / permissions on this group in DSM.

Notifications

21-product-config-notifications.png

Notify at % — usage threshold; when a client exceeds it, a low-disk-space notification is sent.
Email template — the WHMCS email template used for low-disk-space notifications (None to disable).

History

22-product-config-history.png

Save history (days) — how many days of disk-usage statistics to keep in WHMCS.

Client Area

23-product-config-client-area.png

Link to instruction — an optional URL; when set, a User manual button is shown in the client area.
Show password — how the password is presented in the client area (Show button / plain text / hidden).

User

24-product-config-user.png

Username rule — template for the generated username, using macros:
- Base: {client_id}, {service_id}
- Random: {random_digit_x}, {random_letter_x} (where x is the length, e.g. {random_digit_4})
- Date & time: {unixtime}, {year}, {month}, {day}, {hour}, {minute}, {second}
- Example: {client_id}-{service_id}-{random_digit_4}
- The generated name is automatically normalised to be Synology/DSM compliant, and collisions with other services are resolved automatically.
Password rule — generated password length (minimum 8), e.g. 12. The generated password always includes lowercase, uppercase, digit and special characters to satisfy the Synology DSM password-strength rules.