Server Configurator

The AdminTool's Server Configurator module gives access to all the global SmartFoxServer parameters that drive its behavior at runtime. When started, SmartFoxServer configures itself with these settings.

Usage

When the module is opened, the current configuration is automatically requested to the server. It is also possible to reload it later by pressing the Reload button located at the bottom of the module.

In order to submit your changes, click the Submit button. In case of simultaneous changes made by multiple administrators, an alert message is displayed.

Server restart

Configuration changes are not applied automatically by SmartFoxServer when submitted (with the exception of the Remote Admin tab). You will need to manually restart the server for the changes to take effect.

If checked, the Backup checkbox located near the Submit button instructs the server to make a backup copy of the existing settings before saving the new ones. This is always recommended. The backup files are located under the config/_backups folder with the date and time of the backup in their name.

In order to restore a backup, rename it to server.xml and move it to the config folder, overwriting the existing file. Then restart SmartFoxServer.

Configuration settings

The SmartFoxServer configuration settings are divided into a number of tabs. Most of the settings are self-explanatory, anyway they are all accompanied by an Help () icon: hovering the mouse pointer shows a brief description in a tooltip. Reading such notes is highly recommended.

The following sections show the screenshots of all module's tabs, delving deeper into the less straightforward settings.

General

This tab contains the basic SmartFoxServer settings, including the main IP addresses and ports which are listened for incoming connections.

---

IP Filter

This tab configures the IP addresses black-list and white-list. Please note that these settings are not related to IP banning (see the Ban Manager module): black-listed IPs are never permitted to connect to the SmartFoxServer instance, while white-listed IPs can still be banned.

Additional information

• The IP addresses white-list parameter overrides the Maximum connections per IP address setting, allowing unlimited incoming connections from the listed IPs.
• It is possible to use IP ranges for both white and black lists. IP ranges must be expressed using standard CIDR Notation. For example adding the range 192.168.1.1/24 to a white list means that all addresses from 192.168.1.1 to 192.168.1.255 will be allowed to connect. If the same range is added to a blacklist, all those addresses will be rejected by the server.

---

Ban Manager

This tab collects the global banning settings. Ban rules can then be configured on a per-Zone basis in Words Filter and Flood Filter tabs of the Zone Configurator module.

---

Web Server

This tab activates the Apache Tomcat web server embedded in SmartFoxServer and the HTML5 WebSocket protocol, both standard (WS) and secure (WSS). The WebSocket protocol is required to support HTML5/WebGL applications. HTTP/WS and HTTPS/WSS protocols can be enabled and configured separately.

Activating the web server is mandatory in order to run the BlueBox service, for which a few advanced settings are also available here.

WSS connections also require an SSL certificate to be deployed on the server, as described in the Configuring SSL/TLS document. The Manage button opens a popup window allowing the certificate keystore to be uploaded to the embedded web server.

Additional information

• Make sure that the HTTP/WS port and HTTPS/WSS port settings do not conflict with each other and the general TCP port (default: 9977).
• The keystore password provided in the SSL Certificate Manager popup is transmitted securely to the server. Also, the administrator password is requested as an additional security measure.
• Tomcat users table can contain a dedicated set of credentials to access to the web server's native status console from the Dashboard module.

File upload protection

As the SSL Certificate Manager popup allows uploading any kind of file to the server, a physical lock has been placed on the server to improve security. The lock prevents using this feature until it is removed. This means that even if you forget to change the default access credentials of the AdminTool, a malicious user won't be able to take advantage of it.

To enable the feature you have to remove the config/UploadsLock.txt file by accessing the server directly (via FTP or using a terminal/console window). Please make absolutely sure to first setup a secure password before removing the lock file.

As the module leverages SmartFoxServer's file uploading feature, in addition to the above, the feature requires the internal web server to be already running and the HTTP protocol to be active.

---

Database

