» SmartFoxServer 2X License Management System

The SmartFoxServer 2X License Management System has been developed to give our customers full control over the licenses they purchased, maximum freedom in choosing their hosting partners (including those offering cloud services) and large flexibility when it comes to reassigning licenses to new SFS2X instances.

The following paragraphs describe the general architecture of the system and provide detailed operating instructions. Troubleshooting and FAQ sections at the bottom offer guidance in case of issues.

Whenever contacting the SmartFoxServer Support Team as suggested in the following paragraphs, you can use this email address:


» Architecture

The SmartFoxServer 2X License Management System is based on three components: the License Server, one or more SmartFoxServer 2X instances and the AdminTool's License Manager module. Let's go into details describing each component, starting from the main one.

» License Server

The License Server is a centralized server hosted by the SmartFoxServer Team on an the highly available and scalable infrastructure provided by Amazon Web Services. The License Server enables our customers to manage their licenses very easily and efficiently through a centralized console showing the status of all the licenses through a simple web interface (see the Licenses Administration dashboard paragraph below for detailed informations).

As the License Server is also responsible for validating the licenses assigned to SmartFoxServer 2X instances, the only requirement is that such instances must be able to connect to the License Server using a regular HTTPS connection (TCP 443), which guarantees maximum security of communication and ease of use. Find more about this subject in the Setting up a license paragraph.

» SmartFoxServer instance

Within the Licenses Management System, each SmartFoxServer 2X is responsible for contacting the License Server to validate the license assigned to it by means of the AdminTool's License Manager module.

The License Server is contacted both during the startup of the server (license initialization) and at runtime (license validation). In case the License Server goes down for whatever reason (scheduled maintenance, unexpected hardware failure, etc) all SmartFoxServer instances will keep working normally for 48 hours before reverting to the Community Edition version (and as such limiting the maximum number of concurrent users to 100).

If properly configured, SmartFoxServer takes care of sending alerts by email to inform the system administrator that the License Server can't be reached. The grace period can be used to analyze the problem and take the appropriate actions (see the Troubleshooting section below).

» License Manager

The License Manager module of the SmartFoxServer 2X Administration Tool is used to assign a license to a SFS2X instance and test the connection between the instance and the License Server.
Please read the public documentation for usage instructions.


» Licenses Administration dashboard

The Licenses Administration dashboard is the place where you can control the status of all your SmartFoxServer 2X licenses. You can reach it at this URL: https://lms.smartfoxserver.com/.

In order to access the dashboard you need the username and password you received by email the first time you purchased a SFS2X license. The username is your email address, while the password is randomly generated by the system. This can be changed to your password of choice.

We recommend, if possible, that you always buy your licenses under the same company name, to avoid having your licenses scattered over multiple accounts.

