Personal tools


Amazon Lightsail For WHMCS

From ModulesGarden Wiki
Jump to: navigation, search


About Amazon Lightsail For WHMCS

Amazon Lightsail For WHMCS will enhance your AWS provisioning business by letting you provide and manage Amazon Lightsail instances straight from your WHMCS system.

Your clients will receive the chance to handle their machines remotely through start, stop, and reboot options as well as access flexible graphs on their server usage.
Moreover, the module allows you to adjust all product features, and supervise the status of each supplied machine at all times.

  • Admin Area Features:
✔ Create/Suspend/Unsuspend/Terminate Server
✔ Start/Stop/Reboot Server
✔ Toggle Static IP Address
✔ View Server Status And Details
✔ View Remote Connection Details
✔ View Assigned Public And Private IP Addresses
✔ View Attached Disk Details
✔ View Scheduled Tasks
✔ Configure Product Details:
✔ Choose Region
✔ Choose Availability Zone
✔ Choose Platform:
✔ Linux/Unix
✔ Microsoft Windows
✔ Choose Blueprint
✔ Choose Instance Plan
✔ Define Snapshots Limit
✔ Choose Email Template
✔ Define Tag Name
✔ Provide User Data Script
✔ Provide Displayed Client Area Merge Fields Variables
✔ Toggle Static IP Address
✔ Toggle API Request Logging
✔ Choose Client Area Features
✔ Generate Configurable Options
✔ Run API Connection Test
  • Client Area Features:
✔ Start/Stop/Reboot Server
✔ View Server Status And Details
✔ View Provided Merge Field Variables
✔ View Remote Connection Details
✔ View Assigned Public And Private IP Addresses
✔ View Attached Disk Details
✔ View Scheduled Tasks
✔ View Tasks History
✔ View Usage Graphs For Given Time Period
✔ View/Create/Edit/Delete Firewall Rules
✔ View/Create/Restore/Delete Snapshots
✔ Provide SSH Key During Order
  • Configurable Options:
✔ Region
✔ Instance Plan
✔ Blueprint
✔ Static IP Address
✔ Snapshots Limit
  • Available Blueprints:
✔ Linux/Unix Applications:
✔ Drupal
✔ GitLab CE
✔ Joomla
✔ LAMP (PHP 7)
✔ Magento
✔ Nginx
✔ Node.js
✔ Plesk Hosting Stack
✔ Redmine
✔ WordPress
✔ WordPress MultiSite
✔ Linux/Unix OS:
✔ Amazon Linux
✔ CentOS
✔ Debian
✔ FreeBSD
✔ openSUSE
✔ Ubuntu
✔ Microsoft Windows:
✔ SQL Server 2016 Express
✔ Windows Server 2012 R2
✔ Windows Server 2016
✔ Any Other Applications And OS When Available
  • General Info:
✔ Multi-Language Support
✔ Supports PHP 7.2 Up To PHP 7.4
✔ Supports WHMCS Themes "Six" And "Twenty-One"
✔ Supports WHMCS V7.10 And Later
✔ Easy Module Upgrade To Open Source Version

Installation and Configuration

This tutorial will show you how to successfully install and configure Amazon Lightsail For WHMCS smoothly.

We will guide you step by step through the whole process.


1. Log in to our client area and download the module.
ALS 1.png
2. Upload and extract the extension into the main WHMCS directory.

Extracted files in your WHMCS directory should look like this:

Note: The module uses modified AWS files provided by WHMCS in the 'vendor' folder. In order for the module to work properly, it is necessary to overwrite these files with the files from the module.
Please keep this in mind when installing a WHMCS update, because then you may also need to overwrite these files with the files from the module again.

ALS 2.png
3. When you install Amazon Lightsail For WHMCS for the first time, you have to rename the 'license_RENAME.php' file.

The file is located in '/yourWHMCS/modules/servers/AmazonLightsail/license_RENAME.php'. Rename it from 'license_RENAME.php' to 'license.php'.

ALS 3.png
4. In order to configure your license key, you have to edit the previously renamed 'license.php' file.

Enter your license key between the quotation marks as presented on the following screen.
You can find your license key in our client area → 'My Products'.