This tab exposes the connection settings of the HSQL database used internally by SmartFoxServer. By default this is an embedded local database in which data collected at runtime is stored in order to provide historical data views in Dashboard, Zone Monitor and Analytics modules.

It is also possible to configure an external HSQL database where data should be stored. This is used only by services supporting it: for example this works for Analytics module data, while runtime stats displayed by Dashboard and Zone Monitor modules always use the embedded database.

---

Audio Streaming

This tab allows enabling audio streaming capabilities in SmartFoxServer. The settings configure the clients' live stream quality and various parameters that improve the experience under bad network conditions.

---

Mailer

Entering an SMTP server address and account details in this tab enables the SmartFoxServer Mailer service, allowing emails to be sent from within Extensions without the need of external software.

If active, the Mailer is also used by SmartFoxServer itself to send warning emails in case of license issues, so configuring it in production environments is highly recommended.

---

Remote Admin

This tab allows configuring the users enabled to access the server's administration through the AdminTool. For additional security, a list of allowed IP addresses or IP ranges and the TCP communication port should be declared.

The ability to stop/restart the server and the list of disabled AdminTool modules can be configured on a per-administrator basis.

Please note that unlike the other server parameters, most of the settings grouped under this tab are applied immediately, as soon as configuration changes are submitted, without needing a server restart. This is reminded by an Bolt () icon.

Additional information

• Removing all the entries in the Administrators table will make the server's administration inaccessible. Also, at least one administrator should have full permissions, otherwise some features could become inaccessible, requiring a manual intervention on the configuration files on the server.
• The Enable password hashing setting enables storing administrator passwords as hashes rather than plain text in the local configuration. This is highly recommended for production environments in conjunction with enabling SSL. After this option is turned on, all existing passwords are automatically hashed as soon as configuration changes are submitted.
• If the Allowed client IP addresses list is left empty, no restrictions on client IP addresses are applied (administrators can connect from any IP). The list can contain IP ranges too, using the CIDR notation (i.e. 192.168.0.1/24).
• If the Administration TCP port is set to -1, no restrictions on connection ports is applied (administrators can connect to any port bound by SmartFoxServer).
• The Use encryption switch enables protocol encryption for the AdminTool client; check the Configuring SSL/TLS document for more information.

---

Analytics

In this tab it is possible to enable metrics data collection for the Analytics module.

---

Geolocation DB

In order to provide basic user geolocation and the Demographics view in Analytics module, IP to Country Lite database (provided by DB-IP) is used to identify the users location by means of their IP address (both IPv4 and IPv6 are supported).

The IP to Country Lite database is licensed under the Creative Commons Attribution 4.0 International License (more information here). This license allows you to update the local database when a new version is made available by DB-IP on their website. Click on the Install latest release button to update the database.

Additional information

• The geolocation database is in binary format ant it's stored in the /data/geolocation folder.
• It is possible to substitute the lite database with a commercial version. Follow the instructions provided in the Geolocation DB tab itself.

---

JVM Settings

This tabs allows advanced users and system administrators to configure additional settings to fine tune the Java Virtual Machine when the SmartFoxServer process is launched. It is also possible to add classpath entries to load additional, external libraries to be used by the Extensions (even if the default entries should be enough for all purposes).

Additional information

• Common examples of parameters which can be added to the JVM options list are:
  • -Xms and -Xmx, to configure the heap memory size (for example -Xms512M and -Xmx2048M to start with 512 MB of heap memory, up to 2048 MB);
  • -XX:+CMSClassUnloadingEnabled and -XX:+CMSPermGenSweepingEnabled to make the Garbage Collector (GC) sweep the PermGen too.
• For more information on the JVM options, check this link on the Oracle website.
• Do not to remove the predefined entries from the JVM classpath list; doing so can break the SmartFoxServer functioning.

Manual changes

When the JVM settings are changed, the AdminTool takes care of re-generating the server's startup scripts by means of specific templates. For this reason it's not recommended to edit the startup scripts manually, or your changes could be overwritten in case you later make changes using this tab.