If you need to change your account details (in case you changed the administrator's email address or the company name), please send an email to the SmartFoxServer Support Team. Please always provide your company name and the email address associated with your account.

Enter the access credentials in the dashboard main page; after a successful login, the main interface to manage your licenses is displayed. In the header, the main menu gives access to the following sections.

» Licenses

This overview page shows the list of licenses you own, divided in two tabs depending on their status (see below). The list is not refreshed automatically, so in case the status of one of the licenses changes, click the Refresh button.
Use the Buy more button to visit the SmartFoxServer website's Buy page to add more licenses to your account. As licenses can be perpetual or elastic (based on a rechargeable credit), the interface can vary accordingly. We strongly recommend that you check the linked page to understand the difference between the two.

Each license in the list is described by the following information:

Click on the View button to show full information on the selected license, and access the license administration controls.

License details

On the license details page, the code of the selected license is highlighted, together with the status icon (see above). In case a custom name is assigned to the license, this is displayed in place of the license code.
The custom name can be useful to know which game / application / server the license is assigned to, and easily locate it among other licenses on the overview page. In order to set it, click on the Rename button and enter the name in the modal window that pops up.

The Configure button is available for elastic licenses only; it allows to set the maximum number of CCU for the license and the active add-ons. Check the Configuring an elastic license paragraph for detailed information.

If the license is perpetual and has a limited max. number of CCU, the Configure button is substituted by the Upgrade button. Click it to visit our online shop to extend the number of CCU if needed.

Under the license name/code, the license code and status are displayed, followed by the full license details and administration controls, divided into four groups; please note that the Subscription group is available if the license is elastic only.

Subscription (elastic licenses only)
Configuration
Allocation

In case the deprecated file-based license system is used (must be requested to the SmartFoxServer team for specific reasons), all the details above are substituted by the fixed IP address to which the license is bound.

Other

» Billing

The billing page shows the credit consumption (or increase) of your elastic licenses on a daily basis. Select one of the licenses listed in the first dropdown, select the period (last twelve months available) and hit the Show button to get the list of transactions.

The base cost of an elastic license depends on the maximum number of concurrent users (CCU) allowed to connect to the SFS2X instance to which che license is assigned. Such cost is charged on a daily basis using this formula: daily charge = pcm * ccumax / 30 where:

Click on the Info button in the billing entry description to check the transaction details. If you activated one or more optional license add-ons, or changes have been made to the initial license configuration, detailed information is provided.

As licenses can be created or modified at any time of the day, refunds are often due as described in the example below. In this case actual license usage is calculated rounding the time to the previous full hour.

Billing example

The image above shows a typical billing report; let's go through it starting from the bottom.

  1. On January 18th at 14:50 the selected license was purchased. The first row of the table shows the initial credit assigned to the license. The second one instead is the actual initial charge. The details show the daily cost for the number of CCU set at creation time and the subscription name (A). The daily price was calculated using the above formula, but due to the time of the day when the license was created, the customer was charged for the remaining hours of the day only (rounded – in this example 10 hours, from 14:00 to 24:00) and the corresponding fraction of the daily price was refunded (B).
  2. From January 19th to 21st the full daily price was charged.
  3. On January 21st at 15:01 the license configuration was changed by the customer: the maximum CCU was increased from 1500 to 4000 and the Analytics add-on was activated. The full new daily cost was charged (C) together with the monthly price of the add-on (D).
    As the customer already paid for the whole day (previous table row), a refund was also due (E+F). The refund is based on the time at which the configuration change occurred, rounded to the full hour; this formula is used: refund = dcp + ((dcn - dcp) * h/24) where:
    • dcn is the new daily charge
    • dcp is the previous daily charge
    • h is the rounded hour of the day at which the configuration change occurred
    In the example above the change was made at 15:00 (rounded).
  4. Starting from January 22nd, the new full daily price is charged.
  5. Maybe because the license was running out of credit, on January 22nd the customer also recharged it with an amount of 100€.

» Account

This page shows your License Server account details: customer identifier, name, contact and email address of the account owner. Other than for login purpose, the email address is used by the License Server to send specific informations to the licenses administrator whenever a change occurs (new license added, password changed, license details modified, elastic license credit depletion approaching, etc). Make sure this address is constantly monitored!

The Reset password button can be clicked to start the password update procedure.

» Help

Click the Help menu item to visit the current documentation page.

» Logout

Click the Logout menu item to return to the login page.


» Setting up a license

» Prerequisites

Before assigning a license to a SFS2X instance as described in the next paragraph, you have to check if the server on which SFS2X is installed is able to communicate with the License Server by means of a standard HTTPS connection. If the server hosting SFS2X is behind a firewall (software or hardware), simply make sure that the traffic over TCP port 443 is not blocked.

» Setup

In order to setup a license on a SFS2X instance, execute the following steps. Make sure you read the License Manager documentation for additional informations.

  1. Open the AdminTool and connect to the SFS2X instance.
  2. Open the License Manager module.
  3. Access the Licenses Administration dashboard, locate the license and click the View button.
  4. Copy&paste the license code in the License code field of the License Manager module.
  5. In the License Manager module, click the Submit button to save the license code.
  6. Click the Test license button: if a warning is displayed, then the SFS2X instance is not able to validate the license on the License Server; otherwise the license details are reported.
    In case of license validation issues, check the Troubleshooting section below.
  7. Stop and restart SmartFoxServer.
  8. Go back to the Licenses Administration dashboard and refresh the licenses list by hitting the Refresh button: the license should now be reported as running () and the SmartFoxServer's public IP address and version should be displayed.

As an additional step, you might want to check the startup log of SmartFoxServer: the main license details are displayed at the beginning of the log, like this for example:

17:34:20,284 INFO  [main] v2.SmartFoxServer     - Boot sequence starts...
17:34:20,334 INFO  [main] v2.SmartFoxServer     - 
 _____ _____ _____    ___ __ __    _____ _____ _____ _____ 
|   __|   __|   __|  |_  |  |  |  | __  |     |     |_   _|
|__   |   __|__   |  |  _|-   -|  | __ -|  |  |  |  | | |  
|_____|__|  |_____|  |___|__|__|  |_____|_____|_____| |_|

17:34:21,527 INFO  [main] v2.SmartFoxServer     - Validating license...
                                                  (this process may take a few seconds)
17:34:32,460 INFO  [main] v2.SmartFoxServer     - Connection to the License Server established
17:34:32,470 INFO  [main] v2.SmartFoxServer     - License retrieved successfully
17:34:32,685 INFO  [main] v2.SmartFoxServer     - License loaded:

===================================
LICENSE DETAILS
-----------------------------------
Type            : Retail
Max users       : Unlimited
===================================

» Moving a SFS2X instance to a new server

When moving a SFS2X instance to a new server, for example if you are changing your hosting provider for the production environment, you have to release the license allocation in the Licenses Administration dashboard, or SFS2X won't be able to retrieve its license from the new location.
In order to do this, execute the following steps.

  1. Stop the SFS2X instance.
  2. Access the Licenses Administration dashboard and locate the license: its status should be allocated () or running ().
  3. Select the license by clicking on the View button.
  4. Scroll to the Allocation details and click on the Deallocate button: the license status should be reverted to free ().
  5. Move the SFS2X instance to the new server.
  6. Assign the license back to the SFS2X instance by following the steps described in the Setting up a license paragraph.

A common scenario which also requires the steps above to be executed is a server instance termination in a cloud environment. When the server is terminated and restarted, it might be unable to retrieve its license: you can test this using the Test license button in the AdminTool's License Manager module. If the license is reported as being already allocated, you should reset its allocation as explained.

For SmartFoxServer 2X versions before 2.9 you will need to reset the license allocation even if you change the network interface of the server on which the SFS2X instance is installed.

IMPORTANT NOTE
An alternative to manual license deallocation is to change its allocation mode from Static to Dynamic. In this case the license is always assigned to the last SFS2X instance requesting it on startup. While this can be useful to avoid the manual procedure described above, it should be used carefully: in fact a new SFS2X instance can "steal" the license to a previously running instance, causing its reversal to the Community Edition mode.

» Transferring a license to a new SFS2X instance

There are cases in which you need to transfer a license to a new SFS2X instance, for example when you complete coding and testing in your development environment and you want to install your application/game in production, or in case you installed a new SFS2X version in the same environment of the previous one. In order to make your license work again, you have to release the license allocation in the Licenses Administration dashboard.
Please follow these steps (suppose you need to move the license from instance SFS2X-DEV to instance SFS2X-PROD).

  1. Open the AdminTool and connect to the SFS2X-DEV instance.
  2. Open the License Manager module.
  3. Remove the license code from the License code field and click the Submit button.
  4. Stop and restart SFS2X-DEV: it should now load the default Community Edition license.
  5. Access the Licenses Administration dashboard and locate the license that was assigned to SFS2X-DEV: its status should still be allocated () or running ().
  6. Select the license by clicking on the View button.
  7. Scroll to the Allocation details and click on the Deallocate button: the license status should be reverted to free ().
  8. Assign the license to the SFS2X-PROD instance by following the steps described in the Setting up a license paragraph.

The same important note displayed in the previous paragraph applies here.

» Configuring an elastic license

If you own an elastic license, at any time you can change its configuration to fine tune the daily spending based on the application/game traffic. You can do it by following these steps.

  1. Access the Licenses Administration dashboard and locate the license to be configured.
  2. Select it by clicking on the View button.
  3. Click on the Configure button at the top of the page; the modal shown in the picture pops up:
  4. Set the new maximum concurrent users allowed to connect to the SFS2X instance and enable/disable one or more optional add-on.
  5. Click on the Review button to recap the updated daily / monthly cost of the license for the selected configuration:
  6. Click on the Proceed button to apply the changes. If the license cost is increased or new monthly add-ons are activated, the license credit is decreased accordingly.
  7. Open the AdminTool's License Manager module and connect to the SFS2X instance to which the license is assigned.
  8. Click on the Reload license button to force SFS2X to request the new settings to the License Server and apply them. If this step is not executed, the SFS2X instance will retrieve the new configuration anyway, within the next three hours.

Check the Licenses Administration dashboard's Billing page description for a complete example showing the billed costs when the license configuration is changed.

» Recharging an elastic license

The Elastic license is based on a rechargeable credit which is consumed by a daily charge whose amount depends on the license configuration: maximum concurrent users and active add-ons.

The license is considered exhausted (status icon: ) when the residual credit is not enough to cover the amount being charged. In this case, the SFS2X instance to which the license is assigned is reverted to the Community Edition. In order to avoid this as much as possible, three alerts are sent by email when the credit depletion approaches: one week, three days and one day before.

The credit can be recharged at any time following this procedure.

  1. Access the Licenses Administration dashboard and locate the license to be recharged.
  2. Select it by clicking on the View button.
  3. Scroll to the Allocation details and click on the Add button near the currently available credit; the modal shown in the picture pops up:
  4. Set the credit amount you want to purchase and click on the Review button. The popup now shows the Buy credit button:
  5. Click on the Buy credit button to visit the SmartFoxServer online shop, where the "SmartFoxServer 2X elastic license 10€ credit" product is automatically added to your cart; the product's quantity is used to match the total credit you want to purchase, rounded to the upper 10€ as mentioned in the previous image.
  6. Proceed with the shopping cart checkout and make the payment. If you pay with a credit card or PayPal account, the new credit will be added to your license automatically, as soon as the payment is received. If you pay by wire transfer instead, you will have to wait for us to receive the money and manually recharge your license.

If any issue should occur during the process above, please contact our support team.

Please note that in case the license is recharged after its status became exhausted, the SmartFoxServer instance must be manually restarted.


» Troubleshooting

This section is meant to help you analyze any license-related issue you might encounter while operating SmartFoxServer 2X. In case you can't solve your problem, or it isn't listed here, please contact the SmartFoxServer Support Team by email (you can find the address at the beginning of this page).

Where applicable the following legend is used to describe in which scenarios the issues are reported:

» Licensing issues

  1. The SFS2X instance is unable to contact the License Server ()
    Make sure the License Server is up and running by visiting this URL with a browser, then:
    • if the page can be loaded and the login form of the Licenses Administration dashboard is displayed, see B;
    • if the page can't be loaded and the same happens with other websites, a large network failure might be in progress and prevent you to reach it: see C;
    • if the page can't be loaded for no apparent reason, the License Server might be down: see D.
  2. The SFS2X instance is unable to contact the License Server but I can reach the Licenses Administration dashboard using the browser ()
    Either a software firewall located on the server hosting the SFS2X instance or an hardware firewall in front of it is blocking the HTTPS communication (TCP port 443). Configure the firewall properly to allow HTTPS connections.
    Also make sure the internal clock of your server is set to the right time; a wrong timestamp can cause a failure in checking the SSL certificate when contacting the License Server.
  3. The SFS2X instance is unable to contact the License Server because a temporary network failure is preventing the connection ()
    If you are unable to start SFS2X in production environment or the grace period is going to end within 12 hours, please contact the SmartFoxServer Support Team: you will receive a temporary IP-based license file to be installed on your SFS2X instance which will skip the license initialization/validation for an agreed amount of time.
  4. The SFS2X instance is unable to contact the License Server because the License Server is down ()
    The License Server is hosted on an highly available infrastructure, nevertheless service down periods can happen due to failure or maintenance. If you are unable to start SFS2X in production environment or the grace period is going to end within 12 hours, follow the same advice provided at C.
  5. The entered license code is reported as invalid ()
    Make sure you copied the code from the Licenses Administration dashboard exactly. We suggest you to use the copy&paste functionality of your operating system.
    During license setup, the code is shown as invalid in case the license was disabled by the SmartFoxServer Team too (see H).
  6. The license is reported as already allocated ()
    This warning is displayed in case the license has already been assigned to a SFS2X instance before. If you are moving the license to a new instance, if you are moving the same instance to a new server or if you changed the network interface of your server, you need to reset the license allocation as described in the Moving a SFS2X instance to a new server or Transferring a license to a new SFS2X instance paragraphs.
  7. The license is expired ()
    The expiration date of your time-limited license has passed. Remove the license code using the AdminTool's License Manager to avoid the warning keep being reported at startup or runtime.
  8. The license is disabled ()
    The license was disabled by the SmartFoxServer Team. If this happened for no apparent reason, please contact the SmartFoxServer Support.
  9. The license credit is depleted ()
    The credit assigned to an elastic license was depleted. Follow the procedure described in the Recharging an elastic license.