ALS 4.png
5. Now, set up the 'storage' folder as recursively writable.

This folder is available at '/yourWHMCS/modules/servers/AmazonLightsail/'.

ALS 5.png
6. The last step is setting up the queue cron job.

It will be used to assign IP addresses to created machines as well as to obtain passwords for Windows OS.

php -q /yourWHMCS/modules/servers/AmazonLightsail/cron/cron.php queue

It is suggested to run the cron every 5 minutes.

Configuration of Server

Before you can continue, you must generate your Amazon Lightsail access details. You will need them to connect with the server successfully.

Underneath, you will find detailed instructions on where to find this information.

7. Firstly, log in to your Amazon AWS Management Console and find 'My Security Credentials' section under your account name dropdown.
ALS 6.png
8. There, move to the 'Access Keys (access key ID and secret access key) section.
ALS 7.png
9. If you do not have any active keys yet, then press the 'Create New Access Key' button to generate a new set of details.
ALS 8.png
10. A modal with Access Key ID and Secret Access Key will appear, so copy this information and keep it safe. You may also download a suitable file with these details.

Note: This is the only place where you can find the corresponding secret key later. It will not be visible next to the Key ID in the panel.

ALS 9.png
11. Now, log in to your WHMCS and proceed to 'Setup' 'Products/Services' 'Servers' and press 'Add New Server'.

Note: If you have WHMCS V7.8.X or later, we recommend using 'previous experience' of server configuration instead of the new wizard tool.

ALS 10.png
12. Next, enter your server name and select 'Amazon Lightsail' from the 'Type' field.

Now, provide the previously generated 'Access Key ID' and 'Secret Access Key'. Then, check the connection and if successful, save the changes.

Important: If you are using WHMCS V7.8.X, then a fatal error may occur when trying to save server settings without providing any hostname or IP address details, even if the module configuration does not require them.
In this case, try to provide anything in the hostname field. For this reason, 'Test Connection' may sometimes not work. Please note that this is a bug that occurs in WHMCS, not the module itself.

ALS 11.png
13. Now, it is time to create a server group. To do so, click on 'Create Server Group' .
ALS 12.png
14. Enter a name, click on your previously created server, press 'Add' and afterward 'Save Changes' .
ALS 13.png

Configuration of Product

15. In order to create and configure a product, go to 'Setup' 'Products/Services' 'Products/Services'.

Click on 'Create a New Group'.

ALS 14.png
16. Enter your product group name and press 'Save Changes'.
ALS 15.png
17. Once you have added a product group, you can create a new product.

To do so, first click on 'Create a New Product'.

ALS 16.png
18. Afterward, choose your product type, enter your product name, choose module and the product group from the dropdown menus. Press 'Continue'.
ALS 17.png
19. Now, go to the 'Module Settings' section and choose your previously created server group from the dropdown menu.

The module should automatically save and reload the settings. If not, click on the 'Save Changes' option manually.

ALS 18.png
20. Now, you can start configuring the settings of the offered server.

Just like when creating a new virtual machine in your Lightsail panel, here also you can configure such options as:

  • Region - Choose a geographical area with a set of Lightsail resources. The closer the instance is to your users, the less latency they will experience.
  • Availability Zone - Each AWS Region has up to six 'Availability Zones' . By launching instances in separate 'Availability Zones' , you can protect applications from the failure of a single location.
    To ensure that resources are distributed across the 'Availability Zones' for a region, they are independently mapped to identifiers for each account.
    For example, 'us-east-2a' might not be the same location as 'us-east-2a' for another account. Learn here more about 'Availability Zones' in Amazon Lightsail.
  • Platform - Lightsail images are available on two platforms: 'Linux/Unix' or 'Windows' . Once you choose a platform, you can select a corresponding blueprint of the operating system.
  • Blueprint - select which base operating system (OS) with or without a preinstalled application should be installed. You can select between an Ubuntu Server image with an application or development stack preinstalled,
    or a Windows OS with SQL Server 2016 Express preinstalled. Note that available options depend on the previously selected 'Platform' and some blueprints cannot be launched with certain Instance Plans.
  • Instance Plan - Select resources available for the instance. Please note that the better the instance resources, the higher the monthly costs. Moreover, some blueprints require more powerful resources.
    You can read more about Amazon Lightsail pricing here.
  • Snapshots Limit - Set a limit for a maximum number of taken manual snapshots that the client can have at a given time. Set -1 for unlimited.
    Please remember that Amazon takes fees for each snapshot - click here to find out more.
  • Log API Requests - Enable to allow storing information on API requests in the 'Module Log' section in your WHMCS.
  • Email Template - Choose an email template that will be used to send messages to clients after the successful creation of the instance.
  • Tag Name - Define a tag name; this label will be assigned to Lightsail resources.
  • Static IP Address - Decide whether to assign to an instance a static, fixed, and public IP address. Note that his will be done a moment after instance creation during the next cron execution.
    You can find out more about Lightsail static IP addresses here.
  • Auto Generate SSH Key - If you enable, SSH key pairs will be automatically generated if clients do not provide them during the instance creation.
  • User Data - You can specify user data to configure an instance or to run a configuration script during launch. This field is optional.
    Tutorial on how to use this option can be found here.
  • Client Area Section - Here you may provide the HTML code and display the content in the client area. Before using this option, please make sure that you are familiar with the instruction that can be found here.
ALS 19.png
21. Next, choose which client area features will be available for your clients.
ALS 20.png
22. At the end of the configuration process, you can decide whether you want to generate configurable options for the product.

Configurable options can be used by your clients to select each virtual machine parameters individually while placing an order.
Otherwise, if configurable options are not defined, then the fixed parameters specified in the earlier configuration will be used instead.

ALS 21.png
If you decide to use configurable options, press on the 'Create' button and select which options you want to generate.
Note that the configuration for disabled options will still be taken from the configuration of the main product.
More information about how to use configurable options can be found here or in the official WHMCS documentation.
ALS 22.png
Finally, when everything is set, do not forget to 'Save Changes' .

Client Area Section

The 'Client Area Section' option gives you the possibility to provide the HTML code and display the content in the client area.
Before using this option, please make sure that you are familiar with the following instruction.

Important! If you come across some errors with displaying values in the client area, please check if you closed brackets {}.

1. The values that can be displayed in the client area:

{$serviceid}, {$pid}, {$serverid}, {$domain}, {$username}, {$password}, {$producttype}, {$moduletype}, {$configoptionX}, {$server}, {$serverip}, {$serverhostname}, 
{$serverusername},{$serverpassword}, {$serveraccesshash}, {$serversecure}, {$serverport}, {$bundles}, {$region}, {$zone}, {$platform}, {$blueprint}, {$snapshotsLimit}, 
{$tagName}, {$userData}, {$emailTemplate}, {$userid}, {$orderid}, {$packageid}, {$server}, {$regdate}, {$domain}, {$paymentmethod},{$firstpaymentamount}, {$amount}, 
{$billingcycle}, {$nextduedate}, {$nextinvoicedate}, {$termination_date}, {$completed_date}, {$domainstatus}, {$username}, {$password}, {$notes}, {$subscriptionid}, 
{$promoid}, {$suspendreason}, {$overideautosuspend}, {$overidesuspenduntil}, {$dedicatedip}, {$assignedips}, {$ns1}, {$ns2}, {$diskusage}, {$disklimit}, {$bwusage}, 
{$bwlimit}, {$lastupdate} 

2. On/Off values that you can choose from:

{$clientAreaHistory}, {$clientAreaMetric}, {$clientAreaShowDisk}, {$logApiRequests}, {$staticIpAddress}, {$clientAreafirewall}, {$clientAreasnapshots}, 
{$autoGenerateSSHKey}, {$clientAreaServiceActions} 

3. Access values provided in Arrays:

Please make sure that the provided value complies with this pattern {$ arrayName . fieldName } for example: {$customfields.InstanceTags}, {$}

  • {$clientsdetails} :
{.userid}, {.id}, {.uuid}, {.firstname}, {.lastname}, {.fullname}, {.companyname}, {.email}, {.address1}, {.address2}, {.city}, {.fullstate}, {.state}, 
{.postcode}, {.countrycode}, {.country}, {.phonenumber}, {.tax_id}, {.password}, {.statecode}, {.countryname}, {.phonecc}, {.phonenumberformatted}, {.telephoneNumber}, 
{.billingcid}, {.notes}, {.twofaenabled}, {.currency}, {.defaultgateway}, {.cctype}, {.cclastfour}, {.gatewayid}, {.securityqid}, {.securityqans}, {.groupid}, {.status}, 
{.credit}, {.taxexempt}, {.latefeeoveride}, {.overideduenotices}, {.separateinvoices}, {.disableautocc}, {.emailoptout}, {.marketing_emails_opt_in}, {.overrideautoclose}, 
{.allowSingleSignOn}, {.email_verified}, {.language}, {.isOptedInToMarketingEmails}, {.lastlogin} 
  • {.email_preferences} :
{.general}, {.invoice}, {.support}, {.product}, {.domain}, {.affiliate} 
  • {$customfields} :
{.InstanceId}, {.InstanceTags}, {.sshKey} 

As an example, we provide:

ALS 22 1.png
As you can see, all data is available here:
ALS 22 2.png

SSH Keys

In the 'Custom Fields' tab you will find a 'SSH Public Key' field which is displayed to clients on the order form by default.

Please be aware that this field can be left as optional for Linux/Unix as well as Windows platforms.
Int that case the necessary keys will be generated by Amazon itself and will be displayed in the 'Connection Details' window.

The following formats are supported:

  • OpenSSH public key format (the format in ~/.ssh/authorized_keys)
  • Base64 encoded DER format
  • SSH public key file format as specified in RFC4716
  • SSH private key file format must be PEM (for example, use ssh-keygen -m PEM to convert the OpenSSH key into the PEM format)

Create an RSA key. Amazon Lightsail does not accept DSA keys. The supported lengths are 1024, 2048, and 4096.

If you would like to limit the possibility of entering the key e.g. only to the 'ssh-rsa' format, you can use the regular expression in the validation field, such as:

#ssh-rsa AAAA[0-9A-Za-z+/]+[=]{0,3}( [^@][email protected][^@]+)?# 

Remember that API allows such action only once, during the initial VM creation.

ALS 23.png


Admin Area

Amazon Lightsail For WHMCS allows you to monitor and manage your customer server instance from the admin area of your WHMCS system.

This includes the supervision of such features as:

  1. Configurable options which enable you to view the chosen server details
  2. Module commands to allow easy and quick management of the server
    Important: Currently Change Package command can be only used for enabling or disabling the 'Static IP Address' option.
    The change of the instance plan is currently not supported due to the complex nature of its implementation.
  3. Service actions, including: Start, Stop and Reboot the server as well as display Connection Details for remote connection to the instance
  4. Instance details that provide the current status, resources and options set
  5. Attached disk details
  6. List of scheduled tasks with their type, status and date
ALS 24.png


Due to configurable options, you are able to offer a product which your clients can tailor to their needs.
Additionally, you are able to set up pricing for each configurable option, which makes your offer even more competitive.

At this moment clients can also optionally provide their public SSH key.
Please note that this key should be in one of the OpenSSH standard formats which are supported by API, e.g. ssh-rsa.

ALS 25.png

Client Area

Client area interface of Amazon Lightsail should look like the one on the screen below.
As you can see, the control panel contains useful details of a managed server.

The module allows your customers to easily start, stop and reboot their server instance through pressing the corresponding buttons.
Clients can also take instance snapshots, manage firewall, check the server status with its details, view assigned public and private IP address.
Moreover it is easily to see disk details, access usage graphs as well as control the list of currently scheduled tasks.

ALS 26.png
If the clients want to connect to the instance, by clicking on the 'Connection Details' button, the data will be displayed, which will allow them to make a remote connection.

This data will vary depending on whether the instance is based on Linux/Unix or Windows as well as on whether the public SSH key was provided during the order.

To connect to an instance on the Linux/Unix platform, clients can use an SSH client application such as PuTTY (learn more).
Depending on the configuration of the instance, the popup window will display the instance IP address, connection protocol, username, and private or associated public SSH key.

For Windows-based instances, clients can also connect to their instance using an RDP client such as Remote Desktop Connection (learn more).
Depending on the configuration of the instance, the popup window will display the instance IP address, connection protocol, Windows username and generated password in its decoded or encoded form.
If Windows password is encoded it can still be somehow decrypted using this Amazon method.

ALS 27.png

Task History

To access the history of a machine, simply press the 'Tasks History' button. Afterward, the customer can see all the actions performed on the instance, as well as their status.
ALS 28.png

Usage Graphs

Through pressing the 'Usage Graphs' button, clients will be moved to the page where they can view generated graphs on CPU usage and network traffic as well as check vital statuses.

They can also switch the timeline of graphs by choosing a new one from the 'Edit' dropdown menu. Clients can pick between '1 hour', '6 hours' '1 day', '1 week' and '2 weeks'.

ALS 29.png


In the 'Firewall' section clients can manage their firewall settings to control which ports are open to the public.

Note that when a Lightsail instance is created, some network ports are open by default so the instance can accept public network connections.

Clients can add here new rules, edit existing ones or delete them.

ALS 30.png
When adding or editing an existing rule, clients manually control which ports and protocols (TCP or UDP) on their instances will accept connections.
The selection of predefined application rules are also available so that protocol and port range fields will be automatically fulfilled.

You can also find a complete list of port settings, application layer protocol types, and transport layer protocol types in this Amazon documentation.

ALS 31.png


A snapshot is a point in time backup of the client's instance.

In the snapshots section clients can create new snapshots of their instances, view previous snapshots or restore instance from a snapshot.
The number of allowed snapshots the client can have taken at given time can be limited in the product's module settings or by configurable options.

Please note that Amazon also takes additional fees for each created snapshot.

ALS 32.png
To create a new snapshot simply provide its name and press the 'Create' button.

Note that the name can contain from 2 to 200 characters which can be only alphanumeric, numbers, periods, dashes or underscores.
If Windows is used for instance, it should be also stopped before creating a snapshot.

ALS 33.png
Once the snapshot is created, it can be restored using the following button.
ALS 34.png
Before restoring a snapshot remember that all previous data on the disk will be lost.
ALS 35.png


1. If you need to generate any of the configurable options once again, you must delete the previously created ones.
Only then will it be possible to generate a new configurable option. Read more about configurable options here.
2. When you upgrade WHMCS, please be aware that the module uses custom modified AWS files located in the main WHMCS 'vendor' directory, and their unmodified versions are also delivered by WHMCS itself.
In this case, the WHMCS upgrade may overwrite these files to their default form so you may need to overwrite these files again with the files delivered with the module.
3. Names of snapshots created by clients will have added prefixes with instance domains visible only in your Amazon Lightsail panel.

This is because Amazon requires snapshot names to be unique to each AWS Region in your Lightsail account, not just within a single instance.
Otherwise, customers at WHMCS could often see the message that a particular snapshot name has already been taken up by someone else.
For the domain prefix name, 55 characters from 255 previously available for the snapshot name have been reserved .

Update Instructions

An essential guidance through the process of updating the module is offered here.
After the module update we strongly recommend to open one of the product's module settings tab to make sure that all upgrading processes have been completed successfully.

Keep in mind that there is a quick and easy option in our client area that will let you upgrade the license of your module to an open source version at any time - and at a lower price!
To take advantage of it, simply use the License Upgrade button located on the product's page and a discounted invoice will be generated automatically.

Common Problems

1. When you have problems with connection, check whether your SELinux or firewall does not block ports.
2. If there is a problem with obtaining details in WHMCS for an already existing instance, make sure that the correct region is selected in the product configuration.
Otherwise, if the regions do not match, there can be a problem with fetching details of the instance.
3. If you are using WHMCS V7.8.X, a fatal error may occur when trying to save server settings without providing any hostname or IP address details.
Our module does not require this field to be filled out, but in that case, try to provide anything in the hostname field. Please note that this is a bug that occurs in WHMCS, not in the module itself.
WHMCS Modules
WHMCS Translations
cPanel Modules
Magento Extensions
Magento Themes
PrestaShop Modules
Blesta Extensions
Amazon Lightsail For WHMCS